Create a task describing Pod process namespace sharing

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/tasks/configure-pod-container/share-process-namespace.md

@@ -0,0 +1,110 @@
+---
+title: Share Process Namespace between Containers in a Pod
+approvers:
+- dawnchen
+- verb
+---
+
+{% 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 will be visible
+to all other containers in that pod.
+
+This can be useful for cooperating containers, such as a log handler sidecar
+container, or troubleshooting 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` has to 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`:
+
+        $ kc 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
+
+1. It's possible to signal processes in other containers. Sending `SIGHUP` to
+   nginx causes it 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
+
+1. 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 (e.g. 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 will be 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