OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history
×

Customizing configurations in the TektonConfig custom resource

In Red Hat OpenShift Pipelines, you can customize the following configurations by using the TektonConfig custom resource (CR):

  • Configuring the Red Hat OpenShift Pipelines control plane

  • Changing the default service account

  • Disabling the service monitor

  • Disabling cluster tasks and pipeline templates

  • Disabling the integration of Tekton Hub

  • Disabling the automatic creation of RBAC resources

  • Pruning of task runs and pipeline runs

Prerequisites

  • You have installed the Red Hat OpenShift Pipelines Operator.

Configuring the Red Hat OpenShift Pipelines control plane

You can customize the OpenShift Pipelines control plane by editing the configuration fields in the TektonConfig custom resource (CR). The Red Hat OpenShift Pipelines Operator automatically adds the configuration fields with their default values so that you can use the OpenShift Pipelines control plane.

Procedure

  1. In the Administrator perspective of the web console, navigate to Administration → CustomResourceDefinitions.

  2. Use the Search by name box to search for the tektonconfigs.operator.tekton.dev custom resource definition (CRD). Click TektonConfig to see the CRD details page.

  3. Click the Instances tab.

  4. Click the config instance to see the TektonConfig CR details.

  5. Click the YAML tab.

  6. Edit the TektonConfig YAML file based on your requirements.

    Example of TektonConfig CR with default values
    apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pipeline:
    running-in-environment-with-injected-sidecars: true
    metrics.taskrun.duration-type: histogram
    metrics.pipelinerun.duration-type: histogram
    await-sidecar-readiness: true
    params:
      - name: enableMetrics
        value: 'true'
    default-service-account: pipeline
    require-git-ssh-secret-known-hosts: false
    enable-tekton-oci-bundles: false
    metrics.taskrun.level: task
    metrics.pipelinerun.level: pipeline
    embedded-status: both
    enable-api-fields: stable
    enable-provenance-in-status: false
    enable-custom-tasks: true
    disable-creds-init: false
    disable-affinity-assistant: true

Modifiable fields with default values

The following list includes all modifiable fields with their default values in the TektonConfig CR:

  • running-in-environment-with-injected-sidecars (default: true): Set this field to false if pipelines run in a cluster that does not use injected sidecars, such as Istio. Setting it to false decreases the time a pipeline takes for a task run to start.

    For clusters that use injected sidecars, setting this field to false can lead to an unexpected behavior.

  • await-sidecar-readiness (default: true): Set this field to false to stop OpenShift Pipelines from waiting for TaskRun sidecar containers to run before it begins to operate. This allows tasks to be run in environments that do not support the downwardAPI volume type.

  • default-service-account (default: pipeline): This field contains the default service account name to use for the TaskRun and PipelineRun resources, if none is specified.

  • require-git-ssh-secret-known-hosts (default: false): Setting this field to true requires that any Git SSH secret must include the known_hosts field.

    • For more information about configuring Git SSH secrets, see Configuring SSH authentication for Git in the Additional resources section.

  • enable-tekton-oci-bundles (default: false): Set this field to true to enable the use of an experimental alpha feature named Tekton OCI bundle.

  • embedded-status (default: both): This field has three acceptable values:

    • full: Enables full embedding of Run and TaskRun statuses in the PipelineRun status

    • minimal: Populates the ChildReferences field with information, such as name, kind, and API version for each run and task run in the`PipelineRun` status

    • both: Applies both, full and minimal values

      The embedded-status field is deprecated and will be removed in a future release. In addition, the pipeline default embedded status will be changed to minimal.

  • enable-api-fields (default: stable): Setting this field determines which features are enabled. Acceptable value is stable, beta, or alpha.

    Red Hat OpenShift Pipelines does not support the alpha value.

  • enable-provenance-in-status (default: false): Set this field to true to enable populating the provenance field in TaskRun and PipelineRun statuses. The provenance field contains metadata about resources used in the task run and pipeline run, such as the source from where a remote task or pipeline definition was fetched.

  • enable-custom-tasks (default: true): Set this field to false to disable the use of custom tasks in pipelines.

  • disable-creds-init (default: false): Set this field to true to prevent OpenShift Pipelines from scanning attached service accounts and injecting any credentials into your steps.

  • disable-affinity-assistant (default: true): Set this field to false to enable affinity assistant for each TaskRun resource sharing a persistent volume claim workspace.

Metrics options

You can modify the default values of the following metrics fields in the TektonConfig CR:

  • metrics.taskrun.duration-type and metrics.pipelinerun.duration-type (default: histogram): Setting these fields determines the duration type for a task or pipeline run. Acceptable value is gauge or histogram.

  • metrics.taskrun.level (default: task): This field determines the level of the task run metrics. Acceptable value is taskrun, task, or namespace.

  • metrics.pipelinerun.level (default: pipeline): This field determines the level of the pipeline run metrics. Acceptable value is pipelinerun, pipeline, or namespace.

Optional configuration fields

The following fields do not have a default value, and are considered only if you configure them. By default, the Operator does not add and configure these fields in the TektonConfig custom resource (CR).

  • default-timeout-minutes: This field sets the default timeout for the TaskRun and PipelineRun resources, if none is specified when creating them. If a task run or pipeline run takes more time than the set number of minutes for its execution, then the task run or pipeline run is timed out and cancelled. For example, default-timeout-minutes: 60 sets 60 minutes as default.

  • default-managed-by-label-value: This field contains the default value given to the app.kubernetes.io/managed-by label that is applied to all TaskRun pods, if none is specified. For example, default-managed-by-label-value: tekton-pipelines.

  • default-pod-template: This field sets the default TaskRun and PipelineRun pod templates, if none is specified.

  • default-cloud-events-sink: This field sets the default CloudEvents sink that is used for the TaskRun and PipelineRun resources, if none is specified.

  • default-task-run-workspace-binding: This field contains the default workspace configuration for the workspaces that a Task resource declares, but a TaskRun resource does not explicitly declare.

  • default-affinity-assistant-pod-template: This field sets the default PipelineRun pod template that is used for affinity assistant pods, if none is specified.

  • default-max-matrix-combinations-count: This field contains the default maximum number of combinations generated from a matrix, if none is specified.

Changing the default service account for OpenShift Pipelines

You can change the default service account for OpenShift Pipelines by editing the default-service-account field in the .spec.pipeline and .spec.trigger specifications. The default service account name is pipeline.

Example
apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pipeline:
    default-service-account: pipeline
  trigger:
    default-service-account: pipeline
    enable-api-fields: stable

Disabling the service monitor

You can disable the service monitor, which is part of OpenShift Pipelines, 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):

Example
apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pipeline:
    params:
       - name: enableMetrics
         value: 'false'

Disabling cluster tasks and pipeline templates

By default, the TektonAddon custom resource (CR) installs clusterTasks and pipelineTemplates resources along with OpenShift Pipelines on the cluster.

You can disable installation of the clusterTasks and pipelineTemplates resources by setting the parameter value to false in the .spec.addon specification. In addition, you can disable the communityClusterTasks parameter.

Example
apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  addon:
    params:
      - name: clusterTasks
        value: 'false'
      - name: pipelineTemplates
        value: 'false'
      - name: communityClusterTasks
        value: 'true'

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).

Example of disabling Tekton Hub
apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  hub:
    params:
      - name: enable-devconsole-integration
        value: false

Disabling the automatic creation of RBAC resources

The default installation of the Red Hat OpenShift Pipelines 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.

To disable the automatic creation of cluster-wide RBAC resources after the Red Hat OpenShift Pipelines Operator is installed, cluster administrators can set the createRbacResource parameter to false in the cluster-level TektonConfig custom resource (CR).

Example TektonConfig CR
apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  params:
  - name: createRbacResource
    value: "false"
...

As a cluster administrator or an user with appropriate privileges, when you disable the automatic creation of RBAC resources for all namespaces, the default ClusterTask resource does not work. For the ClusterTask resource to function, you must create the RBAC resources manually for each intended namespace.

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, Red Hat OpenShift Pipelines provides annotations that cluster administrators can use to automatically prune the unused objects and their instances in various namespaces.

Configuring automatic pruning by specifying annotations affects the entire namespace. You cannot selectively auto-prune an individual task run or pipeline run in a namespace.

Annotations for automatically pruning task runs and pipeline runs

To automatically prune task runs and pipeline runs in a namespace, you can set the following annotations in the namespace:

  • operator.tekton.dev/prune.schedule: If the value of this annotation is different from the value specified in the TektonConfig custom resource definition, a new cron job in that namespace is created.

  • operator.tekton.dev/prune.skip: When set to true, the namespace for which it is configured is not pruned.

  • operator.tekton.dev/prune.resources: This annotation accepts a comma-separated list of resources. To prune a single resource such as a pipeline run, set this annotation to "pipelinerun". To prune multiple resources, such as task run and pipeline run, set this annotation to "taskrun, pipelinerun".

  • operator.tekton.dev/prune.keep: Use this annotation to retain a resource without pruning.

  • operator.tekton.dev/prune.keep-since: Use this annotation to retain resources based on their age. The value for this annotation must be equal to the age of the resource in minutes. For example, to retain resources which were created not more than five days ago, set keep-since to 7200.

    The keep and keep-since annotations are mutually exclusive. For any resource, you must configure only one of them.

  • operator.tekton.dev/prune.strategy: Set the value of this annotation to either keep or keep-since.

For example, consider the following annotations that retain all task runs and pipeline runs created in the last five days, and deletes the older resources:

Example of auto-pruning annotations
...
  annotations:
    operator.tekton.dev/prune.resources: "taskrun, pipelinerun"
    operator.tekton.dev/prune.keep-since: 7200
...

Additional resources