openshift · michaelryanpeter · Oct 20, 2025 · Oct 28, 2025 · Oct 28, 2025 · Oct 28, 2025
diff --git a/modules/olm-creating-fb-catalog-image.adoc b/modules/olm-creating-fb-catalog-image.adoc
@@ -42,11 +42,11 @@ $ opm generate dockerfile <catalog_dir>
 endif::[]
 ifndef::openshift-origin[]
 $ opm generate dockerfile <catalog_dir> \
-    -i {registry-image} <1>
+    -i {registry-image}
 endif::[]
 ----
 ifndef::openshift-origin[]
-<1> Specify the official Red Hat base image by using the `-i` flag, otherwise the Dockerfile uses the default upstream image.
+The `-i` flag specifies the official Red Hat base image, otherwise the Dockerfile uses the default upstream image.
 endif::[]
 --
 +
@@ -56,45 +56,52 @@ The Dockerfile must be in the same parent directory as the catalog directory tha
 .Example directory structure
 [source,terminal]
 ----
-. <1>
-├── <catalog_dir> <2>
-└── <catalog_dir>.Dockerfile <3>
+.
+├── <catalog_dir>
+└── <catalog_dir>.Dockerfile
 ----
-<1> Parent directory
-<2> Catalog directory
-<3> Dockerfile generated by the `opm generate dockerfile` command
++
+* `.` is the parent directory.
++
+* `<catalog_dir>` is the catalog directory.
++
+* `<catalog_dir>.Dockerfile` is the Dockerfile generated by the `opm generate dockerfile` command.
 --
 
 .. Populate the catalog with the package definition for your Operator by running the `opm init` command:
 +
 [source,terminal]
 ----
-$ opm init <operator_name> \ <1>
-    --default-channel=preview \ <2>
-    --description=./README.md \ <3>
-    --icon=./operator-icon.svg \ <4>
-    --output yaml \ <5>
-    > <catalog_dir>/index.yaml <6>
-----
-<1> Operator, or package, name
-<2> Channel that subscriptions default to if unspecified
-<3> Path to the Operator's `README.md` or other documentation
-<4> Path to the Operator's icon
-<5> Output format: JSON or YAML
-<6> Path for creating the catalog configuration file
+$ opm init <operator_name> \
+    --default-channel=preview \
+    --description=./README.md \
+    --icon=./operator-icon.svg \
+    --output yaml \
+    > <catalog_dir>/index.yaml
+----
+where:
+
+`<operator_name>`:: Specifies the Operator, or package, name.
+`--default-channel`:: Specifies the channel that subscriptions default to if unspecified.
+`--description`:: Specifies the path to the Operator's `README.md` or other documentation.
+`--icon`:: Specifies the path to the Operator's icon.
+`--output`:: Specifies the output format: JSON or YAML.
+`<catalog_dir>/index.yaml`:: Specifies the path for creating the catalog configuration file.
 +
 This command generates an `olm.package` declarative config blob in the specified catalog configuration file.
 
 . Add a bundle to the catalog by running the `opm render` command:
 +
 [source,terminal]
 ----
-$ opm render <registry>/<namespace>/<bundle_image_name>:<tag> \ <1>
+$ opm render <registry>/<namespace>/<bundle_image_name>:<tag> \
     --output=yaml \
-    >> <catalog_dir>/index.yaml <2>
+    >> <catalog_dir>/index.yaml
 ----
-<1> Pull spec for the bundle image
-<2> Path to the catalog configuration file
+where:
+
+`<registry>/<namespace>/<bundle_image_name>:<tag>`:: Specifies the pull spec for the bundle image.
+`<catalog_dir>/index.yaml`:: Specifies the path to the catalog configuration file.
 +
 [NOTE]
 ====
@@ -111,9 +118,9 @@ schema: olm.channel
 package: <operator_name>
 name: preview
 entries:
-  - name: <operator_name>.v0.1.0 <1>
+  - name: <operator_name>.v0.1.0
 ----
-<1> Ensure that you include the period (`.`) after `<operator_name>` but before the `v` in the version. Otherwise, the entry fails to pass the `opm validate` command.
+Ensure that you include the period (`.`) after `<operator_name>` but before the `v` in the version. Otherwise, the entry fails to pass the `opm validate` command.
 
 . Validate the file-based catalog:
 

diff --git a/modules/olm-deprecations-schema.adoc b/modules/olm-deprecations-schema.adoc
@@ -38,31 +38,36 @@ Each `reference` type has their own requirements, as detailed in the following e
 [source,yaml]
 ----
 schema: olm.deprecations
-package: my-operator <1>
+package: my-operator
 entries:
   - reference:
-      schema: olm.package <2>
-    message: | <3>
+      schema: olm.package
+    message: |
     The 'my-operator' package is end of life. Please use the
     'my-operator-new' package for support.
   - reference:
       schema: olm.channel
-      name: alpha <4>
+      name: alpha
     message: |
     The 'alpha' channel is no longer supported. Please switch to the
     'stable' channel.
   - reference:
       schema: olm.bundle
-      name: my-operator.v1.68.0 <5>
+      name: my-operator.v1.68.0
     message: |
     my-operator.v1.68.0 is deprecated. Uninstall my-operator.v1.68.0 and
     install my-operator.v1.72.0 for support.
 ----
-<1> Each deprecation schema must have a `package` value, and that package reference must be unique across the catalog. There must not be an associated `name` field.
-<2> The `olm.package` schema must not include a `name` field, because it is determined by the `package` field defined earlier in the schema.
-<3> All `message` fields, for any `reference` type, must be a non-zero length and represented as an opaque text blob.
-<4> The `name` field for the `olm.channel` schema is required.
-<5> The `name` field for the `olm.bundle` schema is required.
++
+* Each deprecation schema must have a `package` value, and that package reference must be unique across the catalog. There must not be an associated `name` field.
++
+* The `olm.package` schema must not include a `name` field, because it is determined by the `package` field defined earlier in the schema.
++
+* All `message` fields, for any `reference` type, must be a non-zero length and represented as an opaque text blob.
++
+* The `name` field for the `olm.channel` schema is required.
++
+* The `name` field for the `olm.bundle` schema is required.
 ====
 
 [NOTE]

diff --git a/modules/olmv1-about-target-versions.adoc b/modules/olmv1-about-target-versions.adoc
@@ -35,9 +35,9 @@ apiVersion: olm.operatorframework.io/v1
       catalog:
         packageName: <package_name>
         channels:
-          - latest <1>
+          - latest
 ----
-<1> Optional: Installs the latest release that can be resolved from the specified channel. Updates to the channel are automatically installed. Specify the value of the `channels` parameter as an array.
+The optional `channels` parameter is an array value that installs the latest release that can be resolved from the specified channel. Updates to the channel are automatically installed.
 
 If you specify the Operator or extension's target version in the CR, {olmv1} installs the specified version. When the target version is specified in the CR, {olmv1} does not change the target version when updates are published to the catalog.
 
@@ -58,9 +58,9 @@ apiVersion: olm.operatorframework.io/v1
       sourceType: Catalog
       catalog:
         packageName: <package_name>
-        version: "1.11.1" <1>
+        version: "1.11.1"
 ----
-<1> Optional: Specifies the target version. If you want to update the version of the Operator or extension that is installed, you must manually update this field the CR to the desired target version.
+The optional `version` parameter specifies the target version. If you want to update the version of the Operator or extension that is installed, you must manually update this field in the CR to the desired target version.
 
 If you want to define a range of acceptable versions for an Operator or extension, you can specify a version range by using a comparison string. When you specify a version range, {olmv1} installs the latest version of an Operator or extension that can be resolved by the Operator Controller.
 
@@ -79,9 +79,9 @@ apiVersion: olm.operatorframework.io/v1
       sourceType: Catalog
       catalog:
         packageName: <package_name>
-        version: ">1.11.1" <1>
+        version: ">1.11.1"
 ----
-<1> Optional: Specifies that the desired version range is greater than version `1.11.1`. For more information, see "Support for version ranges".
+The optional `version` parameter specifies that the desired version range is greater than version `1.11.1`. For more information, see "Support for version ranges".
 
 After you create or update a CR, apply the configuration file by running the following command:
 

diff --git a/modules/olmv1-adding-a-catalog.adoc b/modules/olmv1-adding-a-catalog.adoc
@@ -19,19 +19,21 @@ To add a catalog to a cluster for {olmv1-first} usage, create a `ClusterCatalog`
 apiVersion: olm.operatorframework.io/v1
 kind: ClusterCatalog
 metadata:
-  name: my-redhat-operators <1>
+  name: my-redhat-operators
 spec:
-  priority: 1000 <2>
+  priority: 1000
   source:
     image:
-      pollIntervalMinutes: 10 <3>
-      ref: registry.redhat.io/redhat/community-operator-index:v{product-version} <4>
+      pollIntervalMinutes: 10
+      ref: registry.redhat.io/redhat/community-operator-index:v{product-version}
     type: Image
 ----
-<1> The catalog is automatically labeled with the value of the `metadata.name` field when it is applied to the cluster. For more information about labels and catalog selection, see "Catalog content resolution".
-<2> Optional: Specify the priority of the catalog in relation to the other catalogs on the cluster. For more information, see "Catalog selection by priority".
-<3> Specify the interval in minutes for polling the remote registry for newer image digests. To disable polling, do not set the field.
-<4> Specify the catalog image in the `spec.source.image.ref` field.
+where:
+
+`metadata.name`:: Specifies the catalog name. The catalog is automatically labeled with the value of the `metadata.name` field when it is applied to the cluster. For more information about labels and catalog selection, see "Catalog content resolution".
+`priority`:: Optional: Specifies the priority of the catalog in relation to the other catalogs on the cluster. For more information, see "Catalog selection by priority".
+`pollIntervalMinutes`:: Specifies the interval in minutes for polling the remote registry for newer image digests. To disable polling, do not set the field.
+`spec.source.image.ref`:: Specifies the catalog image.
 
 . Add the catalog to your cluster by running the following command:
 +
@@ -99,12 +101,12 @@ Spec:
       Poll Interval Minutes:  10
       Ref:                    registry.redhat.io/redhat/community-operator-index:v{product-version}
     Type:                     Image
-Status: <1>
+Status:
   Conditions:
     Last Transition Time:  2025-02-18T20:29:00Z
     Message:               Successfully unpacked and stored content from resolved source
     Observed Generation:   1
-    Reason:                Succeeded <2>
+    Reason:                Succeeded
     Status:                True
     Type:                  Progressing
     Last Transition Time:  2025-02-18T20:29:00Z
@@ -116,12 +118,15 @@ Status: <1>
   Last Unpacked:           2025-02-18T20:28:59Z
   Resolved Source:
     Image:
-      Ref:  registry.redhat.io/redhat/community-operator-index@sha256:11627ea6fdd06b8092df815076e03cae9b7cede8b353c0b461328842d02896c5 <3>
+      Ref:  registry.redhat.io/redhat/community-operator-index@sha256:11627ea6fdd06b8092df815076e03cae9b7cede8b353c0b461328842d02896c5
     Type:   Image
   Urls:
     Base:  https://catalogd-service.openshift-catalogd.svc/catalogs/my-redhat-operators
 Events:    <none>
 ----
-<1> Describes the status of the catalog.
-<2> Displays the reason the catalog is in the current state.
-<3> Displays the image reference of the catalog.
++
+* `Status` describes the status of the catalog.
++
+* `Reason` displays the reason the catalog is in the current state.
++
+* `Resolved Source.Image.Ref` displays the image reference of the catalog.
diff --git a/modules/olmv1-catalog-selection-by-name.adoc b/modules/olmv1-catalog-selection-by-name.adoc
@@ -16,10 +16,10 @@ kind: ClusterExtension
 metadata:
   name: <example_extension>
   labels:
-    olm.operatorframework.io/metadata.name: <example_extension> <1>
+    olm.operatorframework.io/metadata.name: <example_extension>
 ...
 ----
-<1> A label derived from the `metadata.name` field and automatically added when the catalog is applied.
+The `olm.operatorframework.io/metadata.name` label is derived from the `metadata.name` field and automatically added when the catalog is applied.
 
 The following example resolves the `<example_extension>-operator` package from a catalog with the `openshift-redhat-operators` label:
 

diff --git a/modules/olmv1-creating-a-cluster-role.adoc b/modules/olmv1-creating-a-cluster-role.adoc
@@ -66,9 +66,9 @@ rules:
   - update
   # Scoped to the name of the ClusterExtension
   resourceNames:
-  - <metadata_name> # <1>
+  - <metadata_name>
 ----
-<1> Specifies the value from the `metadata.name` field from the custom resource (CR) of the extension.
+The `<metadata_name>` specifies the value from the `metadata.name` field from the custom resource (CR) of the extension.
 
 . Search for the `clusterrole` and `clusterrolebindings` values in the `rules.resources` field in the extension's CSV file.
 
@@ -89,7 +89,7 @@ rules:
   resources:
   - clusterroles
   verbs:
-  - create # <1>
+  - create
   - list
   - watch
 - apiGroups:
@@ -101,7 +101,7 @@ rules:
   - update
   - patch
   - delete
-  resourceNames: # <2>
+  resourceNames:
   - "*"
 - apiGroups:
   - rbac.authorization.k8s.io
@@ -124,8 +124,10 @@ rules:
   - "*"
 # ...
 ----
-<1> You cannot scope `create`, `list`, and `watch` permissions to specific resource names (the `resourceNames` field). You must scope these permissions to their resources (the `resources` field).
-<2> Some resource names are generated by using the following format: `<package_name>.<hash>`. After you install the extension, look up the resource names for the cluster roles and cluster role bindings for the controller of the extension. Replace the wildcard characters in this example with the generated names and follow the principle of least privilege.
+where:
+
+`create`, `list`, and `watch`:: Specifies permissions that cannot be scoped to specific resource names (the `resourceNames` field). You must scope these permissions to their resources (the `resources` field).
+`resourceNames`:: Specifies some resource names that are generated by using the following format: `<package_name>.<hash>`. After you install the extension, look up the resource names for the cluster roles and cluster role bindings for the controller of the extension. Replace the wildcard characters in this example with the generated names and follow the principle of least privilege.
 
 . Search for the `customresourcedefinitions` value in the `rules.resources` field in the extension's CSV file.
 

diff --git a/modules/olmv1-forcing-an-update-or-rollback.adoc b/modules/olmv1-forcing-an-update-or-rollback.adoc
@@ -32,23 +32,25 @@ apiVersion: olm.operatorframework.io/v1
   metadata:
     name: <clusterextension_name>
   spec:
-    namespace: <installed_namespace> <1>
+    namespace: <installed_namespace>
     serviceAccount:
-      name: <service_account_installer_name> <2>
+      name: <service_account_installer_name>
     source:
       sourceType: Catalog
       catalog:
         packageName: <package_name>
         channels:
-          - <channel_name> <3>
-        version: <version_or_version_range> <4>
-        upgradeConstraintPolicy: SelfCertified <5>
+          - <channel_name>
+        version: <version_or_version_range>
+        upgradeConstraintPolicy: SelfCertified
 ----
-<1> Specifies the namespace where you want the bundle installed, such as `pipelines` or `my-extension`. Extensions are still cluster-scoped and might contain resources that are installed in different namespaces.
-<2> Specifies the name of the service account you created to install, update, and manage your extension.
-<3> Optional: Specifies channel names as an array, such as `pipelines-1.14` or `latest`.
-<4> Optional: Specifies the version or version range, such as `1.14.0`, `1.14.x`, or `>=1.16`, of the package you want to install or update. For more information, see "Example custom resources (CRs) that specify a target version" and "Support for version ranges".
-<5> Optional: Specifies the upgrade constraint policy. To force an update or rollback, set the field to `SelfCertified`. If unspecified, the default setting is `CatalogProvided`. The `CatalogProvided` setting only updates if the new version satisfies the upgrade constraints set by the package author.
+where:
+
+`namespace`:: Specifies the namespace where you want the bundle installed, such as `pipelines` or `my-extension`. Extensions are still cluster-scoped and might contain resources that are installed in different namespaces.
+`serviceAccount.name`:: Specifies the name of the service account you created to install, update, and manage your extension.
+`channels`:: Optional: Specifies channel names as an array, such as `pipelines-1.14` or `latest`.
+`version`:: Optional: Specifies the version or version range, such as `1.14.0`, `1.14.x`, or `>=1.16`, of the package you want to install or update. For more information, see "Example custom resources (CRs) that specify a target version" and "Support for version ranges".
+`upgradeConstraintPolicy`:: Optional: Specifies the upgrade constraint policy. To force an update or rollback, set the field to `SelfCertified`. If unspecified, the default setting is `CatalogProvided`. The `CatalogProvided` setting only updates if the new version satisfies the upgrade constraints set by the package author.
 
 . Apply the changes to your Operator or extensions CR by running the following command:
 +

diff --git a/modules/olmv1-granting-user-access-binding.adoc b/modules/olmv1-granting-user-access-binding.adoc
@@ -75,9 +75,9 @@ rules:
   resources:
   - <cluster_extension_custom_resources>
   verbs:
-  - '*' <1>
+  - '*'
 ----
-<1> Setting a wildcard (`*`) in `verbs` allows all actions on the specified resources.
+Setting a wildcard (`*`) in `verbs` allows all actions on the specified resources.
 
 .. Create the cluster roles by running the following command for any YAML files you created:
 +

diff --git a/modules/olmv1-installing-an-operator.adoc b/modules/olmv1-installing-an-operator.adoc
@@ -26,23 +26,25 @@ apiVersion: olm.operatorframework.io/v1
   metadata:
     name: <clusterextension_name>
   spec:
-    namespace: <installed_namespace> <1>
+    namespace: <installed_namespace>
     serviceAccount:
-      name: <service_account_installer_name> <2>
+      name: <service_account_installer_name>
     source:
       sourceType: Catalog
       catalog:
         packageName: <package_name>
         channels:
-          - <channel_name> <3>
-        version: <version_or_version_range> <4>
-        upgradeConstraintPolicy: CatalogProvided <5>
+          - <channel_name>
+        version: <version_or_version_range>
+        upgradeConstraintPolicy: CatalogProvided
 ----
-<1> Specifies the namespace where you want the bundle installed, such as `pipelines` or `my-extension`. Extensions are still cluster-scoped and might contain resources that are installed in different namespaces.
-<2> Specifies the name of the service account you created to install, update, and manage your extension.
-<3> Optional: Specifies channel names as an array, such as `pipelines-1.14` or `latest`.
-<4> Optional: Specifies the version or version range, such as `1.14.0`, `1.14.x`, or `>=1.16`, of the package you want to install or update. For more information, see "Example custom resources (CRs) that specify a target version" and "Support for version ranges".
-<5> Optional: Specifies the upgrade constraint policy. If unspecified, the default setting is `CatalogProvided`. The `CatalogProvided` setting only updates if the new version satisfies the upgrade constraints set by the package author. To force an update or rollback, set the field to `SelfCertified`. For more information, see "Forcing an update or rollback".
+where:
+
+`<installed_namespace>`:: Specifies the namespace where you want the bundle installed, such as `pipelines` or `my-extension`. Extensions are still cluster-scoped and might contain resources that are installed in different namespaces.
+`<service_account_installer_name>`:: Specifies the name of the service account you created to install, update, and manage your extension.
+`<channel_name>`:: Optional: Specifies channel names as an array, such as `pipelines-1.14` or `latest`.
+`<version_or_version_range>`:: Optional: Specifies the version or version range, such as `1.14.0`, `1.14.x`, or `>=1.16`, of the package you want to install or update. For more information, see "Example custom resources (CRs) that specify a target version" and "Support for version ranges".
+`CatalogProvided`:: Optional: Specifies the upgrade constraint policy. If unspecified, the default setting is `CatalogProvided`. The `CatalogProvided` setting only updates if the new version satisfies the upgrade constraints set by the package author. To force an update or rollback, set the field to `SelfCertified`. For more information, see "Forcing an update or rollback".
 
 .Example `pipelines-operator.yaml` CR
 [source,yaml]