Installation¶

This guide covers installing kardinal-promoter in a Kubernetes cluster using Helm.

Prerequisites¶

Install kardinal-promoter¶

1. Create the GitHub token secret¶

kardinal-promoter needs a GitHub personal access token to open and monitor pull requests. The token requires the repo scope (contents read/write, pull requests read/write).

kubectl create namespace kardinal-system

kubectl create secret generic github-token \
  --namespace kardinal-system \
  --from-literal=token=<your-github-token>

2. Install with Helm¶

helm install kardinal-promoter oci://ghcr.io/pnz1990/charts/kardinal-promoter \
  --namespace kardinal-system \
  --create-namespace \
  --set github.secretRef.name=github-token

This single command installs:

• The kardinal-promoter controller in the kardinal-system namespace
• The krocodile Graph controller in the kro-system namespace (unless --set krocodile.enabled=false)

Verify both controllers are running:

kubectl get pods -n kardinal-system
# NAME                                              READY   STATUS    RESTARTS   AGE
# kardinal-promoter-controller-6b6c8c8446-jc79g     1/1     Running   0          30s

kubectl get pods -n kro-system
# NAME                              READY   STATUS    RESTARTS   AGE
# graph-controller-7d4b8f9f5-xk2pq  1/1     Running   0          30s

Bring your own krocodile¶

If you already run krocodile independently in your cluster, disable the bundled installation:

helm install kardinal-promoter oci://ghcr.io/pnz1990/charts/kardinal-promoter \
  --namespace kardinal-system \
  --create-namespace \
  --set github.secretRef.name=github-token \
  --set krocodile.enabled=false

Helm values reference¶

kardinal-promoter controller¶

krocodile Graph controller¶

Accessing the UI¶

The kardinal controller serves an embedded web UI at port 8082 (configurable via --ui-listen-address).

In-cluster access (recommended): kubectl port-forward¶

The supported access method for in-cluster deployments without Ingress is kubectl port-forward:

kubectl port-forward svc/kardinal-controller -n kardinal-system 8082:8082

Then open http://localhost:8082/ui/ in your browser.

With TLS (production)¶

If you configure TLS via --tls-cert-file / --tls-key-file (or the Helm values controller.tlsCertFile / controller.tlsKeyFile), the UI is served over HTTPS and no browser warning is shown. See the Security guide for a cert-manager example.

Upgrade¶

helm upgrade kardinal-promoter oci://ghcr.io/pnz1990/charts/kardinal-promoter \
  --namespace kardinal-system \
  --reuse-values

Graceful shutdown¶

The controller handles SIGTERM gracefully: it stops accepting new reconcile requests and allows in-flight reconcile loops up to 30 seconds to complete before exiting. This prevents mid-step interruptions during rolling updates or node evictions — for example, a git-push that was 5 seconds from finishing will complete rather than leaving the PromotionStep in an inconsistent state.

The Helm chart sets terminationGracePeriodSeconds: 60 (double the shutdown timeout) so Kubernetes sends SIGKILL only after the controller has had a full 30 seconds to drain.

To adjust the timeout:

# values.yaml
terminationGracePeriodSeconds: 120  # increase if reconcile loops routinely take >30s

This upgrades both the kardinal-promoter controller and the bundled krocodile controller to the versions pinned in the new chart version.

Uninstall¶

helm uninstall kardinal-promoter -n kardinal-system

# Optional: remove kardinal CRDs (deletes all Pipelines, Bundles, PolicyGates, etc.)
kubectl delete crd \
  pipelines.kardinal.io \
  bundles.kardinal.io \
  promotionsteps.kardinal.io \
  policygates.kardinal.io \
  prstatuses.kardinal.io \
  rollbackpolicies.kardinal.io

# Optional: remove krocodile CRDs (only if you don't use krocodile elsewhere)
kubectl delete crd \
  graphs.experimental.kro.run \
  graphrevisions.experimental.kro.run

# Optional: remove krocodile namespace
kubectl delete namespace kro-system

RBAC requirements¶

The kardinal-promoter controller's ServiceAccount requires:

The krocodile controller's ServiceAccount requires full cluster-level access to manage arbitrary resources as directed by Graph specs. This is inherent to its design as a general-purpose DAG engine — it applies resources of any type that appear in Graph node templates.

Both ClusterRole and ClusterRoleBinding resources are created automatically by the Helm chart.

Next steps¶

• Quickstart — apply your first Pipeline and promote a Bundle
• Concepts — understand Pipelines, Bundles, PolicyGates
• Policy Gates — write CEL expressions for promotion policies
• Troubleshooting — diagnose installation issues with kardinal doctor