Install from Helm chart

This documentation is for an as-yet unreleased version of Cerbos PDP. Choose 0.53.0 from the version picker at the top right or navigate to https://docs.cerbos.dev for the latest version.

Add the Cerbos Helm repository:

helm repo add cerbos https://download.cerbos.dev/helm-charts
helm repo update

You can view all the available configuration values for the chart by running the following command:

helm show values cerbos/cerbos --version=0.54.0-prerelease

Securing Cerbos with TLS

Cerbos PDP endpoints can be secured with TLS by providing a secret containing the certificate and its private key in the cert-manager format:

tls.crt
Certificate chain. Required.

tls.key
Private key. Required.

ca.crt
Trust chain. Optional.

During installation, provide the name of the Kubernetes secret containing the certificates by using the cerbos.tlsSecretName value.

helm install cerbos cerbos/cerbos --version=0.54.0-prerelease --set=cerbos.tlsSecretName=my-certificate-secret

If you require advanced features such as automatic certificate reloading, workload identities or mTLS, we recommend deploying a proxy server like Envoy, Ghostunnel or Traefik as a frontend to the Cerbos PDP server. See the Kubernetes sidecar documentation for an example of deploying Cerbos PDP as a sidecar to Ghostunnel.

Customizing the manifests

For the sake of simplicity, the Cerbos Helm chart only exposes settings that are most likely to be changed in a typical deployment scenario. If you want to customize the manifests further, use the post-renderer functionality in Helm to patch the generated manifests before they are applied.

For example, if you want to set loadBalancerSourceRanges of the service generated by the Cerbos Helm chart, you can use Kustomize to patch the service as follows:

Create a file named kustomization.yaml with the patches you want to apply:

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

Create a file named kustomize.sh with the following contents and make it executable:

#!/usr/bin/env bash

cat > base.yaml
exec kubectl kustomize

Test that the patch works as expected:

helm template cerbos/cerbos --post-renderer ./kustomize.sh

Now you can install Cerbos with your patches:

helm install cerbos cerbos/cerbos --version=0.54.0-prerelease --post-renderer=./kustomize.sh

Deploy Cerbos configured to read policies from a GitHub repository

• Follow the instructions at https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token to create a personal access token (PAT) with repo permissions.

• Create a new Kubernetes secret to hold the PAT

PAT=YOUR_GITHUB_PAT kubectl create secret generic cerbos-github-token --from-literal=GITHUB_TOKEN=$PAT

• Create a new values file named git-values.yaml with the following contents:

envFrom:
  - secretRef:
      name: cerbos-github-token

cerbos:
config:
    # Configure the git storage driver
    storage:
      driver: "git"
      git:
        protocol: https
        # Replace with the URL of your GitHub repo.
        url: https://github.com/cerbos/sample-policies.git
        # Replace with the branch name of your repo.
        branch: main
        # Remove or leave empty if the policies are not stored in a subdirectory.
        subDir: hr
        # Path to checkout. By default, /work is a Kubernetes emptyDir volume that is only available for the lifetime of the pod.
        # If you want the work directory to persist between pod restarts, specify the mount path of a persistent volume here.
        checkoutDir: /work
        # How often the remote repo should be checked for updates.
        updatePollInterval: 60s
        # Credentials used to login to the remote GitHub repo. We are using an environment variable mounted from the secret we created earlier.
        https:
          username: "cerbos"
          password: "${GITHUB_TOKEN}"

• Deploy Cerbos PDP using the Helm chart

helm install cerbos cerbos/cerbos --version=0.54.0-prerelease --values=git-values.yaml

Deploy Cerbos PDP configured to read policies from a mounted volume

Here we demonstrate how to use a hostPath volume to feed policies to a Cerbos PDP deployment. You can easily substitute the hostPath volume type with any other type of volumes supported by Kubernetes. See https://kubernetes.io/docs/concepts/storage/volumes/.

• Create a new values file named pv-values.yaml with the following contents:

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

• Deploy Cerbos PDP using the Helm chart

helm install cerbos cerbos/cerbos --version=0.54.0-prerelease --values=pv-values.yaml

Deploy a PDP connected to Cerbos Hub

Requires a Cerbos Hub account.

• Create a new Kubernetes secret to hold the Cerbos Hub credentials

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=CERBOS_HUB_DEPLOYMENT_ID

• Create a new values file named hub-values.yaml with the following contents:

cerbos:
    config:
      # Configure the Hub audit backend
      audit:
        enabled: true
        backend: "hub"
        hub:
          storagePath: /audit_logs

# Create environment variables from the secret.
envFrom:
  - secretRef:
      name: cerbos-hub-credentials

# Mount volume for locally buffering the audit logs. A persistent volume is recommended for production use cases.
volumes:
  - name: cerbos-audit-logs
    emptyDir: {}

volumeMounts:
  - name: cerbos-audit-logs
    mountPath: /audit_logs

• Deploy Cerbos using the Helm chart

helm install cerbos cerbos/cerbos --version=0.54.0-prerelease --values=hub-values.yaml