Install from Helm chart

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.25.0

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.25.0

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.25.0 --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.

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

1	Create an environment variable from the secret we created
2	Use the environment variable containing the PAT as the username to login to GitHub
3	Password should be empty when using a PAT to authenticate to GitHub

Deploy Cerbos using the Helm chart

helm install cerbos cerbos/cerbos --version=0.25.0 --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.25.0 --values=pv-values.yaml