Merge pull request #37587 from sftim/20221029_revise_psa_tutorials

Revise tutorials for Pod Security Admission

Author: k8s-ci-robot

content/en/docs/tutorials/security/cluster-level-pss.md

@@ -30,6 +30,11 @@ Install the following on your workstation:
 - [KinD](https://kind.sigs.k8s.io/docs/user/quick-start/#installation)
 - [kubectl](/docs/tasks/tools/)
 
+This tutorial demonstrates what you can configure for a Kubernetes cluster that you fully
+control. If you are learning how to configure Pod Security Admission for a managed cluster
+where you are not able to configure the control plane, read
+[Apply Pod Security Standards at the namespace level](/docs/tutorials/security/ns-level-pss).
+
 ## Choose the right Pod Security Standard to apply
 
 [Pod Security Admission](/docs/concepts/security/pod-security-admission/)
@@ -42,22 +47,22 @@ that are most appropriate for your configuration, do the following:
 1. Create a cluster with no Pod Security Standards applied:
 
    ```shell
-   kind create cluster --name psa-wo-cluster-pss --image kindest/node:v1.24.0
+   kind create cluster --name psa-wo-cluster-pss
    ```
-   The output is similar to this:
+   The output is similar to:
    ```
    Creating cluster "psa-wo-cluster-pss" ...
-   ✓ Ensuring node image (kindest/node:v1.24.0) 🖼
-   ✓ Preparing nodes 📦  
+   ✓ Ensuring node image (kindest/node:v{{< skew currentVersion >}}.0) 🖼
+   ✓ Preparing nodes 📦
    ✓ Writing configuration 📜
    ✓ Starting control-plane 🕹️
    ✓ Installing CNI 🔌
    ✓ Installing StorageClass 💾
    Set kubectl context to "kind-psa-wo-cluster-pss"
    You can now use your cluster with:
-   
+
    kubectl cluster-info --context kind-psa-wo-cluster-pss
-   
+
    Thanks for using kind! 😊
    ```
 
@@ -72,7 +77,7 @@ that are most appropriate for your configuration, do the following:
    Kubernetes control plane is running at https://127.0.0.1:61350
 
    CoreDNS is running at https://127.0.0.1:61350/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
-   
+
    To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.
    ```
 
@@ -82,7 +87,7 @@ that are most appropriate for your configuration, do the following:
    kubectl get ns
    ```
    The output is similar to this:
-   ```     
+   ```
    NAME                 STATUS   AGE
    default              Active   9m30s
    kube-node-lease      Active   9m32s
@@ -99,21 +104,23 @@ that are most appropriate for your configuration, do the following:
       kubectl label --dry-run=server --overwrite ns --all \
       pod-security.kubernetes.io/enforce=privileged
       ```
-      The output is similar to this:
-      ```      
+
+      The output is similar to:
+      ```
       namespace/default labeled
       namespace/kube-node-lease labeled
       namespace/kube-public labeled
       namespace/kube-system labeled
       namespace/local-path-storage labeled
       ```
    2. Baseline
-      ```shell    
+      ```shell
       kubectl label --dry-run=server --overwrite ns --all \
       pod-security.kubernetes.io/enforce=baseline
       ```
-      The output is similar to this:
-      ```   
+
+      The output is similar to:
+      ```
       namespace/default labeled
       namespace/kube-node-lease labeled
       namespace/kube-public labeled
@@ -123,15 +130,16 @@ that are most appropriate for your configuration, do the following:
       Warning: kube-proxy-m6hwf: host namespaces, hostPath volumes, privileged
       namespace/kube-system labeled
       namespace/local-path-storage labeled
-      ```   
+      ```
 
    3. Restricted
       ```shell
       kubectl label --dry-run=server --overwrite ns --all \
       pod-security.kubernetes.io/enforce=restricted
       ```
-      The output is similar to this:
-      ```   
+
+      The output is similar to:
+      ```
       namespace/default labeled
       namespace/kube-node-lease labeled
       namespace/kube-public labeled
@@ -180,7 +188,7 @@ following:
 
    ```
    mkdir -p /tmp/pss
-   cat <<EOF > /tmp/pss/cluster-level-pss.yaml 
+   cat <<EOF > /tmp/pss/cluster-level-pss.yaml
    apiVersion: apiserver.config.k8s.io/v1
    kind: AdmissionConfiguration
    plugins:
@@ -212,7 +220,7 @@ following:
 1. Configure the API server to consume this file during cluster creation:
 
    ```
-   cat <<EOF > /tmp/pss/cluster-config.yaml 
+   cat <<EOF > /tmp/pss/cluster-config.yaml
    kind: Cluster
    apiVersion: kind.x-k8s.io/v1alpha4
    nodes:
@@ -255,22 +263,22 @@ following:
    these Pod Security Standards:
 
    ```shell
-   kind create cluster --name psa-with-cluster-pss --image kindest/node:v1.24.0 --config /tmp/pss/cluster-config.yaml
+   kind create cluster --name psa-with-cluster-pss --config /tmp/pss/cluster-config.yaml
    ```
    The output is similar to this:
    ```
    Creating cluster "psa-with-cluster-pss" ...
-    ✓ Ensuring node image (kindest/node:v1.24.0) 🖼 
-    ✓ Preparing nodes 📦  
-    ✓ Writing configuration 📜 
-    ✓ Starting control-plane 🕹️ 
-    ✓ Installing CNI 🔌 
-    ✓ Installing StorageClass 💾 
+    ✓ Ensuring node image (kindest/node:v{{< skew currentVersion >}}.0) 🖼
+    ✓ Preparing nodes 📦
+    ✓ Writing configuration 📜
+    ✓ Starting control-plane 🕹️
+    ✓ Installing CNI 🔌
+    ✓ Installing StorageClass 💾
    Set kubectl context to "kind-psa-with-cluster-pss"
    You can now use your cluster with:
-    
+
    kubectl cluster-info --context kind-psa-with-cluster-pss
-    
+
    Have a question, bug, or feature request? Let us know! https://kind.sigs.k8s.io/#community 🙂
    ```
 
@@ -281,36 +289,21 @@ following:
    The output is similar to this:
    ```
    Kubernetes control plane is running at https://127.0.0.1:63855
-
    CoreDNS is running at https://127.0.0.1:63855/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
-  
+
    To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.
    ```
-1. Create the following Pod specification for a minimal configuration in the default namespace:
 
-   ```
-   cat <<EOF > /tmp/pss/nginx-pod.yaml
-   apiVersion: v1
-   kind: Pod
-   metadata:
-     name: nginx
-   spec:
-     containers:
-       - image: nginx
-         name: nginx
-         ports:
-           - containerPort: 80
-   EOF
-   ```
-1. Create the Pod in the cluster:
+1. Create a Pod in the default namespace:
 
    ```shell
-   kubectl apply -f /tmp/pss/nginx-pod.yaml
+   kubectl apply -f https://k8s.io/examples/security/example-baseline-pod.yaml
    ```
-   The output is similar to this:
+
+   The pod is started normally, but the output includes a warning:
    ```
-    Warning: would violate PodSecurity "restricted:latest": allowPrivilegeEscalation != false (container "nginx" must set securityContext.allowPrivilegeEscalation=false), unrestricted capabilities (container "nginx" must set securityContext.capabilities.drop=["ALL"]), runAsNonRoot != true (pod or container "nginx" must set securityContext.runAsNonRoot=true), seccompProfile (pod or container "nginx" must set securityContext.seccompProfile.type to "RuntimeDefault" or "Localhost")
-    pod/nginx created
+   Warning: would violate PodSecurity "restricted:latest": allowPrivilegeEscalation != false (container "nginx" must set securityContext.allowPrivilegeEscalation=false), unrestricted capabilities (container "nginx" must set securityContext.capabilities.drop=["ALL"]), runAsNonRoot != true (pod or container "nginx" must set securityContext.runAsNonRoot=true), seccompProfile (pod or container "nginx" must set securityContext.seccompProfile.type to "RuntimeDefault" or "Localhost")
+   pod/nginx created
    ```
 
 ## Clean up

content/en/docs/tutorials/security/ns-level-pss.md

@@ -31,14 +31,14 @@ Install the following on your workstation:
 1. Create a `KinD` cluster as follows:
 
    ```shell
-   kind create cluster --name psa-ns-level --image kindest/node:v1.23.0
+   kind create cluster --name psa-ns-level
    ```
 
    The output is similar to this:
 
    ```
    Creating cluster "psa-ns-level" ...
-    ✓ Ensuring node image (kindest/node:v1.23.0) 🖼 
+    ✓ Ensuring node image (kindest/node:v{{< skew currentVersion >}}.0) 🖼 
     ✓ Preparing nodes 📦  
     ✓ Writing configuration 📜 
     ✓ Starting control-plane 🕹️ 
@@ -80,20 +80,21 @@ The output is similar to this:
 namespace/example created
 ```
 
-## Apply Pod Security Standards
+## Enable Pod Security Standards checking for that namespace
 
 1. Enable Pod Security Standards on this namespace using labels supported by
-   built-in Pod Security Admission. In this step we will warn on baseline pod
-   security standard as per the latest version (default value)
+   built-in Pod Security Admission. In this step you will configure a check to
+   warn on Pods that don't meet the latest version of the _baseline_ pod
+   security standard.
 
    ```shell
    kubectl label --overwrite ns example \
       pod-security.kubernetes.io/warn=baseline \
       pod-security.kubernetes.io/warn-version=latest
    ```
 
-2. Multiple pod security standards can be enabled on any namespace, using labels.
-   Following command will `enforce` the `baseline` Pod Security Standard, but
+2. You can configure multiple pod security standard checks on any namespace, using labels.
+   The following command will `enforce` the `baseline` Pod Security Standard, but
    `warn` and `audit` for `restricted` Pod Security Standards as per the latest
    version (default value)
 
@@ -107,51 +108,34 @@ namespace/example created
      pod-security.kubernetes.io/audit-version=latest
    ```
 
-## Verify the Pod Security Standards
+## Verify the Pod Security Standard enforcement
 
-1. Create a minimal pod in `example` namespace:
+1. Create a baseline Pod in the `example` namespace:
 
    ```shell
-   cat <<EOF > /tmp/pss/nginx-pod.yaml
-   apiVersion: v1
-   kind: Pod
-   metadata:
-     name: nginx
-   spec:
-     containers:
-       - image: nginx
-         name: nginx
-         ports:
-           - containerPort: 80
-   EOF
+   kubectl apply -n example -f https://k8s.io/examples/security/example-baseline-pod.yaml
    ```
-
-1. Apply the pod spec to the cluster in `example` namespace:
-
-   ```shell
-   kubectl apply -n example -f /tmp/pss/nginx-pod.yaml
-   ```
-   The output is similar to this:
+   The Pod does start OK; the output includes a warning. For example:
 
    ```
    Warning: would violate PodSecurity "restricted:latest": allowPrivilegeEscalation != false (container "nginx" must set securityContext.allowPrivilegeEscalation=false), unrestricted capabilities (container "nginx" must set securityContext.capabilities.drop=["ALL"]), runAsNonRoot != true (pod or container "nginx" must set securityContext.runAsNonRoot=true), seccompProfile (pod or container "nginx" must set securityContext.seccompProfile.type to "RuntimeDefault" or "Localhost")
    pod/nginx created
    ```
 
-1. Apply the pod spec to the cluster in `default` namespace:
+1. Create a baseline Pod in the `default` namespace:
 
    ```shell
-   kubectl apply -n default -f /tmp/pss/nginx-pod.yaml
+   kubectl apply -n default -f https://k8s.io/examples/security/example-baseline-pod.yaml
    ```
    Output is similar to this:
 
    ```
    pod/nginx created
    ```
 
-The Pod Security Standards were applied only to the `example`
-namespace. You could create the same Pod in the `default` namespace
-with no warnings.
+The Pod Security Standards enforcement and warning settings were applied only
+to the `example` namespace. You could create the same Pod in the `default`
+namespace with no warnings.
 
 ## Clean up
 

content/en/examples/security/example-baseline-pod.yaml

@@ -0,0 +1,10 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: nginx
+spec:
+  containers:
+    - image: nginx
+      name: nginx
+      ports:
+        - containerPort: 80

content/en/examples/security/kind-with-cluster-level-baseline-pod-security.sh

@@ -51,11 +51,12 @@ nodes:
     # default None
     propagation: None
 EOF
-kind create cluster --name psa-with-cluster-pss --image kindest/node:v1.23.0 --config /tmp/pss/cluster-config.yaml
+kind create cluster --name psa-with-cluster-pss --config /tmp/pss/cluster-config.yaml
 kubectl cluster-info --context kind-psa-with-cluster-pss
+
 # Wait for 15 seconds (arbitrary) ServiceAccount Admission Controller to be available
 sleep 15
-cat <<EOF > /tmp/pss/nginx-pod.yaml
+cat <<EOF |
 apiVersion: v1
 kind: Pod
 metadata:
@@ -67,4 +68,17 @@ spec:
       ports:
         - containerPort: 80
 EOF
-kubectl apply -f /tmp/pss/nginx-pod.yaml
+kubectl apply -f -
+
+# Await input
+sleep 1
+( bash -c 'true' 2>/dev/null && bash -c 'read -p "Press any key to continue... " -n1 -s' ) || \
+    ( printf "Press Enter to continue... " && read ) 1>&2
+
+# Clean up
+printf "\n\nCleaning up:\n" 1>&2
+set -e
+kubectl delete pod --all -n example --now
+kubectl delete ns example
+kind delete cluster --name psa-with-cluster-pss
+rm -f /tmp/pss/cluster-config.yaml

content/en/examples/security/kind-with-namespace-level-baseline-pod-security.sh

@@ -1,19 +1,21 @@
 #!/bin/sh
-# Until v1.23 is released, kind node image needs to be built from k/k master branch
-# Ref: https://kind.sigs.k8s.io/docs/user/quick-start/#building-images
-kind create cluster --name psa-ns-level --image kindest/node:v1.23.0
+kind create cluster --name psa-ns-level
 kubectl cluster-info --context kind-psa-ns-level
-# Wait for 15 seconds (arbitrary) ServiceAccount Admission Controller to be available
+# Wait for 15 seconds (arbitrary) for ServiceAccount Admission Controller to be available
 sleep 15
-kubectl create ns example
+
+# Create and label the namespace
+kubectl create ns example || exit 1 # if namespace exists, don't do the next steps
 kubectl label --overwrite ns example \
   pod-security.kubernetes.io/enforce=baseline \
   pod-security.kubernetes.io/enforce-version=latest \
   pod-security.kubernetes.io/warn=restricted \
   pod-security.kubernetes.io/warn-version=latest \
   pod-security.kubernetes.io/audit=restricted \
   pod-security.kubernetes.io/audit-version=latest
-cat <<EOF > /tmp/pss/nginx-pod.yaml
+
+# Try running a Pod
+cat <<EOF |
 apiVersion: v1
 kind: Pod
 metadata:
@@ -25,4 +27,16 @@ spec:
       ports:
         - containerPort: 80
 EOF
-kubectl apply -n example -f /tmp/pss/nginx-pod.yaml
+kubectl apply -n example -f -
+
+# Await input
+sleep 1
+( bash -c 'true' 2>/dev/null && bash -c 'read -p "Press any key to continue... " -n1 -s' ) || \
+    ( printf "Press Enter to continue... " && read ) 1>&2
+
+# Clean up
+printf "\n\nCleaning up:\n" 1>&2
+set -e
+kubectl delete pod --all -n example --now
+kubectl delete ns example
+kind delete cluster --name psa-ns-level