Build & Package Policy¶

Preface¶

This guide will explain how to build and package a OPA Bundle from your policy. The bundle will be exported in OCI format, allowing publishing to an OCI registry.

Tip

Bundle Manifest¶

OPA OCI Bundles must contain a JSON formatted Manifest file (.manifest) which describes the bundle contents. This file must include the package roots - a list of package paths which the bundle provides.

Example

.manifest

{
    "roots": ["system", "my/helper"]
}

Building Policy¶

The OPA Bundle can be built using the opa build command. The policy bundle we are building is supplied using the --bundle option with the version given using the --revision option. If your policy package contains tests then you should ignore them using --ignore *_test.rego. This should produce a file of the form ``.

Example

opa build --bundle policy/ --revision v1.2.3 --ignore *_test.rego

Publishing Policy¶

The OCI image can be created an published using the oras push command. The first argument of the command is the registry which the image is to be pushed to whilst the second argument is the file to include in the image and the custom media type to use - this should be the file produced by opa build followed by :application/vnd.oci.image.layer.v1.tar+gzip.

Example

oras push localhost:5000/policy:v1.2.3 bundle.tar.gz:application/vnd.oci.image.layer.v1.tar+gzip

Continious Delivery¶

It is strongly recommended you implement policy packaging as part of your Continious Integration (CI) and Continious Delivey (CD) pipelines, an example for doing this in GitHub Actions is shown below.

Github action for building and releasing OPA policy as OCI bundle on GHCR

name: Policy Container

on:
  workflow_call:

jobs:
  build_publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - name: Checkout source
        uses: actions/checkout@v4.2.2

      - name: Generate Image Name
        run: echo IMAGE_REPOSITORY=ghcr.io/$(echo "${{ github.repository }}-policy" | tr '[:upper:]' '[:lower:]' | tr '[_]' '[\-]') >> $GITHUB_ENV

      - name: Log in to GitHub Docker Registry
        uses: docker/login-action@v3.3.0
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Setup OPA
        uses: open-policy-agent/setup-opa@v2.2.0
        with:
          version: latest

      - name: Build OPA Policy
        run: >
          opa
          build
          --bundle policy
          --revision ${{ github.ref_name }}
          --ignore *_test.rego

      - name: Publish OPA Bundle
        if: ${{ github.event_name == 'push' && startsWith(github.ref, 'refs/tags') }}
        run: >
          oras
          push
          ${{ env.IMAGE_REPOSITORY }}:${{ github.ref_name }}
          bundle.tar.gz:application/vnd.oci.image.layer.v1.tar+gzip