Comply with Pod Security Restricted Standard
TOC
Feature OverviewUse CasesPrerequisitesUnderstanding the Restricted StandardSteps1. Configure Tekton to add security context to init containersOption A: Configure via TektonPipelineOption B: Configure via TektonConfig2. Add security context to custom Task definitions3. Configure container images to use non-root usersOperation ResultsUsing Policy Enforcement ToolsTroubleshootingBuilt-in Tasks and the Restricted StandardTaskRun fails with container user errorsTaskRun fails withviolates PodSecurity "restricted:latest": unrestricted capabilitiesTaskRun fails with CreateContainerConfigError after a Pod template sets runAsUser: 0Recommended SettingsLearn MoreFeature 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 Pipelinesin namespaces withpod-security.kubernetes.io/enforce=restrictedlabel - Meeting organizational security compliance requirements
- Enhancing the security posture of your CI/CD pipelines
- Running workloads in highly regulated environments
Prerequisites
Tekton Pipelinesis installed viaTektonConfigCR, or via aTektonPipelineCR that is not managed byTektonConfig- You have permission to modify the
TektonConfigresource, or theTektonPipelineresource when it is not managed byTektonConfig - You can create or edit
Taskdefinitions - For custom images, you have access to modify
Containerfilesand rebuild images - To check an image on your workstation (step 3), a container CLI such as
podmanordockerthat 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:
Configuration breakdown:
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
TektonConfignamedconfigowns theTektonPipelinenamedpipeline, and the operator overwrites direct changes to theTektonPipelinespecwithin seconds. Configure it throughTektonConfig(Option B). Option A applies only whenTektonPipelineis not managed byTektonConfig.
Apply the configuration:
Option B: Configure via TektonConfig
If you manage Tekton through TektonConfig CR:
Apply the configuration:
Note: This configuration change takes effect immediately without requiring a restart of the
Tektoncontroller. NewTaskRunsandPipelineRunscreated 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:
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-inTasksprovided by the platform (exceptbuildah, see Built-in Tasks and the Restricted Standard) already declare arestricted-compliantsecurityContexton 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:
Note: The
addusercommand 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:
For detailed guidance on adjusting catalog Task images, see Adjust Containerfile for Building Task-Compatible Custom Images.
Operation Results
After completing the above steps:
- Init Containers:
Tekton-created init containers will automatically comply with therestrictedstandard - Custom Tasks: The steps and sidecars of your custom
Taskswill have the required security context - 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):
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.
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:
Solutions:
-
Use the
buildahTaskin a separate namespace withbaselinemode instead ofrestrictedmode.To allow
buildahworkloads to run, changingpod-security.kubernetes.io/enforcetobaselineis the required step. Thewarnandauditlabels do not block admission. Read and save the current value of the label first, and restore it later, as described in Recommended Settings.After relabeling the namespace, create a new
TaskRunorPipelineRunthat uses thebuildahTaskin that namespace. When the registry credentials,Containerfile, and workspaces are configured correctly, thebuildahTaskcan run normally under thebaselinestandard.Optional: Enable the Tekton Pipelines
ValidatingAdmissionPolicyguardrail if the namespace must usebaselinemode forbuildah, but you still want to prevent other Pods in the same namespace from requesting broader privileges. This guardrail does not make the built-inbuildahTaskcompatible withrestrictedmode. It applies to all Pods in namespaces labeled withbuildah.alauda.io/enabled=true: it allows only theSETFCAPadded capability required bybuildah, and rejects privileged containers, host namespaces, hostPath volumes, and added capabilities other thanSETFCAP.Edit the
TektonConfigresource to enable the policy:Add or update the following entry under
spec.pipeline.params. Ifparamsalready contains other entries, keep them and only add or updateenable-validating-admission-policy.Wait until
TektonConfigis ready:Verify that the policy resources are installed:
Both commands should return a resource named
pipelines-restricted.Verify that the guardrail rejects workloads that request permissions beyond the
buildahexception. The following server-side dry run does not create aPod, but it still goes through admission. It should be denied becauseNET_BIND_SERVICEis allowed by thebaselinestandard but is not allowed by this guardrail: -
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
USERdirective in theContainerfile(defaults to root) or explicitly setsUSER 0 - "container has runAsNonRoot and image has non-numeric user" - The container image uses a symbolic username (e.g.,
USER appuserorUSER root) instead of a numeric UID
Solutions:
-
Rebuild the image with a numeric non-root user ID as described in Step 3. For example, use
USER 65532instead ofUSER appuserorUSER root. -
Specify the user in the
TasksecurityContext: -
Specify the user in the
TaskRunpodTemplate:
Note: The
podTemplate.securityContextsets Pod-level security context, which is inherited by all containers unless overridden at the container level. It replaces thesecurityContextof the default Pod template as a whole, so the sample repeats the shippedfsGroupChangePolicy: "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.
Recommended Settings
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:
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:
To undo the change, set the saved value again:
If the saved output was empty, remove the label instead:
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):
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:
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:
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:
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.