Skip to content

Envoy Tutorial ENTERPRISE

Envoy is an Layer 7 proxy and communication bus designed for large modern service oriented architectures. Envoy version v1.7.0 and later supports an external authorization filter which calls an authorization service to check if the incoming request is authorized or not. This feature makes it possible to delegate authorization decisions to an external service. It also makes the request context available to the service, which can then be used to make an informed decision about the incoming request received by Envoy.

This tutorial shows how Envoy’s external authorization filter can be used with OPA as an authorization service to enforce security policies over API requests received by Envoy. It also covers examples of authoring policies over the HTTP request body. It is based on the HTTP API Authorization OPA tutorial with added policies to control the ingress or egress behavior of the application and client.

Getting Started

This tutorial requires Kubernetes 1.14 or later. To run the tutorial locally, Styra recommends that you use minikube version v1.0+ with Kubernetes 1.14.

Install Envoy System

This section describes the installation steps to create a Envoy system, install Styra on Envoy, enforce and validate the ingress policy.

Create a New Envoy System

To demonstrate the enforcement of ingress and egress policies for a sample application, you can start by creating a new Styra Envoy system. Systems are displayed on the left side of the navigation panel. To add a new system, click the + next to SYSTEMS on the left side of the navigation panel.

Fill in the following fields:

  • System type (required): Select Envoy from the drop down list.

  • System name (required): A human-friendly name so that you can distinguish between the different systems.

  • Description (optional): More details about this system.

  • Leave the Read-only switch ON to prevent users from modifying policies.

  • Leave the Launch Quick Start switch on. After this system is added, the Quick Start sidebar will guide you through configuring the system.

Now, you will see the instructions to install an example application onto your cluster.

Install the Envoy Example Application

Be sure kubectl is configured to point to the cluster and namespace you want to use for the Envoy example application.

To install Styra on Envoy, you must copy and paste all the four installation commands from SYSTEMS >> Settings >> Install for your Envoy system into your terminal. This will download and deploy the Styra Local Plane (SLP), OPA config and Envoy config.

Quick start provides the link to install example application. It consists of the following components which should now be running in your minikube. All resources are suffixed by the SYSTEM ID to mark them as unique.

  • example-app: A simple HTTP web server that allows employees of a hypothetical organization to obtain salary details at the path /finance/salary. It also exposes a path /hr/dashboard that is only accessible by employees who are part of HR. Functionally, it is a simple echo server that returns a HTTP 200 response with a plain/text body which contains a success or error message.

  • client-load: A simple shell script that generates some pre-configured HTTP GET requests to test the behavior of the deployed policy. It helps generate data to visualize the impact of the configured Egress and Ingress policies by simulating traffic to the example-app.

  • slp: Styra Local Plane (SLP) is a service that acts as an intermediary between the OPAs and Styra DAS. OPAs are configured to retrieve bundles from SLP rather than directly from DAS. This increases availability as SLP fetches bundles from Styra DAS and persists them to disk, so policies are still available to new or restarted OPAs even if Styra DAS is unavailable.

  • Each application has an initContainer openpolicyagent/proxy_init:v4 that sets up redirections for the inbound and outbound packets. Additionally, two sidecar containers for Envoy and OPA are also present in each application.

When you run the Envoy example application, the OPA sidecars will pull down the policy from the DAS tenant and start enforcing it. This process takes few minutes to complete.

![envoy-example-app](../images/envoy-example-app.png)
Figure 1: Envoy Example Application

Enforce the Ingress Policy

You can see the policies in place for your Envoy system in its app, egress, and ingress folders.

  • For app policy type, click your Envoy system to expand the policy folder >> app >> rules.rego to see the application rules for your Envoy system.

  • For egress policy type, click your Envoy system to expand the policy folder >> egress >> rules.rego to see the egress rules for your Envoy system.

  • For ingress policy type, click your Envoy system to expand the policy folder >> ingress >> rules.rego to see the ingress rules for your Envoy system.

The client-load deployment repeatedly executes the following HTTP calls in an interval of 30 seconds, pretending to be different users to help generate sample data for visualization.

1
2
3
4
5
6
7
curl --user alice:password example-app/finance/salary/alice
curl --user bob:password example-app/finance/salary/alice
curl --user bob:password example-app/finance/salary/charlie
curl --user david:password example-app/finance/salary/bob
curl --user david:password example-app/hr/dashboard
curl --user eve:password example-app/admin
curl -is httpbin.org/anything;

By default, all policies allow traffic to the service with Envoy data plane as sidecar container. You could click on Decisions tab for the Envoy system created and verify all the Allowed decisions.

The Envoy system Quick Start provides a link to replace the sample Ingress policy. With this Ingress policy published, example-app can receive Ingress traffic only on the whitelisted endpoint /finance/salary. Switch to Decisions tab and verify traffic to path /hr/dashboard and /admin are Denied.

Validate the Ingress Policy

Modify the existing Ingress policy to allow traffic to path /hr/dashboard. Quick start provides link for modifying the policy in step Modify and test your policy. To determine the effect of policy, click Validate. You will see new panes Tests and Decisions. The Decisions pane displays the change caused by replaying past decisions with the updated policy. The decisions for path /hr/dashboard are now marked as Allowed.

Next Steps

Congratulations!

Now, you have learned the following about Envoy with OPA and Styra:

  • The OPA-Envoy integration gives you fine-grained access control over microservice API authorization.

  • You can use Styra to write policies, distribute policies to OPA, and manage the decisions made by OPA.