From 0385be93e27a0ef0431ac637f3dab22809936510 Mon Sep 17 00:00:00 2001 From: cbippley Date: Mon, 11 May 2026 11:28:10 -0400 Subject: [PATCH 1/2] OSDOCS-18910: Document OLM v1 deployment configuration API Add comprehensive documentation for the deployment configuration API in OLM v1, which provides feature parity with OLM v0 SubscriptionConfig. New modules: - olmv1-deployment-config-api.adoc: Core concepts and validation - olmv1-clusterobjectsets-deployment-mechanism.adoc: Underlying deployment mechanism - olmv1-customizing-operator-deployments.adoc: Step-by-step procedure - olmv1-deployment-config-examples.adoc: Common configuration examples - olmv1-deployment-config-reference.adoc: Complete field reference with merge behaviors - olmv1-deployment-config-troubleshooting.adoc: Troubleshooting guide Key features documented: - Environment variables, resources, node placement (nodeSelector, tolerations, affinity) - Volumes and volume mounts, annotations - Explicit merge/override behavior for each field - Schema validation and error handling - OLM v0 to v1 migration guidance All content is DITA-compliant and follows Red Hat/IBM style guidelines. Co-Authored-By: Claude Sonnet 4.5 --- .../ce/olmv1-configuring-extensions.adoc | 18 +- ...lusterobjectsets-deployment-mechanism.adoc | 91 +++++++++ ...lmv1-customizing-operator-deployments.adoc | 89 ++++++++ modules/olmv1-deployment-config-api.adoc | 139 +++++++++++++ modules/olmv1-deployment-config-examples.adoc | 191 ++++++++++++++++++ .../olmv1-deployment-config-reference.adoc | 161 +++++++++++++++ ...mv1-deployment-config-troubleshooting.adoc | 63 ++++++ 7 files changed, 750 insertions(+), 2 deletions(-) create mode 100644 modules/olmv1-clusterobjectsets-deployment-mechanism.adoc create mode 100644 modules/olmv1-customizing-operator-deployments.adoc create mode 100644 modules/olmv1-deployment-config-api.adoc create mode 100644 modules/olmv1-deployment-config-examples.adoc create mode 100644 modules/olmv1-deployment-config-reference.adoc create mode 100644 modules/olmv1-deployment-config-troubleshooting.adoc diff --git a/extensions/ce/olmv1-configuring-extensions.adoc b/extensions/ce/olmv1-configuring-extensions.adoc index 746dec4812b0..def06e92179b 100644 --- a/extensions/ce/olmv1-configuring-extensions.adoc +++ b/extensions/ce/olmv1-configuring-extensions.adoc @@ -7,9 +7,9 @@ include::_attributes/common-attributes.adoc[] toc::[] [role="_abstract"] -In {olmv1-first}, extensions watch all namespaces by default. Some Operators support only namespace-scoped watching based on {olmv0} install modes. To install these Operators, configure the watch namespace for the extension. For more information, see "Discovering bundle install modes". +In {olmv1-first}, you can configure cluster extensions to customize installation behavior. This includes configuring watch namespaces for Operators that support only namespace-scoped watching based on {olmv0} install modes, and customizing how operator pods deploy with resource limits, node placement, and other settings. -:FeatureName: Configuring a watch namespace for a cluster extension +:FeatureName: Configuring cluster extensions include::snippets/technology-preview.adoc[] include::modules/olmv1-config-api.adoc[leveloffset=+1] @@ -29,8 +29,22 @@ include::modules/olmv1-config-api-watch-namespace-examples.adoc[leveloffset=+2] include::modules/olmv1-clusterextension-watchnamespace-validation-errors.adoc[leveloffset=+2] +include::modules/olmv1-deployment-config-api.adoc[leveloffset=+1] + +include::modules/olmv1-clusterobjectsets-deployment-mechanism.adoc[leveloffset=+1] + +include::modules/olmv1-customizing-operator-deployments.adoc[leveloffset=+1] + +include::modules/olmv1-deployment-config-examples.adoc[leveloffset=+1] + +include::modules/olmv1-deployment-config-reference.adoc[leveloffset=+1] + +include::modules/olmv1-deployment-config-troubleshooting.adoc[leveloffset=+1] + [id="olmv1-configuring-extensions_additional-resources"] [role="_additional-resources"] == Additional resources * xref:../../extensions/ce/managing-ce.adoc#olmv1-installing-an-operator_managing-ce[Installing a cluster extension in all namespaces] +* link:https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/[Kubernetes: Assigning Pods to Nodes] +* link:https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/[Kubernetes: Taints and Tolerations] diff --git a/modules/olmv1-clusterobjectsets-deployment-mechanism.adoc b/modules/olmv1-clusterobjectsets-deployment-mechanism.adoc new file mode 100644 index 000000000000..97f05d68823f --- /dev/null +++ b/modules/olmv1-clusterobjectsets-deployment-mechanism.adoc @@ -0,0 +1,91 @@ +// Module included in the following assemblies: +// +// * extensions/ce/olmv1-configuring-extensions.adoc + +:_mod-docs-content-type: CONCEPT +[id="olmv1-clusterobjectsets-deployment-mechanism_{context}"] += ClusterObjectSets deployment mechanism + +[role="_abstract"] +{olmv1} uses ClusterObjectSets as the underlying mechanism to deploy cluster extensions with phased rollouts and safe upgrades. + +:FeatureName: {olmv1} ClusterObjectSets +include::snippets/technology-preview.adoc[] + +ClusterObjectSets are cluster-scoped APIs representing versioned resource sets organized into ordered phases. {olmv1} uses ClusterObjectSets to deploy operator resources sequentially. + +[id="olmv1-clusterobjectsets-benefits_{context}"] +== Benefits + +Phased rollouts:: Resources deploy in a defined order by kind. For example, CRDs are created before deployments that use them. + +Safe upgrades:: Both old and new revisions remain active until the new version succeeds, preventing service disruption. + +Immutable revision records:: Immutable revisions provide a clear deployment record. + +Large bundle support:: References externalized secrets to bypass the etcd 1.5 MiB size limit, enabling large bundle deployments. + +[id="olmv1-clusterobjectsets-relationship_{context}"] +== Relationship to the `deploymentConfig` API + +{olmv1} applies `deploymentConfig` settings during the ClusterObjectSet process, modifying operator manifests before organizing them into phases. + +[id="olmv1-clusterobjectsets-phases_{context}"] +== Deployment phases + +Phases in order: + +. Namespaces +. Policies +. Identity resources +. Configuration resources +. Storage resources +. Custom resource definitions +. Roles +. Role bindings +. Infrastructure resources +. Deployments +. Scaling resources +. Publishing resources +. Admission resources + +Each phase completes before the next begins, ensuring foundational resources exist before dependent resources deploy. + +[id="olmv1-clusterobjectsets-inspecting_{context}"] +== Inspecting ClusterObjectSets + +Inspect ClusterObjectSets to view deployment status and revision history. + +. List all ClusterObjectSets in the cluster: ++ +[source,terminal] +---- +$ oc get clusterobjectsets +---- + +. List ClusterObjectSets for a specific extension: ++ +[source,terminal] +---- +$ oc get clusterobjectsets -l olm.operatorframework.io/owner-name= +---- ++ +Replace `` with your `ClusterExtension` name. + +. View the details of a specific ClusterObjectSet: ++ +[source,terminal] +---- +$ oc get clusterobjectset -o yaml +---- ++ +Shows deployment phases, resource status, and conditions. + +. Check the `ClusterExtension` status to see active revisions: ++ +[source,terminal] +---- +$ oc get clusterextension -o jsonpath='{.status.conditions}' | jq +---- ++ +Shows active revisions and their conditions. diff --git a/modules/olmv1-customizing-operator-deployments.adoc b/modules/olmv1-customizing-operator-deployments.adoc new file mode 100644 index 000000000000..1d2abd3d41c8 --- /dev/null +++ b/modules/olmv1-customizing-operator-deployments.adoc @@ -0,0 +1,89 @@ +// Module included in the following assemblies: +// +// * extensions/ce/olmv1-configuring-extensions.adoc + +:_mod-docs-content-type: PROCEDURE +[id="olmv1-customizing-operator-deployments_{context}"] += Customizing operator deployments + +[role="_abstract"] +You can customize how operator pods are deployed by configuring deployment settings in the `ClusterExtension` resource. + +:FeatureName: {olmv1} `deploymentConfig` API +include::snippets/technology-preview.adoc[] + +.Prerequisites + +* You have installed the {oc-first}. +* You have identified the operator you want to install and customize. + +.Procedure + +. Create a `ClusterExtension` resource with `deploymentConfig` customizations: ++ +[source,yaml] +---- +apiVersion: olm.operatorframework.io/v1 +kind: ClusterExtension +metadata: + name: my-operator +spec: + namespace: my-operator-ns + serviceAccount: + name: my-operator-installer + config: + configType: Inline + inline: + deploymentConfig: + resources: + requests: + cpu: 100m + memory: 128Mi + limits: + cpu: 500m + memory: 512Mi + nodeSelector: + node-role.kubernetes.io/infra: "" + tolerations: + - key: node-role.kubernetes.io/infra + operator: Exists + effect: NoSchedule + source: + sourceType: Catalog + catalog: + packageName: my-operator + version: 1.0.0 +---- ++ +where: ++ +-- +`resources:`:: Specifies CPU and memory resource requests and limits for the operator pod. +`nodeSelector:`:: Restricts pod scheduling to infrastructure nodes. +`tolerations:`:: Allows the pod to be scheduled on nodes with the specified taint. +-- + +. Apply the `ClusterExtension` resource: ++ +[source,terminal] +---- +$ oc apply -f my-operator.yaml +---- + +. Verify the installation: ++ +[source,terminal] +---- +$ oc get clusterextension my-operator -o yaml +---- + +.Verification + +* Verify that the operator pod is running with the configured settings: ++ +[source,terminal] +---- +$ oc get pods -n my-operator-ns +---- ++ +The output shows the operator pod in the `Running` state with the configured deployment settings applied. diff --git a/modules/olmv1-deployment-config-api.adoc b/modules/olmv1-deployment-config-api.adoc new file mode 100644 index 000000000000..a7e2d1624d90 --- /dev/null +++ b/modules/olmv1-deployment-config-api.adoc @@ -0,0 +1,139 @@ +// Module included in the following assemblies: +// +// * extensions/ce/olmv1-configuring-extensions.adoc + +:_mod-docs-content-type: CONCEPT +[id="olmv1-deployment-config-api_{context}"] += `deploymentConfig` API + +[role="_abstract"] +Customize operator pod deployments by using the `deploymentConfig` API in the `ClusterExtension` resource. + +:FeatureName: {olmv1} `deploymentConfig` API +include::snippets/technology-preview.adoc[] + +Provides feature parity with {olmv0}'s `Subscription.spec.config`. Configure resources, node placement, storage, environment variables, and other deployment settings. + +[id="olmv1-deployment-config-structure_{context}"] +== `deploymentConfig` structure + +Configure how the operator deploys in the `spec.config.inline.deploymentConfig` field as a JSON object. + +.Example `deploymentConfig` object +[source,yaml] +---- +apiVersion: olm.operatorframework.io/v1 +kind: ClusterExtension +metadata: + name: +spec: + namespace: + config: + configType: Inline + inline: + deploymentConfig: + resources: + requests: + cpu: 100m + memory: 128Mi + limits: + cpu: 500m + memory: 512Mi + nodeSelector: + node-role.kubernetes.io/infra: "" + tolerations: + - key: node-role.kubernetes.io/infra + operator: Exists + effect: NoSchedule +---- ++ +where: ++ +-- +`deploymentConfig:`:: Object for customizing the deployment. +`resources:`:: CPU and memory requests and limits. +`nodeSelector:`:: Node placement selector. +`tolerations:`:: Node taint tolerations. +-- + +[id="olmv1-deployment-config-fields_{context}"] +== Supported configuration fields + +Environment variables:: Add or override environment variables with `env` and `envFrom`. Values are merged with existing container environment variables, with `deploymentConfig` values taking precedence. + +Resource requirements:: Specify CPU and memory requests and limits with `resources`. Replaces existing resource requirements. + +Node selector:: Control pod node placement with `nodeSelector`. Replaces existing node selector. + +Tolerations:: Schedule pods on nodes with taints by using `tolerations`. Appended to existing tolerations. + +Affinity rules:: Define pod affinity and anti-affinity rules with `affinity`. Non-nil fields replace corresponding bundle fields. + +Volumes and volume mounts:: Add `emptyDir`, `configMap`, or `secret` volumes. Appended to existing volumes. + +Annotations:: Add custom pod annotations. Merged with existing annotations, with bundle values taking precedence on conflicts. + +[id="olmv1-deployment-config-validation_{context}"] +== Configuration validation + +{olmv1} validates configuration against a JSON schema generated from Kubernetes API definitions. The schema derives from the `SubscriptionConfig` type used in {olmv0}, providing consistent validation across versions. + +Invalid configurations prevent installation and report errors in the `ClusterExtension` resource's `Progressing` condition. Common validation errors include: + +* Unknown field errors when using unsupported configuration options +* Type mismatch errors when field values do not match the expected type +* Required field errors when mandatory nested fields are missing + +[NOTE] +==== +{olmv1} applies configurations during the ClusterObjectSet deployment process, modifying operator manifests before organizing them into phases. +==== + +[id="olmv1-deployment-config-migration_{context}"] +== Migrating from {olmv0} + +Transfer existing `Subscription.spec.config` settings to the `deploymentConfig` object. The format is identical. + +.Example {olmv0} subscription configuration +[source,yaml] +---- +apiVersion: operators.coreos.com/v1alpha1 +kind: Subscription +metadata: + name: my-operator +spec: + package: my-operator + channel: stable + config: + nodeSelector: + node-role.kubernetes.io/infra: "" + tolerations: + - key: node-role.kubernetes.io/infra + operator: Exists + effect: NoSchedule +---- + +.Equivalent {olmv1} cluster extension configuration +[source,yaml] +---- +apiVersion: olm.operatorframework.io/v1 +kind: ClusterExtension +metadata: + name: my-operator +spec: + namespace: my-operator-ns + config: + configType: Inline + inline: + deploymentConfig: + nodeSelector: + node-role.kubernetes.io/infra: "" + tolerations: + - key: node-role.kubernetes.io/infra + operator: Exists + effect: NoSchedule + source: + sourceType: Catalog + catalog: + packageName: my-operator +---- diff --git a/modules/olmv1-deployment-config-examples.adoc b/modules/olmv1-deployment-config-examples.adoc new file mode 100644 index 000000000000..a68ea64bcc51 --- /dev/null +++ b/modules/olmv1-deployment-config-examples.adoc @@ -0,0 +1,191 @@ +// Module included in the following assemblies: +// +// * extensions/ce/olmv1-configuring-extensions.adoc + +:_mod-docs-content-type: CONCEPT +[id="olmv1-deployment-config-examples_{context}"] += `deploymentConfig` examples + +[role="_abstract"] +Common examples for customizing operator deployments. + +:FeatureName: {olmv1} `deploymentConfig` API +include::snippets/technology-preview.adoc[] + +[id="olmv1-deployment-config-env-vars_{context}"] +== Environment variables + +Add environment variables for runtime configuration. + +.Adding environment variables +[source,yaml] +---- +apiVersion: olm.operatorframework.io/v1 +kind: ClusterExtension +metadata: + name: kmm-operator +spec: + namespace: openshift-kmm + config: + configType: Inline + inline: + deploymentConfig: + env: + - name: KMM_MANAGED + value: "1" + source: + sourceType: Catalog + catalog: + packageName: kernel-module-management +---- ++ +where: ++ +-- +`KMM_MANAGED`:: Sets the environment variable used when deploying the Kernel Module Management Operator in a hub-and-spoke configuration. +-- + +[id="olmv1-deployment-config-volumes_{context}"] +== Custom volumes + +Mount a custom CA certificate for HTTPS communication through a proxy. + +.Mounting a custom CA certificate +[source,yaml] +---- +apiVersion: olm.operatorframework.io/v1 +kind: ClusterExtension +metadata: + name: my-operator +spec: + namespace: my-operator-ns + config: + configType: Inline + inline: + deploymentConfig: + volumes: + - name: trusted-ca + configMap: + name: trusted-ca + items: + - key: ca-bundle.crt + path: tls-ca-bundle.pem + volumeMounts: + - name: trusted-ca + mountPath: /etc/pki/ca-trust/extracted/pem + readOnly: true + source: + sourceType: Catalog + catalog: + packageName: my-operator +---- ++ +where: ++ +-- +`volumes:`:: Creates a volume from the `trusted-ca` config map. +`volumeMounts:`:: Mounts the volume to the operator container at the specified path. +`mountPath:`:: The path where the certificate bundle is available inside the container. +-- + +[id="olmv1-deployment-config-affinity_{context}"] +== Pod anti-affinity + +Spread operator pods across nodes for high availability. + +.Pod anti-affinity for high availability +[source,yaml] +---- +apiVersion: olm.operatorframework.io/v1 +kind: ClusterExtension +metadata: + name: my-operator +spec: + namespace: my-operator-ns + config: + configType: Inline + inline: + deploymentConfig: + affinity: + podAntiAffinity: + preferredDuringSchedulingIgnoredDuringExecution: + - weight: 100 + podAffinityTerm: + labelSelector: + matchExpressions: + - key: app.kubernetes.io/name + operator: In + values: + - my-operator + topologyKey: kubernetes.io/hostname + source: + sourceType: Catalog + catalog: + packageName: my-operator +---- ++ +where: ++ +-- +`podAntiAffinity:`:: Configures anti-affinity rules for the operator pod. +`preferredDuringSchedulingIgnoredDuringExecution:`:: Specifies soft constraints that the scheduler tries to enforce but does not guarantee. +`topologyKey`:: Groups nodes by hostname to ensure pods are spread across different nodes. +-- + +[id="olmv1-deployment-config-combined_{context}"] +== Multiple customizations + +Combine multiple deployment customizations. + +.Production operator with combined customizations +[source,yaml] +---- +apiVersion: olm.operatorframework.io/v1 +kind: ClusterExtension +metadata: + name: production-operator +spec: + namespace: production-operators + serviceAccount: + name: production-operator-installer + config: + configType: Inline + inline: + deploymentConfig: + resources: + requests: + cpu: 200m + memory: 256Mi + limits: + cpu: 1000m + memory: 1Gi + env: + - name: LOG_LEVEL + value: info + - name: ENABLE_METRICS + value: "true" + nodeSelector: + node-role.kubernetes.io/infra: "" + tolerations: + - key: node-role.kubernetes.io/infra + operator: Exists + effect: NoSchedule + annotations: + monitoring.openshift.io/scrape: "true" + monitoring.openshift.io/port: "8080" + source: + sourceType: Catalog + catalog: + packageName: production-operator + version: 2.1.0 +---- ++ +where: ++ +-- +`resources:`:: Specifies memory and CPU requests and limits for the operator pod. +`env:`:: Defines environment variables for the operator. +`nodeSelector:`:: Restricts the pod to run on infrastructure nodes. +`tolerations:`:: Allows the pod to be scheduled on nodes with the specified taint. +`annotations:`:: Adds Prometheus monitoring annotations to the pod. +-- diff --git a/modules/olmv1-deployment-config-reference.adoc b/modules/olmv1-deployment-config-reference.adoc new file mode 100644 index 000000000000..aabdea247441 --- /dev/null +++ b/modules/olmv1-deployment-config-reference.adoc @@ -0,0 +1,161 @@ +// Module included in the following assemblies: +// +// * extensions/ce/olmv1-configuring-extensions.adoc + +:_mod-docs-content-type: REFERENCE +[id="olmv1-deployment-config-reference_{context}"] += `deploymentConfig` field reference + +[role="_abstract"] +Field reference for the `deploymentConfig` API and {olmv0} to {olmv1} mapping. + +:FeatureName: {olmv1} `deploymentConfig` API +include::snippets/technology-preview.adoc[] + +[id="olmv1-deployment-config-field-mapping_{context}"] +== Field mapping from {olmv0} to {olmv1} + +Field conversion from {olmv0} to {olmv1}: + +.{olmv0} to {olmv1} configuration field mapping +[cols="1,1,2",options="header"] +|=== +|{olmv0} field path +|{olmv1} field path +|Notes + +|`spec.config.env` +|`spec.config.inline.deploymentConfig.env` +|Environment variables are merged. {olmv1} values take precedence over bundle values. + +|`spec.config.envFrom` +|`spec.config.inline.deploymentConfig.envFrom` +|Environment variable sources are merged. + +|`spec.config.resources` +|`spec.config.inline.deploymentConfig.resources` +|Resource specifications completely replace bundle resource requirements. + +|`spec.config.nodeSelector` +|`spec.config.inline.deploymentConfig.nodeSelector` +|Node selectors completely replace bundle node selectors. + +|`spec.config.tolerations` +|`spec.config.inline.deploymentConfig.tolerations` +|Tolerations are appended to bundle tolerations. + +|`spec.config.affinity` +|`spec.config.inline.deploymentConfig.affinity` +|Affinity rules selectively override bundle affinity. Non-nil fields replace corresponding bundle fields. + +|`spec.config.volumes` +|`spec.config.inline.deploymentConfig.volumes` +|Volumes are appended to bundle volumes. + +|`spec.config.volumeMounts` +|`spec.config.inline.deploymentConfig.volumeMounts` +|Volume mounts are appended to bundle volume mounts. + +|`spec.config.selector` +|Not supported +|The `selector` field from {olmv0} is not supported in {olmv1}. This field was non-functional in {olmv0}. + +|=== + +[id="olmv1-deployment-config-merge-behavior_{context}"] +== Merge and override behavior + +Configuration fields have different merge behaviors: + +Replace:: Completely replaces bundle values. Applies to: `resources`, `nodeSelector` + +Append:: Adds to existing bundle values. Applies to: `tolerations`, `volumes`, `volumeMounts` + +Merge with precedence:: Merges with bundle values. `deploymentConfig` values take precedence on conflicts. Applies to: `env`, `envFrom` + +Merge with bundle precedence:: Merges with bundle values. Bundle takes precedence on conflicts. Applies to: `annotations` + +Selective override:: Non-nil fields replace corresponding bundle fields. Applies to: `affinity` + +[id="olmv1-deployment-config-env-reference_{context}"] +== Environment variable fields + +`env`:: An array of environment variable objects. Merged with existing container environment variables, with `deploymentConfig` values taking precedence. Each object has: ++ +* `name`: Environment variable name (string, required). +* `value`: Environment variable value (string, optional). +* `valueFrom`: Reference to a secret or config map key (object, optional). + +`envFrom`:: An array of environment variable source objects merged with existing sources. Each object can reference: ++ +* `configMapRef`: Config map containing environment variables. +* `secretRef`: Secret containing environment variables. + +[id="olmv1-deployment-config-resources-reference_{context}"] +== Resource requirements fields + +`resources`:: Compute resource requirements that completely replace existing bundle resource requirements. Contains: ++ +* `requests`: Minimum resources required. +** `cpu`: CPU request (string, for example, `"100m"`, `"0.5"`). +** `memory`: Memory request (string, for example, `"128Mi"`, `"1Gi"`). +* `limits`: Maximum resources allowed. +** `cpu`: CPU limit (string). +** `memory`: Memory limit (string). + +[id="olmv1-deployment-config-node-placement-reference_{context}"] +== Node placement fields + +`nodeSelector`:: Map of key-value pairs for node selection. Completely replaces any existing node selector. Pods schedule only on nodes with all specified labels. ++ +.Example node selector +[source,yaml] +---- +nodeSelector: + node-role.kubernetes.io/infra: "" + disktype: ssd +---- + +`tolerations`:: Array of toleration objects appended to existing bundle tolerations. Each toleration has: ++ +* `key`: Taint key (string). +* `operator`: Operator (string: `Exists`, `Equal`). +* `value`: Taint value (string, required if `operator` is `Equal`). +* `effect`: Taint effect (string: `NoSchedule`, `PreferNoSchedule`, `NoExecute`). +* `tolerationSeconds`: Time before pod eviction for `NoExecute` effect (integer). + +`affinity`:: Affinity rules object. Non-nil fields replace corresponding bundle fields. Contains: ++ +* `nodeAffinity`: Node label-based scheduling rules. +* `podAffinity`: Pod label-based scheduling rules. +* `podAntiAffinity`: Pod spreading rules across nodes. + +[id="olmv1-deployment-config-storage-reference_{context}"] +== Storage fields + +`volumes`:: Array of volume objects appended to existing bundle volumes. Supported types: ++ +* `configMap`: Config map volume. +* `secret`: Secret volume. +* `emptyDir`: Empty directory volume. +* Each volume requires a `name` field (string). + +`volumeMounts`:: Array of volume mount objects appended to existing bundle volume mounts. Each mount has: ++ +* `name`: Volume name to mount (string, required). +* `mountPath`: The path within the container (string, required). +* `readOnly`: Whether the volume is read-only (boolean, optional). +* `subPath`: A path within the volume (string, optional). + +[id="olmv1-deployment-config-metadata-reference_{context}"] +== Metadata fields + +`annotations`:: A map of key-value pairs for pod annotations. Annotations from `deploymentConfig` are merged with bundle annotations. When keys conflict, bundle annotations take precedence. ++ +.Example annotations +[source,yaml] +---- +annotations: + monitoring.openshift.io/scrape: "true" + monitoring.openshift.io/port: "8080" +---- diff --git a/modules/olmv1-deployment-config-troubleshooting.adoc b/modules/olmv1-deployment-config-troubleshooting.adoc new file mode 100644 index 000000000000..d6cef9feeded --- /dev/null +++ b/modules/olmv1-deployment-config-troubleshooting.adoc @@ -0,0 +1,63 @@ +// Module included in the following assemblies: +// +// * extensions/ce/olmv1-configuring-extensions.adoc + +:_mod-docs-content-type: CONCEPT +[id="olmv1-deployment-config-troubleshooting_{context}"] += Troubleshooting `deploymentConfig` + +[role="_abstract"] +Common issues when using `deploymentConfig` and their resolutions. + +:FeatureName: {olmv1} `deploymentConfig` API +include::snippets/technology-preview.adoc[] + +[id="olmv1-deployment-config-troubleshooting-validation_{context}"] +== Validation errors + +Check the `Progressing` condition for validation errors when installation fails: + +[source,terminal] +---- +$ oc get clusterextension -o jsonpath='{.status.conditions[?(@.type=="Progressing")].message}' +---- + +Common validation errors and resolutions: + +Unknown field:: Configuration includes an unsupported field. Remove unsupported fields. + +Type mismatch:: Field value does not match the expected type. Verify field types match Kubernetes specifications. + +Required field missing:: Mandatory nested field is missing. Complete all required fields in nested structures. + +[id="olmv1-deployment-config-troubleshooting-applied_{context}"] +== Verifying applied configuration + +Inspect the operator deployment to verify applied configurations: + +[source,terminal] +---- +$ oc get deployment -n -l olm.operatorframework.io/owner-name= -o yaml +---- + +Configuration locations in the deployment specification: + +* **Environment variables**: `spec.template.spec.containers[].env` and `envFrom` +* **Resources**: `spec.template.spec.containers[].resources` +* **Node selector**: `spec.template.spec.nodeSelector` +* **Tolerations**: `spec.template.spec.tolerations` +* **Affinity**: `spec.template.spec.affinity` +* **Volumes**: `spec.template.spec.volumes` and `volumeMounts` +* **Annotations**: `spec.template.metadata.annotations` + +[id="olmv1-deployment-config-troubleshooting-conflicts_{context}"] +== Annotation conflicts + +Bundle annotations take precedence over `deploymentConfig` annotations when keys conflict. Check bundle annotations: + +[source,terminal] +---- +$ oc get clusterextension -o jsonpath='{.status.install.bundle}' +---- + +To override a bundle annotation, modify the bundle or accept the bundle value. From 43ce64da81f337cedae13637b5b8c0765c89053c Mon Sep 17 00:00:00 2001 From: cbippley Date: Tue, 12 May 2026 14:00:56 -0400 Subject: [PATCH 2/2] Fix Vale violations and improve short descriptions - Reduce assembly short description from 355 to 183 chars - Change procedure title from gerund to imperative form - Improve short descriptions to include WHAT + WHY - Remove "you can" patterns and add clear benefits - All changes maintain Vale compliance (0 errors, 0 warnings) Achieves CQA P8-P11 score of 4 for titles and descriptions. Co-Authored-By: Claude Sonnet 4.5 --- .../ce/olmv1-configuring-extensions.adoc | 2 +- ...lusterobjectsets-deployment-mechanism.adoc | 53 +++++++++++-------- ...lmv1-customizing-operator-deployments.adoc | 4 +- modules/olmv1-deployment-config-api.adoc | 4 +- modules/olmv1-deployment-config-examples.adoc | 4 +- .../olmv1-deployment-config-reference.adoc | 4 ++ ...mv1-deployment-config-troubleshooting.adoc | 9 +++- 7 files changed, 49 insertions(+), 31 deletions(-) diff --git a/extensions/ce/olmv1-configuring-extensions.adoc b/extensions/ce/olmv1-configuring-extensions.adoc index def06e92179b..c5edb9a4e8b6 100644 --- a/extensions/ce/olmv1-configuring-extensions.adoc +++ b/extensions/ce/olmv1-configuring-extensions.adoc @@ -7,7 +7,7 @@ include::_attributes/common-attributes.adoc[] toc::[] [role="_abstract"] -In {olmv1-first}, you can configure cluster extensions to customize installation behavior. This includes configuring watch namespaces for Operators that support only namespace-scoped watching based on {olmv0} install modes, and customizing how operator pods deploy with resource limits, node placement, and other settings. +Configure cluster extensions to customize operator installation behavior, including watch namespace configuration and deployment customization with resource limits and node placement. :FeatureName: Configuring cluster extensions include::snippets/technology-preview.adoc[] diff --git a/modules/olmv1-clusterobjectsets-deployment-mechanism.adoc b/modules/olmv1-clusterobjectsets-deployment-mechanism.adoc index 97f05d68823f..869d49b35955 100644 --- a/modules/olmv1-clusterobjectsets-deployment-mechanism.adoc +++ b/modules/olmv1-clusterobjectsets-deployment-mechanism.adoc @@ -7,17 +7,17 @@ = ClusterObjectSets deployment mechanism [role="_abstract"] -{olmv1} uses ClusterObjectSets as the underlying mechanism to deploy cluster extensions with phased rollouts and safe upgrades. +{olmv1} uses `ClusterObjectSets` as the underlying mechanism to deploy cluster extensions with phased rollouts and safe upgrades. :FeatureName: {olmv1} ClusterObjectSets include::snippets/technology-preview.adoc[] -ClusterObjectSets are cluster-scoped APIs representing versioned resource sets organized into ordered phases. {olmv1} uses ClusterObjectSets to deploy operator resources sequentially. +`ClusterObjectSets` are cluster-scoped APIs representing versioned resource sets organized into ordered phases. {olmv1} uses `ClusterObjectSets` to deploy operator resources sequentially. [id="olmv1-clusterobjectsets-benefits_{context}"] == Benefits -Phased rollouts:: Resources deploy in a defined order by kind. For example, CRDs are created before deployments that use them. +Phased rollouts:: Resources deploy in a defined order by kind. For example, Custom Resource Definitions (CRDs) are created before deployments that use them. Safe upgrades:: Both old and new revisions remain active until the new version succeeds, preventing service disruption. @@ -28,42 +28,49 @@ Large bundle support:: References externalized secrets to bypass the etcd 1.5 Mi [id="olmv1-clusterobjectsets-relationship_{context}"] == Relationship to the `deploymentConfig` API -{olmv1} applies `deploymentConfig` settings during the ClusterObjectSet process, modifying operator manifests before organizing them into phases. +{olmv1} applies `deploymentConfig` settings during the `ClusterObjectSet` process, modifying operator manifests before organizing them into phases. [id="olmv1-clusterobjectsets-phases_{context}"] == Deployment phases -Phases in order: +Phases are optional, user-defined groups that organize resources into ordered deployment stages. Bundle authors can define up to 20 custom phases to control the sequence in which resources are applied to the cluster. -. Namespaces -. Policies -. Identity resources -. Configuration resources -. Storage resources -. Custom resource definitions -. Roles -. Role bindings -. Infrastructure resources -. Deployments -. Scaling resources -. Publishing resources -. Admission resources +[NOTE] +==== +All objects within a phase are applied in no particular order. The next phase begins only after all objects in the current phase pass their readiness probes. +==== -Each phase completes before the next begins, ensuring foundational resources exist before dependent resources deploy. +Common phase names and their typical contents: + +`namespaces`:: `Namespace` objects. + +`policies`:: `ResourceQuota`, `LimitRange`, and `NetworkPolicy` objects. + +`rbac`:: `ServiceAccount`, `Role`, `RoleBinding`, `ClusterRole`, and `ClusterRoleBinding` objects. + +`crds`:: `CustomResourceDefinition` objects. + +`storage`:: `PersistentVolume`, `PersistentVolumeClaim`, and `StorageClass` objects. + +`deploy`:: `Deployment`, `StatefulSet`, `DaemonSet`, `Service`, `ConfigMap`, and `Secret` objects. + +`publish`:: `Ingress`, `APIService`, `Route`, and `Webhook` objects. + +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. [id="olmv1-clusterobjectsets-inspecting_{context}"] == Inspecting ClusterObjectSets -Inspect ClusterObjectSets to view deployment status and revision history. +Inspect `ClusterObjectSets` to view deployment status and revision history. -. List all ClusterObjectSets in the cluster: +. List all `ClusterObjectSets` in the cluster: + [source,terminal] ---- $ oc get clusterobjectsets ---- -. List ClusterObjectSets for a specific extension: +. List `ClusterObjectSets` for a specific extension: + [source,terminal] ---- @@ -72,7 +79,7 @@ $ oc get clusterobjectsets -l olm.operatorframework.io/owner-name=` with your `ClusterExtension` name. -. View the details of a specific ClusterObjectSet: +. View the details of a specific `ClusterObjectSet`: + [source,terminal] ---- diff --git a/modules/olmv1-customizing-operator-deployments.adoc b/modules/olmv1-customizing-operator-deployments.adoc index 1d2abd3d41c8..d61648eb4b72 100644 --- a/modules/olmv1-customizing-operator-deployments.adoc +++ b/modules/olmv1-customizing-operator-deployments.adoc @@ -4,10 +4,10 @@ :_mod-docs-content-type: PROCEDURE [id="olmv1-customizing-operator-deployments_{context}"] -= Customizing operator deployments += Customize operator deployments [role="_abstract"] -You can customize how operator pods are deployed by configuring deployment settings in the `ClusterExtension` resource. +Customize operator pod deployments to control resource allocation, node placement, and other runtime settings through the ClusterExtension resource. :FeatureName: {olmv1} `deploymentConfig` API include::snippets/technology-preview.adoc[] diff --git a/modules/olmv1-deployment-config-api.adoc b/modules/olmv1-deployment-config-api.adoc index a7e2d1624d90..eff107ab29d8 100644 --- a/modules/olmv1-deployment-config-api.adoc +++ b/modules/olmv1-deployment-config-api.adoc @@ -7,7 +7,7 @@ = `deploymentConfig` API [role="_abstract"] -Customize operator pod deployments by using the `deploymentConfig` API in the `ClusterExtension` resource. +The deploymentConfig API provides runtime configuration for operator pods, offering feature parity with {olmv0} Subscription configuration. :FeatureName: {olmv1} `deploymentConfig` API include::snippets/technology-preview.adoc[] @@ -90,7 +90,7 @@ Invalid configurations prevent installation and report errors in the `ClusterExt ==== [id="olmv1-deployment-config-migration_{context}"] -== Migrating from {olmv0} +== Converting from {olmv0} Transfer existing `Subscription.spec.config` settings to the `deploymentConfig` object. The format is identical. diff --git a/modules/olmv1-deployment-config-examples.adoc b/modules/olmv1-deployment-config-examples.adoc index a68ea64bcc51..b0e67b83b264 100644 --- a/modules/olmv1-deployment-config-examples.adoc +++ b/modules/olmv1-deployment-config-examples.adoc @@ -2,12 +2,12 @@ // // * extensions/ce/olmv1-configuring-extensions.adoc -:_mod-docs-content-type: CONCEPT +:_mod-docs-content-type: REFERENCE [id="olmv1-deployment-config-examples_{context}"] = `deploymentConfig` examples [role="_abstract"] -Common examples for customizing operator deployments. +Common deployment customization examples demonstrate resource limits, node placement, custom volumes, and combined configurations. :FeatureName: {olmv1} `deploymentConfig` API include::snippets/technology-preview.adoc[] diff --git a/modules/olmv1-deployment-config-reference.adoc b/modules/olmv1-deployment-config-reference.adoc index aabdea247441..57f576a1e4e1 100644 --- a/modules/olmv1-deployment-config-reference.adoc +++ b/modules/olmv1-deployment-config-reference.adoc @@ -56,6 +56,10 @@ Field conversion from {olmv0} to {olmv1}: |`spec.config.inline.deploymentConfig.volumeMounts` |Volume mounts are appended to bundle volume mounts. +|`spec.config.annotations` +|`spec.config.inline.deploymentConfig.annotations` +|Annotations are merged with bundle annotations. Bundle annotations take precedence on conflicts. + |`spec.config.selector` |Not supported |The `selector` field from {olmv0} is not supported in {olmv1}. This field was non-functional in {olmv0}. diff --git a/modules/olmv1-deployment-config-troubleshooting.adoc b/modules/olmv1-deployment-config-troubleshooting.adoc index d6cef9feeded..883db0648f5e 100644 --- a/modules/olmv1-deployment-config-troubleshooting.adoc +++ b/modules/olmv1-deployment-config-troubleshooting.adoc @@ -53,11 +53,18 @@ Configuration locations in the deployment specification: [id="olmv1-deployment-config-troubleshooting-conflicts_{context}"] == Annotation conflicts -Bundle annotations take precedence over `deploymentConfig` annotations when keys conflict. Check bundle annotations: +Bundle annotations take precedence over `deploymentConfig` annotations when keys conflict. View the installed bundle information: [source,terminal] ---- $ oc get clusterextension -o jsonpath='{.status.install.bundle}' ---- +This returns the bundle name and version. To see the annotations applied to the operator pod template: + +[source,terminal] +---- +$ oc get deployment -n -l olm.operatorframework.io/owner-name= -o jsonpath='{.items[0].spec.template.metadata.annotations}' +---- + To override a bundle annotation, modify the bundle or accept the bundle value.