From ec18c5d4f71185a517a943f90ab2cf3742cca07c Mon Sep 17 00:00:00 2001
From: Sami Wagiaalla <swagiaal@redhat.com>
Date: Wed, 23 Mar 2016 12:37:41 -0700
Subject: [PATCH] Flesh out security context documentation

---
 docs/user-guide/security-context.md | 81 ++++++++++++++++++++++++++++-
 1 file changed, 80 insertions(+), 1 deletion(-)

diff --git a/docs/user-guide/security-context.md b/docs/user-guide/security-context.md
index 434ae29d38..df159de8e4 100644
--- a/docs/user-guide/security-context.md
+++ b/docs/user-guide/security-context.md
@@ -1,4 +1,83 @@
 ---
 ---
 
-A security context defines the operating system security settings (uid, gid, capabilities, SELinux role, etc..) applied to a container. See [security context design](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/security_context.md) for more details.
\ No newline at end of file
+A security context defines the operating system security settings (uid, gid, capabilities, SELinux role, etc..) applied to a container. See [security context design](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/security_context.md) for more details.
+
+There are two levels of security context: pod level security context, and container level security context.
+
+## Pod Level Security Context
+Setting security context at the pod applies those settings to all containers in the pod 
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: hello-world
+spec:
+  containers:
+  # specification of the pod’s containers
+  # ...
+  securityContext:
+    fsGroup: 1234
+    supplementalGroups: [5678]
+    seLinuxOptions:
+      level: "s0:c123,c456"
+```
+
+Please refer to the [API documentation](/docs/api-reference/v1/definitions/#_v1_podsecuritycontext) for a detailed listing and
+description of all the fields available within the pod security
+context.
+
+### Volume Security context
+
+Another functionality of pod level security context is that it applies
+those settings to volumes where applicable. Specifically `fsGroup` and
+`seLinuxOptions` are applied to the volume as follows:
+
+#### `fsGroup`
+
+Volumes which support ownership management are modified to be owned
+and writable by the GID specified in `fsGroup`. See the
+[Ownership Management design document](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/proposals/volume-ownership-management.md)
+for more details.
+
+#### `selinuxOptions`
+
+Volumes which support SELinux labeling are relabled to be accessable
+by the label specified unders `seLinuxOptions`. Usually you will only
+need to set the `level` section. This sets the SELinux MCS label given
+to all containers within the pod as well as the volume.
+
+**Attention**: Once the MCS label is specified in the pod description
+all pods with the same label will able to access the
+volume. So if interpod protection is needed you must ensure each pod
+is assigned a unique MCS label.
+
+## Container Level Security Context
+
+Container level security context settings are applied to the specific
+container and override settings made at the pod level where there is
+overlap. Container level settings however do not affect the pod's
+volumes.
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: hello-world
+spec:
+  containers:
+    - name: hello-world-container
+      # The container definition
+      # ...
+      securityContext:
+        privileged: true
+        seLinuxOptions:
+          level: "s0:c123,c456"
+```
+
+Please refer to the
+[API documentation](/docs/api-reference/v1/definitions/#_v1_securitycontext) 
+for a detailed listing and description of all the fields available
+within the container security context.
+