OSDOCS-18910: Document OLM v1 deployment configuration API

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".
+Configure cluster extensions to customize operator installation behavior, including watch namespace configuration and deployment customization with resource limits and node placement.
 
-: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]

modules/olmv1-clusterobjectsets-deployment-mechanism.adoc

@@ -0,0 +1,98 @@
+// 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, 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.
+
+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 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.
+
+[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.
+====
+
+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.
+
+. 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=<extension_name>
+----
++
+Replace `<extension_name>` with your `ClusterExtension` name.
+
+. View the details of a specific `ClusterObjectSet`:
++
+[source,terminal]
+----
+$ oc get clusterobjectset <clusterobjectset_name> -o yaml
+----
++
+Shows deployment phases, resource status, and conditions.
+
+. Check the `ClusterExtension` status to see active revisions:
++
+[source,terminal]
+----
+$ oc get clusterextension <extension_name> -o jsonpath='{.status.conditions}' | jq
+----
++
+Shows active revisions and their conditions.

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}"]
+= Customize operator deployments
+
+[role="_abstract"]
+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[]
+
+.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.

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"]
+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[]
+
+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: <extension_name>
+spec:
+  namespace: <installation_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}"]
+== Converting 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
+----