Reference

Annotations

Every annotation the Kuberik controllers and the dashboard read or write, grouped by the resource it goes on.

On this page
  1. Rollout
  2. Kustomization
  3. OCIRepository
  4. HealthCheck
    1. Any class
    2. Class kustomization
    3. Classes datadog and datadog-incidents
    4. Class datadog-monitor-crd
    5. Class prometheus-alert
  5. DatadogMonitor
  6. RolloutGate
  7. RolloutSchedule and ClusterRolloutSchedule
  8. ApprovalPolicy and ClusterApprovalPolicy
  9. RolloutApproval
  10. Environment
  11. ReleaseSlice
  12. OpenKruise Rollout
  13. RolloutTest
  14. OCI artifact
  15. Example

Rollout

The rollout-controller reads these from a Kuberik Rollout in the Rollout’s namespace unless the row names another reader.

AnnotationValuesDefaultSet byEffect
rollout.kuberik.com/force-deployRelease tagNoneYou, dashboardDeploys that tag now, past the gates, the unhealthy health-check hold and the failed-bake hold; the tag must be in the ReleaseSource catalogue, spec.wantedVersion wins, and the controller removes it after the tag deploys. An older tag stays only until its bake succeeds, then the newest release the gates allow deploys again: roll back with spec.wantedVersion (Deploy a specific version).
rollout.kuberik.com/deploy-messageFree textManual deployment for spec.wantedVersion, Manual deployment, with force deploy for force-deployYou, dashboardMessage of the history entry for a deploy by hand (force-deploy or spec.wantedVersion), removed after the next deploy (Deploy a specific version).
rollout.kuberik.com/deploy-userUser nameKind System, name rollout-controllerYou, dashboardRecorded as triggeredBy with kind User for a deploy by hand, removed after the next deploy; the dashboard writes the signed-in user unless it is a service account (Deploy a specific version).
rollout.kuberik.com/bypass-gatesRelease tagNoneYou, dashboardLets that build past every gate once if it is a release newer than the deployed one; health checks and a failed bake still hold it, and the controller removes it after the next deploy (Let one build past the gates).
rollout.kuberik.com/bypass-gates-onlyComma-separated RolloutGate namesEvery gateYou, dashboardNarrows bypass-gates to the named gates and is removed with it when that build deploys; unknown names raise a BypassGatesUnknown warning event (Let one build past the gates).
rollout.kuberik.com/unblock-failed"true"NoneYouLets the next automatic deploy through after a failed bake while gates and the unhealthy hold still apply, removed after that deploy (Resume after a failed bake).
rollout.kuberik.com/retryAny, ignoredNoneYou, dashboardWhen the latest bake is Failed, resets it to Deploying, records lastRetryTimestamp and is removed at once (Retry a failed bake).
rollouttest.kuberik.com/retry-moderetry, skipretryYou, dashboardRead by the openkruise-controller with retry: retry runs failed RolloutTests again, skip marks them Skipped, and the controller removes it after acting (Retry or skip a failed test).
dashboard.rollout.kuberik.com/themedevelopment, staging, test, production or a hex colourFrom the Environment tierYouRead by the dashboard: the preset or colour of the Rollout’s environment chip.
dashboard.rollout.kuberik.com/theme-colorHex colour (#7c3aed)The theme’s colourYouRead by the dashboard: overrides the chip colour.
dashboard.rollout.kuberik.com/theme-labelTextThe preset’s name when theme is a preset, else the environment name (Custom when there is none)YouRead by the dashboard: the tooltip on the environment chip (in the breadcrumb, in the rollout header before the first deploy, and in the rollout header for a Rollout with no Environment) and, when the Rollout also sets theme or theme-color, the environment’s title in search; search also finds the Rollout by it. The chip itself shows the Environment’s name, lower-cased, with development, production and testing shortened to dev, prod and test; only on a Rollout with no Environment that sets theme or theme-color does the chip show this text instead, shortened the same way.

Kustomization

The rollout-controller and the openkruise-controller read this from a Flux Kustomization in the Rollout’s namespace.

AnnotationValuesDefaultSet byEffect
rollout.kuberik.com/substitute.<VAR>.fromRollout nameNoneYouOn each deploy the rollout-controller writes the release tag to spec.postBuild.substitute.<VAR>; the openkruise-controller uses it to find the Rollout behind a canary (Set a Kustomization substitute).

OCIRepository

These go on a Flux OCIRepository.

AnnotationValuesDefaultSet byEffect
rollout.kuberik.com/rolloutRollout nameNoneYouOn each deploy the rollout-controller writes the release tag to spec.ref.tag of an OCIRepository in the Rollout’s namespace (Set an OCIRepository tag).
rollout.kuberik.com/nameRollout nameNoneYouRead only by the openkruise-controller to find the Rollout behind a canary; the rollout-controller does not patch the OCIRepository for it.
rollout.kuberik.com/namespaceNamespaceThe OCIRepository’s namespaceYouNamespace of the Rollout named by rollout.kuberik.com/name.

HealthCheck

Each class is served by its own controller, which reads only the annotations in its table.

Any class

AnnotationValuesDefaultSet byEffect
kuberik.com/display-nameTextmetadata.nameYouRead by the dashboard: the name it shows for the check.

Class kustomization

AnnotationValuesDefaultSet byEffect
healthcheck.kuberik.com/kustomization<name> or <namespace>/<name>None, requiredYouThe rollout-controller reports the health of this Kustomization; a bare name is looked up in the HealthCheck’s namespace (Choose how a Kustomization is checked).
healthcheck.kuberik.com/requeue-intervalGo duration (30s, 2m)30sYouHow often the check is evaluated again; values under 5s count as 5s and a value that does not parse uses the default (Report Kustomization health).

Classes datadog and datadog-incidents

AnnotationValuesDefaultSet byEffect
healthcheck.kuberik.com/datadog-monitor-idsComma-separated monitor IDsNoneYouClass datadog: the check is unhealthy while any of these monitors alerts; set this, datadog-monitor-tags, or both (Fail a deploy on alerting monitors).
healthcheck.kuberik.com/datadog-monitor-tagsComma-separated tagsNoneYouClass datadog: also selects every monitor that carries all of these tags (Fail a deploy on alerting monitors).
healthcheck.kuberik.com/datadog-group-tagsComma-separated tags (service:api)Every groupYouClass datadog: counts only the groups of each selected monitor that match these tags (Fail a deploy on alerting monitors).
healthcheck.kuberik.com/datadog-incident-queryDatadog incident search queryNone, requiredYouClass datadog-incidents: the check is unhealthy while an open incident matches the query (Hold deploys during an incident).
healthcheck.kuberik.com/requeue-intervalGo duration60sYouHow often Datadog is polled; a value under 10s or one that does not parse uses the default (Fail a deploy on alerting monitors).

Class datadog-monitor-crd

The datadog-controller creates these HealthChecks, named datadog-check-<monitor>, from an annotated DatadogMonitor.

AnnotationValuesDefaultSet byEffect
kuberik.com/datadog-monitor-nameDatadogMonitor nameThe monitor’s namedatadog-controllerFinds the monitor when the HealthCheck has lost its owner reference (Use DatadogMonitor resources).
kuberik.com/datadog-monitor-uidDatadogMonitor UIDThe monitor’s UIDdatadog-controllerRecords which DatadogMonitor the check was created from.

Class prometheus-alert

AnnotationValuesDefaultSet byEffect
healthcheck.kuberik.com/prometheus-urlPrometheus base URLNone, requiredYouThe Prometheus server whose ALERTS series the prometheus-controller queries (Fail a deploy on a firing alert).
healthcheck.kuberik.com/prometheus-alert-labelsComma-separated key=value (alertname=HighErrorRate,app=hello-world)None, requiredYouThe check is unhealthy while an alert with these labels fires (Fail a deploy on a firing alert).
healthcheck.kuberik.com/prometheus-credentials-secret<name> or <namespace>/<name>No credentialsYouSecret with key token (bearer) or username and password (basic auth); a bare name is looked up in the HealthCheck’s namespace (Authenticate to Prometheus).
healthcheck.kuberik.com/requeue-intervalGo duration30sYouHow often Prometheus is queried; values under 5s count as 5s and a value that does not parse uses the default (Fail a deploy on a firing alert).
healthcheck.kuberik.com/observation-limitDecimal (0.05)Inferred from a simple rule expression such as rate(x[5m]) > 0.05YouThe alert’s threshold, shown in status.observations; needs observation-direction (Read the status).
healthcheck.kuberik.com/observation-directionAbove, BelowInferred with the limitYouWhether the value fails above or below the limit; without a valid direction the observation falls back to a count of firing alerts (Read the status).
healthcheck.kuberik.com/observation-unitText (%, ms)NoneYouUnit shown with the observed value (Read the status).
healthcheck.kuberik.com/observation-nameTextThe alertname label, else the rule name, else alertYouName of the observation (Read the status).
healthcheck.kuberik.com/last-scrape-timeRFC 3339 timeOne requeue interval agoprometheus-controllerStart of the next ALERTS range query, written after each query so an alert that fired between polls still counts.

DatadogMonitor

The datadog-controller reads this from a Datadog Operator DatadogMonitor.

AnnotationValuesDefaultSet byEffect
kuberik.com/health-check"true"NoneYouCreates a HealthCheck datadog-check-<monitor> of class datadog-monitor-crd that mirrors the monitor, with the monitor’s labels and its other annotations copied (Use DatadogMonitor resources).

RolloutGate

The dashboard reads these to name a gate and say what releases it.

AnnotationValuesDefaultSet byEffect
gate.kuberik.com/pretty-nameTextThe gate’s nameYou, rollout-controller, environment-controllerThe gate’s name in the dashboard; the controllers write it on the gates they create for schedules, dependencies, approval policies and Environments (Allow deploys during business hours).
gate.kuberik.com/descriptionTextNoneYou, rollout-controller, environment-controllerThe explanation the dashboard shows under the gate on the rollout page (Allow deploys during business hours).

RolloutSchedule and ClusterRolloutSchedule

The rollout-controller copies these to every gate it creates for the schedule.

AnnotationValuesDefaultSet byEffect
gate.kuberik.com/pretty-nameTextThe gate’s nameYouBecomes the gate’s gate.kuberik.com/pretty-name (Allow deploys during business hours).
gate.kuberik.com/descriptionTextNoneYouBecomes the gate’s gate.kuberik.com/description (Allow deploys during business hours).

ApprovalPolicy and ClusterApprovalPolicy

The rollout-controller keeps these in sync on every approval gate the policy owns, and removes them from the gate when you remove them from the policy.

AnnotationValuesDefaultSet byEffect
gate.kuberik.com/pretty-nameTextThe gate’s name (approval-gate-…)YouBecomes the approval gate’s gate.kuberik.com/pretty-name (Require an approval).
gate.kuberik.com/descriptionTextNoneYouBecomes the approval gate’s gate.kuberik.com/description (Require an approval).

RolloutApproval

AnnotationValuesDefaultSet byEffect
approval.kuberik.com/byYour Kubernetes user nameNoneYou, dashboardWho approved; the admission policy kuberik-rolloutapproval-by rejects any name but the requester’s and any change after create, and the rollout-controller copies it to status.history[].approval.by on deploy (Approve a build).

Environment

The environment-controller reads these from an Environment.

AnnotationValuesDefaultSet byEffect
environments.kuberik.com/take-over-site"true"NoneYouOn an Environment in a DuplicateSite conflict, marks the other owners of the site deregistered in GitHub and takes the site; it is not removed (Troubleshoot promotion).
environments.kuberik.com/skip-deregister"true"NoneYouOn delete, removes the environments.kuberik.com/deregister finalizer without calling GitHub, for a dead cluster or a revoked token (When a site leaves).

ReleaseSlice

The release-controller writes this on every slice of a ReleaseSource catalogue.

AnnotationValuesDefaultSet byEffect
kuberik.com/source-identityspec.oci.image or the imagePolicyRef nameSet on every slicerelease-controllerWhen the ReleaseSource’s identity no longer matches, the controller lists the new source and rebuilds the catalogue from it, keeping the old one if the new source cannot be listed.

OpenKruise Rollout

The openkruise-controller reads and writes these on an OpenKruise Rollout (rollouts.kruise.io); <N> is the canary step number, from 1.

AnnotationValuesDefaultSet byEffect
rollout.kuberik.io/step-<N>-ready-timeoutGo duration (10m)No limitYouIf step N is not ready (paused, tests passed) within this time, the Rollout gets Stalled with reason StepReadyTimeoutExceeded and waits for you (Define the canary steps).
rollout.kuberik.io/step-<N>-bake-timeGo duration (5m)0, continue at onceYouHow long step N stays ready before the controller resumes the canary; a step without RolloutTests only continues on its own when this is set (Define the canary steps).
internal.rollout.kuberik.io/step-<N>-started-atRFC 3339 timeSet on entering the stepopenkruise-controllerStart of the step’s ready timeout; a retry on the Kuberik Rollout moves it to the retry time.
internal.rollout.kuberik.io/step-<N>-ready-atRFC 3339 timeSet when the step is readyopenkruise-controllerStart of the step’s bake time.
internal.rollout.kuberik.io/step-<N>-last-revisionCanary revisionSet per stepopenkruise-controllerThe canary revision the step was last evaluated for.
internal.rollout.kuberik.io/last-step-indexStep numberSet per stepopenkruise-controllerDetects a step change so the next step’s times start fresh.

RolloutTest

AnnotationValuesDefaultSet byEffect
kuberik.com/display-nameTextmetadata.nameYouRead by the dashboard: the test’s name in the retry dialog.
rollout.kuberik.com/link.<label>URLNoneYouRead by the dashboard: a link named <label> on the test’s row in the rollout’s pipeline; a Logs, CI or Trace label (any case) replaces the link of that name the dashboard builds from the test job’s DD_SERVICE and DD_ENV variables.

OCI artifact

The release-controller reads these from each release’s OCI manifest, manifest annotations first and then the config descriptor’s, when it adds the release to a ReleaseSource catalogue; set them in CI when you push.

AnnotationValuesDefaultSet byEffect
org.opencontainers.image.revisionGit commit SHANoneYour CIThe commit the build came from, used by the environment-controller as the GitHub deployment ref, so it must be a commit in the repository (Publishing releases).
org.opencontainers.image.versionSemantic versionNoneYour CIThe release’s version, which a service dependency compares against the consumer’s constraint (Declare the contract on the images).
org.opencontainers.image.createdRFC 3339 timeNoneYour CIThe release’s creation time; other formats are ignored (Publishing releases).
org.opencontainers.image.sourceRepository URLNoneYour CICopied to the Rollout’s status.source (Publishing releases).
org.opencontainers.image.titleTextNoneYour CICopied to the Rollout’s status.title (Publishing releases).
org.opencontainers.image.descriptionTextNoneYour CICopied to the Rollout’s status.description (Publishing releases).
com.kuberik.rollout.requires.<contract>Semver constraint (^1.66.0)NoneYour CIWhat this release requires of <contract>, checked by a RolloutDependency; at most 32 per image, contract name up to 64 bytes, value up to 256 (Declare the contract on the images).

Example

The dashboard annotations stay on the Rollout in Git.

rollout.yamlYAML
apiVersion: kuberik.com/v1alpha1
kind: Rollout
metadata:
  name: hello-world
  namespace: hello-world
  annotations:
    dashboard.rollout.kuberik.com/theme: production
spec:
  releaseSourceRef:
    name: hello-world

The rollout-controller removes force-deploy, deploy-message and deploy-user after the deploy, so set them with kubectl annotate rather than keeping them in Git.

Terminal
kubectl -n hello-world annotate rollout hello-world --overwrite \
  rollout.kuberik.com/force-deploy=1.4.2 \
  rollout.kuberik.com/deploy-message="Ship the checkout timeout fix" \
  rollout.kuberik.com/deploy-user=emma.clarke@acme.com