Skip to main content
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 ModeDescription
alwaysAlways cache the resolved resource
neverNever cache the resolved resource
autoNever 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us