Trusted Resources

Trusted Resources is a feature that enables signing Tekton resources and verifying their authenticity before execution. This helps ensure that only trusted Tasks and Pipelines run in your cluster.

This is an alpha feature supporting v1beta1 and v1 versions of Task and Pipeline.

Overview

Trusted Resources provides cryptographic verification of Tekton resources using digital signatures. Key capabilities:

Sign Tasks and Pipelines with private keys
Verify signatures before execution using public keys
Support multiple verification policies
Enforce or warn on verification failures
Automatic verification for remote resources (Git, OCI, Artifact Hub)

Currently, Trusted Resources only supports verifying resources from remote sources (Git, OCI registry, Artifact Hub). For cluster resolver with in-cluster resources, ensure all default values are set before applying to the cluster, as the mutating webhook may update default fields and fail verification.

Verification failure marks the corresponding TaskRun/PipelineRun as Failed and stops execution.

Signing Resources

Use the Tekton CLI to sign Tasks and Pipelines:

tkn task sign task.yaml -K cosign.key -f signed-task.yaml

For detailed signing instructions, refer to the Tekton CLI documentation.

Signed Task Example

apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  annotations:
    tekton.dev/signature: MEYCIQDM8WHQAn/yKJ6psTsa0BMjbI9IdguR+Zi6sPTVynxv6wIhAMy8JSETHP7A2Ncw7MyA7qp9eLsu/1cCKOjRL1mFXIKV
  creationTimestamp: null
  name: example-task
  namespace: tekton-trusted-resources
spec:
  steps:
  - image: ubuntu
    name: echo

The signature is stored in the tekton.dev/signature annotation.

Enabling Trusted Resources

Configure Feature Flag

Update the feature-flags ConfigMap to enable verification:

apiVersion: v1
kind: ConfigMap
metadata:
  name: feature-flags
  namespace: tekton-pipelines
  labels:
    app.kubernetes.io/instance: default
    app.kubernetes.io/part-of: tekton-pipelines
data:
  trusted-resources-verification-no-match-policy: "fail"

Or patch the ConfigMap:

kubectl patch configmap feature-flags -n tekton-pipelines \
  -p='{"data":{"trusted-resources-verification-no-match-policy":"fail"}}'

No-Match Policy Options

Policy	Behavior
`ignore`	Skip verification if no policies match, don’t log, don’t fail
`warn`	Skip verification if no policies match, log warning, don’t fail
`fail`	Fail TaskRun/PipelineRun if no policies match

Skip Verification
Enable Verification

To skip verification, set trusted-resources-verification-no-match-policy to warn or ignore and ensure no VerificationPolicies exist in the cluster.

To enable verification, install VerificationPolicy resources that match your resources and set trusted-resources-verification-no-match-policy to fail or warn.

Verification Policy

Define verification policies using the VerificationPolicy resource.

How Policies Work

Trusted Resources looks up policies from the resource namespace (typically the TaskRun/PipelineRun namespace)
For each policy, checks if the resource URL matches any patterns in the resources list
If multiple policies match, the resource must pass ALL “enforce” mode policies
Resources that only match “warn” mode policies will log warnings but not fail
To pass a policy, the resource must verify against ANY public key in that policy

Basic Example

apiVersion: tekton.dev/v1alpha1
kind: VerificationPolicy
metadata:
  name: verification-policy-a
  namespace: resource-namespace
spec:
  resources:
    - pattern: "https://github.com/tektoncd/catalog.git"
    - pattern: "gcr.io/tekton-releases/catalog/upstream/git-clone"
    - pattern: "https://artifacthub.io/"
  authorities:
    - name: key1
      key:
        secretRef:
          name: secret-name-a
          namespace: secret-namespace
        hashAlgorithm: sha256
    - name: key2
      key:
        data: "STRING_ENCODED_PUBLIC_KEY"
  mode: enforce

Policy Fields

resources

pattern - Regex pattern to match resource URLs (e.g., https://github.com/tektoncd/catalog.git)
Uses Go regex Match function
.* matches all resources

authorities

name - Identifier for the authority
key - Public key configuration (choose ONE):
- secretRef - Reference to a Secret containing the public key
- data - Inline PEM-encoded public key
- kms - URI of the public key (follows Sigstore format)
hashAlgorithm - Hash algorithm (default: sha256, also supports SHA224, SHA384, SHA512)

mode

enforce (default) - Fail TaskRun/PipelineRun on verification failure
warn - Log warning on verification failure, don’t fail

Multiple Policies Example

apiVersion: tekton.dev/v1alpha1
kind: VerificationPolicy
metadata:
  name: verification-policy-a
  namespace: resource-namespace
spec:
  resources:
    - pattern: "https://github.com/tektoncd/catalog.git"
  authorities:
    - name: key1
      key:
        secretRef:
          name: secret-name-a
          namespace: secret-namespace
        hashAlgorithm: sha256
    - name: key2
      key:
        data: "STRING_ENCODED_PUBLIC_KEY"
  mode: enforce
---
apiVersion: tekton.dev/v1alpha1
kind: VerificationPolicy
metadata:
  name: verification-policy-b
  namespace: resource-namespace
spec:
  resources:
    - pattern: "https://github.com/tektoncd/catalog.git"
  authorities:
    - name: key3
      key:
        data: "STRING_ENCODED_PUBLIC_KEY"

A resource from https://github.com/tektoncd/catalog.git must:

Pass verification-policy-a (using either key1 OR key2)
AND pass verification-policy-b (using key3)

Status Reporting

Trusted Resources updates the TaskRun/PipelineRun conditions to indicate verification status.

No Matching Policies

No-Match Policy	`TrustedResourcesVerified`	`Succeeded`
`ignore`	(not set)	(not set)
`warn`	False	(not set)
`fail`	False	False

Matching Policies

Scenario	`TrustedResourcesVerified`	`Succeeded`
All policies pass	True	(not set)
Any enforce policy fails	False	False
Only warn policies fail	False	(not set)

Success Example

status:
  conditions:
  - lastTransitionTime: "2023-03-01T18:17:05Z"
    message: Trusted resource verification passed
    status: "True"
    type: TrustedResourcesVerified

Failure Example

status:
  conditions:
  - lastTransitionTime: "2023-03-01T18:17:05Z"
    message: resource verification failed
    status: "False"
    type: TrustedResourcesVerified
  - lastTransitionTime: "2023-03-01T18:17:10Z"
    message: resource verification failed
    status: "False"
    type: Succeeded

Storing Public Keys

Using Secrets
Inline Data
Using KMS

Store public keys in Kubernetes Secrets:

apiVersion: v1
kind: Secret
metadata:
  name: cosign-public-key
  namespace: tekton-pipelines
type: Opaque
data:
  cosign.pub: LS0tLS1CRUdJTi...

Reference in VerificationPolicy:

apiVersion: tekton.dev/v1alpha1
kind: VerificationPolicy
metadata:
  name: verification-policy
  namespace: resource-namespace
spec:
  resources:
    - pattern: "https://github.com/tektoncd/catalog.git"
  authorities:
    - name: key1
      key:
        secretRef:
          name: cosign-public-key
          namespace: tekton-pipelines

Embed the public key directly:

apiVersion: tekton.dev/v1alpha1
kind: VerificationPolicy
metadata:
  name: verification-policy
  namespace: resource-namespace
spec:
  resources:
    - pattern: "https://github.com/tektoncd/catalog.git"
  authorities:
    - name: inline-key
      key:
        data: |
          -----BEGIN PUBLIC KEY-----
          MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...
          -----END PUBLIC KEY-----

Reference keys from KMS providers:

apiVersion: tekton.dev/v1alpha1
kind: VerificationPolicy
metadata:
  name: verification-policy
  namespace: resource-namespace
spec:
  resources:
    - pattern: "https://github.com/tektoncd/catalog.git"
  authorities:
    - name: kms-key
      key:
        kms: "gcpkms://projects/PROJECT_ID/locations/LOCATION/keyRings/KEYRING/cryptoKeys/KEY/cryptoKeyVersions/VERSION"

Migration from ConfigMap

Key configuration in ConfigMap is deprecated. Migrate to VerificationPolicy.

Old ConfigMap Approach (Deprecated)

apiVersion: v1
kind: ConfigMap
metadata:
  name: config-trusted-resources
  namespace: tekton-pipelines
data:
  publickeys: "/etc/verification-secrets/cosign.pub, /etc/verification-secrets/cosign2.pub"

New VerificationPolicy Approach

Store public key files in Secrets and reference them:

apiVersion: tekton.dev/v1alpha1
kind: VerificationPolicy
metadata:
  name: verification-policy-name
  namespace: resource-namespace
spec:
  authorities:
    - name: key1
      key:
        secretRef:
          name: secret-name-cosign
          namespace: secret-namespace
        hashAlgorithm: sha256
    - name: key2
      key:
        secretRef:
          name: secret-name-cosign2
          namespace: secret-namespace
        hashAlgorithm: sha256

Best Practices

Use enforce mode for production - Set mode: enforce on policies protecting production resources
Test with warn mode - Use mode: warn when rolling out new policies
Scope patterns carefully - Use specific patterns rather than .* to limit policy scope
Multiple keys per policy - Add multiple authorities to allow key rotation
Namespace isolation - Create policies in the same namespace as resources
Monitor verification status - Check TrustedResourcesVerified conditions in CI/CD dashboards

Get Started

Core Concepts

Guides

Advanced Features

Resolvers

Operations

Migration

Overview

Signing Resources

Signed Task Example

Enabling Trusted Resources

Configure Feature Flag

No-Match Policy Options

Verification Policy

How Policies Work

Basic Example

Policy Fields

Multiple Policies Example

Status Reporting

No Matching Policies

Matching Policies

Success Example

Failure Example

Storing Public Keys

Migration from ConfigMap

Old ConfigMap Approach (Deprecated)

New VerificationPolicy Approach

Best Practices

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Advanced Features

Resolvers

Operations

Migration

​Overview

​Signing Resources

​Signed Task Example

​Enabling Trusted Resources

​Configure Feature Flag

​No-Match Policy Options

​Verification Policy

​How Policies Work

​Basic Example

​Policy Fields

​Multiple Policies Example

​Status Reporting

​No Matching Policies

​Matching Policies

​Success Example

​Failure Example

​Storing Public Keys

​Migration from ConfigMap

​Old ConfigMap Approach (Deprecated)

​New VerificationPolicy Approach

​Best Practices

Build docs developers (and LLMs) love

Overview

Signing Resources

Signed Task Example

Enabling Trusted Resources

Configure Feature Flag

No-Match Policy Options

Verification Policy

How Policies Work

Basic Example

Policy Fields

Multiple Policies Example

Status Reporting

No Matching Policies

Matching Policies

Success Example

Failure Example

Storing Public Keys

Migration from ConfigMap

Old ConfigMap Approach (Deprecated)

New VerificationPolicy Approach

Best Practices