Add description info for the PodSecurityPolicy ConstraintTemplates

Signed-off-by: juliankatz <juliankatz@google.com>

library/pod-security-policy/allow-privilege-escalation/template.yaml

@@ -3,7 +3,11 @@ kind: ConstraintTemplate
 metadata:
   name: k8spspallowprivilegeescalationcontainer
   annotations:
-    description: Controls restricting escalation to root privileges.
+    description: >-
+      Controls restricting escalation to root privileges. Corresponds to the
+      `allowPrivilegeEscalation` field in a PodSecurityPolicy. For more
+      information, see
+      https://kubernetes.io/docs/concepts/policy/pod-security-policy/#privilege-escalation
 spec:
   crd:
     spec:

library/pod-security-policy/apparmor/template.yaml

@@ -3,7 +3,11 @@ kind: ConstraintTemplate
 metadata:
   name: k8spspapparmor
   annotations:
-    description: Controls the AppArmor profile used by containers.
+    description: >-
+      Configures an allow-list of AppArmor profiles for use by containers.
+      This corresponds to specific annotations applied to a PodSecurityPolicy.
+      For information on AppArmor, see
+      https://kubernetes.io/docs/tutorials/clusters/apparmor/
 spec:
   crd:
     spec:
@@ -15,6 +19,7 @@ spec:
           type: object
           properties:
             allowedProfiles:
+              description: "An array of AppArmor profiles. Examples: `runtime/default`, `unconfined`."
               type: array
               items:
                 type: string

library/pod-security-policy/capabilities/template.yaml

@@ -3,7 +3,11 @@ kind: ConstraintTemplate
 metadata:
   name: k8spspcapabilities
   annotations:
-    description: Controls Linux capabilities.
+    description: >-
+      Controls Linux capabilities on containers. Corresponds to the
+      `allowedCapabilities` and `requiredDropCapabilities` fields in a
+      PodSecurityPolicy. For more information, see
+      https://kubernetes.io/docs/concepts/policy/pod-security-policy/#capabilities
 spec:
   crd:
     spec:
@@ -16,10 +20,12 @@ spec:
           properties:
             allowedCapabilities:
               type: array
+              description: "A list of Linux capabilities that can be added to a container."
               items:
                 type: string
             requiredDropCapabilities:
               type: array
+              description: "A list of Linux capabilities that are required to be dropped from a container."
               items:
                 type: string
   targets:

library/pod-security-policy/flexvolume-drivers/template.yaml

@@ -3,7 +3,11 @@ kind: ConstraintTemplate
 metadata:
   name: k8spspflexvolumes
   annotations:
-    description: Controls the allowlist of Flexvolume drivers.
+    description: >-
+      Controls the allowlist of FlexVolume drivers. Corresponds to the
+      `allowedFlexVolumes` field in PodSecurityPolicy. For more information,
+      see
+      https://kubernetes.io/docs/concepts/policy/pod-security-policy/#flexvolume-drivers
 spec:
   crd:
     spec:
@@ -16,10 +20,12 @@ spec:
           properties:
             allowedFlexVolumes:
               type: array
+              description: "An array of AllowedFlexVolume objects."
               items:
                 type: object
                 properties:
                   driver:
+                    description: "The name of the FlexVolume driver."
                     type: string
   targets:
     - target: admission.k8s.gatekeeper.sh

library/pod-security-policy/forbidden-sysctls/template.yaml

@@ -3,7 +3,10 @@ kind: ConstraintTemplate
 metadata:
   name: k8spspforbiddensysctls
   annotations:
-    description: Controls the `sysctl` profile used by containers.
+    description: >-
+      Controls the `sysctl` profile used by containers. Corresponds to the
+      `forbiddenSysctls` field in a PodSecurityPolicy. For more information,
+      see https://kubernetes.io/docs/tasks/administer-cluster/sysctl-cluster/
 spec:
   crd:
     spec:
@@ -16,6 +19,7 @@ spec:
           properties:
             forbiddenSysctls:
               type: array
+              description: "A disallow-list of sysctls. `*` forbids all sysctls."
               items:
                 type: string
   targets:

library/pod-security-policy/fsgroup/template.yaml

@@ -3,7 +3,10 @@ kind: ConstraintTemplate
 metadata:
   name: k8spspfsgroup
   annotations:
-    description: Controls allocating an FSGroup that owns the Pod's volumes.
+    description: >-
+      Controls allocating an FSGroup that owns the Pod's volumes. Corresponds
+      to the `fsGroup` field in a PodSecurityPolicy. For more information, see
+      https://kubernetes.io/docs/concepts/policy/pod-security-policy/#volumes-and-file-systems
 spec:
   crd:
     spec:
@@ -15,15 +18,23 @@ spec:
           type: object
           properties:
             rule:
+              description: "An FSGroup rule name."
+              enum:
+                - MayRunAs
+                - MustRunAs
+                - RunAsAny
               type: string
             ranges:
               type: array
+              description: "GID ranges affected by the rule."
               items:
                 type: object
                 properties:
                   min:
+                    description: "The minimum GID in the range, inclusive."
                     type: integer
                   max:
+                    description: "The maximum GID in the range, inclusive."
                     type: integer
   targets:
     - target: admission.k8s.gatekeeper.sh

library/pod-security-policy/host-filesystem/template.yaml

@@ -3,7 +3,11 @@ kind: ConstraintTemplate
 metadata:
   name: k8spsphostfilesystem
   annotations:
-    description: Controls usage of the host filesystem.
+    description: >-
+      Controls usage of the host filesystem. Corresponds to the
+      `allowedHostPaths` field in a PodSecurityPolicy. For more information,
+      see
+      https://kubernetes.io/docs/concepts/policy/pod-security-policy/#volumes-and-file-systems
 spec:
   crd:
     spec:
@@ -16,13 +20,16 @@ spec:
           properties:
             allowedHostPaths:
               type: array
+              description: "An array of hostpath objects, representing paths and read/write configuration."
               items:
                 type: object
                 properties:
-                  readOnly:
-                    type: boolean
                   pathPrefix:
                     type: string
+                    description: "The path prefix that the host volume must match."
+                  readOnly:
+                    type: boolean
+                    description: "when set to true, any container volumeMounts matching the pathPrefix must include `readOnly: true`."
   targets:
     - target: admission.k8s.gatekeeper.sh
       rego: |

library/pod-security-policy/host-namespaces/template.yaml

@@ -3,7 +3,11 @@ kind: ConstraintTemplate
 metadata:
   name: k8spsphostnamespace
   annotations:
-    description: Controls usage of host namespaces.
+    description: >-
+      Disallows sharing of host PID and IPC namespaces by pod containers.
+      Corresponds to the `hostPID` and `hostIPC` fields in a PodSecurityPolicy.
+      For more information, see
+      https://kubernetes.io/docs/concepts/policy/pod-security-policy/#host-namespaces
 spec:
   crd:
     spec:

library/pod-security-policy/host-network-ports/template.yaml

@@ -3,7 +3,11 @@ kind: ConstraintTemplate
 metadata:
   name: k8spsphostnetworkingports
   annotations:
-    description: Controls usage of host networking and ports.
+    description: >-
+      Controls usage of host network namespace by pod containers. Specific
+      ports must be specified. Corresponds to the `hostNetwork` and
+      `hostPorts` feilds in a PodSecurityPolicy. For more information, see
+      https://kubernetes.io/docs/concepts/policy/pod-security-policy/#host-namespaces
 spec:
   crd:
     spec:
@@ -15,10 +19,13 @@ spec:
           type: object
           properties:
             hostNetwork:
+              description: "Determines if the policy allows the use of HostNetwork in the pod spec."
               type: boolean
             min:
+              description: "The start of the allowed port range, inclusive."
               type: integer
             max:
+              description: "The end of the allowed port range, inclusive."
               type: integer
   targets:
     - target: admission.k8s.gatekeeper.sh

library/pod-security-policy/privileged-containers/template.yaml

@@ -3,7 +3,11 @@ kind: ConstraintTemplate
 metadata:
   name: k8spspprivilegedcontainer
   annotations:
-    description: Controls running of privileged containers.
+    description: >-
+      Controls the ability of any container to enable privileged mode.
+      Corresponds to the `privileged` field in a PodSecurityPolicy. For more
+      information, see
+      https://kubernetes.io/docs/concepts/policy/pod-security-policy/#privileged
 spec:
   crd:
     spec:

library/pod-security-policy/proc-mount/template.yaml

@@ -3,7 +3,11 @@ kind: ConstraintTemplate
 metadata:
   name: k8spspprocmount
   annotations:
-    description: Controls the allowed `procMount` types for the container.
+    description: >-
+      Controls the allowed `procMount` types for the container. Corresponds to
+      the `allowedProcMountTypes` field in a PodSecurityPolicy. For more
+      information, see
+      https://kubernetes.io/docs/concepts/policy/pod-security-policy/#allowedprocmounttypes
 spec:
   crd:
     spec:
@@ -16,6 +20,14 @@ spec:
           properties:
             procMount:
               type: string
+              description: >-
+                Defines the strategy for the security exposure of certain paths
+                in `/proc` by the container runtime. Setting to `Default` uses
+                the runtime defaults, where `Unmasked` bypasses the default
+                behavior.
+              enum:
+                - Default
+                - Unmasked
   targets:
     - target: admission.k8s.gatekeeper.sh
       rego: |

library/pod-security-policy/read-only-root-filesystem/template.yaml

@@ -3,7 +3,11 @@ kind: ConstraintTemplate
 metadata:
   name: k8spspreadonlyrootfilesystem
   annotations:
-    description: Requires the use of a read only root file system.
+    description: >-
+      Requires the use of a read-only root file system by pod containers.
+      Corresponds to the `readOnlyRootFilesystem` field in a
+      PodSecurityPolicy. For more information, see
+      https://kubernetes.io/docs/concepts/policy/pod-security-policy/#volumes-and-file-systems
 spec:
   crd:
     spec:

library/pod-security-policy/seccomp/template.yaml

@@ -3,7 +3,11 @@ kind: ConstraintTemplate
 metadata:
   name: k8spspseccomp
   annotations:
-    description: Controls the seccomp profile used by containers.
+    description: >-
+      Controls the seccomp profile used by containers. Corresponds to the
+      `seccomp.security.alpha.kubernetes.io/allowedProfileNames` annotation on
+      a PodSecurityPolicy. For more information, see
+      https://kubernetes.io/docs/concepts/policy/pod-security-policy/#seccomp
 spec:
   crd:
     spec:
@@ -16,6 +20,7 @@ spec:
           properties:
             allowedProfiles:
               type: array
+              description: "An array of allowed profile values for seccomp annotations on Pods."
               items:
                 type: string
   targets:

library/pod-security-policy/selinux/template.yaml

@@ -3,7 +3,11 @@ kind: ConstraintTemplate
 metadata:
   name: k8spspselinuxv2
   annotations:
-    description: Controls the SELinux context of the container.
+    description: >-
+      Defines an allow-list of seLinuxOptions configurations for pod
+      containers. Corresponds to a PodSecurityPolicy requiring SELinux configs.
+      For more information, see
+      https://kubernetes.io/docs/concepts/policy/pod-security-policy/#selinux
 spec:
   crd:
     spec:
@@ -16,17 +20,23 @@ spec:
           properties:
             allowedSELinuxOptions:
               type: array
+              description: "An allow-list of SELinux options configurations."
               items:
                 type: object
+                description: "An allowed configuration of SELinux options for a pod container."
                 properties:
                   level:
-                      type: string
+                    type: string
+                    description: "An SELinux level."
                   role:
-                      type: string
+                    type: string
+                    description: "An SELinux role."
                   type:
-                      type: string
+                    type: string
+                    description: "An SELinux type."
                   user:
-                      type: string
+                    type: string
+                    description: "An SELinux user."
   targets:
     - target: admission.k8s.gatekeeper.sh
       rego: |