Pod Security Policy doc improvements (#3010)

* docs/user-guide/pod-security-policy: minor improvements.

* docs/user-guide/pod-security-policy: convert JSON to YAML.

* docs/user-guide/pod-security-policy: mention kubectl get/edit commands.

docs/user-guide/pod-security-policy/index.md

@@ -4,7 +4,7 @@ assignees:
 title: Pod Security Policies
 ---
 
-Objects of type `podsecuritypolicy` govern the ability 
+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.
 
@@ -84,6 +84,7 @@ 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. azureDisk
 1. flocker
 1. flexVolume
 1. hostPath
@@ -104,8 +105,10 @@ to the volume sources that are defined when creating a volume:
 1. configMap
 1. vsphereVolume
 1. quobyte
-1. azureDisk
 1. photonPersistentDisk
+1. projected
+1. portworxVolume
+1. scaleIO
 1. \* (allow all volumes)
 
 The recommended minimum set of allowed volumes for new PSPs are 
@@ -116,8 +119,8 @@ 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 control_ with `PodSecurityPolicy` allows for control over the
+creation and modification of resources based on the capabilities allowed in the cluster.
 
 Admission uses the following approach to create the final security context for
 the pod:
@@ -146,6 +149,28 @@ $ kubectl create -f ./psp.yaml
 podsecuritypolicy "permissive" created
 ```
 
+## Getting a list of Pod Security Policies
+
+To get a list of existing policies, use `kubectl get`:
+
+```shell
+$ kubectl get psp
+NAME        PRIV   CAPS  SELINUX   RUNASUSER         FSGROUP   SUPGROUP  READONLYROOTFS  VOLUMES
+permissive  false  []    RunAsAny  RunAsAny          RunAsAny  RunAsAny  false           [*]
+privileged  true   []    RunAsAny  RunAsAny          RunAsAny  RunAsAny  false           [*]
+restricted  false  []    RunAsAny  MustRunAsNonRoot  RunAsAny  RunAsAny  false           [emptyDir secret downwardAPI configMap persistentVolumeClaim]
+```
+
+## Editing a Pod Security Policy
+
+To modify policy interactively, use `kubectl edit`:
+
+```shell
+$ kubectl edit psp permissive
+```
+
+This command will open a default text editor where you will be ably to modify policy.
+
 ## Deleting a Pod Security Policy
 
 Once you don't need a policy anymore, simply delete it with `kubectl`:

docs/user-guide/pod-security-policy/psp.yaml

@@ -1,28 +1,18 @@
-{
-  "kind": "PodSecurityPolicy",
-  "apiVersion":"extensions/v1beta1",
-  "metadata": {
-    "name": "permissive"
-  },
-  "spec": {
-      "seLinux": {
-          "rule": "RunAsAny"
-      },
-      "supplementalGroups": {
-          "rule": "RunAsAny"
-      },
-      "runAsUser": {
-          "rule": "RunAsAny"
-      },
-      "fsGroup": {
-          "rule": "RunAsAny"
-      },
-      "HostPorts": [
-          {
-          "min": 8000,
-          "max": 8080
-          }
-      ],
-      "volumes": ["*"]
-  }
-}
+apiVersion: extensions/v1beta1
+kind: PodSecurityPolicy
+metadata:
+  name: permissive
+spec:
+  seLinux:
+    rule: RunAsAny
+  supplementalGroups:
+    rule: RunAsAny
+  runAsUser:
+    rule: RunAsAny
+  fsGroup:
+    rule: RunAsAny
+  hostPorts:
+  - min: 8000
+    max: 8080
+  volumes:
+  - '*'