Concepts

Propagation Modes

A Rollout decides which version runs in an environment, and that version can point at your app’s image tag or at the rendered manifests for that environment. Kuberik supports both, and the difference is one annotation.

On this page
  1. Image tag
  2. Rendered manifests
  3. Run both
  4. Related
Image tagRendered manifests
Kuberik watchesA ReleaseSource over your app imageA ReleaseSource over your manifest artifact
Kuberik writespostBuild.substitute on a Kustomizationspec.ref.tag on an OCIRepository
Annotationrollout.kuberik.com/substitute.<VAR>.fromrollout.kuberik.com/rollout
Flux sourceAny source of the Kustomization: GitRepository, OCIRepository or BucketOCIRepository
A release changesOne variableEverything in the artifact

Gates, health checks, bake time and cross-environment promotion work the same way in both modes.

Image tag

Your manifests live in any Flux source of the Kustomization: a Git repository, an OCI artifact or a bucket. Kuberik selects a version and writes it into the Kustomization’s substitution variables; Flux renders the overlay and applies it.

The Resources card of a production rollout: the objects Flux applied for it, here the hello-world Deployment and its canary Rollout, both readyThe Resources card of a production rollout: the objects Flux applied for it, here the hello-world Deployment and its canary Rollout, both ready
kustomization.yamlYAML
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: hello-world
  namespace: hello-world
  annotations:
    rollout.kuberik.com/substitute.APP_VERSION.from: "hello-world"
spec:
  interval: 10m
  path: ./deploy/production
  prune: true
  sourceRef:
    kind: GitRepository
    name: hello-world
  postBuild:
    substitute:
      ENVIRONMENT: production  # Kuberik adds APP_VERSION

A rollout in this mode changes exactly one thing: the image tag. Config changes reach the cluster through a separate path, whenever the Kustomization next reconciles its source. That keeps each rollout narrow, and it means pinning an older build restores the image, not the configuration that shipped with it.

Reach for this when your deployments are a single service whose changes are almost always “new build of the same code”, and when you want the smallest possible setup.

One Kustomization, several Rollouts

Declare one annotation per substitution variable. A frontend and a backend managed by independent Rollouts can drive the same Kustomization.

Rendered manifests

Your CI renders the manifests for an environment (kustomize build, helm template, cdk8s synth, whatever you already run) and pushes the result as an OCI artifact to a path scoped to that environment. Kuberik owns the tag on the matching OCIRepository.

On a rendered-manifests rollout, View source in the rollout header shows the files of the artifact that is deployed, one tab per file:

The View source dialog of a rendered-manifests rollout in production: Source files for checkout-edge at artifact tag vd09e6f4, one tab per rendered file (deployment.yaml, configmap.yaml), and the Deployment exactly as it was appliedThe View source dialog of a rendered-manifests rollout in production: Source files for checkout-edge at artifact tag vd09e6f4, one tab per rendered file (deployment.yaml, configmap.yaml), and the Deployment exactly as it was applied
ocirepository.yamlYAML
apiVersion: source.toolkit.fluxcd.io/v1
kind: OCIRepository
metadata:
  name: hello-world
  namespace: hello-world
  annotations:
    rollout.kuberik.com/rollout: "hello-world"
spec:
  interval: 60s
  url: oci://ghcr.io/acme/hello-world/production/manifests
kustomization.yamlYAML
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: hello-world
  namespace: hello-world
spec:
  interval: 10m
  prune: true
  sourceRef:
    kind: OCIRepository
    name: hello-world

A release in this mode is a tag bump on one OCIRepository. A promotion is the same tag bump on the next environment’s OCIRepository. Pinning an older build in production moves that one tag back and leaves staging where it is. Because the artifact carries the whole desired state, a config change is a release: it goes through the same gates, health checks and bake time as a code change, and a failed bake holds further deploys the same way.

This does not replace committing rendered manifests to git. You can do both from the same render: people review the commit in a pull request, and the cluster pulls the artifact built from it.

Reach for this when config changes are as risky as code changes, when you want promotion to move the same tag, rendered from one commit, from one environment to the next, or when the cluster should not need source access or build tooling to produce its own desired state.

Same namespace

Kuberik resolves the ReleaseSource, Kustomization, and OCIRepository in the Rollout’s own namespace. Resources in other namespaces are ignored.

Run both

The two modes are not exclusive. A common setup gives one service two Rollouts: one over the manifest artifact, one over the application image.

Two Rollouts drive one service: one moves the manifests tag, one sets the app versionA Rollout over the manifests artifact moves the tag of a Flux OCIRepository. A second Rollout over the application image sets a version substitute on the Flux Kustomization. The OCIRepository feeds the Kustomization, which applies the workload.KuberikRolloutover the manifestsRolloutover the app imageFluxOCIRepositoryfetches manifestsKustomizationapplies themmoves tagsets versionWorkload Two Rollouts drive one service: one moves the manifests tag, one sets the app versionA Rollout over the manifests artifact moves the tag of a Flux OCIRepository. A second Rollout over the application image sets a version substitute on the Flux Kustomization. The OCIRepository feeds the Kustomization, which applies the workload.KuberikRolloutover manifestsRolloutover app imagemoves tagsetsversionFluxOCIRepositoryfetches manifestsKustomizationapplies themWorkload
Two Rollouts on one service: one moves the manifests tag, the other sets the app version.

The manifests Rollout gates changes to the workload’s configuration, and the app Rollout gates new builds of the code. Each has its own schedule, approvals and health checks, so you can deploy code automatically all day and hold configuration changes for a maintenance window.

Related