OSDOCS-18910: Document OLM v1 deployment configuration API

[cbippley]

Overview

Documents the deployment configuration API for OLM v1, providing feature parity with OLM v0's SubscriptionConfig. This allows users to customize operator pod deployments with resources, node placement, storage, environment variables, and annotations.

Related Issues

• JIRA: OSDOCS-18910
• Upstream Feature: OCPSTRAT-2305
• Enhancement Proposal: OPRUN-4099: OLMv1 Deployment Configuration API openshift/enhancements#1915
• Upstream Documentation: 📖 Bundle Deployment Configuration operator-framework/operator-controller#2528

Content Added

New Modules (6)

1. olmv1-deployment-config-api.adoc (4.4K) - CONCEPT

   • Deployment configuration API overview
   • Configuration structure and validation
   • OLM v0 to v1 migration guidance

2. olmv1-clusterobjectsets-deployment-mechanism.adoc (2.7K) - CONCEPT

   • ClusterObjectSets deployment mechanism
   • Benefits: phased rollouts, safe upgrades, immutable revisions
   • 13 deployment phases documented

3. olmv1-customizing-operator-deployments.adoc (2.1K) - PROCEDURE

   • Step-by-step customization guide
   • Prerequisites and verification steps
   • DITA-compliant procedure structure

4. olmv1-deployment-config-examples.adoc (4.7K) - CONCEPT

   • Environment variables (KMM use case)
   • Custom volumes (CA certificates)
   • Pod anti-affinity (high availability)
   • Multiple customizations (production scenario)

5. olmv1-deployment-config-reference.adoc (5.8K) - REFERENCE

   • Complete OLM v0 → v1 field mapping table
   • Explicit merge/override behavior for each field:
     • Replace: resources, nodeSelector
     • Append: tolerations, volumes, volumeMounts
     • Merge with precedence: env, envFrom
     • Merge with bundle precedence: annotations
     • Selective override: affinity
   • Detailed field descriptions

6. olmv1-deployment-config-troubleshooting.adoc (2.2K) - CONCEPT

   • Validation error diagnosis
   • Configuration verification procedures
   • Annotation conflict resolution

Updated Files

• extensions/ce/olmv1-configuring-extensions.adoc - Added new modules to assembly

Documentation Quality

✅ DITA Compliance: 0 errors, 0 warnings across all modules
✅ Vale Style Guide: 0 errors, 0 warnings (Red Hat + IBM style guides)
✅ Concise Language: ~30-40% prose reduction while maintaining accuracy
✅ Technical Accuracy: Validated against upstream documentation
✅ Module Structure: Proper CONCEPT, PROCEDURE, REFERENCE types
✅ Definition Lists: DITA-compliant explanations (no callouts)

Testing Checklist

• Vale linting passes (0 errors, 0 warnings)
• DITA validation passes (0 errors)
• AsciiDoc builds successfully
• Cross-references are valid
• All YAML examples are syntactically correct
• Technical review by SME (Per Goncalves da Silva)
• QE review (Bruno Andrade)
• Content tested against OLM v1 Tech Preview

SME Review Needed

I will add inline comments on specific areas that need SME verification.

Target Version

OpenShift 4.22 (Tech Preview)

[cbippley]

Areas Requiring SME Verification

The following claims could not be validated against upstream documentation and should be verified with Per Goncalves da Silva before merging:

🔴 Medium Priority - Commands/Procedures

1. Label Selector for Finding Operator Deployments

• Files: modules/olmv1-deployment-config-troubleshooting.adoc:40, modules/olmv1-clusterobjectsets-deployment-mechanism.adoc:74
• Claim: olm.operatorframework.io/owner-name=<extension_name>
• Issue: Not documented in upstream customize-operator-deployments.md
• Risk: If incorrect, troubleshooting commands won't find deployments
• Action: Verify this is the correct label for finding ClusterExtension-owned deployments

2. ClusterExtension Progressing Condition Path

• File: modules/olmv1-deployment-config-troubleshooting.adoc:22
• Claim: {.status.conditions[?(@.type=="Progressing")].message}
• Issue: Condition type name not documented in upstream
• Risk: Command may fail if condition is named differently (e.g., "Installing", "Reconciling")
• Action: Confirm ClusterExtension uses "Progressing" condition type

3. ClusterExtension Bundle Status Path

• File: modules/olmv1-deployment-config-troubleshooting.adoc:60
• Claim: {.status.install.bundle}
• Issue: Status field structure not in upstream docs
• Risk: May not return bundle annotations as expected
• Action: Verify correct jsonpath for retrieving bundle information

🟡 Low Priority - Should Confirm

4. Volume Type Support

• Files: Multiple modules
• Claim: Supports emptyDir, configMap, secret volumes
• Issue: Upstream says "volumes" supported but doesn't enumerate types
• Action: Confirm these types work; verify if other volume types are also supported

5. Deployment Specification Paths

• File: modules/olmv1-deployment-config-troubleshooting.adoc:45-51
• Claim: All the spec.template.spec.* paths for configuration verification
• Issue: Standard Kubernetes paths, not OLM-specific validation
• Action: Confirm these paths are correct in OLM v1 generated deployments

---

All other content has been validated against upstream documentation:

• https://github.com/operator-framework/operator-controller/blob/main/docs/draft/howto/customize-operator-deployments.md
• https://github.com/operator-framework/operator-controller/blob/main/docs/draft/howto/configure-bundles.md
• https://github.com/operator-framework/operator-controller/blob/main/docs/draft/concepts/clusterobjectsets.md

[cbippley]

Inline SME Review Requests

Adding specific line comments for areas requiring verification...

[cbippley]

SME Verification: Label Selector

File: modules/olmv1-deployment-config-troubleshooting.adoc:40

Please verify this label selector is correct for finding deployments owned by ClusterExtensions:

olm.operatorframework.io/owner-name=<extension_name>

Questions:

• Is this the correct label applied to operator deployments by OLM v1?
• Should this be a different label like olm.operatorframework.io/clusterextension or similar?
• Can you provide the exact label key/value pattern?

Testing: Run this command against a deployed ClusterExtension to verify it finds the deployment.

[cbippley]

SME Verification: ClusterExtension Condition Type

File: modules/olmv1-deployment-config-troubleshooting.adoc:22

Please verify the condition type name in the ClusterExtension status:

$ oc get clusterextension <name> -o jsonpath='{.status.conditions[?(@.type=="Progressing")].message}'

Questions:

• Is "Progressing" the correct condition type for installation/validation errors?
• Should it be "Installed", "Reconciling", or another type?
• What condition types are available in ClusterExtension status?

Testing: Check actual ClusterExtension resources to confirm available condition types.

[cbippley]

SME Verification: Bundle Status Path

File: modules/olmv1-deployment-config-troubleshooting.adoc:60

Please verify the jsonpath for retrieving bundle information:

$ oc get clusterextension <name> -o jsonpath='{.status.install.bundle}'

Questions:

• Is .status.install.bundle the correct path?
• Does this return the bundle annotations as expected?
• Is there a better way to retrieve bundle annotations for troubleshooting annotation conflicts?

Context: This is used in the "Annotation conflicts" section to help users identify which annotations come from the bundle vs. deployment configuration.

Alternative approaches to suggest if path is incorrect:

• Should users inspect the deployment directly?
• Is there a ClusterExtension field that lists bundle metadata?

[cbippley]

SME Verification: ClusterObjectSets Label Selector

File: modules/olmv1-clusterobjectsets-deployment-mechanism.adoc:74

Same label selector question as in troubleshooting module:

$ oc get clusterobjectsets -l olm.operatorframework.io/owner-name=<extension_name>

Questions:

• Is this the correct label for filtering ClusterObjectSets by owner?
• Does this label exist on ClusterObjectSet resources?
• Should this use a different label pattern?

Testing: Verify this command returns ClusterObjectSets for a specific ClusterExtension.

[cbippley]

SME Verification: Deployment Configuration Paths

File: modules/olmv1-deployment-config-troubleshooting.adoc:45-51

Please confirm these paths are accurate for verifying applied configurations in OLM v1 generated deployments:

* spec.template.spec.containers[].env
* spec.template.spec.containers[].resources
* spec.template.spec.nodeSelector
* spec.template.spec.tolerations
* spec.template.spec.affinity
* spec.template.spec.volumes
* spec.template.metadata.annotations

Questions:

• Are these the correct paths in deployments created by ClusterExtensions?
• Does OLM v1 use standard Kubernetes Deployment structure, or are there variations?
• Are there any OLM-specific annotations or labels users should look for?

Testing: Deploy a ClusterExtension with deployment configuration and verify these paths contain the configured values.

---

SME Verification: Supported Volume Types

Files: Multiple modules (olmv1-deployment-config-api.adoc, olmv1-deployment-config-examples.adoc, olmv1-deployment-config-reference.adoc)

Please confirm the supported volume types:

volumes:
- emptyDir
- configMap
- secret

Questions:

• Are these the only volume types supported?
• Can users also use: persistentVolumeClaim, hostPath, projected, downwardAPI, etc.?
• Are there any restrictions on volume types in deployment configuration?

Upstream note: Upstream docs say "volumes and volumeMounts" are supported but don't enumerate specific types.

[cbippley]

SME Review Needed

The following technical details need engineering verification before merge:

modules/olmv1-deployment-config-troubleshooting.adoc:

• Line 22: Verify Progressing condition type name
• Line 40: Verify olm.operatorframework.io/owner-name label selector
• Line 60: Verify {.status.install.bundle} jsonpath
• Lines 45-51: Verify deployment spec paths (env, resources, nodeSelector, tolerations, affinity, volumes, annotations)

modules/olmv1-clusterobjectsets-deployment-mechanism.adoc:

• Line 74: Verify olm.operatorframework.io/owner-name label selector for ClusterObjectSets

modules/olmv1-deployment-config-reference.adoc:

• Lines 136-141: Verify supported volume types (emptyDir, configMap, secret)

Please confirm these technical details match the actual OLMv1 API implementation.

[cbippley]

SME Review Needed

The following technical details need engineering verification before merge:

modules/olmv1-deployment-config-troubleshooting.adoc:

• Line 22: Verify Progressing condition type name
• Line 40: Verify olm.operatorframework.io/owner-name label selector
• Line 60: Verify {.status.install.bundle} jsonpath
• Lines 45-51: Verify deployment spec paths (env, resources, nodeSelector, tolerations, affinity, volumes, annotations)

modules/olmv1-clusterobjectsets-deployment-mechanism.adoc:

• Line 74: Verify olm.operatorframework.io/owner-name label selector for ClusterObjectSets

modules/olmv1-deployment-config-reference.adoc:

• Lines 136-141: Verify supported volume types (emptyDir, configMap, secret)

Please confirm these technical details match the actual OLMv1 API implementation.