Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kguardian.dev/llms.txt

Use this file to discover all available pages before exploring further.

This guide covers all installation methods for kguardian, from quick setups to production deployments.

​
Prerequisites

Before installing kguardian, verify your environment meets these requirements:
Required:
  • Kubernetes version: 1.19+
  • Node OS: Linux
  • Kernel version: 6.2+ (for eBPF support)
  • Container runtime: containerd (Docker/CRI-O supported with limitations)
Verify kernel version:
kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.nodeInfo.kernelVersion}{"\n"}{end}'
  • kubectl 1.19+ configured with admin privileges
Verify access:
kubectl auth can-i create daemonsets --all-namespaces
kubectl auth can-i create clusterroles
Kernel Compatibility: kguardian requires Linux kernel 6.2+ for eBPF CO-RE (Compile Once, Run Everywhere) support. Older kernels may work with manual BPF program compilation but are not officially supported.

​
Installation Methods

​
Configuration Options

​
Common Helm Values

Customize your installation by creating a values.yaml file: 
# Controller configuration
controller:
  # Resource limits
  resources:
    requests:
      cpu: "100m"
      memory: "128Mi"
    limits:
      cpu: "500m"
      memory: "512Mi"

  # Exclude namespaces from monitoring
  excludedNamespaces: "kube-system,kguardian,monitoring,istio-system"

  # Enable debug logging
  debug: true

  # Image configuration
  image:
    repository: ghcr.io/kguardian-dev/controller
    tag: "1.0.0"
    pullPolicy: IfNotPresent

# Broker configuration
broker:
  replicaCount: 1
  resources:
    requests:
      cpu: "100m"
      memory: "256Mi"
    limits:
      memory: "1Gi"

# Frontend (UI) — gated by `frontend.enabled`
frontend:
  enabled: true
  replicaCount: 1

# Bundled PostgreSQL — see "Use External PostgreSQL" below to disable.
database:
  enabled: true
  user: rust
  databaseName: kube
  image:
    tag: "18-alpine"
  persistence:
    enabled: true
    # Auto-provisioned PVC sizing (only used when existingClaim is unset)
    size: "10Gi"
    # Empty string => use the cluster's default StorageClass.
    storageClassName: ""
    # Or BYO PVC:
    # existingClaim: "my-pg-pvc"
Install with custom values: 
helm install kguardian oci://ghcr.io/kguardian-dev/charts/kguardian \
  --namespace kguardian \
  --create-namespace \
  --values values.yaml \
  --wait
For the full list of values, see charts/kguardian/values.yaml or the auto-generated chart README.

​
Use External PostgreSQL

For production-grade deployments — managed services like AWS RDS / Cloud SQL / a CloudNativePG cluster you already run — disable the bundled Postgres and point the broker at the external instance: 
database:
  # Disable the bundled in-cluster Postgres deployment, PVC, secret, and SA.
  enabled: false

  # Role + database the broker will connect as. Must already exist on the
  # external instance.
  user: kguardian
  databaseName: kguardian_prod

  # The chart will not create a credentials secret when external — supply
  # your own and reference it here.
  existingSecret: kguardian-db-secret
  passwordSecretKey: password

  external:
    # FQDN or hostname of the external Postgres. Can be in any namespace
    # (or outside the cluster) — the broker resolves it via DNS.
    host: postgres.databases.svc.cluster.local
    port: 5432
    # libpq sslmode. Cloud-managed Postgres typically requires "require".
    sslMode: prefer
Create the secret in the kguardian namespace before installing: 
kubectl create namespace kguardian
kubectl create secret generic kguardian-db-secret \
  --namespace kguardian \
  --from-literal=password='your-secure-password'
Then install: 
helm install kguardian oci://ghcr.io/kguardian-dev/charts/kguardian \
  --namespace kguardian \
  --values values.yaml --wait

​
Install the CLI Plugin

After deploying the controller, install the CLI to generate policies.

​
Verification

After installation, verify all components are working:

​
1. Check Pod Status

kubectl get pods -n kguardian

# Expected output:
# NAME                                  READY   STATUS    RESTARTS   AGE
# kguardian-controller-xxxxx            1/1     Running   0          5m
# kguardian-broker-xxxxxxxxxx-xxxxx     1/1     Running   0          5m
# kguardian-db-xxxxxxxxxx-xxxxx         1/1     Running   0          5m
# kguardian-frontend-xxxxxxxxxx-xxxxx   1/1     Running   0          5m

​
2. Check Controller Logs

kubectl logs -n kguardian daemonset/kguardian-controller --tail=50

# Look for:
# - "eBPF programs loaded successfully"
# - "Watching pods on node: <node-name>"
# - No error messages

​
3. Check Broker Connectivity

# Port-forward to broker
kubectl port-forward -n kguardian svc/kguardian-broker 9090:9090 &

# Test health endpoint
curl http://localhost:9090/health

# Expected: {"status":"ok"}

​
4. Test CLI Connection

# List some pods (controller auto-forwards to broker)
kubectl kguardian gen networkpolicy --help

# Try generating a policy for a test pod
kubectl run test-nginx --image=nginx
sleep 30  # Let controller observe it
kubectl kguardian gen networkpolicy test-nginx -n default --dry-run
If all checks pass, kguardian is ready to use!

​
Upgrade

To upgrade kguardian to a newer version: 
# 1. Check available versions (optional)
# You can view releases at https://github.com/kguardian-dev/kguardian/releases

# 2. Upgrade to a specific pinned version (preserves your values.yaml)
helm upgrade kguardian oci://ghcr.io/kguardian-dev/charts/kguardian \
  --version 1.9.1 \
  --namespace kguardian \
  --values values.yaml \
  --wait

# 3. Verify new version
kubectl get pods -n kguardian -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[0].image}{"\n"}{end}'
Always review the Release Notes before upgrading, especially for breaking changes in major versions.

​
Uninstall

To completely remove kguardian: 
# 1. Uninstall Helm release
helm uninstall kguardian --namespace kguardian

# 2. Delete namespace (removes all resources)
kubectl delete namespace kguardian

# 3. Remove CLI plugin
sudo rm /usr/local/bin/kubectl-kguardian
This will not remove generated policies that were already applied to your namespaces. Clean those up separately if needed.

Quick Start

Jump right into generating policies

Configuration Guide

Deep dive into configuration options

Troubleshooting

Fix common installation issues

Architecture

Understand how components work