Installation Guide

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

Prerequisites

Before installing kguardian, verify your environment meets these requirements:

Kubernetes Cluster

Required:

Kubernetes version: 1.19+
Node OS: Linux
Kernel version: 6.2+ (for eBPF support)
Container runtime: containerd (required — Docker and CRI-O are not supported)

Verify kernel version:

kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.nodeInfo.kernelVersion}{"\n"}{end}'

Helm (Recommended)

Helm 3.0+

Install Helm:

curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

kubectl Access

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)
Kind (Local Development)

Install from OCI Registry

The simplest and recommended method for production deployments.

# 1. Install kguardian from OCI registry (latest chart version)
helm install kguardian oci://ghcr.io/kguardian-dev/charts/kguardian \
  --namespace kguardian \
  --create-namespace \
  --wait

# 2. Verify installation
kubectl get pods -n kguardian

All pods — controller (one per node), broker, db, frontend, and evaluator — should be in Running state within 2-3 minutes.

Install Specific Version

You can pin a particular chart version:

helm install kguardian oci://ghcr.io/kguardian-dev/charts/kguardian \
  --version 1.14.0 \
  --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

Install in Kind Cluster

Perfect for local testing and development.

# 1. Install Task (build tool)
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b /usr/local/bin

# 2. Clone the repository
git clone https://github.com/kguardian-dev/kguardian.git
cd kguardian

# 3. Create a fresh Kind cluster
task kind

# 4. Build images, load them into Kind, and install via Helm
task install:oci

task install:oci rebuilds the controller and broker images, loads them into Kind, and runs a production-style Helm install with the local image tags.

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

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

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

# Frontend (UI)
frontend:
  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.

Quick Install Script (Recommended)
Manual Download
From Source

# 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

# 1. Download binary from GitHub Releases
# CLI releases are tagged advisor/vX.Y.Z; assets are named advisor-<os>-<arch>
VERSION="advisor/v1.6.1"
OS="linux"  # or darwin, windows
ARCH="amd64"  # or arm64

curl -LO "https://github.com/kguardian-dev/kguardian/releases/download/${VERSION}/advisor-${OS}-${ARCH}"

# 2. Verify build provenance (optional but recommended, requires the gh CLI)
gh attestation verify advisor-${OS}-${ARCH} --repo kguardian-dev/kguardian

# 3. Install
chmod +x advisor-${OS}-${ARCH}
sudo mv advisor-${OS}-${ARCH} /usr/local/bin/kubectl-kguardian

# 4. Verify
kubectl kguardian --version

# 1. Clone repository
git clone https://github.com/kguardian-dev/kguardian.git
cd kguardian/advisor

# 2. Build binary
go build -o kubectl-kguardian .

# 3. Install
sudo mv kubectl-kguardian /usr/local/bin/

# 4. Verify
kubectl kguardian --version

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-evaluator-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:
# - "Network probe eBPF program loaded and attached"
# - "Syscall probe eBPF program loaded and attached"
# - "Ignoring namespaces: [...]"
# - 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: Healthy!
# A 503 with body "Database unavailable" or "Database schema not up to date"
# means the broker is up but cannot serve requests yet.

4. Test CLI Connection

# Print the command help (the CLI port-forwards to the broker automatically)
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.14.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
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

Getting Started

Core Concepts

User Guides

Policy Gallery

CLI Reference

Advanced

Roadmap

Installation Guide

Prerequisites

Installation Methods

Install from OCI Registry

Install Specific Version

Review Default Values

Install in Kind Cluster

Configuration Options

Common Helm Values

Use External PostgreSQL

Install the CLI Plugin

Verification

1. Check Pod Status

2. Check Controller Logs

3. Check Broker Connectivity

4. Test CLI Connection

Upgrade

Uninstall

Quick Start

Configuration Guide

Troubleshooting

Architecture

​Prerequisites

​Installation Methods

​Install from OCI Registry

​Install Specific Version

​Review Default Values

​Install in Kind Cluster

​Configuration Options

​Common Helm Values

​Use External PostgreSQL

​Install the CLI Plugin

​Verification

​1. Check Pod Status

​2. Check Controller Logs

​3. Check Broker Connectivity

​4. Test CLI Connection

​Upgrade

​Uninstall

Quick Start

Configuration Guide

Troubleshooting

Architecture

Prerequisites

Installation Methods

Install from OCI Registry

Install Specific Version

Review Default Values

Install in Kind Cluster

Configuration Options

Common Helm Values

Use External PostgreSQL

Install the CLI Plugin

Verification

1. Check Pod Status

2. Check Controller Logs

3. Check Broker Connectivity

4. Test CLI Connection

Upgrade

Uninstall