Pod Security Admission (PSA) - AI-Optimized Technical Reference

Core Functionality

What PSA Does:

• Built-in Kubernetes validating admission controller (enabled by default since v1.23)
• Enforces three predefined security profiles via namespace labels
• Replaces deprecated Pod Security Policies (PSPs) removed in v1.25
• Validates pods before creation, rejects non-compliant workloads immediately

Key Technical Advantage:

• Namespace-label based policy assignment eliminates RBAC complexity
• Built into API server (no webhook timeouts or external dependencies)
• Sub-millisecond validation performance (<1ms per pod)

Configuration That Works in Production

Essential Namespace Configuration

apiVersion: v1
kind: Namespace
metadata:
  name: production-workloads
  labels:
    pod-security.kubernetes.io/enforce: restricted
    pod-security.kubernetes.io/enforce-version: v1.29  # CRITICAL: Always pin version
    pod-security.kubernetes.io/audit: restricted
    pod-security.kubernetes.io/audit-version: v1.29
    pod-security.kubernetes.io/warn: baseline
    pod-security.kubernetes.io/warn-version: v1.29

Critical Configuration Requirements:

• Always pin version (enforce-version: v1.29) - Kubernetes upgrades change policy rules without warning
• Use three enforcement modes during rollout:
  • audit: Logs violations without blocking (for discovery)
  • warn: Shows warnings to users (for preparation)
  • enforce: Blocks violating pods (for production)

Security Profile Selection

Profile	Use Case	Blocks	Allows
Privileged	System pods, legacy apps	Nothing	Root users, host access, privileged containers
Baseline	Most production workloads	Privileged containers, host networking	Root users, most capabilities
Restricted	Cloud-native apps only	Root users, most capabilities, host access	Non-root only, read-only root FS

Profile Selection Reality:

• Privileged: Required for kube-proxy, CNI drivers, most legacy applications
• Baseline: Where 80% of production workloads end up (developers haven't fixed root user dependencies)
• Restricted: Only works for applications designed with security from day one

Implementation Failure Scenarios

Critical Migration Failures

PSP to PSA Migration Gotchas:

• Existing pods continue running but fail to restart when nodes drain/pods crash
• Friday afternoon PSA enablement → Monday morning half the applications down
• Missing version pinning → Kubernetes upgrades silently change security policies
• Global audit mode → Thousands of violation logs flood monitoring systems

Common Production Failures

Pod Rejection Scenarios:

# This will fail in restricted mode - missing security context
spec:
  containers:
  - name: app
    image: myapp:latest
    # ERROR: No securityContext specified

Required Fix for Restricted Mode:

spec:
  securityContext:
    runAsNonRoot: true
    runAsUser: 1000
    runAsGroup: 1000
  containers:
  - name: app
    image: myapp:latest
    securityContext:
      allowPrivilegeEscalation: false
      readOnlyRootFilesystem: true
      capabilities:
        drop: ["ALL"]

Hidden Validation Requirements:

• Both pod AND container security contexts required for restricted mode
• Init containers must also comply with namespace policy
• Ephemeral containers validated against same rules
• Sidecar containers injected by operators can violate policy and block entire pod

Cloud Provider Specific Issues

Amazon EKS:

• Works as expected, no surprises
• PSA enabled in privileged mode by default

Google GKE:

• Standard clusters: Normal PSA behavior
• Autopilot clusters: Forces baseline mode, cannot override to privileged for user workloads
• Migration blocker: Legacy monitoring stacks requiring privileged access

Azure AKS:

• Policy conflict hell: PSA AND Azure Policy can fight each other
• Confusing error messages: Multiple systems blocking same pod with different reasons
• Recommendation: Choose PSA OR Azure Policy, not both

Resource Requirements and Costs

Time Investment for Migration

• Discovery phase: 1-2 weeks running audit mode to identify violations
• Remediation per application: 2-8 hours depending on security context requirements
• Testing and validation: 1 week per environment
• Total migration time: 4-12 weeks for medium-sized clusters

Expertise Requirements

• Kubernetes security context understanding: Medium complexity
• YAML debugging skills: Required for violation troubleshooting
• Namespace organization: Critical for policy boundaries

Hidden Costs

• Increased namespace count: PSA forces proper workload separation
• Application refactoring: Legacy apps requiring root access need code changes
• Monitoring system updates: Need to handle PSA violation logs

Performance and Operational Impact

Performance Characteristics

• Validation latency: <1ms per pod creation
• Memory overhead: Negligible (namespace policies cached in memory)
• CPU impact: Minimal (simple security context comparisons)
• Scale limit: None identified (scales with API server capacity)

Monitoring Requirements

# Essential monitoring commands
kubectl describe pod <pod-name>  # Shows PSA rejection reasons in events
kubectl get events --field-selector type=Warning  # Shows what would break
kubectl get namespace -o yaml  # Verify which policies are active

Decision Criteria: When PSA is Worth It

PSA vs Alternatives Comparison

Solution	Installation	Learning Curve	Policy Flexibility	Maintenance	Performance
PSA	Built-in	Low (3 profiles)	Limited to standards	None	Minimal
OPA Gatekeeper	External deployment	High (Rego language)	Unlimited custom	High monitoring overhead	Low impact
Falco	Daemon deployment	Medium	Event-based only	Daemon management	High CPU usage

Use PSA When:

• Standard security profiles meet requirements
• Want zero operational overhead
• Need consistent policy across cloud providers
• Migrating from deprecated PSPs

Add OPA Gatekeeper When:

• Need custom compliance policies beyond three standard profiles
• Require fine-grained per-workload policies within namespaces
• Compliance frameworks demand specific controls not in PSA

Critical Warnings and Gotchas

What Official Documentation Doesn't Tell You

Version Pinning Critical:

• Unpinned versions (latest) change behavior during Kubernetes upgrades
• Policy rules can become stricter without warning
• Always use specific versions: v1.29 not latest

Namespace Organization Impact:

• Cannot have different security levels for workloads in same namespace
• Forces organizational changes to namespace structure
• Dev/prod workload separation becomes mandatory

Existing Workload Behavior:

• Running pods unaffected by PSA policy changes
• Pods fail to restart during maintenance/crashes if they violate new policies
• Zero-downtime migration requires careful audit mode planning

Breaking Points and Failure Modes

Failure Conditions:

• Legacy applications requiring root access fail restricted mode
• Applications needing host filesystem access fail baseline/restricted modes
• Init containers with privileged requirements break entire pod
• Sidecar injection by service mesh operators can violate policies

Recovery Strategies:

• Temporary privileged mode override for emergency deployments
• Namespace-level policy relaxation during incidents
• Application-specific namespace creation for incompatible workloads

Migration Strategy for Production

Phase 1: Discovery (Week 1-2)

1. Enable audit mode with restricted profile globally
2. Monitor audit logs for violations
3. Catalog applications by security profile requirements
4. Identify applications requiring remediation

Phase 2: Preparation (Week 3-6)

1. Enable warn mode for user feedback
2. Remediate applications for target security profiles
3. Create namespace organization plan
4. Test policy enforcement in staging environments

Phase 3: Enforcement (Week 7-12)

1. Enable enforcement namespace by namespace
2. Start with new applications and least critical workloads
3. Migrate critical production workloads last
4. Maintain emergency override procedures

Phase 4: Optimization (Ongoing)

1. Monitor for policy violations
2. Upgrade applications to higher security profiles when possible
3. Review and tighten policies based on operational experience

Troubleshooting Guide

Common Error Messages and Solutions

Error: violates PodSecurity "restricted:latest": securityContext.runAsNonRoot != true
Solution: Add runAsNonRoot: true and runAsUser: 1000 to pod security context

Error: violates PodSecurity "baseline:latest": allowPrivilegeEscalation != false
Solution: Set allowPrivilegeEscalation: false in container security context

Error: violates PodSecurity "restricted:latest": allowPrivilegeEscalation != false
Solution: Add complete security context with all required fields for restricted mode

Debugging Workflow

1. Check namespace labels with kubectl get namespace <name> -o yaml
2. Verify version pinning is correct for cluster version
3. Review pod security context completeness
4. Test with kubectl apply --dry-run=server before actual deployment
5. Use audit mode temporarily to identify all violations

This technical reference provides the operational intelligence needed for successful PSA implementation while avoiding the common pitfalls that cause production failures.