Monitor a Cluster

What you’ll accomplish

UDS clusters include two Kubernetes controllers built with Pepr. By the end of this guide you’ll know how to:

• Stream logs from both controllers in a single view
• Filter logs by controller type or policy action
• Use flags to control output format and history

Prerequisites

• UDS CLI installed
• Access to a running UDS cluster

Before you begin

UDS Core runs two Pepr-based controllers that uds monitor streams logs from:

Controller	Pod prefix	Responsibility
Admission Controller	pepr-uds-core	Validates and mutates resources; enforces UDS Exemptions
Operator Controller	pepr-uds-core-watcher	Manages lifecycle of UDS Package resources

Steps

1. Confirm the controllers are running

   uds zarf tools kubectl get pods -n pepr-system

   You should see pepr-uds-core-* and pepr-uds-core-watcher-* pods in a Running state before proceeding.

2. Stream logs

   Run the command matching what you want to observe:

   All logs: aggregate admission and operator logs into a single stream:

   uds monitor pepr

   Operator logs only: UDS Package processing, status updates, and errors:

   uds monitor pepr operator

   All policy decisions (allow, deny, mutate):

   uds monitor pepr policies

   Specific policy actions:

   uds monitor pepr allowed   # allow logs
   uds monitor pepr denied    # deny logs
   uds monitor pepr mutated   # mutation logs
   uds monitor pepr failed    # deny + operator error logs

3. (Optional) Refine with flags

   Flag	Description
   -f, --follow	Continuously stream logs (keep the session open)
   --json	Return raw JSON output
   --since <duration>	Only show logs newer than the given duration (e.g., 5s, 2m, 3h). Defaults to all logs.
   -t, --timestamps	Show timestamps in log output

   # Follow all logs with timestamps
   uds monitor pepr --follow --timestamps
   
   # Show only the last 5 minutes of policy deny logs
   uds monitor pepr denied --since 5m
   
   # Get raw JSON for programmatic processing
   uds monitor pepr --json

Verification

Confirm logs are streaming by running:

uds monitor pepr --follow

You should see a continuous stream of admission and operator events as activity occurs in the cluster.

Troubleshooting

Problem: No logs returned

Symptom: uds monitor pepr returns immediately with no output.

Solution: Confirm the cluster is a UDS cluster with Pepr installed.

Problem: Connection error

Symptom: An error connecting to the cluster when running uds monitor pepr.

Solution: Verify kubectl can reach the cluster with kubectl get nodes.

Problem: Log stream cuts off

Symptom: Logs stop streaming after a short time.

Solution: Add --follow to keep the stream open.

Related Documentation

• Use Bundle Overrides: Tune deployments at runtime with Helm overrides and variables.
• Use UDS Runner: Automate workflows with tasks.yaml.