Reference

API Reference

Every field of the Rollout, Environment, OpenKruise and Release resources, grouped by API.

On this page
  1. Rollout API
    1. ApprovalPolicy
    2. ClusterApprovalPolicy
    3. ClusterRolloutSchedule
    4. HealthCheck
    5. Rollout
    6. RolloutApproval
    7. RolloutDependency
    8. RolloutGate
    9. RolloutSchedule
    10. Definitions
  2. Environment API
    1. Environment
    2. Definitions
  3. OpenKruise Integration API
    1. RolloutTest
    2. Definitions
  4. Release API
    1. ReleaseSlice
    2. ReleaseSource
    3. Definitions

Rollout API

ApprovalPolicy

ApprovalPolicy is the Schema for the approvalpolicies API

FieldDescription
metadata
ObjectMeta
metadata is a standard object metadata
spec
ApprovalPolicySpec
spec defines the desired state of ApprovalPolicy
status
ApprovalPolicyStatus
status defines the observed state of ApprovalPolicy

ClusterApprovalPolicy

ClusterApprovalPolicy is the Schema for the clusterapprovalpolicies API

FieldDescription
metadata
ObjectMeta
metadata is a standard object metadata
spec
ClusterApprovalPolicySpec
spec defines the desired state of ClusterApprovalPolicy
status
ClusterApprovalPolicyStatus
status defines the observed state of ClusterApprovalPolicy

ClusterRolloutSchedule

ClusterRolloutSchedule is the Schema for the clusterrolloutschedules API.

FieldDescription
metadata
ObjectMeta
spec
ClusterRolloutScheduleSpec
status
ClusterRolloutScheduleStatus

HealthCheck

HealthCheck is the Schema for the healthchecks API.

FieldDescription
metadata
ObjectMeta
spec
HealthCheckSpec
status
HealthCheckStatus

Rollout

Rollout is the Schema for the rollouts API.

FieldDescription
metadata
ObjectMeta
spec
RolloutSpec
status
RolloutStatus

RolloutApproval

RolloutApproval is the Schema for the rolloutapprovals API

FieldDescription
metadata
ObjectMeta
metadata is a standard object metadata
spec
RolloutApprovalSpec
spec defines the desired state of RolloutApproval

RolloutDependency

RolloutDependency is the Schema for the rolloutdependencies API

FieldDescription
metadata
ObjectMeta
metadata is a standard object metadata
spec
RolloutDependencySpec
spec defines the desired state of RolloutDependency
status
RolloutDependencyStatus
status defines the observed state of RolloutDependency

RolloutGate

RolloutGate is the Schema for the rolloutgates API.

FieldDescription
metadata
ObjectMeta
spec
RolloutGateSpec
status
RolloutGateStatus

RolloutSchedule

RolloutSchedule is the Schema for the rolloutschedules API.

FieldDescription
metadata
ObjectMeta
spec
RolloutScheduleSpec
status
RolloutScheduleStatus

Definitions

ApprovalPolicySpec

Appears in:

ApprovalPolicySpec defines the desired state of ApprovalPolicy

FieldDescription
rolloutSelector
LabelSelector
RolloutSelector selects the Rollouts this policy applies to. An empty selector matches every Rollout.

ApprovalPolicyStatus

Appears in:

ApprovalPolicyStatus defines the observed state of ApprovalPolicy.

FieldDescription
rollouts
[]string
Rollouts lists the matched Rollouts, sorted.
conditions
[]Condition
conditions represent the current state of the ApprovalPolicy resource. Each condition has a unique type and reflects the status of a specific aspect of the resource.

Standard condition types include: - "Available": the resource is fully functional - "Progressing": the resource is being created or updated - "Degraded": the resource failed to reach or maintain its desired state

The status of each condition is one of True, False, or Unknown.

ApprovalRecord

Appears in:

ApprovalRecord is a copy of the RolloutApproval that allowed a deployment, taken when the history entry was written.

FieldDescription
name
string
Name of the RolloutApproval, in the Rollout's namespace.
by
string
By is the approval.kuberik.com/by annotation at deploy time, if set.

BlockedRelease

Appears in:

BlockedRelease describes a consumer release candidate held back by this dependency, and why.

FieldDescription
tag
string
Tag is the image tag of the blocked release candidate.
requiredVersion
string
RequiredVersion is the version constraint the candidate places on the provider's contract, verbatim from its requires annotation.
reason
string
Reason is a short, machine-readable reason the candidate is blocked.

ClusterApprovalPolicySpec

Appears in:

ClusterApprovalPolicySpec defines the desired state of ClusterApprovalPolicy

FieldDescription
rolloutSelector
LabelSelector
RolloutSelector selects the Rollouts this policy applies to. An empty selector matches every Rollout.
namespaceSelector
LabelSelector
NamespaceSelector restricts the policy to Rollouts in matching namespaces. A nil selector matches every namespace.

ClusterApprovalPolicyStatus

Appears in:

ClusterApprovalPolicyStatus defines the observed state of ClusterApprovalPolicy.

FieldDescription
rollouts
[]string
Rollouts lists the matched Rollouts, sorted, as <namespace>/<name>.
conditions
[]Condition
conditions represent the current state of the ClusterApprovalPolicy resource. Each condition has a unique type and reflects the status of a specific aspect of the resource.

Standard condition types include: - "Available": the resource is fully functional - "Progressing": the resource is being created or updated - "Degraded": the resource failed to reach or maintain its desired state

The status of each condition is one of True, False, or Unknown.

ClusterRolloutScheduleSpec

Appears in:

ClusterRolloutScheduleSpec defines the desired state of ClusterRolloutSchedule.

FieldDescription
rolloutSelector
LabelSelector
RolloutSelector is a label selector to match Rollouts across namespaces.
namespaceSelector
LabelSelector
NamespaceSelector is a label selector to match namespaces. If empty, applies to all namespaces.
rules
[]ScheduleRule
Rules is a list of schedule rules. The schedule is active if ANY rule matches the current time/date.
timezone
string
Timezone is the IANA timezone for the schedule (e.g., "America/New_York"). Defaults to "UTC" if not specified.
action
RolloutScheduleAction
Action defines what to do when the schedule is active. - "Allow": Gate passes when active, blocks when inactive - "Deny": Gate blocks when active, passes when inactive

ClusterRolloutScheduleStatus

Appears in:

ClusterRolloutScheduleStatus defines the observed state of ClusterRolloutSchedule.

FieldDescription
active
bool
Active indicates if the schedule is currently active (any rule matches).
activeRules
[]string
ActiveRules is a list of rule names that are currently active.
nextTransition
Time
NextTransition is the timestamp when the active state will next change.
managedGates
[]string
ManagedGates is a list of RolloutGate names being managed by this schedule. Format: "namespace/name"
matchingRollouts
int
MatchingRollouts is the count of rollouts currently matched by the selectors.
conditions
[]Condition
Conditions represents the current state of the schedule.

DateRange

Appears in:

DateRange represents a date range.

FieldDescription
start
string
Start date in YYYY-MM-DD format
end
string
End date in YYYY-MM-DD format

DayOfWeek

(Alias of string)

Appears in:

DayOfWeek represents a day of the week.

DeploymentHistoryEntry

Appears in:

DeploymentHistoryEntry represents a single entry in the deployment history.

FieldDescription
id
int64
ID is a unique auto-incrementing identifier for this history entry.
version
VersionInfo
Version is the version information that was deployed.
timestamp
Time
Timestamp is the time when the deployment occurred.
message
string
Message provides a descriptive message about this deployment entry This field contains human-readable information about the deployment context. For automatic deployments, it includes information about gate bypass and failed bake unblock. For manual deployments (when wantedVersion is specified), it can contain a custom message provided via the "rollout.kuberik.com/deploy-message" annotation, or defaults to "Manual deployment".
triggeredBy
TriggeredByInfo
TriggeredBy indicates what triggered this deployment. Kind can be "User" for manual deployments triggered by a user, or "System" for automatic deployments. Name contains the name of the user or system that triggered the deployment. For user-triggered deployments, this is extracted from the "rollout.kuberik.com/deploy-user" annotation. For system-triggered deployments, this is typically "rollout-controller".
bakeStatus
string
BakeStatus tracks the bake state for this deployment (e.g., None, InProgress, Succeeded, Failed, Cancelled) The bake process ensures that the deployment is stable and healthy before marking as successful.
bakeStatusMessage
string
BakeStatusMessage provides details about the bake state for this deployment This field contains human-readable information about why the bake status is what it is.
bakeStartTime
Time
BakeStartTime is the time when the bake period started for this deployment This is when the rollout controller began monitoring the deployment for stability.
bakeEndTime
Time
BakeEndTime is the time when the bake period ended for this deployment This is when the bake process completed (either successfully or with failure).
failedHealthChecks
[]FailedHealthCheck
FailedHealthChecks contains all health checks that failed during bake. This field is populated when bake fails due to health check errors.
lastRetryTimestamp
Time
LastRetryTimestamp is the time when a retry was most recently requested for this deployment. When set, downstream controllers (health checks, kruise rollout step gates) use this as a cutoff: stale failure conditions with LastTransitionTime older than LastRetryTimestamp are ignored as they reflect the pre-retry state.
approval
ApprovalRecord
Approval names the RolloutApproval that let this build through an approval gate. Nil when no approval gate applied, or when gates were bypassed.

FailedHealthCheck

Appears in:

FailedHealthCheck represents a health check that failed during bake.

FieldDescription
name
string
Name is the name of the health check.
namespace
string
Namespace is the namespace of the health check.
message
string
Message is the error message from the health check.
observations
[]HealthCheckObservation
Observations is a snapshot of the health check's status.observations taken when the failure was recorded. It is not updated afterwards, so the figure survives the health check recovering.

HealthCheckObservation

Appears in:

HealthCheckObservation is one typed fact a health check evaluated. Numeric fields are decimal strings (e.g. “8.2”, “0.082”) so no precision is lost and the CRD stays float-free.

FieldDescription
name
string
Name of the observed quantity, shown as the label ("error rate", "p99 latency").
kind
HealthCheckObservationKind
Kind picks the drawing: Threshold (value vs limit), Ratio (value of total), Count (value), State (no number; label only).
value
string
Value is the observed number, as a decimal string.
limit
string
Limit is the boundary for a Threshold observation, as a decimal string.
total
string
Total is the denominator for a Ratio observation, as a decimal string.
direction
HealthCheckObservationDirection
Direction, for Threshold: Above is bad when value > limit; Below is bad when value < limit.
unit
string
Unit of the numbers: Percent (a ratio 0..1), Milliseconds, Seconds, Count, or free text.
window
string
Window the observation covers, e.g. "5m".
healthy
bool
Healthy says whether this observation alone is within bounds, so a consumer can mark the offending one when several are listed.
observedTime
Time
ObservedTime is when the provider last evaluated this observation.

HealthCheckObservationDirection

(Alias of string)

Appears in:

HealthCheckObservationDirection says which side of a Threshold limit is bad.

HealthCheckObservationKind

(Alias of string)

Appears in:

HealthCheckObservationKind selects how an observation is drawn.

HealthCheckSelectorConfig

Appears in:

HealthCheckSelectorConfig defines how to select HealthChecks for a rollout.

FieldDescription
selector
LabelSelector
Selector specifies the label selector for matching HealthChecks
namespaceSelector
LabelSelector
NamespaceSelector specifies the namespace selector for matching HealthChecks If not specified, only HealthChecks in the same namespace as the Rollout will be considered

HealthCheckSpec

Appears in:

HealthCheckSpec defines the desired state of HealthCheck.

FieldDescription
class
string
Class specifies the type of health check (e.g., 'kustomization')

HealthCheckStatus

Appears in:

HealthCheckStatus defines the observed state of HealthCheck.

FieldDescription
status
HealthStatus
Status indicates the health state of the check (e.g., 'Healthy', 'Unhealthy', 'Pending')
lastErrorTime
Time
LastErrorTime is the timestamp of the most recent error state
message
string
Message provides additional details about the health status
lastChangeTime
Time
LastChangeTime is the timestamp when the health status last changed
observations
[]HealthCheckObservation
Observations are the facts the check last evaluated, most important first. Consumers (the dashboard) draw the first one as the headline figure; Message stays the human sentence. Providers may leave this empty.

HealthStatus

(Alias of string)

Appears in:

ProviderRolloutReference

Appears in:

ProviderRolloutReference identifies the Rollout that provides a contract.

FieldDescription
name
string
Name is the name of the providing Rollout.
namespace
string
Namespace is the namespace of the providing Rollout. Defaults to the namespace of the RolloutDependency.

ReleaseCandidate

Appears in:

ReleaseCandidate is a release the Rollout could deploy next. It is deliberately lean: full release metadata (digest, revision, version, requires) lives in the ReleaseSlice catalogue and in history entries.

FieldDescription
tag
string
Tag is the release tag.
created
Time
Created is the release creation time.
firstSeen
Time
FirstSeen is when the catalogue first admitted this release.
gated
bool
Gated is true when the release passes every gate.
blockedBy
[]string
BlockedBy lists the gates that do not let this release through.

ReleaseSourceStatusRef

Appears in:

ReleaseSourceStatusRef is a Rollout’s view of its ReleaseSource.

FieldDescription
name
string
Name of the ReleaseSource.
ready
bool
Ready mirrors the ReleaseSource Ready condition.
count
int32
Count is the number of releases in the catalogue.
newest
string
Newest is the tag of the newest release in the catalogue.
observedAt
Time
ObservedAt is when name, ready, count or newest last changed.

RolloutApprovalSpec

Appears in:

RolloutApprovalSpec defines the desired state of RolloutApproval

FieldDescription
rolloutRef
LocalObjectReference
RolloutRef names the Rollout, in this object's namespace, that the approval is for.
version
string
Version is the tag of the release candidate being approved. It is matched against releaseCandidates[].tag. It may name a version that does not exist yet.

RolloutDependencySpec

Appears in:

RolloutDependencySpec defines the desired state of RolloutDependency.

A RolloutDependency gates a consumer Rollout on the deployed contract version of a provider Rollout. Each release candidate of the consumer declares what it requires of the contract via a com.kuberik.rollout.requires.<contract> OCI annotation. A candidate is admitted only once the provider has successfully deployed a release whose own contract version (org.opencontainers.image.version) satisfies that constraint. The result is a topological rollout: providers advance before the consumers that depend on them.

FieldDescription
rolloutRef
LocalObjectReference
RolloutRef references the consumer Rollout that this dependency gates. The Rollout must live in the same namespace as this RolloutDependency.

The name is validated here because corev1.LocalObjectReference defaults it to the empty string, which would otherwise be admitted and then fail every lookup.
providerRef
ProviderRolloutReference
ProviderRef references the Rollout that provides the contract.
contract
string
Contract is the contract name matched against the consumer's com.kuberik.rollout.requires.<contract> annotations. Defaults to the name of the provider Rollout.

RolloutDependencyStatus

Appears in:

RolloutDependencyStatus defines the observed state of RolloutDependency.

FieldDescription
conditions
[]Condition
conditions represent the current state of the RolloutDependency resource.

Condition types: - "Ready": the dependency was evaluated and its gate is in sync - "Satisfied": no release the consumer could deploy next is held back by this dependency
providedVersion
string
ProvidedVersion is the contract version currently deployed by the provider Rollout, taken from the OCI version annotation of its deployed release with the numeric per-build ordinal stripped. A real pre-release identifier ("2.0.0-alpha.1") is preserved, because it means the triple has not shipped.
providedTag
string
ProvidedTag is the image tag of the provider release that ProvidedVersion was read from.
admittedVersions
[]string
AdmittedVersions lists the consumer release candidate tags admitted by this dependency. This is the allow list published to the managed RolloutGate. Named for symmetry with RolloutGate.allowedVersions, which also holds tags. Capped at the newest entries; see maxPublishedReleases.
blockedReleases
[]BlockedRelease
BlockedReleases lists the consumer release candidates held back by this dependency, with the constraint each places on the contract. Capped at the newest entries; see maxPublishedReleases.
gateName
string
GateName is the name of the RolloutGate managed by this dependency.

RolloutGateSpec

Appears in:

RolloutGateSpec defines the desired state of RolloutGate.

FieldDescription
rolloutRef
LocalObjectReference
passing
bool
Passing is true if the RolloutGate is passing.
allowedVersions
[]string
AllowedVersions is a list of versions that Rollout can be updated to.

RolloutGateStatus

Appears in:

RolloutGateStatus defines the observed state of RolloutGate.

RolloutGateStatusSummary

Appears in:

RolloutGateStatusSummary summarizes the status of a gate relevant to this rollout.

FieldDescription
name
string
Name is the name of the gate.
passing
bool
Passing is true if the gate is passing, false if it is blocking.
allowedVersions
[]string
AllowedVersions is a list of versions that are allowed by the gate.
message
string
Message is a message describing the status of the gate.
bypassGates
bool
BypassGates indicates whether this gate was bypassed for the current deployment. With the rollout.kuberik.com/bypass-gates-only annotation, only the listed gates are marked.

RolloutScheduleAction

(Alias of string)

Appears in:

RolloutScheduleAction defines the action to take when the schedule is active.

RolloutScheduleSpec

Appears in:

RolloutScheduleSpec defines the desired state of RolloutSchedule.

FieldDescription
rolloutSelector
LabelSelector
RolloutSelector is a label selector to match Rollouts in the same namespace.
rules
[]ScheduleRule
Rules is a list of schedule rules. The schedule is active if ANY rule matches the current time/date.
timezone
string
Timezone is the IANA timezone for the schedule (e.g., "America/New_York"). Defaults to "UTC" if not specified.
action
RolloutScheduleAction
Action defines what to do when the schedule is active. - "Allow": Gate passes when active, blocks when inactive - "Deny": Gate blocks when active, passes when inactive

RolloutScheduleStatus

Appears in:

RolloutScheduleStatus defines the observed state of RolloutSchedule.

FieldDescription
active
bool
Active indicates if the schedule is currently active (any rule matches).
activeRules
[]string
ActiveRules is a list of rule names that are currently active.
nextTransition
Time
NextTransition is the timestamp when the active state will next change.
managedGates
[]string
ManagedGates is a list of RolloutGate names being managed by this schedule.
matchingRollouts
int
MatchingRollouts is the count of rollouts currently matched by the selector.
conditions
[]Condition
Conditions represents the current state of the schedule.

RolloutSpec

Appears in:

RolloutSpec defines the desired state of Rollout.

FieldDescription
releaseSourceRef
LocalObjectReference
ReleaseSourceRef names a ReleaseSource (kuberik.com, served by release-controller) in the same namespace that provides this Rollout's releases. When set (and the release-controller CRDs are installed) the Rollout reads its releases from the source's ReleaseSlice catalogue. This is the only release path: a Rollout without it gets no releases and reports ReleasesUpdated=False and Ready=False with reason ReleaseSourceRequired.
releasesImagePolicy
LocalObjectReference
Deprecated: ignored; removed in a later version. Releases come from releaseSourceRef; to migrate an existing Flux ImagePolicy, create a ReleaseSource with spec.oci.imagePolicyRef. A Rollout that sets it reports ReleasesImagePolicyIgnored=True. A value type, so Go clients always send "releasesImagePolicy: {}".
wantedVersion
string
WantedVersion specifies a specific version to deploy, overriding the automatic version selection
versionHistoryLimit
int32
VersionHistoryLimit defines the maximum number of entries to keep in the deployment history
availableReleasesRetentionDays
int32
Deprecated: ignored; retention is ReleaseSource.spec.retention. Removed in a later version. AvailableReleasesRetentionDays defines how many days of available releases to keep based on creation timestamp When history is full, releases older than this retention period may be removed. Defaults to 7 days if not specified.
availableReleasesMinCount
int32
Deprecated: ignored; retention is ReleaseSource.spec.retention. Removed in a later version. AvailableReleasesMinCount defines the minimum number of available releases to always keep When history is full, at least this many releases will be retained regardless of other criteria. Defaults to 30 if not specified.
bakeTime
Duration
BakeTime specifies how long to wait after bake starts before marking as successful If no errors happen within the bake time, the rollout is baked successfully. If not specified, no bake time is enforced.
deployTimeout
Duration
DeployTimeout specifies the maximum time to wait for bake to start before marking as failed If bake doesn't start within deployTimeout (i.e., health checks don't become healthy), the rollout should be marked as failed. If not specified, the rollout will wait indefinitely for bake to start.
healthCheckSelector
HealthCheckSelectorConfig
HealthCheckSelector specifies how to select HealthChecks for this rollout

RolloutStatus

Appears in:

RolloutStatus defines the observed state of Rollout.

FieldDescription
conditions
[]Condition
Conditions represents the current state of the rollout process.
history
[]DeploymentHistoryEntry
History tracks the deployment history of this Rollout. Each entry contains the version deployed and the timestamp of the deployment.
availableReleases
[]VersionInfo
Deprecated: ignored; no longer written (cleared on reconcile). Read status.candidates and the ReleaseSlice catalogue instead. Removed in a later version. AvailableReleases is a list of all releases available in the releases repository.
releaseCandidates
[]VersionInfo
Deprecated: ignored; no longer written (cleared on reconcile). Read status.candidates instead. Removed in a later version. ReleaseCandidates is a list of releases that are candidates for the next deployment. These are filtered from AvailableReleases based on deployment history and version ordering.
gatedReleaseCandidates
[]VersionInfo
Deprecated: ignored; no longer written (cleared on reconcile). Read status.candidates (gated field) instead. Removed in a later version. GatedReleaseCandidates is a list of release candidates that have passed through all gates. This shows which versions are actually available for deployment after gate evaluation.
releaseSource
ReleaseSourceStatusRef
ReleaseSource summarises the ReleaseSource this Rollout reads (slices mode only).
candidates
[]ReleaseCandidate
Candidates is the working set in slices mode: the K newest releases newer than the deployed one, plus any release newer than the deployed one that a gate's allowedVersions, the force-deploy or bypass-gates annotation, or spec.wantedVersion names. Newest first.
gates
[]RolloutGateStatusSummary
Gates summarizes the status of each gate relevant to this rollout.
artifactType
string
ArtifactType is the media/artifact type of the image extracted from the manifest. This includes OCI artifact types, container image types, and other media types. This field is set once for the entire rollout based on the latest available release.
source
string
Source is the source information extracted from OCI annotations. This typically contains the repository URL or source code location. This field is set once for the entire rollout based on the latest available release.
title
string
Title is the title of the image extracted from OCI annotations. This field is set once for the entire rollout based on the latest available release.
description
string
Description is the description of the image extracted from OCI annotations. This field is set once for the entire rollout based on the latest available release.

ScheduleRule

Appears in:

ScheduleRule defines a time-based rule. The schedule is active if the current time/date matches this rule.

FieldDescription
name
string
Name is an optional identifier for this rule
timeRange
TimeRange
TimeRange restricts the rule to specific times of day
daysOfWeek
[]DayOfWeek
DaysOfWeek restricts the rule to specific days of the week
dateRange
DateRange
DateRange restricts the rule to specific date range

TimeRange

Appears in:

TimeRange represents a time range within a day.

FieldDescription
start
string
Start time in HH:MM format (24-hour)
end
string
End time in HH:MM format (24-hour)

TriggeredByInfo

Appears in:

TriggeredByInfo indicates what triggered a deployment.

FieldDescription
kind
string
Kind indicates the type of trigger: "User" for manual deployments triggered by a user, or "System" for automatic deployments triggered by the rollout controller.
name
string
Name contains the name of the user or system that triggered the deployment. For user-triggered deployments, this is extracted from the "rollout.kuberik.com/deploy-user" annotation. For system-triggered deployments, this is typically "rollout-controller".

VersionInfo

Appears in:

VersionInfo represents detailed information about a version.

FieldDescription
tag
string
Tag is the image tag (e.g., "v1.2.3", "latest").
digest
string
Digest is the image digest if available from the ImagePolicy.
version
string
Version is the semantic version extracted from OCI annotations if available.
revision
string
Revision is the revision information extracted from OCI annotations if available.
created
Time
Created is the creation timestamp extracted from OCI annotations if available.
requires
map[string]string
Requires maps a contract name to what this release requires of that contract, extracted from com.kuberik.rollout.requires.<contract> OCI annotations. Values are version constraints as defined by github.com/Masterminds/semver, applied verbatim — note that a bare version is an exact match there, not a floor. RolloutDependency uses these to gate this release on the deployed version of the Rollout providing each contract.

Bounded because it is populated from image annotations, which are outside this controller's trust boundary, and is stored on every release and every history entry.
metadataUnresolved
bool
MetadataUnresolved is true when this release's OCI manifest could not be read, so Requires and the version fields say nothing about the image. A RolloutDependency blocks such a release rather than reading the absent annotations as "declares no requirement", which would open the gate whenever the registry is unreachable.

Environment API

Environment

Environment is the Schema for the environments API

FieldDescription
metadata
ObjectMeta
metadata is a standard object metadata
spec
EnvironmentSpec
spec defines the desired state of Environment
status
EnvironmentStatus
status defines the observed state of Environment

Definitions

BackendConfig

Appears in:

BackendConfig contains backend-specific configuration

FieldDescription
type
string
Type specifies the backend to use (e.g., "github")
project
string
Project is the project identifier (backend-specific format, e.g., "owner/repo" for GitHub)
secret
string
Secret is the name of the Kubernetes Secret containing the backend authentication token

EnvironmentInfo

Appears in:

EnvironmentInfo represents information about an environment’s deployment.

FieldDescription
environment
string
Environment is the canonical tier name (dev, test, staging, prod)
environmentUrl
string
EnvironmentURL is the URL of the actual deployed environment (e.g., dashboard URL)
history
[]DeploymentHistoryEntry
History contains deployment history entries for this environment

EnvironmentRelationship

Appears in:

EnvironmentRelationship is the deprecated relationship to another environment.

FieldDescription
environment
string
Environment is the environment name this environment related to.
type
RelationshipType
Type is the relationship type.

EnvironmentSpec

Appears in:

EnvironmentSpec defines the desired state of Environment

FieldDescription
rolloutRef
LocalObjectReference
RolloutRef is a reference to the Rollout that this Environment manages
name
string
Name is the name of the GitHub deployment (the "kuberik" prefix will be automatically added for GitHub backend if not already present)
environment
string
Environment is the tier this Environment belongs to. Tiers have a fixed order, earliest first: dev, test, staging, prod. Each tier accepts the aliases listed below; aliases of one tier are the same environment for wave grouping, upstream lookup and GitHub matching (the GitHub environment name is kept as written here). An Environment is gated on the nearest earlier tier that has registered sites for the same name.
relationship
EnvironmentRelationship
Relationship is DEPRECATED and ignored: environment order is fixed (dev, test, staging, prod). It is still accepted so that existing manifests keep applying; the Environment reports a Deprecated condition. It will be removed in a later release.
backend
BackendConfig
Backend contains backend-specific configuration
site
string
Site identifies where this instance of the environment runs (e.g. a region or cluster name such as "eu-west-1"). Members of the same environment that run in different clusters are told apart by site. When empty, the controller's default site is used (key "site" of the optional kuberik-cluster-info ConfigMap in the controller namespace), and when that is not set either, the site is "default". Only one Environment (across clusters) may own a given deployment name, tier and site; a second one is reported with WaveReady=False, reason DuplicateSite, and posts nothing.
wave
int32
Wave is the rollout wave of this site within its environment ("prod wave 1"). Waves of one environment roll out in order: wave N starts a version only after every site of wave N-1 baked it. Defaults to 1.
lockstep
bool
Lockstep, when true, stops the wave-1 leader from selecting a new version until every wave of this environment has baked the currently selected one. The wave-1 leader's value governs; a disagreeing member surfaces a LockstepMismatch condition.
requeueInterval
string
RequeueInterval specifies how often the controller should reconcile this Environment If not specified, defaults to 1 minute. Must be a valid duration string (e.g., "1m", "30s", "5m").

EnvironmentStatus

Appears in:

EnvironmentStatus defines the observed state of Environment.

FieldDescription
lastStatusChangeTime
Time
LastStatusChangeTime is the last time the status was updated (only updated when status changes)
currentVersion
string
CurrentVersion is the current version being deployed
rolloutGateRef
LocalObjectReference
RolloutGateRef is a reference to the RolloutGate that was created/updated
environmentInfos
[]EnvironmentInfo
EnvironmentInfos tracks deployment information for each environment. Each environment has environment URL and relationships (not per version).
wave
WaveStatus
Wave is set for Environments with a site and describes their wave state.
conditions
[]Condition
conditions represent the current state of the Environment resource. Each condition has a unique type and reflects the status of a specific aspect of the resource.

Standard condition types include: - "Available": the resource is fully functional - "Progressing": the resource is being created or updated - "Degraded": the resource failed to reach or maintain its desired state

The status of each condition is one of True, False, or Unknown.

RelationshipType

(Alias of string)

Appears in:

RelationshipType is the type of the deprecated spec.relationship.

SiteOwner

Appears in:

SiteOwner identifies the Environment object that owns a site.

FieldDescription
cluster
string
namespace
string
name
string

WaveBlocker

Appears in:

WaveBlocker is the machine-readable form of a WaveReady=False condition. The condition message is display text and may change; these fields are the contract.

FieldDescription
reason
string
Reason is the WaveReady reason.
environment
string
Environment is the canonical tier of the member waited on or at fault.
site
string
Site is the member waited on.
waitingOn
string
WaitingOn is what the wave waits for.
outcome
string
Outcome is set when a leader's bake ended badly.
revision
string
Revision is the full revision concerned.
pinnedVersion
string
PinnedVersion is the version the Rollout pins (Pinned).
selectedVersion
string
SelectedVersion is the tag of the wave's pick (Pinned).
owner
SiteOwner
Owner is the existing owner of the site (DuplicateSite).
waves
[]int32
Waves are the waves present (InvalidTopology, wave gap).
missingWaves
[]int32
MissingWaves are the waves absent from the sequence (InvalidTopology, wave gap).
names
[]string
Names are the alias names registered for one tier (InvalidTopology), the offending name (UnknownTier), or, for DuplicateSite, names[0] is the deployment name the existing owner holds the site for.

WaveMemberStatus

Appears in:

WaveMemberStatus is one site of a wave as observed in the backend.

FieldDescription
environment
string
Environment of the member.
site
string
Site of the member.
wave
int32
Wave of the member.
revision
string
Revision of the member's newest deployment.
bakeStatus
string
BakeStatus of the member's newest deployment.
deregistered
bool
Deregistered is true when the member was removed and no longer counts.

WaveRole

(Alias of string)

Appears in:

WaveRole is the role a site plays inside its (environment, wave).

WaveStatus

Appears in:

WaveStatus describes the site/wave view the controller used for the last gate decision.

FieldDescription
site
string
Site is the effective site of this Environment (spec or controller default).
environment
string
Environment is the environment name this site was registered under in GitHub. Deregistration uses it even after spec.environment changed.
name
string
Name is the deployment name as written to GitHub (with the kuberik prefix). Deregistration uses it even after spec.name changed.
wave
int32
Wave is the effective wave of this Environment.
role
WaveRole
Role is Leader or Follower within (environment, wave). It is also the role recorded on the next GitHub deployment this site creates.
leader
string
Leader is the site leading this (environment, wave).
selectedRevision
string
SelectedRevision is the revision the leader of this wave currently selected.
members
[]WaveMemberStatus
Members are the registered sites of this environment and of its upstream environment.
blocker
WaveBlocker
Blocker explains why the site is not Ready; nil when WaveReady is True.

OpenKruise Integration API

RolloutTest

RolloutTest is the Schema for the rollouttests API

FieldDescription
metadata
ObjectMeta
metadata is a standard object metadata
spec
RolloutTestSpec
spec defines the desired state of RolloutTest
status
RolloutTestStatus
status defines the observed state of RolloutTest

Definitions

RolloutTestPhase

(Alias of string)

Appears in:

RolloutTestPhase represents the current phase of a RolloutTest

RolloutTestSpec

Appears in:

RolloutTestSpec defines the desired state of RolloutTest

FieldDescription
rolloutName
string
RolloutName is the name of the Rollout to watch.
stepIndex
int32
StepIndex is the index of the step in the Rollout strategy to execute the test at.
jobTemplate
k8s.io/api/batch/v1.JobSpec
JobTemplate is the template for the Job to run.

RolloutTestStatus

Appears in:

RolloutTestStatus defines the observed state of RolloutTest.

FieldDescription
conditions
[]Condition
Conditions store the status conditions of the RolloutTest.
observedCanaryRevision
string
ObservedCanaryRevision is the canaryRevision from the Rollout that the current job was created for. When the canaryRevision changes, it indicates a new rollout and the old job should be deleted.
phase
RolloutTestPhase
Phase represents the current phase of the RolloutTest
jobName
string
JobName is the name of the Job created for this test
retryCount
int32
RetryCount is the number of times the job has been retried (from job status)
activePods
int32
ActivePods is the number of active pods for the job
succeededPods
int32
SucceededPods is the number of succeeded pods for the job
failedPods
int32
FailedPods is the number of failed pods for the job

Release API

ReleaseSlice

ReleaseSlice holds a bounded chunk of a ReleaseSource catalogue. Like EndpointSlice it has no spec/status. Labelled kuberik.com/release-source, owned (controller=true) by its ReleaseSource, named <source>-<5-digit index>.

FieldDescription
metadata
ObjectMeta
source
string
Source is the owning ReleaseSource name. Immutable.
sealed
bool
Sealed slices take no new releases. Once true stays true. Always serialised (no omitempty) and defaulted to false so the transition rule also sees true -> false from clients that drop zero values.
oldestCreated
Time
newestCreated
Time
releases
[]Release
Releases sorted by sequence ascending.

ReleaseSource

ReleaseSource is the Schema for the releasesources API.

FieldDescription
metadata
ObjectMeta
spec
ReleaseSourceSpec
status
ReleaseSourceStatus

Definitions

AlphabeticalPolicy

Appears in:

AlphabeticalPolicy orders tags alphabetically.

FieldDescription
order
string

ArtifactMetadata

Appears in:

ArtifactMetadata is the artifact-level metadata of the newest release.

FieldDescription
type
string
sourceURL
string
title
string
description
string

NumericalPolicy

Appears in:

NumericalPolicy orders tags numerically.

FieldDescription
order
string

OCISource

Appears in:

OCISource configures an OCI repository source.

FieldDescription
image
string
Image is the repository, e.g. ghcr.io/org/app.
secretRef
LocalObjectReference
SecretRef names a kubernetes.io/dockerconfigjson Secret.
insecure
bool
Insecure allows plain HTTP registries.
filterTags
TagFilter
FilterTags has the Flux ImagePolicy shape.
policy
OrderPolicy
Policy has the Flux ImagePolicy shape. Required with image: release order and admission are defined by it (with imagePolicyRef the ImagePolicy carries it).
imagePolicyRef
LocalObjectReference
ImagePolicyRef reads image, secretRef, filterTags and policy from an existing Flux ImagePolicy and its ImageRepository (spec only); policy and filterTags must not be set with it.

OrderPolicy

Appears in:

OrderPolicy picks how tags are ordered (Flux ImagePolicy shape). At most one member.

FieldDescription
semver
SemVerPolicy
alphabetical
AlphabeticalPolicy
numerical
NumericalPolicy

Release

Appears in:

Release is one catalogue entry. It is a superset of rollout-controller’s VersionInfo (tag, digest, version, revision, created, requires, metadataUnresolved).

CEL cost: Requires and Metadata sit inside a list with maxItems 1000, so their rules are written as a single self.all(k, …) over a bounded map (maxProperties 32 / 8) and string maxLengths are declared on the values' schema so the apiserver can estimate cost.

FieldDescription
tag
string
Tag is the deployable reference. Unique per source.
digest
string
version
string
revision
string
Revision is a git SHA by contract.
sequence
int64
Sequence is the admission order. Readers sort by it (not by created). Sequence order equals policy order: incremental releases get max+1.., backfilled releases get min-1.. going down. Never renumbered.
created
Time
Created is source-provided, else firstSeen (createdObserved=true).
createdObserved
bool
firstSeen
Time
FirstSeen is when this catalogue first admitted the release.
requires
map[string]string
Requires: keys <= 64, values <= 256 (same as VersionInfo.Requires).
metadataUnresolved
bool
url
string
URL of the release page.
metadata
map[string]string
Metadata is source-specific and small; OCI v1 leaves it empty.

ReleaseRef

Appears in:

ReleaseRef identifies the newest release.

FieldDescription
tag
string
created
Time
revision
string

ReleaseSourceSpec

Appears in:

ReleaseSourceSpec is a discriminated union: exactly one source member must be set. v1 has only oci.

FieldDescription
oci
OCISource
OCI lists tags of an OCI repository.
interval
Duration
Interval between syncs. Jittered +-10% by the controller.
suspend
bool
Suspend stops syncing while true.
retention
Retention
Retention controls when whole old slices are dropped.

ReleaseSourceStatus

Appears in:

ReleaseSourceStatus defines the observed state of ReleaseSource.

FieldDescription
observedGeneration
int64
newest
ReleaseRef
Newest is the newest release in the catalogue.
count
int32
Count of releases in the catalogue.
sliceCount
int32
SliceCount is the number of ReleaseSlices of this source. Slice names are not listed (an unbounded catalogue would overflow any list bound); readers select slices by the kuberik.com/release-source label.
openSlice
string
OpenSlice is the name of the slice taking new releases ("" if none).
backfillComplete
bool
BackfillComplete is true once the catalogue reaches back to the retention window (or the registry has no older tags). While false the controller keeps walking older tags in policy-descending order.
nextSliceIndex
int32
artifact
ArtifactMetadata
Artifact metadata of the newest release.
cursor
string
Cursor is source-opaque (e.g. an ETag).
lastSyncTime
Time
conditions
[]Condition
Conditions: Ready, SourceReachable, Syncing.

Retention

Appears in:

Retention mirrors Rollout.availableReleasesRetentionDays / MinCount.

FieldDescription
days
int32
Days after which a release counts as expired. 0 means age never expires anything.
minCount
int32
MinCount is the number of newest releases always kept.

SemVerPolicy

Appears in:

SemVerPolicy orders tags by semantic version within a range.

FieldDescription
range
string

TagFilter

Appears in:

TagFilter filters tags by regular expression (Flux ImagePolicy shape).

FieldDescription
pattern
string
Pattern is a regular expression tags must match.
extract
string
Extract is a capture-group expression applied before ordering.