Merge pull request #61617 from mramendi/OCPBUGS-10548

OCPBUGS-10548: fix doc issues about unprivileged runs of Buildah in Pipelines

Author: gabriel-rh

cicd/pipelines/unprivileged-building-of-container-images-using-buildah.adoc

@@ -1,12 +1,12 @@
 :_content-type: ASSEMBLY
 [id="unprivileged-building-of-container-images-using-buildah"]
-= Unprivileged building of container images using Buildah
+= Building of container images using Buildah as a non-root user
 include::_attributes/common-attributes.adoc[]
 :context: unprivileged-building-of-container-images-using-buildah
 
 toc::[]
 
-Running {pipelines-shortname} as the root user on a container can expose the container processes and the host to other potentially malicious resources. You can reduce this type of exposure by running the workload as a specific non-root user in the container. For secure unprivileged builds of container images using Buildah, you can perform the following steps:
+Running {pipelines-shortname} as the root user on a container can expose the container processes and the host to other potentially malicious resources. You can reduce this type of exposure by running the workload as a specific non-root user in the container. To run builds of container images using Buildah as a non-root user, you can perform the following steps:
 
 * Define custom service account (SA) and security context constraint (SCC).
 * Configure Buildah to use the `build` user with id `1000`.
@@ -20,4 +20,4 @@ include::modules/op-limitations-of-unprivileged-builds.adoc[leveloffset=+1]
 
 .Additional resources
 
-* xref:../../authentication/managing-security-context-constraints.adoc#managing-pod-security-policies[Managing security context constraints (SCCs)]
+* xref:../../authentication/managing-security-context-constraints.adoc#managing-pod-security-policies[Managing security context constraints (SCCs)]

modules/op-configuring-buildah-to-use-build-user.adoc

@@ -6,22 +6,22 @@
 [id="configuring-builah-to-use-build-user_{context}"]
 = Configuring Buildah to use `build` user
 
-You can define a Buildah task to use the `build` user with user id `1000`. 
+You can define a Buildah task to use the `build` user with user id `1000`.
 
 .Procedure
 
 . Create a copy of the `buildah` cluster task as an ordinary task.
 +
 [source,terminal]
 ----
-$ tkn task create --from=buildah
+$ oc get clustertask buildah -o yaml | yq '. |= (del .metadata |= with_entries(select(.key == "name" )))' | yq '.kind="Task"' | yq '.metadata.name="buildah-as-user"' | oc create -f -
 ----
 
 . Edit the copied `buildah` task.
 +
 [source,terminal]
 ----
-$ oc edit task buildah
+$ oc edit task buildah-as-user
 ----
 +
 .Example: Modified Buildah task with `build` user
@@ -98,13 +98,11 @@ spec:
       cat $(workspaces.source.path)/image-digest | tee /tekton/results/IMAGE_DIGEST
     volumeMounts:
     - name: varlibcontainers
-      mountPath: /home/build/.local/share/containers
-    volumeMounts:
-    - name: varlibcontainers
-      mountPath: /home/build/.local/share/containers
+      mountPath: /home/build/.local/share/containers <3>
   volumes:
   - name: varlibcontainers
     emptyDir: {}
 ----
 <1> Run the container explicitly as the user id `1000`, which corresponds to the `build` user in the Buildah image.
-<2> Display the user id to confirm that the process is running as user id `1000`.
+<2> Display the user id to confirm that the process is running as user id `1000`.
+<3> You can change the path for the volume mount as necessary.

modules/op-configuring-custom-sa-and-scc.adoc

@@ -8,28 +8,33 @@
 
 The default `pipeline` SA allows using a user id outside of the namespace range. To reduce dependency on the default SA, you can define a custom SA and SCC with necessary cluster role and role bindings for the `build` user with user id `1000`.
 
+[IMPORTANT]
+====
+At this time, enabling the `allowPrivilegeEscalation` setting is required for Buildah to run successfully in the container. With this setting, Buildah can leverage `SETUID` and `SETGID` capabilities when running as a non-root user.
+====
+
 .Procedure
 
 * Create a custom SA and SCC with necessary cluster role and role bindings.
 +
 .Example: Custom SA and SCC for used id `1000`
 [source,yaml]
 ----
-apiVersion: v1 
+apiVersion: v1
 kind: ServiceAccount
 metadata:
-  name: pipelines-sa-userid-1000 <1>
+  name: pipelines-sa-userid-1000 # <1>
 ---
-kind: SecurityContextConstraints 
+kind: SecurityContextConstraints
 metadata:
   annotations:
-  name: pipelines-scc-userid-1000 <2>
+  name: pipelines-scc-userid-1000 # <2>
 allowHostDirVolumePlugin: false
 allowHostIPC: false
 allowHostNetwork: false
 allowHostPID: false
 allowHostPorts: false
-allowPrivilegeEscalation: false
+allowPrivilegeEscalation: true # <3>
 allowPrivilegedContainer: false
 allowedCapabilities: null
 apiVersion: security.openshift.io/v1
@@ -42,7 +47,8 @@ priority: 10
 readOnlyRootFilesystem: false
 requiredDropCapabilities:
 - MKNOD
-runAsUser: <3>
+- KILL
+runAsUser: # <4>
   type: MustRunAs
   uid: 1000
 seLinuxContext:
@@ -58,10 +64,10 @@ volumes:
 - projected
 - secret
 ---
-apiVersion: rbac.authorization.k8s.io/v1 
+apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRole
 metadata:
-  name: pipelines-scc-userid-1000-clusterrole <4>
+  name: pipelines-scc-userid-1000-clusterrole # <5>
 rules:
 - apiGroups:
   - security.openshift.io
@@ -72,10 +78,10 @@ rules:
   verbs:
   - use
 ---
-apiVersion: rbac.authorization.k8s.io/v1 
+apiVersion: rbac.authorization.k8s.io/v1
 kind: RoleBinding
 metadata:
-  name: pipelines-scc-userid-1000-rolebinding <5>
+  name: pipelines-scc-userid-1000-rolebinding # <6>
 roleRef:
   apiGroup: rbac.authorization.k8s.io
   kind: ClusterRole
@@ -89,8 +95,10 @@ subjects:
 
 <2> Define a custom SCC created based on restricted privileges, with modified `runAsUser` field.
 
-<3> Restrict any pod that gets attached with the custom SCC through the custom SA to run as user id `1000`.
+<3> At this time, enabling the `allowPrivilegeEscalation` setting is required for Buildah to run successfully in the container. With this setting, Buildah can leverage `SETUID` and `SETGID` capabilities when running as a non-root user.
+
+<4> Restrict any pod that gets attached with the custom SCC through the custom SA to run as user id `1000`.
 
-<4> Define a cluster role that uses the custom SCC.
+<5> Define a cluster role that uses the custom SCC.
 
-<5> Bind the cluster role that uses the custom SCC to the custom SA.
+<6> Bind the cluster role that uses the custom SCC to the custom SA.

modules/op-starting-a-task-run-pipeline-run-build-user.adoc

@@ -6,7 +6,7 @@
 [id="starting-a-task-run-with-custom-config-map-or-a-pipeline-run_{context}"]
 = Starting a task run with custom config map, or a pipeline run
 
-After defining the custom Buildah cluster task, you can create a `TaskRun` object that builds an image as a `build` user with user id `1000`. In addition, you can integrate the `TaskRun` object as part of a `PipelineRun` object. 
+After defining the custom Buildah cluster task, you can create a `TaskRun` object that builds an image as a `build` user with user id `1000`. In addition, you can integrate the `TaskRun` object as part of a `PipelineRun` object.
 
 .Procedure
 
@@ -26,14 +26,14 @@ data:
     CMD git
 kind: ConfigMap
 metadata:
-  name: dockerfile <1>
+  name: dockerfile # <1>
 ---
 apiVersion: tekton.dev/v1beta1
 kind: TaskRun
 metadata:
   name: buildah-as-user-1000
 spec:
-  serviceAccountName: pipelines-sa-userid-1000
+  serviceAccountName: pipelines-sa-userid-1000 # <2>
   params:
   - name: IMAGE
     value: image-registry.openshift-image-registry.svc:5000/test/buildahuser
@@ -42,11 +42,12 @@ spec:
     name: buildah-as-user
   workspaces:
   - configMap:
-      name: dockerfile <2>
+      name: dockerfile # <3>
     name: source
 ----
-<1> Use a config map because the focus is on the task run, without any prior task that fetches some sources with a Dockerfile. 
-<2> Mount a config map as the source workspace for the `buildah-as-user` task.
+<1> Use a config map because the focus is on the task run, without any prior task that fetches some sources with a Dockerfile.
+<2> The name of the service account that you created.
+<3> Mount a config map as the source workspace for the `buildah-as-user` task.
 
 . (Optional) Create a pipeline and a corresponding pipeline run.
 +
@@ -66,7 +67,7 @@ spec:
   - name: sslcertdir
     optional: true
   tasks:
-  - name: fetch-repository <1>
+  - name: fetch-repository # <1>
     taskRef:
       name: git-clone
       kind: ClusterTask
@@ -82,7 +83,7 @@ spec:
       value: "true"
   - name: buildah
     taskRef:
-      name: buildah-as-user <2>
+      name: buildah-as-user # <2>
     runAfter:
     - fetch-repository
     workspaces:
@@ -99,17 +100,18 @@ kind: PipelineRun
 metadata:
   name: pipelinerun-buildah-as-user-1000
 spec:
-  serviceAccountName: pipelines-sa-userid-1000
+  taskRunSpecs:
+    - pipelineTaskName: buildah
+      taskServiceAccountName: pipelines-sa-userid-1000 # <3>
   params:
   - name: URL
     value: https://github.com/openshift/pipelines-vote-api
   - name: IMAGE
     value: image-registry.openshift-image-registry.svc:5000/test/buildahuser
-  taskRef:
-    kind: Pipeline
+  pipelineRef:
     name: pipeline-buildah-as-user-1000
   workspaces:
-  - name: shared-workspace <3>
+  - name: shared-workspace # <4>
     volumeClaimTemplate:
       spec:
         accessModes:
@@ -120,6 +122,7 @@ spec:
 ----
 <1> Use the `git-clone` cluster task to fetch the source containing a Dockerfile and build it using the modified Buildah task.
 <2> Refer to the modified Buildah task.
-<3> Share data between the `git-clone` task and the modified Buildah task using a persistent volume claim (PVC) created automatically by the controller.
+<3> Use the service account that you created for the Buildah task.
+<4> Share data between the `git-clone` task and the modified Buildah task using a persistent volume claim (PVC) created automatically by the controller.
 
-. Start the task run or the pipeline run.
+. Start the task run or the pipeline run.