Skip to content
Switch branches/tags
Go to file
Cannot retrieve contributors at this time


Build Status Go Report Card

This repository contains an extended version of OPA (OPA-Envoy) that allows you to enforce OPA policies with Envoy.

Issue Management

Use OPA GitHub Issues to request features or file bugs.

Examples with Envoy-based service meshes

The OPA-Envoy plugin can be deployed with Envoy-based service meshes such as:


OPA-Envoy extends OPA with a gRPC server that implements the Envoy External Authorization API. You can use this version of OPA to enforce fine-grained, context-aware access control policies with Envoy without modifying your microservice.

More information about the OPA-Envoy plugin including performance benchmarks, debugging tips, detailed usage examples can be found here.

Quick Start

This section assumes you are testing with Envoy v1.10.0 or later.

  1. Start Minikube.

    minikube start
  2. Install OPA-Envoy.

    kubectl apply -f

    The quick_start.yaml manifest defines the following resources:

    • A ConfigMap containing an Envoy configuration with an External Authorization Filter to direct authorization checks to the OPA-Envoy sidecar. See kubectl get configmap proxy-config for details.

    • OPA configuration file, and an OPA policy into ConfigMaps in the namespace where the app will be deployed, e.g., default.

    • A Deployment consisting an example Go application with OPA-Envoy and Envoy sidecars. The sample app provides information about employees in a company and exposes APIs to get and create employees. More information about the app can be found here. The deployment also includes an init container that installs iptables rules to redirect all container traffic through the Envoy proxy sidecar. More information can be found here.

  3. Make the application accessible outside the cluster.

    kubectl expose deployment example-app --type=NodePort --name=example-app-service --port=8080
  4. Set the SERVICE_URL environment variable to the service’s IP/port.


    export SERVICE_PORT=$(kubectl get service example-app-service -o jsonpath='{.spec.ports[?(@.port==8080)].nodePort}')
    export SERVICE_HOST=$(minikube ip)
    echo $SERVICE_URL

    minikube (example):
  5. Exercise the sample OPA policy.

    For convenience, we’ll want to store Alice’s and Bob’s tokens in environment variables.

    export ALICE_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiZ3Vlc3QiLCJzdWIiOiJZV3hwWTJVPSIsIm5iZiI6MTUxNDg1MTEzOSwiZXhwIjoxNjQxMDgxNTM5fQ.K5DnnbbIOspRbpCr2IKXE9cPVatGOCBrBQobQmBmaeU"
    export BOB_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYWRtaW4iLCJzdWIiOiJZbTlpIiwibmJmIjoxNTE0ODUxMTM5LCJleHAiOjE2NDEwODE1Mzl9.WCxNAveAVAdRCmkpIObOTaSd0AJRECY2Ch2Qdic3kU8"

    Check that Alice can get employees but cannot create one.

    curl -i -H "Authorization: Bearer "$ALICE_TOKEN"" http://$SERVICE_URL/people
    curl -i -H "Authorization: Bearer "$ALICE_TOKEN"" -d '{"firstname":"Charlie", "lastname":"OPA"}' -H "Content-Type: application/json" -X POST http://$SERVICE_URL/people

    Check that Bob can get employees and also create one.

     curl -i -H "Authorization: Bearer "$BOB_TOKEN"" http://$SERVICE_URL/people
     curl -i -H "Authorization: Bearer "$BOB_TOKEN"" -d '{"firstname":"Charlie", "lastname":"Opa"}' -H "Content-Type: application/json" -X POST http://$SERVICE_URL/people

    Check that Bob cannot create an employee with the same firstname as himself.

     curl -i  -H "Authorization: Bearer "$BOB_TOKEN"" -d '{"firstname":"Bob", "lastname":"Rego"}' -H "Content-Type: application/json" -X POST http://$SERVICE_URL/people


To deploy OPA-Envoy include the following container in your Kubernetes Deployments:

- image: openpolicyagent/opa:latest-envoy
  imagePullPolicy: IfNotPresent
  name: opa-envoy
  - mountPath: /config
    name: opa-envoy-config
  - run
  - --server
  - --addr=localhost:8181
  - --diagnostic-addr=
  - --config-file=/config/config.yaml
      path: /health?plugins
      port: 8282
      path: /health?plugins
      port: 8282

The OPA-Envoy configuration file should be volume mounted into the container. Add the following volume to your Kubernetes Deployments:

- name: opa-envoy-config
    name: opa-envoy-config

Example Bundle Configuration

In the Quick Start section an OPA policy is loaded via a volume-mounted ConfigMap. For production deployments, we recommend serving policy Bundles from a remote HTTP server.

Using the configuration shown below, OPA will download a sample bundle from The sample bundle contains the exact same policy that was loaded into OPA via the volume-mounted ConfigMap.


  - name: controller
    service: controller
    addr: :9191
    path: envoy/authz/allow
    dry-run: false
    enable-reflection: false

You can download the bundle and inspect it yourself:

mkdir example && cd example
curl -s -L | tar xzv

In this way OPA can periodically download bundles of policy from an external server and hence loading the policy via a volume-mounted ConfigMap would not be required. The readinessProbe to GET /health?bundles ensures that the opa-envoy container becomes ready after the bundles are activated.


Dependencies are managed with Modules. If you need to add or update dependencies, modify the go.mod file or use go get. More information is available here. Finally commit all changes to the repository.