Coming from Kubernetes
New line, in development. This page describes SHC as it is on the
devbranch, 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):
shc tenant lsshc ctx -t defaultChecked 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.
At a glance
Section titled “At a glance”| Kubernetes | SHC |
|---|---|
| Pod | A service. Services that share a namespace form one pod. |
| Deployment, ReplicaSet | deploy.replicas and --scale |
| StatefulSet | A group, written with {% members %} |
| DaemonSet | deploy.mode: global |
| Rolling update strategy | deploy.update_config |
| PodDisruptionBudget | deploy.disruption, the operator’s config key |
| Service, ClusterIP | expose:, 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, headless | Not supported. A group’s members each have a name. |
| Ingress | --expose <hostname>, x-shc-primary, x-shc-path |
| ConfigMap | Top-level configs: with content:, or a file in the app |
| Secret | The vault: x-shc-vault, or a @secret variable |
| PersistentVolumeClaim, PersistentVolume, StorageClass | A named volume, x-shc-volumes, a volume provider |
| emptyDir | A tmp* volume, or tmpfs |
| hostPath | A data volume of the deployment. A bind that reaches the host needs a grant. |
| Job | A <name>.job.yaml file, shc job run |
| CronJob | crons: in app.yaml, shc schedule |
| Init container | A start job with before: |
| Sidecar | A service with network_mode: service:<name> |
| Requests and limits | deploy.resources, read as a quota |
kubelet --system-reserved, --kube-reserved | shc node update <node> --reserve |
| Liveness, readiness and startup probes | healthcheck, SHC-HTTP, SHC-TCP, x-shc-health |
| nodeSelector, affinity, anti-affinity | --where, --prefer and node labels |
| Taints and tolerations | 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. |
| HorizontalPodAutoscaler | Not supported |
| Namespace | Tenant, environment and deployment |
| RBAC | shc user grant with SHC’s roles |
| NetworkPolicy | A fixed policy. There is nothing to write. |
| securityContext, privileged, capabilities | Compose keys. What reaches the host needs a grant on the deployment. |
| Helm chart | Repackaged as an SHC app |
| Operators and CRDs | Not supported, by design |
The whole app
Section titled “The whole app”A Deployment of two nginx replicas, its Service and Ingress, and Redis on a PersistentVolumeClaim:
apiVersion: apps/v1kind: Deploymentmetadata: name: webspec: 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: v1kind: Servicemetadata: name: webspec: selector: {app: web} ports: - port: 80---apiVersion: networking.k8s.io/v1kind: Ingressmetadata: name: webspec: rules: - host: web.example.com http: paths: - path: / pathType: Prefix backend: service: name: web port: {number: 80}---apiVersion: v1kind: PersistentVolumeClaimmetadata: name: dataspec: accessModes: [ReadWriteOnce] resources: requests: storage: 1Gi---apiVersion: apps/v1kind: Deploymentmetadata: name: cachespec: 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: v1kind: Servicemetadata: name: cachespec: selector: {app: cache} ports: - port: 6379The same app in SHC is a directory of three files:
name: k8sdemoversion: "1.0.0"title: K8s demodescription: A web Deployment, its Service and Ingress, and a cache on a volume, written for SHCcategory: demolicense: id: MITservices: 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: 1include: [data]shc validate ./k8sdemoshc install ./k8sdemo -s k8sdemo --expose web.example.comThe 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
--exposeflag on the deployment, not a file in the app.x-shc-primarynames the service a bare hostname reaches. dataneeds no claim. SHC declares it and binds a directory of the deployment,mounts/data, on the node that runscache, or a block volume where the cluster has a volume provider.backup.yamllists the volume underinclude, 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: 1does the job ofRecreateand more.shc update k8sdemo --scale cache=2is 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.
Workloads
Section titled “Workloads”apiVersion: v1kind: Podmetadata: name: toolsspec: 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.
Deployment and ReplicaSet
Section titled “Deployment and ReplicaSet”apiVersion: apps/v1kind: Deploymentmetadata: name: webspec: replicas: 3 selector: matchLabels: {app: web} template: metadata: labels: {app: web} spec: containers: - name: web image: nginx:1.27-alpineservices: web: image: nginx:1.27-alpine deploy: replicas: 3 x-shc-scale: max: 6shc update k8sdemo --scale web=4deploy.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.
StatefulSet
Section titled “StatefulSet”apiVersion: apps/v1kind: StatefulSetmetadata: name: dbspec: 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: 10Giservices:{% 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 %}shc update db --scale db=5shc update db --scale db=2@home,1@farA 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.
DaemonSet
Section titled “DaemonSet”apiVersion: apps/v1kind: DaemonSetmetadata: name: agentspec: 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: globalA 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.
Rolling update strategy
Section titled “Rolling update strategy”spec: minReadySeconds: 10 strategy: type: RollingUpdate rollingUpdate: maxSurge: 1 maxUnavailable: 0services: web: image: nginx:1.27-alpine deploy: replicas: 3 update_config: parallelism: 1 order: start-first monitor: 10s failure_action: rollback| Kubernetes | deploy.update_config |
|---|---|
maxSurge: 1, maxUnavailable: 0 | order: start-first: the new replica starts before the old one stops |
maxSurge: 0, maxUnavailable: 1 | order: stop-first, the default |
| replicas changed per step | parallelism, default 1. 0 takes every replica in one batch. |
type: Recreate | parallelism: 0 with stop-first comes closest |
minReadySeconds | monitor, default 5s. A replica that reports failure inside it counts as failed. |
| pause between steps | delay |
progressDeadlineSeconds and kubectl rollout undo | failure_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.
PodDisruptionBudget
Section titled “PodDisruptionBudget”apiVersion: policy/v1kind: PodDisruptionBudgetmetadata: name: wikispec: 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.
shc update wiki -c deploy.disruption=neverrolling, 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.
Init containers
Section titled “Init containers”spec: initContainers: - name: migrate image: busybox:1.36 command: ["sh", "-c", "echo migrated"] containers: - name: web image: nginx:1.27-alpinename: migratecontext: containerimage: busybox:1.36after: [cache]before: [web]command: ["sh", "-c", "echo migrated"]timeout: 60A 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.
Sidecars
Section titled “Sidecars”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:webnetwork_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/v1kind: Jobmetadata: name: reportspec: 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: dataname: reportcontext: containerimage: busybox:1.36command: ["sh", "-c", "ls /data"]volumes: - data:/data:rotimeout: 60shc job run report -s k8sdemo --waitA 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.
CronJob
Section titled “CronJob”apiVersion: batch/v1kind: CronJobmetadata: name: reportspec: schedule: "0 3 * * *" jobTemplate: spec: template: spec: restartPolicy: Never containers: - name: report image: busybox:1.36 command: ["sh", "-c", "ls /data"]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.
shc schedule ls -s k8sdemoshc schedule edit report "0 4 * * *" -s k8sdemoshc schedule disable report -s k8sdemoshc schedule enable report -s k8sdemodisable is the suspend: true of a CronJob. shc schedule add <job> <cron> -s <deployment> schedules a job the app did not.
Networking
Section titled “Networking”Service
Section titled “Service”apiVersion: v1kind: Servicemetadata: name: apispec: selector: {app: api} ports: - port: 80 targetPort: 8080services: 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).
NodePort
Section titled “NodePort”apiVersion: v1kind: Servicemetadata: name: webspec: type: NodePort selector: {app: web} ports: - port: 80 nodePort: 30080shc update k8sdemo --expose 30080=web:80shc 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.
LoadBalancer
Section titled “LoadBalancer”apiVersion: v1kind: Servicemetadata: name: webspec: type: LoadBalancer selector: {app: web} ports: - port: 8443 targetPort: 8443shc update shop --expose 8443@hetzner=web:8443shc update db --expose db.example.com:5432=dbA 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.
Headless Service
Section titled “Headless Service”apiVersion: v1kind: Servicemetadata: name: dbspec: clusterIP: None selector: {app: db} ports: - port: 5432Not 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:1services:{% 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.
Ingress
Section titled “Ingress”apiVersion: networking.k8s.io/v1kind: Ingressmetadata: name: shop annotations: cert-manager.io/cluster-issuer: letsencryptspec: 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: trueshc config set acme.providers.letsencrypt.directory https://acme-v02.api.letsencrypt.org/directoryshc config set acme.default letsencryptshc install ./shop -s shop --expose shop.example.com --publicRoutes go through the cluster’s one system Traefik, which listens on 80 and 443.
- Host.
--expose shop.example.comroutes the hostname to the service markedx-shc-primary, the front door, and follows it if the app moves the marker.--expose shop.example.com=web:80pins the route to a service and port instead. Repeat--exposefor more hostnames. - Path. The app declares
x-shc-path: /apiand the route gets/apibeside the front door.x-shc-path-strip: truestrips the prefix before the request reachesapi, 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: Exactis not supported. - TLS. There is no TLS block to write. Every routed hostname gets a certificate from the tenant’s own CA. A
--publicroute gets one from the ACME provider onceacme.*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, asecretName, is not supported: import your CA withshc 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 --privatetakes that back.--gatedputs Keycloak login in front of the app. - Ingress classes and annotations are not supported. An authored
traefik.*label is refusedX400358LBLTRF: routes come from--exposeonly.
shc ingress ls lists every route with its upstream. See A hostname and a certificate.
NetworkPolicy
Section titled “NetworkPolicy”apiVersion: networking.k8s.io/v1kind: NetworkPolicymetadata: name: cachespec: podSelector: matchLabels: {app: cache} ingress: - from: - podSelector: matchLabels: {app: web} ports: - port: 6379SHC 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.
shc cluster fabric explain shop:web k8sdemo:cache --port 6379explain 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.
Config and storage
Section titled “Config and storage”ConfigMap
Section titled “ConfigMap”apiVersion: v1kind: ConfigMapmetadata: name: web-confdata: extra.conf: | server_tokens off;---# in the pod speccontainers: - name: web image: nginx:1.27-alpine volumeMounts: - name: conf mountPath: /etc/nginx/conf.d/extra.conf subPath: extra.confvolumes: - name: conf configMap: name: web-confservices: web: image: nginx:1.27-alpine configs: - source: web_conf target: /etc/nginx/conf.d/extra.confconfigs: 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.
Secret
Section titled “Secret”apiVersion: v1kind: Secretmetadata: name: apistringData: 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_tokensecrets: api_token: x-shc-vault: ref+vault://api_token?autogenAs an environment variable, through a secret variable:
vars: apiToken@secret!: the API tokenapiToken: "ref+vault://api_token?autogen"services: web: image: nginx:1.27-alpine environment: API_TOKEN: "{{ vars.apiToken }}"shc vault set api_token -s k8sdemo --value-file ./api-token.txtshc update k8sdemoSecrets 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: v1kind: PersistentVolumeClaimmetadata: name: pgdataspec: storageClassName: hcloud-volumes accessModes: [ReadWriteOnce] resources: requests: storage: 20Giservices: db: image: postgres:17 volumes: - pgdata:/var/lib/postgresql/data x-shc-scale: max: 1x-shc-volumes: pgdata: size: 20Gi access: rwoshc install ./db -s db --storage hetznerA 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.
| Kubernetes | SHC |
|---|---|
ReadWriteOnce | access: rwo, the default |
ReadOnlyMany | access: rox, where the provider supports it |
ReadWriteMany | Not supported, refused X400328VOLACC. Give the data one writer, or keep shared files in object storage the app reaches through a plug. |
volumeClaimTemplates | data-{{ m.n }} in a group |
| what to keep in a backup | backup.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.
emptyDir
Section titled “emptyDir”volumes: - name: scratch emptyDir: {} - name: fast emptyDir: {medium: Memory}services: web: image: nginx:1.27-alpine volumes: - tmp-cache:/var/cache/scratch tmpfs: - /tmpA 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.
hostPath
Section titled “hostPath”volumes: - name: logs hostPath: {path: /var/log}services: reader: image: busybox:1.36 volumes: - /var/log:/logs:roA 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:
shc volume mount host-var-log -s hostlogs --read-writeIt 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 and health
Section titled “Resources and health”Requests and limits
Section titled “Requests and limits”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: 256MSHC 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.
System-reserved and kube-reserved
Section titled “System-reserved and kube-reserved”shc node update home01 --reserve cpu=1,memory=4Gi,disk=50GiA 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.
Liveness, readiness and startup probes
Section titled “Liveness, readiness and startup probes”startupProbe: httpGet: {path: /healthz, port: 8080} failureThreshold: 30 periodSeconds: 2readinessProbe: httpGet: {path: /healthz, port: 8080} periodSeconds: 10livenessProbe: httpGet: {path: /healthz, port: 8080} periodSeconds: 10 failureThreshold: 3services: 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: 30sOne healthcheck answers all three questions.
| Kubernetes | SHC |
|---|---|
| readiness | The 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. |
| liveness | The 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. |
| startup | start_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, failureThreshold | interval, timeout, retries |
grpc | Not supported. Use a CMD check with a gRPC health client in the image. |
| separate readiness and liveness checks | Not 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.
Scheduling
Section titled “Scheduling”nodeSelector, affinity and anti-affinity
Section titled “nodeSelector, affinity and anti-affinity”spec: nodeSelector: disktype: ssd affinity: podAffinity: requiredDuringSchedulingIgnoredDuringExecution: - labelSelector: matchLabels: {app: db} topologyKey: kubernetes.io/hostnameshc node label n1 disktype=ssdshc 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.
| Kubernetes | SHC |
|---|---|
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 app | Automatic: 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 cluster | shc 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.
Taints and tolerations
Section titled “Taints and tolerations”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.
HorizontalPodAutoscaler
Section titled “HorizontalPodAutoscaler”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.
Tenancy and access
Section titled “Tenancy and access”Namespaces
Section titled “Namespaces”A namespace does two jobs in Kubernetes: it isolates teams and it names one copy of an app. SHC splits them.
| SHC | What it is |
|---|---|
| tenant | The isolation boundary: its own deployments, vault, Keycloak realm, CA and network. One tenant never sees another’s. |
| environment | A copy of the same deployments, such as prod and staging, with its own data and secrets. The first install into one makes it. |
| deployment | One app in one tenant and environment, named with -s. It is the unit of placement, policy, backup and scale. |
shc tenant add acmeshc install ./shop -s shop -t acme -e stagingshc ctx -t acme -e stagingshc 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/v1kind: RoleBindingmetadata: name: alice-view namespace: shopsubjects: - kind: User name: aliceroleRef: kind: ClusterRole name: view apiGroup: rbac.authorization.k8s.ioshc user grant alice tenant:read --tenant prodshc user grant bob tenant:manage --tenant prodshc user grant alice stack:shop --tenant prodshc user revoke alice tenant:read --tenant prodUsers 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”| Kubernetes | Compose key |
|---|---|
runAsUser, runAsGroup | user: "1000:1000" |
readOnlyRootFilesystem: true | read_only: true |
allowPrivilegeEscalation: false | security_opt: ["no-new-privileges"] |
capabilities.drop | cap_drop |
capabilities.add, a capability in the runtime’s default set | cap_add |
capabilities.add outside that set, such as NET_ADMIN | cap_add, with the caps grant |
privileged: true | privileged: true, with the privileged grant |
| an unconfined seccomp or AppArmor profile | security_opt, with the confinement grant |
fsGroup, a volume’s owner | The mount’s own fields: data:/data:rw:0750:1000:1000 sets mode and owner |
hostNetwork, hostPID, hostIPC | network_mode: host, pid: host, ipc: host, with the host-namespaces grant |
| device plugins | devices:, with the devices grant, or gpus: with the gpus grant. deploy.resources.*.devices is refused. |
sysctls | sysctls. 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:
$ shc update scoresshc: [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 scopeshc config set privilege.deployment_grants.prod.prod.scores capsThe 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.
Packaging
Section titled “Packaging”Helm charts
Section titled “Helm charts”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:
helm template shop ./chart --values values.yaml > rendered.yamlThen work through rendered.yaml with this page:
- Each Deployment, StatefulSet or DaemonSet becomes a service or a group in
compose.yaml: its image, command, args, env, ports, probes and resources. - Each Service’s ports become
expose:; each Ingress becomes the--exposethe operator passes and the app’sx-shc-primaryandx-shc-path. - ConfigMaps become
configs:or files in the app directory. Secrets become vault references, never values in the app. - PersistentVolumeClaims become named volumes, and
backup.yamlsays which are kept. - The chart’s
values.yamlbecomesvars:inapp.yaml, with defaults invars.yaml, set at install with--var. Templates are Jinja, not Go templates:{{ vars.replicas.web }}. - 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). - Helm hooks become lifecycle hooks in
app.yamlthat name jobs:pre-installispre_install,post-upgradeispost_update,pre-deleteispre_uninstall,pre-rollbackispre_rollback.helm testis not supported. shc validate ./shopreads the directory as an install would, thenshc install.
| Helm | SHC |
|---|---|
helm install | shc install ./shop -s shop |
helm upgrade | shc update shop |
helm upgrade --install from a file, helmfile | shc deploy -f shop.shc.yaml -e prod |
helm rollback | shc 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 uninstall | shc 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.
Operators and CRDs
Section titled “Operators and CRDs”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 job | In SHC |
|---|---|
| Run a replicated database and follow its primary | A group, live labels and a service selector (Headless Service), and SHC’s Postgres app |
| Create a database and user for an app | A plug to a socket: the provider makes them at install (Plugs and sockets) |
| Run setup and migrations in order | Start jobs and lifecycle hooks |
| Back up and restore | backup.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 controller | The system Traefik |
| Secrets from an outside store | The vault, with providers |
| Periodic maintenance | crons: and shc schedule |
Logic that needs its own control loop belongs in the app, as a service of the deployment.
kubectl equivalents
Section titled “kubectl equivalents”| kubectl | shc |
|---|---|
kubectl get pods | shc status k8sdemo: replicas, nodes and state |
kubectl get deployments | shc ls |
kubectl get nodes | shc node ls |
kubectl describe deployment web | shc status k8sdemo; shc inspect k8sdemo prints the rendered files |
kubectl apply -f | shc install, shc update, or shc deploy -f app.shc.yaml -e prod |
kubectl delete | shc uninstall k8sdemo |
kubectl logs -f deploy/web | shc logs web -s k8sdemo -f |
kubectl exec -it deploy/web -- sh | shc 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=3 | shc update k8sdemo --scale web=3 |
kubectl rollout status | shc update waits until every replica is ready; --no-wait returns at once |
kubectl rollout restart deploy/web | shc restart k8sdemo -S web |
kubectl rollout undo | shc update k8sdemo --rollback, or failure_action: rollback to do it on failure |
kubectl port-forward svc/web 8080:80 | shc forward k8sdemo web:80=8080 |
kubectl get events | shc events |
kubectl top pods | shc status --resources |
kubectl cordon, drain, uncordon | shc node cordon, shc node drain, shc node uncordon |
kubectl label node n1 tier=gold | shc node label n1 tier=gold |
kubectl config set-context --namespace | shc ctx -t acme -e staging |
kubectl create secret generic | shc vault set |
kubectl create job --from=cronjob/report | shc job run report -s k8sdemo --wait |
compose.yaml or shc.yaml
Section titled “compose.yaml or shc.yaml”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.