agentleFS
Aidas-devAidas-dev/k8s-agent-skills/skills/tekton-operator/SKILL.md

tekton-operator

Skill4 starsChanged 5 months agoMITView on GitHub

Tekton operator (tektoncd/operator) — install, upgrade, and manage Tekton components (Pipelines, Triggers, Dashboard, Chains, Results, PaC) via TektonConfig and component CRs. Covers profiles, pipeline config, tektonpruner, external results DB.

The file

Files
SKILL.md

tekton-operator — Install & Manage Tekton

For authoring pipelines see tekton-pipelines. For Pipelines-as-Code see tekton-pac.

Repo: github.com/tektoncd/operator
Latest: v0.80.0 (2026-06-09). LTS: v0.78.x (pipeline v1.6.x LTS, EOL 2026-12-08), v0.77.x (EOL 2026-08-21). Min K8s 1.28.
API group: operator.tekton.dev/v1alpha1

CR Model

CRManages
TektonConfigTop-level — installs/configures all components via profile
TektonPipelinePipeline component
TektonTriggerTrigger component
TektonDashboardDashboard
TektonChainSupply-chain security (SSDF/SLSA provenance)
TektonResultResults API (pipeline run records)
TektonPrunerEvent-based cleanup of old PipelineRuns/TaskRuns
OpenShiftPipelinesAsCodePipelines-as-Code (K8s since v0.80.0 via spec.platforms.kubernetes.pipelinesAsCode)
TektonAddonAddons (OpenShift: templates, resolver tasks)
TektonSchedulerMulti-cluster scheduling (requires Kueue + cert-manager)

Install TektonConfig, get everything. The user only needs to create TektonConfig with the desired profile — the operator creates the component CRs and manages their lifecycle. TektonResult and TektonChain are optional components NOT installed through TektonConfig currently.

Install

# 1. Operator itself (also installs pipelines/triggers/chains/dashboard via profile CRs below)
kubectl apply -f https://infra.tekton.dev/tekton-releases/operator/latest/release.yaml

# 2. Choose profile — installs the components
kubectl apply -f https://raw.githubusercontent.com/tektoncd/operator/main/config/crs/kubernetes/config/all/operator_v1alpha1_config_cr.yaml

Profiles

ProfileInstalls
litePipeline
basicPipeline, Trigger, Chains
all (K8s)Pipeline, Trigger, Chains, Dashboard
all (OpenShift)Pipeline, Trigger, Chains, PaC, Addons

Helm alternative

The operator repo ships charts/tekton-operator — install via Flux GitRepository pinned to a release tag (e.g. tekton-operator-0.79.0) + HelmRelease with installCRDs: true. The TektonConfig CR is created separately after install (post-install), and the operator reconciles it.

TektonConfig Example

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  targetNamespace: tekton-pipelines   # openshift-pipelines on OpenShift
  targetNamespaceMetadata:
    labels: {}
    annotations: {}
  profile: all
  config:
    nodeSelector: <>
    tolerations: []
    priorityClassName: system-cluster-critical
  chain:
    disabled: false
  pipeline:
    coschedule: disabled           # workspaces | disabled
    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-provenance-in-status: true
    enable-step-actions: false
    max-result-size: 4096
    results-from: termination-message
    running-in-environment-with-injected-sidecars: true
    performance:
      disable-ha: false
      buckets: 1
      replicas: 1
      threads-per-controller: 2
      kube-api-qps: 5.0
      kube-api-burst: 10
  trigger:
    disabled: false
  dashboard:
    readonly: true
  chain:
    disabled: false
  pruner:
    disabled: true               # job-based pruner (cron); must be OFF for tektonpruner
    keep: 100
    resources: [pipelinerun]
    schedule: "0 8 * * *"
  tektonpruner:
    disabled: false
    global-config:
      enforcedConfigLevel: global
      ttlSecondsAfterFinished: 1800
      successfulHistoryLimit: 5
      failedHistoryLimit: 3
  result:
    is_external_db: true
    db_host: tekton-results-db-rw.tekton-pipelines.svc.cluster.local
    db_port: 5432
    db_name: tekton-results
    db_sslmode: disable
    db_secret_name: tekton-results-db-app
    db_secret_user_key: user
    db_secret_password_key: password

Key Decisions

Pruner vs TektonPruner (mutually exclusive)

prunertektonpruner
MechanismCron job (schedule)Event-based controller
Configkeep N resourcesTTL + success/failure history limits
RecommendationDisable when using tektonprunerPrefer this for event-driven cleanup

Both cannot be enabled simultaneously. Job-based pruner must be disabled: true for tektonpruner to work. TTL cleanup (ttlSecondsAfterFinished) + separate success/failure history limits is the modern pattern.

Pipeline config highlights

  • enable-api-fields: beta unlocks alpha→beta features; stable keeps v1 semantics
  • Resolvers (bundles/cluster/git/hub) toggle independently
  • coschedule: workspaces groups taskruns sharing workspaces
  • enable-step-actions — task-level step actions (beta)
  • performance block tunes controller replicas/threads (HA: disable-ha: false runs 2 replicas)

Results with external DB (production)

Point result.is_external_db: true at your own Postgres (e.g. CNPG). The DB secret holds user/password keys (customizable via db_secret_user_key/db_secret_password_key). Results API keeps run history beyond PipelineRun object TTL — needed if PaC prunes runs but you still want audit.

v0.80.0 Changes (breaking)

  • OpenTelemetry metrics migration — config key metrics.backend-destination → metrics-protocol; workqueue metrics renamed tekton_*lifecycle_* → kn_*; several unused metrics removed.
  • Pipelines-as-Code on Kubernetes — OpenShiftPipelinesAsCode CR now installable on plain K8s via spec.platforms.kubernetes.pipelinesAsCode (previously OpenShift-only).
  • Centralized TLS config (OpenShift) — components inherit cluster APIServer TLS profile when enableCentralTLSConfig set.

Common Mistakes

  • Creating component CRs directly — Create TektonConfig (top-level) and let it own components. Individual CRs conflict with TektonConfig management.
  • Both pruners enabled — pruner (job-based) and tektonpruner (event-based) are mutually exclusive. Disable pruner to use TTL-based cleanup.
  • Inline config vs ConfigMaps — TektonConfig pipeline section overrides generated ConfigMaps; editing the ConfigMaps directly gets reverted by the operator on next reconcile.
  • Wrong targetNamespace — defaults to tekton-pipelines (K8s) / openshift-pipelines (OpenShift); PaC cannot deploy in the same namespace as the operator (Repository CR forbidden there).
  • Forgetting installCRDs — Helm install of the operator without installCRDs: true leaves CRDs missing; TektonConfig apply fails.
  • PaC deployed standalone + operator PaC — if you vendored the PaC release (release.k8s.yaml), don't also enable OpenShiftPipelinesAsCode — duplicate controllers fight over webhooks.
  • Air-gap — operator defaults pull images from upstream registries; follow the AirGapImageConfiguration guide for custom registries.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.