Comply with Pod Security Restricted Standard

Feature Overview

The pod-security.kubernetes.io/enforce=restricted standard is the most restrictive Pod Security Standard, enforcing current pod hardening best practices. When a namespace is labeled with this standard, all pods created in that namespace must comply with strict security requirements.

This guide explains how to configure Tekton Pipelines to meet the restricted security standard, ensuring that all containers in your Tasks can run successfully in restricted namespaces.

Use Cases

  • Running Tekton Pipelines in namespaces with pod-security.kubernetes.io/enforce=restricted label
  • Meeting organizational security compliance requirements
  • Enhancing the security posture of your CI/CD pipelines
  • Running workloads in highly regulated environments

Prerequisites

  • Tekton Pipelines is installed via TektonConfig CR, or via a TektonPipeline CR that is not managed by TektonConfig
  • You have permission to modify the TektonConfig resource, or the TektonPipeline resource when it is not managed by TektonConfig
  • You can create or edit Task definitions
  • For custom images, you have access to modify Containerfiles and rebuild images
  • To check an image on your workstation (step 3), a container CLI such as podman or docker that can pull the image

Understanding the Restricted Standard

The pod-security.kubernetes.io/enforce=restricted standard requires all three types of containers in a Pod to meet the following security context requirements:

  • Regular containers (containers)
  • Init containers (initContainers)
  • Ephemeral containers (ephemeralContainers)

Each container must set allowPrivilegeEscalation: false and drop ALL capabilities. runAsNonRoot: true and a seccompProfile of type RuntimeDefault or Localhost can be set on each container or once in the Pod securityContext. The following container security context sets all four fields, as the step samples on this page do:

securityContext:
  allowPrivilegeEscalation: false
  runAsNonRoot: true
  capabilities:
    drop:
      - "ALL"
  seccompProfile:
    type: RuntimeDefault

Configuration breakdown:

FieldValuePurposeImpact
allowPrivilegeEscalationfalsePrevents processes from gaining more privileges than their parent processBlocks malicious code from escalating privileges through setuid binaries or file capabilities
runAsNonRoottrueRequires containers to run as a non-root user (UID ≠ 0)Prevents containers from running as root, reducing the impact of container breakout vulnerabilities
capabilities.dropa list with the single entry ALLRemoves all Linux capabilities from the containerLimits the container's ability to perform privileged operations (e.g., network configuration, loading kernel modules)
seccompProfile.typeRuntimeDefaultApplies the container runtime's default seccomp profileRestricts the system calls available to the container, reducing the kernel attack surface

Steps

1. Configure Tekton to add security context to init containers

Tekton creates init containers for each Pod it manages. To comply with the restricted standard, these init containers need the required security context, which Tekton adds when set-security-context is true. In Alauda DevOps Pipelines 4.15.1, set-security-context is true by default. The commands below only re-enable it if it was set to false; on a default installation they report patched (no change).

Option A: Configure via TektonPipeline

If you manage Tekton directly through TektonPipeline CR:

Note: On the default installation, the TektonConfig named config owns the TektonPipeline named pipeline, and the operator overwrites direct changes to the TektonPipeline spec within seconds. Configure it through TektonConfig (Option B). Option A applies only when TektonPipeline is not managed by TektonConfig.

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonPipeline
spec:
  set-security-context: true

Apply the configuration:

$ kubectl patch tektonpipeline pipeline \
  --type merge \
  -p '{"spec":{"set-security-context":true}}'

tektonpipeline.operator.tekton.dev/pipeline patched (no change)

Option B: Configure via TektonConfig

If you manage Tekton through TektonConfig CR:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
spec:
  pipeline:
    set-security-context: true

Apply the configuration:

$ kubectl patch tektonconfig config \
  --type merge \
  -p '{"spec":{"pipeline":{"set-security-context":true}}}'

tektonconfig.operator.tekton.dev/config patched (no change)

Note: This configuration change takes effect immediately without requiring a restart of the Tekton controller. New TaskRuns and PipelineRuns created after this change will automatically have the required security context applied to init containers.

2. Add security context to custom Task definitions

For custom Tasks (not the built-in Tasks provided by the platform), you need to explicitly add the security context to each step and to each sidecar in sidecars. Steps and sidecars run as containers in the TaskRun Pod. set-security-context (step 1) adds the security context to the init containers that Tekton adds to the Pod, and to its results sidecar when it adds one, but not to the steps and sidecars of your Task. A sidecar without it makes the restricted standard reject the Pod, and the TaskRun fails with reason PodAdmissionFailed.

Example Task with security context:

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: custom-build-task
spec:
  steps:
    - name: build
      image: registry.example.com/builder:latest
      securityContext:
        allowPrivilegeEscalation: false
        runAsNonRoot: true
        capabilities:
          drop:
            - "ALL"
        seccompProfile:
          type: RuntimeDefault
      script: |
        #!/bin/sh
        echo "Building application..."

Note: Replace the sample images on this page with images your cluster can pull, for example from an internal registry. The registry.example.com/... images stand for your own images.

Important: This step applies to custom Tasks. Built-in Tasks provided by the platform (except buildah, see Built-in Tasks and the Restricted Standard) already declare a restricted-compliant securityContext on their steps, so you do not need to add one.

3. Configure container images to use non-root users

Container images must be configured to run as a non-root user. The user must be specified using a numeric UID rather than a username.

In your Containerfile, add a non-root user and set it as the default. Here's an example for Alpine-based images:

# Add a non-root user with UID 65532 (Alpine syntax)
RUN adduser -u 65532 -h /home/nonroot -D nonroot

# Set appropriate permissions for working directories
RUN chown -R 65532:65532 /app

# Switch to the non-root user (use numeric UID)
USER 65532

Note: The adduser command syntax varies by base image. See the referenced documentation below for examples with other base images.

Verify the image configuration with podman, or with docker, which takes the same arguments. Replace <image> with the image you built. --entrypoint id runs the id command of the image instead of its ENTRYPOINT; without it, an image that sets an ENTRYPOINT would get id as an argument of that ENTRYPOINT:

# Check that the image runs as non-root
$ podman run -it --rm --entrypoint id <image>

uid=65532(nonroot) gid=65532(nonroot) groups=65532(nonroot)

For detailed guidance on adjusting catalog Task images, see Adjust Containerfile for Building Task-Compatible Custom Images.

Operation Results

After completing the above steps:

  1. Init Containers: Tekton-created init containers will automatically comply with the restricted standard
  2. Custom Tasks: The steps and sidecars of your custom Tasks will have the required security context
  3. Container Images: Images will run as non-root users with minimal privileges

You can verify compliance by creating a TaskRun in a restricted namespace. Use a new test namespace: the label applies to every Pod in the namespace, so do not add it to a namespace that other workloads use.

Save the following TaskRun as taskrun.yaml. The custom-build-task Task from step 2 does not exist in the new namespace, so the TaskRun holds the same step as an inline taskSpec. The Tekton webhook rejects a TaskRun with an inline taskSpec when the cluster setting disable-inline-spec contains taskrun (see Constrain Tekton Pipeline Execution with Kyverno); on such a cluster, create the Task of step 2 in the new namespace and reference it with taskRef instead. Use an image that runs as a non-root user (step 3):

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: example-taskrun
spec:
  taskSpec:
    steps:
      - name: build
        image: registry.example.com/builder:latest
        securityContext:
          allowPrivilegeEscalation: false
          runAsNonRoot: true
          capabilities:
            drop:
              - "ALL"
          seccompProfile:
            type: RuntimeDefault
        script: |
          #!/bin/sh
          echo "Building application..."
# Create a test namespace and label it with the restricted standard
$ kubectl create namespace test-ns

namespace/test-ns created

$ kubectl label namespace test-ns pod-security.kubernetes.io/enforce=restricted

namespace/test-ns labeled

# Create a TaskRun in the restricted namespace
$ kubectl -n test-ns create -f taskrun.yaml

taskrun.tekton.dev/example-taskrun created

# Verify the TaskRun succeeds
$ kubectl -n test-ns get taskrun

NAME              SUCCEEDED   REASON      STARTTIME   COMPLETIONTIME
example-taskrun   True        Succeeded   2m          1m

# Delete the test namespace when the check is done
$ kubectl delete namespace test-ns

namespace "test-ns" deleted

A successful TaskRun shows SUCCEEDED as True and REASON as Succeeded, indicating that all containers ran successfully with the required security constraints.

Using Policy Enforcement Tools

For a more automated approach, you can use policy enforcement tools like Kyverno to automatically inject the required security context into all containers. By creating a Kyverno Policy (using apiVersion: kyverno.io/v1 and kind: Policy), you can automatically mutate Pods to add the necessary security context configurations.

For more info please refer to Scenario 4: Specified Namespace Security Context Enforcement.

Buildah limitation

This Kyverno-based approach does not make the built-in buildah Task compatible with the restricted standard. For the buildah limitation, see Built-in Tasks and the Restricted Standard below.

This approach eliminates the need to manually configure security context for each Task, simplifying compliance management.

For detailed guidance on configuring Kyverno policies for this purpose, refer to:

Troubleshooting

Built-in Tasks and the Restricted Standard

Among the built-in Tasks provided by the platform, only the buildah Task cannot run under the restricted standard. This is because buildah requires elevated privileges to build container images.

This limitation still applies even when using Kyverno to automatically inject the required restricted security context into Pods. Kyverno can add the fields required by the restricted standard, but it cannot make the built-in buildah Task compatible with restricted because buildah requires privileges that are forbidden by this standard.

The buildah Task requires the following security context:

securityContext:
  # allowPrivilegeEscalation: false  # Cannot be set to false - buildah needs to escalate privileges to use the SETFCAP capability for setting file capabilities during container image builds; forcing false also blocks newuidmap/newgidmap, causing rootless to fall back to single UID/GID mapping with warnings and potentially incorrect file ownership
  runAsNonRoot: true
  capabilities:
    # drop:  # Cannot drop ALL capabilities - buildah requires SETFCAP capability to set file capabilities (e.g., cap_net_bind_service) on files within container images during the build process
    #   - "ALL"
    add:
      - "SETFCAP"
  # seccompProfile:
  #   type: RuntimeDefault  # Cannot use RuntimeDefault - default seccomp blocks unshare/clone(CLONE_NEWUSER)/setns needed by buildah, leading to build failure; the baseline standard rejects an explicit Unconfined, so use a Localhost profile that allows these syscalls instead

Solutions:

  1. Use the buildah Task in a separate namespace with baseline mode instead of restricted mode.

    To allow buildah workloads to run, changing pod-security.kubernetes.io/enforce to baseline is the required step. The warn and audit labels do not block admission. Read and save the current value of the label first, and restore it later, as described in Recommended Settings.

    # Required: change enforce to baseline for buildah workloads
    $ kubectl label namespace <build-namespace> \
      pod-security.kubernetes.io/enforce=baseline \
      --overwrite
    
    namespace/<build-namespace> labeled

    After relabeling the namespace, create a new TaskRun or PipelineRun that uses the buildah Task in that namespace. When the registry credentials, Containerfile, and workspaces are configured correctly, the buildah Task can run normally under the baseline standard.

    Optional: Enable the Tekton Pipelines ValidatingAdmissionPolicy guardrail if the namespace must use baseline mode for buildah, but you still want to prevent other Pods in the same namespace from requesting broader privileges. This guardrail does not make the built-in buildah Task compatible with restricted mode. It applies to all Pods in namespaces labeled with buildah.alauda.io/enabled=true: it allows only the SETFCAP added capability required by buildah, and rejects privileged containers, host namespaces, hostPath volumes, and added capabilities other than SETFCAP.

    Edit the TektonConfig resource to enable the policy:

    kubectl edit tektonconfig config

    Add or update the following entry under spec.pipeline.params. If params already contains other entries, keep them and only add or update enable-validating-admission-policy.

    apiVersion: operator.tekton.dev/v1alpha1
    kind: TektonConfig
    metadata:
      name: config
    spec:
      pipeline:
        params:
          - name: enable-validating-admission-policy
            value: "true"

    Wait until TektonConfig is ready:

    $ kubectl get tektonconfig config \
      -o jsonpath='{.status.conditions[?(@.type=="Ready")].status}{"\n"}'
    
    True

    Verify that the policy resources are installed:

    kubectl get validatingadmissionpolicy pipelines-restricted
    kubectl get validatingadmissionpolicybinding pipelines-restricted

    Both commands should return a resource named pipelines-restricted.

    # Enable the guardrail for the build namespace.
    $ kubectl label namespace <build-namespace> \
      buildah.alauda.io/enabled=true \
      --overwrite
    
    namespace/<build-namespace> labeled

    Verify that the guardrail rejects workloads that request permissions beyond the buildah exception. The following server-side dry run does not create a Pod, but it still goes through admission. It should be denied because NET_BIND_SERVICE is allowed by the baseline standard but is not allowed by this guardrail:

    $ kubectl -n <build-namespace> create -f - --dry-run=server <<'EOF'
    apiVersion: v1
    kind: Pod
    metadata:
      name: vap-extra-capability-check
    spec:
      restartPolicy: Never
      containers:
        - name: check
          image: registry.k8s.io/pause:3.9
          securityContext:
            capabilities:
              add:
                - NET_BIND_SERVICE
    EOF
    
    The pods "vap-extra-capability-check" is invalid: : ValidatingAdmissionPolicy 'pipelines-restricted' with binding 'pipelines-restricted' denied request: only SETFCAP capability may be added
  2. Explore alternative container image build methods that may have different security requirements.

TaskRun fails with container user errors

You may encounter one of the following errors:

  • "container has runAsNonRoot and image will run as root" - The container image has no USER directive in the Containerfile (defaults to root) or explicitly sets USER 0
  • "container has runAsNonRoot and image has non-numeric user" - The container image uses a symbolic username (e.g., USER appuser or USER root) instead of a numeric UID

Solutions:

  1. Rebuild the image with a numeric non-root user ID as described in Step 3. For example, use USER 65532 instead of USER appuser or USER root.

  2. Specify the user in the Task securityContext:

    apiVersion: tekton.dev/v1
    kind: Task
    metadata:
      name: example-task
    spec:
      steps:
        - name: step1
          image: registry.example.com/myimage:latest
          securityContext:
            runAsUser: 65532
            runAsNonRoot: true
            allowPrivilegeEscalation: false
            capabilities:
              drop:
                - "ALL"
            seccompProfile:
              type: RuntimeDefault
          script: |
            #!/bin/sh
            echo "Running as user $(id -u)"
  3. Specify the user in the TaskRun podTemplate:

    apiVersion: tekton.dev/v1
    kind: TaskRun
    metadata:
      name: example-taskrun
    spec:
      taskRef:
        name: example-task
      podTemplate:
        securityContext:
          runAsUser: 65532
          runAsNonRoot: true
          fsGroup: 65532
          fsGroupChangePolicy: "OnRootMismatch"

Note: The podTemplate.securityContext sets Pod-level security context, which is inherited by all containers unless overridden at the container level. It replaces the securityContext of the default Pod template as a whole, so the sample repeats the shipped fsGroupChangePolicy: "OnRootMismatch".

Options 2 and 3 are useful when you cannot modify the container image.

TaskRun fails with violates PodSecurity "restricted:latest": unrestricted capabilities

The TaskRun fails with reason PodAdmissionFailed and a message such as pods "<taskrun-name>-pod" is forbidden: violates PodSecurity "restricted:latest": unrestricted capabilities (container "step-<step-name>" must not include "SYS_ADMIN" in securityContext.capabilities.add). The restricted standard rejects any capability in securityContext.capabilities.add other than NET_BIND_SERVICE, even when the step also drops ALL.

Solution: Remove that capability from capabilities.add and keep ALL in capabilities.drop. The only capability the restricted standard allows you to add back is NET_BIND_SERVICE.

TaskRun fails with CreateContainerConfigError after a Pod template sets runAsUser: 0

If the TaskRun fails with CreateContainerConfigError and the Pod events show Error: container's runAsUser breaks non-root policy (pod: "<pod-name>_<namespace>(<pod-uid>)", container: prepare), a Pod template sets runAsUser: 0. With set-security-context: true, Tekton starts its init containers, such as prepare, with runAsNonRoot: true and without runAsUser, so they inherit the Pod-level UID 0. In a namespace that enforces restricted, the Pod is rejected at admission instead, and the TaskRun fails with PodAdmissionFailed.

Solution: Remove runAsUser: 0 from the Pod template of the TaskRun, of the PipelineRun, or of the global default, and use a non-root UID as in option 3 of TaskRun fails with container user errors.

When to enable. Enable the restricted standard when several projects share a cluster and need a common minimum security level for their pipeline Pods.

Recommended values. Label every pipeline workload namespace with pod-security.kubernetes.io/enforce=restricted. Among the built-in Tasks, only the buildah Task cannot run under restricted (see Built-in Tasks and the Restricted Standard); run image builds in a separate namespace labeled pod-security.kubernetes.io/enforce=baseline, as described in that section, which also documents the optional ValidatingAdmissionPolicy guardrail for such a namespace.

Changing the label needs permission to patch the Namespace object, which is cluster-scoped, so this is usually done by a cluster administrator. Before you change the label of a namespace, read its current value and save the output. An empty output means that the label is not set:

kubectl get namespace <namespace> -o jsonpath='{.metadata.labels.pod-security\.kubernetes\.io/enforce}'

Then set the label. --overwrite is needed when the label already has a value; without it, kubectl stops with error: 'pod-security.kubernetes.io/enforce' already has a value (<value>), and --overwrite is false:

kubectl label namespace <namespace> pod-security.kubernetes.io/enforce=restricted --overwrite

To undo the change, set the saved value again:

kubectl label namespace <namespace> pod-security.kubernetes.io/enforce=<saved-value> --overwrite

If the saved output was empty, remove the label instead:

kubectl label namespace <namespace> pod-security.kubernetes.io/enforce-

In TektonConfig, keep set-security-context at its default true for init containers (step 1 in the Steps section), and set a non-root default Pod template once as described in Method 4: Global Default Configuration (TektonConfig):

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pipeline:
    set-security-context: true
    default-pod-template: |
      securityContext:
        runAsNonRoot: true
        runAsUser: 65532
        fsGroup: 65532
        fsGroupChangePolicy: "OnRootMismatch"

The default-pod-template value replaces the current default Pod template as a whole, and the change applies to every new TaskRun on the cluster. Read the value in effect and the value set in TektonConfig first, save both outputs, and keep the default's fields in the sample; on a default installation the value in effect is the shipped template with fsGroup: 65532 and fsGroupChangePolicy: "OnRootMismatch", which the sample repeats:

kubectl get configmap -n tekton-pipelines config-defaults -o jsonpath='{.data.default-pod-template}'
kubectl get tektonconfig config -o jsonpath='{.spec.pipeline.default-pod-template}'

tekton-pipelines is the default of TektonConfig spec.targetNamespace; replace it in the commands if your installation uses another namespace.

Save the sample as tektonconfig-security.yaml and merge it into the existing TektonConfig in the same way as step 1:

kubectl patch tektonconfig config --type merge --patch-file tektonconfig-security.yaml

Do not use kubectl apply -f for this partial sample. It warns that tektonconfigs/config is missing the kubectl.kubernetes.io/last-applied-configuration annotation and then adds that annotation with the content of the file; a later kubectl apply -f of another partial TektonConfig file then deletes the fields that this file set and the later file leaves out, such as this default-pod-template.

To undo the change: if the saved TektonConfig output was empty, remove the field from TektonConfig, which returns to the shipped default Pod template:

kubectl patch tektonconfig config --type json \
  -p '[{"op":"remove","path":"/spec/pipeline/default-pod-template"}]'

Otherwise set the saved TektonConfig value again.

Individual TaskRuns or PipelineRuns can still override the default Pod template where a custom image requires it; see the Pod Template Configuration Guide. An override replaces the whole securityContext of the default Pod template, so in a restricted namespace repeat runAsNonRoot: true in the override unless each step and each sidecar of the Task sets it.

Prerequisites. Permission to modify TektonConfig and to patch the namespaces that you label; both are cluster-scoped objects, so this is usually a cluster administrator. Custom Tasks must declare the container security context on each step and each sidecar, and use images that run as a numeric non-root UID (the runAsUser of the default Pod template above also satisfies the check, but the image must then work as that UID), as described in steps 2 and 3 of the Steps section; build custom Task images as described in Adjust Containerfile for Building Task-Compatible Custom Images before moving a namespace to restricted.

Learn More