Using Built On Envoy (BOE) Extensions

Built on Envoy (BOE) is a curated catalog of Envoy extensions covering security, traffic control, authentication, and AI use cases. TEG comes with all BOE extensions pre-loaded and ready to use — no additional images, init containers, or custom builds required. You simply declare which extension to activate on a given route or gateway, and TEG handles the rest.

Notable Extensions

Extension	Category	Description
openapi-validator	Traffic Control	Validate HTTP requests against an OpenAPI 3.x specification; reject non-conforming requests before they reach your service
opa	Security	Evaluate Open Policy Agent Rego policies inline in the data plane — no external OPA server required
cedar-auth	Security	Inline Cedar policy evaluation for fine-grained, attribute-based authorization
azure-content-safety	AI / Security	Azure AI Content Safety integration for LLM prompt protection and content moderation
bedrock-guardrails	AI / Security	Apply AWS Bedrock Guardrails for LLM prompt protection and content moderation
token-exchange	Authentication / Security	Exchange inbound Bearer tokens for service-scoped tokens via an STS, implementing RFC 8693
saml	Authentication / Security	SAML 2.0 Service Provider authentication for Envoy HTTP traffic

BOE also includes a growing set of AI extensions — including LLM request routing, token usage monitoring, and OpenAI/Anthropic request decoding. See the full catalog for details.

Overview

Configuring a BOE extension involves two steps:

1. Configure auto-mount annotations — if the extension needs to read files (e.g., an OpenAPI spec, a Rego policy, or TLS certificates), create a ConfigMap or Secret in the same namespace as the Envoy deployment, label it with teg.tetrate.io/auto-mount: "true", and annotate it to declare which Gateways should receive the mount. TEG will automatically project these files into the Envoy pod at /etc/teg/auto-mounts/<resource-name>/.

2. Configure an EnvoyExtensionPolicy — reference the BOE composer dynamic module and select the extension by name with its configuration. File paths in the config must match the paths provided by the auto-mount controller.

How auto-mount Works

When a ConfigMap or Secret is labeled and annotated correctly, the TEG auto-mount controller patches the target EnvoyProxy resource to add the necessary volumes and volume mounts. The result is that files appear at:

/etc/teg/auto-mounts/<configmap-or-secret-name>/<key>

The required annotations are:

Annotation	Required	Description
teg.tetrate.io/scope	yes	GatewayClass or Gateway — whether targets are GatewayClass names or Gateway namespace/name pairs
teg.tetrate.io/targets	yes	Comma-separated list of target names. Bare names for GatewayClass scope; namespace/name for Gateway scope
teg.tetrate.io/items	no	Comma-separated list of keys to mount. If omitted, all keys are mounted

Namespace requirements

ConfigMaps and Secrets must be created in the same namespace as the Envoy deployment:

• Controller-namespace mode (default): envoy-gateway-system
• Gateway-namespace mode: the namespace of the Gateway resource

Prerequisites

• TEG 1.8.0 or later installed (BOE extensions are included in the default TEG Envoy image — no additional setup is needed)
• A Gateway and HTTPRoute deployed. You can follow the Expose Your Application guide to reach this point

Example 1: OpenAPI Request Validation

The openapi-validator extension validates incoming HTTP requests against an OpenAPI specification, rejecting requests that do not conform.

Step 1 — Create a ConfigMap with the OpenAPI spec

Store your OpenAPI spec in a ConfigMap in the envoy-gateway-system namespace and annotate it for auto-mount. This example targets a GatewayClass named teg:

apiVersion: v1
kind: ConfigMap
metadata:
  name: httpbin-openapi-spec
  namespace: envoy-gateway-system
  labels:
    teg.tetrate.io/auto-mount: "true"
  annotations:
    teg.tetrate.io/scope: GatewayClass
    teg.tetrate.io/targets: teg
    teg.tetrate.io/items: openapi.yaml
data:
  openapi.yaml: |
    openapi: "3.0.3"
    info:
      title: httpbin API
      version: "1.0"
    paths:
      /get:
        get:
          summary: Returns the request's GET parameters
          responses:
            "200":
              description: The request's GET parameters
              content:
                application/json:
                  schema:
                    type: object
      /post:
        post:
          summary: Returns the request's POST parameters
          requestBody:
            required: true
            content:
              application/json:
                schema:
                  type: object
                  required:
                    - name
                    - email
                  additionalProperties: false
                  properties:
                    name:
                      type: string
                    email:
                      type: string
                      format: email
          responses:
            "200":
              description: The request's POST parameters
              content:
                application/json:
                  schema:
                    type: object

TEG will mount this file at /etc/teg/auto-mounts/httpbin-openapi-spec/openapi.yaml on all Envoy pods managed by the teg GatewayClass.

Step 2 — Configure the EnvoyExtensionPolicy

Apply an EnvoyExtensionPolicy that attaches the openapi-validator filter to your HTTPRoute:

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyExtensionPolicy
metadata:
  name: openapi-validation
  namespace: default
spec:
  targetRef:
    group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: httpbin
  dynamicModule:
    - name: composer
      filterName: openapi-validator
      config:
        spec:
          file: /etc/teg/auto-mounts/httpbin-openapi-spec/openapi.yaml
        max_body_bytes: 65536
        deny_response:
          status: 422
          body: "Request does not conform to the API specification"
          headers:
            content-type: "text/plain"

Requests to paths or with parameters not described in the spec will be rejected with a 422 response.

tip

Set dry_run: true during initial rollout to log validation failures without blocking traffic. Switch to enforcement mode once you are confident the spec is accurate.

Example 2: OPA Policy Enforcement

The opa extension evaluates incoming HTTP requests against Open Policy Agent Rego policies inline in the data plane — no external OPA server required.

Step 1 — Create a ConfigMap with the Rego policy

The following policy allows requests only if the x-user header is set to alice:

apiVersion: v1
kind: ConfigMap
metadata:
  name: opa-authz-policy
  namespace: envoy-gateway-system
  labels:
    teg.tetrate.io/auto-mount: "true"
  annotations:
    teg.tetrate.io/scope: Gateway
    teg.tetrate.io/targets: default/edge-gateway
    teg.tetrate.io/items: authz.rego
data:
  authz.rego: |
    package envoy.authz

    import input.attributes.request.http as http_request

    default allow := {"allowed": false, "http_status": 403, "body": "Rejected by OPA\n"}

    allow := {"allowed": true} if {
      http_request.headers["x-user"] == "alice"
    }

TEG will mount this file at /etc/teg/auto-mounts/opa-authz-policy/authz.rego on the Envoy pod serving the default/edge-gateway Gateway.

Step 2 — Configure the EnvoyExtensionPolicy

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyExtensionPolicy
metadata:
  name: opa-authz
  namespace: default
spec:
  targetRef:
    group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: my-route
  dynamicModule:
    - name: composer
      filterName: opa
      config:
        policies:
          - file: /etc/teg/auto-mounts/opa-authz-policy/authz.rego
        decision_path: envoy.authz.allow
        fail_open: false

Requests that do not satisfy the policy will be rejected with a 403 Forbidden response.

Testing the policy

# Denied — header missing
curl -i http://${GATEWAY_IP}/my-route/resource

# Allowed — correct header
curl -i -H "x-user: alice" http://${GATEWAY_IP}/my-route/resource

OPA input document

The Rego policy receives the full HTTP request context under input.attributes.request.http (method, path, headers) and peer identity under input.attributes.source when mTLS is enabled. Set with_body: true in the config to also expose the parsed JSON request body as input.body.

You can check the list of all available attributes in the extension documentation.

Multiple policies

You can mount multiple Rego files and list them all under policies. OPA loads all of them into the same evaluation context, so you can split helper rules and authorization logic across separate files.

Example 3: Azure AI Content Safety

The azure-content-safety extension connects to Azure AI Content Safety to inspect LLM traffic flowing through your gateway. It covers both the request path (prompt injection detection, task adherence) and the response path (harmful content categories, protected material detection). Non-chat traffic passes through uninspected.

The extension needs an Azure API key to authenticate with the Content Safety service. Store the key in a Kubernetes Secret and use auto-mount to deliver it to the Envoy pod as a file — the extension's api_key field accepts a file path directly.

Step 1 — Create a Secret with the Azure API key

apiVersion: v1
kind: Secret
metadata:
  name: azure-content-safety-key
  namespace: envoy-gateway-system
  labels:
    teg.tetrate.io/auto-mount: "true"
  annotations:
    teg.tetrate.io/scope: Gateway
    teg.tetrate.io/targets: default/ai-gateway
    teg.tetrate.io/items: api-key
stringData:
  api-key: "<your-azure-content-safety-subscription-key>"

TEG mounts this file at /etc/teg/auto-mounts/azure-content-safety-key/api-key on the Envoy pod serving the default/ai-gateway Gateway.

Step 2 — Configure the EnvoyExtensionPolicy

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyExtensionPolicy
metadata:
  name: azure-content-safety
  namespace: default
spec:
  targetRef:
    group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: llm-route
  dynamicModule:
    - name: composer
      filterName: azure-content-safety
      config:
        endpoint: "https://my-resource.cognitiveservices.azure.com"
        api_key:
          file: /etc/teg/auto-mounts/azure-content-safety-key/api-key
        mode: block
        fail_open: false
        hate_threshold: 4
        violence_threshold: 4
        enable_protected_material: true

Requests containing detected prompt injection attacks are rejected with 403 Forbidden. Responses containing harmful content above the configured thresholds are also blocked before reaching the client.

Detection coverage

On the request path, the extension runs Prompt Shield on every chat request to detect injection attacks. Enable enable_task_adherence: true to also verify that agent tool calls align with the declared task.

On the response path, the extension analyses text across four harm categories — hate, self-harm, sexual, and violence — using a severity scale from 0 to 6. The default threshold of 2 blocks anything above the safe level. Enable enable_protected_material: true to additionally detect copyrighted text in model responses.

Start in monitor mode

Set mode: monitor during initial rollout to log detections without blocking traffic. This lets you evaluate the safety service and tune thresholds before switching to mode: block.

What's Next

The examples above cover three common use cases, but TEG ships with the full Built on Envoy extension catalog available out of the box. Whether you need fine-grained Cedar authorization, JWE token decryption, IP restrictions, AI gateway capabilities, or a Web Application Firewall, there is a BOE extension ready to activate with a single EnvoyExtensionPolicy.

Browse the catalog at builtonenvoy.io/extensions to discover what else is available — each extension page includes a full config reference, examples, and notes on expected behavior.