Skip to content
SHC Docs

The same app in shc.yaml

This page moves guestbook from compose to shc.yaml, SHC’s own file for an app’s services. Every key in it is one SHC honours, and a key it does not name stops the install with an error that names the service and the key. Compose is the format most apps already have; shc.yaml is the one to write a new app in. shc convert prints the shc.yaml a compose file becomes and writes nothing, so send its output to the file.

home01
$ shc convert ~/learn/guestbook > ~/learn/guestbook/shc.yaml
$ cat ~/learn/guestbook/shc.yaml
...

shc.yaml is the app now. Delete the compose file it came from.

home01
$ rm ~/learn/guestbook/compose.yaml

The x-shc-* keys became plain keys: primary, health, scale, path and path_strip. deploy.replicas became replicas and each volume a mount entry with a name or a source. See shc.yaml.

Now replace it with a longer version that uses keys compose has no SHC meaning for. Add the file it reads first.

~/learn/guestbook/web.env
NGINX_ENTRYPOINT_QUIET_LOGS=1
~/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"; }
}
services:
web:
image: nginx:1.27-alpine
primary: true
replicas: 2
expose: [80]
hostname: guestbook-web
domainname: learn.test
environment:
TZ: UTC
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", "8080", "--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"]
expose: [6379]
restart: always
networks:
default:
aliases: [store]
volumes:
- name: data
path: /data
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

What the new keys do:

  • where places the deployment only on the nodes of location learn/home. On this cluster of one that is home01; the rule starts to choose once there are nodes elsewhere.
  • configs holds a file’s bytes in shc.yaml itself; web mounts this one as nginx’s site, which adds /healthz.
  • env_file, environment, labels, hostname and domainname are what compose means by them. env_file names a file of the app, and every replica gets it on whichever node it runs. labels may not start with shc..
  • tmpfs gives nginx the three directories it writes, in memory. read_only makes the root filesystems of api and peek read-only.
  • init, cap_add, pull_policy, stop_signal and stop_grace_period are the runtime’s: an init process, a capability from the default set, pull only a missing image, and stop nginx gracefully with up to 20 seconds to finish.
  • post_start runs a command in each web container once it starts.
  • quota is what the service may use. Its container limit is the quota times the cluster’s limit ratio.
  • user, group_add, working_dir, platform, security_opt, dns, dns_search and extra_hosts set how api runs and what it resolves.
  • networks gives counter a second name, store. sysctls, ulimits and shm_size tune its kernel and limits; restart is its policy.
  • peek joins counter’s network, process and IPC namespaces and its volumes, so the two are one pod and always run on one node. depends_on with condition: healthy starts it once counter’s healthcheck passes, and tty gives it a terminal, for a shell opened in it later.
  • The seed job is not in shc.yaml: a job is its own file, and seed.job.yaml stays as it is.

Escalating capabilities, the Docker socket and host devices go in a privileges block, which this app does not need. oci_runtime names an OCI runtime such as nvidia on a node that has one.

guestbook has no use for links or oci_runtime, so show both on a small app that is validated and never installed. shell joins cache’s pod through volumes_from, links gives it a second name for cache, kv, and oci_runtime names runc, the runtime every node already runs.

~/learn/pod/app.yaml
name: pod
version: "1.0.0"
title: Pod
description: Two services in one pod, read and never installed
category: demo
license:
id: MIT
~/learn/pod/shc.yaml
services:
cache:
image: redis:7-alpine
expose: [6379]
shell:
image: redis:7-alpine
entrypoint: ["sh", "-c"]
command: ["sleep infinity"]
volumes_from: [cache]
links: ["cache:kv"]
oci_runtime: runc
home01
$ shc validate ~/learn/pod
...

shc validate reads shc.yaml now, and shc update installs the new files.

home01
$ shc validate ~/learn/guestbook
...
$ shc update guestbook
...
$ shc status -s guestbook
...

Check what the new keys did.

home01
$ curl -sk --resolve guestbook.learn.test:443:127.0.0.1 https://guestbook.learn.test/healthz
ok
$ shc exec -s guestbook -S web -- cat /etc/nginx/conf.d/default.conf
...
$ shc exec -s guestbook -S web -- printenv NGINX_ENTRYPOINT_QUIET_LOGS
1
$ shc exec -s guestbook -S web -- cat /tmp/started
...
$ curl -sk --resolve guestbook.learn.test:443:127.0.0.1 https://guestbook.learn.test/api/
...
$ shc exec -s guestbook -S peek -- redis-cli -h 127.0.0.1 get visits
3
$ shc exec -s guestbook -S peek -- ls -d /data/appendonlydir
/data/appendonlydir
$ shc exec -s guestbook -S peek -- sh -c 'touch /etc/written 2>&1 || echo refused'
touch: /etc/written: Read-only file system
refused

post_start wrote the start time. api still answers as user 65534. peek reads the counter on 127.0.0.1 and sees its /data, since it shares both, and its touch is refused because its root filesystem is read-only.

Keep guestbook installed for the next page.

Next: Variables.