Skip to main content

Envoy Proxy Configuration

This document describes the configuration options for PATH's Envoy Proxy which is responsible for:

  1. Defining the set of allowed services it can process
  2. Authorizing incoming requests
  3. Rate limiting

tl;dr Just show me the config files ​

There are a total of four files used to configure Envoy Proxy in PATH:

  1. .allowed-services.lua (template example)
  2. .envoy.yaml (template example)
  3. .ratelimit.yaml (template example)
  4. .gateway-endpoints.yaml (template example)

Table of Contents ​

Initialization of configuration files​

The required Envoy configuration files can be generated from their templates by running:

make init_envoy

This will generate the following files in the local/path/envoy directory:

  • .allowed-services.lua
  • .envoy.yaml
  • .ratelimit.yaml
  • .gateway-endpoints.yaml
note

All of these files are git ignored from the PATH repo as they are specific to each PATH instance and may contain sensitive information.

Allowed Services - .allowed-services.lua​

The .allowed-services.lua file is used to define the allowed services for the Envoy Proxy.

Once created in local/path/envoy, the .allowed-services.lua file is mounted as a file in the Envoy Proxy container at /etc/envoy/.allowed-services.lua.

Terminology​

  • Authoritative ID: The service ID that that PATH uses to identify a service.
  • Alias: A string that resolves to a service ID, useful for creating human-readable subdomains for services.

The key in the config file may either be the authoritative service ID or an alias.

The value in the config file must be the authoritative service ID.

Allowed Services Functionality​

The Envoy Proxy's Lua filter will forward requests to PATH with the authoritative ID set in the target-service-id header.

For more information, see the Service ID Specification section of the Envoy Proxy documentation.

warning

All service IDs allowed by the PATH instance must be defined in the .allowed-services.lua file.

Requests for services not defined in this file will be rejected.

Allowed Services File Format​

Below is the expect file format for .allowed-services.lua. You can find a template file here.

return {
  -- 1. Shannon Service IDs
  ["anvil"] = "anvil", -- Anvil (Authoritative ID)

  -- 2. Morse Service IDs
  ["F000"] = "F000",   -- Pocket (Authoritative ID)
  ["pocket"] = "F000", -- Pocket (Alias)
}

Envoy Proxy Configuration - .envoy.yaml​

The .envoy.yaml file is used to configure the Envoy Proxy.

Once created in local/path/envoy, the .envoy.yaml file is mounted as a file in the Envoy Proxy container at /etc/envoy/.envoy.yaml.

For more information on Envoy Proxy configuration file, see the Envoy Proxy documentation.

warning

Once configured using the prompts in the make init_envoy target, the .envoy.yaml file does not require further modification.

It is not recommended to modify the .envoy.yaml file directly unless you know what you are doing.

Ratelimit Configuration - .ratelimit.yaml​

The .ratelimit.yaml file is used to configure the Ratelimit service.

Once created in local/path/envoy, the .ratelimit.yaml file is mounted as a file in the Envoy Proxy container at /etc/envoy/.ratelimit.yaml.

To make changes to the Ratelimit service, modify the .ratelimit.yaml file.

Ratelimit File Format​

Below is the expect file format for .ratelimit.yaml. You can find a template file here.

For more information on Rate Limit descriptors, see the documentation in the Envoy Rate Limit repository.

.ratelimit.yaml format:

---
domain: rl
descriptors:
  - key: rl-endpoint-id
    descriptors:
      - key: rl-throughput
        value: "30"
        rate_limit:
          unit: second
          requests_per_unit: 30

Ratelimit Customizations​

To add new throughput limits, add a new descriptor array item under the descriptors key.

For more information on Rate Limit descriptors, see the documentation in the Envoy Rate Limit repository.

Gateway Endpoints Data - .gateway-endpoints.yaml​

A GatewayEndpoint is how PATH defines a single endpoint that is authorized to use the PATH service.

It is used to define the authorization method, rate limits, and metadata for an endpoint.

For more information, see the Gateway Endpoint section in the Envoy docs.

Gateway Endpoint Functionality​

The .gateway-endpoints.yaml file is used to define the Gateway Endpoints that are authorized to make requests to the PATH instance.

Once created in local/path/envoy, the .gateway-endpoints.yaml file is mounted as a file in the PATH Auth Data Server (PADS) container at /app/.gateway-endpoints.yaml.

tip

This YAML file is provided as an easy default way to define Gateway Endpoints to get started with PATH.

For more complex use cases, you may wish to use a database as the data source for Gateway Endpoints.

For more information on how to use a database as the data source for Gateway Endpoints, see the PATH Auth Data Server (PADS) section of the Envoy docs.

Gateway Endpoint File Format​

Below is the expect file format for .gateway-endpoints.yaml. You can find an example file here which uses this schema.

endpoints:
  endpoint_1_static_key:
    auth:
      api_key: "api_key_1"

  endpoint_2_jwt:
    auth:
      jwt_authorized_users:
        - "auth0|user_1"
        - "auth0|user_2"

  endpoint_3_no_auth:
    rate_limiting:
      throughput_limit: 30
      capacity_limit: 100000
      capacity_limit_period: "CAPACITY_LIMIT_PERIOD_MONTHLY"