Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 7. Using buildah-ns Tekton task

The buildah-ns Tekton task builds Open Container Initiative (OCI) images without requiring a container runtime daemon, such as the Docker daemon. The task uses buildah and applies user namespace isolation to provide enhanced security.

After a successful build, the task produces the following results:

  • The fully qualified image name
  • The SHA256 digest of the image

The buildah-ns task is functionally identical to the standard buildah Tekton task, but applies additional security mechanisms to improve container isolation at the kernel level.

The buildah-ns task extends the standard buildah task with the following security-focused changes:

  • Task name: The task is named buildah-ns instead of buildah.

  • Annotations: The task includes security annotations that enable automatic user namespace mapping: 

    io.kubernetes.cri-o.userns-mode: "auto"
io.openshift.builder: "true"
    Copy to Clipboard Toggle word wrap
  • Security model: User namespace separation improves privilege isolation and limits the impact of potential container escape vulnerabilities.

7.2. Security model of the buildah-ns task
Copy link

The buildah-ns task applies user namespace isolation to provide privilege separation between containers and the host system.

7.2.1. UID mapping behavior
Copy link

When the task runs with namespace annotations, user IDs (UIDs) are mapped as follows:

  • Inside the container: Processes run as UID 0, which appears as the root user.
  • Outside the container: The same processes run as a non-zero UID on the host system.

This mapping allows processes inside the container to behave as if they have root privileges while restricting their privileges on the host system.

7.2.2. Security benefits
Copy link

User namespace isolation provides the following security advantages:

  • Kernel-level isolation: Adds an extra isolation boundary between containers.
  • Reduced privilege exposure: Limits the impact of compromised workloads by running them as non-root users on the host.
  • Container escape protection: Helps mitigate potential vulnerabilities that allow escaping from the container runtime environment.

The buildah-ns task requires a workspace, accepts several parameters for image build customization, and provides results that contain information about the built image.

7.3.1. Workspace
Copy link

Expand
NameRequiredDescription

source

Yes

The build context for the container image. Typically contains application source code and a Containerfile or Dockerfile.

7.3.2. Parameters
Copy link

Expand
NameTypeDefaultDescription

IMAGE

string

Required

Fully qualified name of the image to build, including tag.

CONTAINERFILE_PATH

string

Containerfile

Path to the container build file relative to the source workspace.

TLS_VERIFY

string

true

Whether to verify TLS when pushing images. Setting this value to true is recommended.

VERBOSE

string

false

Enables verbose build output.

SUBDIRECTORY

string

.

Subdirectory in the workspace to use as the build context.

STORAGE_DRIVER

string

overlay

Storage driver for Buildah, aligned with the cluster node configuration.

BUILD_EXTRA_ARGS

string

Empty

Additional flags for the Buildah build command.

PUSH_EXTRA_ARGS

string

Empty

Additional flags for the Buildah push command.

SKIP_PUSH

string

false

If set to true, the image is not pushed to the registry.

7.3.3. Results
Copy link

Expand
NameDescription

IMAGE_URL

Fully qualified name of the built image.

IMAGE_DIGEST

SHA256 digest of the built image.

7.4. Running the buildah-ns task
Copy link

You can run the buildah-ns task as part of a PipelineRun resource. 

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata: {}
spec:
  pipelineRef:
    name: task-buildah-ns
  params:
    - name: IMAGE
      value: your-image-name
1 

    - name: TLS_VERIFY
      value: true
    - name: VERBOSE
      value: false
  workspaces:
    - name: source
      persistentVolumeClaim:
        claimName: your-pvc-name
2
Copy to Clipboard Toggle word wrap
1
Replace your-image-name with the full name of the container image that you want to build.
2
Replace your-pvc-name with the name of the PersistentVolumeClaim (PVC) that stores the application source code.
Note

If the target container registry requires authentication, configure a Kubernetes secret for registry access and link it to the service account that runs the TaskRun or PipelineRun resources.

Additional resources

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat