khook

Declarative bootstrap for Kubernetes.

A single static binary that runs a DAG of helm, apply, wait, and related steps against a freshly created cluster. The Kubernetes and Helm SDKs are compiled in; it never calls kubectl, helm, or a shell.

Docs · Quickstart · DSL · CLI · vs Terraform

---

Why

Terraform, eksctl, or CAPI creates the cluster; Argo CD or Flux manages it once installed. The steps in between (CNI, CRDs, secrets tooling, the GitOps controller, readiness waits) usually live in a shell script. khook replaces that script with a spec:

apiVersion: khook.io/v1
kind: Khook
metadata:
  name: bootstrap
steps:
  - name: cilium
    helm:
      chart: cilium
      repo: https://helm.cilium.io/
      version: 1.18.4
      namespace: kube-system
      atomic: true
  - name: all-ready
    needs: [cilium]
    wait:
      for: condition=Ready
      on: pods
      allNamespaces: true

$ khook apply -f bootstrap.yaml
✓ cilium (helm)  21.457s
✓ all-ready (wait)  4.203s

• No runtime dependencies. Nothing to install on the runner besides khook.
• DAG execution. Steps declare needs: and run in parallel levels. Cycles fail validation before the cluster is touched.
• Idempotent. Helm release history decides install vs upgrade, applies converge existing objects, deletes treat "not found" as success. Safe to run on every terraform apply.
• Explicit failures. Per-step timeouts and retries, onError: fail | continue, a summary of what succeeded, failed, or was skipped, and separate exit codes for validation and execution errors.
• Not a GitOps engine. khook installs the GitOps controller and stops.

Step types: helm, apply, delete, patch, wait, rollout, job. Specs take ${VAR} substitution, sprig pipelines, and when: (CEL) conditions. Field reference: DSL spec.

Quickstart

make build
k3d cluster create dev
bin/khook apply -f examples/simple.yaml \
  --set NAMESPACE_NAME_TO_CREATE=demo \
  --set NAMESPACE_NAME_FOR_INGRESS=ingress

A TTY gets live per-step status lines; CI gets plain logs and a summary table, or JSON with --output json. Re-running converges without changes.

Walkthrough: Getting started.

Docs

• Getting started: install, first spec, variables
• DSL specification: step types, variables, pipelines, conditions
• CLI reference: commands, flags, variable precedence, exit codes
• vs Terraform: why not the kubernetes/helm providers
• Examples: real-case.yaml (EKS bootstrap), localenv.yaml (k3d/kind)

Status

Pre-release. The v1 core is implemented and covered by unit and k3d end-to-end tests: the seven step types, DAG engine, variables, resumable runs (state:), teardown (destroy), and the CLI. Planned work, including a Terraform/Lambda integration, is in the roadmap.

Development

go test ./...   # unit tests (engine, spec, executors against fakes)
./tests/e2e.sh  # end-to-end against a throwaway k3d cluster

Repo conventions and reading order: AGENTS.md.

License

MIT