hammerkit

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.

.hammerkit.yaml
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.js

Kubernetes target

FieldRequiredDescription
contextyesThe kube context (cluster + user) the tasks run in.
namespacenoNamespace the jobs and deployments are created in.
kubeconfignoPath to a kubeconfig file. Defaults to $HOME/.kube/config.
httpRoutesnoGateway API routes that expose services, see HTTP routes.
networkPolicynoenforced: the cluster's network plugin enforces NetworkPolicy, which a task or service with a limited network needs.
volumeSizenoThe 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

FieldRequiredDescription
hostnoAddress 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 ci

A 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 default

The --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
FieldRequiredDescription
hostyesHostname the route responds to.
serviceyesName of the service to route to.
gatewayyesName of the parent Gateway.
gatewayNamespacenoNamespace of the parent Gateway, if not the route's own.
servicePortnoPort of the service to route to.
pathnoPath 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.

On this page