Secrets and the vault
This page keeps a secret in the vault. A secret never sits in an app’s files. The files hold a reference,
ref+vault://<key>, and SHC reads the value from the cluster’s vault when it
renders the deployment. guestbook’s owner password has been one since
Variables. Now give guestbook an API key of its own.
Write the key to a file only root reads, and store it for guestbook’s
deployment. --value-file keeps the value off the command line, where every
user of the node could read it.
gb-key-0001$ chmod 600 ~/learn/api-key.txt$ shc vault set api_key -s guestbook --value-file ~/learn/api-key.txt...$ shc vault exists api_key -s guestbook...$ shc vault get api_key -s guestbookgb-key-0001$ shc vault ls -s guestbook --verbose...-s names the deployment, in the environment its install used, so the key
is guestbook’s alone. A read walks from the deployment out to the tenant and
the whole cluster and takes the first value it finds; --scope reads or
writes one tier.
Write a key at the tenant tier, and one under guestbook’s own api_key. That
second write is refused unless --allow-shadowed says you know the narrower
row hides it. get --scope reads that tier alone, ls and rm take it
too, and --limit and --offset page a long listing. Remove both after.
$ shc vault set motd -s guestbook --scope tenant --value-file ~/learn/api-key.txt...$ shc vault set api_key -s guestbook --scope tenant --allow-shadowed --value-file ~/learn/api-key.txt...$ shc vault get api_key -s guestbook --scope tenant...$ shc vault ls -s guestbook --scope tenant --limit 10 --offset 0...$ shc vault rm motd -s guestbook --scope tenant --yes...$ shc vault rm api_key -s guestbook --scope tenant --yes...Typed alone, shc vault asks for the vault’s password at the terminal. Each
verb takes it with --password where it needs one, which puts it in the
process list; --password-file keeps it off.
$ shc vault$ shc vault unlock --password P@ssw0rdshc.yaml names the secret at the top level and lists it on the service that
reads it. Replace ~/learn/guestbook/shc.yaml: the secrets block before
services: and the secrets line on web are new.
where: - location=learn/homeconfigs: site: content: | server { listen 80; root /usr/share/nginx/html; location = /healthz { return 200 "ok\n"; } location = /greeting { return 200 "{{ vars.greeting }}\n"; } }secrets: api_key: vault: ref+vault://api_keyservices: web: image: nginx:1.27-alpine primary: true replicas: 2 expose: [80] secrets: [api_key] hostname: guestbook-web domainname: learn.test environment: TZ: UTC OWNER_EMAIL: "{{ vars.owner.email }}" OWNER_HOMEPAGE: "{{ vars.owner.homepage }}" SIGNING_OPEN: "{{ vars.open }}" MAX_SIGNERS: "{{ vars.maxSigners }}" env_file: - ./web.env labels: tier: front configs: - name: site path: /etc/nginx/conf.d/default.conf volumes: - source: ./site path: /usr/share/nginx/html read_only: true tmpfs: - /var/cache/nginx - /var/run - /tmp init: true cap_add: [NET_BIND_SERVICE] pull_policy: missing stop_signal: SIGQUIT stop_grace_period: 20s post_start: - command: ["sh", "-c", "date -u > /tmp/started"] quota: cpu: "0.25" memory: 64M healthcheck: test: ["SHC-HTTP", ":80/healthz"] interval: 10s timeout: 3s retries: 3 health: restart_after: 30s api: image: traefik/whoami:v1.10 command: ["--port", "{{ vars.apiPort }}", "--name", "guestbook-api"] expose: [8080] healthcheck: test: ["SHC-HTTP", ":8080/"] interval: 10s timeout: 3s retries: 3 path: /api path_strip: true user: "65534:65534" group_add: ["65534"] working_dir: / platform: linux/amd64 read_only: true security_opt: ["no-new-privileges:true"] dns: ["1.1.1.1"] dns_search: [learn.test] extra_hosts: - printer.learn.test:192.0.2.10 counter: image: redis:7-alpine command: ["redis-server", "--appendonly", "yes", "--dir", "{{ vars.dataPath }}"] expose: [6379] restart: always networks: default: aliases: [store] volumes: - name: data path: "{{ vars.dataPath }}" sysctls: net.core.somaxconn: 1024 ulimits: nofile: soft: 4096 hard: 8192 shm_size: 64m healthcheck: test: ["CMD", "redis-cli", "ping"] interval: 5s timeout: 3s retries: 12 scale: max: 1 peek: image: redis:7-alpine entrypoint: ["sh", "-c"] command: ["sleep infinity"] network_mode: service:counter pid: service:counter ipc: service:counter volumes_from: [counter] read_only: true tty: true depends_on: counter: condition: healthy$ shc update guestbook...$ shc exec -s guestbook -S web -- cat /run/secrets/api_keygb-key-0001A compose file says the same with x-shc-vault on a secret. A one-service
app that prints its key shows it:
services: holder: image: busybox:1.36 command: ["sh", "-c", "cat /run/secrets/token; sleep infinity"] secrets: - tokensecrets: token: x-shc-vault: ref+vault://api_keyname: keyholderversion: "1.0.0"title: Keyholderdescription: Prints the key it was givencategory: demolicense: id: MIT$ shc vault set api_key -s keyholder --value-file ~/learn/api-key.txt...$ shc install ~/learn/keyholder -s keyholder...$ shc logs holder -s keyholder...Change guestbook’s key: store the new value, then update so the render reads it again. The update sees the secret changed and restarts what mounts it.
gb-key-0002$ shc vault set api_key -s guestbook --value-file ~/learn/api-key.txt...$ shc update guestbook...$ shc exec -s guestbook -S web -- cat /run/secrets/api_keygb-key-0002An encrypted bundle moves secrets between clusters, or keeps a copy. Export guestbook’s, remove the key, and import it back.
$ shc vault export ~/learn/guestbook-secrets.enc -s guestbook -P P@ssw0rd...$ shc vault rm api_key -s guestbook --yes...$ shc vault ls -s guestbook -k api_key...$ shc vault import ~/learn/guestbook-secrets.enc -P P@ssw0rd...$ shc vault get api_key -s guestbookgb-key-0002--bundle-format json writes the bundle’s payload as JSON instead of YAML.
An import skips a key the target already holds unless --overwrite.
$ shc vault export ~/learn/guestbook-secrets-json.enc -s guestbook -P P@ssw0rd --bundle-format json...$ shc vault import ~/learn/guestbook-secrets-json.enc -P P@ssw0rd --overwrite...--stack and --remap-scope land an import under another deployment’s
name, for a bundle taken from a deployment called something else.
$ shc vault import ~/learn/guestbook-secrets.enc -P P@ssw0rd --stack keyholder$ shc vault import ~/learn/guestbook-secrets.enc -P P@ssw0rd --remap-scope tenant=prod,stack=keyholderThe vault itself is sealed by the password shc init was given. status
shows whether it is unlocked, and coldstart which node unlocks it after the
whole cluster restarts: home01, the only one. The groups page moves that duty
to another node once there is one.
$ shc vault status...$ shc vault coldstart...rotate re-encrypts every secret under a new password. Rotate to a new one
and back. unlock reads the password from a file only root reads.
P@ssw0rd$ chmod 600 ~/learn/vault.pw$ shc vault rotate --old-password P@ssw0rd --new-password N3w-P@ssw0rd...$ shc vault rotate --old-password N3w-P@ssw0rd --new-password P@ssw0rd...$ shc vault unlock --password-file ~/learn/vault.pw...A node whose auto-unlock file still holds a password an earlier rotation
replaced refuses the next rotation; --adopt-drop-in lets that rotation
overwrite it.
$ shc vault rotate --old-password P@ssw0rd --new-password N3w-P@ssw0rd --adopt-drop-inThe cluster’s vault is the default. vault.provider points SHC at an outside
secrets backend instead, configured under vault.providers. This ladder
keeps the cluster’s own.
$ shc config set vault.provider hashicorp --scope global$ shc config set vault.providers '{"hashicorp": {"url": "https://vault.example.com"}}' --scope globalNext: Jobs, hooks and schedules.