From 2c714ef2f02a91540b147adae000bf94ca23608e Mon Sep 17 00:00:00 2001 From: Per Goncalves da Silva Date: Wed, 19 Nov 2025 11:15:57 +0100 Subject: [PATCH] Update ClusterExtensionRevision API docs Signed-off-by: Per Goncalves da Silva --- api/v1/clusterextensionrevision_types.go | 220 +++++++++++++++--- ...ramework.io_clusterextensionrevisions.yaml | 141 +++++++++-- manifests/experimental-e2e.yaml | 141 +++++++++-- manifests/experimental.yaml | 141 +++++++++-- 4 files changed, 547 insertions(+), 96 deletions(-) diff --git a/api/v1/clusterextensionrevision_types.go b/api/v1/clusterextensionrevision_types.go index e048e1b54..4d88dc40a 100644 --- a/api/v1/clusterextensionrevision_types.go +++ b/api/v1/clusterextensionrevision_types.go @@ -24,42 +24,121 @@ import ( const ( ClusterExtensionRevisionKind = "ClusterExtensionRevision" - // Condition Types + // ClusterExtensionRevisionTypeAvailable is the condition type that represents whether the + // ClusterExtensionRevision is available and has been successfully rolled out. ClusterExtensionRevisionTypeAvailable = "Available" + + // ClusterExtensionRevisionTypeSucceeded is the condition type that represents whether the + // ClusterExtensionRevision rollout has succeeded at least once. ClusterExtensionRevisionTypeSucceeded = "Succeeded" - // Condition Reasons - ClusterExtensionRevisionReasonAvailable = "Available" - ClusterExtensionRevisionReasonReconcileFailure = "ReconcileFailure" + // ClusterExtensionRevisionReasonAvailable is set when the revision is available + // and passes all probes after a successful rollout. + // Condition: Available, Status: True + ClusterExtensionRevisionReasonAvailable = "Available" + + // ClusterExtensionRevisionReasonReconcileFailure is set when the ClusterExtensionRevision + // encounters a general reconciliation failure, such as errors ensuring finalizers or + // establishing watches. + // Condition: Available, Status: False + ClusterExtensionRevisionReasonReconcileFailure = "ReconcileFailure" + + // ClusterExtensionRevisionReasonRevisionValidationFailure is set when the revision + // fails preflight validation checks at the revision level. + // Condition: Available, Status: False ClusterExtensionRevisionReasonRevisionValidationFailure = "RevisionValidationFailure" - ClusterExtensionRevisionReasonPhaseValidationError = "PhaseValidationError" - ClusterExtensionRevisionReasonObjectCollisions = "ObjectCollisions" - ClusterExtensionRevisionReasonRolloutSuccess = "RolloutSuccess" - ClusterExtensionRevisionReasonProbeFailure = "ProbeFailure" - ClusterExtensionRevisionReasonIncomplete = "Incomplete" - ClusterExtensionRevisionReasonProgressing = "Progressing" - ClusterExtensionRevisionReasonArchived = "Archived" - ClusterExtensionRevisionReasonMigrated = "Migrated" + + // ClusterExtensionRevisionReasonPhaseValidationError is set when a phase within + // the revision fails preflight validation checks. + // Condition: Available, Status: False + ClusterExtensionRevisionReasonPhaseValidationError = "PhaseValidationError" + + // ClusterExtensionRevisionReasonObjectCollisions is set when objects in the revision + // collide with existing objects on the cluster that cannot be adopted based on + // the configured collision protection policy. + // Condition: Available, Status: False + ClusterExtensionRevisionReasonObjectCollisions = "ObjectCollisions" + + // ClusterExtensionRevisionReasonRolloutSuccess is set when the revision has + // successfully completed its rollout for the first time. + // Condition: Succeeded, Status: True + ClusterExtensionRevisionReasonRolloutSuccess = "RolloutSuccess" + + // ClusterExtensionRevisionReasonProbeFailure is set when one or more objects + // in the revision fail their readiness probes during rollout. + // Condition: Available, Status: False + ClusterExtensionRevisionReasonProbeFailure = "ProbeFailure" + + // ClusterExtensionRevisionReasonIncomplete is set when the revision rollout + // has not completed but no specific probe failures have been detected. + // Condition: Available, Status: False + ClusterExtensionRevisionReasonIncomplete = "Incomplete" + + // ClusterExtensionRevisionReasonProgressing is set when the revision rollout + // is actively making progress and is in transition. + // Condition: Progressing, Status: True + ClusterExtensionRevisionReasonProgressing = "Progressing" + + // ClusterExtensionRevisionReasonArchived is set when the revision has been + // archived and its objects have been torn down. + // Condition: Available, Status: Unknown + ClusterExtensionRevisionReasonArchived = "Archived" + + // ClusterExtensionRevisionReasonMigrated is set when the revision was + // migrated from an existing Helm release to a ClusterExtensionRevision. + // Condition: Available, Status: Unknown + ClusterExtensionRevisionReasonMigrated = "Migrated" ) // ClusterExtensionRevisionSpec defines the desired state of ClusterExtensionRevision. +// +// A ClusterExtensionRevision represents a specific immutable snapshot of the objects +// to be installed for a ClusterExtension. Each revision is rolled out in phases, +// with objects organized by their Group-Kind into well-known phases such as namespaces, +// rbac, crds, and deploy. type ClusterExtensionRevisionSpec struct { - // Specifies the lifecycle state of the ClusterExtensionRevision. + // The lifecycleState field specifies the lifecycle state of the ClusterExtensionRevision. + // + // When set to "Active" (the default), the revision is actively managed and reconciled. + // When set to "Paused", reconciliation is disabled but status updates continue. + // When set to "Archived", the revision is torn down and scaled to zero. + // The revision is removed from the owner list of all objects previously under management. + // All objects that did not transition to a succeeding revision are deleted. + // + // Once a revision is set to "Archived", it cannot be un-archived. // // +kubebuilder:default="Active" // +kubebuilder:validation:Enum=Active;Paused;Archived // +kubebuilder:validation:XValidation:rule="oldSelf == 'Active' || oldSelf == 'Paused' || oldSelf == 'Archived' && oldSelf == self", message="can not un-archive" LifecycleState ClusterExtensionRevisionLifecycleState `json:"lifecycleState,omitempty"` - // Revision is a sequence number representing a specific revision of the ClusterExtension instance. - // Must be positive. Each ClusterExtensionRevision of the same parent ClusterExtension needs to have - // a unique value assigned. It is immutable after creation. The new revision number must always be previous revision +1. + + // The revision field is a required, immutable sequence number representing a specific revision + // of the parent ClusterExtension. + // + // The revision field must be a positive integer. + // Each ClusterExtensionRevision belonging to the same parent ClusterExtension must have a unique revision number. + // The revision number must always be the previous revision number plus one, or 1 for the first revision. // // +kubebuilder:validation:Required // +kubebuilder:validation:Minimum:=1 // +kubebuilder:validation:XValidation:rule="self == oldSelf", message="revision is immutable" Revision int64 `json:"revision"` - // Phases are groups of objects that will be applied at the same time. - // All objects in the phase will have to pass their probes in order to progress to the next phase. + + // The phases field is an optional, immutable list of phases that group objects to be applied together. + // + // Objects are organized into phases based on their Group-Kind. Common phases include: + // - namespaces: Namespace objects + // - policies: ResourceQuota, LimitRange, NetworkPolicy objects + // - rbac: ServiceAccount, Role, RoleBinding, ClusterRole, ClusterRoleBinding objects + // - crds: CustomResourceDefinition objects + // - storage: PersistentVolume, PersistentVolumeClaim, StorageClass objects + // - deploy: Deployment, StatefulSet, DaemonSet, Service, ConfigMap, Secret objects + // - publish: Ingress, APIService, Route, Webhook objects + // + // All objects in a phase are applied simultaneously. + // The revision progresses to the next phase only after all objects in the current phase pass their readiness probes. + // + // Once set (even if empty), the phases field is immutable. // // +kubebuilder:validation:XValidation:rule="self == oldSelf || oldSelf.size() == 0", message="phases is immutable" // +listType=map @@ -75,33 +154,68 @@ const ( // ClusterExtensionRevisionLifecycleStateActive / "Active" is the default lifecycle state. ClusterExtensionRevisionLifecycleStateActive ClusterExtensionRevisionLifecycleState = "Active" // ClusterExtensionRevisionLifecycleStatePaused / "Paused" disables reconciliation of the ClusterExtensionRevision. - // Only Status updates will still propagated, but object changes will not be reconciled. + // Object changes will not be reconciled. However, status updates will be propagated. ClusterExtensionRevisionLifecycleStatePaused ClusterExtensionRevisionLifecycleState = "Paused" - // ClusterExtensionRevisionLifecycleStateArchived / "Archived" disables reconciliation while also "scaling to zero", - // which deletes all objects that are not excluded via the pausedFor property and - // removes itself from the owner list of all other objects previously under management. + // ClusterExtensionRevisionLifecycleStateArchived / "Archived" archives the revision for historical or auditing purposes. + // The revision is removed from the owner list of all other objects previously under management and all objects + // that did not transition to a succeeding revision are deleted. ClusterExtensionRevisionLifecycleStateArchived ClusterExtensionRevisionLifecycleState = "Archived" ) -// ClusterExtensionRevisionPhase are groups of objects that will be applied at the same time. -// All objects in the a phase will have to pass their probes in order to progress to the next phase. +// ClusterExtensionRevisionPhase represents a group of objects that are applied together. +// +// Objects in a phase are applied simultaneously. +// All objects must pass their readiness probes before the revision progresses to the next phase. +// Phases are applied in a defined order based on the types of objects they contain. type ClusterExtensionRevisionPhase struct { - // Name identifies this phase. + // The name field is a required identifier for this phase. + // + // Phase names must follow the DNS label standard as defined in [RFC 1123]. + // They must contain only lowercase alphanumeric characters or hyphens (-), + // start and end with an alphanumeric character, and be no longer than 63 characters. + // + // Common phase names include: namespaces, policies, rbac, crds, storage, deploy, publish. + // + // [RFC 1123]: https://tools.ietf.org/html/rfc1123 // // +kubebuilder:validation:MaxLength=63 // +kubebuilder:validation:Pattern=`^[a-z]([-a-z0-9]*[a-z0-9])?$` Name string `json:"name"` - // Objects are a list of all the objects within this phase. + + // The objects field is a required list of all Kubernetes objects in this phase. + // + // All objects in this list are applied to the cluster simultaneously. + // The phase is considered complete only after all objects pass their readiness probes. Objects []ClusterExtensionRevisionObject `json:"objects"` } -// ClusterExtensionRevisionObject contains an object and settings for it. +// ClusterExtensionRevisionObject represents a Kubernetes object to be applied as part +// of a ClusterExtensionRevision, along with its collision protection settings. type ClusterExtensionRevisionObject struct { + // The object field is a required embedded Kubernetes object to be applied. + // + // This object must be a valid Kubernetes resource with apiVersion, kind, and metadata fields. + // Status fields are not permitted and are removed if present. + // Only specific metadata fields are preserved: name, namespace, labels, and annotations. + // // +kubebuilder:validation:EmbeddedResource // +kubebuilder:pruning:PreserveUnknownFields Object unstructured.Unstructured `json:"object"` - // CollisionProtection controls whether OLM can adopt and modify objects - // already existing on the cluster or even owned by another controller. + + // The collisionProtection field controls whether the operator can adopt and modify objects + // that already exist on the cluster. + // + // When set to "Prevent" (the default), the operator only manages objects it created itself. + // This prevents ownership collisions. + // + // When set to "IfNoController", the operator can adopt and modify pre-existing objects + // that are not owned by another controller. + // This is useful for taking over management of manually-created resources. + // + // When set to "None", the operator can adopt and modify any pre-existing object, even if + // owned by another controller. + // Use this setting with extreme caution as it may cause multiple controllers to fight over + // the same resource, resulting in increased load on the API server and etcd. // // +kubebuilder:default="Prevent" // +kubebuilder:validation:Enum=Prevent;IfNoController;None @@ -128,6 +242,27 @@ const ( // ClusterExtensionRevisionStatus defines the observed state of a ClusterExtensionRevision. type ClusterExtensionRevisionStatus struct { + // conditions is an optional list of status conditions describing the state of the + // ClusterExtensionRevision. + // + // The Progressing condition represents whether the revision is actively rolling out: + // - When status is True and reason is Progressing, the revision rollout is actively making progress and is in transition. + // - When Progressing is not present, the revision is not currently in transition. + // + // The Available condition represents whether the revision has been successfully rolled out and is available: + // - When status is True and reason is Available, the revision has been successfully rolled out and all objects pass their readiness probes. + // - When status is False and reason is Incomplete, the revision rollout has not yet completed but no specific failures have been detected. + // - When status is False and reason is ProbeFailure, one or more objects are failing their readiness probes during rollout. + // - When status is False and reason is ReconcileFailure, the revision has encountered a general reconciliation failure. + // - When status is False and reason is RevisionValidationFailure, the revision failed preflight validation checks. + // - When status is False and reason is PhaseValidationError, a phase within the revision failed preflight validation checks. + // - When status is False and reason is ObjectCollisions, objects in the revision collide with existing cluster objects that cannot be adopted. + // - When status is Unknown and reason is Archived, the revision has been archived and its objects have been torn down. + // - When status is Unknown and reason is Migrated, the revision was migrated from an existing release and object status probe results have not yet been observed. + // + // The Succeeded condition represents whether the revision has successfully completed its rollout at least once: + // - When status is True and reason is RolloutSuccess, the revision has successfully completed its rollout. This condition is set once and persists even if the revision later becomes unavailable. + // // +listType=map // +listMapKey=type // +optional @@ -137,19 +272,38 @@ type ClusterExtensionRevisionStatus struct { // +kubebuilder:object:root=true // +kubebuilder:resource:scope=Cluster // +kubebuilder:subresource:status - -// ClusterExtensionRevision is the Schema for the clusterextensionrevisions API // +kubebuilder:printcolumn:name="Available",type=string,JSONPath=`.status.conditions[?(@.type=='Available')].status` // +kubebuilder:printcolumn:name=Age,type=date,JSONPath=`.metadata.creationTimestamp` + +// ClusterExtensionRevision is the schema for the ClusterExtensionRevisions API. +// +// A ClusterExtensionRevision represents an immutable snapshot of Kubernetes objects +// for a specific version of a ClusterExtension. Each revision contains objects +// organized into phases that roll out sequentially. +// +// The ClusterExtension controller creates and manages ClusterExtensionRevisions automatically. +// Do not create them directly. Each ClusterExtension can have multiple revisions as it +// upgrades or reconfigures. +// +// The revision rollout uses a phased approach where objects apply in a defined order based +// on type (for example: namespaces, then RBAC, then CRDs, then deployments). All objects +// in a phase apply simultaneously and must pass readiness probes before rollout continues +// to the next phase. +// +// Revisions have three lifecycle states: +// - Active: The revision is actively managed and reconciled (default) +// - Paused: Reconciliation is disabled but status updates continue +// - Archived: The revision is torn down, objects are deleted, and the revision removes +// itself from the owner list of managed objects type ClusterExtensionRevision struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` - // spec is an optional field that defines the desired state of the ClusterExtension. + // The spec field is optional and defines the desired state of the ClusterExtensionRevision. // +optional Spec ClusterExtensionRevisionSpec `json:"spec,omitempty"` - // status is an optional field that defines the observed state of the ClusterExtension. + // The status field is optional and defines the observed state of the ClusterExtensionRevision. // +optional Status ClusterExtensionRevisionStatus `json:"status,omitempty"` } diff --git a/helm/olmv1/base/operator-controller/crd/experimental/olm.operatorframework.io_clusterextensionrevisions.yaml b/helm/olmv1/base/operator-controller/crd/experimental/olm.operatorframework.io_clusterextensionrevisions.yaml index b25e57903..978688430 100644 --- a/helm/olmv1/base/operator-controller/crd/experimental/olm.operatorframework.io_clusterextensionrevisions.yaml +++ b/helm/olmv1/base/operator-controller/crd/experimental/olm.operatorframework.io_clusterextensionrevisions.yaml @@ -25,8 +25,27 @@ spec: name: v1 schema: openAPIV3Schema: - description: ClusterExtensionRevision is the Schema for the clusterextensionrevisions - API + description: |- + ClusterExtensionRevision is the schema for the ClusterExtensionRevisions API. + + A ClusterExtensionRevision represents an immutable snapshot of Kubernetes objects + for a specific version of a ClusterExtension. Each revision contains objects + organized into phases that roll out sequentially. + + The ClusterExtension controller creates and manages ClusterExtensionRevisions automatically. + Do not create them directly. Each ClusterExtension can have multiple revisions as it + upgrades or reconfigures. + + The revision rollout uses a phased approach where objects apply in a defined order based + on type (for example: namespaces, then RBAC, then CRDs, then deployments). All objects + in a phase apply simultaneously and must pass readiness probes before rollout continues + to the next phase. + + Revisions have three lifecycle states: + - Active: The revision is actively managed and reconciled (default) + - Paused: Reconciliation is disabled but status updates continue + - Archived: The revision is torn down, objects are deleted, and the revision removes + itself from the owner list of managed objects properties: apiVersion: description: |- @@ -46,12 +65,21 @@ spec: metadata: type: object spec: - description: spec is an optional field that defines the desired state - of the ClusterExtension. + description: The spec field is optional and defines the desired state + of the ClusterExtensionRevision. properties: lifecycleState: default: Active - description: Specifies the lifecycle state of the ClusterExtensionRevision. + description: |- + The lifecycleState field specifies the lifecycle state of the ClusterExtensionRevision. + + When set to "Active" (the default), the revision is actively managed and reconciled. + When set to "Paused", reconciliation is disabled but status updates continue. + When set to "Archived", the revision is torn down and scaled to zero. + The revision is removed from the owner list of all objects previously under management. + All objects that did not transition to a succeeding revision are deleted. + + Once a revision is set to "Archived", it cannot be un-archived. enum: - Active - Paused @@ -63,36 +91,83 @@ spec: && oldSelf == self phases: description: |- - Phases are groups of objects that will be applied at the same time. - All objects in the phase will have to pass their probes in order to progress to the next phase. + The phases field is an optional, immutable list of phases that group objects to be applied together. + + Objects are organized into phases based on their Group-Kind. Common phases include: + - namespaces: Namespace objects + - policies: ResourceQuota, LimitRange, NetworkPolicy objects + - rbac: ServiceAccount, Role, RoleBinding, ClusterRole, ClusterRoleBinding objects + - crds: CustomResourceDefinition objects + - storage: PersistentVolume, PersistentVolumeClaim, StorageClass objects + - deploy: Deployment, StatefulSet, DaemonSet, Service, ConfigMap, Secret objects + - publish: Ingress, APIService, Route, Webhook objects + + All objects in a phase are applied simultaneously. + The revision progresses to the next phase only after all objects in the current phase pass their readiness probes. + + Once set (even if empty), the phases field is immutable. items: description: |- - ClusterExtensionRevisionPhase are groups of objects that will be applied at the same time. - All objects in the a phase will have to pass their probes in order to progress to the next phase. + ClusterExtensionRevisionPhase represents a group of objects that are applied together. + + Objects in a phase are applied simultaneously. + All objects must pass their readiness probes before the revision progresses to the next phase. + Phases are applied in a defined order based on the types of objects they contain. properties: name: - description: Name identifies this phase. + description: |- + The name field is a required identifier for this phase. + + Phase names must follow the DNS label standard as defined in [RFC 1123]. + They must contain only lowercase alphanumeric characters or hyphens (-), + start and end with an alphanumeric character, and be no longer than 63 characters. + + Common phase names include: namespaces, policies, rbac, crds, storage, deploy, publish. + + [RFC 1123]: https://tools.ietf.org/html/rfc1123 maxLength: 63 pattern: ^[a-z]([-a-z0-9]*[a-z0-9])?$ type: string objects: - description: Objects are a list of all the objects within this - phase. + description: |- + The objects field is a required list of all Kubernetes objects in this phase. + + All objects in this list are applied to the cluster simultaneously. + The phase is considered complete only after all objects pass their readiness probes. items: - description: ClusterExtensionRevisionObject contains an object - and settings for it. + description: |- + ClusterExtensionRevisionObject represents a Kubernetes object to be applied as part + of a ClusterExtensionRevision, along with its collision protection settings. properties: collisionProtection: default: Prevent description: |- - CollisionProtection controls whether OLM can adopt and modify objects - already existing on the cluster or even owned by another controller. + The collisionProtection field controls whether the operator can adopt and modify objects + that already exist on the cluster. + + When set to "Prevent" (the default), the operator only manages objects it created itself. + This prevents ownership collisions. + + When set to "IfNoController", the operator can adopt and modify pre-existing objects + that are not owned by another controller. + This is useful for taking over management of manually-created resources. + + When set to "None", the operator can adopt and modify any pre-existing object, even if + owned by another controller. + Use this setting with extreme caution as it may cause multiple controllers to fight over + the same resource, resulting in increased load on the API server and etcd. enum: - Prevent - IfNoController - None type: string object: + description: |- + The object field is a required embedded Kubernetes object to be applied. + + This object must be a valid Kubernetes resource with apiVersion, kind, and metadata fields. + Status fields are not permitted and are removed if present. + Only specific metadata fields are preserved: name, namespace, labels, and annotations. type: object x-kubernetes-embedded-resource: true x-kubernetes-preserve-unknown-fields: true @@ -113,9 +188,12 @@ spec: rule: self == oldSelf || oldSelf.size() == 0 revision: description: |- - Revision is a sequence number representing a specific revision of the ClusterExtension instance. - Must be positive. Each ClusterExtensionRevision of the same parent ClusterExtension needs to have - a unique value assigned. It is immutable after creation. The new revision number must always be previous revision +1. + The revision field is a required, immutable sequence number representing a specific revision + of the parent ClusterExtension. + + The revision field must be a positive integer. + Each ClusterExtensionRevision belonging to the same parent ClusterExtension must have a unique revision number. + The revision number must always be the previous revision number plus one, or 1 for the first revision. format: int64 minimum: 1 type: integer @@ -126,10 +204,31 @@ spec: - revision type: object status: - description: status is an optional field that defines the observed state - of the ClusterExtension. + description: The status field is optional and defines the observed state + of the ClusterExtensionRevision. properties: conditions: + description: |- + conditions is an optional list of status conditions describing the state of the + ClusterExtensionRevision. + + The Progressing condition represents whether the revision is actively rolling out: + - When status is True and reason is Progressing, the revision rollout is actively making progress and is in transition. + - When Progressing is not present, the revision is not currently in transition. + + The Available condition represents whether the revision has been successfully rolled out and is available: + - When status is True and reason is Available, the revision has been successfully rolled out and all objects pass their readiness probes. + - When status is False and reason is Incomplete, the revision rollout has not yet completed but no specific failures have been detected. + - When status is False and reason is ProbeFailure, one or more objects are failing their readiness probes during rollout. + - When status is False and reason is ReconcileFailure, the revision has encountered a general reconciliation failure. + - When status is False and reason is RevisionValidationFailure, the revision failed preflight validation checks. + - When status is False and reason is PhaseValidationError, a phase within the revision failed preflight validation checks. + - When status is False and reason is ObjectCollisions, objects in the revision collide with existing cluster objects that cannot be adopted. + - When status is Unknown and reason is Archived, the revision has been archived and its objects have been torn down. + - When status is Unknown and reason is Migrated, the revision was migrated from an existing release and object status probe results have not yet been observed. + + The Succeeded condition represents whether the revision has successfully completed its rollout at least once: + - When status is True and reason is RolloutSuccess, the revision has successfully completed its rollout. This condition is set once and persists even if the revision later becomes unavailable. items: description: Condition contains details for one aspect of the current state of this API Resource. diff --git a/manifests/experimental-e2e.yaml b/manifests/experimental-e2e.yaml index 672830225..792bdb32b 100644 --- a/manifests/experimental-e2e.yaml +++ b/manifests/experimental-e2e.yaml @@ -616,8 +616,27 @@ spec: name: v1 schema: openAPIV3Schema: - description: ClusterExtensionRevision is the Schema for the clusterextensionrevisions - API + description: |- + ClusterExtensionRevision is the schema for the ClusterExtensionRevisions API. + + A ClusterExtensionRevision represents an immutable snapshot of Kubernetes objects + for a specific version of a ClusterExtension. Each revision contains objects + organized into phases that roll out sequentially. + + The ClusterExtension controller creates and manages ClusterExtensionRevisions automatically. + Do not create them directly. Each ClusterExtension can have multiple revisions as it + upgrades or reconfigures. + + The revision rollout uses a phased approach where objects apply in a defined order based + on type (for example: namespaces, then RBAC, then CRDs, then deployments). All objects + in a phase apply simultaneously and must pass readiness probes before rollout continues + to the next phase. + + Revisions have three lifecycle states: + - Active: The revision is actively managed and reconciled (default) + - Paused: Reconciliation is disabled but status updates continue + - Archived: The revision is torn down, objects are deleted, and the revision removes + itself from the owner list of managed objects properties: apiVersion: description: |- @@ -637,12 +656,21 @@ spec: metadata: type: object spec: - description: spec is an optional field that defines the desired state - of the ClusterExtension. + description: The spec field is optional and defines the desired state + of the ClusterExtensionRevision. properties: lifecycleState: default: Active - description: Specifies the lifecycle state of the ClusterExtensionRevision. + description: |- + The lifecycleState field specifies the lifecycle state of the ClusterExtensionRevision. + + When set to "Active" (the default), the revision is actively managed and reconciled. + When set to "Paused", reconciliation is disabled but status updates continue. + When set to "Archived", the revision is torn down and scaled to zero. + The revision is removed from the owner list of all objects previously under management. + All objects that did not transition to a succeeding revision are deleted. + + Once a revision is set to "Archived", it cannot be un-archived. enum: - Active - Paused @@ -654,36 +682,83 @@ spec: && oldSelf == self phases: description: |- - Phases are groups of objects that will be applied at the same time. - All objects in the phase will have to pass their probes in order to progress to the next phase. + The phases field is an optional, immutable list of phases that group objects to be applied together. + + Objects are organized into phases based on their Group-Kind. Common phases include: + - namespaces: Namespace objects + - policies: ResourceQuota, LimitRange, NetworkPolicy objects + - rbac: ServiceAccount, Role, RoleBinding, ClusterRole, ClusterRoleBinding objects + - crds: CustomResourceDefinition objects + - storage: PersistentVolume, PersistentVolumeClaim, StorageClass objects + - deploy: Deployment, StatefulSet, DaemonSet, Service, ConfigMap, Secret objects + - publish: Ingress, APIService, Route, Webhook objects + + All objects in a phase are applied simultaneously. + The revision progresses to the next phase only after all objects in the current phase pass their readiness probes. + + Once set (even if empty), the phases field is immutable. items: description: |- - ClusterExtensionRevisionPhase are groups of objects that will be applied at the same time. - All objects in the a phase will have to pass their probes in order to progress to the next phase. + ClusterExtensionRevisionPhase represents a group of objects that are applied together. + + Objects in a phase are applied simultaneously. + All objects must pass their readiness probes before the revision progresses to the next phase. + Phases are applied in a defined order based on the types of objects they contain. properties: name: - description: Name identifies this phase. + description: |- + The name field is a required identifier for this phase. + + Phase names must follow the DNS label standard as defined in [RFC 1123]. + They must contain only lowercase alphanumeric characters or hyphens (-), + start and end with an alphanumeric character, and be no longer than 63 characters. + + Common phase names include: namespaces, policies, rbac, crds, storage, deploy, publish. + + [RFC 1123]: https://tools.ietf.org/html/rfc1123 maxLength: 63 pattern: ^[a-z]([-a-z0-9]*[a-z0-9])?$ type: string objects: - description: Objects are a list of all the objects within this - phase. + description: |- + The objects field is a required list of all Kubernetes objects in this phase. + + All objects in this list are applied to the cluster simultaneously. + The phase is considered complete only after all objects pass their readiness probes. items: - description: ClusterExtensionRevisionObject contains an object - and settings for it. + description: |- + ClusterExtensionRevisionObject represents a Kubernetes object to be applied as part + of a ClusterExtensionRevision, along with its collision protection settings. properties: collisionProtection: default: Prevent description: |- - CollisionProtection controls whether OLM can adopt and modify objects - already existing on the cluster or even owned by another controller. + The collisionProtection field controls whether the operator can adopt and modify objects + that already exist on the cluster. + + When set to "Prevent" (the default), the operator only manages objects it created itself. + This prevents ownership collisions. + + When set to "IfNoController", the operator can adopt and modify pre-existing objects + that are not owned by another controller. + This is useful for taking over management of manually-created resources. + + When set to "None", the operator can adopt and modify any pre-existing object, even if + owned by another controller. + Use this setting with extreme caution as it may cause multiple controllers to fight over + the same resource, resulting in increased load on the API server and etcd. enum: - Prevent - IfNoController - None type: string object: + description: |- + The object field is a required embedded Kubernetes object to be applied. + + This object must be a valid Kubernetes resource with apiVersion, kind, and metadata fields. + Status fields are not permitted and are removed if present. + Only specific metadata fields are preserved: name, namespace, labels, and annotations. type: object x-kubernetes-embedded-resource: true x-kubernetes-preserve-unknown-fields: true @@ -704,9 +779,12 @@ spec: rule: self == oldSelf || oldSelf.size() == 0 revision: description: |- - Revision is a sequence number representing a specific revision of the ClusterExtension instance. - Must be positive. Each ClusterExtensionRevision of the same parent ClusterExtension needs to have - a unique value assigned. It is immutable after creation. The new revision number must always be previous revision +1. + The revision field is a required, immutable sequence number representing a specific revision + of the parent ClusterExtension. + + The revision field must be a positive integer. + Each ClusterExtensionRevision belonging to the same parent ClusterExtension must have a unique revision number. + The revision number must always be the previous revision number plus one, or 1 for the first revision. format: int64 minimum: 1 type: integer @@ -717,10 +795,31 @@ spec: - revision type: object status: - description: status is an optional field that defines the observed state - of the ClusterExtension. + description: The status field is optional and defines the observed state + of the ClusterExtensionRevision. properties: conditions: + description: |- + conditions is an optional list of status conditions describing the state of the + ClusterExtensionRevision. + + The Progressing condition represents whether the revision is actively rolling out: + - When status is True and reason is Progressing, the revision rollout is actively making progress and is in transition. + - When Progressing is not present, the revision is not currently in transition. + + The Available condition represents whether the revision has been successfully rolled out and is available: + - When status is True and reason is Available, the revision has been successfully rolled out and all objects pass their readiness probes. + - When status is False and reason is Incomplete, the revision rollout has not yet completed but no specific failures have been detected. + - When status is False and reason is ProbeFailure, one or more objects are failing their readiness probes during rollout. + - When status is False and reason is ReconcileFailure, the revision has encountered a general reconciliation failure. + - When status is False and reason is RevisionValidationFailure, the revision failed preflight validation checks. + - When status is False and reason is PhaseValidationError, a phase within the revision failed preflight validation checks. + - When status is False and reason is ObjectCollisions, objects in the revision collide with existing cluster objects that cannot be adopted. + - When status is Unknown and reason is Archived, the revision has been archived and its objects have been torn down. + - When status is Unknown and reason is Migrated, the revision was migrated from an existing release and object status probe results have not yet been observed. + + The Succeeded condition represents whether the revision has successfully completed its rollout at least once: + - When status is True and reason is RolloutSuccess, the revision has successfully completed its rollout. This condition is set once and persists even if the revision later becomes unavailable. items: description: Condition contains details for one aspect of the current state of this API Resource. diff --git a/manifests/experimental.yaml b/manifests/experimental.yaml index 199838eac..90e9797d1 100644 --- a/manifests/experimental.yaml +++ b/manifests/experimental.yaml @@ -581,8 +581,27 @@ spec: name: v1 schema: openAPIV3Schema: - description: ClusterExtensionRevision is the Schema for the clusterextensionrevisions - API + description: |- + ClusterExtensionRevision is the schema for the ClusterExtensionRevisions API. + + A ClusterExtensionRevision represents an immutable snapshot of Kubernetes objects + for a specific version of a ClusterExtension. Each revision contains objects + organized into phases that roll out sequentially. + + The ClusterExtension controller creates and manages ClusterExtensionRevisions automatically. + Do not create them directly. Each ClusterExtension can have multiple revisions as it + upgrades or reconfigures. + + The revision rollout uses a phased approach where objects apply in a defined order based + on type (for example: namespaces, then RBAC, then CRDs, then deployments). All objects + in a phase apply simultaneously and must pass readiness probes before rollout continues + to the next phase. + + Revisions have three lifecycle states: + - Active: The revision is actively managed and reconciled (default) + - Paused: Reconciliation is disabled but status updates continue + - Archived: The revision is torn down, objects are deleted, and the revision removes + itself from the owner list of managed objects properties: apiVersion: description: |- @@ -602,12 +621,21 @@ spec: metadata: type: object spec: - description: spec is an optional field that defines the desired state - of the ClusterExtension. + description: The spec field is optional and defines the desired state + of the ClusterExtensionRevision. properties: lifecycleState: default: Active - description: Specifies the lifecycle state of the ClusterExtensionRevision. + description: |- + The lifecycleState field specifies the lifecycle state of the ClusterExtensionRevision. + + When set to "Active" (the default), the revision is actively managed and reconciled. + When set to "Paused", reconciliation is disabled but status updates continue. + When set to "Archived", the revision is torn down and scaled to zero. + The revision is removed from the owner list of all objects previously under management. + All objects that did not transition to a succeeding revision are deleted. + + Once a revision is set to "Archived", it cannot be un-archived. enum: - Active - Paused @@ -619,36 +647,83 @@ spec: && oldSelf == self phases: description: |- - Phases are groups of objects that will be applied at the same time. - All objects in the phase will have to pass their probes in order to progress to the next phase. + The phases field is an optional, immutable list of phases that group objects to be applied together. + + Objects are organized into phases based on their Group-Kind. Common phases include: + - namespaces: Namespace objects + - policies: ResourceQuota, LimitRange, NetworkPolicy objects + - rbac: ServiceAccount, Role, RoleBinding, ClusterRole, ClusterRoleBinding objects + - crds: CustomResourceDefinition objects + - storage: PersistentVolume, PersistentVolumeClaim, StorageClass objects + - deploy: Deployment, StatefulSet, DaemonSet, Service, ConfigMap, Secret objects + - publish: Ingress, APIService, Route, Webhook objects + + All objects in a phase are applied simultaneously. + The revision progresses to the next phase only after all objects in the current phase pass their readiness probes. + + Once set (even if empty), the phases field is immutable. items: description: |- - ClusterExtensionRevisionPhase are groups of objects that will be applied at the same time. - All objects in the a phase will have to pass their probes in order to progress to the next phase. + ClusterExtensionRevisionPhase represents a group of objects that are applied together. + + Objects in a phase are applied simultaneously. + All objects must pass their readiness probes before the revision progresses to the next phase. + Phases are applied in a defined order based on the types of objects they contain. properties: name: - description: Name identifies this phase. + description: |- + The name field is a required identifier for this phase. + + Phase names must follow the DNS label standard as defined in [RFC 1123]. + They must contain only lowercase alphanumeric characters or hyphens (-), + start and end with an alphanumeric character, and be no longer than 63 characters. + + Common phase names include: namespaces, policies, rbac, crds, storage, deploy, publish. + + [RFC 1123]: https://tools.ietf.org/html/rfc1123 maxLength: 63 pattern: ^[a-z]([-a-z0-9]*[a-z0-9])?$ type: string objects: - description: Objects are a list of all the objects within this - phase. + description: |- + The objects field is a required list of all Kubernetes objects in this phase. + + All objects in this list are applied to the cluster simultaneously. + The phase is considered complete only after all objects pass their readiness probes. items: - description: ClusterExtensionRevisionObject contains an object - and settings for it. + description: |- + ClusterExtensionRevisionObject represents a Kubernetes object to be applied as part + of a ClusterExtensionRevision, along with its collision protection settings. properties: collisionProtection: default: Prevent description: |- - CollisionProtection controls whether OLM can adopt and modify objects - already existing on the cluster or even owned by another controller. + The collisionProtection field controls whether the operator can adopt and modify objects + that already exist on the cluster. + + When set to "Prevent" (the default), the operator only manages objects it created itself. + This prevents ownership collisions. + + When set to "IfNoController", the operator can adopt and modify pre-existing objects + that are not owned by another controller. + This is useful for taking over management of manually-created resources. + + When set to "None", the operator can adopt and modify any pre-existing object, even if + owned by another controller. + Use this setting with extreme caution as it may cause multiple controllers to fight over + the same resource, resulting in increased load on the API server and etcd. enum: - Prevent - IfNoController - None type: string object: + description: |- + The object field is a required embedded Kubernetes object to be applied. + + This object must be a valid Kubernetes resource with apiVersion, kind, and metadata fields. + Status fields are not permitted and are removed if present. + Only specific metadata fields are preserved: name, namespace, labels, and annotations. type: object x-kubernetes-embedded-resource: true x-kubernetes-preserve-unknown-fields: true @@ -669,9 +744,12 @@ spec: rule: self == oldSelf || oldSelf.size() == 0 revision: description: |- - Revision is a sequence number representing a specific revision of the ClusterExtension instance. - Must be positive. Each ClusterExtensionRevision of the same parent ClusterExtension needs to have - a unique value assigned. It is immutable after creation. The new revision number must always be previous revision +1. + The revision field is a required, immutable sequence number representing a specific revision + of the parent ClusterExtension. + + The revision field must be a positive integer. + Each ClusterExtensionRevision belonging to the same parent ClusterExtension must have a unique revision number. + The revision number must always be the previous revision number plus one, or 1 for the first revision. format: int64 minimum: 1 type: integer @@ -682,10 +760,31 @@ spec: - revision type: object status: - description: status is an optional field that defines the observed state - of the ClusterExtension. + description: The status field is optional and defines the observed state + of the ClusterExtensionRevision. properties: conditions: + description: |- + conditions is an optional list of status conditions describing the state of the + ClusterExtensionRevision. + + The Progressing condition represents whether the revision is actively rolling out: + - When status is True and reason is Progressing, the revision rollout is actively making progress and is in transition. + - When Progressing is not present, the revision is not currently in transition. + + The Available condition represents whether the revision has been successfully rolled out and is available: + - When status is True and reason is Available, the revision has been successfully rolled out and all objects pass their readiness probes. + - When status is False and reason is Incomplete, the revision rollout has not yet completed but no specific failures have been detected. + - When status is False and reason is ProbeFailure, one or more objects are failing their readiness probes during rollout. + - When status is False and reason is ReconcileFailure, the revision has encountered a general reconciliation failure. + - When status is False and reason is RevisionValidationFailure, the revision failed preflight validation checks. + - When status is False and reason is PhaseValidationError, a phase within the revision failed preflight validation checks. + - When status is False and reason is ObjectCollisions, objects in the revision collide with existing cluster objects that cannot be adopted. + - When status is Unknown and reason is Archived, the revision has been archived and its objects have been torn down. + - When status is Unknown and reason is Migrated, the revision was migrated from an existing release and object status probe results have not yet been observed. + + The Succeeded condition represents whether the revision has successfully completed its rollout at least once: + - When status is True and reason is RolloutSuccess, the revision has successfully completed its rollout. This condition is set once and persists even if the revision later becomes unavailable. items: description: Condition contains details for one aspect of the current state of this API Resource.