podsecurityreadinesscontroller: create classification, add README

Author: ibihim

pkg/operator/podsecurityreadinesscontroller/README.md

@@ -0,0 +1,113 @@
+# Pod Security Readiness Controller
+
+The Pod Security Readiness Controller evaluates namespace compatibility with Pod Security Admission (PSA) enforcement in clusters.
+
+## Purpose
+
+This controller performs dry-run PSA evaluations to determine which namespaces would experience pod creation failures if PSA enforcement labels were applied.
+
+The controller generates telemetry data for `ClusterFleetEvaluation` and helps us to understand PSA compatibility before enabling enforcement.
+
+## Implementation
+
+The controller follows this evaluation algorithm:
+
+1. **Namespace Discovery** - Find namespaces without PSA enforcement
+2. **PSA Level Determination** - Predict what enforcement level would be applied
+3. **Dry-Run Evaluation** - Test namespace against predicted PSA level
+4. **Violation Classification** - Categorize any violations found for telemetry
+
+### Namespace Discovery
+
+Selects namespaces without PSA enforcement labels:
+
+```go
+selector := "!pod-security.kubernetes.io/enforce"
+```
+
+### PSA Level Determination
+
+The controller determines the effective PSA enforcement level using this precedence:
+
+1. `security.openshift.io/MinimallySufficientPodSecurityStandard` annotation
+2. Most restrictive of existing `pod-security.kubernetes.io/warn` or `pod-security.kubernetes.io/audit` labels, if owned by the PSA label syncer
+3. Kube API server's future global default: `restricted`
+
+### Dry-Run Evaluation
+
+The controller performs the equivalent of this oc command:
+
+```bash
+oc label --dry-run=server --overwrite namespace $NAMESPACE_NAME \
+    pod-security.kubernetes.io/enforce=$POD_SECURITY_STANDARD
+```
+
+PSA warnings during dry-run indicate the namespace contains violating workloads.
+
+### Violation Classification
+
+Violating namespaces are categorized for telemetry analysis:
+
+| Classification   | Criteria                                                        | Purpose                                |
+|------------------|-----------------------------------------------------------------|----------------------------------------|
+| `runLevelZero`   | Core namespaces: `kube-system`, `default`, `kube-public`        | Platform infrastructure tracking       |
+| `openshift`      | Namespaces with `openshift-` prefix                             | OpenShift component tracking           |
+| `disabledSyncer` | Label `security.openshift.io/scc.podSecurityLabelSync: "false"` | Intentionally excluded namespaces      |
+| `userSCC`        | Contains user workloads that violate PSA                        | SCC vs PSA policy conflicts |
+| `customer`       | All other violating namespaces                                  | Customer workload compatibility issues |
+| `inconclusive`   | Evaluation failed due to API errors                             | Operational problems                   |
+
+#### User SCC Detection
+
+The PSA label syncer bases its evaluation exclusively on a ServiceAccount's SCCs, ignoring a user's SCCs.
+When a pod's SCC assignment comes from user permissions rather than its ServiceAccount, the syncer's predicted PSA level may be incorrect.
+Therefore we need to evaluate the affected pods (if any) against the target PSA level.
+
+### Inconclusive Handling
+
+When the evaluation process fails, namespaces are marked as `inconclusive`.
+
+Common causes for inconclusive results:
+
+- **API server unavailable** - Network timeouts, etcd issues
+- **Resource conflicts** - Concurrent namespace modifications
+- **Invalid PSA levels** - Malformed enforcement level strings
+- **Pod listing failures** - RBAC issues or resource pressure
+
+High rates of inconclusive results across the fleet may indicate systematic issues that requires investigation.
+
+## Output
+
+The controller updates `OperatorStatus` conditions for each violation type:
+
+```go
+type podSecurityOperatorConditions struct {
+    violatingRunLevelZeroNamespaces   []string
+    violatingOpenShiftNamespaces      []string  
+    violatingDisabledSyncerNamespaces []string
+    violatingCustomerNamespaces       []string
+    userSCCViolationNamespaces        []string
+    inconclusiveNamespaces            []string
+}
+```
+
+Conditions follow the pattern:
+
+- `PodSecurity{Type}EvaluationConditionsDetected`
+- Status: `True` (violations found) / `False` (no violations)
+- Message includes violating namespace list
+
+## Configuration
+
+The controller runs with a configurable interval (default: 4 hours) and uses rate limiting to avoid overwhelming the API server:
+
+```go
+kubeClientCopy.QPS = 2
+kubeClientCopy.Burst = 2  
+```
+
+## Integration Points
+
+- **PSA Label Syncer**: Reads syncer-managed PSA labels to predict enforcement levels
+- **Cluster Operator**: Reports status through standard operator conditions
+- **Telemetry**: Violation data feeds into cluster fleet analysis systems

pkg/operator/podsecurityreadinesscontroller/classification.go

@@ -0,0 +1,133 @@
+package podsecurityreadinesscontroller
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	securityv1 "github.com/openshift/api/security/v1"
+	corev1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/util/sets"
+	"k8s.io/klog/v2"
+	psapi "k8s.io/pod-security-admission/api"
+)
+
+var (
+	runLevelZeroNamespaces = sets.New[string](
+		"default",
+		"kube-system",
+		"kube-public",
+		"kube-node-lease",
+	)
+)
+
+func (c *PodSecurityReadinessController) classifyViolatingNamespace(ctx context.Context, conditions *podSecurityOperatorConditions, ns *corev1.Namespace, enforceLevel string) error {
+	if runLevelZeroNamespaces.Has(ns.Name) {
+		conditions.addViolatingRunLevelZero(ns)
+		return nil
+	}
+	if strings.HasPrefix(ns.Name, "openshift") {
+		conditions.addViolatingOpenShift(ns)
+		return nil
+	}
+	if ns.Labels[labelSyncControlLabel] == "false" {
+		conditions.addViolatingDisabledSyncer(ns)
+		return nil
+	}
+
+	// TODO@ibihim: increase log level
+	klog.InfoS("Checking for user violations", "namespace", ns.Name, "enforceLevel", enforceLevel)
+	isUserViolation, err := c.isUserViolation(ctx, ns, enforceLevel)
+	if err != nil {
+		klog.V(2).ErrorS(err, "Error checking user violations", "namespace", ns.Name)
+		// Transient API server error or temporary resource unavailability (most likely).
+		// Theoretically, psapi parsing errors could occur that retry without hope for recovery.
+		return err
+	}
+
+	// TODO@ibihim: increase log level
+	klog.InfoS("User violation check result", "namespace", ns.Name, "isUserViolation", isUserViolation)
+	if isUserViolation {
+		// TODO@ibihim: increase log level
+		klog.InfoS("Adding namespace to user SCC violations", "namespace", ns.Name)
+		conditions.addViolatingUserSCC(ns)
+		return nil
+	}
+
+	// Historically, we assume that this is a customer issue, but
+	// actually it means we don't know what the root cause is.
+	conditions.addViolatingCustomer(ns)
+
+	return nil
+}
+
+func (c *PodSecurityReadinessController) isUserViolation(ctx context.Context, ns *corev1.Namespace, label string) (bool, error) {
+	var enforcementLevel psapi.Level
+	switch strings.ToLower(label) {
+	case "restricted":
+		enforcementLevel = psapi.LevelRestricted
+	case "baseline":
+		enforcementLevel = psapi.LevelBaseline
+	case "privileged":
+		// If privileged is violating, something is seriously wrong
+		// but testing against privileged level is pointless (everything passes)
+		klog.V(2).InfoS("Namespace violating privileged level - skipping user check",
+			"namespace", ns.Name)
+		return false, nil
+	default:
+		return false, fmt.Errorf("unknown level: %q", label)
+	}
+
+	allPods, err := c.kubeClient.CoreV1().Pods(ns.Name).List(ctx, metav1.ListOptions{})
+	if err != nil {
+		klog.V(2).ErrorS(err, "Failed to list pods in namespace", "namespace", ns.Name)
+		return false, err
+	}
+
+	var userPods []corev1.Pod
+	for _, pod := range allPods.Items {
+		// TODO@ibihim: we should exclude Pod that have restricted-v2.
+		// restricted-v2 SCCs are allowed for all system:authenticated. ServiceAccounts
+		// are able to use that, but they are not part of the group. So restricted-v2
+		// will always result in user.
+		if pod.Annotations[securityv1.ValidatedSCCSubjectTypeAnnotation] == "user" {
+			userPods = append(userPods, pod)
+		}
+	}
+
+	if len(userPods) == 0 {
+		return false, nil // No user pods = violation is from service accounts
+	}
+
+	enforcementVersion := psapi.LatestVersion()
+	for _, pod := range userPods {
+		klog.InfoS("Evaluating user pod against PSA level",
+			"namespace", ns.Name, "pod", pod.Name, "level", label,
+			"podSecurityContext", pod.Spec.SecurityContext)
+
+		results := c.psaEvaluator.EvaluatePod(
+			psapi.LevelVersion{Level: enforcementLevel, Version: enforcementVersion},
+			&pod.ObjectMeta,
+			&pod.Spec,
+		)
+
+		klog.InfoS("PSA evaluation results",
+			"namespace", ns.Name, "pod", pod.Name, "level", label,
+			"resultCount", len(results))
+
+		for _, result := range results {
+			klog.InfoS("PSA evaluation result",
+				"namespace", ns.Name, "pod", pod.Name, "level", label,
+				"allowed", result.Allowed, "reason", result.ForbiddenReason,
+				"detail", result.ForbiddenDetail)
+			if !result.Allowed {
+				klog.InfoS("User pod violates PSA level",
+					"namespace", ns.Name, "pod", pod.Name, "level", label)
+				return true, nil
+			}
+		}
+	}
+
+	return false, nil
+}