Variables
A variable is a setting the person installing an app may change. app.yaml
declares it with a type, vars.yaml gives it a default, and shc.yaml reads
it as {{ vars.<name> }}. Replace guestbook’s app.yaml and add vars.yaml
on home01.
name: guestbookversion: "1.1.0"title: Guestbookdescription: A page, an API under its path and a countercategory: demolicense: id: MITvars: greeting@string!: the line the page answers at /greeting maxSigners@int: how many people may sign open@bool: whether signing is open apiPort@port: the port the API listens on dataPath@path: where the counter keeps its data theme@json: colours the page uses owner: email@email: who runs the guestbook homepage@url:endpoint: the owner's page password@secret: the owner's passwordgreeting: Sign the guestbook.maxSigners: 100open: trueapiPort: 8080dataPath: /datatheme: '{"background": "white"}'owner: homepage: https://example.com password: "ref+vault://owner_password?autogen"title, description and category are new too: they are what listings
and the catalogue show. Each leaf under vars is <name>@<type>. ! makes
it required. @secret keeps the value
in the vault, and ?autogen makes one on the first install. @url also
names what a move of the app does to it: endpoint is replaced by the new
address. owner groups three variables, read as vars.owner.email and so
on. See Variables and
App variables.
Use them in shc.yaml. Only the lines that change are new: site answers
/greeting, api listens on apiPort, counter keeps its data at
dataPath, and web gets the owner’s address and the signing settings.
api’s expose stays a number: SHC reads the port a route goes to before it
fills in variables, so change apiPort and expose together.
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"; } }services: web: image: nginx:1.27-alpine primary: true replicas: 2 expose: [80] 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: healthyUpdate the deployment, then read what the variables became.
$ shc update guestbook...$ shc exec -s guestbook -S web -- printenv OWNER_EMAIL SIGNING_OPEN MAX_SIGNERS...$ shc vault ls -s guestbook...The owner’s password is in the vault, not in any file. --var changes a
variable at install or update, and the deployment keeps the new value for
every later update.
$ shc update guestbook --var greeting="Welcome back."...$ curl -sk --resolve guestbook.learn.test:443:127.0.0.1 https://guestbook.learn.test/greetingWelcome back.--check says whether the app’s files changed since the deployment was last
rendered, and changes nothing. --quiet drops an update’s progress lines.
$ shc update guestbook --check...$ shc update guestbook --quiet...Install and update take the same flags for what a deployment may use and how
it starts. --cpu-quota and --memory-quota set one service’s quota over
the file’s. --naming-exception records why a deployment keeps a name that
is not the hostname it serves. --no-rollback leaves a failed install in
place to inspect, and --no-wait returns before the containers report
healthy. Try them on a spare copy and remove it.
$ shc install ~/learn/guestbook -s spare --cpu-quota web=0.5 --memory-quota web=128M --naming-exception "a spare copy for this page" --no-rollback --no-wait --quiet...$ shc uninstall spare --no-backup --yes --quiet...--config-set writes a config row at the deployment’s own scope, and on an
update key! removes it. --interactive opens the variables form, prefilled
with the deployment’s values.
$ shc update guestbook --cpu-quota web=0.5 --memory-quota web=128M --naming-exception "the hostname is the app's" --no-wait$ shc update guestbook --config-set deploy.limit_ratio=2$ shc install ~/learn/guestbook -s spare --config-set deploy.limit_ratio=2$ shc install ~/learn/guestbook -s spare --interactive$ shc update guestbook --interactiveNext: Your own catalogue.