> ## 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.

# Installation Guide

> Comprehensive installation instructions for all kguardian components

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

## Prerequisites

Before installing kguardian, verify your environment meets these requirements:

<AccordionGroup>
  <Accordion icon="server" title="Kubernetes Cluster">
    **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:**

    ```bash theme={null}
    kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.nodeInfo.kernelVersion}{"\n"}{end}'
    ```
  </Accordion>

  <Accordion icon="helm" title="Helm (Recommended)">
    * Helm **3.0+**

    **Install Helm:**

    ```bash theme={null}
    curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
    ```
  </Accordion>

  <Accordion icon="terminal" title="kubectl Access">
    * `kubectl` **1.19+** configured with admin privileges

    **Verify access:**

    ```bash theme={null}
    kubectl auth can-i create daemonsets --all-namespaces
    kubectl auth can-i create clusterroles
    ```
  </Accordion>
</AccordionGroup>

<Warning>
  **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.
</Warning>

***

## Installation Methods

<Tabs>
  <Tab title="Helm (Recommended)">
    ### Install from OCI Registry

    The simplest and recommended method for production deployments.

    ```bash theme={null}
    # 1. Install kguardian from OCI registry
    helm install kguardian oci://ghcr.io/kguardian-dev/charts/kguardian \
      --version 1.9.1 \
      --namespace kguardian \
      --create-namespace \
      --wait

    # 2. Verify installation
    kubectl get pods -n kguardian
    ```

    <Check>
      All three pods (controller, broker, UI) should be in `Running` state within 2-3 minutes.
    </Check>

    ### Install Specific Version

    You can specify a particular version:

    ```bash theme={null}
    helm install kguardian oci://ghcr.io/kguardian-dev/charts/kguardian \
      --version 1.9.1 \
      --namespace kguardian \
      --create-namespace \
      --wait
    ```

    ### Review Default Values

    To customize your installation, you can view and save the default values:

    ```bash theme={null}
    # Pull and extract the chart to view values
    helm pull oci://ghcr.io/kguardian-dev/charts/kguardian --version 1.9.1 --untar
    cat kguardian/values.yaml > my-values.yaml

    # Install with custom values
    helm install kguardian oci://ghcr.io/kguardian-dev/charts/kguardian \
      --version 1.9.1 \
      --namespace kguardian \
      --create-namespace \
      --values my-values.yaml \
      --wait
    ```
  </Tab>

  <Tab title="Kind (Local Development)">
    ### Install in Kind Cluster

    Perfect for local testing and development.

    ```bash theme={null}
    # 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 Kind cluster and install everything
    task install

    # This will:
    # - Create a Kind cluster with appropriate settings
    # - Build controller and broker images
    # - Load images into Kind
    # - Install via Helm with local tags
    ```

    <Tip>
      The `task install` command is perfect for development. It rebuilds images and reloads them automatically.
    </Tip>
  </Tab>
</Tabs>

***

## Configuration Options

### Common Helm Values

Customize your installation by creating a `values.yaml` file:

```yaml theme={null}
# 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:

```bash theme={null}
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`](https://github.com/kguardian-dev/kguardian/blob/main/charts/kguardian/values.yaml) or the auto-generated [chart README](https://github.com/kguardian-dev/kguardian/blob/main/charts/kguardian/README.md).

### 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:

```yaml theme={null}
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:

```bash theme={null}
kubectl create namespace kguardian
kubectl create secret generic kguardian-db-secret \
  --namespace kguardian \
  --from-literal=password='your-secure-password'
```

Then install:

```bash theme={null}
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.

<Tabs>
  <Tab title="Quick Install Script (Recommended)">
    ```bash theme={null}
    # 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
  </Tab>

  <Tab title="Manual Download">
    ```bash theme={null}
    # 1. Download binary from GitHub Releases
    VERSION="v1.0.0"
    OS="linux"  # or darwin, windows
    ARCH="amd64"  # or arm64

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

    # 2. Verify checksum (optional but recommended)
    curl -LO "https://github.com/kguardian-dev/kguardian/releases/download/${VERSION}/checksums.txt"
    sha256sum --check --ignore-missing checksums.txt

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

    # 4. Verify
    kubectl kguardian --version
    ```
  </Tab>

  <Tab title="From Source">
    ```bash theme={null}
    # 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
    ```
  </Tab>
</Tabs>

***

## Verification

After installation, verify all components are working:

### 1. Check Pod Status

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
# 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
```

<Check>
  If all checks pass, kguardian is ready to use!
</Check>

***

## Upgrade

To upgrade kguardian to a newer version:

```bash theme={null}
# 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}'
```

<Warning>
  Always review the [Release Notes](https://github.com/kguardian-dev/kguardian/releases) before upgrading, especially for breaking changes in major versions.
</Warning>

***

## Uninstall

To completely remove kguardian:

```bash theme={null}
# 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
```

<Info>
  This will **not** remove generated policies that were already applied to your namespaces. Clean those up separately if needed.
</Info>

***

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Jump right into generating policies
  </Card>

  <Card title="Configuration Guide" icon="sliders" href="/advanced/custom-configurations">
    Deep dive into configuration options
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/advanced/troubleshooting">
    Fix common installation issues
  </Card>

  <Card title="Architecture" icon="sitemap" href="/architecture">
    Understand how components work
  </Card>
</CardGroup>