Installation

Table of contents

1. Helm Installation
   1. Add the Helm Repository
   2. Install with Default Settings
   3. Verify Installation
2. Configuration
   1. Minimal Production Configuration
   2. Enable Slack Notifications
   3. Enable MCP Server for AI Agents
   4. Enable Hubble Integration (Cilium)
3. CLI Installation
   1. Download Binary
   2. Using Go
   3. From Source
   4. kubectl Plugin (Alternative)
4. RBAC Details
   1. Controller ClusterRole
   2. Webhook ClusterRole
5. High Availability
   1. Controller HA
   2. Webhook HA
   3. Pod Disruption Budgets
6. Certificate Management
   1. Self-Signed (Default)
   2. cert-manager
7. Uninstallation
8. Troubleshooting
   1. Controller Not Starting
   2. No Constraints Discovered
   3. Webhook Not Receiving Events

---

Helm Installation

Add the Helm Repository

helm repo add potoo https://potoo.io/charts
helm repo update

Install with Default Settings

helm install potoo potoo/potoo \
  -n potoo-system \
  --create-namespace

Alternatively, install directly from the OCI registry (Helm 3.8+):

helm install potoo oci://ghcr.io/potooio/charts/potoo \
  -n potoo-system \
  --create-namespace

This installs:

• Controller with 2 replicas (leader election enabled)
• Admission webhook with 2 replicas
• RBAC with cluster-wide read access
• ServiceAccount with necessary permissions

Verify Installation

# Check pods are running
kubectl get pods -n potoo-system

# Check CRDs are installed
kubectl get crd | grep potoo

# View controller logs
kubectl logs -n potoo-system -l app=potoo-controller

Expected CRDs:

constraintreports.potoo.io
constraintprofiles.potoo.io
notificationpolicies.potoo.io

---

Configuration

Minimal Production Configuration

# values.yaml
controller:
  replicas: 2
  leaderElect: true
  resources:
    requests:
      cpu: 100m
      memory: 256Mi
    limits:
      cpu: 500m
      memory: 512Mi

admissionWebhook:
  enabled: true
  replicas: 2
  failurePolicy: Ignore  # MUST be Ignore for safety

notifications:
  kubernetesEvents: true
  constraintReports: true

privacy:
  defaultDeveloperDetailLevel: summary
  remediationContact: "[email protected]"

Install with custom values:

helm install potoo potoo/potoo \
  -n potoo-system \
  --create-namespace \
  -f values.yaml

Enable Slack Notifications

notifications:
  slack:
    enabled: true
    webhookUrl: "https://hooks.slack.com/services/XXX/YYY/ZZZ"
    minSeverity: Critical  # Only Critical alerts

Enable MCP Server for AI Agents

mcp:
  enabled: true
  port: 8090
  transport: sse
  authentication:
    method: kubernetes-sa

Enable Hubble Integration (Cilium)

hubble:
  enabled: true
  relayAddress: hubble-relay.kube-system.svc:4245

---

CLI Installation

Download Binary

Pre-built binaries are available from GitHub Releases.

Linux (amd64):

curl -sL https://github.com/potooio/potoo/releases/latest/download/potooctl-linux-amd64 -o potoo
chmod +x potoo
sudo mv potoo /usr/local/bin/

Linux (arm64):

curl -sL https://github.com/potooio/potoo/releases/latest/download/potooctl-linux-arm64 -o potoo
chmod +x potoo
sudo mv potoo /usr/local/bin/

macOS (Apple Silicon):

curl -sL https://github.com/potooio/potoo/releases/latest/download/potooctl-darwin-arm64 -o potoo
chmod +x potoo
sudo mv potoo /usr/local/bin/

macOS (Intel):

curl -sL https://github.com/potooio/potoo/releases/latest/download/potooctl-darwin-amd64 -o potoo
chmod +x potoo
sudo mv potoo /usr/local/bin/

Windows (amd64):

Invoke-WebRequest -Uri https://github.com/potooio/potoo/releases/latest/download/potooctl-windows-amd64.exe -OutFile potoo.exe
Move-Item potoo.exe C:\Windows\System32\

Verify checksum (optional, replace platform suffix as needed):

curl -sL https://github.com/potooio/potoo/releases/latest/download/potooctl-linux-amd64.sha256 -o potoo.sha256
sha256sum -c potoo.sha256

Using Go

Requires Go 1.21+.

go install github.com/potooio/potoo/cmd/potooctl@latest

The binary is named potoo. Verify installation:

potoo version
potoo --help

From Source

git clone https://github.com/potooio/potoo.git
cd potoo
make build
mv bin/potoo /usr/local/bin/

kubectl Plugin (Alternative)

The CLI can also be invoked as a kubectl plugin:

# Download binary (Linux amd64)
curl -sL https://github.com/potooio/potoo/releases/latest/download/potoo-sentinel-linux-amd64 -o kubectl-sentinel
chmod +x kubectl-sentinel
sudo mv kubectl-sentinel /usr/local/bin/

# Or via Go (requires Go 1.21+)
# go install github.com/potooio/potoo/cmd/kubectl-sentinel@latest

# Use
kubectl sentinel query -n my-namespace
kubectl sentinel explain -n my-namespace "connection refused"

---

RBAC Details

Controller ClusterRole

The controller requires broad read access:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: potoo-controller
rules:
  # Read all resources to discover policies
  - apiGroups: ["*"]
    resources: ["*"]
    verbs: ["get", "list", "watch"]

  # Write Potoo CRDs
  - apiGroups: ["potoo.io"]
    resources: ["constraintreports", "constraintreports/status"]
    verbs: ["create", "update", "patch", "delete"]

  # Create Events on workloads
  - apiGroups: [""]
    resources: ["events"]
    verbs: ["create", "patch"]

Webhook ClusterRole

The admission webhook has minimal permissions:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: potoo-webhook
rules:
  # Read Potoo CRDs for constraint lookup
  - apiGroups: ["potoo.io"]
    resources: ["constraintreports"]
    verbs: ["get", "list"]

---

High Availability

Controller HA

With controller.replicas: 2 and controller.leaderElect: true, one controller is active while the other is standby. Failover is automatic.

Webhook HA

With admissionWebhook.replicas: 2 and admissionWebhook.pdb.enabled: true, the webhook maintains availability during rolling updates.

Pod Disruption Budgets

admissionWebhook:
  pdb:
    enabled: true
    minAvailable: 1

---

Certificate Management

The admission webhook requires TLS certificates.

Self-Signed (Default)

admissionWebhook:
  certManagement: self-signed

Potoo generates certificates automatically and rotates them before expiry.

cert-manager

admissionWebhook:
  certManagement: cert-manager

Requires cert-manager installed in the cluster. Potoo creates a Certificate resource.

---

Uninstallation

# Remove Helm release
helm uninstall potoo -n potoo-system

# Remove CRDs (optional - deletes all ConstraintReports)
kubectl delete crd constraintreports.potoo.io
kubectl delete crd constraintprofiles.potoo.io
kubectl delete crd notificationpolicies.potoo.io

# Remove namespace
kubectl delete namespace potoo-system

---

Troubleshooting

Controller Not Starting

Check logs:

kubectl logs -n potoo-system -l app=potoo-controller

Common issues:

• RBAC errors: Ensure ClusterRole and ClusterRoleBinding are created
• CRD not found: Run helm install again or check Helm hooks

No Constraints Discovered

1. Verify adapters are enabled:

   kubectl get constraintprofiles
   

2. Check controller logs for adapter errors:

   kubectl logs -n potoo-system -l app=potoo-controller | grep adapter
   

3. Verify policy CRDs exist:

   kubectl get crd | grep -E 'networkpolic|gatekeeper|kyverno'
   

Webhook Not Receiving Events

1. Check webhook registration:

   kubectl get validatingwebhookconfiguration potoo-webhook
   

2. Verify failurePolicy is Ignore:

   kubectl get validatingwebhookconfiguration potoo-webhook -o yaml | grep failurePolicy
   

3. Check webhook pod logs:

   kubectl logs -n potoo-system -l app=potoo-webhook