Create a task describing Pod process namespace sharing (#7489)

Author: verb

_data/tasks.yml

@@ -32,6 +32,7 @@ toc:
   - docs/tasks/configure-pod-container/configure-pod-initialization.md
   - docs/tasks/configure-pod-container/attach-handler-lifecycle-event.md
   - docs/tasks/configure-pod-container/configure-pod-configmap.md
+  - docs/tasks/configure-pod-container/share-process-namespace.md
   - docs/tools/kompose/user-guide.md
 
 - title: Inject Data Into Applications

docs/reference/feature-gates.md

@@ -65,6 +65,7 @@ different Kubernetes components.
 | `PersistentLocalVolumes` | `false` | Alpha | 1.7 | 1.9 |
 | `PersistentLocalVolumes` | `true` | Beta | 1.10 | |
 | `PodPriority` | `false` | Alpha | 1.8 | |
+| `PodShareProcessNamespace` | `false` | Alpha | 1.10 | |
 | `PVCProtection` | `false` | Alpha | 1.9 | |
 | `ResourceLimitsPriorityFunction` | `false` | Alpha | 1.9 | |
 | `RotateKubeletClientCertificate` | `true` | Beta | 1.7 | |

docs/tasks/configure-pod-container/share-process-namespace.md

@@ -0,0 +1,111 @@
+---
+title: Share Process Namespace between Containers in a Pod
+min-kubernetes-server-version: v1.10
+approvers:
+- verb
+- yujuhong
+- dchen1107
+---
+
+{% capture overview %}
+
+{% include feature-state-alpha.md %}
+
+This page shows how to configure process namespace sharing for a pod. When
+process namespace sharing is enabled, processes in a container are visible
+to all other containers in that pod.
+
+You can use this feature to configure cooperating containers, such as a log
+handler sidecar container, or to troubleshoot container images that don't
+include debugging utilities like a shell.
+
+{% endcapture %}
+
+{% capture prerequisites %}
+
+{% include task-tutorial-prereqs.md %}
+
+A special **alpha** feature gate `PodShareProcessNamespace` must be set to true
+across the system: `--feature-gates=PodShareProcessNamespace=true`.
+
+{% endcapture %}
+
+{% capture steps %}
+
+## Configure a Pod
+
+Process Namespace Sharing is enabled using the `ShareProcessNamespace` field of
+`v1.PodSpec`. For example:
+
+{% include code.html language="yaml" file="share-process-namespace.yaml" ghlink="/docs/tasks/configure-pod-container/share-process-namespace.yaml" %}
+
+1. Create the pod `nginx` on your cluster:
+
+        $ kubectl create -f https://k8s.io/docs/tasks/configure-pod-container/share-process-namespace.yaml
+
+1. Attach to the `shell` container and run `ps`:
+
+        $ kubectl attach -it nginx -c shell
+        If you don't see a command prompt, try pressing enter.
+        / # ps ax
+        PID   USER     TIME  COMMAND
+            1 root      0:00 /pause
+            8 root      0:00 nginx: master process nginx -g daemon off;
+           14 101       0:00 nginx: worker process
+           15 root      0:00 sh
+           21 root      0:00 ps ax
+
+You can signal processes in other containers. For example, send `SIGHUP` to
+nginx to restart the worker process. This requires the `SYS_PTRACE` capability.
+
+        / # kill -HUP 8
+        / # ps ax
+        PID   USER     TIME  COMMAND
+            1 root      0:00 /pause
+            8 root      0:00 nginx: master process nginx -g daemon off;
+           15 root      0:00 sh
+           22 101       0:00 nginx: worker process
+           23 root      0:00 ps ax
+
+It's even possible to access another container image using the
+`/proc/$pid/root` link.
+
+        / # head /proc/8/root/etc/nginx/nginx.conf
+
+        user  nginx;
+        worker_processes  1;
+
+        error_log  /var/log/nginx/error.log warn;
+        pid        /var/run/nginx.pid;
+
+
+        events {
+            worker_connections  1024;
+
+{% endcapture %}
+
+{% capture discussion %}
+
+## Understanding Process Namespace Sharing
+
+Pods share many resources so it makes sense they would also share a process
+namespace. Some container images may expect to be isolated from other
+containers, though, so it's important to understand these differences:
+
+1. **The container process no longer has PID 1.** Some container images refuse
+   to start without PID 1 (for example, containers using `systemd`) or run
+   commands like `kill -HUP 1` to signal the container process. In pods with a
+   shared process namespace, `kill -HUP 1` will signal the pod sandbox.
+   (`/pause` in the above example.)
+
+1. **Processes are visible to other containers in the pod.** This includes all
+   information visible in `/proc`, such as passwords that were passed as arguments
+   or environment variables. These are protected only by regular Unix permissions.
+
+1. **Container filesystems are visible to other containers in the pod through the
+   `/proc/$pid/root` link.** This makes debugging easier, but it also means
+   that filesystem secrets are protected only by filesystem permissions.
+
+{% endcapture %}
+
+{% include templates/task.md %}

docs/tasks/configure-pod-container/share-process-namespace.yaml

@@ -0,0 +1,17 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: nginx
+spec:
+  shareProcessNamespace: true
+  containers:
+  - name: nginx
+    image: nginx
+  - name: shell
+    image: busybox
+    securityContext:
+      capabilities:
+        add:
+        - SYS_PTRACE
+    stdin: true
+    tty: true

test/examples_test.go

@@ -414,6 +414,7 @@ func TestExampleObjectSchemas(t *testing.T) {
 			"security-context-2":      {&api.Pod{}},
 			"security-context-3":      {&api.Pod{}},
 			"security-context-4":      {&api.Pod{}},
+			"share-process-namespace": {&api.Pod{}},
 			"task-pv-claim":           {&api.PersistentVolumeClaim{}},
 			"task-pv-pod":             {&api.Pod{}},
 			"task-pv-volume":          {&api.PersistentVolume{}},
@@ -589,6 +590,8 @@ func TestExampleObjectSchemas(t *testing.T) {
 	capabilities.SetForTests(capabilities.Capabilities{
 		AllowPrivileged: true,
 	})
+	// PodShareProcessNamespace needed for example share-process-namespace.yaml
+	utilfeature.DefaultFeatureGate.Set("PodShareProcessNamespace=true")
 
 	for path, expected := range cases {
 		tested := 0