openshift · johnwilkins · Nov 21, 2025
diff --git a/_attributes/common-attributes.adoc b/_attributes/common-attributes.adoc
@@ -2,6 +2,8 @@
 // {product-title} and {product-version} are parsed when AsciiBinder queries the _distro_map.yml file in relation to the base branch of a pull request.
 // See https://github.com/openshift/openshift-docs/blob/main/contributing_to_docs/doc_guidelines.adoc#product-name-and-version for more information on this topic.
 // Other common attributes are defined in the following lines:
+:_mod-docs-content-type: SNIPPET
+
 :data-uri:
 :icons:
 :experimental:

diff --git a/modules/op-additional-options-webhooks.adoc b/modules/op-additional-options-webhooks.adoc
@@ -5,17 +5,19 @@
 [id="op-additional-options-webhooks_{context}"]
 = Setting additional options for webhooks
 
-Optionally, you can set the `failurePolicy`, `timeoutSeconds`, or `sideEffects` options for the webhooks created by several controllers in {pipelines-shortname}. For more information about these options, see the link:https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/[Kubernetes documentation].
+[role="_abstract"]
+You can configure advanced webhook options, such as failure policies and timeouts, for {pipelines-shortname} controllers to improve stability and error handling. These settings are applied by using the `TektonConfig` custom resource (CR) and allow you to customize how admission controllers interact with the Kubernetes API server.
 
 .Prerequisites
 
 * You installed the `oc` command-line utility.
 
-* You are logged into your {OCP} cluster with administrator rights for the namespace in which {pipelines-shortname} is installed, typically the `openshift-pipelines` namespace.
+* You have logged in to your {OCP} cluster with administrator rights for the namespace in which {pipelines-shortname} is installed, typically the `openshift-pipelines` namespace.
 
 .Procedure
 
 . View the list of webhooks that the {pipelines-shortname} controllers created. There are two types of webhooks: mutating webhooks and validating webhooks.
+
 .. To view the list of mutating webhooks, enter the following command:
 +
 [source,terminal]
@@ -24,7 +26,6 @@ $ oc get MutatingWebhookConfiguration
 ----
 +
 .Example output
-+
 [source,terminal]
 ----
 NAME                             WEBHOOKS   AGE
@@ -34,6 +35,7 @@ webhook.operator.tekton.dev      1          4m22s
 webhook.pipeline.tekton.dev      1          4m20s
 webhook.triggers.tekton.dev      1          3m50s
 ----
+
 .. To view the list of validating webhooks, enter the following command:
 +
 [source,terminal]
@@ -42,7 +44,6 @@ $ oc get ValidatingWebhookConfiguration
 ----
 +
 .Example output
-+
 [source,terminal]
 ----
 NAME                                                 WEBHOOKS   AGE

diff --git a/modules/op-annotations-for-automatic-pruning-taskruns-pipelineruns.adoc b/modules/op-annotations-for-automatic-pruning-taskruns-pipelineruns.adoc
@@ -6,7 +6,8 @@
 [id="annotations-for-automatic-pruning-taskruns-pipelineruns_{context}"]
 = Annotations for automatically pruning task runs and pipeline runs
 
-To modify the configuration for automatic pruning of task runs and pipeline runs in a namespace, you can set annotations in the namespace.
+[role="_abstract"]
+You can customize the pruning behavior for specific namespaces by applying annotations to the `Namespace` resource. These annotations allow you to override global pruning settings, such as retention limits and schedules, for individual projects.
 
 The following namespace annotations have the same meanings as the corresponding keys in the `TektonConfig` custom resource:
 

diff --git a/modules/op-automatic-pruning-taskrun-pipelinerun.adoc b/modules/op-automatic-pruning-taskrun-pipelinerun.adoc
@@ -5,7 +5,8 @@
 [id="op-automatic-pruning-taskrun-pipelinerun_{context}"]
 = Automatic pruning of task runs and pipeline runs
 
-Stale `TaskRun` and `PipelineRun` objects and their executed instances occupy physical resources that can be used for active runs. For optimal utilization of these resources, {pipelines-title} provides a pruner component that automatically removes unused objects and their instances in various namespaces.
+[role="_abstract"]
+You can automatically prune stale `TaskRun` and `PipelineRun` resources to free up cluster resources and maintain optimal performance. {pipelines-title} provides a configurable pruner component that removes unused objects based on your defined policies.
 
 [NOTE]
 ====

diff --git a/modules/op-changing-default-service-account.adoc b/modules/op-changing-default-service-account.adoc
@@ -1,13 +1,13 @@
 // This module is included in the following assemblies:
 // * install_config/customizing-configurations-in-the-tektonconfig-cr.adoc
 
-:_mod-docs-content-type: CONCEPT
+:_mod-docs-content-type: PROCEDURE
 [id="op-changing-default-service-account_{context}"]
 = Changing the default service account for {pipelines-shortname}
 
-You can change the default service account for {pipelines-shortname} by editing the `default-service-account` field in the `.spec.pipeline` and `.spec.trigger` specifications. The default service account name is `pipeline`.
+[role="_abstract"]
+You can change the default service account used by {pipelines-shortname} for task and pipeline runs to meet your security or operational requirements. By editing the `TektonConfig` custom resource (CR), you can specify a different service account for pipelines and triggers.
 
-.Example
 [source,yaml]
 ----
 apiVersion: operator.tekton.dev/v1alpha1

diff --git a/modules/op-configuration-rbac-trusted-ca-flags.adoc b/modules/op-configuration-rbac-trusted-ca-flags.adoc
@@ -5,7 +5,8 @@
 [id="op-configuration-rbac-trusted-ca-flags.adoc_{context}"]
 = Configuration of RBAC and Trusted CA flags
 
-The {pipelines-title} Operator provides independent control over RBAC resource creation and Trusted CA bundle config map through two separate flags, `createRbacResource` and `createCABundleConfigMaps`.
+[role="_abstract"]
+You can independently control the creation of RBAC resources and Trusted CA bundle config maps to customize your {pipelines-shortname} installation. The `TektonConfig` custom resource (CR) provides specific flags, `createRbacResource` and `createCABundleConfigMaps`, to manage these components separately.
 
 [cols="1,3,1", options="header"]
 |===
@@ -30,12 +31,13 @@ spec:
   profile: all
   targetNamespace: openshift-pipelines
   params:
-    - name: createRbacResource # <1>
+    - name: createRbacResource
       value: "true"
-    - name: createCABundleConfigMaps # <2>
+    - name: createCABundleConfigMaps
       value: "true"
     - name: legacyPipelineRbac
       value: "true"
 ----
-<1> Specifies RBAC resource creation.
-<2> Specifies Trusted CA bundle config map creation.
+
+`params[0].name`:: Specifies RBAC resource creation.
+`params[1].name`:: Specifies Trusted CA bundle config map creation.
diff --git a/modules/op-configuring-pipeline-resolvers.adoc b/modules/op-configuring-pipeline-resolvers.adoc
@@ -5,7 +5,8 @@
 [id="op-configuring-pipeline-resolvers_{context}"]
 = Configuring pipeline resolvers
 
-You can configure pipeline resolvers in the `TektonConfig` custom resource (CR). You can enable or disable these pipeline resolvers:
+[role="_abstract"]
+You can enable or disable specific pipeline resolvers, such as git, cluster, bundle, and hub resolvers, to control how your pipelines fetch resources. These settings are managed within the `TektonConfig` custom resource (CR), where you can also provide resolver-specific configurations.
 
 * `enable-bundles-resolver`
 * `enable-cluster-resolver`

diff --git a/modules/op-configuring-pipelines-control-plane.adoc b/modules/op-configuring-pipelines-control-plane.adoc
@@ -5,7 +5,8 @@
 [id="op-configuring-pipelines-control-plane_{context}"]
 = Configuring the {pipelines-title} control plane
 
-You can customize the {pipelines-shortname} control plane by editing the configuration fields in the `TektonConfig` custom resource (CR). The {pipelines-title} Operator automatically adds the configuration fields with their default values so that you can use the {pipelines-shortname} control plane.
+[role="_abstract"]
+You can configure the {pipelines-shortname} control plane to suit your operational needs by editing the `TektonConfig` custom resource (CR). Customize settings such as metrics collection, sidecar injection, and service account defaults directly through the {OCP} web console as needed.
 
 .Procedure
 
@@ -21,7 +22,6 @@ You can customize the {pipelines-shortname} control plane by editing the configu
 
 . Edit the `TektonConfig` YAML file based on your requirements.
 +
-.Example of `TektonConfig` CR with default values
 [source,yaml]
 ----
 apiVersion: operator.tekton.dev/v1alpha1

diff --git a/modules/op-default-pruner-configuration.adoc b/modules/op-default-pruner-configuration.adoc
@@ -6,7 +6,8 @@
 [id="default-pruner-configuration_{context}"]
 = Configuring the pruner
 
-You can use the `TektonConfig` custom resource to configure periodic pruning of resources associated with pipeline runs and task runs.
+[role="_abstract"]
+You can configure the default pruner to automatically remove old `TaskRun` and `PipelineRun` resources based on a schedule or resource count. By modifying the `TektonConfig` custom resource (CR), you can set retention limits and pruning intervals to manage resource usage.
 
 The following example corresponds to the default configuration:
 

diff --git a/modules/op-deleting-the-pipelines-custom-resources.adoc b/modules/op-deleting-the-pipelines-custom-resources.adoc
@@ -3,9 +3,10 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="op-deleting-the-pipelines-custom-resources_{context}"]
-= Deleting the {pipelines-shortname} Custom Resources
+= Deleting the {pipelines-shortname} custom resources
 
-If the Custom Resources (CRs) for the optional components, `TektonHub` and `TektonResult`, exist, delete these CRs. Then delete the `TektonConfig` CR.
+[role="_abstract"]
+You can remove the {pipelines-shortname} custom resources (CRs) to clean up the configuration before uninstalling the Operator. This involves deleting optional components such as `TektonHub` and `TektonResult`, followed by the main `TektonConfig` CR.
 
 .Procedure
 . In the *Administrator* perspective of the web console, navigate to *Administration* -> *CustomResourceDefinitions*.

diff --git a/modules/op-deleting-the-tekton-dev-crds.adoc b/modules/op-deleting-the-tekton-dev-crds.adoc
@@ -3,11 +3,15 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="op-deleting-the-tekton-dev-crds_{context}"]
-= Deleting the Custom Resource Definitions of the `operator.tekton.dev` group
+= Deleting the custom resource definitions of the `operator.tekton.dev` group
 
-Delete the Custom Resource Definitions (CRDs) of the `operator.tekton.dev` group. These CRDs are created by default during the installation of the {pipelines-title} Operator.
+[role="_abstract"]
+You can delete the `operator.tekton.dev` custom resource definitions (CRDs) to fully remove all {pipelines-shortname} traces from your cluster. This step ensures that no residual definitions remain after the Operator uninstallation.
+
+Delete the `CustomResourceDefinitions` of the `operator.tekton.dev` group. The {pipelines-title} Operator creates these CRDs by default during installation.
 
 .Procedure
+
 . In the *Administrator* perspective of the web console, navigate to *Administration* -> *CustomResourceDefinitions*.
 
 . Type `operator.tekton.dev` in the *Filter by name* box to search for the CRDs in the `operator.tekton.dev` group.

diff --git a/modules/op-disabling-automatic-creation-of-rbac-resources.adoc b/modules/op-disabling-automatic-creation-of-rbac-resources.adoc
@@ -1,13 +1,14 @@
 // This module is included in the following assemblies:
 // * install_config/customizing-configurations-in-the-tektonconfig-cr.adoc
 
-:_mod-docs-content-type: CONCEPT
+:_mod-docs-content-type: PROCEDURE
 [id="op-disabling-automatic-creation-of-rbac-resources_{context}"]
 = Disabling the automatic creation of RBAC resources
 
-The default installation of the {pipelines-title} Operator creates multiple role-based access control (RBAC) resources for all namespaces in the cluster, except the namespaces matching the `^(openshift|kube)-*` regular expression pattern. Among these RBAC resources, the `pipelines-scc-rolebinding` security context constraint (SCC) role binding resource is a potential security issue, because the associated `pipelines-scc` SCC has the `RunAsAny` privilege. 
+[role="_abstract"]
+You can disable the automatic creation of cluster-wide RBAC resources by using the {pipelines-title} Operator to improve security and control over permissions. This is done by setting the `createRbacResource` parameter to `false` in the `TektonConfig` custom resource (CR), preventing the creation of potentially privileged role bindings.
 
-To disable the automatic creation of cluster-wide RBAC resources after the {pipelines-title} Operator is installed, cluster administrators can set the `createRbacResource` parameter to `false` in the cluster-level `TektonConfig` custom resource (CR).
+The default installation of the {pipelines-title} Operator creates multiple role-based access control (RBAC) resources for all namespaces in the cluster, except the namespaces matching the `^(openshift|kube)-*` regular expression pattern. Among these RBAC resources, the `pipelines-scc-rolebinding` security context constraint (SCC) role binding resource is a potential security issue, because the associated `pipelines-scc` SCC has the `RunAsAny` privilege.
 
 .Procedure
 
@@ -19,8 +20,7 @@ $ oc edit TektonConfig config
 ----
 
 . In the `TektonConfig` CR, set the `createRbacResource` param value to `false`:
-
-.Example `TektonConfig` CR
++
 [source,yaml]
 ----
 apiVersion: operator.tekton.dev/v1alpha1

diff --git a/modules/op-disabling-inline-spec.adoc b/modules/op-disabling-inline-spec.adoc
@@ -5,6 +5,9 @@
 [id="op-disabling-inline-spec_{context}"]
 = Disabling inline specification of pipelines and tasks
 
+[role="_abstract"]
+You can disable the inline specification of tasks and pipelines to enforce the use of referenced resources and improve security. By configuring the `disable-inline-spec` field in the `TektonConfig` custom resource (CR), you can restrict the use of embedded specs in `Pipeline`, `PipelineRun`, and `TaskRun` resources.
+
 By default, {pipelines-shortname} supports inline specification of pipelines and tasks in the following cases:
 
 * You can create a `Pipeline` CR that includes one or more task specifications, as in the following example:

diff --git a/modules/op-disabling-pipeline-templates.adoc b/modules/op-disabling-pipeline-templates.adoc
@@ -5,9 +5,10 @@
 [id="op-disabling-pipeline-templates_{context}"]
 = Disabling resolver tasks and pipeline templates
 
-By default, the `TektonAddon` custom resource (CR) installs `resolverTasks` and `pipelineTemplates` resources along with {pipelines-shortname} on the cluster.
+[role="_abstract"]
+You can disable the automatic installation of resolver tasks and pipeline templates to customize your cluster's initial state. By modifying the `TektonConfig` custom resource (CR), you can prevent these default resources from being deployed if they are not required for your environment.
 
-You can disable the installation of the resolver tasks and pipeline templates by setting the parameter value to `false` in the `.spec.addon` specification.
+By default, the `TektonAddon` custom resource (CR) installs `resolverTasks` and `pipelineTemplates` resources along with {pipelines-shortname} on the cluster.
 
 .Procedure
 

diff --git a/modules/op-disabling-pipeline-triggers.adoc b/modules/op-disabling-pipeline-triggers.adoc
@@ -5,7 +5,8 @@
 [id="op-disabling-pipeline-triggers_{context}"]
 = Disabling the installation of {tekton-triggers}
 
-You can disable the automatic istallation of {tekton-triggers} when deploying {pipelines-shortname} through the Operator, to provide more flexibility for environments where triggers are managed separately. To disable the istallation of {tekton-triggers}, set the `disabled` parameter to `true` in the `spec.trigger` specification of your `TektonConfig` custom resource (CR):
+[role="_abstract"]
+You can disable the automatic installation of {tekton-triggers} during the {pipelines-shortname} deployment to manage triggers separately or exclude them from your environment. This is achieved by setting the `disabled` parameter to `true` in the `TektonConfig` custom resource (CR).
 
 [source, yaml]
 ----

diff --git a/modules/op-disabling-the-integretion-of-tekton-hub.adoc b/modules/op-disabling-the-integretion-of-tekton-hub.adoc
@@ -5,7 +5,8 @@
 [id="op-disabling-the-integretion-of-tekton-hub_{context}"]
 = Disabling the integration of {tekton-hub}
 
-You can disable the integration of {tekton-hub} in the web console *Developer* perspective by setting the `enable-devconsole-integration` parameter to `false` in the `TektonConfig` custom resource (CR).
+[role="_abstract"]
+You can disable the {tekton-hub} integration in the {OCP} web console Developer perspective to customize the user experience. This setting is controlled by the `enable-devconsole-integration` parameter in the `TektonConfig` custom resource (CR).
 
 .Example of disabling {tekton-hub}
 

diff --git a/modules/op-disabling-the-service-monitor.adoc b/modules/op-disabling-the-service-monitor.adoc
@@ -5,7 +5,8 @@
 [id="op-disabling-the-service-monitor_{context}"]
 = Disabling the service monitor
 
-You can disable the service monitor, which is part of {pipelines-shortname}, to expose the telemetry data. To disable the service monitor, set the `enableMetrics` parameter to `false` in the `.spec.pipeline` specification of the `TektonConfig` custom resource (CR):
+[role="_abstract"]
+You can disable the service monitor in {pipelines-shortname} if you do not need to expose telemetry data or want to reduce resource consumption. This configuration is managed by setting the `enableMetrics` parameter to `false` in the `TektonConfig` custom resource (CR).
 
 .Example
 [source,yaml]

diff --git a/modules/op-event-pruner-configuration.adoc b/modules/op-event-pruner-configuration.adoc
@@ -8,7 +8,8 @@
 :FeatureName: The event-based pruner
 include::snippets/technology-preview.adoc[]
 
-You can use the event-based `tektonpruner` controller to automatically delete completed resources, such as `PipelineRuns` and `TaskRuns`, based on configurable policies. Unlike the default job-based pruner, the event-based pruner listens for resource events and prunes resources in near real time.
+[role="_abstract"]
+You can enable the event-based pruner to delete completed `PipelineRun` and `TaskRun` resources in near real-time. By configuring the `tektonpruner` controller in the `TektonConfig` custom resource (CR), you can replace the default scheduled pruner with an event-driven approach for more immediate resource cleanup.
 
 [IMPORTANT]
 ====

diff --git a/modules/op-event-pruner-observability.adoc b/modules/op-event-pruner-observability.adoc
@@ -8,9 +8,10 @@
 :FeatureName: The event-based pruner
 include::snippets/technology-preview.adoc[]
 
-The event-based pruner exposes detailed metrics through the `tekton-pruner-controller` controller `Service` definition on port `9090` in OpenTelemetry format for monitoring, troubleshooting, and capacity planning.
+[role="_abstract"]
+You can monitor the performance and health of the event-based pruner using the metrics exposed by the `tekton-pruner-controller`. These metrics, available in OpenTelemetry format, provide insights into resource processing, error rates, and reconciliation times for effective troubleshooting and capacity planning.
 
-Following are categories of the metrics exposed:
+The following bullets are categories of the metrics exposed:
 
 * Resource processing
 * Performance timing

diff --git a/modules/op-event-pruner-reference.adoc b/modules/op-event-pruner-reference.adoc
@@ -8,7 +8,8 @@
 :FeatureName: The event-based pruner
 include::snippets/technology-preview.adoc[]
 
-You can configure the pruning behavior of the event-based pruner by modifying your `TektonConfig` custom resource (CR).
+[role="_abstract"]
+You can fine-tune the event-based pruner by adjusting settings in the `TektonConfig` custom resource (CR). This reference details the available configuration options, including history limits, time-to-live (TTL) values, and namespace-specific policies.
 
 The following is an example of the `TektonConfig` CR with the default configuration that uses global pruning rules:
 
@@ -32,11 +33,12 @@ spec:
     options: {}
   # ...
 ----
-* `failedHistoryLimit`: The amount of retained failed runs.
-* `historyLimit`: The amount of runs to retain. Pruner uses this setting if status-specific limits are not defined.
-* `namespaces`: Definition of per-namespace pruning policies, when you set `enforcedConfigLevel` to `namespace`.
-* `successfulHistoryLimit`: The amount of retained successful runs. 
-* `ttlSecondsAfterFinished`: Time in seconds after completion, after which the pruner deletes resources.
+
+`failedHistoryLimit`:: The amount of retained failed runs.
+`historyLimit`:: The amount of runs to retain. Pruner uses this setting if status-specific limits are not defined.
+`namespaces`:: Definition of per-namespace pruning policies, when you set `enforcedConfigLevel` to `namespace`.
+`successfulHistoryLimit`:: The amount of retained successful runs. 
+`ttlSecondsAfterFinished`:: Time in seconds after completion, after which the pruner deletes resources.
 
 You can define pruning rules for individual namespaces by setting `enforcedConfigLevel` to `namespace` and configuring policies under the `namespaces` section. In the following example, a 60 second time to live (TTL) is applied to resources in the `dev-project` namespace: