2579: psp migration

Author: liggitt

keps/sig-auth/2579-psp-replacement/README.md

@@ -41,6 +41,7 @@
   - [Scalability](#scalability)
   - [Troubleshooting](#troubleshooting)
 - [Optional Future Extensions](#optional-future-extensions)
+  - [Automated PSP migration tooling](#automated-psp-migration-tooling)
   - [Rollout of baseline-by-default for unlabeled namespaces](#rollout-of-baseline-by-default-for-unlabeled-namespaces)
   - [Custom Profiles](#custom-profiles)
   - [Custom Warning Messages](#custom-warning-messages)
@@ -661,47 +662,35 @@ The following audit annotations will be added:
 5. `pod-security.kubernetes.io/exempt = [user, namespace, runtimeClass]` For exempt requests, record the parameters
    that triggered the exemption here.
 
-### PodSecurityPolicy Migration
-
-<<[UNRESOLVED]>>
 
-_Targeting Beta or GA, non-blocking for Alpha._
+### PodSecurityPolicy Migration
 
 Migrating to the replacement policy from PodSecurityPolicies can be done effectively using a
 combination of dry-run and audit/warn modes (although this becomes harder if mutating PSPs are
 used).
 
-We could also ship a standalone tool to assist with the PodSecurityPolicy migration. Here are some
-ideas for the sorts of things the tool could assist with:
-
-- Analyze PSP resources, identify the closest profile level, and highlight the differences
-- Check the authorization mode for existing pods. For example, if a pod’s service account is not
-  authorized to use the PSP that validated it (based on the `kubernetes.io/psp` annotation), then
-  that should trigger a warning.
-- Automate the dry-run and/or labeling process.
-- Automatically select (and optionally apply) a policy level for each namespace.
-
-We should also publish a step-by-step migration guide. A rough approach might look something like
+Publish a step-by-step migration guide. A rough approach might look something like
 this, with the items tagged (automated) having support from the PSP migration tool.
 
-1. Enable 3-tier policy admission plugin, default everything to privileged.
+1. Enable the `PodSecurity` admission plugin, default everything to privileged.
 2. Eliminate mutating PSPs:
-    1. Clone all mutating PSPs to a non-mutating version (automated)
+    1. Clone all mutating PSPs to a non-mutating version
     2. Update all ClusterRoles authorizing use of the mutating PSPs to also authorize use of the
-       non-mutating variant (automated)
+       non-mutating variant
     3. Watch for pods using the mutating PSPs (check via the `kubernetes.io/psp` annotation), and
        work with code owners to migrate to valid non-mutating resources.
     4. Delete mutating PSPs
-3. Select a compatible profile for each namespace, based on the existing resources in the namespace
-   (automated)
-    1. Review the profile choices
-    2. Evaluate the difference in privileges that would come from disabling the PSP controller
-       (automated).
-4. (optional) Apply the profiles in `warn` and `audit` mode (automated)
-5. Apply the profiles in `enforce` mode (automated)
-6. Disable PodSecurityPolicy
+3. Select a compatible pod security level for each namespace, based on the existing resources in the namespace
+    1. Review the pod security level choices
+    2. Evaluate the difference in privileges that would come from disabling the PSP controller.
+4. Apply the pod security levels in `warn` and `audit` mode
+5. Iterate on Pod and workload configurations until no warnings or audit violations exist
+6. Apply the pod security levels in `enforce` mode
+7. Disable `PodSecurityPolicy` admission plugin
+
+This was published at https://kubernetes.io/docs/tasks/configure-pod-container/migrate-from-psp/ in 1.22.
+
 
-<<[/UNRESOLVED]>>
 
 ### Graduation Criteria
 
@@ -974,6 +963,20 @@ which case they should be moved out of this section).
 
 This whole section should be considered <<[UNRESOLVED]>>.
 
+### Automated PSP migration tooling
+
+We could also ship a standalone tool to assist with the steps identified above.
+Here are some ideas for the sorts of things the tool could assist with:
+
+- Analyze PSP resources
+  - identify mutating PSPs
+  - for non-mutating PSPs, identify the closest Pod Security Standards levels and highlight the differences
+- Check the authorization mode for existing pods. For example, if a pod’s service account is not
+  authorized to use the PSP that validated it (based on the `kubernetes.io/psp` annotation), then
+  that should trigger a warning.
+- Automate the dry-run and/or labeling process.
+- Automatically select (and optionally apply) a policy level for each namespace.
+
 ### Rollout of baseline-by-default for unlabeled namespaces
 
 If we wanted to change the default-default value from privileged to baseline, here is a possible