From 01fe9bf1f28761da4cc7de88a67b8e261075175b Mon Sep 17 00:00:00 2001 From: pweil- Date: Fri, 2 Sep 2016 14:41:59 -0400 Subject: [PATCH] psp initial documentation --- _data/reference.yml | 2 + .../user-guide/pod-security-policy/OWNERS.txt | 2 + docs/user-guide/pod-security-policy/index.md | 158 ++++++++++++++++++ docs/user-guide/pod-security-policy/psp.yaml | 22 +++ 4 files changed, 184 insertions(+) create mode 100644 docs/user-guide/pod-security-policy/OWNERS.txt create mode 100644 docs/user-guide/pod-security-policy/index.md create mode 100644 docs/user-guide/pod-security-policy/psp.yaml diff --git a/_data/reference.yml b/_data/reference.yml index bf06023fb173b..32f2d6b54a423 100644 --- a/_data/reference.yml +++ b/_data/reference.yml @@ -212,6 +212,8 @@ toc: path: /docs/user-guide/petset/ - title: Pods path: /docs/user-guide/pods/ + - title: Pod Security Policies + path: /docs/user-guide/pod-security-policy/ - title: Replica Sets path: /docs/user-guide/replicasets/ - title: Replication Controller diff --git a/docs/user-guide/pod-security-policy/OWNERS.txt b/docs/user-guide/pod-security-policy/OWNERS.txt new file mode 100644 index 0000000000000..f7232a6fe6445 --- /dev/null +++ b/docs/user-guide/pod-security-policy/OWNERS.txt @@ -0,0 +1,2 @@ +assignees: +- pweil- \ No newline at end of file diff --git a/docs/user-guide/pod-security-policy/index.md b/docs/user-guide/pod-security-policy/index.md new file mode 100644 index 0000000000000..8287d0c5e1a0d --- /dev/null +++ b/docs/user-guide/pod-security-policy/index.md @@ -0,0 +1,158 @@ +--- +assignees: +- pweil- + +--- + +Objects of type `podsecuritypolicy` govern the ability +to make requests on a pod that affect the `SecurityContext` that will be +applied to a pod and container. + +See [PodSecurityPolicy proposal](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/proposals/security-context-constraints.md) for more information. + +* TOC +{:toc} + +## What is a _Pod Security Policy_? + +A _Pod Security Policy_ is a cluster-level resource that controls the +actions that a pod can perform and what it has the ability to access. The +`PodSecurityPolicy` objects define a set of conditions that a pod must +run with in order to be accepted into the system. They allow an +administrator to control the following: + +1. Running of privileged containers. +1. Capabilities a container can request to be added. +1. The SELinux context of the container. +1. The user ID. +1. The use of host namespaces and networking. +1. Allocating an FSGroup that owns the pod’s volumes +1. Configuring allowable supplemental groups +1. Requiring the use of a read only root file system +1. Controlling the usage of volume types + +_Pod Security Policies_ are comprised of settings and strategies that +control the security features a pod has access to. These settings fall +into three categories: + +- *Controlled by a boolean*: Fields of this type default to the most +restrictive value. +- *Controlled by an allowable set*: Fields of this type are checked +against the set to ensure their value is allowed. +- *Controlled by a strategy*: Items that have a strategy to generate a value provide +a mechanism to generate the value and a mechanism to ensure that a +specified value falls into the set of allowable values. + + +## Strategies + +### RunAsUser + +- *MustRunAs* - Requires a `*range*` to be configured. Uses the first value +of the range as the default. Validates against the configured range. +- *MustRunAsNonRoot* - Requires that the pod be submitted with a non-zero +`*runAsUser*` or have the `USER` directive defined in the image. No default +provided. +- *RunAsAny* - No default provided. Allows any `*runAsUser*` to be specified. + +### SELinuxContext + +- *MustRunAs* - Requires `*seLinuxOptions*` to be configured if not using +pre-allocated values. Uses `*seLinuxOptions*` as the default. Validates against +`*seLinuxOptions*`. +- *RunAsAny* - No default provided. Allows any `*seLinuxOptions*` to be +specified. + +### SupplementalGroups + +- *MustRunAs* - Requires at least one range to be specified. Uses the +minimum value of the first range as the default. Validates against all ranges. +- *RunAsAny* - No default provided. Allows any `*supplementalGroups*` to be +specified. + +### FSGroup + +- *MustRunAs* - Requires at least one range to be specified. Uses the +minimum value of the first range as the default. Validates against the +first ID in the first range. +- *RunAsAny* - No default provided. Allows any `*fsGroup*` ID to be specified. + +### Controlling Volumes + +The usage of specific volume types can be controlled by setting the +volumes field of the PSP. The allowable values of this field correspond +to the volume sources that are defined when creating a volume: + +1. azureFile +1. flocker +1. flexVolume +1. hostPath +1. emptyDir +1. gcePersistentDisk +1. awsElasticBlockStore +1. gitRepo +1. secret +1. nfs +1. iscsi +1. glusterfs +1. persistentVolumeClaim +1. rbd +1. cinder +1. cephFS +1. downwardAPI +1. fc +1. configMap +1. \* (allow all volumes) + +The recommended minimum set of allowed volumes for new PSPs are +configMap, downwardAPI, emptyDir, persistentVolumeClaim, and secret. + +## Admission + +_Admission control_ with `PodSecurityPolicy` allows for control over the creation of resources +based on the capabilities allowed in the cluster. + +Admission uses the following approach to create the final security context for +the pod: + +1. Retrieve all PSPs available for use. +1. Generate field values for security context settings that were not specified +on the request. +1. Validate the final settings against the available policies. + +If a matching policy is found, then the pod is accepted. If the +request cannot be matched to a PSP, the pod is rejected. + +A pod must validate every field against the PSP. + +## Creating a Pod Security Policy + +Here is an example Pod Security Policy. It has permissive settings for +all fields + +{% include code.html language="yaml" file="sj.yaml" ghlink="/docs/user-guide/pod-security-policy/psp.yaml" %} + +Create the policy by downloading the example file and then running this command: + +```shell +$ kubectl create -f ./psp.yaml +podsecuritypolicy "permissive" created +``` + +## Deleting a Pod Security Policy + +Once you don't need a policy anymore, simply delete it with `kubectl`: + +```shell +$ kubectl delete psp permissive +podsecuritypolicy "permissive" deleted +``` + +## Enabling Pod Security Policies + +In order to use Pod Security Policies in your cluster you must ensure the +following + +1. You have enabled the api type `extensions/v1beta1/podsecuritypolicy` +1. You have enabled the admission controller `PodSecurityPolicy` +1. You have defined your policies \ No newline at end of file diff --git a/docs/user-guide/pod-security-policy/psp.yaml b/docs/user-guide/pod-security-policy/psp.yaml new file mode 100644 index 0000000000000..a16c1f350d4d5 --- /dev/null +++ b/docs/user-guide/pod-security-policy/psp.yaml @@ -0,0 +1,22 @@ +{ + "kind": "PodSecurityPolicy", + "apiVersion":"extensions/v1beta1", + "metadata": { + "name": "permissive" + }, + "spec": { + "seLinux": { + "rule": "RunAsAny" + }, + "supplementalGroups": { + "rule": "RunAsAny" + }, + "runAsUser": { + "rule": "RunAsAny" + }, + "fsGroup": { + "rule": "RunAsAny" + }, + "volumes": ["*"] + } +}