Development

Toolchain-free workflow

The repo ships a containerized dev environment so nothing but a container runtime (Podman or Docker) is needed on the host:

hack/dev.sh go build ./...        # any Go command
hack/dev.sh go test ./...         # unit tests
hack/dev.sh make manifests        # regenerate CRDs after editing api/
hack/dev.sh make lint             # golangci-lint

hack/dev.sh builds the kimo-dev image on first use, mounts the repo read-write, and persists Go module/build caches under ~/.cache/kimo-dev. A VS Code devcontainer wrapping the same image lives in .devcontainer/.

Test suites

hack/dev.sh go test ./internal/...      # unit tests (fake client, no cluster)
hack/dev.sh make test                   # unit + envtest integration suite
hack/dev.sh make test-e2e               # e2e against a kind cluster

• Unit tests cover the controllers, integrations, PoW, and the REST API handlers.
• Integration tests (test/integration) run against envtest — a real API server — and exercise the full manager, including cross-controller behavior like pod-readiness-driven phase transitions.
• E2E tests (test/e2e) run the operator in a kind cluster and validate the complete scenario.

Local cluster

hack/kind.sh   # containerized kind cluster for manual testing

Or by hand with kind on Podman:

KIND_EXPERIMENTAL_PROVIDER=podman kind create cluster --name kimo-dev
podman build -t controller:latest .
podman save controller:latest -o /tmp/kimo.tar
KIND_EXPERIMENTAL_PROVIDER=podman kind load image-archive /tmp/kimo.tar --name kimo-dev
kubectl apply -k config/crd
kubectl kustomize config/default \
  | sed 's|image: controller:latest|image: localhost/controller:latest\n        imagePullPolicy: IfNotPresent|' \
  | kubectl apply -f -

Repository layout

api/v1alpha1/          CRD type definitions
cmd/manager/           operator entrypoint (controllers + REST API)
internal/controller/   the five reconcilers
internal/api/          REST API server, handlers, PoW
internal/integrations/ Backend interface + generic/ctfd adapters
config/                kustomize manifests (CRDs, RBAC, samples)
helm/kimo/             Helm chart
hack/                  dev-container and kind helpers
docs/                  this documentation site (MkDocs)

Documentation site

podman run --rm -p 8000:8000 -v "$PWD:/docs:Z" squidfunk/mkdocs-material serve -a 0.0.0.0:8000

The site deploys to GitHub Pages automatically on pushes to main that touch docs/ or mkdocs.yml.

Contributing

Standard flow: branch, change, hack/dev.sh go test ./..., PR. Regenerate manifests (hack/dev.sh make manifests) whenever anything under api/ changes, and keep config/samples/ working — they're what the quickstart runs.