A vapp and an add-on
A vapp lives inside another deployment. It has no compose file and starts no
container: installing one runs its jobs in the parent’s containers. The
catalogue Postgres carries one, postgres/database. Give notes its own:
a database and the user that owns it.
Four files make a vapp, all in the parent app’s directory. Create them on home01.
version: "1.0"name: databaseapp: notestype: vappdescription: A database and the user that owns itvars: password@secret: the user's password cleanup: drop the database and the user when the instance is removedpassword: P@ssw0rdcleanup: falsevsocket: databasedata: database: "{{ instance_name }}" username: "{{ instance_name }}" password: "{{ vars.password }}" cleanup: "{{ vars.cleanup }}"schema: plug: database@identifier!: the database to create username@identifier!: the user that owns it password@secret!: that user's password cleanup@boolean: drop both when the instance is removed socket: hostname@string!: the host Postgres answers on port@port!: the port it answers ondata: hostname: "{{ environment }}.postgres.{{ stack }}" port: 5432jobs: integration: - name: create context: service service: postgres environment: DB: "{{ integration.plug.data.database }}" OWNER: "{{ integration.plug.data.username }}" PASSWORD: "{{ integration.plug.data.password }}" command: | psql -U postgres -v ON_ERROR_STOP=1 <<'SQL' \getenv db DB \getenv owner OWNER \getenv password PASSWORD create user :"owner" password :'password'; create database :"db" owner :"owner"; SQL cleanup: - name: drop context: service service: postgres environment: DB: "{{ integration.plug.data.database }}" OWNER: "{{ integration.plug.data.username }}" command: | psql -U postgres -v ON_ERROR_STOP=1 <<'SQL' \getenv db DB \getenv owner OWNER drop database :"db"; drop user :"owner"; SQLdatabase.vapp.yaml names the vapp, the app it belongs to and its variables.
database.vvars.yaml gives them defaults. database.vplug.yaml is what an
instance asks the parent for: a database and a user, both named after the
instance. database.vsocket.yaml is what the parent does about it: its
integration jobs run at install and its cleanup jobs at removal, inside
the parent’s postgres service, and psql reads the plug’s values from the
environment with \getenv. Its data is what an app whose plug connects to
an instance gets back. See
Virtual apps.
Install an instance named shop into placed. --into names the parent and
--instance names the instance.
$ shc install notes/database --into placed --instance shopinstalling deployment "placed/shop"✔ installed deployment "placed/shop"$ shc exec -s placed -S postgres -- psql -U postgres -tAc "select datname, pg_get_userbyid(datdba) from pg_database where datname = 'shop'"shop|shopAn add-on is a set of variables published under a name, so an install can
name a known configuration instead of typing --vars. This one belongs to
the database vapp and turns cleanup on.
vapp: databasedescription: a database for a blog, dropped with its instancevars: cleanup: trueThe file’s name is the add-on’s name, and vapp: database says which vapp it
configures. See Add-ons.
$ shc install notes/blog --into placedinstalling deployment "placed/blog"✔ installed deployment "placed/blog"$ shc lsSTACK TENANT ENV APP STATUS NODEcloud prod prod nextcloud running home01db prod prod postgres running home01pgweb prod prod /root/learn/pgweb running home01placed prod prod notes running home01store prod prod /root/learn/versitygw running home01web prod prod /root/learn/nginx running home01placed/shop prod prod notes/database running -placed/blog prod prod notes/database running -$ shc exec -s placed -S postgres -- psql -U postgres -tAc "select datname, pg_get_userbyid(datdba) from pg_database where datname in ('shop', 'blog') order by 1"blog|blogshop|shopThe add-on named the instance after itself. Each instance is a row with no node, because it runs nothing. Remove both.
$ shc uninstall placed/shop -yuninstalling deployment "placed/shop"[placed/shop] Complete 1/1✔ tear down✔ uninstalled deployment "placed/shop"$ shc uninstall placed/blog -yuninstalling deployment "placed/blog"[placed/blog] Complete 1/1✔ tear down✔ uninstalled deployment "placed/blog"$ shc exec -s placed -S postgres -- psql -U postgres -tAc "select datname from pg_database where datname in ('shop', 'blog') order by 1"shopSHC runs a vapp’s cleanup jobs only when the instance’s cleanup is true.
shop took the default, false, so its database stays. blog took the
add-on’s true, so its database is gone.
Read Underneath the vapp before going on; it reads what this page left running.
Every page so far ran on home01 alone. The next two need more machines: a group whose members sit in two locations, and a node that fails while the others carry on.