add docs for AllowPrivilegeEscalation (#5448)

Signed-off-by: Jess Frazelle <acidburn@microsoft.com>

Author: jessfraz

docs/concepts/policy/pod-security-policy.md

@@ -21,22 +21,24 @@ actions that a pod can perform and what it has the ability to access. The
 run with in order to be accepted into the system. They allow an
 administrator to control the following:
 
-| Control Aspect                                                | Field Name                        |
-| ------------------------------------------------------------- | --------------------------------- |
-| Running of privileged containers                              | `privileged`                      |
-| Default set of capabilities that will be added to a container | `defaultAddCapabilities`          |
-| Capabilities that will be dropped from a container            | `requiredDropCapabilities`        |
-| Capabilities a container can request to be added              | `allowedCapabilities`             |
-| Controlling the usage of volume types                         | [`volumes`](#controlling-volumes) |
-| The use of host networking                                    | [`hostNetwork`](#host-network)    |
-| The use of host ports                                         | `hostPorts`                       |
-| The use of host's PID namespace                               | `hostPID`                         |
-| The use of host's IPC namespace                               | `hostIPC`                         |
-| The SELinux context of the container                          | [`seLinux`](#selinux)             |
-| The user ID                                                   | [`runAsUser`](#runasuser)         |
-| Configuring allowable supplemental groups                     | [`supplementalGroups`](#supplementalgroups) |
-| Allocating an FSGroup that owns the pod's volumes             | [`fsGroup`](#fsgroup)             |
-| Requiring the use of a read only root file system             | `readOnlyRootFilesystem`          |
+| Control Aspect                                                         | Field Name                                  |
+| ---------------------------------------------------------------------- | ------------------------------------------- |
+| Running of privileged containers                                       | `privileged`                                |
+| Default set of capabilities that will be added to a container          | `defaultAddCapabilities`                    |
+| Capabilities that will be dropped from a container                     | `requiredDropCapabilities`                  |
+| Capabilities a container can request to be added                       | `allowedCapabilities`                       |
+| Controlling the usage of volume types                                  | [`volumes`](#controlling-volumes)           |
+| The use of host networking                                             | [`hostNetwork`](#host-network)              |
+| The use of host ports                                                  | `hostPorts`                                 |
+| The use of host's PID namespace                                        | `hostPID`                                   |
+| The use of host's IPC namespace                                        | `hostIPC`                                   |
+| The SELinux context of the container                                   | [`seLinux`](#selinux)                       |
+| The user ID                                                            | [`runAsUser`](#runasuser)                   |
+| Configuring allowable supplemental groups                              | [`supplementalGroups`](#supplementalgroups) |
+| Allocating an FSGroup that owns the pod's volumes                      | [`fsGroup`](#fsgroup)                       |
+| Requiring the use of a read only root file system                      | `readOnlyRootFilesystem`                    |
+| Running of a container that allow privilege escalation from its parent | [`allowPrivilegeEscalation`](#allowPrivilegeEscalation) |
+| Control whether a process can gain more privileges than its parent process | [`defaultAllowPrivilegeEscalation`](#defaultAllowPrivilegeEscalation) |
 
 _Pod Security Policies_ are comprised of settings and strategies that
 control the security features a pod has access to. These settings fall
@@ -124,7 +126,21 @@ configMap, downwardAPI, emptyDir, persistentVolumeClaim, secret, and projected.
 
 ### Host Network
  - *HostPorts*, default `empty`. List of `HostPortRange`, defined by `min`(inclusive) and `max`(inclusive), which define the allowed host ports.
- 
+
+### AllowPrivilegeEscalation
+
+Gates whether or not a user is allowed to set the security context of a container
+to `allowPrivilegeEscalation=true`. This field defaults to `false`.
+
+### DefaultAllowPrivilegeEscalation
+
+Sets the default for the security context `AllowPrivilegeEscalation` of a container.
+This bool directly controls whether the `no_new_privs` flag gets set on the
+container process. It defaults to `nil`. The default behavior of `nil`
+allows privilege escalation so as to not break setuid binaries. Setting it to `false`
+ensures that no child process of a container can gain more privileges than
+its parent.
+
 ## Admission
 
 _Admission control_ with `PodSecurityPolicy` allows for control over the

docs/tasks/configure-pod-container/security-context-2.yaml

@@ -1,7 +1,7 @@
 apiVersion: v1
 kind: Pod
 metadata:
-  name: security-context-demo-2 
+  name: security-context-demo-2
 spec:
   securityContext:
     runAsUser: 1000
@@ -10,3 +10,4 @@ spec:
     image: gcr.io/google-samples/node-hello:1.0
     securityContext:
       runAsUser: 2000
+      allowPrivilegeEscalation: false

docs/tasks/configure-pod-container/security-context.md

@@ -24,6 +24,8 @@ a Pod or Container. Security context settings include:
 
 * [Seccomp](https://en.wikipedia.org/wiki/Seccomp): Limit a process's access to open file descriptors.
 
+* AllowPrivilegeEscalation: Controls whether a process can gain more privileges than its parent process. This bool directly controls whether the [`no_new_privs`](https://www.kernel.org/doc/Documentation/prctl/no_new_privs.txt) flag gets set on the container process. AllowPrivilegeEscalation is true always when the container is: 1) run as Privileged OR 2) has `CAP_SYS_ADMIN`.
+
 For more information about security mechanisms in Linux, see
 [Overview of Linux Kernel Security Features](https://www.linux.com/learn/overview-linux-kernel-security-features)
 
@@ -345,6 +347,8 @@ label given to all Containers in the Pod as well as the Volumes.
 * [Security Contexts design document](https://git.k8s.io/community/contributors/design-proposals/security_context.md)
 * [Ownership Management design document](https://git.k8s.io/community/contributors/design-proposals/volume-ownership-management.md)
 * [Pod Security Policies](/docs/concepts/policy/pod-security-policy/)
+* [AllowPrivilegeEscalation design
+  document](https://git.k8s.io/community/contributors/design-proposals/auth/no-new-privs.md)
 
 
 {% endcapture %}

docs/tasks/configure-pod-container/security-context.yaml

@@ -1,7 +1,7 @@
 apiVersion: v1
 kind: Pod
 metadata:
-  name: security-context-demo  
+  name: security-context-demo
 spec:
   securityContext:
     runAsUser: 1000
@@ -15,3 +15,4 @@ spec:
     volumeMounts:
     - name: sec-ctx-vol
       mountPath: /data/demo
+      allowPrivilegeEscalation: false