# Install from Helm chart

Add the Cerbos Helm repository:

```sh
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:

```sh
helm show values cerbos/cerbos --version=0.53.0
```

|     |     |
| --- | --- |
|  | Cerbos Helm chart is also available from an [OCI registry](https://helm.sh/docs/topics/registries/).<br>```sh<br>HELM_EXPERIMENTAL_OCI=1 helm install cerbos oci://ghcr.io/cerbos/helm-charts/cerbos --version=0.53.0<br>``` |

## 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](https://cert-manager.io/) 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.

```sh
helm install cerbos cerbos/cerbos --version=0.53.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](https://www.envoyproxy.io/), [Ghostunnel](https://github.com/ghostunnel/ghostunnel) or [Traefik](https://traefik.io/) as a frontend to the Cerbos server. See the [Kubernetes sidecar](https://docs.cerbos.dev/cerbos/latest/deployment/k8s-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:

```yaml
---
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:

```sh
#!/usr/bin/env bash

cat > base.yaml
exec kubectl kustomize
```

Test that the patch works as expected:

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

Now you can install Cerbos with your patches:

```sh
helm install cerbos cerbos/cerbos --version=0.53.0 --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](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

```sh
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:

```yaml
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.
        checkoutDir: /work
        # How often the remote repo should be checked for updates.
        updatePollInterval: 60s
        # Credentials used to login to the remote GitHub repo.
        https:
          username: "cerbos"
          password: "${GITHUB_TOKEN}"
```

- Deploy Cerbos using the Helm chart

```sh
helm install cerbos cerbos/cerbos --version=0.53.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/](https://kubernetes.io/docs/concepts/storage/volumes/).

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

```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
```

- Deploy Cerbos using the Helm chart

```sh
helm install cerbos cerbos/cerbos --version=0.53.0 --values=pv-values.yaml
```

## Deploy a PDP connected to Cerbos Hub

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

```sh
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:

```yaml
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

```sh
helm install cerbos cerbos/cerbos --version=0.53.0 --values=hub-values.yaml
```