Install from Helm chart
This documentation is for an as-yet unreleased version of Cerbos. Choose 0.40.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.41.0-prerelease
Cerbos Helm chart is also available from an OCI registry.
|
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.41.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.41.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 type2 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.41.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.41.0-prerelease --values=hub-values.yaml