Cluster Resolver

Fetch Tasks and Pipelines from within the same Kubernetes cluster

The Cluster Resolver fetches Tekton resources that are already deployed in the same Kubernetes cluster, enabling resource reuse across namespaces.

Resolver Type

This resolver responds to type cluster.

Parameters

kind · string · required

The kind of resource to fetch.

Options: task, pipeline, stepaction

name · string · required

The name of the resource to fetch.

Example: some-pipeline, some-task

namespace · string · required

The namespace containing the resource.

Example: default, other-namespace

cache · string · default: "auto"

Optional cache mode for the resolver.

Options: always, never, auto

Requirements

• A cluster running Tekton Pipeline v0.41.0 or later
• Built-in remote resolvers installed
• The enable-cluster-resolver feature flag set to true in the resolvers-feature-flags ConfigMap
• Beta features enabled

Configuration

The Cluster Resolver uses the cluster-resolver-config ConfigMap in the tekton-pipelines-resolvers namespace.

Configuration Options

default-kind

Default resource kind if not specified (e.g., task, pipeline)

default-namespace

Default namespace if not specified (e.g., default)

allowed-namespaces

Comma-separated list of allowed namespaces (empty = all allowed)

blocked-namespaces

Comma-separated list of blocked namespaces (* = block all except allowed)

Namespace Access Control

Control which namespaces the resolver can access:

apiVersion: v1
kind: ConfigMap
metadata:
  name: cluster-resolver-config
  namespace: tekton-pipelines-resolvers
data:
  # Allow only specific namespaces
  allowed-namespaces: "default,production,staging"
  
  # Block specific namespaces
  blocked-namespaces: "kube-system,kube-public"
  
  # Block all except allowed (use * with allowed-namespaces)
  # blocked-namespaces: "*"
  # allowed-namespaces: "default,production"

Cache Configuration

The cluster resolver supports caching, but only when explicitly enabled with cache: always:

Cache Mode	Description
always	Always cache the resolved resource
never	Never cache the resolved resource
auto	Never cache (cluster resources lack immutable references)
(not specified)	Never cache (same as auto)

Cluster resources (Tasks, Pipelines, etc.) do not have immutable references like Git commit hashes or bundle digests. Automatic caching is disabled by default to prevent stale data.

Configure default cache mode:

apiVersion: v1
kind: ConfigMap
metadata:
  name: cluster-resolver-config
  namespace: tekton-pipelines-resolvers
data:
  default-cache-mode: "never"  # Recommended for mutable resources

Global Cache Configuration

apiVersion: v1
kind: ConfigMap
metadata:
  name: resolver-cache-config
  namespace: tekton-pipelines-resolvers
data:
  max-size: "1000"
  ttl: "5m"

Usage Examples

Task Resolution

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: cluster-task-run
spec:
  taskRef:
    resolver: cluster
    params:
    - name: kind
      value: task
    - name: name
      value: some-task
    - name: namespace
      value: namespace-containing-task

Task Resolution with Caching

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: cluster-task-cached
spec:
  taskRef:
    resolver: cluster
    params:
    - name: kind
      value: task
    - name: name
      value: some-task
    - name: namespace
      value: namespace-containing-task
    - name: cache
      value: always

Task Resolution without Caching

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: cluster-task-no-cache
spec:
  taskRef:
    resolver: cluster
    params:
    - name: kind
      value: task
    - name: name
      value: some-task
    - name: namespace
      value: namespace-containing-task
    - name: cache
      value: never

Pipeline Resolution

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: cluster-pipeline-run
spec:
  pipelineRef:
    resolver: cluster
    params:
    - name: kind
      value: pipeline
    - name: name
      value: some-pipeline
    - name: namespace
      value: namespace-containing-pipeline

StepAction Resolution

apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: task-with-stepaction
spec:
  steps:
  - name: step-action-example
    ref:
      resolver: cluster
      params:
      - name: kind
        value: stepaction
      - name: name
        value: some-stepaction
      - name: namespace
        value: namespace-containing-stepaction

Cross-Namespace Task Reuse

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: shared-task-run
  namespace: team-a
spec:
  taskRef:
    resolver: cluster
    params:
    - name: kind
      value: task
    - name: name
      value: shared-build-task
    - name: namespace
      value: shared-tasks  # Task from shared-tasks namespace

ResolutionRequest Status

The ResolutionRequest.Status.RefSource field captures source metadata:

status:
  refSource:
    uri: /apis/tekton.dev/v1beta1/namespaces/default/task/a-simple-task@3b82d8c4-f89e-47ea-a49d-3be0dca4c038
    digest:
      sha256: 245b1aa918434cc8195b4d4d026f2e43df09199e2ed31d4dfd9c2cbea1c7ce54
  data: YXBpVmVyc2lvbjog...

uri

Namespace-scoped resource URI with UID (format: <resource-uri>@<uid>)

digest

SHA-256 checksum of the resource spec content

Understanding the URI Format

The URI follows Kubernetes resource URI conventions:

/apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE/NAME@UID

Example:

/apis/tekton.dev/v1beta1/namespaces/default/task/build-task@3b82d8c4-f89e-47ea-a49d-3be0dca4c038

Understanding the Digest

The digest is a hex-encoded SHA-256 checksum of the resource’s spec field only. This enables supply chain verification tools like Tekton Chains to detect malicious changes, even if metadata (like annotations) is modified.

The entrypoint field is empty because path information is already available in the URI field.

Use Cases

Shared Libraries

Create a central namespace with reusable Tasks and Pipelines

Multi-Tenancy

Allow teams to share common resources across namespaces

Platform Teams

Platform teams provide standard tasks to application teams

Testing

Reference test resources from dedicated test namespaces

Best Practices

Access Control

Use allowed-namespaces to restrict which namespaces can be accessed

Cache Carefully

Only use cache: always for truly immutable resources

Naming Conventions

Use clear naming conventions for shared resources

RBAC

Ensure the resolver ServiceAccount has read access to target namespaces

The Cluster Resolver is ideal for creating a “library” namespace of reusable Tasks and Pipelines that multiple teams can reference.