Concepts

How Kuberik Works

Kuberik is a set of controllers that decide which build of your app runs in each environment and write that choice into Flux. This page names the resources they work with and follows one build from discovery to verification.

On this page
  1. How the resources connect
  2. What each resource does
  3. How a build travels
  4. Related

How the resources connect

Kuberik picks the version, Flux applies itInside Kuberik, a ReleaseSource lists the release tags, RolloutGates allow versions and HealthChecks report health; all three feed the Rollout, which picks the version. The Rollout moves the tag of a Flux OCIRepository or sets a version substitute on a Flux Kustomization. The OCIRepository feeds the Kustomization, which applies your workload.KuberikFluxReleaseSourcelists release tagsRolloutGateallows versionsHealthCheckreports healthRolloutpicks the versionOCIRepositoryfetches the artifactKustomizationapplies manifestsmoves tagsets versionWorkload Kuberik picks the version, Flux applies itInside Kuberik, a ReleaseSource lists the release tags, RolloutGates allow versions and HealthChecks report health; all three feed the Rollout, which picks the version. The Rollout moves the tag of a Flux OCIRepository or sets a version substitute on a Flux Kustomization. The OCIRepository feeds the Kustomization, which applies your workload.KuberikRolloutGateallows versionsHealthCheckreports healthReleaseSourcelists release tagsRolloutpicks the versionmoves tagsets versionFluxOCIRepositoryfetches the artifactKustomizationapplies manifestsWorkload
Kuberik decides which version runs; Flux fetches and applies it.

Every cluster runs its own controllers, which deploy only that cluster’s Rollouts and share bake results with other clusters through GitHub deployments (Sites and waves). One cluster’s dashboard is the hub that shows them all; deploys do not depend on it (Connect several clusters).

What each resource does

ResourcePurpose
RolloutThe core state machine. Reads the releases a ReleaseSource discovers and orchestrates releases. Drives either a Kustomization substitution or an OCIRepository tag.
ReleaseSourceLists the tags of an OCI repository, orders them by a policy and keeps the catalogue of releases (served by the release-controller). A Rollout points at one with spec.releaseSourceRef.
EnvironmentPlaces a Rollout in an environment tier (e.g. “production”), records each deploy as a GitHub deployment, and writes a RolloutGate that admits only the releases the upstream tier baked.
HealthCheckReports health from a Flux Kustomization or from an integration (Datadog monitors, Prometheus alerts). The Rollout reads it before and during the bake.
RolloutGateHolds builds until it allows them: written by hand, or by schedules, approval policies, service dependencies and Environments.
One rollout in the dashboard: the three health checks it watches, all passing, and the resources it manages, 2 of 2 readyOne rollout in the dashboard: the three health checks it watches, all passing, and the resources it manages, 2 of 2 ready

How a build travels

A ReleaseSource finds a new tag in the OCI repository and adds it to its catalogue of releases. Every release newer than the deployed one becomes a candidate for the Rollout; status.candidates shows the newest of them.

RolloutGates decide which candidates may deploy. If any gate does not allow the build, the build waits until a gate changes. Gates never hold deploys you start by hand. On a Rollout’s first deploy they never hold either: it deploys the newest release the gates allow, or the newest release if they allow none.

Kuberik then updates the Flux source it owns, a substitution variable on a Kustomization or the tag on an OCIRepository, and Flux applies the change. See Propagation Modes.

Once every selected health check is healthy, the bake starts: Kuberik waits for bakeTime and watches the HealthChecks for errors. The deploy ends with one bake status:

  • Succeeded The bake ran its full bakeTime with no health-check error. On a recovery deploy (BakeFailureDisabled=True) errors do not count, so the full bakeTime is enough. Downstream environments can now admit the build through their gates.
  • Failed A health check reported an error, or the checks were not healthy within deployTimeout. The build keeps running and further automatic deploys are held until someone acts; see When a bake fails.
  • Cancelled A deploy you started by hand replaced this one before its bake finished.

Related