System Apps

Overview

System Apps are Kubernetes operators that run inside your cluster and extend what PodWarden can do. They are separate from PodWarden itself — you install only the ones you need. PodWarden detects installed operators automatically and enables the corresponding features in the UI.

Without the relevant operator installed, the associated features (e.g. backup scheduling, Helm chart deployment) will not function even if policies are configured.

How PodWarden Detects System Apps

When PodWarden connects to a cluster, it looks for a ConfigMap in each namespace with the label:

podwarden.com/system-app=true

This ConfigMap declares the operator name, version, and capabilities. PodWarden reads it and reflects the status in Settings → System Apps. No polling agent is required — detection happens on each cluster sync.

Available System Apps

Backup Operator

Manages the full backup lifecycle for PodWarden workloads.

What it does:

• Watches BackupPolicy CRDs created by PodWarden
• Schedules and executes BackupRun resources on the defined cron schedule
• Runs Restic inside the cluster to copy volume data to your storage target
• Applies retention rules and manages RestoreRun resources for data recovery

Required for: the Backups feature. Without this operator, backup policies remain in Pending state and backup runs will fail with "BackupPolicy CRD not found" errors.

Install:

kubectl apply -f https://www.podwarden.com/operators/backup-operator/install.yaml

See the Backups guide for full usage documentation.

Admission Webhook

Intercepts direct kubectl operations on PodWarden-managed namespaces and logs bypass events to PodWarden's system messages.

What it does:

• Watches CREATE, UPDATE, and DELETE operations on resources in managed namespaces
• Logs bypass events to PodWarden system messages with context about the resource and operation
• In strict mode, can block direct kubectl operations and suggest the equivalent PodWarden API or MCP tool
• Includes deny messages that reference the correct PodWarden MCP tool for each operation (e.g. deploy_workload, create_ingress_rule)

Required for: detecting when users or LLM agents bypass PodWarden and modify cluster resources directly.

Current version: chart 0.4.0 (updated 2026-05-01).

Install:

The Admission Webhook is automatically installed on cluster registration — no manual installation needed.

Configuration: Go to Settings → Admission Webhook to configure the webhook behavior:

Fail-closed behavior

As of chart 0.4.0 the webhook uses failurePolicy: Fail. This means: if the webhook is unavailable (pods down, image pull failure, timeout), the Kubernetes API server will reject write operations on managed namespaces. This is intentional — it closes the bypass class where disabling the webhook would silently remove enforcement.

In production, the webhook runs with 2 replicas across different nodes (anti-affinity) and is protected by a PodDisruptionBudget (minAvailable: 1) so that node drains cannot simultaneously evict all webhook pods.

For single-node dev clusters you can override to 1 replica via replicaCount: 1 in the Helm values, and disable the PDB via podDisruptionBudget.enabled: false.

Temporary bypass

Temporary bypass: When you genuinely need to run kubectl directly — typically a narrow diagnostic or break-glass operation that is not yet supported by a PodWarden API or MCP tool — open Apps → Admission Webhook and use the Temporary bypass panel to pause the gate for 60, 180, or 300 seconds. The bypass auto-resumes when the timer expires, and every operation performed while the bypass is active is still recorded as a category=admission severity=warning entry in the violation log. The maximum bypass duration is hard-capped at 300 seconds server-side; re-open the panel to renew if you need more time.

Break-glass procedure

If the webhook pods are completely down and you need to make an emergency change to a managed namespace:

kubectl delete validatingwebhookconfiguration podwarden-admission

This is an audited cluster-admin action and the explicit "break-the-seal" gesture. After the emergency, reinstall the webhook (or let PodWarden's reconcile cycle reinstall it automatically).

For the full operational runbook including diagnosis steps, see the GitLab wiki — Runbooks/Webhook Fail-Closed Break-Glass.

Helm Operator

Manages Helm chart deployments as first-class PodWarden workloads.

What it does:

• Watches HelmRelease CRDs created by PodWarden
• Installs, upgrades, and rolls back Helm charts in the cluster
• Reports release status and history back to PodWarden

Required for: deploying workloads from Helm charts via the PodWarden UI.

Install:

kubectl apply -f https://www.podwarden.com/operators/helm-operator/install.yaml

Or find it in the Hub catalog under System Apps.

Installing via Hub Catalog

1. Go to Hub in the PodWarden sidebar
2. Filter by category System Apps
3. Select the operator you want to install
4. Choose the target cluster
5. Click Deploy

PodWarden applies the operator manifest to the cluster and the detection label is registered automatically.

Verifying Installation

After installing, confirm the operator is running:

kubectl -n podwarden-system get pods

Check the ConfigMap that signals detection:

kubectl get configmaps -A -l podwarden.com/system-app=true

In the PodWarden UI, go to Settings → System to see detected system apps and their versions.