alepha@docs:~/framework/docs/guides/deployment$
cat 10-kubernetes.md | pretty
4 min read
Last commit:

#Kubernetes

An image built by alepha image runs on Kubernetes with nothing Alepha-specific in the cluster. This page is one Deployment and one Service, and why each field is set the way it is. Every manifest here was applied to a kind cluster (Kubernetes 1.34), with the standard image and with the compiled one.

yaml
  1apiVersion: v1  2kind: ConfigMap  3metadata:  4  name: myapp-config  5data:  6  DATA_DIR: /data  7---  8apiVersion: v1  9kind: Secret 10metadata: 11  name: myapp-secrets 12type: Opaque 13stringData: 14  APP_SECRET: replace-me # openssl rand -hex 32 15--- 16apiVersion: apps/v1 17kind: Deployment 18metadata: 19  name: myapp 20spec: 21  replicas: 2 22  selector: 23    matchLabels: 24      app: myapp 25  strategy: 26    type: RollingUpdate 27    rollingUpdate: 28      maxUnavailable: 0 29      maxSurge: 1 30  template: 31    metadata: 32      labels: 33        app: myapp 34    spec: 35      terminationGracePeriodSeconds: 25 36      securityContext: 37        runAsNonRoot: true 38        seccompProfile: 39          type: RuntimeDefault 40      containers: 41        - name: app 42          image: ghcr.io/myorg/myapp:1.4.0 43          ports: 44            - name: http 45              containerPort: 3000 46          envFrom: 47            - configMapRef: 48                name: myapp-config 49            - secretRef: 50                name: myapp-secrets 51          startupProbe: 52            httpGet: 53              path: /livez 54              port: http 55            periodSeconds: 1 56            failureThreshold: 30 57          livenessProbe: 58            httpGet: 59              path: /livez 60              port: http 61            periodSeconds: 10 62            failureThreshold: 3 63          readinessProbe: 64            httpGet: 65              path: /readyz 66              port: http 67            periodSeconds: 2 68            failureThreshold: 1 69          lifecycle: 70            preStop: 71              sleep: 72                seconds: 10 73          resources: 74            requests: 75              cpu: 100m 76              memory: 128Mi 77            limits: 78              memory: 512Mi 79          securityContext: 80            allowPrivilegeEscalation: false 81            readOnlyRootFilesystem: true 82            capabilities: 83              drop: ["ALL"] 84          volumeMounts: 85            - name: data 86              mountPath: /data 87      volumes: 88        - name: data 89          emptyDir: {} 90--- 91apiVersion: v1 92kind: Service 93metadata: 94  name: myapp 95spec: 96  selector: 97    app: myapp 98  ports: 99    - name: http100      port: 80101      targetPort: http

#Probes

Every Alepha server answers three paths (see Liveness and readiness):

Probe Path Why
startupProbe /livez Nothing answers before the listener is bound. Once it is, /livez answers 200.
livenessProbe /livez 200 whatever the lifecycle: a restart only helps a process that stopped answering at all.
readinessProbe /readyz 503 while the app starts (migrations included) and from the moment it starts to stop.

⚠️ Never point a liveness probe at /health. It answers 503 until the app is ready, so a slow migration gets the pod restarted, which runs the migration again, in a loop.

The startup probe gives the process 30 seconds to bind its port; readiness, not the startup probe, covers a long migration, since /livez answers while it runs and /readyz does not.

#Shutdown

On SIGTERM the app stops within 8 seconds: its stop hooks are bounded, and the listener closes as soon as its own stop hook runs. The framework adds no drain delay of its own. /readyz turns 503 when the stop begins, but by then Kubernetes has already removed the pod from the Service's endpoints, and what is left is the time that removal takes to reach every node.

So the manifest drains before the stop, with a preStop wait: the pod stops receiving new connections while it still serves the ones it has. terminationGracePeriodSeconds is that wait, plus the 8 seconds, plus a margin: 10 + 8 + 7 = 25 above.

Use the sleep lifecycle action, not an exec of sleep: the compiled image has no shell and no sleep binary, so an exec hook fails and is skipped. The sleep action needs Kubernetes 1.30 or later (beta and on by default from 1.30, generally available in 1.34).

Measured on the kind cluster, with a client inside the cluster requesting /health through the Service as fast as it could while kubectl rollout restart replaced both pods:

Image preStop wait Requests Failed
standard 10 seconds 30,129 0
standard none 14,216 7
compiled 10 seconds 13,027 0

#Security context

Both images run as a non-root numeric user (1000 standard, 65532:65532 compiled), which is what runAsNonRoot: true checks. Capabilities are dropped and the root file system is read-only.

One path needs to be writable: the data directory. Unset, the local providers write under /app/node_modules/.alepha, inside the image, which a read-only root refuses. Point DATA_DIR (and a SQLite DATABASE_URL, when there is one) at a mounted volume: an emptyDir above, or a PersistentVolumeClaim for data that must outlive the pod. Nothing else is written: not /tmp, not /app.

#Configuration

Configuration is environment variables, from a ConfigMap and a Secret through envFrom. APP_SECRET goes in the Secret: it signs sessions and tokens, and a production app refuses to start without it. Everything the image bakes with image.env is a default that these override.

#More than one replica

What moves to Redis, and how cron jobs are claimed so that one replica runs each, is the same as anywhere else: see More than one instance. What Kubernetes adds is the database: a SQLite file on a volume means one replica, so several replicas need a shared database (DATABASE_URL=postgres://...).

#Supply chain

alepha image --sbom --provenance --push attaches an SBOM and a SLSA provenance to the image index (see Evidence: SBOM and provenance). Read them back before admitting an image:

bash
docker buildx imagetools inspect ghcr.io/myorg/myapp:1.4.0 --format '{{json .SBOM}}'
docker buildx imagetools inspect ghcr.io/myorg/myapp:1.4.0 --format '{{json .Provenance}}'

Signing is a step of your CI after the push, with cosign or your registry's own signing; alepha image does not sign. An admission policy can then require the signature and the attestations.