Install from Helm chart

This documentation is for an as-yet unreleased version of Cerbos. Choose 0.39.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.40.0-prerelease

Cerbos Helm chart is also available from an OCI registry.

HELM_EXPERIMENTAL_OCI=1 helm install cerbos oci://ghcr.io/cerbos/helm-charts/cerbos --version=0.40.0-prerelease

Securing Cerbos with TLS

Cerbos 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.40.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 server. See the Kubernetes sidecar documentation for an example of deploying Cerbos 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.40.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 (1)

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" (2)
          password: "${GITHUB_TOKEN}" (3)

1	Create an environment variable from the secret we created
2	Username should be set to a string value (can be any value if using GitHub)
3	Use the environment variable containing the PAT as the password to login to GitHub

Deploy Cerbos using the Helm chart

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

Deploy Cerbos configured to read policies from a mounted volume

Here we demonstrate how to use a hostPath volume to feed policies to a Cerbos 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: (1)
  - name: cerbos-policies
    hostPath:
      path: /data/cerbos-policies

volumeMounts: (2)
  - name: cerbos-policies
    mountPath: /policies
    readOnly: true

cerbos:
  config:
    storage:
      driver: "disk"
      disk:
        directory: /policies (3)
        watchForChanges: true

1	Define a `hostPath` volume type
2	Mount the volume to the container at the path `/policies`
3	Configure Cerbos to read policies from the mounted `/policies` directory

Deploy Cerbos using the Helm chart

helm install cerbos cerbos/cerbos --version=0.40.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 \ (1)
   --from-literal=CERBOS_HUB_CLIENT_SECRET=YOUR_CLIENT_SECRET \ (2)
   --from-literal=CERBOS_HUB_WORKSPACE_SECRET=YOUR_WORKSPACE_SECRET (3)

1	Client ID from the Cerbos Hub credential
2	Client secret from the Cerbos Hub credential
3	Cerbos Hub workspace secret

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

cerbos:
  config:
    # Configure the Hub storage driver
    storage:
      driver: "hub"
      # Configure deployment label. Alternatively, add `CERBOS_HUB_BUNDLE=<YOUR_LABEL>` to the secret you created above.
      hub:
        remote:
          bundleLabel: "YOUR_LABEL" (1)

    # Configure the Hub audit backend
    audit:
      enabled: true (2)
      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

1	The label to watch for bundle updates. See deployment labels documentation for details.
2	Enables audit log collection. See Hub audit log collection documentation for information about masking sensitive fields and other advanced settings.

Deploy Cerbos using the Helm chart

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