Virtual apps (vApps)
Layer 6. Services. Services
A vApp is a sub-resource that lives inside another deployment rather
than as a top-level deployment of its own. vApps let a parent app expose
“per-tenant instances” of something it provides (a Keycloak realm, a
Postgres database, a MariaDB database, a bucket on the provisioning s3
app) without each instance being a full deployment with its own compose file,
networks, and volumes. The bucket vApp is declared in
apps/standalone/s3/bucket.vapp.yaml.
Source of truth (ce module):
modules/app/vdeployment_runner.go
(the synchronous vapp install path and the
*.vapp.yaml / *.vsocket.yaml / *.vplug.yaml / *.vvars.yaml
file contract), with the closed key set for those documents in
modules/app/vdocument_lint.go, the cleanup guard in
modules/app/vapp_cleanup_lint.go and
modules/app/vdeployment_cleanup_report.go.
When to use a vApp vs a deployment
Section titled “When to use a vApp vs a deployment”Use a vApp when:
- The resource is naturally owned by a parent deployment (a realm belongs
to a Keycloak, a bucket belongs to a provisioning
s3deployment). - You want many instances of it on one parent: a dozen realms on one Keycloak deployment, a dozen databases on one Postgres.
- It has no containers of its own; it’s configuration applied to containers the parent already runs.
Use a deployment when:
- It has its own compose file and runs independently.
- It could plausibly live on a different node from the thing it integrates with.
vApps do not start any containers. They exist as rows in the database plus jobs that configure state inside parent-deployment services.
Naming
Section titled “Naming”vApps and their instances use slash notation throughout:
| Concept | Format | Example |
|---|---|---|
| App name in the catalog | <parent-app>/<vapp> | keycloak/realm, postgres/database |
Address (<stack>/<instance>) | the host deployment’s stack name, then the instance | my-keycloak/test-realm, dbs/blog |
The stack name’s left-hand side identifies the host deployment (must already be installed); the right-hand side names this specific instance.
Example: the Postgres database vApp
Section titled “Example: the Postgres database vApp”Files shipped with the postgres app (apps/postgres/):
apps/postgres/├── app.yaml├── compose.yaml # the actual postgres service├── postgres.socket.yaml # admin-level socket│├── database.vapp.yaml # ← THE vAPP: a sub-resource "database"├── database.vsocket.yaml # ← per-instance socket consumers plug into├── database.vplug.yaml # ← vPlug definition (how the vApp talks to postgres)└── database.vvars.yaml # ← variables the vApp auto-generatesdatabase.vapp.yaml: the vApp definition
Section titled “database.vapp.yaml: the vApp definition”version: "1.0"name: databaseapp: postgrestype: vappdescription: "PostgreSQL database with dedicated user"
vars: database: Database name username: Database username password@secret: Database passwordThis declares that the postgres app offers a database sub-resource
with those three variables. app: postgres identifies the parent.
type: vapp is the discriminator.
database.vsocket.yaml: the per-instance socket
Section titled “database.vsocket.yaml: the per-instance socket”schema: plug: database@string!: Database name to create username@string!: Database username password@secret!: Database password extensions@json: Optional list of PostgreSQL extensions socket: hostname@string!: PostgreSQL hostname port@port!: PostgreSQL port admin_user@string!: Admin username admin_password@secret!: Admin password
data: hostname: "{{ environment }}.postgres.{{ stack }}" port: 5432 admin_user: "{{ vars.postgres.username }}" admin_password: "{{ vars.postgres.password }}"
jobs: integration: - name: vapp-create-database context: service service: postgres command: | # create DB + user inside the parent postgres container ...A vSocket is almost identical to a regular socket, but it’s
scoped per vApp instance: when wordpress plugs into a
specific instance of postgres/database, it gets that instance’s
database name and password, not the parent postgres admin
credentials.
database.vvars.yaml: auto-generated variables
Section titled “database.vvars.yaml: auto-generated variables”username: "!ref+autogen?length=16&charset=alphanum"password: "!ref+autogen?length=32"database: "{{ vapp_instance }}"Auto-generated values ensure every instance gets unique credentials without the operator having to supply them.
Installing a vApp instance
Section titled “Installing a vApp instance”# Parent deployment already installed:shc install postgres --stack dbs
# Install vApp instances into it:shc install postgres/database --into dbs --instance blogshc install postgres/database --into dbs --instance analyticsshc install postgres/database --into dbs --instance wikipostgres/database names a vApp in the postgres app. --into dbs --instance blog says “host deployment dbs, instance name blog”. The full
deployment identifier becomes dbs/blog.
Install flow (InstallVdeployment in
vdeployment_runner.go):
- Validates the parent deployment exists (
X400005PARNOFif not). - Validates the instance name is unique on that parent
(
X409003STKEXSon collision). - Refuses any key in the four documents that no loader reads
(
X400341VDCUNK/X400342VDCSHP; see The document key set is closed). - Loads the vApp definition and vars; merges auto-generated and
user-supplied values, then enforces the
@type!required markers (X400978VARREQ). - Persists a
vdeploymentrow keyed by(host_deployment_id, instance_name). A vApp instance gets nodeploymentrow of its own. - Runs the vSocket’s
discoveryphase jobs and re-renders the vPlugdata:block against what they printed. - Runs the vSocket’s
integrationphase jobs inside parent-deployment services to provision the resource (create the database, create the user, grant privileges).
vApps do not run compose up: all their work happens through
jobs against services the parent deployment already runs.
vApp instances appear as regular deployments in the listings:
$ shc lsNAME APP ENV STATUSdbs postgres default runningdbs/blog postgres/database default runningdbs/analytics postgres/database default runningmy-keycloak keycloak default runningmy-keycloak/qa keycloak/realm default runningConnecting a consumer to a vApp instance
Section titled “Connecting a consumer to a vApp instance”A vApp instance presents itself as a regular deployment. The consumer plugs into it the same way it would any other deployment, by stack name:
# WordPress's `postgres` plug connects to the `blog` instance# of postgres on the `dbs` deployment:shc install wordpress --stack blog \ -i postgres=dbs/blogThe <plugname>=<stack-name> form names the target deployment.
Because vApp instances are deployments, the same syntax works: the
consumer doesn’t need to know it’s connecting to a vApp rather
than a top-level deployment. The consumer’s integrations.postgres.socket.*
template context is populated from the vApp instance’s vSocket
data, which contains per-instance credentials, not parent-deployment
admin credentials.
Lifecycle semantics
Section titled “Lifecycle semantics”| Operation | What happens |
|---|---|
shc uninstall <parent> | vApp instances are uninstalled first (unintegrated + cleaned up) before the parent’s compose-down |
shc uninstall <parent>/<instance> | Only that instance’s cleanup phase runs; parent untouched. An instance the parent does not hold refuses X404070VDPNOF and runs nothing |
shc backup create <parent> | vApp instance data is included in the parent’s backup |
shc backup restore <parent> | vApp instances are restored; the parent app’s own post_restore hook replays (a vSocket has no restore phase) |
shc clone <parent> | vApp instances are copied with the parent deployment; source instances remain |
shc update <parent> --where '<key>=<value>' relocating it | vApp instances move with the parent |
vApp teardown is driven by UninstallVdeployment in
vdeployment_runner.go. It replays the persisted plug context against
jobs.cleanup, and it deliberately does not run the document key
check, so a catalogue edit that lands a bad key under a live instance can
never make that instance unremovable.
vApps vs plugs-and-sockets: when do I use which?
Section titled “vApps vs plugs-and-sockets: when do I use which?”| Scenario | Use |
|---|---|
| I want a blog to connect to an existing Postgres database | a plug on the blog, a socket on Postgres |
| I want the blog to get its own private database inside a shared Postgres | a vApp instance of postgres/database, then a plug on the blog connecting to that instance’s deployment |
| I want each tenant of my multi-tenant app to get its own Keycloak realm | a vApp instance of keycloak/realm per tenant against a shared Keycloak |
| I want one Redis shared across 20 deployments | a plain socket on Redis, plugs on each consumer |
Rule of thumb: if the thing being provisioned has per-consumer state (a database, a realm, a bucket), use a vApp. If it’s a shared cache / shared service with no per-consumer state to create, use a plain socket.
Catalog and listings
Section titled “Catalog and listings”shc search: shows both regular apps and vApps (vApp names contain a slash, e.g.keycloak/realm); pass a query to filter across both.shc ls: lists installed deployments; vApp instances show as<parent>/<instance>with their parent’s app name as the app.shc search --kind vapp: filters to vApp catalog entries only.
The catalog index (apps.json) lists vApps with a parent_app and
type: vapp discriminator. vApps are auto-discovered from
*.vapp.yaml files within app directories during repo sync.
A *.vapp.yaml may declare hidden: true, the same authoring key an
app.yaml carries (see catalog
visibility):
name: bucketapp: s3type: vapphidden: true # a bucket is provisioned by an integration, never picked off a listingOn a vApp the key records the author’s verdict that this sub-resource
is reached through an integration or an explicit name rather than
offered as a choice; s3/bucket is the shipped example. It never
makes the vApp uninstallable (naming it still installs it), and it
never affects publication: the bucket vApp rides the s3 app into
every repo. Keeping an app out of the registry is the separate
private: key on app.yaml; see
Publication.
API surface
Section titled “API surface”vApps share endpoints with regular apps and deployments:
| Operation | Endpoint | Notes |
|---|---|---|
| List apps | GET /api/resource/App | Filter vApps with ?vapp=true or ?parent_app=X |
| Get app | GET /api/resource/App/{name} | {name} may be keycloak/realm |
| Install | POST /api/method/shc.stack.install | Pass the parent/instance pair via stack_name (slash-separated) |
| List deployments | GET /api/resource/Stack?environment=X | Includes vApp instances; each carries parent_stack |
| Uninstall | DELETE /api/resource/Stack/{name} | On a parent, cascades to child vApp instances |
Schema-wise, AppModel carries parent_app (str?) and vapp
(bool); an installed instance is a vdeployment row whose
host_deployment_id names its host deployment, beside instance_name
and vapp_name.
Writing your own vApp
Section titled “Writing your own vApp”Minimal layout:
apps/myapp/├── app.yaml├── compose.yaml├── myapp.socket.yaml # optional: admin-level socket│├── resource.vapp.yaml # the vApp definition├── resource.vsocket.yaml # per-instance socket└── resource.vvars.yaml # auto-generated per-instance varsresource.vapp.yaml:
name: resourceapp: myapptype: vappversion: "1.0"description: A per-instance resource inside myapp
vars: instance_name@string!: Name of the instance credential@secret: Generated credentialresource.vsocket.yaml: like a regular *.socket.yaml, with
jobs.integration calling context: service against services the
parent app already runs. Prefer context: service over context: container with your own image: a vApp doesn’t own any containers, so
a service-context job that execs into a parent service is the idiom.
The document key set is closed
Section titled “The document key set is closed”Every one of the four documents is decoded into a partial Go
struct. YAML happily accepts a key the struct does not name and then
throws it away, so a key SHC does not read used to be indistinguishable
on disk from one whose request was honoured. It no longer is: a key no
loader reads refuses the install (X400341VDCUNK) and is reported
by shc validate, and a value whose shape cannot be decoded refuses
too (X400342VDCSHP).
This closed exactly the bug that motivated it. postgres/database
shipped a jobs.post_deployment: phase (a whole job wiring its own
extensions@json plug field), and nothing ever ran it, because
post_deployment belongs to the consumer plug surface
(<plug>.plug.yaml, run after the consumer’s compose-up) and a
vDeployment starts no containers at all. Every instance ever created
ignored its extensions var without a word.
| Document | Keys |
|---|---|
<vapp>.vapp.yaml | version, name, app, type, description, hidden, vars |
<vapp>.vsocket.yaml | schema (plug, socket), data, jobs |
<vapp>.vplug.yaml | vsocket, data |
addons/<name>.addon.yaml | one add-on: vapp, name, description, icon, homepage, category, tags, hidden, default, versions, aliases, vars |
<vapp>.vvars.yaml | not checked: its keys are the vApp’s variable names, declared in the .vapp.yaml vars: block |
A vSocket has exactly three phases, and they are not the plug/socket surface’s phases:
| Phase | When |
|---|---|
jobs.discovery | first; each job’s stdout is parsed and exposed as {{ discovery.<job_name> }}, and the vPlug data: block is re-rendered against it |
jobs.integration | provisioning, in the order written, aborting on the first failure |
jobs.cleanup | on shc uninstall <parent>/<instance>, against the persisted plug context |
There is no post_deployment and no unintegration here: those are
the plug/socket surface’s, and writing one is refused with a message
naming where it does belong.
Each job entry takes name, context, service, image, command,
user, working_dir, environment and timeout (seconds; the module
default is 600).
Curating a plugin catalogue
Section titled “Curating a plugin catalogue”A plugin-shaped vApp (nextcloud/plugin, wordpress/plugin,
frappe/plugin) usually ships a curated catalogue beside it: an
addons/ directory whose files are the known-good plugins an operator
installs by name. One file is one add-on:
addons/<name>.addon.yaml, the stem being the name, and an add-on
belongs to this vApp by declaring vapp: <vapp> (an add-on with no
vapp: key configures the parent app instead). The mechanism is only
a named var bundle with a version map; everything ecosystem-shaped
about a good catalogue is authoring convention, and the convention is a
contract (catalog.md §35.6), written down here because breaking it has
already produced production bugs:
- Declare the vvars in the vApp, and every add-on var name must
match a declared vvar exactly. Add-on vars are merged into the
vvars map by name, and an undeclared key is silently dropped:
no error, no report. This is not hypothetical: every entry in the
nextcloud plugin catalogue once set
app_idwhile the vApp declaredappId, so the key was dropped, the vvars default (calendar) won, andshc install nextcloud/talkinstalled the Calendar app, as did every other entry in the catalogue. Green install, wrong software, no diagnostic anywhere. - Per-item constants go in
vars; per-version deltas go in theversionsoverlay. A value that never changes across versions (an app id, a slug, a repo url) belongs invars; the overlay carries only what the version choice changes (a git ref, a pinned tag). - Version keys mirror upstream’s own identifiers when upstream is
selectable; a single
latestkey when it is not. The frappe catalogue keys entries by upstream git tags (v15.59.0, …) becausebench get-appgenuinely installs the ref you name. The nextcloud catalogue uses onelatestkey becauseocc app:installtakes no version at all: a per-rung map there would be identical vars pretending to pin something. - Name a
default, and fill the display keys (descriptionat minimum). The default is what an unversionedshc install <app>/<name>resolves; the display keys are literally what the catalogue renders on the tile. They are top-level keys of the add-on document; the oldmeta:sub-map is gone, because a file is one add-on and there is nothing left to disambiguate.
Rules 1 and 4 are enforced by the catalogue-wide unit gate
(tests/unit/catalog/addon_var_parity_test.go) because both have
already failed silently. What the unit gate deliberately does NOT
check is whether a pinned upstream ref still exists: that needs the
network and lives in the freshness guard (make catalog/freshness);
see Add-ons: keeping a catalogue
fresh.
Related
Section titled “Related”- Integration doctrine: vApp vs add-on vs
deployment, and the
vapp:mode inventory - App definition: where
VAppDefinitionfits in the broader schema - Plugs & sockets: the broader integration model vApps build on
- Lifecycle hooks: vApp jobs follow the same job-execution contract
- Architecture: app module:
VAppExecutorandVAppContextinternals