documentation and example on running step containers as non root

docs/pipelineruns.md

@@ -242,7 +242,7 @@ point for the `Pod` in which the container images specified in your `Tasks` will
 customize the `Pod` confguration specifically for each `TaskRun`.
 
 In the following example, the `Task` defines a `volumeMount` object named `my-cache`. The `PipelineRun`
-provisions this object for the `Task` using a `persistentVolumeClaim` and executes it as a non-root user.
+provisions this object for the `Task` using a `persistentVolumeClaim` and executes it as user 1001.
 
 ```yaml
 apiVersion: tekton.dev/v1beta1
@@ -279,6 +279,7 @@ spec:
   podTemplate:
     securityContext:
       runAsNonRoot: true
+      runAsUser: 1001
     volumes:
     - name: my-cache
       persistentVolumeClaim:

docs/taskruns.md

@@ -186,6 +186,7 @@ spec:
     hostNetwork: true
     securityContext:
       runAsNonRoot: true
+      runAsUser: 1001
     volumes:
     - name: my-cache
       persistentVolumeClaim:
@@ -631,6 +632,38 @@ data:
   known_hosts: Z2l0aHViLmNvbSBzc2g.....[example]
 ```
 
+### Running Step Containers as a Non Root User
+
+All steps that do not require to be run as a root user should make use of TaskRun features to 
+designate the container for a step runs as a user without root permissions. As a best practice, 
+running containers as non root should be built into the container image to avoid any possibility 
+of the container being run as root. However, as a further measure of enforcing this practice, 
+TaskRun pod templates can be used to specify how containers should be run within a TaskRun pod. 
+
+An example of using a TaskRun pod template is shown below to specify that containers running via this 
+TaskRun's pod should run as non root and run as user 1001 if the container itself does not specify what 
+user to run as:
+
+```yaml
+apiVersion: tekton.dev/v1beta1
+kind: TaskRun
+metadata:
+  generateName: show-non-root-steps-run-
+spec:
+  taskRef:
+    name: show-non-root-steps
+  podTemplate:
+    securityContext:
+      runAsNonRoot: true
+      runAsUser: 1001
+```
+
+If a Task step specifies that it is to run as a different user than what is specified in the pod template, 
+the step's `securityContext` will be applied instead of what is specified at the pod level. An example of 
+this is available as a [TaskRun example](../examples/v1beta1/taskruns/run-steps-as-non-root.yaml).
+
+More information about Pod and Container Security Contexts can be found via the [Kubernetes website](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/#set-the-security-context-for-a-pod).
+
 ---
 
 Except as otherwise noted, the content of this page is licensed under the

docs/tasks.md

@@ -872,6 +872,71 @@ log into the `Pod` and add a `Step` that pauses the `Task` at the desired stage.
 
 ```
 
+### Running Step Containers as a Non Root User
+
+All steps that do not require to be run as a root user should make use of TaskRun features to 
+designate the container for a step runs as a user without root permissions. As a best practice, 
+running containers as non root should be built into the container image to avoid any possibility 
+of the container being run as root. However, as a further measure of enforcing this practice, 
+steps can make use of a `securityContext` to specify how the container should run.
+
+An example of running Task steps as a non root user is shown below:
+
+```yaml
+apiVersion: tekton.dev/v1beta1
+kind: Task
+metadata:
+  name: show-non-root-steps
+spec:
+  steps:
+    # no securityContext specified so will use 
+    # securityContext from TaskRun podTemplate
+    - name: show-user-1001
+      image: ubuntu
+      command:
+        - ps
+      args:
+        - "aux"
+    # securityContext specified so will run as  
+    # user 2000 instead of 1001
+    - name: show-user-2000
+      image: ubuntu
+      command:
+        - ps
+      args:
+        - "aux"
+      securityContext:
+        runAsUser: 2000
+---
+apiVersion: tekton.dev/v1beta1
+kind: TaskRun
+metadata:
+  generateName: show-non-root-steps-run-
+spec:
+  taskRef:
+    name: show-non-root-steps
+  podTemplate:
+    securityContext:
+      runAsNonRoot: true
+      runAsUser: 1001
+```
+
+In the example above, the step `show-user-2000` specifies via a `securityContext` that the container 
+for the step should run as user 2000. A `securityContext` must still be specified via a TaskRun `podTemplate` 
+for this TaskRun to run in a Kubernetes environment that enforces running containers as non root as a requirement. 
+
+The `runAsNonRoot` property specified via the `podTemplate` above validates that steps part of this TaskRun are 
+running as non root users and will fail to start any step container that attempts to run as root. Only specifying 
+`runAsNonRoot: true` will not actually run containers as non root as the property simply validates that steps are not 
+running as root. It is the `runAsUser` property that is actually used to set the non root user ID for the container.
+
+If a step defines its own `securityContext`, it will be applied for the step container over the `securityContext` 
+specified at the pod level via the TaskRun `podTemplate`. 
+
+More information about Pod and Container Security Contexts can be found via the [Kubernetes website](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/#set-the-security-context-for-a-pod).
+
+The example Task/TaskRun above can be found as a [TaskRun example](../examples/v1beta1/taskruns/run-steps-as-non-root.yaml).
+
 Except as otherwise noted, the contents of this page are licensed under the
 [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/).
 Code samples are licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0).

examples/v1beta1/taskruns/run-steps-as-non-root.yaml

@@ -0,0 +1,36 @@
+apiVersion: tekton.dev/v1beta1
+kind: Task
+metadata:
+  name: show-non-root-steps
+spec:
+  steps:
+    # no securityContext specified so will use 
+    # securityContext from TaskRun podTemplate
+    - name: show-user-1001
+      image: ubuntu
+      command:
+        - ps
+      args:
+        - "aux"
+    # securityContext specified so will run as  
+    # user 2000 instead of 1001
+    - name: show-user-2000
+      image: ubuntu
+      command:
+        - ps
+      args:
+        - "aux"
+      securityContext:
+        runAsUser: 2000
+---
+apiVersion: tekton.dev/v1beta1
+kind: TaskRun
+metadata:
+  generateName: show-non-root-steps-run-
+spec:
+  taskRef:
+    name: show-non-root-steps
+  podTemplate:
+    securityContext:
+      runAsNonRoot: true
+      runAsUser: 1001