Skip to content
SHC Docs

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.

~/learn/notebook/app.yaml
name: notebook
version: "1.0.0"
title: Notebook
description: Writes a line every 30 seconds and keeps them
category: demo
license:
id: MIT
~/learn/notebook/notes.conf
every=30
~/learn/notebook/shc.yaml
where:
- node=home01
services:
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: true

where keeps notebook on home01, so its volumes are on the machine you type on. Each mount has a name or a source, never both:

  • notes is a named volume. mode and owner are what its directory gets before notes starts, so the service, which runs as user 65534, can write it.
  • notes.conf is a file of the app, bound read-only.
  • tmpfs is scratch space in memory, empty at every start.
  • html starts as a copy of what the image holds at that path, nginx’s own two pages. noinit leaves entrypoint empty instead, so nginx’s start scripts are not there to run.

The mount fields are in shc.yaml.

home01
$ shc validate ~/learn/notebook
...
$ shc install ~/learn/notebook -s notebook
...
home01
$ shc exec -s notebook -S notes -- ls -ldn /srv/notes
...
$ shc exec -s notebook -S notes -- cat /etc/notes.conf
every=30
$ shc exec -s notebook -S notes -- tail -n 1 /srv/notes/log
...
$ shc exec -s notebook -S page -- ls /usr/share/nginx/html
50x.html
index.html
$ shc exec -s notebook -S page -- ls -A /docker-entrypoint.d

On home01 the named volumes are directories of the deployment.

home01
$ 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.

home01
$ 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.

~/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:65534
secrets:
token:
x-shc-vault: ref+vault://api_key
volumes:
cache:
scratch:
x-shc-volumes:
cache:
size: 1Gi
access: rwo
home01
$ 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.

home01
$ 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.

home01
$ 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.

~/learn/broken/app.yaml
name: broken
version: "1.0.0"
title: Broken
description: Mounts what SHC refuses
category: demo
license:
id: MIT
~/learn/broken/shc.yaml
services:
reader:
image: busybox:1.36
command: ["sleep", "infinity"]
volumes:
- source: /var/log
path: /logs
home01
$ shc validate ~/learn/broken
validation 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.

~/learn/nested/app.yaml
name: nested
version: "1.0.0"
title: Nested
description: Names a volume inside another
category: demo
license:
id: MIT
~/learn/nested/compose.yaml
services:
reader:
image: busybox:1.36
command: ["sleep", "infinity"]
volumes:
- data/uploads:/uploads
volumes:
data:
home01
$ shc validate ~/learn/nested
validation 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 another

Keep notebook installed for the backup page.

Next: Back up and restore your app.