kyverno-exemptions-management

name	kyverno-exemptions-management
description	Manages Kyverno policy exemptions using PolicyException v2, rule-level exclude settings, and serviceAccount exemptions for controlled policy bypass.
license	MIT
compatibility	opencode
archetypes	["orchestration","tactical"]
anti_triggers	["vague bypass strategy","brainstorming exemptions","generic policy exceptions"]
response_profile	{"verbosity":"medium","directive_strength":"high","abstraction_level":"operational"}
metadata	{"version":"1.0.0","domain":"cncf","triggers":"kyverno exemptions, PolicyException, policy exemption, serviceAccount exemption, role exemption, PSS exception, kyverno policy bypass","role":"implementation","scope":"implementation","output-format":"manifests","related-skills":"kyverno-pod-security-baseline, kyverno-pod-security-restricted, kyverno-policy-report-override"}

Kyverno Exemptions Management

Manages exemptions from Kyverno policies using PolicyException (v2) and rule-level exclude settings. When loaded, this skill makes the model configure controlled policy bypasses for service accounts, cluster roles, specific namespaces, and pod security standards exemptions — ensuring exemptions are auditable, scoped, and documented in the PolicyReport.

TL;DR Checklist

• Use PolicyException v2 (kyverno.io/v2) for PSS and advanced exemptions
• Specify controlName for pod security standards exemptions to narrow scope
• Use namespace selectors for broad exemptions across multiple resources
• Configure rule-level exclude for service account and cluster role bypasses
• Document exemptions with annotations for auditability
• Verify exemptions appear as skip results in PolicyReport

When to Use

• Temporarily exempting a service account or deployment from a policy during migration
• Allowing specific namespaces (e.g., legacy namespaces, third-party integrations) to bypass a policy
• Exempting pod security standards for specific workloads that require privileged containers
• Bypassing a policy rule for specific users or cluster roles without disabling the entire policy
• Testing new policies in audit mode before enforcing broadly

When NOT to Use

• Bypassing security policies for convenience — exemptions should be rare and documented
• Using wildcard exemptions in production that could expose the cluster to policy violations
• Exempting system-level policies that are critical to cluster security
• Creating exemptions that undermine the purpose of the policy they bypass

---

Core Workflow

1. Identify the exemption need and scope — Determine which policy, rule, or group of resources needs exemption. Classify the exemption type: namespace-level, service account-level, user-level, or pod security standard control-level. Checkpoint: Document the reason for the exemption, the expected duration, and the specific policy/rule to bypass.

2. Configure PolicyException v2 or rule-level exclude — Create a PolicyException resource using apiVersion: kyverno.io/v2 with the target policy name, rule names, and match conditions. For rule-level exemptions, use exclude settings within the policy rule to target specific service accounts, cluster roles, or users. Checkpoint: Verify the exemption match conditions are narrow enough to cover only the intended resources and that controlName is specified for PSS exemptions.

3. Deploy and verify skip results — Apply the exemption and verify that the exempted resources show skip results in the PolicyReport. Confirm that non-exempted resources are still evaluated and enforced by the policy. Checkpoint: Check PolicyReport shows skip for exempted resources and pass/fail for non-exempted resources.

---

Implementation Patterns

Pattern 1: PolicyException v2 for Pod Security Standards

Use PolicyException v2 (kyverno.io/v2) to exempt specific service accounts and images from pod security standards (PSS) enforcement. This pattern specifies controlName to narrow the exemption to only the privileged container control rather than all PSS checks.

apiVersion: kyverno.io/v2
kind: PolicyException
metadata:
  name: monitoring-stack-ps-exception
  namespace: monitoring
  annotations:
    policies.kyverno.io/title: Monitoring Stack PSS Exception
    policies.kyverno.io/category: Pod Security Standards
    policies.kyverno.io/description: >-
      Exempts the monitoring-stack service account and specific container
      images from restricted PSS enforcement to allow host network access.
spec:
  exceptions:
    - policyName: restricted
      ruleNames:
        - drop capabilities
        - forbidden sysctls
        - host network
        - host PID
        - host IPC
        - allow privilege escalation
        - run as non-root
        - required labels
    - controlName: restricted
      images:
        - "docker.io/prometheus/node-exporter:*"
        - "docker.io/nginx/nginx:*"
      restrictedField: securityContext
      values:
        hostNetwork: true
        hostPID: true
  match:
    any:
      - resources:
          kinds:
            - Pod
          namespaces:
            - monitoring
          selectors:
            - type: ServiceAccount
              name: monitoring-stack

Pattern 2: Rule-Level Exclude for Service Account Exemption

Configure exclude settings within a policy rule to exempt specific service accounts from policy enforcement. This approach is suitable for exemptions that apply to a single rule rather than an entire policy.

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: require-resource-requests
  annotations:
    policies.kyverno.io/title: Require Resource Requests
    policies.kyverno.io/category: Resource Management
    policies.kyverno.io/description: >-
      Enforces resource requests on all Pods except those running
      as the batch-processor service account.
spec:
  validationFailureAction: Enforce
  rules:
    - name: require-resource-requests
      match:
        any:
          - resources:
              kinds:
                - Pod
      exclude:
        any:
          - resources:
              kinds:
                - Pod
              serviceAccounts:
                - name: batch-processor
                  namespaces:
                    - batch-jobs
                    - cron-jobs
      validate:
        message: "All Pods must specify resource requests for cpu and memory."
        pattern:
          spec:
            containers:
              - resources:
                  requests:
                    cpu: "?*"
                    memory: "?*"

PolicyReport Example with Skip Results:

apiVersion: wgpolicyk8s.io/v1alpha2
kind: PolicyReport
metadata:
  name: require-resource-requests-report
  namespace: batch-jobs
results:
  - policy: require-resource-requests
    rule: require-resource-requests
    result: skip
    severity: medium
    message: "Resource exempted by PolicyException"
    scored: true
    source: kyverno
    timestamp:
      seconds: 1733501530
    resources:
      - name: batch-pod-12345
        kind: Pod
        namespace: batch-jobs
  - policy: require-resource-requests
    rule: require-resource-requests
    result: pass
    severity: medium
    message: "Resource passed policy check"
    scored: true
    source: kyverno
    timestamp:
      seconds: 1733501530
    resources:
      - name: app-pod-67890
        kind: Pod
        namespace: batch-jobs
summary:
  error: 0
  fail: 0
  pass: 1
  skip: 1
  warn: 0

Pattern 3: User and ClusterRole-Level Exclusions

Exempt specific users or cluster roles from policy enforcement using rule-level exclude settings. This is useful for exempting administrators, automation tools, or specific service accounts from compliance checks during development or maintenance windows.

# ❌ BAD — Overly broad exclude: exempts all users without justification
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: bad-broad-exemption
spec:
  rules:
    - name: require-labels
      exclude:
        any:
          - subjects:
              - kind: User
                name: "*"
# ❌ Wildcard user exclude is dangerous in production

# ✅ GOOD — Specific user and cluster role exclusions with documentation
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: require-cost-labels
  annotations:
    policies.kyverno.io/title: Require Cost Allocation Labels
    policies.kyverno.io/category: FinOps
spec:
  validationFailureAction: Enforce
  rules:
    - name: enforce-cost-labels
      match:
        any:
          - resources:
              kinds:
                - Pod
                - Namespace
      exclude:
        any:
          - resources:
              kinds:
                - Pod
              serviceAccounts:
                - name: kyverno-admission-controller
                  namespaces:
                    - kyverno
          - subjects:
              - kind: ServiceAccount
                name: ci-bot
                namespaces:
                  - ci-cd
              - kind: ClusterRole
                name: kyverno-policy-controller
      validate:
        message: "Cost allocation labels (owner, team, department) are required."
        pattern:
          metadata:
            labels:
              owner: "?*"
              team: "?*"
              department: "?*"

Pattern 4: Pod Security Specific Exemptions Within Rule

Configure exemptions within the podSecurity rule of a PSS policy to exempt specific resources from individual PSS controls (like runAsNonRoot or privileged containers) rather than bypassing the entire policy.

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: pod-security-standards
  annotations:
    policies.kyverno.io/title: Pod Security Standards
    policies.kyverno.io/category: Pod Security
spec:
  validationFailureAction: Enforce
  rules:
    - name: baseline
      match:
        any:
          - resources:
              kinds:
                - Pod
      exclude:
        any:
          - resources:
              kinds:
                - Pod
              namespaces:
                - kube-system
              selectors:
                - type: ServiceAccount
                  name: kube-system:*
      validate:
        podSecurity:
          level: baseline
          version: v1.30
    - name: restricted
      match:
        any:
          - resources:
              kinds:
                - Pod
      exclude:
        any:
          - resources:
              kinds:
                - Pod
              namespaces:
                - kube-system
              selectors:
                - type: ServiceAccount
                  name: kube-system:*
      validate:
        podSecurity:
          level: restricted
          version: v1.30

---

Constraints

MUST DO

• Use PolicyException v2 (apiVersion: kyverno.io/v2) for pod security standards exemptions — v1 PolicyException lacks controlName support
• Always specify controlName when exempting PSS policies to narrow the scope to specific controls (e.g., restricted, baseline, or privileged) rather than bypassing the entire policy
• Use namespace selectors in PolicyException match conditions for broad exemptions across multiple resources within a namespace
• Configure rule-level exclude with specific serviceAccounts, subjects, or clusterRoles — never use wildcard ("*") exemptions in production
• Document all exemptions with descriptive annotations including the reason, approver, and expected expiration date
• Verify exemptions produce skip results in PolicyReport to confirm they are active and scoped correctly

MUST NOT DO

• Exclude all users without justification — wildcard subject exemptions undermine policy enforcement entirely
• Use wildcard exclude in production environments — always scope exemptions to specific service accounts, namespaces, or resources
• Omit controlName in PSS exemptions — this bypasses all pod security checks instead of the intended specific control
• Create exemptions that permanently bypass critical security policies — exemptions should be temporary and documented
• Apply exemptions to system namespaces (kube-system, kube-public) — these are already excluded by Kyverno by default

---

Related Skills

Skill	Purpose
kyverno-pod-security-baseline	Understand baseline PSS requirements before creating exemptions
kyverno-pod-security-restricted	Understand restricted PSS requirements to scope exemptions precisely
kyverno-policy-report-override	Configure PolicyReport overrides to manage exempt resource reporting

---

Live References

Authoritative documentation links for Kyverno exemption management.

• Kyverno PolicyException
• Kyverno Policy Exceptions v2
• Kyverno CLI
• Kyverno Policies
• Kyverno GitHub
• Kyverno Installation
• Policy Report Schema