Tekton – Operator

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Tekton Config

TektonConfig custom resource is the top most component of the operator which allows user to install and customize all other components at a single place.

Operator provides support for installing and managing following operator components through TektonConfig:

Other than the above components depending on the platform operator also provides support for

On both Kubernetes and OpenShift
On Kubernetes
- TektonDashboard
- OpenShiftPipelinesAsCode (installed via spec.platforms.kubernetes.pipelinesAsCode; same CRD/kind as on OpenShift)
On OpenShift
- TektonAddon
- OpenShiftPipelinesAsCode
When Tekton Kueue multi-cluster is enabled with Hub role (both Kubernetes and OpenShift)
- TektonMulticlusterProxyAAE

The TektonConfig CR provides the following features

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  targetNamespace: tekton-pipelines
  targetNamespaceMetadata:
    labels: {}
    annotations: {}
  profile: all
  config:
    nodeSelector: <>
    tolerations: []
    priorityClassName: system-cluster-critical
  chain:
    disabled: false
  manualApproval:
    disabled: true
  pipeline:
    await-sidecar-readiness: true
    coschedule: workspaces
    disable-creds-init: false
    disable-home-env-overwrite: true
    disable-working-directory-overwrite: true
    disable-inline-spec: "pipeline,pipelinerun,taskrun"
    enable-api-fields: beta
    enable-bundles-resolver: true
    enable-cel-in-whenexpression: false
    enable-cluster-resolver: true
    enable-custom-tasks: true
    enable-git-resolver: true
    enable-hub-resolver: true
    enable-param-enum: false
    enable-provenance-in-status: true
    enable-step-actions: false
    enforce-nonfalsifiability: none
    keep-pod-on-cancel: false
    max-result-size: 4096
    metrics.count.enable-reason: false
    metrics.pipelinerun.duration-type: histogram
    metrics.pipelinerun.level: pipeline
    metrics.taskrun.duration-type: histogram
    metrics.taskrun.level: task
    # Tracing configuration (optional)
    # traces.enabled: true
    # traces.endpoint: "http://jaeger-collector.jaeger.svc.cluster.local:4318/v1/traces"
    # traces.credentialsSecret: ""
    require-git-ssh-secret-known-hosts: false
    results-from: termination-message
    running-in-environment-with-injected-sidecars: true
    send-cloudevents-for-runs: false
    set-security-context: false
    trusted-resources-verification-no-match-policy: ignore
    performance:
      disable-ha: false
      buckets: 1
      replicas: 1
      threads-per-controller: 2
      kube-api-qps: 5.0
      kube-api-burst: 10
    options:
      disabled: false
      configMaps: {}
      deployments: {}
      webhookConfigurationOptions: {}
  pruner:
    disabled: false
    schedule: "0 8 * * *"
    resources:
      - taskrun
      - pipelinerun
    keep: 3
    # keep-since: 1440
    # NOTE: you can use either "keep" or "keep-since", not both
    prune-per-resource: true
  dashboard:
    readonly: true
    options:
      disabled: false
      configMaps: {}
      deployments: {}
      webhookConfigurationOptions: {}
  result:
    disabled: false
    is_external_db: false
    options: {}
    performance:
      disable-ha: false
      buckets: 1
      replicas: 1
  trigger:
    disabled: false
platforms:
    openshift:   # or `kubernetes:` on Kubernetes clusters
      pipelinesAsCode:
        additionalPACControllers:
          <controllerName>:
            enable: true
            configMapName:
            secretName:
            settings:
        enable: true
        settings:
          application-name: Pipelines as Code CI
          auto-configure-new-github-repo: "false"
          bitbucket-cloud-check-source-ip: "true"
          custom-console-name: ""
          custom-console-url: ""
          custom-console-url-pr-details: ""
          custom-console-url-pr-tasklog: ""
          error-detection-from-container-logs: "false"
          error-detection-max-number-of-lines: "50"
          error-detection-simple-regexp:
            ^(?P<filename>[^:]*):(?P<line>[0-9]+):(?P<column>[0-9]+):([
            ]*)?(?P<error>.*)
          error-log-snippet: "true"
          error-log-snippet-number-of-lines: "3"
          enable-cancel-in-progress-on-pull-requests: "false"
          enable-cancel-in-progress-on-push: "false"
          hub-catalog-name: tekton
          hub-url: https://api.hub.tekton.dev/v1
          require-ok-to-test-sha: "false"
          skip-push-event-for-pr-commits: "true"
          remote-tasks: "true"
          secret-auto-create: "true"
          secret-github-app-token-scoped: "true"
      options:
        disabled: false
        configMaps: {}
        deployments: {}
        webhookConfigurationOptions: {}

Look for the particular section to understand a particular field in the spec.

Target Namespace

This allows user to choose a namespace to install the Tekton Components such as pipelines, triggers.

By default, namespace would be tekton-pipelines for Kubernetes and openshift-pipelines for OpenShift.

Note: Namespace openshift-operators is not allowed in OpenShift as a targetNamespace.

Target Namespace Metadata

targetNamespaceMetadata allows user to add their custom labels and annotations to the target namespace via TektonConfig CR.

Profile

This allows user to choose which all components to install on the cluster. There are 3 profiles available:

all: This profile will install all components (TektonPipeline, TektonTrigger, TektonResult and TektonChain)
basic: This profile will install only TektonPipeline, TektonTrigger, TektonResult and TektonChain component
lite: This profile will install only TektonPipeline component

On Kubernetes, all profile will install TektonDashboard and on OpenShift TektonAddon will be installed.

Config

Config provides fields to configure deployments created by the Operator. This provides following fields:

User can pass the required fields and this would be passed to all Operator components which will get added in all deployments created by Operator.

Example:

config:
  nodeSelector:
    key: value
  tolerations:
    - key: "key1"
      operator: "Equal"
      value: "value1"
      effect: "NoSchedule"
  priorityClassName: system-node-critical

This is an Optional section.

NOTE: If spec.config.priorityClassName is used, then the required priorityClass is expected to be created by the user to get the Tekton resources pods in running state

Pipeline

Pipeline section allows user to customize the Tekton pipeline features. This allow user to customize the values in configmaps.

Refer to properties section in TektonPipeline for available options.

Some of the fields have default values, so operator will add them if user haven’t passed in CR. Other fields which doesn’t have default values won’t be passed unless user specify them in CR. User can find those here.

Example:

pipeline:
  disable-creds-init: false
  disable-home-env-overwrite: true
  disable-working-directory-overwrite: true
  enable-api-fields: stable
  enable-custom-tasks: false
  metrics.pipelinerun.duration-type: histogram
  metrics.pipelinerun.level: pipelinerun
  metrics.taskrun.duration-type: histogram
  metrics.taskrun.level: taskrun
  traces.enabled: true
  traces.endpoint: "http://jaeger-collector.jaeger.svc.cluster.local:4318/v1/traces"
  traces.credentialsSecret: "" # optional
  require-git-ssh-secret-known-hosts: false
  running-in-environment-with-injected-sidecars: true
  trusted-resources-verification-no-match-policy: ignore
  performance:
    replicas: 1
    disable-ha: false
    buckets: 1
    threads-per-controller: 2
    kube-api-qps: 5.0
    kube-api-burst: 10

Chain

Chain section allows user to customize the Tekton Chain features. This allows user to customize the values in configmaps

Refer to properties section in TektonChain for available options

Example:

chain:
  disabled: false # - `disabled` : if the value set as `true`, chains feature will be disabled (default: `false`)
  targetNamespace: tekton-pipelines
  generateSigningSecret: true # default value: false
  controllerEnvs:
    - name: MONGO_SERVER_URL # This is the only field supported at the moment which is optional and when added by user, it is added as env to Chains controller
      value: #value               # This can be provided same as env field of container
  artifacts.taskrun.format: in-toto
  artifacts.taskrun.storage: tekton,oci (comma separated values)
  artifacts.taskrun.signer: x509
  artifacts.oci.storage: oci (comma separated values)
  artifacts.oci.format: simplesigning
  artifacts.oci.signer: x509
  artifacts.pipelinerun.format: in-toto
  artifacts.pipelinerun.storage: tekton,oci (comma separated values)
  artifacts.pipelinerun.signer: x509
  storage.gcs.bucket: #value
  storage.oci.repository: #value
  storage.oci.repository.insecure: #value (boolean - true/false)
  storage.oci.encoding-format: #value (dsse or sigstore-bundle, default: dsse)
  storage.docdb.url: #value
  storage.grafeas.projectid: #value
  storage.grafeas.noteid: #value
  storage.grafeas.notehint: #value
  builder.id: #value
  signers.x509.fulcio.enabled: #value (boolean - true/false)
  signers.x509.fulcio.address: #value
  signers.x509.fulcio.issuer: #value
  signers.x509.fulcio.provider: #value
  signers.x509.identity.token.file: #value
  signers.x509.tuf.mirror.url: #value
  signers.kms.kmsref: #value
  signers.kms.kmsref.auth.address: #value
  signers.kms.kmsref.auth.token: #value
  signers.kms.kmsref.auth.oidc.path: #value
  signers.kms.kmsref.auth.oidc.role: #value
  signers.kms.kmsref.auth.spire.sock: #value
  signers.kms.kmsref.auth.spire.audience: #value
  transparency.enabled: #value (boolean - true/false)
  transparency.url: #value

Manual Approval Gate

Manual Approval Gate section allows user to enable or disable the ManualApprovalGate component through TektonConfig. When enabled, the operator installs and manages the ManualApprovalGate CR automatically.

Example:

manualApproval:
  disabled: true # - `disabled` : if the value set as `true`, ManualApprovalGate will not be installed (default: `true`)
  options:
    disabled: false
    deployments: {}

disabled: if set to true, the ManualApprovalGate component will not be installed. Default is true (disabled).
options: allows customizing the ManualApprovalGate deployments and configmaps. See Additional fields as options for details.

Result

Result section allows user to customize the Tekton Result component, Refer to Result Spec section in TektonResult for available options.

On OpenShift, route_tls_termination controls TLS termination on the Results route. Only reencrypt is supported (and is the default). edge breaks the route outright (no client flag can fix it). passthrough also works, but the client connects to the backend’s service-serving certificate, so it must trust the cluster’s service CA (or pass --insecure). reencrypt instead presents the ingress router certificate; note that by default this is cluster-signed rather than publicly trusted, so clients may still need the cluster’s ingress CA (or --insecure) unless the router uses a publicly trusted certificate. See route_tls_termination for details.

Default Result configuration in TektonConfig looks like following if user doesn’t specified any configuration options

Example:

result:
  disabled: false
  is_external_db: false
  options: {}

User can customize Result configuration with following options

Example:

result:
  disabled: false # - `disabled` : if the value set as `true`, result component will be disabled (default: `false`)
  targetNamespace: tekton-pipelines
  is_external_db: false # By default, this is set to false, TektonOperator will create Tekton Results database. If set to true, an external database will be used, and Tekton Results will retrieve its database credentials from the Kubernetes secret named tekton-results-postgres
  db_host: localhost
  db_port: 5342
  db_sslmode: verify-full
  db_sslrootcert: /etc/tls/db/ca.crt
  db_enable_auto_migration: true
  log_level: debug
  logs_api: true
  logs_type: File
  logs_buffer_size: 90kb
  logs_path: /logs
  auth_disable: true
  logging_pvc_name: tekton-logs
  secret_name: # optional
  gcs_creds_secret_name: <value>
  gcc_creds_secret_key: <value>
  gcs_bucket_name: <value>
  loki_stack_name: #optional
  loki_stack_namespace: #optional
  prometheus_port: 9090
  prometheus_histogram: false
  route_tls_termination: reencrypt # OpenShift only; only reencrypt is supported (default: reencrypt)
  watcher:
    completed_run_grace_period: 24h
    check_owner: true
    store_deadline: 10m
    disable_storing_incomplete_runs: true

Tekton Results Watcher configuration

Watcher-specific settings are configured under result.watcher. These map to command-line flags on the tekton-results-watcher deployment. See Results Watcher documentation for behavior details.

Not every watcher flag is exposed under result.watcher:

Performance flags (threadiness, qps, burst, disable-ha) are configured under result.performance.
Operator-managed flags (api_addr, auth_mode, namespace) are set by the operator and must not be overridden.
Secrets (token) must not be stored in the CR; use Secrets / auth_mode instead.

For optional string fields (summary_labels, summary_annotations, label_selector):

omit the field to keep the watcher binary default
set a non-empty value to override
set "" to clear the default (operator passes an empty flag value)

Example:

result:
  disabled: false
  watcher:
    completed_run_grace_period: 24h
    check_owner: true
    store_deadline: 10m
    disable_storing_incomplete_runs: true
    logs_api: true
    logs_timestamps: false
    store_event: false
    summary_labels: tekton.dev/pipeline
    label_selector: ""

Field	Watcher flag	Default	Description
`completed_run_grace_period`	`-completed_run_grace_period`	`0`	Time after completion before deleting Runs from the cluster. `0` disables deletion.
`check_owner`	`-check_owner`	`true`	Skip deletion when the Run has owner references.
`store_deadline`	`-store_deadline`	`10m`	Max wait to store a Run before clearing its finalizer on delete.
`disable_storing_incomplete_runs`	`-disable_storing_incomplete_runs`	`false`	Only store Runs after they complete.
`logs_api`	`-logs_api`	`false`	Send logs to the Results API (separate from API server `logs_api`).
`logs_timestamps`	`-logs_timestamps`	`false`	Include timestamps in stored logs.
`store_event`	`-store_event`	`false`	Store Kubernetes events related to Runs.
`summary_labels`	`-summary_labels`	`tekton.dev/pipeline`	Comma-separated labels copied into Result summary. Omit to keep default; `""` clears it.
`summary_annotations`	`-summary_annotations`	`""`	Comma-separated annotations copied into Result summary. Omit to keep default; `""` clears it.
`label_selector`	`-label_selector`	`""`	Label selector for Runs eligible for post-grace deletion. Omit to keep default; `""` clears it.
`requeue_interval`	`-requeue_interval`	`10m`	Requeue delay for certain watcher events.
`forward_buffer`	`-forward_buffer`	`150s`	Wait time for log forwarder after TaskRun completion.
`update_log_timeout`	`-update_log_timeout`	`300s`	Timeout for log storage operations.
`dynamic_reconcile_timeout`	`-dynamic_reconcile_timeout`	`30s`	Timeout for dynamic reconciler processing.
`disable_crd_update`	`-disable_crd_update`	`false`	Disable Tekton CRD annotation updates during reconcile.

User can configure custom database secret name for internal/external database via Tekton Config CR.

Example:

result:
  db_secret_name: # custom database secret name
  db_secret_user_key: # optional: required if custom database secret user key is not "POSTGRES_USER"
  db_secret_password_key: # optional: required if custom database secret password key is not "POSTGRES_PASSWORD"

Pruner

Pruner provides auto clean up feature for the Tekton pipelinerun and taskrun resources. In the background pruner container runs tkn command.

Example:

pruner:
  disabled: false
  schedule: "0 8 * * *"
  startingDeadlineSeconds: 100 # optional
  resources:
    - taskrun
    - pipelinerun
  keep: 3
  # keep-since: 1440
  # NOTE: you can use either "keep" or "keep-since", not both
  prune-per-resource: true

disabled : if the value set as true, pruner feature will be disabled (default: false)
schedule: how often to run the pruner job. User can understand the schedule syntax here.
startingDeadlineSeconds: Optional deadline in seconds for starting the job if it misses scheduled time for any reason. Missed jobs executions will be counted as failed ones
resources: supported resources for auto prune are taskrun and pipelinerun
keep: maximum number of resources to keep while deleting or removing resources
keep-since: retain the resources younger than the specified value in minutes
prune-per-resource: if the value set as true (default value false), the keep applied to each resource. The resources(pipeline and/or task) taken dynamically from that namespace and applied.
example: in a namespace ns-1 I have two pipeline, named pipeline-1 and pipeline-2, the out come would be: tkn pipelinerun delete --pipeline=my-pipeline-1 --keep=3 --namespace=ns-1, tkn pipelinerun delete --pipeline=my-pipeline-2 --keep=3 --namespace=ns-1. the same way works for task too.
We do not see any benefit by enabling prune-per-resource=true, when you use keep-since. As keep-since is limiting the resources by time(irrespective of resource count), there is no change on the outcome.

Note:

if disabled: false and schedule: with empty value, global pruner job will be disabled. however, if there is a prune schedule (operator.tekton.dev/prune.schedule) annotation present with a value in a namespace. a namespace wide pruner jobs will be created.

Pruner Namespace annotations

By default pruner job will be created from the global pruner config (spec.pruner), though user can customize a pruner config to a specific namespace with the following annotations. If some of the annotations are not present or has invalid value, for that value, falls back to global value or skipped the namespace.

operator.tekton.dev/prune.skip - pruner job will be skipped to a namespace, if the value set as true
operator.tekton.dev/prune.schedule - pruner job will be created on a specific schedule
operator.tekton.dev/prune.keep - maximum number of resources will be kept
operator.tekton.dev/prune.keep-since - retain the resources younger than the specified value in minutes
operator.tekton.dev/prune.prune-per-resource - the keep or keep-since applied to each resource
operator.tekton.dev/prune.resources - can be taskrun and/or pipelinerun, both value can be specified with comma separated. example: taskrun,pipelinerun
operator.tekton.dev/prune.strategy - allowed values: either keep or keep-since

Note:

if a global value is not present the following values will be consider as default value
> resources: pipelinerun
> keep: 100

Tekton Kueue

The spec.kueue section allows you to install and manage the Tekton Kueue through TektonConfig. The Tekton Kueue component uses Kueue and cert-manager; you must install Kueue and cert-manager CRDs before enabling Tekton Kueue. For full pre-requisites and multi-cluster configuration details, see Tekton Kueue.

The deprecated spec.scheduler field is migrated automatically to spec.kueue during pre-upgrade reconciliation. If both fields are configured, spec.kueue takes precedence.

Tekton Kueue can be enabled by setting disabled to false in the kueue section. If you are working with multi-cluster pipelines, you can enable multi-cluster from the kueue config. In a multi-cluster environment a cluster can play the role of Hub or Spoke. The TektonConfig settings for Tekton Kueue for Hub and Spoke are defined below.

Hub cluster

kueue:
  disabled: false
  multi-cluster-disabled: false
  multi-cluster-role: Hub
  config.yaml:
    queueName: pipelines-queue
  options: {}

Spoke cluster

kueue:
  disabled: false
  multi-cluster-disabled: false
  multi-cluster-role: Spoke
  config.yaml:
    queueName: pipelines-queue
  options: {}

disabled: set to false to enable the Tekton Kueue component (default is true).
multi-cluster-disabled: when false, multi-cluster features are enabled (default is true).
multi-cluster-role: Hub or Spoke. When set to Hub, TektonConfig also creates and manages the TektonMulticlusterProxyAAE component automatically (the proxy is used to communicate with spoke clusters, e.g. for Kueue MultiKueue). On spoke clusters use Spoke; the proxy is not installed there.

See TektonMulticlusterProxyAAE for details on the proxy component and its requirements.

OpenShift: proxy-aae Kueue namespace

The proxy-aae deployment reads WORKERS_SECRET_NAMESPACE to locate the Kueue operator namespace. The Kubernetes default is kueue-system; on OpenShift the operator automatically sets this to openshift-kueue-operator. If Kueue is installed in a non-default namespace, override WORKERS_SECRET_NAMESPACE via spec.multiclusterProxyAAE.options in TektonConfig:

spec:
  multiclusterProxyAAE:
    options:
      deployments:
        proxy-aae:
          spec:
            template:
              spec:
                containers:
                - name: proxy-aae
                  env:
                  - name: WORKERS_SECRET_NAMESPACE
                    value: my-kueue-namespace

Addon

TektonAddon install some resources along with Tekton Pipelines on the cluster. This provides few PipelineTemplates, ResolverTasks, ResolverStepActions and CommunityResolverTasks.

This section allows to customize installation of those resources through params. You can read more about the supported params here.

Example:

addon:
  params:
    - name: "pipelineTemplates"
      value: "true"
    - name: "resolverTasks"
      value: "true"
    - name: "resolverStepActions"
      value: "true"
    - name: "communityResolverTasks"
      value: "true"

NOTE: TektonAddon is currently available for OpenShift Platform only. Enabling this for Kubernetes platform is in roadmap of Operator.

Dashboard

Dashboard provides configuration options for the Tekton Dashboard if the specified profile value includes the Dashboard component. (E.g. all on Kubernetes)

Example:

dashboard:
  readonly: true

readonly: If set to true, install the Dashboard in read-only mode

This is an Optional section.

Resolvers

As part of TektonPipelines, resolvers are installed which are by default enabled. User can disable them through TektonConfig.

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pipeline:
    enable-bundles-resolver: true
    enable-cluster-resolver: true
    enable-git-resolver: true
    enable-hub-resolver: true

User can also provide resolver specific configurations through TektonConfig. The Default configurations are not added by default in TektonConfig. To override default configurations, user can provide the configurations as below. You can find the default configurations here

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pipeline:
    bundles-resolver-config:
      default-service-account: pipelines
    cluster-resolver-config:
      default-namespace: cluster-resolver-test
    enable-bundles-resolver: true
    enable-cluster-resolver: true
    enable-git-resolver: true
    enable-hub-resolver: true
    git-resolver-config:
      server-url: localhost.com
    hub-resolver-config:
      default-tekton-hub-catalog: tekton
      tekton-hub-api: "https://my-custom-tekton-hub.example.com"
      artifact-hub-api: "https://my-custom-artifact-hub.example.com"

Under the hub-resolver-config, the tekton-hub-api and artifact-hub-api will be passed as environment variable into tekton-pipelines-remote-resolvers controller.
In the deployment the environment name will be converted as follows,

tekton-hub-api => TEKTON_HUB_API
artifact-hub-api => ARTIFACT_HUB_API

NamespaceSync (OpenShift only)

The namespaceSync block under spec.platforms.openshift controls the NamespaceSyncController, which watches every user namespace and ensures Tekton-required resources are present and up to date. It replaces the legacy per-namespace batch loop that was part of the RBAC reconciler.

Resources managed per namespace

Resource	Kind	Purpose
`pipeline`	`ServiceAccount`	Identity for PipelineRun pods
`pipelines-scc-rolebinding`	`RoleBinding` → `pipelines-scc-clusterrole`	Grants the pipeline SA permission to use the default SCC
`openshift-pipelines-edit`	`RoleBinding` → `ClusterRole/edit`	Gives the pipeline SA edit access within its namespace
`config-trusted-cabundle`	`ConfigMap`	CA bundle for custom/internal PKI trust
`config-service-cabundle`	`ConfigMap`	OpenShift service CA bundle
`openshift-pipelines-clusterinterceptors`	`ClusterRoleBinding` subject	Lets the pipeline SA call ClusterInterceptors

Configuration fields

spec:
  platforms:
    openshift:
      namespaceSync:
        createPipelineSA: true          # create/maintain the pipeline SA
        createSCCRoleBinding: true      # create/maintain pipelines-scc-rolebinding
        createEditRoleBinding: true     # create/maintain openshift-pipelines-edit
        createCABundles: true           # inject CA bundle ConfigMaps

        # Optional: restrict which namespaces are synced.
        # Omit entirely (or set to {}) to sync all non-system namespaces (default).
        # Use matchLabels/matchExpressions to restrict to a subset.
        namespaceSelector:
          matchLabels:
            pipelines.openshift.io/sync: "true"

        # Optional: automatically bind secrets to the pipeline SA.
        # Use secretName for an exact name, or labelSelector to match by label.
        secretBindings:
          - secretName: pipeline-quay-openshift     # Quay Bridge robot account secret
          - labelSelector:
              matchLabels:
                quay-integration: my-quay            # all secrets with this label

All boolean fields default to true when the namespaceSync block is present.

Disabling individual features

Set the flag to false to stop managing that resource class. Existing resources are not deleted — the controller simply stops reconciling them:

spec:
  platforms:
    openshift:
      namespaceSync:
        createEditRoleBinding: false   # do not create openshift-pipelines-edit

Restricting sync to specific namespaces

Use namespaceSelector to limit which namespaces the controller acts on. Label namespaces you want synced, then configure the selector to match:

# Label a namespace to opt in
oc label namespace my-project pipelines.openshift.io/sync=true

spec:
  platforms:
    openshift:
      namespaceSync:
        namespaceSelector:
          matchLabels:
            pipelines.openshift.io/sync: "true"

To disable sync for all namespaces while keeping the feature flags intact, set all individual flags to false:

namespaceSync:
  createPipelineSA: false
  createCABundles: false
  createEditRoleBinding: false
  createSCCRoleBinding: false

Or remove the namespaceSync field entirely to fall back to operator defaults.

Quay Bridge secret auto-binding

When the Quay Bridge Operator is installed, it creates a robot-account secret named pipeline-quay-openshift in each namespace. Declare a secretBinding to have the NamespaceSyncController automatically bind that secret to the pipeline SA as an image pull secret:

spec:
  platforms:
    openshift:
      namespaceSync:
        secretBindings:
          - secretName: pipeline-quay-openshift

Once configured:

When the secret appears in a namespace it is added to both imagePullSecrets and secrets on the pipeline SA within seconds.
When the secret is deleted the reference is removed automatically.

Migration from legacy `spec.params`

Older releases controlled this behaviour through spec.params entries. These are deprecated: the operator continues to honor them for backward compatibility, but they should be migrated to the typed fields below. The operator automatically migrates and persists them during the first reconcile after an upgrade:

Legacy `spec.params`	Typed field
`createRbacResource: "false"`	`createPipelineSA`, `createSCCRoleBinding`, `createEditRoleBinding` all set to `false`
`createCABundleConfigMaps: "false"`	`createCABundles: false`
`legacyPipelineRbac: "false"`	`createEditRoleBinding: false`

After migration the legacy params are removed from spec.params and the typed fields take effect. There is no need to manually update the TektonConfig CR.

OpenShiftPipelinesAsCode

The PipelinesAsCode section allows you to customize the Pipelines as Code features on both Kubernetes and OpenShift. When you change the TektonConfig CR, the Operator automatically applies the settings to custom resources and configmaps in your installation. On Kubernetes, configure spec.platforms.kubernetes.pipelinesAsCode (the managed CR remains OpenShiftPipelinesAsCode for API compatibility).

Some of the fields have default values, so operator will add them if the user hasn’t passed in CR. Other fields which don’t have default values unless the user specifies them. User can find those here.

Example:

platforms:
  openshift:   # or `kubernetes:`
    pipelinesAsCode:
      additionalPACControllers:
        controllername:
          enable: true
          configMapName:
          secretName:
          settings:
      enable: true
      settings:
        application-name: Pipelines as Code CI
        auto-configure-new-github-repo: "false"
        bitbucket-cloud-check-source-ip: "true"
        custom-console-name: ""
        custom-console-url: ""
        custom-console-url-pr-details: ""
        custom-console-url-pr-tasklog: ""
        error-detection-from-container-logs: "false"
        error-detection-max-number-of-lines: "50"
        error-detection-simple-regexp:
          ^(?P<filename>[^:]*):(?P<line>[0-9]+):(?P<column>[0-9]+):([
          ]*)?(?P<error>.*)
        error-log-snippet: "true"
        enable-cancel-in-progress-on-pull-requests: "false"
        enable-cancel-in-progress-on-push: "false"
        hub-catalog-name: tekton
        hub-url: https://api.hub.tekton.dev/v1
        require-ok-to-test-sha: "false"
        remote-tasks: "true"
        secret-auto-create: "true"
        secret-github-app-token-scoped: "true"

Remote Hub Catalogs

Pipelines as Code supports configuring remote hub catalogs to fetch tasks and pipelines. You can configure custom catalogs using the catalog-{INDEX}-* settings pattern.

Each custom catalog requires the following four fields:

Field	Description	Required
`catalog-{INDEX}-id`	Unique identifier for the catalog. Users reference tasks from this catalog using this ID as prefix (e.g., `custom://task-name`)	Yes
`catalog-{INDEX}-name`	Name of the catalog within the hub	Yes
`catalog-{INDEX}-url`	URL endpoint of the hub API	Yes
`catalog-{INDEX}-type`	Type of hub: `artifacthub` (for Artifact Hub) or `tektonhub` (for Tekton Hub)	Yes

Where {INDEX} is a number that can be incremented to add multiple catalogs (e.g., 1, 2, 3).

Example: Configuring a Custom Hub Catalog

platforms:
  openshift:
    pipelinesAsCode:
      enable: true
      settings:
        catalog-1-id: "custom"
        catalog-1-name: "tekton"
        catalog-1-url: "https://api.custom.hub/v1"
        catalog-1-type: "tektonhub"

Example: Configuring Multiple Hub Catalogs

You can configure multiple hub catalogs by incrementing the catalog-{INDEX} number:

platforms:
  openshift:
    pipelinesAsCode:
      enable: true
      settings:
        catalog-1-id: "custom"
        catalog-1-name: "tekton"
        catalog-1-url: "https://api.custom.hub/v1"
        catalog-1-type: "tektonhub"
        catalog-2-id: "artifact"
        catalog-2-name: "tekton-catalog-tasks"
        catalog-2-url: "https://artifacthub.io"
        catalog-2-type: "artifacthub"

Referencing Tasks from Custom Catalogs

Once configured, users can reference tasks from custom catalogs by adding a prefix matching the catalog ID:

pipelinesascode.tekton.dev/task: "custom://git-clone"
pipelinesascode.tekton.dev/task: "artifact://buildah"

Note: Pipelines-as-Code will not try to fallback to the default or another custom hub if the task referenced is not found (the Pull Request will be set as failed).

For more details, see the Pipelines-as-Code Remote Hub Catalogs documentation.

NOTE: On Kubernetes clusters, use spec.platforms.kubernetes.pipelinesAsCode. The custom resource kind remains OpenShiftPipelinesAsCode.

Event based pruner

The tektonpruner section in the TektonConfig spec allows you to manage the event-driven Tekton Pruner, which enables configuration-based cleanup of Tekton resources such as PipelineRuns and TaskRuns.

Important: This component is disabled by default. To enable the event-based pruner, the existing job-based pruner pruner MUST be disabled.

Basic Configuration

  pruner:
    disabled: true  # Must disable job-based pruner
  tektonpruner:
    disabled: false  # Enable event-based pruner
    global-config:
      enforcedConfigLevel: global  # Options: global, namespace
      ttlSecondsAfterFinished: 3600  # Delete runs older than 1 hour (optional)
      historyLimit: 100              # Keep only 100 runs total (optional)
      successfulHistoryLimit: 50     # Keep only 50 successful runs (optional)
      failedHistoryLimit: 20         # Keep only 20 failed runs (optional)
    options: {}

Configuration Levels

The enforcedConfigLevel determines the configuration hierarchy:

global: Cluster-wide defaults apply to all namespaces (no namespace overrides allowed)
namespace: Allows namespace-level overrides via ConfigMaps in individual namespaces

Pruning Fields

You can specify any combination of these fields. The pruner deletes runs when any one of the specified conditions is met:

ttlSecondsAfterFinished: Time in seconds to retain completed runs before pruning
historyLimit: Maximum number of runs to retain for each status (applies independently to both successful and failed runs)
successfulHistoryLimit: Maximum number of successful runs to retain
failedHistoryLimit: Maximum number of failed runs to retain

Note: If successfulHistoryLimit or failedHistoryLimit is not specified, historyLimit value is used as fallback for that status type.

Namespace-Level Configuration

Configure different default pruning policies for specific namespaces in the global config:

  tektonpruner:
    disabled: false
    global-config:
      enforcedConfigLevel: namespace
      historyLimit: 100  # Global default
      namespaces:
        dev-namespace:
          historyLimit: 50
          ttlSecondsAfterFinished: 1800  # 30 minutes for dev
        prod-namespace:
          successfulHistoryLimit: 200
          failedHistoryLimit: 50
          ttlSecondsAfterFinished: 86400  # 24 hours for prod

Note: For advanced configurations including resource-level selectors and per-namespace overrides via ConfigMaps, refer to the TektonPruner documentation.

Complete Example

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  targetNamespace: tekton-pipelines
  profile: all
  pruner:
    disabled: true  # Disable job-based pruner
  tektonpruner:
    disabled: false
    global-config:
      enforcedConfigLevel: namespace
      historyLimit: 100
      ttlSecondsAfterFinished: 7200  # 2 hours
      namespaces:
        tekton-pipelines:
          historyLimit: 200
          successfulHistoryLimit: 150
          failedHistoryLimit: 50
        dev:
          ttlSecondsAfterFinished: 3600  # 1 hour
          historyLimit: 50
    options:
      disabled: false
      deployments:
        tekton-pruner-controller:
          spec:
            replicas: 1

Configuration Notes:

Both pruners (job-based and event-based) cannot be enabled simultaneously
The event-based pruner responds to resource events in real-time, providing more efficient cleanup
When enforcedConfigLevel is set to namespace, individual namespaces can override these settings using ConfigMaps

Additional fields as `options`

There is a field called options available in all the components.

NOTE: There is a possibility to have two different values for a field.
An example: with a pre-defined field you can set value and the same field may be defined under options as well. In that case value from options will be final.

NOTE: The embedded objects are not merged as a whole. The operator copies a known set of fields onto the manifest, and the per-kind lists below are exhaustive - a field outside them is ignored silently, with no error or warning. If a field you set under options has no effect, it is most likely not supported yet - please open an issue.

A sample options field,

options:
  disabled: false
  configMaps:
    config-leader-election: # name of the configMap
      data:
        lease-duration: "90s"
    pipeline-config-logging: # creates new configMap under targetNamespace
      metadata:
        labels:
          my-custom-logger: "true"
        annotations:
          logger-type: "uber-zap"
      data:
        loglevel.controller: "info"
        loglevel.webhook: "info"
        zap-logger-config: |
          {
            "level": "debug",
            "development": false,
            "sampling": {
              "initial": 100,
              "thereafter": 50
            },
            "outputPaths": ["stdout"],
            "errorOutputPaths": ["stderr"],
            "encoding": "json",
            "encoderConfig": {
              "timeKey": "ts",
              "levelKey": "severity",
              "nameKey": "logger",
              "callerKey": "caller",
              "messageKey": "message",
              "stacktraceKey": "stacktrace",
              "lineEnding": "",
              "levelEncoder": "",
              "timeEncoder": "iso8601",
              "durationEncoder": "",
              "callerEncoder": ""
            }
          }          

  deployments:
    tekton-pipelines-controller: # name of the deployment
      metadata:
        labels:
          custom-label: "foo"
        annotations:
          custom-annotation: "foo"
      spec:
        replicas: 2
        strategy:
          type: RollingUpdate
          rollingUpdate:
            maxSurge: 0
            maxUnavailable: 1
        template:
          spec:
            containers:
              - name: tekton-pipelines-controller
                env:
                  - name: CONFIG_LOGGING_NAME
                    value: pipeline-config-logging
  statefulSets:
    web: # name of the statefulSets
      metadata:
        labels:
          custom-label: foo
        annotations:
          custom-annotation: foo
      spec:
        replicas: 3
        updateStrategy:
          type: RollingUpdate
          rollingUpdate:
            partition: 1
        template:
          spec:
            containers:
              - name: nginx
                env:
                  - name: NGINX_MODE
                    value: production
  horizontalPodAutoscalers:
    tekton-pipelines-webhook: # name of the hpa
      metadata:
        annotations:
        labels:
      spec:
        minReplicas: 2
        maxReplicas: 7
        metrics:
          - resource:
              name: cpu
              target:
                averageUtilization: 85
                type: Utilization
            type: Resource
  webhookConfigurationOptions:
    validation.webhook.pipeline.tekton.dev:
      failurePolicy: Fail
      timeoutSeconds: 20
      sideEffects: None
    webhook.pipeline.tekton.dev:
      failurePolicy: Fail
      timeoutSeconds: 20
      sideEffects: None

disabled - disables the additional options support, if disabled set to true. default: false

ConfigMaps

Supports to update existing configMap also supports to create new configMap.

The following fields are supported in configMap

metadata
- labels - supports add and update
- annotations - supports add and update
data - supports add and update

Deployments

Supports to update the existing deployments. But not supported to create new deployment.

The following fields are supported in deployment

metadata
- labels - supports add and update
- annotations - supports add and update
spec
- replicas - updates deployment replicas count
- strategy - replaces the existing deployment strategy with this, if type is not empty
- template
  - metadata
    - labels - supports add and update
    - annotations - supports add and update
  - spec
    - affinity - replaces the existing Affinity with this, if not empty
    - priorityClassName - replaces the existing PriorityClassName with this, if not empty
    - nodeSelector - replaces the existing NodeSelector with this, if not empty
    - tolerations - replaces the existing tolerations with this, if not empty
    - topologySpreadConstraints - replaces the existing TopologySpreadConstraints with this, if not empty
    - runtimeClassName - adds and updates runtimeClassName
    - volumes - adds and updates volumes
    - initContainers - adds and updates init-containers
      - resources - replaces the resources requirements with this, if not empty
      - envs - adds and updates environments
      - volumeMounts - adds and updates VolumeMounts
      - args - appends given args with existing arguments. NOTE: THIS OPERATION DO NOT REPLACE EXISTING ARGS
    - containers - adds and updates containers
      - resources - replaces the resources requirements with this, if not empty
      - envs - adds and updates environments
      - volumeMounts - adds and updates VolumeMounts
      - args - appends given args with existing arguments. NOTE: THIS OPERATION DO NOT REPLACE EXISTING ARGS

StatefulSets

Supports to update the existing StatefulSet. But not supported to create new StatefulSet.

The following fields are supported in StatefulSet

metadata
- labels - supports add and update
- annotations - supports add and update
spec
- replicas - updates statefulSets replicas count
- updateStrategy - replaces the existing statefulSet update strategy with this, if type is not empty
- serviceName - updates service name
- podManagementPolicy - updates pod management policy
- volumeClaimTemplates - updates volume claim templates
- template
  - metadata
    - labels - supports add and update
    - annotations - supports add and update
  - spec
    - affinity - replaces the existing Affinity with this, if not empty
    - priorityClassName - replaces the existing PriorityClassName with this, if not empty
    - nodeSelector - replaces the existing NodeSelector with this, if not empty
    - tolerations - replaces the existing tolerations with this, if not empty
    - topologySpreadConstraints - replaces the existing TopologySpreadConstraints with this, if not empty
    - runtimeClassName - adds and updates runtimeClassName
    - volumes - adds and updates volumes
    - initContainers - adds and updates init-containers
      - resources - replaces the resources requirements with this, if not empty
      - envs - adds and updates environments
      - volumeMounts - adds and updates VolumeMounts
      - args - appends given args with existing arguments. NOTE: THIS OPERATION DO NOT REPLACE EXISTING ARGS
    - containers - adds and updates containers
      - resources - replaces the resources requirements with this, if not empty
      - envs - adds and updates environments
      - volumeMounts - adds and updates VolumeMounts
      - args - appends given args with existing arguments. NOTE: THIS OPERATION DO NOT REPLACE EXISTING ARGS

HorizontalPodAutoscalers

Supports to update the existing HorizontalPodAutoscaler(HPA) also supports to create new HPA.

The following fields are supported in HorizontalPodAutoscaler (aka HPA)

metadata
- labels - supports add and update
- annotations - supports add and update
spec
- scaleTargetRef - replaces scaleTargetRef with this, if kind and name are not empty
- minReplicas - updates minimum replicas count
- maxReplicas - updates maximum replicas count
- metrics - replaces the metrics details with this array, if not empty
- behavior - updates behavior data with this, if not empty
  - scaleUp - replaces scaleUp with this, if not empty
  - scaleDown - replaces scaleDown with this, if not empty

NOTE: If a Deployment or StatefulSet has a Horizontal Pod Autoscaling (HPA) and is in active state, Operator will not control the replicas to that resource. However if status.desiredReplicas and spec.minReplicas not present in HPA, operator takes the control. Also if HPA disabled, operator takes control. Even though the operator takes the control, the replicas value will be adjusted to the hpa’s scaling range.

webhookConfigurationOptions

Defines additional options for each webhooks. Use webhook name as a key to define options for a webhook. Options are ignored if the webhook does not exist with the name key. To get detailed information about webhooks options visit https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/

the following options are supported for webhookConfigurationOptions

failurePolicy - defines how unrecognized errors and timeout errors from the admission webhook are handled. Allowed values are Ignore or Fail
timeoutSeconds - allows configuring how long the API server should wait for a webhook to respond before treating the call as a failure.
sideEffects - indicates whether the webhook have a side effet. Allowed values are None, NoneOnDryRun, Unknown, or Some

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Tekton Pipeline

TektonPipeline custom resource allows user to install and manage Tekton Pipeline.

It is recommended to install the component through TektonConfig.

The TektonPipeline CR is as below:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonPipeline
metadata:
  name: pipeline
spec:
  targetNamespace: tekton-pipelines
  await-sidecar-readiness: true
  coschedule: workspaces
  disable-creds-init: false
  disable-home-env-overwrite: true
  disable-working-directory-overwrite: true
  disable-inline-spec: "taskrun,pipelinerun,pipeline"
  enable-api-fields: beta
  enable-bundles-resolver: true
  enable-cel-in-whenexpression: false
  enable-cluster-resolver: true
  enable-custom-tasks: true
  enable-git-resolver: true
  enable-hub-resolver: true
  enable-param-enum: false
  enable-provenance-in-status: true
  enable-step-actions: false
  enforce-nonfalsifiability: none
  keep-pod-on-cancel: false
  max-result-size: 4096
  metrics.count.enable-reason: false
  metrics.pipelinerun.duration-type: histogram
  metrics.pipelinerun.level: pipeline
  metrics.taskrun.duration-type: histogram
  metrics.taskrun.level: task
  # Tracing configuration (optional)
  # traces.enabled: true
  # traces.endpoint: "http://jaeger-collector.jaeger.svc.cluster.local:4318/v1/traces"
  # traces.credentialsSecret: ""
  require-git-ssh-secret-known-hosts: false
  results-from: termination-message
  running-in-environment-with-injected-sidecars: true
  send-cloudevents-for-runs: false
  set-security-context: false
  trusted-resources-verification-no-match-policy: ignore
  performance:
    disable-ha: false
    buckets: 1
    replicas: 1
    threads-per-controller: 2
    kube-api-qps: 5.0
    kube-api-burst: 10
    statefulset-ordinals: false
  options:
    disabled: false
    configMaps: {}
    deployments: {}

You can install this component using TektonConfig by choosing appropriate profile.

Properties

This fields have default values so even if user have not passed them in CR, operator will add them. User can later change them as per their need.

disable-creds-init (Default: false)

Setting this flag to “true” will prevent Tekton scanning attached service accounts and injecting any credentials it finds into your Steps.

The default behaviour currently is for Tekton to search service accounts for secrets matching a specified format and automatically mount those into your Steps.

Note: setting this to “true” will prevent PipelineResources from working. See more info here.
await-sidecar-readiness (Default: true)

Setting this flag to “false” to allow the Tekton controller to start a TasksRun’s first step immediately without waiting for sidecar containers to be running first.

Note: setting this flag to “false” will mean the running-in-environment-with-injected-sidecars flag has no effect.
coschedule (Default: workspaces)

This flag determines how PipelineRun Pods are scheduled with Affinity Assistant. Acceptable values are “workspaces” (default), “pipelineruns”, “isolate-pipelinerun”, or “disabled”
running-in-environment-with-injected-sidecars (Default: true)

This option should be set to false when Pipelines is running in a cluster that does not use injected sidecars such as Istio. Setting it to false should decrease the time it takes for a TaskRun to start running. For clusters that use injected sidecars, setting this option to false can lead to unexpected behavior.

See more info here.
require-git-ssh-secret-known-hosts (Default: false)

Setting this flag to “true” will require that any Git SSH Secret offered to Tekton must have known_hosts included.

See more info here.
enable-custom-tasks (Default: false)

Setting this flag to “true” enables the use of custom tasks from within pipelines. This is an experimental feature and thus should still be considered an alpha feature.
enable-api-fields (Default: stable)

Setting this flag will determine which gated features are enabled. Acceptable values are “stable” or “alpha”.
results-from (Default: termination-message)

This feature is to use the container’s termination message to fetch results from. Set it to “sidecar-logs” to enable use of a results sidecar logs to extract results instead of termination message.
max-result-size (Default: 4096)

This feature is to configure the size of the task results if using sidecar-logs. The default value if 4096 and maximum value can be 1572863.
enable-provenance-in-status (Default: true)

This feature is to enable populating the provenance field in TaskRun and PipelineRun status. The provenance field contains metadata about resources used in the TaskRun/PipelineRun such as the source from where a remote Task/Pipeline definition was fetched. To disable populating this field, set this flag to “false”.
set-security-context (Default: false)

Setting this flag to “true” to set a security context for containers injected by Tekton that will allow TaskRun pods to run in namespaces with restricted pod security admission
keep-pod-on-cancel (Default: false)

Setting this flag to “true” will not delete the pod associated with cancelled taskrun.
enforce-nonfalsifiability (Default: none)

Setting this flag to “spire” to enable integration with SPIRE.
enable-param-enum (Default: false)

Setting this flag to “true” will enable params of type Enum
enable-step-actions (Default: false)

Setting this flag to “true” will enable specifying StepAction in a Step. A StepAction is the reusable and scriptable unit of work that is performed by a Step
enable-cel-in-whenexpression (Default: false)

Setting this flag to “true” will enable using CEL in when expressions.
trusted-resources-verification-no-match-policy (Default: ignore)

Trusted Resources is a feature which can be used to sign Tekton Resources and verify them. Details of design can be found at TEP–0091. This feature is under alpha version and support v1beta1 version of Task and Pipeline. To know more about this visit pipelines documentation

Metrics Properties

These fields have default values so even if user have not passed them in CR, operator will add them and override the values configure in pipelines.

metrics.pipelinerun.duration-type (Default: histogram)

Setting this flag will determine the duration type - gauge or histogram.
metrics.pipelinerun.level (Default: pipeline)

Setting this flag will determine the level of pipelinerun metrics.
metrics.taskrun.duration-type (Default: histogram)

Setting this flag will determine the duration type - gauge or histogram.
metrics.taskrun.level (Default: task)

Setting this flag will determine the level of taskrun metrics.
metrics.count.enable-reason (Default: false)

Setting this flag to “true” will include reason label on count metrics.

Tracing Properties

Tekton Pipelines supports distributed tracing using OpenTelemetry. These fields allow you to configure tracing to send trace data to observability backends like Jaeger, Zipkin, or other OTLP-compatible collectors.

traces.enabled (Optional)

Setting this flag to “true” enables distributed tracing for Tekton Pipelines. When enabled, the pipeline controller will export trace spans for pipeline and task reconciliation operations.
```
spec:
  traces.enabled: true
```
traces.endpoint (Optional)

The URL of the OpenTelemetry trace collector endpoint. Tekton Pipeline exports traces using the OTLP (OpenTelemetry Protocol) format over HTTP.

Supported endpoints:
- Jaeger with OTLP: Use port 4318 for OTLP HTTP (e.g., http://jaeger-collector.jaeger.svc.cluster.local:4318/v1/traces)
- OpenTelemetry Collector: OTLP HTTP endpoint (e.g., http://otel-collector.observability.svc.cluster.local:4318/v1/traces)
- Other OTLP-compatible backends: Any trace backend that supports OTLP HTTP protocol
```
spec:
  traces.enabled: true
  traces.endpoint: "http://jaeger-collector.jaeger.svc.cluster.local:4318/v1/traces"
```
traces.credentialsSecret (Optional)

The name of a Kubernetes secret containing credentials for authenticating with the tracing endpoint. This is useful when your tracing backend requires authentication.
```
spec:
  traces.enabled: true
  traces.endpoint: "https://secure-jaeger-collector.example.com/api/traces"
  traces.credentialsSecret: "jaeger-auth-secret"
```

Example: Complete Tracing Configuration

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonPipeline
metadata:
  name: pipeline
spec:
  targetNamespace: tekton-pipelines
  # ... other configuration ...

  # Enable tracing with OpenTelemetry Collector
  traces.enabled: true
  traces.endpoint: "http://otel-collector.observability.svc.cluster.local:4318/v1/traces"

Example: Tracing with Jaeger

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonPipeline
metadata:
  name: pipeline
spec:
  targetNamespace: tekton-pipelines
  # ... other configuration ...

  # Enable tracing with Jaeger (using OTLP endpoint)
  traces.enabled: true
  traces.endpoint: "http://jaeger-collector.jaeger.svc.cluster.local:4318/v1/traces"

For more information about distributed tracing in Tekton Pipelines, see the TEP-0124: Distributed Tracing for Tasks and Pipelines.

Optional Properties

This fields doesn’t have default values so will be considered only if user passes them. By default Operator won’t add this fields CR and won’t configure for pipelines.

The Default values for this fields are already set in pipelines are not set by Operator. If user passes some values then those will be set for the particular field.

default-timeout-minutes

default-timeout-minutes contains the default number of minutes to use for TaskRun and PipelineRun, if none is specified.

default-timeout-minutes: "60" # 60 minutes
default-service-account

default-service-account contains the default service account name to use for TaskRun and PipelineRun, if none is specified.

default-service-account: "default"
default-managed-by-label-value

default-managed-by-label-value contains the default value given to the “app.kubernetes.io/managed-by” label applied to all Pods created for TaskRuns. If a user’s requested TaskRun specifies another value for this label, the user’s request supersedes.

default-managed-by-label-value: "tekton-pipelines"
disable-inline-spec (Default: ``)

Inline specifications can be disabled for specific resources only. To achieve that, set the disable-inline-spec flag to a comma-separated list of the desired resources. Valid values are pipeline, pipelinerun and taskrun.
default-pod-template

default-pod-template contains the default pod template to use TaskRun and PipelineRun, if none is specified. If a pod template is specified, the default pod template is ignored.
default-cloud-events-sink

default-cloud-events-sink contains the default CloudEvents sink to be used for TaskRun and PipelineRun, when no sink is specified. Note that right now it is still not possible to set a PipelineRun or TaskRun specific sink, so the default is the only option available. If no sink is specified, no CloudEvent is generated
default-task-run-workspace-binding

default-task-run-workspace-binding contains the default workspace configuration provided for any Workspaces that a Task declares but that a TaskRun does not explicitly provide.
default-resolver-type

default-resolver-type contains the resolver type to be used as default resolver.

Performance Properties

spec:
  # omitted other fields ...
  performance:
    disable-ha: false
    buckets: 1
    replicas: 1
    threads-per-controller: 2
    kube-api-qps: 5.0
    kube-api-burst: 10
    statefulset-ordinals: false

These fields are optional and there is no default values. If user passes them, operator will include most of fields into the deployment tekton-pipelines-controller under the container tekton-pipelines-controller as arguments(duplicate name? No, container and deployment has the same name), otherwise pipelines controller’s default values will be considered. and buckets field is updated into config-leader-election config-map under the namespace tekton-pipelines.

A high level descriptions are given here. To get the detailed information please visit pipelines documentation, High Availability Support, and Performance Configuration

disable-ha - enable or disable ha feature, defaults in pipelines controller is disable-ha=false
buckets - buckets is the number of buckets used to partition key space of each reconciler. If this number is M and the replica number of the controller is N, the N replicas will compete for the M buckets. The owner of a bucket will take care of the reconciling for the keys partitioned into that bucket. The maximum value of buckets at this time is 10. default value in pipeline controller is 1
replicas - pipelines controller deployment replicas count
threads-per-controller - is the number of threads(aka worker) to use when processing the pipelines controller’s workqueue, default value in pipelines controller is 2
kube-api-qps - QPS indicates the maximum QPS to the cluster master from the REST client, default value in pipeline controller is 5.0
kube-api-burst - maximum burst for throttle, default value in pipeline controller is 10
statefulset-ordinals - enables StatefulSet Ordinals mode for the Tekton Pipelines Controller. When set to true, the Pipelines Controller is deployed as a StatefulSet, allowing for multiple replicas to be configured with a load-balancing mode. This ensures that the load is evenly distributed across replicas, and the number of buckets is enforced to match the number of replicas. Moreover, There are two mechanisms available for scaling for scaling Pipelines Controller horizontally:

Using leader election, which allows for failover, but can result in hot-spotting.
Using StatefulSet ordinals, which doesn’t allow for failover, but guarantees load is evenly spread across replicas.

Note:

kube-api-qps and kube-api-burst will be multiplied by 2 in pipelines controller. To get the detailed information visit Performance Configuration guide

if you modify or remove any of the performance properties, tekton-pipelines-controller deployment and config-leader-election config-map (if buckets changed) will be updated, and tekton-pipelines-controller pods will be recreated

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Tekton Trigger

TektonTrigger custom resource allows user to install and manage Tekton Trigger.

It is recommended to install the components through TektonConfig.

The TektonTrigger CR is as below:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonTrigger
metadata:
  name: trigger
spec:
  targetNamespace: tekton-pipelines

You can install this component using TektonConfig by choosing appropriate profile.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Tekton Dashboard

TektonDashboard custom resource allows user to install and manage Tekton Dashboard.

It is recommended to install the components through TektonConfig.

The TektonDashboard CR is as below:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonDashboard
metadata:
  name: dashboard
spec:
  targetNamespace: tekton-pipelines
  readonly: false

You can install this component using TektonConfig by choosing appropriate profile.

Properties

readonly (Default: false)

If set to true, installs the Dashboard in read-only mode.

If set to false, the following features will be enabled on the Dashboard:
- delete a pipeline
- create a pipelinerun
- rerun a pipelinerun
- delete a pipelinerun
- create a pipelineresource
- create a taskrun
- import resources from repository
external-logs

External URL from which to fetch logs when logs are not available in the cluster

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Tekton Result

TektonResult custom resource allows user to install and manage Tekton Result.

TektonResult is installed through TektonConfig by default.

Note : TektonOperator creates a secret for default database root password and a tls secret for TektonResult, the TektonResult doesn’t rotate the tls certificate.

Create PVC if using PVC for logging (Optional)

cat <<EOF > pvc.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: tekton-logs
  namespace: tekton-pipelines
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi
EOF
// Apply the above PVC
kubectl apply -f pvc.yaml

Check the status of installation using following command
```
kubectl get tektonresults.operator.tekton.dev
```

Spec

The TektonResult CR is like below:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonResult
metadata:
  name: result
spec:
  targetNamespace: tekton-pipelines
  db_host: localhost
  db_port: 5342
  db_sslmode: verify-full
  db_sslrootcert: /etc/tls/db/ca.crt
  db_enable_auto_migration: true
  db_secret_name: # optional: custom database secret name
  db_secret_user_key: # optional
  db_secret_password_key: # optional
  log_level: debug
  logs_api: true
  logs_type: File
  logs_buffer_size: 32768
  logs_path: /logs
  auth_disable: true
  logging_pvc_name: tekton-logs
  secret_name: # optional
  gcs_creds_secret_name: <value>
  gcc_creds_secret_key: <value>
  gcs_bucket_name: <value>
  is_external_db: false
  loki_stack_name: #optional
  loki_stack_namespace: #optional
  prometheus_port: 9090
  prometheus_histogram: false

These properties are analogous to the one in configmap of tekton results api tekton-results-api-config documented at api.md

Property “route_tls_termination” (OpenShift only)

On OpenShift, the operator exposes the Results API through an OpenShift Route. The route_tls_termination property controls how TLS is terminated on that route:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonResult
metadata:
  name: result
spec:
  route_tls_termination: reencrypt

If the property is left empty, the operator defaults it to reencrypt.

Only reencrypt is supported. The Results API pod serves HTTPS only. reencrypt terminates TLS at the router and re-encrypts traffic to the HTTPS backend, giving correct end-to-end TLS. It is the default and the recommended value.

Other values are not recommended. edge terminates TLS at the router and forwards plain HTTP to the HTTPS-only backend; this breaks the route outright and no client flag can fix it (--insecure only disables the client’s verification of the router certificate, it cannot repair the router-to-backend connection). passthrough also produces a working route, but the client connects directly to the backend, which presents the OpenShift service-serving certificate; clients must therefore trust the cluster’s service CA (or pass --insecure).

With reencrypt the client sees the ingress router certificate instead. Note this is not necessarily publicly trusted either — by default the ingress certificate is cluster-signed, so clients may still need the cluster’s ingress CA (or --insecure) unless the router is configured with a publicly trusted certificate. The advantage of reencrypt is that it works out of the box and keeps end-to-end TLS; do not change this property away from reencrypt.

Note: On upgrade, existing installs that still carry the previous edge default are automatically migrated to reencrypt.

Property “secret_name”:

secret_name - name of your custom secret or leave it as empty. It an optional property. The secret should be created by the user on the targetNamespace. The secret can contain S3_ prefixed keys from the result API properties. Please note: the key of the secret should be in UPPER_CASE and values should be in string format. The following keys are supported by this secret.

S3_BUCKET_NAME
S3_ENDPOINT
S3_HOSTNAME_IMMUTABLE
S3_REGION
S3_ACCESS_KEY_ID
S3_SECRET_ACCESS_KEY
S3_MULTI_PART_SIZE

Sample Secret File

apiVersion: v1
kind: Secret
metadata:
  name: my_custom_secret
  namespace: tekton-pipelines
type: Opaque
stringData:
  S3_BUCKET_NAME: foo
  S3_ENDPOINT: https://example.localhost.com
  S3_HOSTNAME_IMMUTABLE: "false"
  S3_REGION: region-1
  S3_ACCESS_KEY_ID: "1234"
  S3_SECRET_ACCESS_KEY: secret_key
  S3_MULTI_PART_SIZE: "5242880"

GCS specific Property

The follow keys are needed for enabling GCS storage of logs:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonResult
metadata:
  name: result
spec:
  gcs_creds_secret_name: <value>
  gcc_creds_secret_key: <value>
  gcs_bucket_name: <value>

We need to create a secret with google application creds for a bucket foo-bar like below:

kubectl create secret generic gcs-credentials --from-file=creds.json

To know more about Application Default Credentials in creds.json that is use to create above secret for GCS, please visit: https://cloud.google.com/docs/authentication/application-default-credentials

In the above example, our properties are:

gcs_creds_secret_name: gcs-credentials
gcc_creds_secret_key: creds.json
gcs_bucket_name: foo-bar

External DB

It is not recommended to use internal DB, operator hard code PVC configuration and DB settings.

If you want to move from internal DB to external DB, please take backup of the DB. If you want to start fresh, then delete previous TektonResult CR. and recreate the fresh one with following instructions:

Generate a secret with user name and password for Postgres (subsitute ${password} with your password):

   export NAMESPACE="tekton-pipelines" # Put the targetNamespace of TektonResult where it is going to be installed.
   kubectl create secret generic tekton-results-postgres --namespace=${NAMESPACE} --from-literal=POSTGRES_USER=result --from-literal=POSTGRES_PASSWORD=${password}

Create a TektonResult CR like below:

Add db_host with DB url without port.
Add db_port with your DB port.
Set is_external_db to true.

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonResult
metadata:
  name: result
spec:
  targetNamespace: tekton-pipelines
  db_port: 5432
  db_user: result
  db_host: tekton-results-postgres-external-service.pg-redhat.svc.cluster.local
  is_external_db: true
...

Securing the DB connection

To secure the DB connection using self-segned certificate or using certificate signed by 3rd party CA (e.g AWS RDS), one can provide path to the DB SSL root certificate, mounted and available on the Results API pod. The configuration will look like:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonResult
metadata:
  name: result
spec:
  targetNamespace: tekton-pipelines
  db_host: tekton-results-postgres-service.openshift-pipelines.svc.cluster.local
  db_port: 5342
  db_sslmode: verify-full
  db_sslrootcert: /etc/tls/db/ca.crt
  ...

The valid options for db_sslmode are explained here https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-PROTECTION. To use any of the require, verify-ca and verify-full modes with self signed certificate, the path to the CA certificate which signed the DB certificate must be provided as db_sslrootcert.

LokiStack + TektonResult

Tekton Results leverages external Third Party APIs to query data. Storing of data via Tekton Results is inefficient and bad for performance. It’s better to use forwarders like Vector, Promtail, Fluentd for forwarding TaskRun pod Logs from nodes.

Kubernetes (GCP) + LokiStack/Loki

Loki

You can either use Grafana’s Helm Repo or operator from OperatorHub to install Loki. Installing via operator simplies certain operations for Tekton Operator. You just need to configure lokistack_name and lokistack_namespace.

In case of helm installation, you will need to configure options field to configure Results API configMap tekton-results-api-config:

LOGS_API
LOGGING_PLUGIN_PROXY_PATH
LOGGING_PLUGIN_API_URL
LOGGING_PLUGIN_TOKEN_PATH
LOGGING_PLUGIN_NAMESPACE_KEY
LOGGING_PLUGIN_STATIC_LABELS
LOGGING_PLUGIN_TLS_VERIFICATION_DISABLE
LOGGING_PLUGIN_FORWARDER_DELAY_DURATION
LOGGING_PLUGIN_QUERY_PARAMS
LOGGING_PLUGIN_QUERY_LIMIT

Please consult the docs here for information on these fields.

These fields allow you to configure how Tekton Results interacts with your Loki backend.

You might need to configure following environment variable to Tekton Results API deployment if you are using some custom CA to generate TLS certificate:

LOGGING_PLUGIN_CA_CERT

LOGGING_PLUGIN_FORWARDER_DELAY_DURATION: This is the max duration in minutes taken by third party logging system to forward and store the logs after completion of taskrun and pipelinerun. This is used to search between start time of runs and completion plus buffer duration.

Forwarder

You need to configure forwarder systems to add labels for namespace, pass TaskRun UID/PipelineRun UID in pods and a common label key:value alongwith logs from nodes.

A sample configuration for vector: values.yaml.

OpenShift (LokiStack + OpenShift Logging)

To configure LokiStack with TektonResult, you can use the lokistack_name and lokistack_namespace properties in the TektonResult custom resource. Here’s how to do it:

First, ensure that you have LokiStack installed in your cluster.
Then, create or update your TektonResult CR with the following properties:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonResult
metadata:
  name: result
spec:
  targetNamespace: tekton-pipelines
  // ... other properties ...
  lokistack_name: your-lokistack-name
  lokistack_namespace: your-lokistack-namespace

Replace your-lokistack-name with the name of your LokiStack instance and your-lokistack-namespace with the namespace where LokiStack is installed.

By setting these properties, Operator will configure Tekton Result to use the specified LokiStack instance for log retrieval.

OpenShift Logging

Install the openshift logging operator by following this: Deploying Cluster Logging

If you are installing OpenShift Logging Operator only for TaskRun Logs, then you also need to configure a ClusterLogForwarder:

apiVersion: "logging.openshift.io/v1"
kind: ClusterLogForwarder
metadata:
  name: instance
  namespace: openshift-logging
spec:
  inputs:
  - name: only-tekton
    application:
      selector:
        matchLabels:
          app.kubernetes.io/managed-by: tekton-pipelines
  pipelines:
    - name: enable-default-log-store
      inputRefs: [ only-tekton ]
      outputRefs: [ default ]

Tekton Result Watcher Performance Properties

Tekton Results Watcher can now be deployed using StatefulSet ordinals to partition work among replicas. When enabled, this feature uses stable pod identities (ordinals) to determine which pod is responsible for reconciling a given set of resources, instead of relying solely on traditional leader election. This can improve work distribution under load and provides a deterministic mechanism for controller coordination.

Results Watcher Performance Configuration

spec:
  # omitted other fields ...
  performance:
    disable-ha: false
    buckets: 1
    replicas: 1
    statefulset-ordinals: false

These fields are optional and there is no default values. If user passes them, operator will include most of fields into the tekton-results-watcher workload (Deployment by default, or StatefulSet when statefulset-ordinals is enabled) under the container watcher as arguments, otherwise results watcher controller’s default values will be considered. The buckets field is updated into tekton-results-config-leader-election config-map under the namespace tekton-pipelines.

disable-ha - enable or disable ha feature, defaults in results watcher controller is disable-ha=false
buckets - buckets is the number of buckets used to partition key space of each reconciler. If this number is M and the replica number of the controller is N, the N replicas will compete for the M buckets. The owner of a bucket will take care of the reconciling for the keys partitioned into that bucket. The maximum value of buckets at this time is 10. Default value in results watcher controller is 1. When statefulset-ordinals is enabled and replicas is greater than 1, buckets is automatically defaulted to match replicas (consistent with Pipeline’s behavior).
replicas - results watcher controller replicas count
statefulset-ordinals - enables StatefulSet Ordinals mode for the Tekton Results Watcher Controller. When set to true, the Results Watcher Controller is deployed as a StatefulSet instead of a Deployment, allowing for multiple replicas to be configured with a load-balancing mode. This ensures that the load is evenly distributed across replicas, and the number of buckets is enforced to match the number of replicas. Moreover, There are two mechanisms available for scaling Results Watcher Controller horizontally:

Using leader election, which allows for failover, but can result in hot-spotting.
Using StatefulSet ordinals, which doesn’t allow for failover, but guarantees load is evenly spread across replicas.

Note:

If you modify or remove any of the performance properties, the tekton-results-watcher workload (Deployment or StatefulSet) and tekton-results-config-leader-election config-map (if buckets changed) will be updated, and tekton-results-watcher pods will be recreated

Tekton Result Watcher Configuration

Watcher behavior is configured under spec.result.watcher on TektonConfig, or spec.watcher on TektonResult. These settings are passed as command-line flags to the tekton-results-watcher deployment. Updating these fields reconciles the watcher Deployment and recreates pods so the new configuration takes effect.

Performance-related flags remain under spec.result.performance (TektonConfig) / spec.performance (TektonResult). Operator-managed flags (api_addr, auth_mode, namespace) and secrets (token) are not exposed here.

For summary_labels, summary_annotations, and label_selector: omit the field to keep the watcher default, set a value to override, or set "" to clear the default.

spec:
  # omitted other fields ...
  watcher:
    completed_run_grace_period: 24h
    check_owner: true
    store_deadline: 10m
    disable_storing_incomplete_runs: true
    logs_api: true

See TektonConfig Result Watcher section for the full list of supported fields.

Debugging

Debugging gRPC

Set prometheus_histogram: true to turns on recording of handling time of RPCs. Histogram metrics can be very expensive for Prometheus to retain and query. Disabled by default.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Tekton Addon

TektonAddon custom resource allows user to install resource like resolverTasks, resolverStepActions, communityResolverTasks and pipelineTemplate along with Pipelines. It also allows user to install various Tasks in openshift-pipelines namespace.

NOTE: TektonAddon is currently available only for OpenShift Platform. This is roadmap to enable it for Kubernetes platform.

It is recommended to install the components through TektonConfig.

The TektonAddon CR is as below:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonAddon
metadata:
  name: addon
spec:
  targetNamespace: openshift-pipelines
  params:
  - name: pipelineTemplates
    value: "true"
  - name: resolverTasks
    value: "true"
  - name: resolverStepActions
    value: "true"
  - name: communityResolverTasks
    value: "true"

You can install this component using TektonConfig by choosing appropriate profile.

Params

params provide a way to enable/disable the installation of resources. Available params are

pipelineTemplates (Default: true)
resolverTasks (Default: true)
resolverStepActions (Default: true)
communityResolverTasks (Default: true)

User can disable the installation of resources by changing the value to false.

Pipelines templates uses tasks from openshift-pipelines. Therefore, to install pipelineTemplates, resolverTasks must be set to true

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Manual Approval Gate

ManualApprovalGate custom resource allows user to install and manage Manual Approval Gate.

ManualApprovalGate CR is as below

On Kubernetes, ManualApprovalGate CR is as below:

apiVersion: operator.tekton.dev/v1alpha1
kind: ManualApprovalGate
metadata:
  name: manual-approval-gate
spec:
  targetNamespace: tekton-pipelines

On OpenShift, ManualApprovalGate CR is as below:

apiVersion: operator.tekton.dev/v1alpha1
kind: ManualApprovalGate
metadata:
  name: manual-approval-gate
spec:
  targetNamespace: openshift-pipelines

Check the status of installation using following command:

kubectl get manualapprovalgates.operator.tekton.dev
NAME                   VERSION   READY   REASON
manual-approval-gate   v0.2.0    True

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Tekton Chain

TektonChain custom resource allows user to install and manage Tekton Chains.

It is recommended to install the component through TektonConfig.

TektonChain CR is as below

On Kubernetes, TektonChain CR is as below:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonChain
metadata:
  name: chain
spec:
  disabled: false
  targetNamespace: tekton-pipelines

On OpenShift, TektonChain CR is as below:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonChain
metadata:
  name: chain
spec:
  disabled: false
  targetNamespace: openshift-pipelines

Check the status of installation using following command:
```
kubectl get tektonchains.operator.tekton.dev
```

Chain Config

There are some fields which you can define on Tekton Chains CR to configure the behaviour of the chains If nothing is set, the operator sets these default properties: artifacts.taskrun.format: in-toto artifacts.taskrun.storage: oci artifacts.oci.storage: oci artifacts.oci.format: simplesigning artifacts.pipelinerun.format: in-toto artifacts.pipelinerun.storage: oci

Properties (Mandatory)

targetNamespace

Setting this field to provide the namespace in which you want to install the chains component.

Properties (Optional)

These fields don’t have default values so will be considered only if user passes them. By default, Operator won’t add these fields in CR and won’t configure for chains.

The Default values for some of these fields are already set in chains and are not set by Operator. If user passes some values then those will be set for the particular field.

Details of the field can be found in Tekton Chains Config

Chains CR will look like this after providing all the fields.

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonChain
metadata:
  name: chain
spec:
  disabled: false
  targetNamespace: tekton-pipelines
  generateSigningSecret: true # default value: false
  controllerEnvs:
    - name: MONGO_SERVER_URL      # This is the only field supported at the moment which is optional and when added by user, it is added as env to Chains controller
      value: #value               # This can be provided same as env field of container
  artifacts.taskrun.format: in-toto # default value: in-toto
  artifacts.taskrun.storage: tekton,oci (comma separated values) # default value: oci
  artifacts.taskrun.signer: x509
  artifacts.oci.storage: oci (comma separated values)
  artifacts.oci.format: simplesigning
  artifacts.oci.signer: x509
  artifacts.pipelinerun.format: in-toto # default value: in-toto
  artifacts.pipelinerun.storage: tekton,oci (comma separated values) # default value: oci
  artifacts.pipelinerun.signer: x509
  artifacts.pipelinerun.enable-deep-inspection: #value (boolean - true/false)
  storage.gcs.bucket: #value
  storage.oci.repository: #value
  storage.oci.repository.insecure: #value (boolean - true/false)
  storage.oci.encoding-format: #value (dsse or sigstore-bundle, default: dsse)
  storage.docdb.url: #value
  storage.docdb.mongo-server-url: #value
  storage.docdb.mongo-server-url-dir: #value
  storage.grafeas.projectid: #value
  storage.grafeas.noteid: #value
  storage.grafeas.notehint: #value
  builder.id: #value
  builddefinition.buildtype: #value
  signers.x509.fulcio.enabled: #value (boolean - true/false)
  signers.x509.fulcio.address: #value
  signers.x509.fulcio.issuer: #value
  signers.x509.fulcio.provider: #value
  signers.x509.identity.token.file: #value
  signers.x509.tuf.mirror.url: #value
  signers.kms.kmsref: #value
  signers.kms.auth.address: #value
  signers.kms.auth.token: #value
  signers.kms.auth.token-path: #value
  signers.kms.auth.oidc.path: #value
  signers.kms.auth.oidc.role: #value
  signers.kms.auth.spire.sock: #value
  signers.kms.auth.spire.audience: #value
  transparency.enabled: #value (boolean - true/false)
  transparency.url: #value

disabled : if the value set as true, chains feature will be disabled (default: false)
generateSigningSecret: When set to true, the operator will generate a cosign key pair (cosign.key as the private key, cosign.password as the password for decrypting private key and cosign.pub as the public key) and store them in the signing-secrets secret within the tekton-pipelines namespace. This secret is used by the Chains controller to sign Tekton artifacts (taskruns, pipelineruns). If the signing-secret is empty, enabling generateSigningSecret will create a new Cosign key pair and password. However, if the secret already contains data, enabling generateSigningSecret should not overwrite the existing secret. It is important to note that:

The user should retrieve and store the cosign.pub public key in a secure location verify later artifact attestations.
the operator doesnt provide any function about key rotation to limit potential security issues
the operator doesnt provide any function for auditing key usage
the operator doesnt provide any function for proper access control to the key

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Proxy Support

We have added the support for running the tekton components in a proxy environment through operator. This will enable running the tekton controllers, webhook and also taskrun pods with proxy configuration. We are attaching the proxy env variables like HTTP_PROXY, NO_PROXY and HTTPS_PROXY to the pods created through automation on the fly.

Note:

This funcationality will only be available for pods created using taskruns, not for all pods on clusters.

Proxy Support on Kubernetes

For enabling the proxy support on Kubernetes, users need to update the operator deployment with proxy environment variables like

spec:
  containers:
    - env:
        - name: HTTP_PROXY
          value: "url-to-be-pasted-here"

This will restart the operator pod, ending up in proxy environment variables attached to all components pods. Also whenever you run a taskrun, the resulting pod will also be having the environment variables in all containers.

This functionality of adding proxy environment variables is not available on taskruns created in tekton-pipelines namespace.

Proxy Support on OpenShift

For enabling proxy support on OpenShift environment, configure the proxy environments on OpenShift like mentioned here. After that install the operator through Operator Hub, and proxy environment variables will be available in tekton component’s controllers and webhook pod, also all taskrun pods created will also have the these environments

By default, openshift-pipelines namespace is exempted from adding the proxy environment varaibles in taskrun pods

Configuring namespace to be exempted from proxy environment feature

By default, the automation of adding proxy environment variables to taskrun pod is available on all namespace except the namespace in which tekton components are installed.

If you want to disable this feature in any other namespace, you can update the namespace object with following label

operator.tekton.dev/disable-proxy: true

Support for certificates for HTTPS proxy

TBD

Global opt-out option

If your cluster does not require proxy settings or CA bundle injection for Tekton TaskRun pods, you can disable the proxy webhook cluster-wide by setting the DISABLE_PROXY_WEBHOOK environment variable on the operator controller deployment to true. When enabled, the operator will not deploy the proxy webhook manifests and no proxy injection will occur.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

OpenShiftPipelinesAsCode

OpenShiftPipelinesAsCode custom resource allows the user to install and manage OpenShift PipelinesAsCode.

It is recommended that you install OpenShiftPipelinesAsCode through TektonConfig.

OpenShiftPipelinesAsCode CR is as below

On OpenShift, OpenShiftPipelinesAsCode CR is as below:

apiVersion: operator.tekton.dev/v1alpha1
kind: OpenShiftPipelinesAsCode
metadata:
  name: pipelines-as-code
spec:
  additionalPACControllers:
    controllername:
      enable: true
      configMapName:
      secretName:
      settings:
  enable: true
  settings:
    application-name: Pipelines as Code CI
    auto-configure-new-github-repo: "false"
    bitbucket-cloud-check-source-ip: "true"
    custom-console-name: ""
    custom-console-url: ""
    custom-console-url-pr-details: ""
    custom-console-url-pr-tasklog: ""
    error-detection-from-container-logs: "false"
    error-detection-max-number-of-lines: "50"
    error-detection-simple-regexp: ^(?P<filename>[^:]*):(?P<line>[0-9]+):(?P<column>[0-9]+):([
      ]*)?(?P<error>.*)
    error-log-snippet: "true"
    error-log-snippet-number-of-lines: "3"
    enable-cancel-in-progress-on-pull-requests: "false"
    enable-cancel-in-progress-on-push: "false"
    hub-catalog-name: tekton
    hub-url: https://api.hub.tekton.dev/v1
    require-ok-to-test-sha: "false"
    skip-push-event-for-pr-commits: "true"
    remote-tasks: "true"
    secret-auto-create: "true"
    secret-github-app-token-scoped: "true"
  targetNamespace: openshift-pipelines

Check the status of the installation using following command:
```
kubectl get openshiftpipelinesascodes.operator.tekton.dev
```

PipelinesAsCode Config

The recommended way to update the OpenShiftPipelinesAsCode CR is using TektonConfig CR.

Properties (Mandatory)

targetNamespace

Set this field to provide the namespace in which you want to install the PipelinesAsCode component.

Properties (Optional)

The fields have default values so even if the user has not passed them in CR, operator will add them. The user can later change them as per their need.

Details of the field can be found in OpenShift Pipelines As Code Settings

Remote Hub Catalogs

Pipelines as Code supports configuring remote hub catalogs to fetch tasks and pipelines. You can configure custom catalogs using the catalog-{INDEX}-* settings pattern.

Each custom catalog requires the following four fields:

Field	Description	Required
`catalog-{INDEX}-id`	Unique identifier for the catalog. Users reference tasks from this catalog using this ID as prefix (e.g., `custom://task-name`)	Yes
`catalog-{INDEX}-name`	Name of the catalog within the hub	Yes
`catalog-{INDEX}-url`	Full URL endpoint of the hub API	Yes
`catalog-{INDEX}-type`	Type of hub: `artifacthub` (for Artifact Hub) or `tektonhub` (for Tekton Hub)	Yes

Where {INDEX} is a number that can be incremented to add multiple catalogs (e.g., 1, 2, 3).

Example: Configuring a Custom Hub Catalog

apiVersion: operator.tekton.dev/v1alpha1
kind: OpenShiftPipelinesAsCode
metadata:
  name: pipelines-as-code
spec:
  enable: true
  settings:
    catalog-1-id: "custom"
    catalog-1-name: "tekton"
    catalog-1-url: "https://api.custom.hub/v1"
    catalog-1-type: "tektonhub"
  targetNamespace: openshift-pipelines

Example: Configuring Multiple Hub Catalogs

You can configure multiple hub catalogs by incrementing the catalog-{INDEX} number:

apiVersion: operator.tekton.dev/v1alpha1
kind: OpenShiftPipelinesAsCode
metadata:
  name: pipelines-as-code
spec:
  enable: true
  settings:
    catalog-1-id: "custom"
    catalog-1-name: "tekton"
    catalog-1-url: "https://api.custom.hub/v1"
    catalog-1-type: "tektonhub"
    catalog-2-id: "artifact"
    catalog-2-name: "tekton-catalog-tasks"
    catalog-2-url: "https://artifacthub.io"
    catalog-2-type: "artifacthub"
  targetNamespace: openshift-pipelines

Referencing Tasks from Custom Catalogs

Once configured, users can reference tasks from custom catalogs by adding a prefix matching the catalog ID:

pipelinesascode.tekton.dev/task: "custom://git-clone"
pipelinesascode.tekton.dev/task: "artifact://buildah"

Note: Pipelines-as-Code will not try to fallback to the default or another custom hub if the task referenced is not found (the Pull Request will be set as failed).

For more details, see the Pipelines-as-Code Remote Hub Catalogs documentation.

Additional Pipelines As Code Controller (Optional)

If users want to deploy additional Pipelines As Code controller on their cluster along with default Pipelines As Code controller then they need to provide the additionalPACControllers field in the pipelinesAsCode section.

Example:

pipelinesAsCode:
  additionalPACControllers: # can provide a list of controllers
    <controllername>: 
      enable:
      configMapName:
      secretName:
      settings:

controllername is the unique name of the new controller, should not be more than 25 characters and should follow k8s naming rules.
enable is optional with default value to true. You can use this field to disable the additional PAC controller without removing the details from the CR.
configMapName is optional and is to provide the ConfigMap name of additional PAC Controller. If user doesn’t provide any value then Operator will add controllerName + -pipelines-as-code-configmap as default value. If user provides configMap name as pipelines-as-code for additional Pipelines As Code controller, then operator will not create the configMap and the default pipeline-as-code configMap will be used with default settings.
secretName is optional and is to provide the secret name of additional PAC Controller. If user does not provide any value then operator will add controllerName + -pipelines-as-code-secret as default value to be added to deployment env.
settings is optional and used to set the settings in the configMap of additional PAC Controller. For the fields whose are not provided, default value will be used. You can check them here. Also, if configmap name is provided as pipelines-as-code then these settings will not be taken.

NOTE: Users can deploy multiple additional PAC Controller by providing multiple entries in additionalPACControllers field.

Example:

pipelinesAsCode:
  additionalPACControllers:
    firstcontroller:
      enable: true
    secondcontroller:
      enable: true
      configMapName: second-config
      secretName: second-secret

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Tekton Multicluster Proxy AAE

TektonMulticlusterProxyAAE deploys the multicluster-proxy-aae component used in multi-cluster setups with Tekton Kueue and Kueue. The proxy runs on the Hub cluster and communicates with Spoke clusters (e.g. via MultiKueue).

It is recommended to install this component through TektonConfig by enabling Tekton Kueue with multi-cluster and setting the cluster role to Hub. TektonConfig will create and reconcile the TektonMulticlusterProxyAAE CR automatically; you do not need to create it manually when using TektonConfig.

When is TektonMulticlusterProxyAAE installed?

TektonConfig creates and manages TektonMulticlusterProxyAAE only when all of the following are true:

Tekton Kueue is not disabled (spec.kueue.disabled is not true).
Multi-cluster is enabled (spec.kueue.multi-cluster-disabled is false).
Cluster role is Hub (spec.kueue.multi-cluster-role is Hub).

On Spoke clusters, leave multi-cluster-role as Spoke; the proxy is not installed there.

Prerequisites

The proxy is only installed when the Tekton Kueue is enabled with multi-cluster (Hub role). cert-manager and Kueue (and MultiKueue for the proxy) are required for Tekton Kueue and multi-cluster in general; you must install them before enabling Tekton Kueue. For full prerequisites and multi-cluster configuration, see Tekton Kueue. TektonConfig (Tekton Kueue section) also summarizes this and points to Tekton Kueue.

If you see a config status error such as:

Components not in ready state: Please install cert-manager (cert-manager.io/v1) First, the server could not find the requested resource

cert-manager is not installed or its APIs are not available. Install cert-manager (v1 API) and ensure Kueue (and for the proxy, MultiKueue) are installed as described in Tekton Kueue, then re-apply or reconcile TektonConfig.

The proxy’s readiness endpoint returns ready only when at least one worker cluster is registered; ensure you have at least one valid MultiKueueCluster (and corresponding kubeconfig secret in kueue-system) if you want the proxy to report Ready.

TektonMulticlusterProxyAAE CR

The TektonMulticlusterProxyAAE CR is cluster-scoped. When managed by TektonConfig, the operator creates a single instance named multicluster-proxy-aae.

Example (for reference; TektonConfig creates this when kueue multi-cluster Hub is enabled):

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonMulticlusterProxyAAE
metadata:
  name: multicluster-proxy-aae
spec:
  targetNamespace: tekton-pipelines   # or openshift-pipelines on OpenShift
  options: {}

Properties

targetNamespace: Namespace where the proxy deployment and related resources are installed (e.g. tekton-pipelines or openshift-pipelines). Set via TektonConfig when the CR is created by the operator.
options: Optional AdditionalOptions for customizing deployments, ConfigMaps, or webhook configuration.

Checking installation status

kubectl get tektonmulticlusterproxyaaes.operator.tekton.dev
# or
oc get tektonmulticlusterproxyaaes.operator.tekton.dev

Check the proxy deployment and pods in the target namespace (e.g. openshift-pipelines or tekton-pipelines):

kubectl get deployment -n <target-namespace> -l app.kubernetes.io/component=proxy-aae
kubectl get pods -n <target-namespace> -l app.kubernetes.io/component=proxy-aae

Standalone installation

If you are not using TektonConfig (e.g. you manage kueue and multi-cluster yourself), you can create a TektonMulticlusterProxyAAE CR manually. Ensure the cluster has Kueue and MultiKueue APIs and that the operator is installed; the operator will reconcile the CR and deploy the proxy in the specified targetNamespace.

TektonConfig – Tekton Kueue and TektonMulticlusterProxyAAE section
Tekton Kueue – Multi-cluster configuration (Hub / Spoke)
Kueue and MultiKueue

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

NetworkPolicy

The operator can manage NetworkPolicy resources for Tekton component workloads. TektonPipeline (core controllers, resolvers, and proxy-webhook), TektonTrigger, TektonChain, Pipelines-as-Code, ManualApprovalGate, TektonPruner, TektonResult, and MultiCluster components (TektonKueue, TektonMulticlusterProxyAAE, SyncerService) are supported; other components will be added later.

Configuration is available via TektonConfig:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  networkPolicy:
    disabled: false          # set to true to remove all managed NetworkPolicies
    policies:                # override or add policies by name
      triggers-controller:   # replaces the default triggers-controller policy
        podSelector:
          matchLabels:
            app: tekton-triggers-controller
        policyTypes: [Ingress]
        ingress:
          - ports:
              - port: 9000

The networkPolicy field is propagated from TektonConfig to TektonPipeline, TektonTrigger, TektonChain, TektonPruner, TektonResult, Pipelines-as-Code, and MultiCluster components. When those component CRs are managed by TektonConfig (the usual install path), TektonConfig is the source of truth: edits to spec.networkPolicy on the component CRs alone are overwritten on the next Config reconcile. Configure NetworkPolicy via TektonConfig.spec.networkPolicy.

Default Policies

When NetworkPolicy is enabled (the default), the following policies are applied to the operand namespace (e.g. tekton-pipelines or openshift-pipelines):

TektonPipeline

Policy	Direction	Port	Source / Destination
`pipeline-default-deny`	deny all	—	All pods with `app.kubernetes.io/part-of: tekton-pipelines`
`pipeline-controller`	ingress	TCP/9090	Prometheus namespace
	egress	UDP+TCP/53 (K8s) or 5353 (OpenShift)	DNS resolver pods
	egress	all	API server (all egress allowed — NP cannot select host-network endpoints)
`pipeline-webhook`	ingress	TCP/8443	Any (admission webhook)
	ingress	TCP/9090	Prometheus namespace
	egress	UDP+TCP/53 or 5353	DNS resolver pods
	egress	all	API server (all egress allowed — NP cannot select host-network endpoints)
`pipeline-events-controller`	ingress	TCP/9090	Prometheus namespace
	egress	UDP+TCP/53 or 5353	DNS resolver pods
	egress	all	API server (all egress allowed — NP cannot select host-network endpoints)
	egress	TCP/80, 443	Any (CloudEvents sinks)
`pipeline-resolvers`	ingress	TCP/8080	Pipeline controller pods
	ingress	TCP/9090	Prometheus namespace
	egress	UDP+TCP/53 or 5353	DNS resolver pods
	egress	all	API server (all egress allowed — NP cannot select host-network endpoints)
	egress	TCP/80, 443	Any (git HTTPS, OCI registries, Tekton Hub, http resolver)
	egress	TCP/22	Any (git clone over SSH)
`tekton-proxy-webhook-default-deny`	deny all	—	All pods with `name: tekton-operator` (proxy-webhook)
`proxy-webhook`	ingress	TCP/8443	Any (admission webhook)
	egress	UDP+TCP/53 or 5353	DNS resolver pods
	egress	all	API server (all egress allowed — NP cannot select host-network endpoints)

TektonTrigger

Policy	Direction	Port	Source / Destination
`tekton-default-deny`	deny all	—	All pods with `app.kubernetes.io/part-of: tekton-triggers`
`triggers-controller`	ingress	TCP/9000	Prometheus namespace
	egress	UDP+TCP/53 (K8s) or 5353 (OpenShift)	DNS resolver pods
	egress	all	API server (all egress allowed — NP cannot select host-network endpoints)
`triggers-webhook`	ingress	TCP/8443	Any (admission webhook)
	ingress	TCP/9000	Prometheus namespace
	egress	UDP+TCP/53 or 5353	DNS resolver pods
	egress	all	API server (all egress allowed — NP cannot select host-network endpoints)
`triggers-core-interceptors`	ingress	TCP/8443	All namespaces (EventListeners)
	ingress	TCP/9000	Prometheus namespace
	egress	UDP+TCP/53 or 5353	DNS resolver pods
	egress	all	API server (all egress allowed — NP cannot select host-network endpoints)
	egress	TCP/80, 443	Any (external APIs e.g. GitHub)

TektonChain

Policy	Direction	Port	Source / Destination
`chains-controller-default-deny`	deny all	—	All pods matching Chains controller selector
`chains-controller`	ingress	TCP/9090	Prometheus namespace
	egress	all	Unrestricted (API server, OCI registries, Sigstore, KMS, storage backends — NP cannot select host-network endpoints)

OpenShift Pipelines-as-Code

Policy	Direction	Port	Source / Destination
`pac-default-deny`	deny all	—	All pods with `app.kubernetes.io/part-of: pipelines-as-code`
`pac-controller`	ingress	TCP/9090	Prometheus namespace
	ingress	TCP/8082	Any (Git provider webhooks via Route/Ingress)
	egress	UDP+TCP/53 (K8s) or 5353 (OpenShift)	DNS resolver pods
	egress	all	API server (all egress allowed — NP cannot select host-network endpoints)
	egress	TCP/80, 443	Any (Git provider APIs: GitHub, GitLab, Bitbucket, Gitea)
`pac-watcher`	ingress	TCP/9090	Prometheus namespace
	egress	UDP+TCP/53 or 5353	DNS resolver pods
	egress	all	API server (all egress allowed — NP cannot select host-network endpoints)
	egress	TCP/80, 443	Any (reporting status to Git providers)
`pac-webhook`	ingress	TCP/8443	Any (admission webhook)
	ingress	TCP/9090	Prometheus namespace
	egress	UDP+TCP/53 or 5353	DNS resolver pods
	egress	all	API server (all egress allowed — NP cannot select host-network endpoints)

ManualApprovalGate

Policy	Direction	Port	Source / Destination
`mag-default-deny`	deny all	—	All pods with `app.kubernetes.io/part-of: openshift-pipelines-manual-approval-gates`
`mag-controller`	ingress	TCP/9090	Prometheus namespace
	egress	UDP+TCP/53 (K8s) or 5353 (OpenShift)	DNS resolver pods
	egress	all	API server (all egress allowed — NP cannot select host-network endpoints)
`mag-webhook`	ingress	TCP/8443	Any (admission webhook)
	ingress	TCP/9090	Prometheus namespace
	egress	UDP+TCP/53 or 5353	DNS resolver pods
	egress	all	API server (all egress allowed — NP cannot select host-network endpoints)

The networkPolicy field is available directly on the ManualApprovalGate CR (MAG is a standalone CR, not managed through TektonConfig):

apiVersion: operator.tekton.dev/v1alpha1
kind: ManualApprovalGate
metadata:
  name: manual-approval-gate
spec:
  networkPolicy:
    disabled: false

TektonPruner

Policy	Direction	Port	Source / Destination
`tekton-pruner-default-deny`	deny all	—	All pods with `app.kubernetes.io/part-of: tekton-pruner`
`pruner-controller`	ingress	TCP/9090	Prometheus namespace
	egress	UDP+TCP/53 or 5353	DNS resolver pods
	egress	all	API server (all egress allowed — NP cannot select host-network endpoints)
`pruner-webhook`	ingress	TCP/8443	Any (admission webhook)
	ingress	TCP/9090	Prometheus namespace
	egress	UDP+TCP/53 or 5353	DNS resolver pods
	egress	all	API server (all egress allowed — NP cannot select host-network endpoints)

TektonResult

Policy	Direction	Port	Source / Destination
`results-default-deny`	deny all	—	Pods with `app.kubernetes.io/name` in Results API, watcher, retention-policy-agent, postgres
`results-api`	ingress	TCP/8080	All namespaces (Console Plugin, CLI, routes, watcher, internal clients)
	ingress	TCP/9090	Prometheus namespace
	egress	UDP+TCP/53 (K8s) or 5353 (OpenShift)	DNS resolver pods
	egress	TCP/`db_port` (default 5432)	Any destination (in-cluster or external DB; port from Results Spec)
	egress	all	API server (auth token review / impersonation)
`results-watcher`	ingress	TCP/9090	Prometheus namespace
	egress	UDP+TCP/53 (K8s) or 5353 (OpenShift)	DNS resolver pods
	egress	all	API server (all egress allowed — NP cannot select host-network endpoints; also covers Results API)
`results-retention-policy-agent`	egress	UDP+TCP/53 or 5353	DNS resolver pods
	egress	TCP/`db_port` (default 5432)	Any destination (in-cluster or external DB)
`results-postgres`	ingress	TCP/`db_port`	Results API and retention-policy-agent pods only
	egress	UDP+TCP/53 or 5353	DNS resolver pods

API and retention DB egress is port-only (no pod/CIDR peer). NetworkPolicy cannot match on hostname or JDBC URL, so restricting To to in-cluster postgres pods would break external databases. Configure db_host / db_port as usual; when db_port changes in the Results Spec, the operator regenerates these policies on reconcile. No custom NetworkPolicy is required for an external database.

Administrative / debug access to in-cluster Postgres

results-postgres ingress allows only Results API and retention-policy-agent pods. One-off workloads (DB migrations, psql debug pods) are otherwise dropped once NetworkPolicy is enabled.

Recommended: add a dedicated temporary NetworkPolicy that allows a dedicated admin label. Do not reuse app: tekton-results-api on a debug pod — that label is also used by the Results API Service selector and can route API traffic to the wrong pod. A dedicated label (below) avoids that.

Apply directly:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: results-postgres-admin
  namespace: tekton-pipelines   # or openshift-pipelines
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/name: tekton-results-postgres
  policyTypes: [Ingress]
  ingress:
    - from:
        - podSelector:
            matchLabels:
              app: tekton-results-db-admin
      ports:
        - protocol: TCP
          port: 5432   # match Spec db_port when customized

Or the same rule via spec.networkPolicy.policies (use a new name so you do not replace a managed default):

spec:
  networkPolicy:
    policies:
      results-postgres-admin:
        podSelector:
          matchLabels:
            app.kubernetes.io/name: tekton-results-postgres
        policyTypes: [Ingress]
        ingress:
          - from:
              - podSelector:
                  matchLabels:
                    app: tekton-results-db-admin
            ports:
              - protocol: TCP
                port: 5432

Label the migration/psql pod with app: tekton-results-db-admin, then remove the policy (or the policies entry) when finished.

Emergency only: temporarily set spec.networkPolicy.disabled: true (on TektonConfig when Config manages Results), run the admin work, then set disabled: false again. Prefer the dedicated admin NetworkPolicy above so other workloads stay locked down.

Console Plugin (OpenShift only)

The console plugin is a static file server (nginx) — all API calls run in the user’s browser via the OpenShift Console’s proxy, not on this pod.

Policy	Direction	Port	Source / Destination
`pipelines-console-plugin-deny`	deny all	—	All pods with `app: pipelines-console-plugin`
`pipelines-console-plugin`	ingress	TCP/8443	`openshift-console` namespace

These are static manifests shipped with the TektonConfig console plugin resources, not reconciled via spec.networkPolicy.

TektonKueue

Policies are applied to the operand namespace (tekton-pipelines or openshift-pipelines). Policy names retain the scheduler- prefix for compatibility.

Policy	Direction	Port	Source / Destination
`scheduler-controller-default-deny`	deny all	—	Tekton Kueue controller pods
`scheduler-webhook-default-deny`	deny all	—	Tekton Kueue webhook pods
`scheduler-controller`	ingress	TCP/8443	Prometheus namespace
	egress	UDP+TCP/53 (K8s) or 5353 (OpenShift)	DNS resolver pods
	egress	all	API server (all egress allowed — NP cannot select host-network endpoints)
`scheduler-webhook`	ingress	TCP/9443	Any (admission webhook)
	ingress	TCP/8443	Prometheus namespace
	egress	UDP+TCP/53 or 5353	DNS resolver pods
	egress	all	API server (all egress allowed — NP cannot select host-network endpoints)

TektonMulticlusterProxyAAE

Policies are applied to the operand namespace (tekton-pipelines or openshift-pipelines). Deployed only when Tekton Kueue is enabled with multi-cluster role = Hub.

Policy	Direction	Port	Source / Destination
`proxy-aae-default-deny`	deny all	—	Proxy-AAE pods (`app: proxy-aae`)
`proxy-aae`	ingress	TCP/8080	Any (spoke clusters connect via service 443→8080)
	egress	UDP+TCP/53 (K8s) or 5353 (OpenShift)	DNS resolver pods
	egress	all	API server (all egress allowed — NP cannot select host-network endpoints)

SyncerService (OpenShift only)

Policies are applied to the operand namespace (openshift-pipelines). Deployed only when Tekton Kueue is enabled with multi-cluster role = Hub.

Policy	Direction	Port	Source / Destination
`syncer-service-default-deny`	deny all	—	SyncerService pods (`app: workload-controller`)
`syncer-service-controller`	egress	UDP+TCP/5353	DNS resolver pods (OpenShift)
	egress	all	API server (all egress allowed — NP cannot select host-network endpoints)

All component policies (TektonPipeline, TektonTrigger, TektonKueue, TektonMulticlusterProxyAAE, SyncerService, and Console Plugin) are applied to the operand namespace (e.g. tekton-pipelines or openshift-pipelines).

Platform differences

Parameter	Kubernetes	OpenShift
DNS port	53	5353
DNS namespace	`kube-system`	`openshift-dns`
Prometheus namespace label	`kubernetes.io/metadata.name: monitoring`	`openshift.io/cluster-monitoring: "true"`

Disabling

spec:
  networkPolicy:
    disabled: true

This removes all managed NetworkPolicies from the operand namespace.

Overriding a policy

Entries in spec.networkPolicy.policies replace or add policies by name. To override a default policy, use the same name (e.g. triggers-controller). New names add additional policies alongside the defaults.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Tekton Pruner

TektonPruner is a custom resource that enables users to install and manage the Tekton Pruner component for event-driven cleanup of Tekton resources.

Note: It is recommended to install Tekton Pruner via the TektonConfig resource for consistency and ease of configuration.

Important: The job-based pruner must be disabled for the event-based pruner to be enabled. Both pruners cannot be enabled simultaneously.

TektonPruner Custom Resource

Example of a TektonPruner Custom Resource (CR):

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonPruner
metadata:
  name: pruner
spec:
  targetNamespace: tekton-pipelines
  disabled: false
  global-config:
    enforcedConfigLevel: global
    historyLimit: 100
    ttlSecondsAfterFinished: 3600
    successfulHistoryLimit: 50
    failedHistoryLimit: 20

On OpenShift, the targetNamespace should be set to openshift-pipelines.

Check the status of installation:

kubectl get tektonpruners.operator.tekton.dev

TektonConfig Pruner Configuration

Default configuration when using TektonConfig:

pruner:
  disabled: true  # Disable job-based pruner

tektonpruner:
  disabled: false
  global-config:
    enforcedConfigLevel: global
    historyLimit: 100
    ttlSecondsAfterFinished: null
    successfulHistoryLimit: null
    failedHistoryLimit: null
  options: {}

Configuration Levels

global: Cluster-wide defaults apply to all namespaces (no namespace overrides)
namespace: Allows namespace-level overrides via ConfigMaps

Pruning Fields

The pruner deletes runs when any one of the specified conditions is met:

historyLimit: Maximum number of runs to retain for each status (applies independently to both successful and failed runs)
successfulHistoryLimit: Maximum number of successful runs to retain
failedHistoryLimit: Maximum number of failed runs to retain
ttlSecondsAfterFinished: Time in seconds to retain completed runs before pruning

Note: If successfulHistoryLimit or failedHistoryLimit is not specified, historyLimit value is used as fallback.

Example Configuration

tektonpruner:
  disabled: false
  global-config:
    enforcedConfigLevel: namespace
    historyLimit: 100
    ttlSecondsAfterFinished: 3600
    namespaces:
      dev:
        historyLimit: 50
        ttlSecondsAfterFinished: 1800
      prod:
        successfulHistoryLimit: 200
        failedHistoryLimit: 50

Namespace-Level Configuration

When enforcedConfigLevel is set to namespace, individual namespaces can override pruning settings using a ConfigMap.

Configuration Precedence: If a namespace has configurations defined in both the global config (under namespaces section) and a namespace-level ConfigMap, the namespace-level ConfigMap values take precedence.

Create a ConfigMap named tekton-pruner-namespace-spec in the target namespace:

apiVersion: v1
kind: ConfigMap
metadata:
  name: tekton-pruner-namespace-spec
  namespace: my-namespace
data:
  ns-config: |
    historyLimit: 100
    ttlSecondsAfterFinished: 7200
    pipelineRuns:
      - name: critical-pipeline
        successfulHistoryLimit: 500
        failedHistoryLimit: 100
      - selector:
          - matchLabels:
              env: production
        ttlSecondsAfterFinished: 604800
    taskRuns:
      - name: cleanup-task
        historyLimit: 10
      - selector:
          - matchLabels:
              type: test
        ttlSecondsAfterFinished: 3600

Learn More

For detailed configuration options, tutorials, and advanced use cases, refer to the Tekton Pruner Getting Started Guide.

For source code and additional information, visit the Tekton Pruner GitHub repository.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Configuring SCC used for Tekton workloads in OpenShift

Security Context Constraints (SCCs) are used to control permissions for pods in a cluster.

By default, the operator uses a custom SCC called pipelines-scc for all Tekton workloads run on OpenShift. pipelines-scc is primarily derived from the anyuid SCC which allows users to run with any UID and GID, and hence is not ideal for some, if not most users given the relaxed permissions allotted to all workloads. Besides, pipelines-scc also allows SETFCAP Linux capability to be requested by workloads. Historically, these relaxed permissions were provided to all Tekton workloads to support use cases like building container images via Tekton.

This document describes how to configure the default SCC and other SCC related configurations to better suit user’s Tekton workloads.

How to change SCC applied to Tekton workloads

Internally, the operator creates a service account (SA) named pipeline and attaches pipelines-scc to it by default. The pipeline SA is attached to all Tekton workloads by the operator and this is how the permissions percolate from the attached SCC to the workload pods.

Now the users can attach a different SA to their workloads as well and hence pipelines-scc will not take effect for those workloads, instead the SCC attached to that SA will take effect.

Configure default and maximum allowed SCC via TektonConfig

Note: Before we look at how to configure default SCC via the operator, it’s worth noting that this feature makes it convenient for users to configure default SCC but it does not restrict users from attaching a different SCC via a different SA to their workloads - and this different SCC could be more restrictive or permissive than the default SCC. So, setting the default SCC should not be considered a security control that prohibits users from applying a different SCC to their Tekton workloads, instead it’s just a way to specify default SCC applied by the operator.

To understand how to configure a default and maximum allowed SCC, let’s look at an example TektonConfig configuration.

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  ...
  ...
  platforms:
    openshift:
      scc:
        default: "restricted-v2"
        maxAllowed: "privileged"

spec.platforms.openshift.scc.default specifies the default SCC that will be attached to the service account used for workloads (pipeline SA by default)
spec.platforms.openshift.scc.maxAllowed specifies the highest (least restrictive) SCC that can be requested via a namespace annotation

If maxAllowed is not set, the operator defaults it to the value of default. This means that, out of the box, a namespace can only request an SCC that is equally or more restrictive than the default SCC. To allow a namespace to request a less restrictive SCC (for example anyuid), you must explicitly set maxAllowed to that SCC (or a less restrictive one) in TektonConfig.

Security note: In earlier releases, leaving maxAllowed empty allowed a namespace to request any SCC — including privileged — via the operator.tekton.dev/scc annotation. This allowed privilege escalation and has been fixed: an empty maxAllowed is now treated as “only the default SCC is allowed”.

Note that the SCC specified in default field cannot be of a higher priority than the one specified in maxAllowed field.

How are SCCs compared

OpenShift uses a prioritization logic to compare and sort SCCs from most restrictive to least restrictive. More on this can be read here.

Configuring default SCC for a specific namespace

If users wish to configure a different SCC for Tekton workloads to be run in a particular namespace, they can do so by adding the annotation operator.tekton.dev/scc: <SCC name> to their namespace.

Example:

apiVersion: v1
kind: Namespace
metadata:
  name: test-namespace
  annotations:
    operator.tekton.dev/scc: nonroot

In this example, in the namespace test-namespace all the Tekton workload pods will have the effective SCC as nonroot irrespective of the default SCC set in TektonConfig.

A use case for specifying a different SCC for a given namespace could be building containers with Tekton. Building containers with, say, buildah in Tekton needs elevated privileges like running as root and elevated Linux capabilities. Users can request for anyuid SCC in one namespace without impacting permissions of Tekton workloads running in other namespaces.

Requesting a less restrictive SCC such as anyuid this way requires maxAllowed to permit it. Because maxAllowed defaults to the default SCC (pipelines-scc by default), you must first set spec.platforms.openshift.scc.maxAllowed to anyuid (or a less restrictive SCC) in TektonConfig; otherwise the namespace annotation is rejected.

Note: The SCC requested by the operator.tekton.dev/scc annotation can not have a higher priority (be less restrictive) than the one specified in TektonConfig.Spec.Platforms.OpenShift.SCC.MaxAllowed. If maxAllowed is not set, it defaults to the default SCC, so only the default SCC (or a more restrictive one) can be requested via the annotation.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Installing Tekton Operator

To configure images from a custom registry, follow the Air Gap Configuration guide.

Install operator

$ kubectl apply -f https://infra.tekton.dev/tekton-releases/operator/latest/release.yaml

Note: This will also install pipelines, triggers, chains, and dashboard

In case you want to install other components, use available installation profiles: lite , all, basic

Where

Platform	Profile	Installed Component
Kubernetes, OpenShift	lite	Pipeline
Kubernetes, OpenShift	basic	Pipeline, Trigger, Chains
Kubernetes	all	Pipeline, Trigger, Chains, Dashboard
OpenShift	all	Pipeline, Trigger, Chains, Pipelines as Code, Addons

To install pipelines, triggers, chains and dashboard (use profile ‘all’)

$ kubectl apply -f https://raw.githubusercontent.com/tektoncd/operator/main/config/crs/kubernetes/config/all/operator_v1alpha1_config_cr.yaml

Platform notes

OpenShift: do not run pipelines in the `default` namespace

On OpenShift, the default namespace is classified as a “highly privileged” system namespace. Pod Security Admission (PSA) label synchronization is permanently disabled there by the platform, so even though the operator correctly creates the pipeline ServiceAccount and RBAC bindings in default, PipelineRuns submitted to that namespace fail with permissionDenied errors: PSA enforces the restricted profile and the SCC-to-PSA label sync never runs.

User-created namespaces are not affected because the Cluster Policy Controller automatically syncs SCC privileges into PSA labels. The OpenShift documentation has the same guidance (Do not run workloads in or share access to default projects).

Run pipelines in a dedicated namespace instead of default on OpenShift. See tektoncd/operator#3427 for the original report.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Air Gap environment (aka disconnected environment)

When we have our cluster on a air gap or proxy environment, we need to copy the actual images into our custom registry and update image details via environment variables on the operator deployment under the container tekton-operator-lifecycle as follows, This will allow us to use images from our custom registry.

Rewrite image registry

You can rewrite the registry host of all images managed by the operator by setting the TEKTON_REGISTRY_OVERRIDE environment variable on the tekton-operator-lifecycle container. This keeps the original repository path and tag/digest, and only changes the registry host.

If not set, no change is applied (default behavior).

We can rewrite the actual registry ghcr.io of all images by simply set the environment variable TEKTON_REGISTRY_OVERRIDE ad follow:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: tekton-operator
  namespace: tekton-operator
spec:
  template:
    spec:
      containers:
        - name: tekton-operator-lifecycle
          env:
            # Optional: globally rewrite registry host for all images
            - name: TEKTON_REGISTRY_OVERRIDE
              value: my-internal-registry.io/my-tekton-folder
            # You can still specify per-image values; their registry host will be rewritten to the override above
            - name: IMAGE_DASHBOARD_TEKTON_DASHBOARD
              value: ghcr.io/tektoncd/dashboard:v0.48.0

Behavior and precedence:

If TEKTON_REGISTRY_OVERRIDE is unset, images are taken from per-image env vars (if set) or from the shipped defaults.
If TEKTON_REGISTRY_OVERRIDE is set, the operator rewrites the registry host for all resolved images (from per-image env vars and defaults, including images with no matching per-image env var), for every component. The repository path and tag/digest are preserved.
There is currently no per-image opt-out when the global override is set. To exempt specific images, do not set TEKTON_REGISTRY_OVERRIDE and rely solely on per-image env vars.

Rewrite image one by one

We can also rewrite images one by one using the following:

Sample: images as environment variable in operator deployment

example.com/tektoncd/dashboard:v0.48.0
            - name: IMAGE_JOB_PRUNER_TKN
              value: custom-example.com/tektoncd/tkn:v0.31.0

Tekton instance update

Changing TEKTON_REGISTRY_OVERRIDE on an existing installation is picked up automatically: the operator refreshes the affected TektonInstallerSets on its next reconcile, no manual action needed.

If you instead change one of the per-image environment variables (IMAGE_*) without touching TEKTON_REGISTRY_OVERRIDE, you will need to refresh the TektonInstallerSets manually so the new value can be taken into account.

kubectl delete tektoninstallerset <installer-set-name>

List of image environment variables

Images supported in kubernetes

Component	Container/Args name	Environment Variable
Chains	tekton-chains-controller	`IMAGE_CHAINS_TEKTON_CHAINS_CONTROLLER`
Dashboard	tekton-dashboard	`IMAGE_DASHBOARD_TEKTON_DASHBOARD`
Manual Approval Gate	manual-approval	`IMAGE_MAG_MANUAL_APPROVAL`
Manual Approval Gate	tekton-taskgroup-controller	`IMAGE_MAG_TEKTON_TASKGROUP_CONTROLLER`
Pipeline	arg:entrypoint-image	`IMAGE_PIPELINES_ARG__ENTRYPOINT_IMAGE`
Pipeline	arg:git-image	`IMAGE_PIPELINES_ARG__GIT_IMAGE`
Pipeline	arg:nop-image	`IMAGE_PIPELINES_ARG__NOP_IMAGE`
Pipeline	arg:shell-image	`IMAGE_PIPELINES_ARG__SHELL_IMAGE`
Pipeline	arg:shell-image-win	`IMAGE_PIPELINES_ARG__SHELL_IMAGE_WIN`
Pipeline	arg:workingdirinit-image	`IMAGE_PIPELINES_ARG__WORKINGDIRINIT_IMAGE`
Pipeline	controller (resolvers controller)	`IMAGE_PIPELINES_CONTROLLER`
Pipeline	tekton-events-controller	`IMAGE_PIPELINES_TEKTON_EVENTS_CONTROLLER`
Pipeline	tekton-pipelines-controller	`IMAGE_PIPELINES_TEKTON_PIPELINES_CONTROLLER`
Pipeline	webhook	`IMAGE_PIPELINES_WEBHOOK`
Results	api	`IMAGE_RESULTS_API`
Results	postgres	`IMAGE_RESULTS_POSTGRES`
Results	watcher	`IMAGE_RESULTS_WATCHER`
Triggers	arg:el-image	`IMAGE_TRIGGERS_ARG__EL_IMAGE`
Triggers	tekton-triggers-controller	`IMAGE_TRIGGERS_TEKTON_TRIGGERS_CONTROLLER`
Triggers	tekton-triggers-core-interceptors	`IMAGE_TRIGGERS_TEKTON_TRIGGERS_CORE_INTERCEPTORS`
Triggers	webhook	`IMAGE_TRIGGERS_WEBHOOK`
Pipelines Proxy	webhook Proxy image	`IMAGE_PIPELINES_PROXY`
Pruner CronJob	image used in pruner cronJob	`IMAGE_JOB_PRUNER_TKN`
Tekton Pruner	image used by pruner controller	`IMAGE_PRUNER_CONTROLLER`
Tekton Pruner	image used by pruner webhook	`IMAGE_PRUNER_WEBHOOK`
Tekton Kueue	controller	`IMAGE_KUEUE_MANAGER`
Tekton Kueue	webhook	`IMAGE_KUEUE_WEBHOOK`
Multicluster Proxy AAE	proxy-aae	`IMAGE_MULTICLUSTERPROXYAAE_PROXY_AAE`
Syncer Service	workload-controller	`IMAGE_SYNCER_SERVICE_WORKLOAD_CONTROLLER`

Images supported in OpenShift

Supports all the images listed above in kubernetes and following are specific to OpenShift

Component	Container/Args name	Environment Variable
Pipeline-as-code	pac-controller	`IMAGE_PAC_PAC_CONTROLLER`
Pipeline-as-code	pac-webhook	`IMAGE_PAC_PAC_WEBHOOK`
Pipeline-as-code	pac-watcher	`IMAGE_PAC_PAC_WATCHER`
Console Plugin (PF5)	console-plugin	`IMAGE_PIPELINES_CONSOLE_PLUGIN_LEGACY`
Console Plugin (PF6)	console-plugin	`IMAGE_PIPELINES_CONSOLE_PLUGIN`
Results	retention-policy-agent	`IMAGE_RESULTS_RETENTION_POLICY_AGENT`
Addons		`IMAGE_ADDONS_BUILD`
Addons		`IMAGE_ADDONS_GENERATE`
Addons		`IMAGE_ADDONS_GEN_ENV_FILE`
Addons		`IMAGE_ADDONS_GIT_RUN`
Addons		`IMAGE_ADDONS_KN`
Addons		`IMAGE_ADDONS_LOAD_SCRIPTS`
Addons		`IMAGE_ADDONS_MAVEN_GENERATE`
Addons		`IMAGE_ADDONS_MAVEN_GOALS`
Addons		`IMAGE_ADDONS_MVN_SETTINGS`
Addons		`IMAGE_ADDONS_OC`
Addons		`IMAGE_ADDONS_PARAM_BUILDER_IMAGE`
Addons		`IMAGE_ADDONS_PARAM_GITINITIMAGE`
Addons		`IMAGE_ADDONS_PARAM_KN_IMAGE`
Addons		`IMAGE_ADDONS_PARAM_MAVEN_IMAGE`
Addons		`IMAGE_ADDONS_PARAM_TKN_IMAGE`
Addons		`IMAGE_ADDONS_PREPARE`
Addons		`IMAGE_ADDONS_REPORT`
Addons		`IMAGE_ADDONS_S2I_BUILD`
Addons		`IMAGE_ADDONS_S2I_GENERATE`
Addons		`IMAGE_ADDONS_SKOPEO_COPY`
Addons		`IMAGE_ADDONS_SKOPEO_RESULTS`
Addons		`IMAGE_ADDONS_TKN`
Addons		`IMAGE_ADDONS_TKN_CLI_SERVE`
Addons		`IMAGE_ADDONS_TKN_CLI_SERVE_INIT_CONFIG`

OpenShift Console Plugin Compatibility

When deploying the Tekton Operator on OpenShift Container Platform (OCP) with the console plugin enabled, you must account for your OCP version.

Starting with OpenShift 4.22, the console plugin was upgraded to use PatternFly 6 (PF6), while earlier versions use PatternFly 5 (PF5). To ensure compatibility, you need to provide both of the following environment variables:

IMAGE_PIPELINES_CONSOLE_PLUGIN: Point this to the PF6 image.

IMAGE_PIPELINES_CONSOLE_PLUGIN_LEGACY: Point this to the PF5 image.

Note: You do not need to manually configure which image to use at runtime. The operator will automatically detect your OCP version and deploy the correct console plugin image.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Centralized TLS Configuration Support

This change adds support for centralized TLS configuration from OpenShift’s APIServer resource, enabling Tekton components to inherit TLS settings (minimum version, cipher suites, curve preferences) from the cluster-wide security policy.

Key Changes

1. New Configuration Flag

Added EnableCentralTLSConfig boolean field to TektonConfig.Spec.Platforms.OpenShift
When enabled, TLS settings from the cluster’s APIServer are automatically injected into supported components
Default: false (opt-in)

2. APIServer Watcher

Single centralized watcher in TektonConfig controller monitors the APIServer cluster resource
Uses a shared informer with 30-minute resync interval
When APIServer TLS profile changes, enqueues TektonConfig for reconciliation

3. Platform Data Annotation

TektonConfig OpenShift extension resolves TLS config via GetPlatformData() and returns a SHA-256 hash of the TLS profile
The shared TektonConfig reconciler stamps this as an operator.tekton.dev/platform-data-hash annotation on sub-component CRs (e.g., TektonResult)
When the annotation value changes, the sub-component CR is updated, triggering its reconciler
The sub-component reconciler includes the annotation value in the installer set hash computation, ensuring the InstallerSet is updated when TLS config changes

4. TektonResult Integration

First component to support centralized TLS configuration
Injects TLS_MIN_VERSION, TLS_CIPHER_SUITES, and TLS_CURVE_PREFERENCES environment variables into the Results API deployment

TLS Configuration Flow

┌─────────────────────────────────────────────────────────────────────────────┐
│                           INITIALIZATION                                     │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  1. TektonConfig Controller starts                                           │
│     └─► setupAPIServerTLSWatch() creates shared informer for APIServer      │
│         └─► Stores lister in occommon.SetSharedAPIServerLister()            │
│         └─► Registers event handler to enqueue TektonConfig on changes      │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                           RECONCILIATION                                     │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  2. TektonConfig reconciliation (shared reconciler)                          │
│     ├─► TektonConfig extension.GetPlatformData()                            │
│     │   └─► Resolves TLS profile from shared APIServer lister               │
│     │   └─► Returns SHA-256 hash of TLS profile                             │
│     ├─► Stamps fingerprint as annotation on TektonResult CR                 │
│     │   (operator.tekton.dev/platform-data-hash)                                  │
│     └─► UpdateResult detects annotation change → updates CR                 │
│                                                                              │
│  3. TektonResult reconciliation triggered by CR update                       │
│     │                                                                        │
│     ▼                                                                        │
│  4. Extension.PreReconcile(ctx) called                                       │
│     └─► ResolveCentralTLSToEnvVars(ctx)                                     │
│         ├─► Check TektonConfig.Spec.Platforms.OpenShift.EnableCentralTLSConfig│
│         │   └─► If false, return nil (no central TLS)                       │
│         └─► GetTLSProfileFromAPIServer → TLSEnvVarsFromProfile              │
│             └─► Store result in oe.resolvedTLSConfig                        │
│                                                                              │
│  5. Hash computation includes platform-data annotation value                 │
│     └─► Change in TLS config → different hash → installer set update        │
│                                                                              │
│  6. Extension.Transformers() called                                          │
│     └─► If resolvedTLSConfig != nil:                                        │
│         └─► InjectTLSEnvVars() transformer added                            │
│                                                                              │
│  7. Manifests transformed                                                    │
│     └─► InjectTLSEnvVars() adds env vars to Results API deployment:         │
│         ├─► TLS_MIN_VERSION                                                 │
│         ├─► TLS_CIPHER_SUITES                                               │
│         └─► TLS_CURVE_PREFERENCES                                           │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                           AUTOMATIC UPDATES                                  │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  8. When APIServer TLS profile changes:                                      │
│     └─► Informer event handler triggers                                     │
│         └─► Enqueues TektonConfig for reconciliation                        │
│             └─► GetPlatformData() returns new TLS fingerprint               │
│                 └─► Annotation on TektonResult CR updated                   │
│                     └─► TektonResult reconciler triggered                   │
│                         └─► New hash → InstallerSet updated                 │
│                             └─► Deployment updated with new env vars        │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Known Limitations

Default TLS profile when none is explicitly set: When enableCentralTLSConfig is enabled but no explicit .spec.tlsSecurityProfile is configured on the APIServer resource, the operator injects the Intermediate profile values (TLS 1.2, standard cipher suite). This is because library-go’s ObserveTLSSecurityProfile defaults to the Intermediate profile when the field is nil, which is the same behavior used by other OpenShift components.
Curve preferences: TLS_CURVE_PREFERENCES is currently not populated and defaults to Go’s standard library values. This will be addressed once openshift/api#2583 is merged and the OpenShift API exposes curve preference configuration.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

PostgreSQL Upgrade from Version 13 to 15

Overview

This document describes the automatic PostgreSQL upgrade mechanism implemented in the Tekton Operator to handle upgrades from PostgreSQL 13 to PostgreSQL 15 for the Tekton Results internal database. This only applies for OpenShift deployments. Kubernetes deployments use Bitnami Postgres images which do not have the same versioning issue.

Problem Statement

When upgrading the operator from a version using PostgreSQL 13 to a version using PostgreSQL 15, the PostgreSQL pod would fail to start because:

PostgreSQL 15 cannot directly read the data directory structure created by PostgreSQL 13
The sclorg PostgreSQL container supports upgrades via the POSTGRESQL_UPGRADE environment variable, but this must only be set once
If the env var remains set after the initial upgrade, subsequent pod restarts will fail
The operator reconciliation loop continuously reapplies manifests, making it difficult to set a “one-time” environment variable

Solution: Wrapper Script Approach

The solution uses a wrapper script that automatically detects when an upgrade is needed and applies the POSTGRESQL_UPGRADE environment variable exactly once.

Key Components

ConfigMap with Wrapper Script (postgres-upgrade-scripts)
- postgres-wrapper.sh: Checks PostgreSQL version and conditionally sets upgrade env var
Modified Main Container
- Uses wrapper script as entrypoint instead of default run-postgresql
- Wrapper checks PG_VERSION file in data directory
- Sets POSTGRESQL_UPGRADE=copy if version 13 is detected
- Executes normal PostgreSQL startup

How It Works

Pod Starts
    ↓
Main Container: postgres
    ↓
Wrapper Script Executes
    ↓
Check /var/lib/pgsql/data/userdata/PG_VERSION
    ↓
    ├─ If file doesn't exist → Fresh install (no action)
    ├─ If version = 15 → Start normally (no action)
    └─ If version = 13 → Set POSTGRESQL_UPGRADE=copy
    ↓
Execute run-postgresql
    ↓
PostgreSQL starts (with or without upgrade)
    ↓
PG_VERSION updated to 15 after successful upgrade
    ↓
Next restart → Version = 15 → Start normally

Implementation Details

Files Modified

cmd/openshift/operator/kodata/static/tekton-results/internal-db/db.yaml
- Changed PostgreSQL image from version 16 to version 15
- Added postgres-upgrade-scripts ConfigMap with wrapper script
pkg/reconciler/openshift/tektonresult/extension.go
- Added injectPostgresUpgradeSupport() transformer
- Transformer modifies postgres container to use wrapper script
pkg/reconciler/kubernetes/tektonresult/transform.go
- Added same injectPostgresUpgradeSupport() transformer for Kubernetes platform

Transformer Behavior

The injectPostgresUpgradeSupport() transformer:

Only applies to the tekton-results-postgres StatefulSet
Modifies main container to:
- Mount the scripts ConfigMap at /upgrade-scripts
- Use wrapper script as command: /bin/bash /upgrade-scripts/postgres-wrapper.sh
Adds ConfigMap volume for the upgrade scripts

Rollback Considerations

⚠️ Important: This is a one-way upgrade. Once the PostgreSQL data has been upgraded from v13 to v15, you cannot downgrade back to v13.

If you need to rollback the operator to a version using PostgreSQL 13:

The PostgreSQL 13 pod will fail to start with the upgraded data
You must either:
- Restore from a backup taken before the upgrade
- Accept data loss and start fresh

Recommendation: Always take a backup of the PostgreSQL PVC before upgrading the operator.

References

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Syncer Service

SyncerService custom resource allows user to install and manage Syncer Service.

Syncer Service is a Kubernetes controller that synchronizes secrets between manager (hub) and worker (spoke) nodes in multi-Kueue environments. It enables seamless multi-cluster pipeline execution by ensuring PipelineRuns have the necessary authentication secrets available on their target clusters.

Overview

When a PipelineRun is scheduled to run on a spoke cluster via Kueue MultiKueue:

The controller detects the Workload resource associated with the PipelineRun
Retrieves the Git authentication secret specified in the PipelineRun’s annotations
Syncs the secret from the hub cluster to the target spoke cluster
Ensures the secret has proper ownership for lifecycle management

Installation

Important: SyncerService is not installed directly by users. It is automatically deployed by the Tekton Operator when specific conditions are met.

Automatic Installation Conditions

SyncerService is automatically installed when both of the following conditions are true:

Multi-cluster mode is enabled (multi-cluster-disabled: false)
Multi-cluster role is set to Hub (multi-cluster-role: Hub)

Installation via TektonConfig

Configure your TektonConfig with the Tekton Kueue settings to automatically deploy SyncerService:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  profile: all
  targetNamespace: openshift-pipelines
  kueue:
    disabled: false
    multi-cluster-disabled: false
    multi-cluster-role: Hub
    config.yaml:
      queueName: pipelines-queue

When this configuration is applied, the operator will:

Deploy TektonKueue component
Automatically deploy SyncerService component (because multi-cluster-role: Hub)

Uninstallation

Automatic Uninstallation Conditions

SyncerService is automatically removed when any of the following conditions become true:

Multi-cluster mode is disabled (multi-cluster-disabled: true)
Multi-cluster role is not Hub (e.g., Spoke or empty/unset)

Uninstall via TektonConfig

To remove SyncerService, update your TektonConfig to disable multi-cluster mode or change the role:

Option 1: Disable Multi-Cluster

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  kueue:
    multi-cluster-disabled: true

Option 2: Change to Spoke Role

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  kueue:
    multi-cluster-disabled: false
    multi-cluster-role: Spoke

Pre-Requisites

SyncerService has the same pre-requisites as TektonKueue:

Kueue must be installed
cert-manager CRDs must be installed

Features

Automatic Secret Syncing: Syncs Git authentication secrets from hub to spoke clusters
Multi-Cluster Support: Works with Kueue’s MultiKueue for distributed workload execution
Selective Processing: Only handles Workloads owned by Tekton PipelineRuns
Lifecycle Management: Automatically managed by the Tekton Operator based on Tekton Kueue configuration

SyncerService CR

The SyncerService CR is managed internally by the operator and looks like:

apiVersion: operator.tekton.dev/v1alpha1
kind: SyncerService
metadata:
  name: syncer-service
spec:
  targetNamespace: openshift-pipelines

Note: Users should not create or modify SyncerService CR directly. It is managed automatically by the operator based on TektonKueue configuration.

Troubleshooting

Check SyncerService Status

kubectl get syncerservice syncer-service -o yaml

Check if SyncerService Should Be Installed

Verify your Tekton Kueue configuration:

kubectl get tektonconfig config -o jsonpath='{.spec.kueue}'

For SyncerService to be deployed, you should see:

multi-cluster-disabled: false
multi-cluster-role: Hub

View Controller Logs

kubectl logs -n openshift-pipelines -l app=syncer-service -f

References

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Tekton Kueue

The cluster-scoped TektonKueue custom resource installs and manages Tekton Kueue. Using TektonConfig is recommended.

Prerequisites

Install these APIs before enabling Tekton Kueue:

Configuration

Enable Tekton Kueue through TektonConfig:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  kueue:
    disabled: false
    multi-cluster-disabled: true
    multi-cluster-role: ""
    config.yaml:
      queueName: pipelines-queue

Alternatively, create the component resource directly:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonKueue
metadata:
  name: kueue
spec:
  disabled: false
  multi-cluster-disabled: true
  multi-cluster-role: ""
  config.yaml:
    queueName: pipelines-queue

Multi-cluster configuration

A multi-cluster installation can configure the cluster as a Hub or Spoke.

Hub:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonKueue
metadata:
  name: kueue
spec:
  disabled: false
  multi-cluster-disabled: false
  multi-cluster-role: Hub
  config.yaml:
    queueName: pipelines-queue

When the Hub role is configured through TektonConfig, the operator also manages the Syncer Service and Tekton Multicluster Proxy AAE.

Spoke:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonKueue
metadata:
  name: kueue
spec:
  disabled: false
  multi-cluster-disabled: false
  multi-cluster-role: Spoke
  config.yaml:
    queueName: pipelines-queue

Upgrade compatibility

TektonKueue replaces the former TektonScheduler API. The deprecated TektonScheduler CRD and TektonConfig.spec.scheduler field remain available during the compatibility window.

During pre-upgrade reconciliation, the operator:

Copies TektonConfig.spec.scheduler to TektonConfig.spec.kueue and clears the deprecated field. If both fields are configured, spec.kueue wins.
Removes InstallerSets owned by the old component.
Removes the deprecated tekton-scheduler-role and tekton-scheduler-rolebinding resources.
Creates TektonKueue/kueue from an existing TektonScheduler/scheduler resource when a TektonKueue resource does not already exist.
Removes the old operator finalizer, preserves other finalizers, and requests deletion of the migrated legacy resource.

The deprecated API is retained only for migration and does not reconcile operand resources. Use TektonKueue and spec.kueue for new configuration.

Rename IMAGE_SCHEDULER_MANAGER and IMAGE_SCHEDULER_WEBHOOK overrides to IMAGE_KUEUE_MANAGER and IMAGE_KUEUE_WEBHOOK.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Tekton Scheduler (deprecated)

TektonScheduler has been replaced by TektonKueue. The legacy CRD and TektonConfig.spec.scheduler field are retained temporarily for automatic upgrade migration. Use TektonKueue and TektonConfig.spec.kueue for new configuration.

Tekton – Operator

Vault:

Tekton Config

Target Namespace

Target Namespace Metadata

Profile

Config

Pipeline

Chain

Manual Approval Gate

Result

Tekton Results Watcher configuration

Pruner

Note:

Pruner Namespace annotations

Note:

Tekton Kueue

Hub cluster

Spoke cluster

OpenShift: proxy-aae Kueue namespace

Addon

Dashboard

Resolvers

NamespaceSync (OpenShift only)

Resources managed per namespace

Configuration fields

Disabling individual features

Restricting sync to specific namespaces

Quay Bridge secret auto-binding

Migration from legacy spec.params

OpenShiftPipelinesAsCode

Remote Hub Catalogs

Example: Configuring a Custom Hub Catalog

Example: Configuring Multiple Hub Catalogs

Referencing Tasks from Custom Catalogs

Event based pruner

Basic Configuration

Configuration Levels

Pruning Fields

Namespace-Level Configuration

Complete Example

Additional fields as options

ConfigMaps

Deployments

StatefulSets

HorizontalPodAutoscalers

webhookConfigurationOptions

Vault:

Tekton Pipeline

Properties

Metrics Properties

Tracing Properties

Optional Properties

Performance Properties

Note:

Vault:

Tekton Trigger

Vault:

Tekton Dashboard

Properties

Vault:

Tekton Result

Spec

Property “route_tls_termination” (OpenShift only)

Property “secret_name”:

Sample Secret File

GCS specific Property

External DB

Securing the DB connection

LokiStack + TektonResult

Kubernetes (GCP) + LokiStack/Loki

Loki

Forwarder

OpenShift (LokiStack + OpenShift Logging)

OpenShift Logging

Tekton Result Watcher Performance Properties

Results Watcher Performance Configuration

Note:

Tekton Result Watcher Configuration

Debugging

Migration from legacy `spec.params`

Additional fields as `options`