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

# Quickstart Guide

> Get kguardian up and running in your Kubernetes cluster in 5 minutes

This guide will help you install kguardian and generate your first security policy.

## Prerequisites

Before you begin, ensure you have:

<AccordionGroup>
  <Accordion icon="kubernetes" title="Kubernetes Cluster">
    * Kubernetes v1.19 or later
    * Linux nodes with kernel 6.2+ (for eBPF support)
    * `kubectl` configured and connected to your cluster
  </Accordion>

  <Accordion icon="helm" title="Helm (Recommended)">
    * Helm v3.0 or later
    * Or use raw manifests if you prefer
  </Accordion>

  <Accordion icon="circle-check" title="Cluster Permissions">
    * Admin access to install the controller (DaemonSet, RBAC, etc.)
    * Permission to create resources in your target namespaces
  </Accordion>

  <Accordion icon="shield-halved" title="Pod Security Admission (if enforced)">
    The kguardian controller needs the `privileged` Pod Security Admission level because it loads eBPF programs. If your cluster enforces [Pod Security Admission](https://kubernetes.io/docs/concepts/security/pod-security-admission/), label the install namespace before running `helm install`:

    ```bash theme={null}
    kubectl create namespace kguardian
    kubectl label namespace kguardian pod-security.kubernetes.io/enforce=privileged --overwrite
    ```

    If you skip this on a PSA-enforced cluster, the controller pods will fail to admit with a `violates PodSecurity "restricted:..."` error.
  </Accordion>
</AccordionGroup>

<Warning>
  **Kernel Version Check:** kguardian requires Linux kernel 6.2+ for eBPF functionality. Run `uname -r` on your nodes to verify.
</Warning>

## Step 1: Install the Controller

The Controller runs as a DaemonSet and uses eBPF to observe your workloads.

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

For specific versions, custom Helm values, Kind-based local development, and external PostgreSQL setups, see the [Installation Guide](/installation) — that page is the canonical install reference.

### Verify Installation

Check that all components are running:

```bash theme={null}
kubectl get pods -n kguardian

# Expected output (one controller pod per node; broker + db + frontend
# as Deployments; evaluator / mcp-server / llm-bridge appear only when
# the corresponding chart values enable them):
# NAME                                   READY   STATUS    RESTARTS   AGE
# kguardian-controller-xxxxx             1/1     Running   0          2m
# kguardian-broker-xxxxxxxxxx-xxxxx      1/1     Running   0          2m
# kguardian-db-xxxxxxxxxx-xxxxx          1/1     Running   0          2m
# kguardian-frontend-xxxxxxxxxx-xxxxx    1/1     Running   0          2m
```

<Check>
  All pods should show `Running` status. If not, see [Troubleshooting](/advanced/troubleshooting).
</Check>

## Step 2: Install the CLI Plugin

The kguardian CLI is a kubectl plugin for generating policies.

<Tabs>
  <Tab title="Quick Install Script (Recommended)">
    ```bash theme={null}
    # Download and install the latest release
    sh -c "$(curl -fsSL https://raw.githubusercontent.com/kguardian-dev/kguardian/main/scripts/quick-install.sh)"

    # Verify installation
    kubectl kguardian --version
    ```
  </Tab>

  <Tab title="Manual Download">
    ```bash theme={null}
    # Download the binary for your platform
    # Replace {VERSION}, {OS}, and {ARCH} with appropriate values
    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}"

    # Make it executable and move to PATH
    chmod +x kguardian-${OS}-${ARCH}
    sudo mv kguardian-${OS}-${ARCH} /usr/local/bin/kubectl-kguardian

    # Verify installation
    kubectl kguardian --version
    ```
  </Tab>
</Tabs>

## Step 3: Let Your Workloads Run

kguardian learns from actual runtime behavior, so let your applications run normally for **5-15 minutes** to collect meaningful data.

<Steps>
  <Step title="Deploy Test Workload (Optional)">
    If you don't have existing workloads, deploy a small test app:

    ```bash theme={null}
    kubectl create deployment nginx --image=nginx:latest
    kubectl expose deployment nginx --port=80
    kubectl run curl-pod --image=curlimages/curl --command -- sleep 3600

    # Generate some traffic
    kubectl exec curl-pod -- curl nginx
    ```
  </Step>

  <Step title="Monitor Data Collection">
    Check that the broker is receiving data:

    ```bash theme={null}
    # Port-forward to the broker
    kubectl port-forward -n kguardian svc/kguardian-broker 9090:9090 &

    # Check for traffic data (replace 'nginx' with your pod name)
    curl http://localhost:9090/pod/traffic/name/default/nginx
    ```

    <Tip>
      The longer you let workloads run, the more traffic and syscall variety the controller will capture, and the closer the generated policy will be to your real runtime profile.
    </Tip>
  </Step>
</Steps>

## Step 4: Generate Your First Network Policy

Now generate a network policy based on observed traffic. `--dry-run=true` is the **default** — the CLI writes YAML to `--output-dir` and does **not** apply anything to the cluster:

```bash theme={null}
# Generate policy for a specific pod (dry-run is on by default)
kubectl kguardian gen networkpolicy nginx -n default \
  --output-dir ./policies

# View the generated policy
cat ./policies/default-nginx-networkpolicy.yaml
```

To apply directly during generation instead of writing files for review, pass `--dry-run=false`. See [`gen networkpolicy`](/cli/gen-networkpolicy) for the full flag reference.

<CodeGroup>
  ```yaml Example Output theme={null}
  apiVersion: networking.k8s.io/v1
  kind: NetworkPolicy
  metadata:
    name: nginx
    namespace: default
    labels:
      kguardian.dev/managed-by: kguardian
      kguardian.dev/version: v1.0.0
  spec:
    podSelector:
      matchLabels:
        app: nginx
    policyTypes:
      - Ingress
      - Egress
    ingress:
      - from:
          - podSelector:
              matchLabels:
                run: curl-pod
            namespaceSelector:
              matchLabels:
                kubernetes.io/metadata.name: default
        ports:
          - protocol: TCP
            port: 80
    egress:
      - to:
          - namespaceSelector:
              matchLabels:
                kubernetes.io/metadata.name: kube-system
            podSelector:
              matchLabels:
                k8s-app: kube-dns
        ports:
          - protocol: UDP
            port: 53
  ```
</CodeGroup>

<Check>
  **Success!** kguardian automatically discovered that your nginx pod receives traffic from the curl-pod on port 80 and makes DNS queries.
</Check>

### Apply the Policy

The default `--dry-run=true` only writes the YAML file. To put the policy on the cluster, either re-run the CLI with `--dry-run=false`, or `kubectl apply` the saved file:

```bash theme={null}
# Option A: let the CLI apply directly
kubectl kguardian gen networkpolicy nginx -n default \
  --output-dir ./policies --dry-run=false

# Option B: apply the saved YAML yourself
kubectl apply --dry-run=client -f ./policies/default-nginx-networkpolicy.yaml  # validate
kubectl apply -f ./policies/default-nginx-networkpolicy.yaml                   # apply

# Verify it's created
kubectl get networkpolicies -n default
```

## Step 5: Generate a Seccomp Profile

Generate a seccomp profile to restrict syscalls:

```bash theme={null}
# Generate seccomp profile for nginx
kubectl kguardian gen seccomp nginx -n default \
  --output-dir ./seccomp

# View the generated profile
cat ./seccomp/default-nginx-seccomp.json
```

<CodeGroup>
  ```json Example Seccomp Profile theme={null}
  {
    "defaultAction": "SCMP_ACT_ERRNO",
    "architectures": ["SCMP_ARCH_X86_64"],
    "syscalls": [
      {
        "names": ["read", "write", "open", "close", "stat"],
        "action": "SCMP_ACT_ALLOW"
      },
      {
        "names": ["socket", "connect", "accept", "bind", "listen"],
        "action": "SCMP_ACT_ALLOW"
      },
      {
        "names": ["mmap", "munmap", "brk", "mprotect"],
        "action": "SCMP_ACT_ALLOW"
      }
    ]
  }
  ```
</CodeGroup>

### Apply the Seccomp Profile

kguardian generates the profile JSON. **Distributing the profile to each node's `/var/lib/kubelet/seccomp/` directory is the user's responsibility** — kguardian does not push profiles to nodes today.

Recommended distribution options:

* **[Security Profiles Operator (SPO)](https://github.com/kubernetes-sigs/security-profiles-operator)** — Wrap the generated JSON in a `SeccompProfile` CRD; SPO's DaemonSet writes it to the kubelet seccomp directory on every node. See the SPO docs for the CRD schema and DaemonSet behavior.
* **A custom hostPath DaemonSet** — Mount `/var/lib/kubelet/seccomp/` and copy the profile in. Suitable if you do not want a separate operator.
* **Image-baked profiles** — Bake the profile into a config map or container image and ship it with your existing deployment pipeline.

Once the profile file lives at `/var/lib/kubelet/seccomp/nginx-profile.json` on every node that may run the pod, reference it from your workload:

```yaml theme={null}
apiVersion: v1
kind: Pod
metadata:
  name: nginx
spec:
  securityContext:
    seccompProfile:
      type: Localhost
      localhostProfile: nginx-profile.json
  containers:
  - name: nginx
    image: nginx:latest
```

<Info>
  Automated seccomp profile distribution from kguardian is on the roadmap. Until then, pair kguardian with SPO or a DaemonSet of your own.
</Info>

## Next Steps

<CardGroup cols={2}>
  <Card title="Architecture" icon="sitemap" href="/architecture">
    See how the Controller, Broker, and UI fit together
  </Card>

  <Card title="Generate Cilium Policies" icon="network-wired" href="/guides/generating-network-policies">
    Create enhanced L7-aware policies
  </Card>

  <Card title="Batch Generation" icon="layer-group" href="/cli/gen-networkpolicy">
    Generate policies for all pods at once
  </Card>

  <Card title="Policy Gallery" icon="images" href="/policy-gallery">
    Worked examples for nginx, Postgres, kube-dns, Prometheus, Istio, Go
  </Card>
</CardGroup>

## Common Issues

<AccordionGroup>
  <Accordion icon="triangle-exclamation" title="No traffic data found">
    **Solution:** Ensure your pods have been running and generating traffic for at least 5 minutes. Check broker logs:

    ```bash theme={null}
    kubectl logs -n kguardian deployment/kguardian-broker
    ```
  </Accordion>

  <Accordion icon="triangle-exclamation" title="Controller pods not starting">
    **Solution:** Verify kernel version (6.2+) and that nodes support eBPF:

    ```bash theme={null}
    kubectl describe pod -n kguardian kguardian-controller-xxxxx
    ```
  </Accordion>

  <Accordion icon="triangle-exclamation" title="CLI can't connect to broker">
    **Solution:** The CLI auto-discovers the broker via port-forwarding. Ensure you have permissions:

    ```bash theme={null}
    kubectl auth can-i create pods/portforward -n kguardian
    ```
  </Accordion>
</AccordionGroup>

For more troubleshooting, see the [Troubleshooting Guide](/advanced/troubleshooting).

***

<Card title="Learn more about kguardian's architecture" icon="sitemap" href="/architecture" horizontal>
  Understand how the components work together →
</Card>