Merge pull request #98353 from Dhruv-Soni11/RHDEVDOCS-6531

RHDEVDOCS-6531: Adding content for buildah-ns task

Author: gabriel-rh

_topic_maps/_topic_map.yml

@@ -117,6 +117,8 @@ Topics:
   File: authenticating-pipelines-repos-using-secrets
 - Name: Unprivileged building of container images using Buildah
   File: unprivileged-building-of-container-images-using-buildah
+- Name: Using buildah-ns tekton task
+  File: using-buildah-ns-tekton-task
 ---
 Name: Custom Tekton Hub instance
 Dir: hub

modules/op-differences-between-buildah-buildah-ns-tasks.adoc

@@ -0,0 +1,19 @@
+// This module is included in the following assemblies:
+// * secure/using-buildah-ns-tekton-task.adoc
+
+:_mod-docs-content-type: CONCEPT
+
+[id="op-differences-between-buildah-buildah-ns-tasks_{context}"]
+= Differences between `buildah` and `buildah-ns` tasks
+
+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"
+----
+
+* **Security model**: User namespace separation improves privilege isolation and limits the impact of potential container escape vulnerabilities.

modules/op-running-buildah-ns-task.adoc

@@ -0,0 +1,37 @@
+// This module is included in the following assemblies:
+// * secure/using-buildah-ns-tekton-task.adoc
+
+:_mod-docs-content-type: CONCEPT
+
+[id="running-buildah-ns-task_{context}"]
+= Running the `buildah-ns` task
+
+You can run the `buildah-ns` task as part of a `PipelineRun` resource.
+
+[source,yaml]
+----
+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>
+----
+<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.
+====

modules/op-security-model-buildah-ns-task.adoc

@@ -0,0 +1,26 @@
+// This module is included in the following assemblies:
+// * secure/using-buildah-ns-tekton-task.adoc
+
+:_mod-docs-content-type: CONCEPT
+
+[id="security-model-buildah-ns-task_{context}"]
+= Security model of the `buildah-ns` task
+
+The `buildah-ns` task applies user namespace isolation to provide privilege separation between containers and the host system.
+
+== UID mapping behavior
+
+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.
+
+== Security benefits
+
+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.

modules/op-workspaces-parameters-results-buildah-ns-task.adoc

@@ -0,0 +1,85 @@
+// This module is included in the following assemblies:
+// * secure/using-buildah-ns-tekton-task.adoc
+
+:_mod-docs-content-type: CONCEPT
+
+[id="workspaces-parameters-results-buildah-ns-task_{context}"]
+= Workspaces, parameters, and results for the `buildah-ns` task
+
+The `buildah-ns` task requires a workspace, accepts several parameters for image build customization, and provides results that contain information about the built image.
+
+== Workspace
+
+[options="header"]
+|===
+| Name | Required | Description
+
+| source
+| Yes
+| The build context for the container image. Typically contains application source code and a `Containerfile` or `Dockerfile`.
+|===
+
+== Parameters
+
+[options="header"]
+|===
+| Name | Type | Default | Description
+
+| 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.
+|===
+
+== Results
+
+[options="header"]
+|===
+| Name | Description
+
+| IMAGE_URL
+| Fully qualified name of the built image.
+
+| IMAGE_DIGEST
+| SHA256 digest of the built image.
+|===

secure/using-buildah-ns-tekton-task.adoc

@@ -0,0 +1,25 @@
+:_mod-docs-content-type: ASSEMBLY
+include::_attributes/common-attributes.adoc[]
+[id="using-buildah-ns-tekton-task"]
+= Using buildah-ns Tekton task
+:context: using-buildah-ns-tekton-task
+
+toc::[]
+
+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.
+
+include::modules/op-differences-between-buildah-buildah-ns-tasks.adoc[leveloffset=+1]
+include::modules/op-security-model-buildah-ns-task.adoc[leveloffset=+1]
+include::modules/op-workspaces-parameters-results-buildah-ns-task.adoc[leveloffset=+1]
+include::modules/op-running-buildah-ns-task.adoc[leveloffset=+1]
+
+.Additional resources
+
+* link:https://docs.openshift.com/container-platform/latest/authentication/managing-security-context-constraints.html[Managing security context constraints (SCCs)]