Skip to content
SHC Docs

Coming from Kubernetes

New line, in development. This page describes SHC as it is on the dev branch, not the released product. See The new line.

SHC runs no Kubernetes. It has no Kubernetes API, no manifest or Helm import, no operators, and runs no Kubernetes distribution as an app. An app that ships only for Kubernetes runs on SHC as an SHC app: a directory with app.yaml and compose.yaml, plus job, plug and backup files when it needs them, installed with shc install.

This page takes each Kubernetes object, shows a short manifest beside the way SHC writes the same thing, and says what differs. Where SHC has no equivalent the section says Not supported and names what to do instead.

Every command on this page runs in a tenant, the way kubectl runs in a namespace. Select it once, as Namespaces explains, and the examples below need no -t. A cluster made through the portal already has default; on a cluster you installed yourself, first shc tenant add default (Tenants):

Terminal window
shc tenant ls
shc ctx -t default

Checked against shc next 8df982a01c, which pins ce 6aeae95bb7, on 2026-10-10. The whole app ran on a four-node test cluster at that pin, and so did the snippets for replicas, the scale ceiling, the rolling update, the sidecar, the path route, the global service, the config, the secret, the start job, the job, the cron, the published port and the refused host path.

KubernetesSHC
PodA service. Services that share a namespace form one pod.
Deployment, ReplicaSetdeploy.replicas and --scale
StatefulSetA group, written with {% members %}
DaemonSetdeploy.mode: global
Rolling update strategydeploy.update_config
PodDisruptionBudgetdeploy.disruption, the operator’s config key
Service, ClusterIPexpose:, the service’s name and its VIP
Service, NodePort--expose <port>=<service>:<port>
Service, LoadBalancer--expose <port>@<connection>=<service>:<port> on a load-balancer connection
Service, headlessNot supported. A group’s members each have a name.
Ingress--expose <hostname>, x-shc-primary, x-shc-path
ConfigMapTop-level configs: with content:, or a file in the app
SecretThe vault: x-shc-vault, or a @secret variable
PersistentVolumeClaim, PersistentVolume, StorageClassA named volume, x-shc-volumes, a volume provider
emptyDirA tmp* volume, or tmpfs
hostPathA data volume of the deployment. A bind that reaches the host needs a grant.
JobA <name>.job.yaml file, shc job run
CronJobcrons: in app.yaml, shc schedule
Init containerA start job with before:
SidecarA service with network_mode: service:<name>
Requests and limitsdeploy.resources, read as a quota
kubelet --system-reserved, --kube-reservedshc node update <node> --reserve
Liveness, readiness and startup probeshealthcheck, SHC-HTTP, SHC-TCP, x-shc-health
nodeSelector, affinity, anti-affinity--where, --prefer and node labels
Taints and tolerationsshc label set <value> --reserved is the taint and a rule naming the value is the toleration. Any tenant can write that rule unless the reservation names tenants, --reserved acme,beta, and the platform’s own per-node agents run there anyway.
HorizontalPodAutoscalerNot supported
NamespaceTenant, environment and deployment
RBACshc user grant with SHC’s roles
NetworkPolicyA fixed policy. There is nothing to write.
securityContext, privileged, capabilitiesCompose keys. What reaches the host needs a grant on the deployment.
Helm chartRepackaged as an SHC app
Operators and CRDsNot supported, by design

A Deployment of two nginx replicas, its Service and Ingress, and Redis on a PersistentVolumeClaim:

apiVersion: apps/v1
kind: Deployment
metadata:
name: web
spec:
replicas: 2
selector:
matchLabels: {app: web}
template:
metadata:
labels: {app: web}
spec:
containers:
- name: web
image: nginx:1.27-alpine
ports:
- containerPort: 80
readinessProbe:
httpGet: {path: /, port: 80}
resources:
limits: {cpu: 500m, memory: 256Mi}
---
apiVersion: v1
kind: Service
metadata:
name: web
spec:
selector: {app: web}
ports:
- port: 80
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: web
spec:
rules:
- host: web.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: web
port: {number: 80}
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: data
spec:
accessModes: [ReadWriteOnce]
resources:
requests:
storage: 1Gi
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: cache
spec:
replicas: 1
strategy: {type: Recreate}
selector:
matchLabels: {app: cache}
template:
metadata:
labels: {app: cache}
spec:
containers:
- name: cache
image: redis:7-alpine
args: ["redis-server", "--appendonly", "yes"]
ports:
- containerPort: 6379
volumeMounts:
- name: data
mountPath: /data
volumes:
- name: data
persistentVolumeClaim:
claimName: data
---
apiVersion: v1
kind: Service
metadata:
name: cache
spec:
selector: {app: cache}
ports:
- port: 6379

The same app in SHC is a directory of three files:

k8sdemo/app.yaml
name: k8sdemo
version: "1.0.0"
title: K8s demo
description: A web Deployment, its Service and Ingress, and a cache on a volume, written for SHC
category: demo
license:
id: MIT
k8sdemo/compose.yaml
services:
web:
image: nginx:1.27-alpine
expose:
- "80"
healthcheck:
test: ["SHC-HTTP", ":80/"]
interval: 10s
timeout: 3s
retries: 3
deploy:
replicas: 2
resources:
limits:
cpus: "0.5"
memory: 256M
x-shc-primary: true
cache:
image: redis:7-alpine
command: ["redis-server", "--appendonly", "yes"]
expose:
- "6379"
volumes:
- data:/data
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 5s
timeout: 3s
retries: 12
x-shc-scale:
max: 1
k8sdemo/backup.yaml
include: [data]
Terminal window
shc validate ./k8sdemo
shc install ./k8sdemo -s k8sdemo --expose web.example.com

The install waits for every healthcheck and prints Healthy 2/2. shc status k8sdemo lists web-r0, web-r1 and cache-r0 ready, and shc ingress ls shows the route to web marked front door. What changed on the way:

  • Six objects became one directory. A service’s name is its selector: there are no labels to match.
  • expose: ["80"] declares the port. Services of the same tenant can reach it; nothing outside the cluster can until the deployment publishes it.
  • The Ingress is the --expose flag on the deployment, not a file in the app. x-shc-primary names the service a bare hostname reaches.
  • data needs no claim. SHC declares it and binds a directory of the deployment, mounts/data, on the node that runs cache, or a block volume where the cluster has a volume provider. backup.yaml lists the volume under include, so a backup copies it and a move carries it, and a replica whose kept volume is on its node’s own disk stays on that node.
  • x-shc-scale.max: 1 does the job of Recreate and more. shc update k8sdemo --scale cache=2 is refused (X400083PODSCL), and no update or move runs two copies at once.
  • The limits are read as a quota. The container runs with 1.5 times the quota as its limit, 0.75 CPU and 384M, and reserves the quota itself, 0.5 CPU and 256M. See requests and limits.

What SHC does to your compose file lists every compose key and what the render does with it. x-shc directives lists every x-shc-* key.

apiVersion: v1
kind: Pod
metadata:
name: tools
spec:
restartPolicy: Never
containers:
- name: tools
image: busybox:1.36
command: ["sh", "-c", "echo done"]
services:
tools:
image: busybox:1.36
command: ["sh", "-c", "echo done"]
restart: "no"

The unit you write is a service, one container image. SHC makes a pod only of services that share a namespace with another service or mount its volumes with volumes_from (see Sidecars). restart takes no, always, on-failure or unless-stopped. With none, a service that exits 0 has completed and is left down, one that fails is restarted, and one the node’s shutdown stopped comes back at boot. The node agent applies it; the runtime itself is given restart: "no". Work that runs once for the deployment is better written as a job.

apiVersion: apps/v1
kind: Deployment
metadata:
name: web
spec:
replicas: 3
selector:
matchLabels: {app: web}
template:
metadata:
labels: {app: web}
spec:
containers:
- name: web
image: nginx:1.27-alpine
services:
web:
image: nginx:1.27-alpine
deploy:
replicas: 3
x-shc-scale:
max: 6
Terminal window
shc update k8sdemo --scale web=4

deploy.replicas is the count when no --scale names the service. --scale changes it at install or update, and the deployment keeps that count for later updates. x-shc-scale.max is a hard ceiling: a count above it is refused, never clamped. Replicas are named web-r0, web-r1 and up; scaling down removes the highest. There is no ReplicaSet to read: the deployment keeps its rendered spec, and an update rolls its replicas from the old spec to the new one. See Replicas and pods.

apiVersion: apps/v1
kind: StatefulSet
metadata:
name: db
spec:
serviceName: db
replicas: 3
selector:
matchLabels: {app: db}
template:
metadata:
labels: {app: db}
spec:
containers:
- name: db
image: postgres:17
ports:
- containerPort: 5432
volumeMounts:
- name: data
mountPath: /var/lib/postgresql/data
volumeClaimTemplates:
- metadata:
name: data
spec:
accessModes: [ReadWriteOnce]
resources:
requests:
storage: 10Gi
services:
{% members "db", default=3, max=5 as m %}
db-{{ m.n }}:
image: postgres:17
expose:
- "5432"
volumes:
- data-{{ m.n }}:/var/lib/postgresql/data
{% endmembers %}
Terminal window
shc update db --scale db=5
shc update db --scale db=2@home,1@far

A group stamps numbered members, each with its own services, name and volume. db-1, db-2 and db-3 are reached by those names, and each has its own VIP on the shc fabric. Numbering starts at 1, not 0. Numbers are stable: scaling up adds the next numbers, scaling down retires the highest and keeps their volumes, and scaling back up brings them back. Placement prefers a node no other member holds, and --scale db=2@home,1@far holds members to locations.

There is no ordered start policy like OrderedReady. Order what the app needs with depends_on and condition: service_healthy, or a start job. Setting up replication between members is the app’s work, as it is in a StatefulSet. To give the members one name that follows the current primary, see Headless Service. Full rules: Groups.

apiVersion: apps/v1
kind: DaemonSet
metadata:
name: agent
spec:
selector:
matchLabels: {app: agent}
template:
metadata:
labels: {app: agent}
spec:
containers:
- name: agent
image: busybox:1.36
command: ["sleep", "infinity"]
services:
agent:
image: busybox:1.36
command: ["sleep", "infinity"]
deploy:
mode: global

A global service runs one replica on each eligible ready node with room for its reservation. --where on the deployment narrows the nodes, as a DaemonSet’s nodeSelector would. A node that joins later gets a replica; a full node gets none and logs X409679SCHGLB. A drain stops global replicas last.

spec:
minReadySeconds: 10
strategy:
type: RollingUpdate
rollingUpdate:
maxSurge: 1
maxUnavailable: 0
services:
web:
image: nginx:1.27-alpine
deploy:
replicas: 3
update_config:
parallelism: 1
order: start-first
monitor: 10s
failure_action: rollback
Kubernetesdeploy.update_config
maxSurge: 1, maxUnavailable: 0order: start-first: the new replica starts before the old one stops
maxSurge: 0, maxUnavailable: 1order: stop-first, the default
replicas changed per stepparallelism, default 1. 0 takes every replica in one batch.
type: Recreateparallelism: 0 with stop-first comes closest
minReadySecondsmonitor, default 5s. A replica that reports failure inside it counts as failed.
pause between stepsdelay
progressDeadlineSeconds and kubectl rollout undofailure_action: rollback. The default is pause; continue is the third value. max_failure_ratio tolerates a share of failures.

deploy.rollback_config takes the same keys for the way back, with failure_action of pause or continue. An unknown key or bad value is refused X400725UPDCFG, and so is start-first on a service with x-shc-scale.max: 1, since it would run two writers. These keys are read by SHC’s own rollout (ce core/placement/rollout.go ParseUpdateConfig).

An update whose rollout fails stops where it is, as a failed helm upgrade does: replicas that moved stay moved and the ready ones keep serving, unless a service’s update_config says failure_action: rollback. Running shc update <deployment> again, with the same spec or a new one, goes forward from there and never rolls back first; once it finishes, its post_update jobs run. shc update <deployment> --rollback goes back to the last version that finished its rollout, never to the failed attempt.

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
name: wiki
spec:
maxUnavailable: 0
selector:
matchLabels: {app: wiki}

SHC has no object for it. How much of a deployment the cluster may take down is the operator’s setting, not the app’s: deploy.disruption, set on the deployment.

Terminal window
shc update wiki -c deploy.disruption=never

rolling, the default, lets a drain move one replica of a service at a time, each ready on its new node before the next is touched: maxUnavailable: 1 by another name. never blocks a drain of any node the deployment runs on. shc node drain refuses X400423CLSDRM and names it, unless --force is given. It never blocks your own shc update. There is no number and no minAvailable, and an app cannot set it: a compose file that carries x-shc-disruption is refused X400330XSHUNK.

spec:
initContainers:
- name: migrate
image: busybox:1.36
command: ["sh", "-c", "echo migrated"]
containers:
- name: web
image: nginx:1.27-alpine
migrate.job.yaml
name: migrate
context: container
image: busybox:1.36
after: [cache]
before: [web]
command: ["sh", "-c", "echo migrated"]
timeout: 60

A job file with after: or before: is a start job. before: [web] holds web until the job ended 0; after: [cache] waits for cache to read ready first. It runs once for the whole deployment at each install and update, not once per replica start, and never on a restart. A failure fails the install, which rolls back, or ends the update before its spec commits. before: [web:stopped] stops the old web replicas first, for work that must not run beside the old version. Setup each replica needs at every start belongs in the image’s entrypoint. See Start jobs.

spec:
containers:
- name: web
image: nginx:1.27-alpine
- name: side
image: busybox:1.36
command: ["sleep", "infinity"]
services:
web:
image: nginx:1.27-alpine
expose:
- "80"
side:
image: busybox:1.36
command: ["sleep", "infinity"]
network_mode: service:web

network_mode: service:web puts side in web’s network namespace, so side reaches nginx on 127.0.0.1:80. The two are one pod: they are placed together, --scale web=3 gives three of each, and side-r1 joins web-r1. pid: service:web, ipc: service:web and volumes_from: [web] make a pod the same way. A podman node cannot share pid or ipc, so such a pod is kept on docker nodes.

apiVersion: batch/v1
kind: Job
metadata:
name: report
spec:
backoffLimit: 0
activeDeadlineSeconds: 60
template:
spec:
restartPolicy: Never
containers:
- name: report
image: busybox:1.36
command: ["sh", "-c", "ls /data"]
volumeMounts:
- name: data
mountPath: /data
readOnly: true
volumes:
- name: data
persistentVolumeClaim:
claimName: data
report.job.yaml
name: report
context: container
image: busybox:1.36
command: ["sh", "-c", "ls /data"]
volumes:
- data:/data:ro
timeout: 60
Terminal window
shc job run report -s k8sdemo --wait

A job is a file of the app, <name>.job.yaml. It runs when you run it, from a lifecycle hook in app.yaml, on a schedule, or as a start job. context: container starts a container that runs once; context: service runs the command inside a running replica of a service, like kubectl exec; context: http sends a request. timeout is in seconds. shc job ps lists runs in progress and shc job history the ones that ended.

Not supported: retries for a container or service job (backoffLimit), and completions and parallelism: a run is one container, once. max_retries and retry_interval exist for the http and graphql contexts only. See Jobs, hooks and schedules.

apiVersion: batch/v1
kind: CronJob
metadata:
name: report
spec:
schedule: "0 3 * * *"
jobTemplate:
spec:
template:
spec:
restartPolicy: Never
containers:
- name: report
image: busybox:1.36
command: ["sh", "-c", "ls /data"]
app.yaml
crons:
report: "0 3 * * *"

crons: maps a job of the app to a cron expression, and the install makes it a schedule of the deployment. An operator changes schedules without editing the app; the next update puts the app’s own cron back.

Terminal window
shc schedule ls -s k8sdemo
shc schedule edit report "0 4 * * *" -s k8sdemo
shc schedule disable report -s k8sdemo
shc schedule enable report -s k8sdemo

disable is the suspend: true of a CronJob. shc schedule add <job> <cron> -s <deployment> schedules a job the app did not.

apiVersion: v1
kind: Service
metadata:
name: api
spec:
selector: {app: api}
ports:
- port: 80
targetPort: 8080
services:
api:
image: traefik/whoami:v1.10
command: ["--port", "8080"]
expose:
- "8080"

A service that declares a port under expose: is reachable on that port. Inside its deployment the short name answers: api:8080. From another deployment of the same tenant the full name does: api.<deployment>.<environment>.<tenant>.shc.internal:8080. On a cluster on the shc fabric that name resolves to the service’s VIP, which sends each connection to a ready replica on the same port.

Three differences. There is no Service object: the compose service is one. There is no port remap inside the cluster: callers dial the port the container listens on, and only a published port can differ from it. A service with no expose: is private to its deployment. To give a set of replicas a name chosen by their labels, as a Service’s selector does, declare a service selector under x-shc-service-selectors. It gets its own VIP, like any service. Another tenant never reaches the service (NetworkPolicy).

apiVersion: v1
kind: Service
metadata:
name: web
spec:
type: NodePort
selector: {app: web}
ports:
- port: 80
nodePort: 30080
Terminal window
shc update k8sdemo --expose 30080=web:80
shc update k8sdemo --expose '30080!' --expose '30080@(edge=true)=web:80'

--expose <outside port>=<service>:<container port> publishes a port. With no @ every node listens, or the nodes the cluster key publish.listen selects; @(<selector>) or @<location> picks the listening nodes. Any port SHC does not own works, not only 30000-32767. A listening node sends a connection to a ready replica of its own, then one under the deepest location level it shares with any ready replica, then any if no level is shared. Levels compare whole path segments; an empty location shares no level; +spread sends it to any ready replica. A trailing ! removes a published port. SHC’s own ports are refused: 80 and 443 belong to the edge. See Published ports.

apiVersion: v1
kind: Service
metadata:
name: web
spec:
type: LoadBalancer
selector: {app: web}
ports:
- port: 8443
targetPort: 8443
Terminal window
shc update shop --expose 8443@hetzner=web:8443
shc update db --expose db.example.com:5432=db

A port published @ a connection whose provider runs load balancers (Hetzner’s hcloud-lb, from shc connection connect hetzner) gets that load balancer, which targets the nodes whose listener for the port has a ready replica behind it, on a node port. A hostname with a port, as in the second line, also gets a DNS record on the tenant’s DNS connection. On a cluster with no load-balancer connection, publish the port on the nodes and point your own load balancer or DNS at them.

apiVersion: v1
kind: Service
metadata:
name: db
spec:
clusterIP: None
selector: {app: db}
ports:
- port: 5432

Not supported. A container that resolves a service gets its VIP, not each replica’s address, and web-r0 and web-r1 have no names of their own. When the copies differ, as a StatefulSet’s do, write a group: each member is its own service with its own name. For one name that follows whichever member is primary, declare a live label and a service selector that picks by it:

x-shc-service-selectors:
db: role=primary:1
services:
{% members "pg", default=3 as m %}
pg-{{ m.n }}:
image: postgres:17
expose:
- "5432"
x-shc-live-labels:
role:
test: ["CMD-SHELL", "psql -U postgres -Atc \"select case when pg_is_in_recovery() then 'replica' else 'primary' end\""]
interval: 5s
timeout: 3s
{% endmembers %}

db then answers on exactly one replica whose role label reads primary, and refuses connections when none or several do.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: shop
annotations:
cert-manager.io/cluster-issuer: letsencrypt
spec:
tls:
- hosts: [shop.example.com]
secretName: shop-tls
rules:
- host: shop.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: web
port: {number: 80}
- path: /api
pathType: Prefix
backend:
service:
name: api
port: {number: 8080}
services:
web:
image: nginx:1.27-alpine
expose:
- "80"
x-shc-primary: true
api:
image: traefik/whoami:v1.10
command: ["--port", "8080"]
expose:
- "8080"
x-shc-path: /api
x-shc-path-strip: true
Terminal window
shc config set acme.email [email protected]
shc config set acme.providers.letsencrypt.directory https://acme-v02.api.letsencrypt.org/directory
shc config set acme.default letsencrypt
shc install ./shop -s shop --expose shop.example.com --public

Routes go through the cluster’s one system Traefik, which listens on 80 and 443.

  • Host. --expose shop.example.com routes the hostname to the service marked x-shc-primary, the front door, and follows it if the app moves the marker. --expose shop.example.com=web:80 pins the route to a service and port instead. Repeat --expose for more hostnames.
  • Path. The app declares x-shc-path: /api and the route gets /api beside the front door. x-shc-path-strip: true strips the prefix before the request reaches api, as a rewrite annotation would. An operator adds a path of their own with --expose shop.example.com/docs=web:80. Paths match by prefix; pathType: Exact is not supported.
  • TLS. There is no TLS block to write. Every routed hostname gets a certificate from the tenant’s own CA. A --public route gets one from the ACME provider once acme.* is set, over DNS-01 when a DNS connection of the tenant owns the hostname’s zone and over HTTP-01 otherwise. A certificate you bring for one hostname, a secretName, is not supported: import your CA with shc ca import, or let an app that ends TLS itself receive the hostname’s certificate (Your own ingress).
  • Exposure. A route answers only the cluster’s own networks until --public; shc update shop --private takes that back. --gated puts Keycloak login in front of the app.
  • Ingress classes and annotations are not supported. An authored traefik.* label is refused X400358LBLTRF: routes come from --expose only.

shc ingress ls lists every route with its upstream. See A hostname and a certificate.

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: cache
spec:
podSelector:
matchLabels: {app: cache}
ingress:
- from:
- podSelector:
matchLabels: {app: web}
ports:
- port: 6379

SHC has no policy to write. The fabric’s policy is derived from what deployments declare, and the unit is the deployment:

  • Inside a deployment everything is open.
  • Inside a tenant, another deployment reaches a service only on the ports the service declares. A service with no declared port is private to its deployment.
  • Between tenants nothing is reached, apart from SHC’s system tier, such as the system Traefik in front of routed hostnames. The node’s DNS answers a container only the names of its own tenant.
Terminal window
shc cluster fabric explain shop:web k8sdemo:cache --port 6379

explain judges one flow against the compiled policy and names the rule that decided it. Rules per container or per label, egress rules and CIDR rules are not supported. Put services that must not meet in different tenants. See The fabric and its policy.

apiVersion: v1
kind: ConfigMap
metadata:
name: web-conf
data:
extra.conf: |
server_tokens off;
---
# in the pod spec
containers:
- name: web
image: nginx:1.27-alpine
volumeMounts:
- name: conf
mountPath: /etc/nginx/conf.d/extra.conf
subPath: extra.conf
volumes:
- name: conf
configMap:
name: web-conf
services:
web:
image: nginx:1.27-alpine
configs:
- source: web_conf
target: /etc/nginx/conf.d/extra.conf
configs:
web_conf:
content: |
server_tokens off;

A config is inline content: in the app, and compose.yaml is a Jinja template, so {{ vars.<name> }} fills it in at render. A service that uses a config is rolled when its content changes. A config read from a host file or the daemon’s environment (file:, environment:) is refused X400944CFGHST. Two other forms carry configuration: a file shipped in the app directory, ./config/app.ini:/etc/app.ini:ro, and environment: values filled from variables the operator sets with --var.

apiVersion: v1
kind: Secret
metadata:
name: api
stringData:
token: s3cr3t
---
containers:
- name: web
env:
- name: API_TOKEN
valueFrom:
secretKeyRef: {name: api, key: token}

As a file, which never reaches the node’s disk:

services:
web:
image: nginx:1.27-alpine
secrets:
- api_token
secrets:
api_token:
x-shc-vault: ref+vault://api_token?autogen

As an environment variable, through a secret variable:

app.yaml
vars:
apiToken@secret!: the API token
vars.yaml
apiToken: "ref+vault://api_token?autogen"
compose.yaml
services:
web:
image: nginx:1.27-alpine
environment:
API_TOKEN: "{{ vars.apiToken }}"
Terminal window
shc vault set api_token -s k8sdemo --value-file ./api-token.txt
shc update k8sdemo

Secrets live in the cluster’s vault, never in the app. ?autogen mints a value on the first install. A compose secret is read from the vault into a RAM-backed file mounted at /run/secrets/<name>, and the rendered compose keeps only the reference. After shc vault set, shc update restarts the services that mount it. A read walks from the deployment to its tenant to the cluster and takes the first value it finds; --scope reads or writes one tier.

PersistentVolumeClaim, PersistentVolume, StorageClass

Section titled “PersistentVolumeClaim, PersistentVolume, StorageClass”
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: pgdata
spec:
storageClassName: hcloud-volumes
accessModes: [ReadWriteOnce]
resources:
requests:
storage: 20Gi
services:
db:
image: postgres:17
volumes:
- pgdata:/var/lib/postgresql/data
x-shc-scale:
max: 1
x-shc-volumes:
pgdata:
size: 20Gi
access: rwo
Terminal window
shc install ./db -s db --storage hetzner

A named volume is the claim; SHC declares it at the top level itself. Where the node has a volume provider (a cloud’s block storage, from a connection), a volume with a size, or one backup.yaml keeps, is provisioned there at that size and bound from its mountpoint. With none, it is a directory of the deployment, mounts/<name>, on the node’s own disk, with no size limit. --storage names the provider, as storageClassName does; shc storage ls lists them and shc volume ls lists provisioned volumes, the PersistentVolumes.

KubernetesSHC
ReadWriteOnceaccess: rwo, the default
ReadOnlyManyaccess: rox, where the provider supports it
ReadWriteManyNot supported, refused X400328VOLACC. Give the data one writer, or keep shared files in object storage the app reaches through a plug.
volumeClaimTemplatesdata-{{ m.n }} in a group
what to keep in a backupbackup.yaml: include volumes are backed up and carried, unlisted ones are scratch and recreated empty

A replica whose kept volume sits on its node’s own disk is pinned to that node and waits for it if the node is lost.

volumes:
- name: scratch
emptyDir: {}
- name: fast
emptyDir: {medium: Memory}
services:
web:
image: nginx:1.27-alpine
volumes:
- tmp-cache:/var/cache/scratch
tmpfs:
- /tmp

A named volume whose name starts with tmp or temp is scratch: it is bound from the deployment’s runtime directory and never backed up, and shc validate says so. tmpfs is memory, empty at every start.

volumes:
- name: logs
hostPath: {path: /var/log}
services:
reader:
image: busybox:1.36
volumes:
- /var/log:/logs:ro

A host path becomes a data volume of the deployment at install. Here /var/log becomes the volume host-var-log, mounted read-only at /logs. The install logs X200338VOLHST naming the path and the volume, and shc validate reads the same rewritten document. The volume starts empty: SHC never opens a host directory into a container, so a log shipper reading the node’s own /var/log has no equivalent, and SHC collects every container’s logs itself. A volume made from a host path is kept by default: a move carries it and a delete names it, but a backup copies it only when backup.yaml lists it under include.

A host file mounted at a file’s path becomes a file inside its own data volume. /etc/machine-id:/etc/machine-id:ro mounts the file machine-id of the volume hostfile-etc-machine-id, a copy of the image’s own /etc/machine-id, or empty when the image has none, and X200338VOLHST says file instead of directory. A path is a file’s when it is a known one such as /etc/machine-id or /etc/hosts, or its name ends in a file extension such as .conf, .yaml or .pem. Anything else is a directory, /etc/nginx/conf.d and /etc/cron.d included. A path inside the app’s own files (./nginx.conf) keeps the kind it has there. The volume is backed up like any other and stays on the node disk. A job or hook that names the same host path mounts the same file as the service.

To fill it from the daemon’s host, mount it there and copy in:

Terminal window
shc volume mount host-var-log -s hostlogs --read-write

It prints the path the volume’s data is bound at, leased for an hour; shc volume umount <handle> releases it sooner.

/etc/localtime and /etc/timezone are the platform’s and mount read-only from the node. A bind of /dev/urandom or /dev/random is dropped and the container uses its own device. /etc/shc/<name> is a read-only platform mount.

What reaches the host runs only with a grant on the deployment: the Docker socket, which mounts the deployment’s own broker socket and never the host’s (The Docker socket), a device, a host namespace, and the rest of securityContext, privileged and capabilities.

resources:
requests: {cpu: 250m, memory: 256Mi}
limits: {cpu: 500m, memory: 512Mi}
services:
web:
image: nginx:1.27-alpine
deploy:
resources:
limits:
cpus: "0.5"
memory: 512M
reservations:
cpus: "0.25"
memory: 256M

SHC reads deploy.resources.limits as the service’s quota. The quota is what is charged against caps. The reservation, written or derived as the quota times 1.0, is what placement fits on a node, like a request. The container’s limit is the quota times deploy.limit_ratio, 1.5 by default, so this service runs with 0.75 CPU and 768M. For a limit equal to the quota, set the ratio to 1 (shc config set deploy.limit_ratio 1) and update the deployment. An operator overrides one service with --cpu-quota web=1 --memory-quota web=512M.

Service-level cpus and mem_limit reach the runtime but escape the quota and placement, so write deploy.resources. A service with neither reserves nothing. Namespace-wide caps are shc quota set (Namespaces). See The resource model.

Terminal window
shc node update home01 --reserve cpu=1,memory=4Gi,disk=50Gi

A kubelet’s --system-reserved keeps room on a node for the host. In SHC the reserve is a property of the node: what it keeps for work outside SHC, which placement and admission never use. It comes on top of what SHC already counts for the containers and Incus instances it did not start. A resource set to 0 clears it, and shc node ls -v shows it as RESERVED.

startupProbe:
httpGet: {path: /healthz, port: 8080}
failureThreshold: 30
periodSeconds: 2
readinessProbe:
httpGet: {path: /healthz, port: 8080}
periodSeconds: 10
livenessProbe:
httpGet: {path: /healthz, port: 8080}
periodSeconds: 10
failureThreshold: 3
services:
api:
image: ghcr.io/example/api:1.0
expose:
- "8080"
healthcheck:
test: ["SHC-HTTP", ":8080/healthz"]
interval: 10s
timeout: 3s
retries: 3
start_period: 60s
x-shc-health:
restart_after: 30s

One healthcheck answers all three questions.

KubernetesSHC
readinessThe healthcheck. Routes, VIPs and published ports send traffic only to ready replicas, and an install or update waits for them. A replica whose readiness flips 4 times in 10 minutes is held out while another replica of its service is ready, until it reads ready for 5 minutes; its service’s health reads flapping.
livenessThe same healthcheck plus x-shc-health.restart_after: a replica unhealthy that long is restarted by its node. Default 5 minutes, 0 turns it off.
startupstart_period: failures inside it do not count.
httpGet["SHC-HTTP", ":PORT/PATH"], sent by the node, so the image needs no client. 2xx and 3xx pass.
tcpSocket["SHC-TCP", ":PORT"]
exec["CMD", ...] or ["CMD-SHELL", "..."], run by the runtime inside the container
periodSeconds, timeoutSeconds, failureThresholdinterval, timeout, retries
grpcNot supported. Use a CMD check with a gRPC health client in the image.
separate readiness and liveness checksNot supported. One check per service.

A service with no healthcheck is ready when it runs, and shc status counts it under NO HEALTHCHECK. See Health probes.

spec:
nodeSelector:
disktype: ssd
affinity:
podAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
- labelSelector:
matchLabels: {app: db}
topologyKey: kubernetes.io/hostname
Terminal window
shc node label n1 disktype=ssd
shc install ./shop -s shop --where 'disktype=ssd & node=@(stack=db)'

Placement rules belong to the deployment, not to the app’s files. A node carries labels SHC derives (node, location at every level, cloud, runtime) and the ones an operator sets with shc node label.

KubernetesSHC
nodeSelector, required node affinity--where 'disktype=ssd'
preferred node affinity--prefer 'tier=gold'
pod affinity to another app--where 'node=@(stack=db)', the nodes of db’s replicas
pod anti-affinity to another app--where 'node!=@(stack=db)'
anti-affinity between replicas of one appAutomatic: placement spreads a deployment’s replicas itself, and a group’s members prefer separate nodes
zone affinity--where 'location=hetzner/hel1'
topologySpreadConstraints--scale web=1/location, or counts per location: --scale web=2@east,1@west
a rule for a whole team or clustershc constraint set --where '...' --scope tenant or --scope cluster

placement.constraints in compose (node.labels.disktype==ssd) is translated into the deployment’s --where with a warning. A rule change on shc update prints the move it causes and asks first; --plan prints it and stops. See Labels and selectors.

shc label set <value> --reserved is the taint and a rule naming the value is the toleration. Any tenant can write that rule unless the reservation names tenants, --reserved acme,beta, and the platform’s own per-node agents run there anyway.

Not supported. SHC never changes a replica count by itself. Change it with shc update <deployment> --scale web=<n> or a deployfile. shc status <deployment> --resources shows measured CPU and memory per deployment, and x-shc-scale.max caps the count. A vertical autoscaler is not supported either.

A namespace does two jobs in Kubernetes: it isolates teams and it names one copy of an app. SHC splits them.

SHCWhat it is
tenantThe isolation boundary: its own deployments, vault, Keycloak realm, CA and network. One tenant never sees another’s.
environmentA copy of the same deployments, such as prod and staging, with its own data and secrets. The first install into one makes it.
deploymentOne app in one tenant and environment, named with -s. It is the unit of placement, policy, backup and scale.
Terminal window
shc tenant add acme
shc install ./shop -s shop -t acme -e staging
shc ctx -t acme -e staging
shc quota set --scope tenant -t acme --cpu 2000m --memory 4g --max-apps 5

-t and -e name the tenant and environment on any command; shc ctx sets them for the commands that follow, as kubectl config set-context --namespace does. shc quota set is the ResourceQuota, at tenant, environment, stack or deployment scope. A LimitRange is not supported. The first tenant besides master is free; a second needs a licence that includes tenancy.

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: alice-view
namespace: shop
subjects:
- kind: User
name: alice
roleRef:
kind: ClusterRole
name: view
apiGroup: rbac.authorization.k8s.io
Terminal window
shc user create alice "Alice Liddell" [email protected] --tenant prod
shc user grant alice tenant:read --tenant prod
shc user grant bob tenant:manage --tenant prod
shc user grant alice stack:shop --tenant prod
shc user revoke alice tenant:read --tenant prod

Users live in each tenant’s Keycloak realm, and a role is a scope and a name. tenant:read reads every deployment’s logs and status in the tenant, tenant:manage administers the tenant, stack:<deployment> opens that deployment through the SSO gate, and platform:manage administers the cluster. Custom roles with their own verbs and resources are not supported.

A ServiceAccount for automation is shc auth create-service-client ci, a confidential client that logs in with shc auth login --client-credentials. Its tokens are platform root: a narrower automation identity is not supported. SHC mounts no API token into a container, so a pod that calls the Kubernetes API has no equivalent; a service that drives containers asks for the Docker socket, which is a per-deployment broker (The Docker socket). See Users and SSO.

securityContext, privileged and capabilities

Section titled “securityContext, privileged and capabilities”
KubernetesCompose key
runAsUser, runAsGroupuser: "1000:1000"
readOnlyRootFilesystem: trueread_only: true
allowPrivilegeEscalation: falsesecurity_opt: ["no-new-privileges"]
capabilities.dropcap_drop
capabilities.add, a capability in the runtime’s default setcap_add
capabilities.add outside that set, such as NET_ADMINcap_add, with the caps grant
privileged: trueprivileged: true, with the privileged grant
an unconfined seccomp or AppArmor profilesecurity_opt, with the confinement grant
fsGroup, a volume’s ownerThe mount’s own fields: data:/data:rw:0750:1000:1000 sets mode and owner
hostNetwork, hostPID, hostIPCnetwork_mode: host, pid: host, ipc: host, with the host-namespaces grant
device pluginsdevices:, with the devices grant, or gpus: with the gpus grant. deploy.resources.*.devices is refused.
sysctlssysctls. A namespaced one (net.*, kernel.shm*, kernel.msg*, kernel.sem, fs.mqueue.*) needs nothing; any other needs the kernel grant.

An app only asks; the master tenant’s operator decides. Without a grant the install or update is refused before any pull, naming the class and the command that grants it:

Terminal window
$ shc update scores
shc: [X403990HSTGNT] deployment prod/prod/scores asks for cap_add NET_ADMIN in service netcheck, a host-reaching feature of class caps; the master tenant's operator grants it with `shc config set privilege.deployment_grants.prod.prod.scores caps` at global scope
Terminal window
shc config set privilege.deployment_grants.prod.prod.scores caps

The grant names the classes one deployment may use (<tenant>.<environment>.<deployment>), as a comma list such as socket,devices, or true for every class: socket, devices, gpus, privileged, caps, confinement, host-namespaces and kernel. privilege.grants.<tenant> grants every deployment of a tenant the same way. Both are set at global scope; a tenant cannot grant itself, and the master tenant needs none. A catalogue app’s app.yaml declares what it needs, per service and value, with a reason, and that declaration admits nothing by itself. Pod Security Admission levels are not supported; a tenant’s own app is held to a closed set of compose keys instead. See A privilege.

Not supported as charts: SHC does not render or install them, and there is no import. Repackage the chart as an SHC app, with helm template as the starting point:

Terminal window
helm template shop ./chart --values values.yaml > rendered.yaml

Then work through rendered.yaml with this page:

  1. Each Deployment, StatefulSet or DaemonSet becomes a service or a group in compose.yaml: its image, command, args, env, ports, probes and resources.
  2. Each Service’s ports become expose:; each Ingress becomes the --expose the operator passes and the app’s x-shc-primary and x-shc-path.
  3. ConfigMaps become configs: or files in the app directory. Secrets become vault references, never values in the app.
  4. PersistentVolumeClaims become named volumes, and backup.yaml says which are kept.
  5. The chart’s values.yaml becomes vars: in app.yaml, with defaults in vars.yaml, set at install with --var. Templates are Jinja, not Go templates: {{ vars.replicas.web }}.
  6. A dependency chart, such as a bundled PostgreSQL, becomes a plug file, postgres.plug.yaml, connected to SHC’s own Postgres at install: shc install ./shop -s shop -i postgres=pg (Plugs and sockets).
  7. Helm hooks become lifecycle hooks in app.yaml that name jobs: pre-install is pre_install, post-upgrade is post_update, pre-delete is pre_uninstall, pre-rollback is pre_rollback. helm test is not supported.
  8. shc validate ./shop reads the directory as an install would, then shc install.
HelmSHC
helm installshc install ./shop -s shop
helm upgradeshc update shop
helm upgrade --install from a file, helmfileshc deploy -f shop.shc.yaml -e prod
helm rollbackshc update shop --rollback goes back to the newest kept spec that finished its rollout and differs from the current one, so a failed attempt is skipped, and --rollback=<digest> to any kept spec. It puts the spec back, not data: shc backup restore does that
helm uninstallshc uninstall shop, which takes a safety backup first

Data in the old cluster’s volumes comes across through the app’s own export and import, such as pg_dump and pg_restore. SHC does not read a PersistentVolume.

Not supported, by design. SHC has no custom resources and no controllers of yours that reconcile them. What operators usually do has a fixed place in SHC:

Operator jobIn SHC
Run a replicated database and follow its primaryA group, live labels and a service selector (Headless Service), and SHC’s Postgres app
Create a database and user for an appA plug to a socket: the provider makes them at install (Plugs and sockets)
Run setup and migrations in orderStart jobs and lifecycle hooks
Back up and restorebackup.yaml, shc backup create, backup schedules
Certificates (cert-manager)The tenant CA and ACME, built in
DNS records (external-dns)DNS connections; --expose writes the records
An ingress controllerThe system Traefik
Secrets from an outside storeThe vault, with providers
Periodic maintenancecrons: and shc schedule

Logic that needs its own control loop belongs in the app, as a service of the deployment.

kubectlshc
kubectl get podsshc status k8sdemo: replicas, nodes and state
kubectl get deploymentsshc ls
kubectl get nodesshc node ls
kubectl describe deployment webshc status k8sdemo; shc inspect k8sdemo prints the rendered files
kubectl apply -fshc install, shc update, or shc deploy -f app.shc.yaml -e prod
kubectl deleteshc uninstall k8sdemo
kubectl logs -f deploy/webshc logs web -s k8sdemo -f
kubectl exec -it deploy/web -- shshc shell k8sdemo -S web
kubectl exec deploy/web -- ls /shc exec -s k8sdemo -S web -- ls /; -S web-r1 picks replica 1
kubectl scale deploy/web --replicas=3shc update k8sdemo --scale web=3
kubectl rollout statusshc update waits until every replica is ready; --no-wait returns at once
kubectl rollout restart deploy/webshc restart k8sdemo -S web
kubectl rollout undoshc update k8sdemo --rollback, or failure_action: rollback to do it on failure
kubectl port-forward svc/web 8080:80shc forward k8sdemo web:80=8080
kubectl get eventsshc events
kubectl top podsshc status --resources
kubectl cordon, drain, uncordonshc node cordon, shc node drain, shc node uncordon
kubectl label node n1 tier=goldshc node label n1 tier=gold
kubectl config set-context --namespaceshc ctx -t acme -e staging
kubectl create secret genericshc vault set
kubectl create job --from=cronjob/reportshc job run report -s k8sdemo --wait

This page writes the SHC side as compose.yaml, which carries every feature on this page. shc.yaml is SHC’s stricter app file, where every key is honoured as written and there are no x-shc-* keys; shc convert ./shop prints it from a compose.yaml. It has no key for deploy.mode: global or deploy.update_config, so an app that needs a DaemonSet or a rolling update strategy stays in compose.yaml.