Skip to content

Installation

Prerequisites

  • A Kubernetes cluster (1.28+). For network isolation to be enforced, the cluster's CNI must support NetworkPolicy (Calico, Cilium, kindnet does not enforce them).
  • kubectl configured against the cluster.
  • Helm 3.

Install with Helm

git clone https://github.com/kimo-ctf/kimo.git
cd kimo
helm install kimo helm/kimo/

This installs:

  • the four CRDs (ChallengeTemplate, ChallengeInstance, ChallengeSet, NetworkFence),
  • the operator Deployment (controllers + REST API on port 8080),
  • RBAC (ServiceAccount, ClusterRole, bindings),
  • a Service exposing the API.

The default install uses the generic scoring backend with no credentials — fine for trying things out, but every API request will be rejected until you configure an API key (see Configuration).

Choosing a scoring backend

The backend is selected at install time:

# values override
integration:
  backend: generic
  config:
    apiKey: "choose-a-strong-key"

Players/platforms authenticate with Authorization: Bearer <apiKey>, and lifecycle events are POSTed to any webhooks you register, signed with HMAC-SHA256.

integration:
  backend: ctfd
  config:
    baseUrl: "https://ctf.example.com"
    webhookUrl: "https://ctf.example.com/plugins/kimo/events"  # optional
    apiKey: "<ctfd admin token>"

Requests are authenticated against CTFd's /api/v1/users/me, and lifecycle events are POSTed to webhookUrl.

helm install kimo helm/kimo/ -f config/samples/values-ctfd-backend.yaml

If the config contains credentials, put them in a Secret and set integration.existingConfigSecret instead of inlining them in values.

Verify the install

kubectl get pods -l app.kubernetes.io/name=kimo
kubectl get crds | grep kimo.io

Then follow the Quickstart.

Running from source (development)

Without Helm, you can run the operator against any kubeconfig:

kubectl apply -k config/crd          # install CRDs
go run ./cmd/manager                 # uses your current kubeconfig

The KIMO_BACKEND and KIMO_BACKEND_CONFIG environment variables select the backend (default generic with empty config).