Helm Chart Installation

Deploy Cerbos to Kubernetes using the official Helm chart

The official Cerbos Helm chart provides a production-ready way to deploy Cerbos to Kubernetes clusters. The chart supports multiple deployment patterns and integrates with Kubernetes-native features.

Prerequisites

• Kubernetes 1.23.0 or later
• Helm 3.0 or later
• kubectl configured to access your cluster

Add Helm Repository

1. Add the Cerbos Helm repository

   helm repo add cerbos https://download.cerbos.dev/helm-charts
   
2. Update repository cache

   helm repo update
   
3. Verify repository

   helm search repo cerbos
   

Quick Start Installation

Install Cerbos with default settings:

helm install cerbos cerbos/cerbos --version=0.52.0

This creates a deployment with:

• 1 replica
• HTTP service on port 3592
• gRPC service on port 3593
• Default policy storage configuration

OCI Registry Installation

The chart is also available from an OCI registry:

helm install cerbos oci://ghcr.io/cerbos/helm-charts/cerbos --version=0.52.0

Configuration Options

View all available configuration values:

helm show values cerbos/cerbos --version=0.52.0

Key Configuration Values

Parameter	Description	Default
replicaCount	Number of Cerbos pods	1
image.repository	Container image repository	ghcr.io/cerbos/cerbos
image.tag	Image tag (defaults to chart appVersion)	""
image.pullPolicy	Image pull policy	IfNotPresent
service.type	Kubernetes service type	ClusterIP
service.httpPort	HTTP service port	3592
service.grpcPort	gRPC service port	3593
cerbos.logLevel	Log level (DEBUG, INFO, WARN, ERROR)	INFO
cerbos.config	Cerbos configuration object	{}
type	Workload type (deployment or daemonset)	deployment

TLS Configuration

Secure Cerbos endpoints with TLS certificates.

Using Existing TLS Secret

1. Create TLS secret

   Create a Kubernetes secret with your certificates:

   kubectl create secret generic cerbos-tls \
     --from-file=tls.crt=/path/to/cert.pem \
     --from-file=tls.key=/path/to/key.pem \
     --from-file=ca.crt=/path/to/ca.pem
   

   The secret must contain:

   • tls.crt - Certificate chain (required)
   • tls.key - Private key (required)
   • ca.crt - CA certificate for trust pool (optional)
2. Install with TLS enabled

   helm install cerbos cerbos/cerbos \
     --version=0.52.0 \
     --set=cerbos.tlsSecretName=cerbos-tls
   

Using cert-manager

If you use cert-manager, the chart can create a Certificate resource:

certManager:
  certSpec:
    secretName: cerbos-tls-cert
    issuerRef:
      name: letsencrypt-prod
      kind: ClusterIssuer
    dnsNames:
      - cerbos.example.com

Install with cert-manager:

helm install cerbos cerbos/cerbos \
  --version=0.52.0 \
  --values=cert-manager-values.yaml

Storage Configurations

Git Repository Storage

Deploy Cerbos configured to read policies from a Git repository.

1. Create GitHub personal access token

   Follow GitHub’s documentation to create a PAT with repo permissions.

2. Create Kubernetes secret

   PAT=YOUR_GITHUB_TOKEN
   kubectl create secret generic cerbos-github-token \
     --from-literal=GITHUB_TOKEN=$PAT
   
3. Create values file

   Create git-values.yaml:

   envFrom:
     - secretRef:
         name: cerbos-github-token
   
   cerbos:
     config:
       storage:
         driver: "git"
         git:
           protocol: https
           url: https://github.com/your-org/policies.git
           branch: main
           subDir: policies
           checkoutDir: /work
           updatePollInterval: 60s
           https:
             username: "cerbos"
             password: "${GITHUB_TOKEN}"
   
4. Install with Git storage

   helm install cerbos cerbos/cerbos \
     --version=0.52.0 \
     --values=git-values.yaml
   

Volume-Mounted Storage

Deploy Cerbos with policies from a Kubernetes volume.

1. Create values file

   Create volume-values.yaml:

   volumes:
     - name: cerbos-policies
       hostPath:
         path: /data/cerbos-policies
   
   volumeMounts:
     - name: cerbos-policies
       mountPath: /policies
       readOnly: true
   
   cerbos:
     config:
       storage:
         driver: "disk"
         disk:
           directory: /policies
           watchForChanges: true
   
2. Install with volume storage

   helm install cerbos cerbos/cerbos \
     --version=0.52.0 \
     --values=volume-values.yaml
   

You can use any Kubernetes volume type (PersistentVolumeClaim, ConfigMap, NFS, etc.) instead of hostPath. See Kubernetes volumes documentation.

Cerbos Hub Storage

Connect your PDP to Cerbos Hub for centralized policy distribution.

1. Create Hub credentials secret

   kubectl create secret generic cerbos-hub-credentials \
     --from-literal=CERBOS_HUB_CLIENT_ID=your_client_id \
     --from-literal=CERBOS_HUB_CLIENT_SECRET=your_client_secret \
     --from-literal=CERBOS_HUB_DEPLOYMENT_ID=your_deployment_id
   
2. Create values file

   Create hub-values.yaml:

   cerbos:
     config:
       audit:
         enabled: true
         backend: "hub"
         hub:
           storagePath: /audit_logs
   
   envFrom:
     - secretRef:
         name: cerbos-hub-credentials
   
   volumes:
     - name: cerbos-audit-logs
       emptyDir: {}
   
   volumeMounts:
     - name: cerbos-audit-logs
       mountPath: /audit_logs
   

   For production, use a PersistentVolume instead of emptyDir for audit log storage.

3. Install with Hub integration

   helm install cerbos cerbos/cerbos \
     --version=0.52.0 \
     --values=hub-values.yaml
   

Scaling and High Availability

Horizontal Scaling

Increase replicas for high availability:

helm install cerbos cerbos/cerbos \
  --version=0.52.0 \
  --set=replicaCount=3

Autoscaling

Enable Horizontal Pod Autoscaler:

autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 80
  targetMemoryUtilizationPercentage: 80

Install with autoscaling:

helm install cerbos cerbos/cerbos \
  --version=0.52.0 \
  --set=autoscaling.enabled=true \
  --set=autoscaling.minReplicas=2 \
  --set=autoscaling.maxReplicas=10

DaemonSet Mode

Deploy as a DaemonSet for node-local access:

helm install cerbos cerbos/cerbos \
  --version=0.52.0 \
  --set=type=daemonset

Resource Management

Set resource limits and requests:

resources:
  limits:
    cpu: 1000m
    memory: 512Mi
  requests:
    cpu: 250m
    memory: 256Mi

Apply resource limits:

helm install cerbos cerbos/cerbos \
  --version=0.52.0 \
  --set=resources.limits.cpu=1000m \
  --set=resources.limits.memory=512Mi \
  --set=resources.requests.cpu=250m \
  --set=resources.requests.memory=256Mi

Advanced Configuration

Customizing Manifests with Kustomize

For advanced customization, use Helm’s post-renderer feature with Kustomize.

1. Create kustomization.yaml

   resources:
     - base.yaml
   patches:
     - patch: |-
         - op: add
           path: /spec/loadBalancerSourceRanges
           values: ["10.0.0.0/16"]
       target:
         version: v1
         kind: Service
   
2. Create post-renderer script

   Create kustomize.sh and make it executable:

   #!/usr/bin/env bash
   cat > base.yaml
   exec kubectl kustomize
   

   chmod +x kustomize.sh
   
3. Test the customization

   helm template cerbos cerbos/cerbos --post-renderer ./kustomize.sh
   
4. Install with customization

   helm install cerbos cerbos/cerbos \
     --version=0.52.0 \
     --post-renderer=./kustomize.sh
   

Service Types

ClusterIP (Default)

helm install cerbos cerbos/cerbos \
  --version=0.52.0 \
  --set=service.type=ClusterIP

Monitoring and Observability

Prometheus Integration

Enable Prometheus service discovery annotations:

cerbos:
  prometheusPodAnnotationsEnabled: true

This adds annotations to pods for automatic Prometheus scraping.

Custom Environment Variables

Inject additional environment variables:

env:
  - name: CERBOS_NO_TELEMETRY
    value: "1"
  - name: CUSTOM_VAR
    value: "custom-value"

Upgrading

Upgrade an existing installation:

helm upgrade cerbos cerbos/cerbos \
  --version=0.52.0 \
  --values=values.yaml

View upgrade diff before applying:

helm diff upgrade cerbos cerbos/cerbos \
  --version=0.52.0 \
  --values=values.yaml

Uninstalling

Remove the Cerbos deployment:

helm uninstall cerbos

Troubleshooting

Check Pod Status

kubectl get pods -l app.kubernetes.io/name=cerbos

Chart Information

• Chart Version: 0.52.0
• App Version: 0.52.0
• Kubernetes Version: >= 1.23.0
• Maintainer: Cerbos Authors ([e-mail])
• Repository: https://download.cerbos.dev/helm-charts
• Source: https://github.com/cerbos/cerbos

Next Steps

• Configure deployment patterns for different use cases
• Set up sidecar deployments for per-pod access
• Explore DaemonSet mode for node-local PDPs
• Review production best practices for Kubernetes