Skip to main content

Installation

Deploy the Watchlight AI Agent Runtime Governance control plane (Beacon) on any Kubernetes cluster using the watchlight-beacon Helm chart.

Prerequisites​

  • Kubernetes 1.27+
  • Helm 3.12+
  • kubectl configured with cluster access
  • GHCR access token (provided by Watchlight AI)
  • For wl-discover eBPF features: Linux nodes with kernel 5.8+ and BTF support

Create Namespace​

kubectl create namespace watchlight

Configure GHCR Image Pull Secret​

All Beacon images are hosted on ghcr.io/watchlight-ai-beacon. Create an image pull secret so your cluster can pull them:

kubectl create secret docker-registry ghcr-credentials \
  --namespace watchlight \
  --docker-server=ghcr.io \
  --docker-username=YOUR_GITHUB_USERNAME \
  --docker-password=YOUR_GHCR_TOKEN

Then reference it in your values:

global:
  imagePullSecrets:
    - name: ghcr-credentials

Download the Chart​

Download the Helm chart from the Watchlight docs site:

curl -fsSL https://docs.watchlight.ai/helm/watchlight-beacon.tar.gz -o watchlight-beacon.tar.gz
tar xzf watchlight-beacon.tar.gz

Or clone from the Beacon repository:

git clone https://github.com/watchlight-ai-beacon/watchlight-beacon.git
cd watchlight-beacon/deploy/helm

Install Tier 1 (Discovery and Registry)​

Tier 1 is the default configuration. It deploys wl-registry, wl-registry-frontend, wl-discover, and postgresql.

helm install beacon ./watchlight-beacon \
  --namespace watchlight \
  --set global.imagePullSecrets[0].name=ghcr-credentials

To use a cloud-specific values file:

helm install beacon ./watchlight-beacon \
  --namespace watchlight \
  -f ./watchlight-beacon/values-aws.yaml

Available cloud value files: values-aws.yaml, values-gcp.yaml, values-azure.yaml, values-minikube.yaml.

Install Tier 2 (Add Authorization)​

Enable wl-apdp and its frontend for Cedar-based policy authorization:

helm install beacon ./watchlight-beacon \
  --namespace watchlight \
  --set global.imagePullSecrets[0].name=ghcr-credentials \
  --set wl-apdp.enabled=true \
  --set wl-apdp-frontend.enabled=true

Install Tier 3 (Full Governance)​

Enable all services including the governance proxy and secrets broker:

helm install beacon ./watchlight-beacon \
  --namespace watchlight \
  --set global.imagePullSecrets[0].name=ghcr-credentials \
  --set wl-apdp.enabled=true \
  --set wl-apdp-frontend.enabled=true \
  --set wl-proxy.enabled=true \
  --set wl-secrets-broker.enabled=true

BYO Database​

To use an existing PostgreSQL instance (such as Amazon RDS, Cloud SQL, or Azure Database for PostgreSQL), disable the built-in database and provide a connection URL:

helm install beacon ./watchlight-beacon \
  --namespace watchlight \
  --set postgresql.enabled=false \
  --set global.externalDatabase.url="postgres://user:password@your-db-host:5432/beacon"

Alternatively, reference an existing Kubernetes Secret:

postgresql:
  enabled: false

wl-registry:
  database:
    urlSecret: "my-db-secret"  # Secret must contain a DATABASE_URL key

The database must be PostgreSQL 14 or later. The wl-registry service runs migrations automatically on startup.

Validate the Installation​

Check that all pods are running:

kubectl get pods -n watchlight

Verify health endpoints:

# Port-forward to the registry
kubectl port-forward -n watchlight svc/beacon-wl-registry 8080:8080

# Check health
curl http://localhost:8080/health

Expected response: 200 OK with service status.

For Tier 2+ deployments, also verify wl-apdp:

kubectl port-forward -n watchlight svc/beacon-wl-apdp 8081:8081
curl http://localhost:8081/health

Uninstall​

helm uninstall beacon --namespace watchlight

This removes all Beacon resources but preserves PersistentVolumeClaims by default. To also remove data volumes:

kubectl delete pvc -n watchlight -l app.kubernetes.io/instance=beacon

To remove the namespace entirely:

kubectl delete namespace watchlight