Volumes
This page takes volumes past A volume: a directory’s mode
and owner, a single file of the app, scratch space, a block volume, and the
mounts SHC refuses. A named volume is a directory of the deployment,
mounts/<name>, on the node that runs the replica; a file or directory of
the app is bound from the deployment’s copy of the app’s files.
The next app is notebook: a service that writes a line every 30 seconds, and
a page server. Write it on home01.
name: notebookversion: "1.0.0"title: Notebookdescription: Writes a line every 30 seconds and keeps themcategory: demolicense: id: MITevery=30where: - node=home01services: notes: image: busybox:1.36 user: "65534:65534" command: ["sh", "-c", "while true; do date -u >> /srv/notes/log; sleep 30; done"] volumes: - name: notes path: /srv/notes mode: "0750" owner: "65534:65534" - source: ./notes.conf path: /etc/notes.conf read_only: true tmpfs: - /tmp page: image: nginx:1.27-alpine expose: [80] volumes: - name: html path: /usr/share/nginx/html - name: entrypoint path: /docker-entrypoint.d noinit: truewhere keeps notebook on home01, so its volumes are on the machine you type
on. Each mount has a name or a source, never both:
notesis a named volume.modeandownerare what its directory gets beforenotesstarts, so the service, which runs as user 65534, can write it.notes.confis a file of the app, bound read-only.tmpfsis scratch space in memory, empty at every start.htmlstarts as a copy of what the image holds at that path, nginx’s own two pages.noinitleavesentrypointempty instead, so nginx’s start scripts are not there to run.
The mount fields are in shc.yaml.
$ shc validate ~/learn/notebook...$ shc install ~/learn/notebook -s notebook...$ shc exec -s notebook -S notes -- ls -ldn /srv/notes...$ shc exec -s notebook -S notes -- cat /etc/notes.confevery=30$ shc exec -s notebook -S notes -- tail -n 1 /srv/notes/log...$ shc exec -s notebook -S page -- ls /usr/share/nginx/html50x.htmlindex.html$ shc exec -s notebook -S page -- ls -A /docker-entrypoint.dOn home01 the named volumes are directories of the deployment.
$ ls -1 /var/lib/shc/deployments/prod/notebook/prod/mounts...The volume is the deployment’s, not the container’s. Restart notes and the
log keeps its lines; an update renders the app again and keeps them too.
$ shc exec -s notebook -S notes -- wc -l /srv/notes/log...$ shc restart notebook -S notes...$ shc update notebook...$ shc exec -s notebook -S notes -- wc -l /srv/notes/log...A compose file says the same in its short form, with SHC’s own fields after
compose’s mode: source:target:mode:perm:uid:gid. Give keyholder a scratch
volume only user 65534 may enter, and a cache. x-shc-volumes asks for
cache to be a 1 GiB block volume that one node writes. Replace
~/learn/keyholder/compose.yaml.
services: holder: image: busybox:1.36 command: ["sh", "-c", "cat /run/secrets/token; sleep infinity"] secrets: - token volumes: - cache:/var/cache/holder - scratch:/srv/scratch:rw:0700:65534:65534secrets: token: x-shc-vault: ref+vault://api_keyvolumes: cache: scratch:x-shc-volumes: cache: size: 1Gi access: rwo$ shc update keyholder...$ shc exec -s keyholder -S holder -- ls -ldn /srv/scratch...A block volume needs a volume provider, a cloud’s block storage that SHC
attaches to the node that runs the replica. This cluster has none, so cache
stays a directory like the others. The Runtimes and clouds ladder sets up a
provider and its shc volume commands. Typed alone, shc volume lists
them; volume ls and volume mounts with --all-tenants read every
tenant’s block volumes and held mounts, none here.
$ shc volume...$ shc volume ls --all-tenants...$ shc volume mounts --all-tenants...shc volume files works on the files inside a deployment’s volumes while
the app runs, on whichever node holds them, the same on every runtime.
Given only the deployment it names the volumes; given a volume and a
folder it lists the folder. put uploads a file and lands it whole or not
at all, owned like its folder, so the app can read it. A second put to
the same path is refused unless --force replaces it. get reads a file
back, to stdout with -. Writes need manage on the deployment and each
one leaves an audit event; a viewer lists folders but reads no bytes.
$ shc volume files ls keyholder...$ shc volume files ls keyholder scratch /...$ echo hello > ~/learn/hello.txt$ shc volume files put keyholder scratch /hello.txt ~/learn/hello.txt...$ shc exec -s keyholder -S holder -- ls -ln /srv/scratch...$ echo hello again > ~/learn/hello.txt$ shc volume files put keyholder scratch /hello.txt ~/learn/hello.txt --force...$ shc volume files get keyholder scratch /hello.txt -...$ shc volume files mv keyholder scratch /hello.txt /greeting.txt...$ shc volume files rm keyholder scratch /greeting.txt --yes...SHC refuses a mount that would reach outside the deployment. A host path is one; so is a named volume with a path in its name, since its directory would sit inside another volume’s. The refusal says which and why. Write a broken copy and validate it.
name: brokenversion: "1.0.0"title: Brokendescription: Mounts what SHC refusescategory: demolicense: id: MITservices: reader: image: busybox:1.36 command: ["sleep", "infinity"] volumes: - source: /var/log path: /logs$ shc validate ~/learn/brokenvalidation failed: /root/learn/broken error: shc.yaml: [X400534SHYHST] broken shc.yaml: service reader mounts the host path /var/log; a mount is a named volume, an app file (./...) or a platform mount (/etc/shc/...)The second is a compose app of its own: a directory with shc.yaml reads that
file, not compose.yaml.
name: nestedversion: "1.0.0"title: Nesteddescription: Names a volume inside anothercategory: demolicense: id: MITservices: reader: image: busybox:1.36 command: ["sleep", "infinity"] volumes: - data/uploads:/uploadsvolumes: data:$ shc validate ~/learn/nestedvalidation failed: /root/learn/nested error: compose.yaml: service reader mounts data/uploads:/uploads: [X403334VOLNST] mount source data/uploads is not one directory name, a mount cannot sit inside anotherKeep notebook installed for the backup page.
Next: Back up and restore your app.