API Reference

This page includes the full API documentation of the Kuberik project.

Environment API

Resource Types:

BackendConfig

Appears in:

EnvironmentSpec

BackendConfig contains backend-specific configuration

Field	Description
`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

Environment

Environment is the Schema for the environments API

Field	Description
`metadata,omitempty,omitzero` `ObjectMeta`	metadata is a standard object metadataRefer to the Kubernetes API documentation for the fields of the `metadata` field.
`spec` `EnvironmentSpec`	spec defines the desired state of Environment
`status,omitempty,omitzero` `EnvironmentStatus`	status defines the observed state of Environment

EnvironmentInfo

Appears in:

EnvironmentStatus

EnvironmentInfo represents information about an environment’s deployment.

Field	Description
`environment` `string`	Environment is the environment name
`environmentUrl` `string`	EnvironmentURL is the URL of the actual deployed environment (e.g., dashboard URL)
`relationship` `EnvironmentRelationship`	Relationship defines how this environment relates to another environment
`history` `[]DeploymentHistoryEntry`	History contains deployment history entries for this environment

EnvironmentRelationship

Appears in:

EnvironmentInfo
EnvironmentSpec

EnvironmentRelationship defines a relationship to another environment

Field	Description
`environment` `string`	Environment is the environment name this environment relates to
`type` `RelationshipType`	Type is the type of relationship: "After" or "Parallel"

EnvironmentSpec

Appears in:

Environment

EnvironmentSpec defines the desired state of Environment

Field	Description
`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 environment name (e.g., "production", "staging")
`relationship` `EnvironmentRelationship`	Relationship defines how this environment relates to another environment
`backend` `BackendConfig`	Backend contains backend-specific configuration
`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:

Environment

EnvironmentStatus defines the observed state of Environment.

Field	Description
`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).
`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:

EnvironmentRelationship

RelationshipType defines the type of relationship between environments

OpenKruise Integration API

Resource Types:

RolloutTest

RolloutTest is the Schema for the rollouttests API

Field	Description
`metadata,omitempty,omitzero` `ObjectMeta`	metadata is a standard object metadataRefer to the Kubernetes API documentation for the fields of the `metadata` field.
`spec` `RolloutTestSpec`	spec defines the desired state of RolloutTest
`status,omitempty,omitzero` `RolloutTestStatus`	status defines the observed state of RolloutTest

RolloutTestSpec

Appears in:

RolloutTest

RolloutTestSpec defines the desired state of RolloutTest

Field	Description
`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:

RolloutTest

RolloutTestStatus defines the observed state of RolloutTest.

Field	Description
`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

Rollout API

Resource Types:

ClusterRolloutSchedule

ClusterRolloutSchedule is the Schema for the clusterrolloutschedules API.

Field	Description
`metadata` `ObjectMeta`	No description provided. Refer to the Kubernetes API documentation for the fields of the `metadata` field.
`spec` `ClusterRolloutScheduleSpec`	No description provided.
`status` `ClusterRolloutScheduleStatus`	No description provided.

ClusterRolloutScheduleSpec

Appears in:

ClusterRolloutSchedule

ClusterRolloutScheduleSpec defines the desired state of ClusterRolloutSchedule.

Field	Description
`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:

ClusterRolloutSchedule

ClusterRolloutScheduleStatus defines the observed state of ClusterRolloutSchedule.

Field	Description
`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:

ScheduleRule

DateRange represents a date range.

Field	Description
`start` `string`	Start date in YYYY-MM-DD format
`end` `string`	End date in YYYY-MM-DD format

DayOfWeek

(Alias of string)

Appears in:

ScheduleRule

DayOfWeek represents a day of the week.

DeploymentHistoryEntry

Appears in:

RolloutStatus

DeploymentHistoryEntry represents a single entry in the deployment history.

Field	Description
`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/deployment-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.

FailedHealthCheck

Appears in:

DeploymentHistoryEntry

FailedHealthCheck represents a health check that failed during bake.

Field	Description
`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.

HealthCheck

HealthCheck is the Schema for the healthchecks API.

Field	Description
`metadata` `ObjectMeta`	No description provided. Refer to the Kubernetes API documentation for the fields of the `metadata` field.
`spec` `HealthCheckSpec`	No description provided.
`status` `HealthCheckStatus`	No description provided.

HealthCheckSelectorConfig

Appears in:

RolloutSpec

HealthCheckSelectorConfig defines how to select HealthChecks for a rollout.

Field	Description
`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:

HealthCheck

HealthCheckSpec defines the desired state of HealthCheck.

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

HealthCheckStatus

Appears in:

HealthCheck

HealthCheckStatus defines the observed state of HealthCheck.

Field	Description
`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

HealthStatus

(Alias of string)

Appears in:

HealthCheckStatus

Rollout

Rollout is the Schema for the rollouts API.

Field	Description
`metadata` `ObjectMeta`	No description provided. Refer to the Kubernetes API documentation for the fields of the `metadata` field.
`spec` `RolloutSpec`	No description provided.
`status` `RolloutStatus`	No description provided.

RolloutGate

RolloutGate is the Schema for the rolloutgates API.

Field	Description
`metadata` `ObjectMeta`	No description provided. Refer to the Kubernetes API documentation for the fields of the `metadata` field.
`spec` `RolloutGateSpec`	No description provided.
`status` `RolloutGateStatus`	No description provided.

RolloutGateSpec

Appears in:

RolloutGate

RolloutGateSpec defines the desired state of RolloutGate.

Field	Description
`rolloutRef` `LocalObjectReference`	No description provided.
`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:

RolloutGate

RolloutGateStatus defines the observed state of RolloutGate.

RolloutGateStatusSummary

Appears in:

RolloutStatus

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

Field	Description
`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.

RolloutSchedule

RolloutSchedule is the Schema for the rolloutschedules API.

Field	Description
`metadata` `ObjectMeta`	No description provided. Refer to the Kubernetes API documentation for the fields of the `metadata` field.
`spec` `RolloutScheduleSpec`	No description provided.
`status` `RolloutScheduleStatus`	No description provided.

RolloutScheduleAction

(Alias of string)

Appears in:

ClusterRolloutScheduleSpec
RolloutScheduleSpec

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

RolloutScheduleSpec

Appears in:

RolloutSchedule

RolloutScheduleSpec defines the desired state of RolloutSchedule.

Field	Description
`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:

RolloutSchedule

RolloutScheduleStatus defines the observed state of RolloutSchedule.

Field	Description
`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:

Rollout

RolloutSpec defines the desired state of Rollout.

Field	Description
`releasesImagePolicy` `LocalObjectReference`	ReleasesImagePolicy specifies the ImagePolicy that provides available releases
`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`	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`	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:

Rollout

RolloutStatus defines the observed state of Rollout.

Field	Description
`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`	AvailableReleases is a list of all releases available in the releases repository.
`releaseCandidates` `[]VersionInfo`	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`	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.
`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:

ClusterRolloutScheduleSpec
RolloutScheduleSpec

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

Field	Description
`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:

ScheduleRule

TimeRange represents a time range within a day.

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

TriggeredByInfo

Appears in:

DeploymentHistoryEntry

TriggeredByInfo indicates what triggered a deployment.

Field	Description
`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:

DeploymentHistoryEntry
RolloutStatus

VersionInfo represents detailed information about a version.

Field	Description
`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.

Annotations Reference