Copies and deployfiles
A clone is a second deployment made from a running one: its app, its
variables, its data and its secrets. The source keeps running. --dry-run
prints the plan and changes nothing.
$ shc clone notebook notecopy --dry-run...$ shc clone notebook notecopy --yes --quiet...$ shc exec -s notecopy -S notes -- wc -l /srv/notes/log...The copy is placed by the source’s own rules, here where: node=home01;
--prefer and --where add to them. It can land in another environment of
the same name, and on a named runtime. constraint explain shows the rules
the copy carries.
$ shc clone notebook notebook --target-environment staging --prefer node=home01 --runtime docker --yes...$ shc constraint explain -s notebook -e staging...$ shc ls...A deployment connected to others is cloned with them. --all-connections
takes the deployments one integration away, --closure every one reachable,
and --rename gives each copy its name. notebook connects to nothing, so the
plan holds notebook alone.
$ shc clone notebook notecopy2 --all-connections --closure --rename notebook=notecopy2 --dry-run...$ shc uninstall notecopy --yes...$ shc uninstall notebook -e staging --yes...Two things a clone takes that this cluster has one of: a tenant and a storage backend.
$ shc clone notebook notebook --target-tenant acme --storage nfs --yesA deployfile
Section titled “A deployfile”A deployfile is a deployment written down: the app, its variables, the
hostnames it answers on and the environments it goes to. shc deploy
installs what does not exist yet and updates what does, so running it again
is the normal case; a pipeline that runs it on every commit keeps the cluster
where the file says.
stack: notebookapp: learn/notebookexpose: - notes.learn.test=page:80environments: dev: {}app is the app’s directory, relative to where shc deploy runs. expose
takes what --expose takes. A hostname is written as prod
serves it and moves with the environment: dev.notes.learn.test for dev,
notes.learn.test for prod. The file is the deployment’s
whole desired state: a route, variable, integration or label it does not
name is removed on the next deploy.
--dry-run is the plan: install, no changes, or each change the update would
make against what runs. It exits 3 when it would change something and 0 when
it would not, so a pipeline can tell drift from a no-op.
$ shc deploy -f learn/notebook.shc.yaml -e dev --dry-run...Plan: 1 to install, 0 to update, 0 unchanged.$ shc deploy -f learn/notebook.shc.yaml -e dev...$ shc deploy -f learn/notebook.shc.yaml -e dev --keep-going...$ curl -sk --resolve dev.notes.learn.test:443:127.0.0.1 https://dev.notes.learn.test/...${NAME} in a deployfile is read from --env-file, the environment and
--set, each beating the one before, so a pipeline passes its commit or a
review slug without editing the file. An undefined name is refused.
NOTES_VERSION=1.0.0stack: notebookapp: learn/notebookvars: release: ${NOTES_VERSION}expose: - notes.learn.test=page:80environments: dev: {}$ shc deploy -f learn/notebook.shc.yaml -e dev --env-file learn/notebook.env --dry-run...Plan: 0 to install, 1 to update, 0 unchanged.$ shc deploy -f learn/notebook.shc.yaml -e dev --set NOTES_VERSION=1.0.1 --dry-run...Plan: 0 to install, 1 to update, 0 unchanged.$ shc uninstall notebook -e dev --yes...A review environment gets a host of its own, <slug>.review.<host>, for a
branch under review; --storage picks the backend of a first install.
$ shc deploy -f learn/notebook.shc.yaml -e review --slug feat-login-42 --storage nfsA set of deployfiles
Section titled “A set of deployfiles”-f can be given more than once, or name a directory, which means every
*.shc.yaml directly inside it. The files deploy as one set. Every
deployment starts at once, except one whose integrate: names another
deployment of the set in the same tenant and environment: that one waits
until its provider has deployed.
deploy/postgres.shc.yaml deploys the catalogue’s postgres:
stack: postgrescatalog: postgresenvironments: prod: {}deploy/gitea.shc.yaml connects gitea’s postgres plug to it:
stack: giteacatalog: giteaexpose: - git.example.comintegrate: postgres: postgresenvironments: prod: {}$ shc deploy -f deploy/ -e prod --dry-run$ shc deploy -f deploy/ -e prodThe dry run prints waits on postgres under gitea. postgres starts first and
gitea once postgres is healthy; a third file that names neither would start
beside postgres. Each deployment gets its own block, live on a terminal and
printed as it settles in a pipe.
If postgres fails, gitea never starts, and the run ends with one line per
deployment: deployed, failed, or not started and why. Without --keep-going
the first failure also keeps every deployment that has not started yet from
starting; with it, anything that does not wait on a failure still starts.
-o json prints one document for the set, a row per deployment with its
status, waits_on, started_at and finished_at.
Two files that name one deployment are refused before anything deploys
(X400428DPFSET), and so are integrate: lines that wait on each other in a
cycle (X400427DPFCYC), the dry run included.
Interrupted moves
Section titled “Interrupted moves”A move or a rename killed half way leaves a record on the node it ran on. The daemon reverts an interrupted move and finishes an interrupted rename when it starts again; what it will not do by itself is listed here with the command that does it. The list is this node’s alone.
$ shc interrupted...A move killed after its source was torn down is one the daemon will not
revert: the target may hold the only running copy. shc finish-forward
finishes it, with the operation id shc interrupted lists. It reads the
target’s health and the bytes it holds again before it removes anything
else, and refuses if it cannot.
$ shc finish-forward 3f2c9a1e-7b4d-4c58-9e21-6a0d5b8c1f47A rename whose new name is a system deployment’s name in another tenant is
one the daemon will not finish. A rename is refused that name before it
starts, but an older daemon could leave such a record, and the deployment
then stays down at the step the rename reached. shc roll-back puts it back
under the name it ran under: it undoes each step the rename reached, starts
the deployment under its own name and retires the record. A rename’s
operation id is rename-<tenant>-<environment>-<name>. If the roll-back
stops part way, the record is kept and the next daemon start or
shc roll-back again carries it on. --drop, which would retire the record
and restore nothing, is refused (X409682CLNDRP): the record is the only
map of what the rename moved.
$ shc roll-back rename-prod-prod-trial$ shc roll-back --drop rename-prod-prod-trial