Skip to main content

Envoy Gateway Integration

Safe Zone 2.1.0 supports Envoy Gateway v1.8.3 with Gateway API v1.5.1 as the BYG preview reference. The Helm chart is the supported deployment source; the repository's Kind environment is the reproducible local verification fixture.

Choose a profile​

Portable preview​

Use the portable profile for evaluation or a manually managed route:

  1. Create, compile, and activate a policy with tsz-policy.
  2. Run tsz-ext-proc with TSZ_POLICY_RESOLUTION_MODE=header.
  3. Apply the repository's EnvoyExtensionPolicy after setting the target and backend references for the deployment namespace.
  4. Add an early gateway-owned header modifier that overwrites X-TSZ-Policy with the activated policy name.
  5. Verify request and response decisions through the gateway.

Never accept a client-supplied X-TSZ-Policy value as policy authority.

Native managed​

Use the native profile when Kubernetes should own policy attachment and lifecycle:

  1. Install the TSZGuardrailPolicy CRD.
  2. Install the Helm chart with envoyGateway.enabled=true and envoyGateway.mode=native. The chart creates controller RBAC and runs tsz-controller and tsz-ext-proc with attribute-based resolution.
  3. Apply a security.thyris.ai/v1beta1 TSZGuardrailPolicy that targets a Gateway API resource.
  4. Wait for Accepted, ResolvedRefs, Programmed, and PolicySynced.
  5. Send traffic through the selected route and inspect the safe metadata, audit events, and metrics.

The controller resolves target attachment deterministically, rejects conflicting policies, publishes immutable snapshots atomically, and retains the last known good snapshot when a new policy cannot be activated.

Installation package​

Use the versioned Safe Zone Helm chart. Set envoyGateway.enabled=true, choose native or manual, and pin the Safe Zone image and chart revision together. The Envoy components remain disabled by default for existing API-only installations.

For a clean local verification, use the repository's Kind bootstrap and run the applicable BYG scenarios. The examples cover inspection, masking, blocking, audit-only rollout, streaming, authentication, rate limiting, mTLS, NetworkPolicy, observability, and response enforcement.

Required production controls​

  • Keep the external processor on a cluster-private service.
  • Authenticate Envoy to Safe Zone with mTLS and rotate both leaf certificates through the organization's PKI.
  • Restrict port 9002 to the intended Envoy workloads with NetworkPolicy.
  • Expose the health and metrics port only to trusted probes and scrapers.
  • Keep request enforcement fail-closed unless an availability exception has been explicitly approved and tested.
  • Set body, timeout, stream-window, and concurrency limits for the expected workload.
  • Monitor degraded decisions, timeouts, response callbacks without request state, stream halts, and policy activation failures.

Envoy continues to own routing, authentication, quotas, retries, and provider credentials. Do not pass provider credentials, prompt bodies, raw findings, or user identifiers through dynamic metadata or metric labels.

Migration between profiles​

Do not attach both profiles to the same route. To migrate, update the external processor's resolver mode, its attachments, and all affected routes as one controlled change. Verify the new policy identity source before removing the old attachment.

The authoritative configuration and complete operational commands live in the source repository's Envoy Gateway guide.