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}'
Install Helm: curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
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 Helm (Recommended)
Kubectl (Manifests)
Kind (Local Development)
Install from OCI Registry The simplest and recommended method for production deployments. # 1. Install kguardian from OCI registry helm install kguardian oci://ghcr.io/kguardian-dev/charts/kguardian \ --namespace kguardian \ --create-namespace \ --wait # 2. Verify installation kubectl get pods -n kguardian All three pods (controller, broker, UI) should be in Running state within 2-3 minutes.
Install Specific Version You can specify a particular version: helm install kguardian oci://ghcr.io/kguardian-dev/charts/kguardian \ --version 1.1.1 \ --namespace kguardian \ --create-namespace \ --wait Review Default Values To customize your installation, you can view and save the default values: # Pull and extract the chart to view values helm pull oci://ghcr.io/kguardian-dev/charts/kguardian --untar cat kguardian/values.yaml > my-values.yaml # Install with custom values helm install kguardian oci://ghcr.io/kguardian-dev/charts/kguardian \ --namespace kguardian \ --create-namespace \ --values my-values.yaml \ --wait 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 : # Number of replicas for HA replicas : 2 # PostgreSQL connection postgresql : host : "kguardian-postgresql" port : 5432 database : "kguardian" username : "kguardian" # Password from secret (created automatically) # Persistence persistence : enabled : true size : "10Gi" storageClass : "standard" # Resource limits resources : requests : cpu : "100m" memory : "256Mi" limits : cpu : "1000m" memory : "1Gi" # UI configuration ui : # Number of replicas replicas : 2 # Ingress (optional) ingress : enabled : true className : "nginx" hosts : - host : kguardian.example.com paths : - path : / pathType : Prefix tls : - secretName : kguardian-tls hosts : - kguardian.example.com # PostgreSQL configuration (uses bitnami/postgresql chart) postgresql : enabled : true auth : username : kguardian password : "change-me-in-production" database : kguardian primary : persistence : enabled : true size : 20Gi resources : requests : memory : "256Mi" cpu : "250m" Install with custom values:
helm install kguardian oci://ghcr.io/kguardian-dev/charts/kguardian \ --namespace kguardian \ --create-namespace \ --values values.yaml \ --wait Use External PostgreSQL For production, use a managed database:
# Disable built-in PostgreSQL postgresql : enabled : false # Configure broker to use external DB broker : postgresql : host : "my-postgres.rds.amazonaws.com" port : 5432 database : "kguardian_prod" username : "kguardian_user" existingSecret : "kguardian-db-secret" # Create this manually existingSecretPasswordKey : "password" Create the secret:
kubectl create secret generic kguardian-db-secret \ --namespace kguardian \ --from-literal=password= 'your-secure-password' Install the CLI Plugin After deploying the controller, install the CLI to generate policies.
# One-line installer sh -c "$( curl -fsSL https://raw.githubusercontent.com/kguardian-dev/kguardian/main/scripts/quick-install.sh)" # Verify kubectl kguardian --version This script:
Detects your OS and architecture
Downloads the latest CLI release
Installs to /usr/local/bin/kubectl-kguardian
Validates the installation
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-postgresql-0 1/1 Running 0 5m # kguardian-ui-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 latest or specific version (preserves your values.yaml) helm upgrade kguardian oci://ghcr.io/kguardian-dev/charts/kguardian \ --namespace kguardian \ --values values.yaml \ --wait # Or upgrade to a specific version helm upgrade kguardian oci://ghcr.io/kguardian-dev/charts/kguardian \ --version 1.2.0 \ --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 (if using Krew) kubectl krew uninstall kguardian # Or remove manual installation 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.
