Skip to content
SHC Docs

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.

~/learn/api-key.txt
gb-key-0001
home01
$ 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 guestbook
gb-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.

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

explained, not walked: one asks at a terminal, and a password on the command line is seen by every process
$ shc vault
$ shc vault unlock --password P@ssw0rd

shc.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.

~/learn/guestbook/shc.yaml
where:
- location=learn/home
configs:
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_key
services:
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
home01
$ shc update guestbook
...
$ shc exec -s guestbook -S web -- cat /run/secrets/api_key
gb-key-0001

A compose file says the same with x-shc-vault on a secret. A one-service app that prints its key shows it:

~/learn/keyholder/compose.yaml
services:
holder:
image: busybox:1.36
command: ["sh", "-c", "cat /run/secrets/token; sleep infinity"]
secrets:
- token
secrets:
token:
x-shc-vault: ref+vault://api_key
~/learn/keyholder/app.yaml
name: keyholder
version: "1.0.0"
title: Keyholder
description: Prints the key it was given
category: demo
license:
id: MIT
home01
$ 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.

~/learn/api-key.txt
gb-key-0002
home01
$ 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_key
gb-key-0002

An encrypted bundle moves secrets between clusters, or keeps a copy. Export guestbook’s, remove the key, and import it back.

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

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

explained, not walked: copying guestbook's secrets onto keyholder would change what later pages list
$ 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=keyholder

The 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.

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

~/learn/vault.pw
P@ssw0rd
home01
$ 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.

explained, not walked: every rotation here completed, so no node is stranded
$ shc vault rotate --old-password P@ssw0rd --new-password N3w-P@ssw0rd --adopt-drop-in

The 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.

explained, not walked: the ladder keeps the cluster's own vault
$ shc config set vault.provider hashicorp --scope global
$ shc config set vault.providers '{"hashicorp": {"url": "https://vault.example.com"}}' --scope global

Next: Jobs, hooks and schedules.