From cb1c47762e864dd8ff351ccab965abaf76d67ca9 Mon Sep 17 00:00:00 2001 From: Lee Verberne Date: Thu, 22 Feb 2018 21:15:18 +0100 Subject: [PATCH] Create a task describing Pod process namespace sharing --- _data/tasks.yml | 1 + .../share-process-namespace.md | 110 ++++++++++++++++++ .../share-process-namespace.yaml | 17 +++ test/examples_test.go | 3 + 4 files changed, 131 insertions(+) create mode 100644 docs/tasks/configure-pod-container/share-process-namespace.md create mode 100644 docs/tasks/configure-pod-container/share-process-namespace.yaml diff --git a/_data/tasks.yml b/_data/tasks.yml index bb3e9a8c7acff..bcc30257349ca 100644 --- a/_data/tasks.yml +++ b/_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 diff --git a/docs/tasks/configure-pod-container/share-process-namespace.md b/docs/tasks/configure-pod-container/share-process-namespace.md new file mode 100644 index 0000000000000..783bef55afe73 --- /dev/null +++ b/docs/tasks/configure-pod-container/share-process-namespace.md @@ -0,0 +1,110 @@ +--- +title: Share Process Namespace between Containers in a Pod +min-kubernetes-server-version: v1.10 +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 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`: + + $ 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 + +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 %} diff --git a/docs/tasks/configure-pod-container/share-process-namespace.yaml b/docs/tasks/configure-pod-container/share-process-namespace.yaml new file mode 100644 index 0000000000000..af812732a247a --- /dev/null +++ b/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 diff --git a/test/examples_test.go b/test/examples_test.go index 9075d9b7137bb..5faf1d95c9d77 100644 --- a/test/examples_test.go +++ b/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