Create UDS policy exemptions

What you’ll accomplish

You’ll create a UDS Exemption CR to allow a workload to bypass specific UDS policies when a code-level fix isn’t possible.

Prerequisites

UDS CLI installed
Access to a Kubernetes cluster with UDS Core deployed
The exemption policy names for your workload (see Policy Engine reference)

Before you begin

UDS Core uses Pepr to enforce policies on every resource submitted to the cluster. When a workload legitimately requires behavior that policy blocks (for example, a privileged DaemonSet for node-level monitoring), you can create an Exemption CR to bypass specific policies for targeted resources.

Steps

Create the Exemption CR manifest

Each exemption specifies which policies to bypass (see the Policy Engine reference for exemption names) and a matcher that targets specific resources:
exemption.yaml
```
apiVersion: uds.dev/v1alpha1
kind: Exemption
metadata:
  name: my-app-exemptions
  namespace: uds-policy-exemptions
spec:
  exemptions:
    - policies:
        - DisallowPrivileged
        - RequireNonRootUser
      matcher:
        namespace: my-namespace
        name: "^my-privileged-pod.*"
        kind: pod
      title: "Privileged monitoring agent"
      description: "Requires privileged access for node-level metrics collection"
```
Matcher fields:

Field Description Required
namespace Namespace of the target resource Yes
name Resource name (supports regex, e.g., "^my-pod.*") Yes
kind Resource kind: pod or service (defaults to pod) No

Exemptions should be used sparingly and with justification. Each exemption reduces the cluster’s security posture. Always document the reason in the title and description fields, as these are visible in audits.

Field	Description	Required
`namespace`	Namespace of the target resource	Yes
`name`	Resource name (supports regex, e.g., `"^my-pod.*"`)	Yes
`kind`	Resource kind: `pod` or `service` (defaults to `pod`)	No

(Optional) Add multiple exemption entries

A single Exemption resource can contain multiple entries targeting different policies and matchers:

apiVersion: uds.dev/v1alpha1
kind: Exemption
metadata:
  name: my-app-exemptions
  namespace: uds-policy-exemptions
spec:
  exemptions:
    - policies:
        - DisallowPrivileged
        - RequireNonRootUser
      matcher:
        namespace: my-namespace
        name: "^my-privileged-pod.*"
      title: "Privileged agent"
      description: "Requires privileged access for node-level metrics collection"
    - policies:
        - DisallowNodePortServices
      matcher:
        namespace: my-namespace
        name: "^my-nodeport-svc.*"
        kind: service
      title: "NodePort service"
      description: "Exposed via NodePort for external load balancer integration"

Deploy the Exemption

(Recommended) Include the Exemption manifest in your Zarf package and create/deploy. See Packaging applications for general packaging guidance.
Terminal window
```
uds zarf package create --confirm
uds zarf package deploy zarf-package-*.tar.zst --confirm
```
Or apply the Exemption directly for quick testing:
Terminal window
```
uds zarf tools kubectl apply -f exemption.yaml
```

Verification

After deploying the exemption, confirm it is active and your workload is running:

# Verify the Exemption CR exists
uds zarf tools kubectl get exemptions -n uds-policy-exemptions

# Check that the target pod has the exemption annotation
uds zarf tools kubectl get pod <pod-name> -n <namespace> -o yaml | \
  uds zarf tools yq '(.metadata.annotations // {}) | to_entries[] | select(.value == "exempted")'

# Verify pods are running
uds zarf tools kubectl get pods -n <namespace>

Success criteria:

All pods are Running and Ready
Exempted pods show uds-core.pepr.dev/uds-core-policies.<POLICY>: exempted annotations
No admission webhook denial events

Troubleshooting

Problem: Exemption not taking effect

Symptom: The workload is still blocked despite an Exemption CR being deployed.

Solution: Verify the following:

The Exemption CR is in the uds-policy-exemptions namespace (or all-namespace exemptions are enabled)
The matcher.namespace matches the workload’s namespace exactly
The matcher.name regex matches the resource name. Test your regex against the actual pod/service name.
The matcher.kind is correct (pod for pods, service for services)

If the exemption exists but still isn’t being applied, see the Exemptions & Packages Not Updating runbook for detailed diagnostics.

Policy Engine - full reference of all enforced policies, severity levels, and blocked annotations
Exemption CR specification - full CR schema and field reference
Policy Violations runbook - diagnose and fix admission failures and unexpected mutations

Next steps

These guides and concepts may be useful to explore next:

Configure infrastructure exemptions Set up exemptions via bundle overrides for Core components and infrastructure workloads.

Audit security posture Review exemptions and Package CR network rules across your cluster.

Cookie Settings Privacy Policy