Install with Helm
Install Kuberik from its Helm chart: one release installs the rollout-controller, the release-controller, the integration controllers you turn on, and the dashboard.
On this page
Before you start, you need Kubernetes 1.30 or later, Helm 3, and Flux 2.6 or later in the cluster (install Flux): Kuberik picks the version and Flux applies it. The rollout-controller ships ValidatingAdmissionPolicies (admissionregistration.k8s.io/v1), which Kubernetes serves from 1.30.
Install the chart
Add the chart repository and install the release into kuberik-system. Helm creates the namespace, so the chart leaves it alone.
helm repo add kuberik https://kuberik.github.io/kuberik
helm repo update
helm install kuberik kuberik/kuberik \
--namespace kuberik-system --create-namespace \
--set createNamespace=falseThe chart is also published as an OCI artifact, oci://ghcr.io/kuberik/charts/kuberik; use it in place of kuberik/kuberik with the same flags. The release-controller, which serves the ReleaseSource objects your Rollouts read their releases from, is on by default and needs no values.
Turn on integration controllers
Each integration controller is off by default. Turn on the ones you use in your values file:
integrations:
datadog:
enabled: true # Datadog monitors as health checks
openkruise:
enabled: true # canary steps with OpenKruise Rollout
environment:
enabled: true # promotion between environments via GitHubPromotion between environments always goes through GitHub deployments, even when every environment runs in one cluster. Datadog, Roll Out with a Canary and GitHub cover the resources each controller reads. The chart does not install the prometheus-controller; Prometheus shows how to build and deploy it.
Expose the dashboard
The dashboard is off by default. Turn it on with an Ingress or a Gateway API HTTPRoute; set one, not both. Sign-in needs the Gateway API route.
dashboard:
enabled: true
gateway:
enabled: true
parentRef:
name: eg
namespace: envoy-gateway-system
hostname: dashboard.kuberik.example.comFor an Ingress, set dashboard.ingress.enabled, host and className (plus annotations and tls as your controller needs) in place of dashboard.gateway.
Turn on dashboard sign-in
The chart installs oauth2-proxy in auth-system and attaches an Envoy Gateway SecurityPolicy to the dashboard route, so every action runs as the signed-in user, subject to RBAC. Add to the values from the previous section:
dashboard:
gateway:
auth: true # attach the SecurityPolicy
auth:
enabled: true
oidc:
issuerUrl: https://idp.example.com
clientId: kuberik-cluster
existingSecret: kuberik-oidc # keys client-secret and cookie-secret
canonicalHost: dashboard.kuberik.example.com
cookieDomain: .example.com
gateway:
name: eg
namespace: envoy-gateway-systemA Secret keeps the client secret out of the rendered manifest and the cookie secret stable across upgrades; auth.oidc.clientSecret sets it inline instead. The chart’s defaults answer /api/ requests with 401 instead of a sign-in redirect, and serve the dashboard’s static files (^/_app/, favicon, icons, manifest) without sign-in, so a stale session does not break polling or the page bundle. The API itself still needs a signed-in user. Set Up Dashboard Sign-in covers the OIDC client and the kube-apiserver flags.
Connect several clusters
To run Kuberik in multiple clusters, install the chart in every cluster. Each cluster’s controllers deploy its own Rollouts, and clusters coordinate only through GitHub deployments (Sites and waves).
The hub is the dashboard people open. It reads and acts on the other clusters, the spokes, through their /api/, and deploys do not depend on it.
A dashboard finds the dashboards of other clusters on its own, from the environmentUrl of each entry in an Environment’s status.environmentInfos. Name the cluster, and run every dashboard but one as a spoke that serves only /api/ and sends the browser to the hub:
dashboard:
enabled: true
url: https://dashboard.staging.example.com
clusterName: staging
hubUrl: https://dashboard.production.example.com # leave empty on the hubThe environmentUrl comes from the environment integration: on each cluster, the environment-controller publishes the host of the dashboard’s Ingress or HTTPRoute from Expose the dashboard, not dashboard.url. So every cluster needs integrations.environment.enabled and an exposed dashboard.
The chart writes these values to the kuberik-cluster-info ConfigMap. insecureSkipTLSVerify: true skips TLS checks on hub-to-spoke calls; set it only for self-signed development clusters.
Use the production values
The chart ships values-production.yaml: three controller replicas with a PodDisruptionBudget, the restricted Pod Security level on the namespace, a ServiceMonitor, a NetworkPolicy, the dashboard behind an Ingress, and the Datadog and environment integrations. The chart owns the namespace there, so install into default without --create-namespace:
helm pull oci://ghcr.io/kuberik/charts/kuberik --untar
helm install kuberik oci://ghcr.io/kuberik/charts/kuberik \
--namespace default -f kuberik/values-production.yamlEdit dashboard.ingress.host and metrics.serviceMonitor.namespace in the file first.
Upgrade
First, write a ReleaseSource for each Rollout. Rollouts read releases only from a ReleaseSource: until a Rollout’s spec.releaseSourceRef names one, it deploys nothing new and reports No release source. The ReleaseSource kind and the field come with the upgrade, so apply them right after it.
helm repo update kuberik
helm upgrade kuberik kuberik/kuberik --namespace kuberik-system -f values.yaml
kubectl apply -f releasesource.yaml
kubectl patch rollout hello-world -n hello-world --type merge \
-p '{"spec":{"releaseSourceRef":{"name":"hello-world"}}}'After a production install, delete the old kuberik/ directory and pull the chart again (helm pull refuses to untar over it), so kuberik/values-production.yaml matches the new version. Then upgrade from the OCI chart: helm upgrade kuberik oci://ghcr.io/kuberik/charts/kuberik --namespace default -f kuberik/values-production.yaml.
The CRDs are chart resources, so helm upgrade installs new CRDs and updates existing ones. If the CRDs were installed outside this release, hand them to it once, or Helm stops with invalid ownership metadata:
kubectl get crd -o name | grep -E 'kuberik\.com$' | xargs -I{} kubectl label --overwrite {} app.kubernetes.io/managed-by=Helm
kubectl get crd -o name | grep -E 'kuberik\.com$' | xargs -I{} kubectl annotate --overwrite {} meta.helm.sh/release-name=kuberik meta.helm.sh/release-namespace=kuberik-systemUse your own release name and namespace; Helm 3.17 and later can do the same with helm upgrade --take-ownership.
Uninstall
helm uninstall kuberik --namespace kuberik-systemAfter a production install, use --namespace default. The chart owns kuberik-system there, so the uninstall deletes the namespace and every Secret in it, such as github-app-credentials and datadog-credentials.
The CRDs stay, with every Rollout and gate in them (crds.keep). To remove them too:
kubectl delete crd --ignore-not-found \
rollouts.kuberik.com rolloutgates.kuberik.com healthchecks.kuberik.com \
rolloutschedules.kuberik.com clusterrolloutschedules.kuberik.com \
rolloutdependencies.kuberik.com releasesources.kuberik.com releaseslices.kuberik.com \
approvalpolicies.kuberik.com clusterapprovalpolicies.kuberik.com rolloutapprovals.kuberik.com \
rollouttests.rollout.kuberik.com environments.environments.kuberik.comRollout, RolloutGate, HealthCheck, ReleaseSource and Environment in the cluster.Check the result
kubectl -n kuberik-system get deploymentsThe rollout-controller Deployment is ready, plus release-controller, rollout-dashboard if you turned the dashboard on, and one Deployment per integration you turned on.
Troubleshoot
| Symptom | Cause | Fix |
|---|---|---|
namespaces "kuberik-system" already exists | --create-namespace and the chart’s createNamespace: true both create it | Add --set createNamespace=false, or drop --create-namespace |
auth.oidc.issuerUrl is required when auth.enabled is true | Sign-in is on without the OIDC details | Set auth.oidc.issuerUrl, auth.canonicalHost and auth.gateway.name |
dashboard.gateway.auth is true but auth.enabled is false | The route asks for sign-in that is not installed | Set auth.enabled: true with the OIDC values, or dashboard.gateway.auth: false |
| Sign-in redirects in a loop | The redirect URI or cookie domain does not match the host | Register https:/; make auth.cookieDomain a parent of the host |
| Prometheus does not scrape the controller | The ServiceMonitor is in kuberik-system | Set metrics.serviceMonitor.namespace to the Prometheus Operator’s namespace |
| No ServiceMonitor exists | The Prometheus Operator CRDs were not in the cluster when the chart was installed | Run helm upgrade after installing the Prometheus Operator |