Automating Cerbos Policy deployments with Buildkite

This guide will help you set up a CI/CD pipeline in Buildkite to automatically upload your Cerbos policies to a Cerbos Hub store whenever you push changes to the main branch of your Git repository.

Prerequisites

• A Buildkite account and a configured "Pipeline".
• Your own "agent" running on a machine that has Docker installed.
• The ID of your Cerbos Hub store, which you can find in the store section of the Cerbos Hub.
• Your CERBOS_HUB_CLIENT_ID and CERBOS_HUB_CLIENT_SECRET values generated in the Client credentials section of the Cerbos Hub store. Make sure to select the Read & Write option when creating the credentials to allow uploading policies.

Step 1: Configure Secrets on Your Agent Machine

Buildkite agents pull secrets from their environment. The simplest way is to define them directly on the agent machine.

1. Log into the server where your Buildkite agent is running.
2. Add your secrets to a system-wide environment file, like /etc/environment. Open it with a text editor (e.g., sudo nano /etc/environment) and add these lines:

CERBOS_HUB_CLIENT_ID="your-client-id-here"
CERBOS_HUB_CLIENT_SECRET="your-client-secret-here"

3. Save the file and restart your Buildkite agent service for the changes to take effect (e.g., sudo systemctl restart buildkite-agent).

Step 2: Create the Pipeline File

1. In your repository, create a directory named .buildkite.
2. Inside .buildkite, create a file named pipeline.yml.
3. Copy and paste the following code into it:
4. Replace [STORE_ID] with the ID of your Cerbos Hub store. You can find this in the Cerbos Hub UI under the store settings.

# .buildkite/pipeline.yml
steps:
  - command: |
      docker run --rm \
        -e CERBOS_HUB_STORE_ID="[STORE_ID]" \
        -e CERBOS_HUB_CLIENT_ID=$CERBOS_HUB_CLIENT_ID \
        -e CERBOS_HUB_CLIENT_SECRET=$CERBOS_HUB_CLIENT_SECRET \
        -v "$PWD":/app \
        ghcr.io/cerbos/cerbosctl:latest \
        hub store replace-files /app --message="Policy upload from Buildkite"
    
    if: build.branch == 'main'
    label: "Upload Cerbos Policies"

Step 3: Commit and Push

1. Commit the .buildkite/pipeline.yml file.
2. Push your changes to the main branch.

Step 4: Verify the Run

1. Go to your pipeline in the Buildkite dashboard.
2. A new build will be triggered. Click on it to watch the "Upload Cerbos Policies" step execute on your agent.