Skip to content
SHC Docs

Stop, start, protect and rename

This page runs the verbs that change a deployment without changing its app: stop, start and restart, protect, rename, and freeing what a move leaves. A deployment keeps its rendered files while it is stopped, so stopping and starting are cheap. Stop guestbook’s API, see the path stop answering, and start it again.

home01
$ shc stop guestbook -S api
...
$ shc ls
...
$ shc start guestbook -S api
...
home01
$ curl -sk --resolve guestbook.learn.test:443:127.0.0.1 https://guestbook.learn.test/api/
...

-S names one service; without it the verb acts on every service. restart stops and starts in one step, and stop --force kills instead of waiting for the container to exit.

home01
$ shc restart guestbook -S web
...
$ shc stop guestbook -S peek --force
...
$ shc stop guestbook
...
$ shc start guestbook
...

stop --pause freezes the containers where they are instead of stopping them: their processes keep their memory and nothing exits. start thaws them.

home01
$ shc stop guestbook --pause
...
$ shc start guestbook
...

--quiet drops the progress lines of any of the three.

home01
$ shc restart guestbook -S api --quiet
...
$ shc stop guestbook -S peek --quiet
...
$ shc start guestbook -S peek --quiet
...

exec runs a command in a service’s container; --workdir says where.

home01
$ shc exec -s guestbook -S web --workdir /etc/nginx -- ls conf.d
default.conf

--interactive (-i) hands the command what you pipe in.

home01
$ printf 'one\ntwo\n' | shc exec -s guestbook -S web --interactive -- wc -l
2

A command typed at a terminal reads what you type and runs on a terminal without either flag. --tty asks for a terminal when the output goes to a pipe or a file.

home01
$ shc exec -s guestbook -S web --tty -- sh -c 'test -t 1 && echo on a terminal' | cat
on a terminal

Two verbs act on one container rather than a service. Typed alone, shc container lists them.

home01
$ shc container
...

Their argument is a container id, a value only the node that runs it can tell you, so the walk of this page does not type them.

explained, not walked: a container id is printed by the node that runs it
$ shc container restart 3f2a9c1b7d4e
$ shc container mount 3f2a9c1b7d4e --ttl 30m
$ shc container mount 3f2a9c1b7d4e --read-write

container restart restarts that one container and leaves its service’s other replicas running. container mount copies the container’s filesystem to the node and prints the path; the copy is released after --ttl. A shell inside a container needs a terminal:

explained, not walked: a shell needs a terminal
$ shc shell guestbook -S web --sh sh --user nginx --workdir /etc/nginx

Install a second copy from the catalogue to protect and rename. --repo names the repository to take it from, the same as mine/guestbook.

home01
$ shc install guestbook --repo mine -s trial --var greeting="Only a trial."
...
$ shc protect trial
...
$ shc uninstall trial --yes
shc: [X409001DEPROT] deployment prod/trial is protected, unprotect it before destroy
$ shc unprotect trial
...

A protected deployment refuses uninstall until it is unprotected, and it can still be moved and drained. An install or an update sets the same flag with --protected and clears it with --unprotected. update takes the deployment as its argument or as --stack.

home01
$ shc update trial --protected --quiet
...
$ shc update --stack trial --unprotected --quiet
...

A deployment can also carry a lease: --ttl 72h ends it when the time runs out. In an environment named prod or production a lease is refused unless --force says you mean it. An update whose ! removal matches nothing reports it and carries on; --strict-removals makes that a failure instead.

explained, not walked: trial is already installed, and a lease would end a deployment this ladder removes by hand
$ shc install guestbook --repo mine -s trial --ttl 72h --force --protected
$ shc install guestbook --repo mine -s trial --unprotected
$ shc update trial --ttl 72h --force
explained, not walked: trial has no route to remove, so the line only fails
$ shc update trial --expose old.learn.test! --strict-removals

rename gives a deployment a new name in its own tenant and environment. --dry-run prints the plan, and a rename is followed by an update so its routes take the new name.

home01
$ shc rename trial pilot --dry-run
...
$ shc rename trial pilot --yes
...
$ shc update pilot
...

run runs a container from an image for a deployment, through the container broker, on a node that holds one of its replicas. It prints what the container prints, fails when the container exits non-zero, and removes the container. The broker is off until the cluster opts in, and a deployment outside tenant master runs one only with the socket class granted, the way A privilege grants caps. Both keys are read at global scope only. With prod selected, a set without --scope writes at tenant scope, which these keys refuse, so each one names --scope global.

home01
$ shc config set container_broker.enabled true --scope global
...
$ shc config set privilege.deployment_grants.prod.prod.pilot socket --scope global
...

--entrypoint replaces the image’s entrypoint, --user and --workdir say who the container runs as and where, and --env sets a variable. Without --network the container has loopback alone.

home01
$ shc -s pilot run --entrypoint /bin/sh --user 65534 --workdir /tmp --env GREETING=hello busybox:1.36 -c 'echo $GREETING; id -u; pwd'
hello
65534
/tmp

--detach starts the container and returns. It runs until a later detached run of the same --name replaces it or the deployment is removed. --network deployment puts it on every network of the deployment, where the replicas reach it by that name, and so does another run on that network.

home01
$ shc -s pilot run --detach --name hello --network deployment traefik/whoami:v1.10 --port 8090
...
home01
$ shc exec -s pilot -S web -- wget -q -O - http://hello:8090/
...
Host: hello:8090
...
$ shc -s pilot run --network deployment busybox:1.36 wget -q -O - http://hello:8090/
...
Host: hello:8090
...

Uninstalling pilot removes its detached run with it. Take the grant back and close the broker again.

home01
$ shc uninstall pilot --no-backup --yes
...
$ shc config unset privilege.deployment_grants.prod.prod.pilot --db --scope global
...
$ shc config unset container_broker.enabled --db --scope global
...

A move keeps the data it moved from on the old node until you free it, so a move that should not have run loses nothing. reclaim runs on the node a deployment left, and without --yes it only reports. Nothing has moved on this cluster of one, so it finds nothing.

home01
$ shc reclaim --older-than 1h
...
$ shc reclaim
...

After a move, --operation keeps only the trees that one move left, by the operation id its plan printed, and --yes removes them.

explained, not walked: nothing has moved on this cluster, so there is no operation to name and no tree to remove
$ shc reclaim --operation 7c1e2b9a --yes

Every command takes a few global flags. --verbose asks for more detail where a command has it. With -o yaml or -o json, --filter keeps only the dotted paths you name and --exclude drops them.

home01
$ shc version --verbose
...
$ shc node info home01 -o yaml --filter hostname,location
...
$ shc node info home01 -o yaml --exclude fabric_chunks,fabric_tenant_slots,fabric_fullest_bridge
...

--debug adds the client’s own log records, which differ on every run. --config layers an extra YAML file over the config the client found, and can be given more than once, later files winning.

explained, not walked: one prints the client's own log, the other needs a client config file of yours to layer
$ shc ls --debug
$ shc ls --config ~/learn/extra-config.yaml

Next: Secrets and the vault.