#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.
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:
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.