Running on Kubernetes
Run your tasks and services on a Kubernetes cluster instead of the local docker daemon by selecting an environment.
Since 1.6.0 hammerkit can execute the same build file either on the local Docker
daemon or on a Kubernetes cluster. This is done through an environment: tasks
run as jobs on the cluster, container services run as deployments, and the result
of each task is cached the same way as locally.
This is different from Kubernetes services, which only forward existing resources from a cluster into a local task. Here your own tasks and services run on the cluster.
Declaring an environment
Environments are declared in a top-level environments: block. Each environment
targets either kubernetes or docker.
environments:
default:
kubernetes:
context: docker-desktop
services:
postgres:
image: postgres:16-alpine
envs:
POSTGRES_USER: postgres
POSTGRES_DB: demo
secrets:
- from: env:DB_PASSWORD
env: POSTGRES_PASSWORD
ports:
- 5432:5432
healthcheck:
cmd: "pg_isready -U postgres"
tasks:
api:
image: node:24-alpine
needs: [postgres]
cmds:
- node index.jsKubernetes target
| Field | Required | Description |
|---|---|---|
context | yes | The kube context (cluster + user) the tasks run in. |
namespace | no | Namespace the jobs and deployments are created in. |
kubeconfig | no | Path to a kubeconfig file. Defaults to $HOME/.kube/config. |
httpRoutes | no | Gateway API routes that expose services, see HTTP routes. |
networkPolicy | no | enforced: the cluster's network plugin enforces NetworkPolicy, which a task or service with a limited network needs. |
volumeSize | no | The size of the claim of a task or service that states no volumeSize of its own, 1Gi when left out. |
The same context, kubeconfig and namespace also supply the cluster connection
for port-forward Kubernetes services: declare the cluster
once here and select it with --env, rather than repeating it on each service.
Docker target
| Field | Required | Description |
|---|---|---|
host | no | Address of a remote Docker daemon to run against. |
Claims
On Kubernetes each container task and service gets one PersistentVolumeClaim
(ReadWriteOnce, the cluster's default storage class). It holds the files of its src,
of the src of its dependencies (as Docker mounts them) and of its mounts, uploaded before
it starts, and what it generates, which the tasks that
depend on it mount from there. It stays until hammerkit clean, so the next run finds the
outputs it already made. On a server, the claim of a task stays for a while after the run,
for the next run of the same source, see
Kept claims.
So a task whose dependencies have a src gets a claim, and an upload before it starts, even
when it has no src, mounts or generates of its own (a check that only reads what
install made and its sources). Each such claim counts against the storage and pod quota of
the namespace and adds the time of an upload pod to the task. Where a dependency's src
covers a large part of the project, a narrower src keeps that small.
Each path has a folder of its own in the claim, named after its last segment. When two
paths of a task end alike, such as node_modules and api/node_modules, the least deep one
keeps that name and the others' folders also carry a hash of their path in the project.
Earlier versions put such paths in one folder, so a task with paths that end alike has a new
id since: the first run after the update runs it again, in a new claim, instead of reusing
the mixed outputs it made before (kept or cached). A service keeps its claim and its id, so
a service with two volumes that end alike should have its claim removed once after the
update (hammerkit clean), since the first of them still holds what both wrote.
A path of generates with an extension, such as lcov.info, is a file, as on Docker: it is
in the claim as an empty file before the task starts, and the task writes into it where it
is. A tool that replaces the file instead of writing into it, by moving another one over it
or by removing it first (BusyBox's cp in an Alpine image does), can't do that with a file
mounted on its own, as on Docker: write into it (cat a > b), or let such a task generate the
folder the file is in instead. hammerkit
tells a file by its extension, so a folder with a dot in its name, such as x.egg-info,
counts as a file too: name the folder it is in. Making the file takes an upload pod before
the task, also when it has no src. Earlier
versions made a folder of such a path, which a kept claim may still hold: it is replaced by
the file before the task runs.
A task's src is mounted read only. A path mounted inside one of its folders, such as a
generates: [pkg/coverage/lcov.info] next to src: [pkg], gets its place in the uploaded
folder before the task starts, since the container runtime can't make it there itself.
A src inside a folder of another src, such as src: [docs, docs/Dockerfile], is in that
folder's upload and mount, as on Docker, and is not mounted on its own. hammerkit tells a
src or mounts path that is there by what it is on disk, so a file without an extension,
such as Dockerfile, counts as a file.
The claim requests 1Gi, or the environment's volumeSize. A task that writes more
(an npm ci, a build of many images) states its own:
tasks:
install:
image: node:24-alpine
src: [package.json, package-lock.json]
generates: [node_modules]
volumeSize: 5Gi
cmds:
- npm ciA cloud disk is the size it requests, so a task that outgrows it fails with
No space left on device; a local cluster's host path storage is not limited. A larger
volumeSize grows a claim an earlier run made, where its storage class allows volume
expansion. Where it does not, the run fails and says so: remove the claim with
hammerkit clean. A smaller one leaves a claim as it is, a claim never shrinks.
Selecting an environment
Pass --env <name> to run against a declared environment. Without it, hammerkit
uses the local Docker daemon.
hammerkit api --env defaultThe --env option is available on the run, store and restore
commands, so cache results can be stored from and restored to a cluster.
Healthchecks
A container service healthcheck is
translated into readiness, liveness and startup probes on the Kubernetes deployment, so
dependent tasks only start once the service is ready. A service without one counts as
ready once its container ran for 10 seconds without a restart (the deployment's
minReadySeconds), so a service that crashes right after it started is not taken as up.
HTTP routes
An HTTP route exposes a service of the environment under a hostname, for example to
reach a deployed application from outside the cluster. Hammerkit creates a Gateway
API HTTPRoute per entry, attached to a
Gateway in the cluster, and removes it again with hammerkit down.
environments:
staging:
kubernetes:
context: staging-cluster
namespace: my-app
httpRoutes:
- host: api.example.com
service: api
servicePort: 3000
path: /
gateway: web # parent Gateway in this namespace
# gatewayNamespace: gateways # set if the Gateway lives elsewhere| Field | Required | Description |
|---|---|---|
host | yes | Hostname the route responds to. |
service | yes | Name of the service to route to. |
gateway | yes | Name of the parent Gateway. |
gatewayNamespace | no | Namespace of the parent Gateway, if not the route's own. |
servicePort | no | Port of the service to route to. |
path | no | Path prefix that is routed to the service. |
This requires the Gateway API CRDs and a
Gateway resource to be installed in the cluster. Hammerkit no longer creates
Ingress resources: the Gateway API is their successor, and an ingresses list in
a build file is rejected with a pointer to httpRoutes.