From d43f929f696dc50b14ed502da122f25a288995c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Volkan=20=C3=96z=C3=A7elik?= Date: Sat, 4 Jul 2026 10:33:33 -0700 Subject: [PATCH 1/2] Update Envoy examples to the v3 API MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The inline Envoy config snippets still used the v2 API, which was removed from Envoy in 1.17 and no longer works on any current release. Convert all three snippets to v3, mirroring the maintained configs in spiffe/spire-tutorials (k8s/envoy-x509): - SPIRE Agent cluster: replace the deprecated hosts/pipe syntax with load_assignment and a pipe endpoint address. - TLS certificates: replace tls_context with a transport_socket using envoy.transport_sockets.tls and a typed DownstreamTlsContext, and set resource_api_version/transport_api_version to V3 in sds_config. - Validation context: use combined_validation_context so SPIRE supplies the trust bundle over SDS while a static default_validation_context can match peer SPIFFE IDs via match_typed_subject_alt_names. Adjust the surrounding prose to name the v3 constructs and note the Envoy versions the examples apply to. Fixes #218 Signed-off-by: Volkan Özçelik --- content/docs/latest/microservices/envoy.md | 82 ++++++++++++++-------- 1 file changed, 54 insertions(+), 28 deletions(-) diff --git a/content/docs/latest/microservices/envoy.md b/content/docs/latest/microservices/envoy.md index f3b6cc49..1f42c027 100644 --- a/content/docs/latest/microservices/envoy.md +++ b/content/docs/latest/microservices/envoy.md @@ -29,6 +29,8 @@ As of SPIRE version v0.10, SDS support is enabled in SPIRE by default, so no SPI # Configuring Envoy +The following examples use the Envoy v3 API, which is required by Envoy 1.17 and later (the deprecated v2 API has been removed from Envoy). + ## SPIRE Agent Cluster Envoy must be configured to communicate with the SPIRE Agent by configuring a cluster that points to the Unix domain socket the SPIRE Agent provides. @@ -40,29 +42,40 @@ clusters: - name: spire_agent connect_timeout: 0.25s http2_protocol_options: {} - hosts: - - pipe: - path: /tmp/spire-agent/public/api.sock + load_assignment: + cluster_name: spire_agent + endpoints: + - lb_endpoints: + - endpoint: + address: + pipe: + path: /tmp/spire-agent/public/api.sock ``` The `connect_timeout` influences how fast Envoy will be able to respond if the SPIRE Agent is not running when Envoy is started or if the SPIRE Agent is restarted. ## TLS Certificates -To obtain a TLS certificate and private key from SPIRE, you can set up an SDS configuration within a TLS context. -For example: +To obtain a TLS certificate and private key from SPIRE, you can set up an SDS configuration within the TLS context of a `transport_socket`. The TLS context is configured via the `typed_config` of the transport socket, using a `DownstreamTlsContext` on listeners or an `UpstreamTlsContext` on clusters. + +For example, on a listener: ``` -tls_context: - common_tls_context: - tls_certificate_sds_secret_configs: - - name: "spiffe://example.org/backend" - sds_config: - api_config_source: - api_type: GRPC - grpc_services: - envoy_grpc: - cluster_name: spire_agent +transport_socket: + name: envoy.transport_sockets.tls + typed_config: + "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext + common_tls_context: + tls_certificate_sds_secret_configs: + - name: "spiffe://example.org/backend" + sds_config: + resource_api_version: V3 + api_config_source: + api_type: GRPC + transport_api_version: V3 + grpc_services: + envoy_grpc: + cluster_name: spire_agent ``` The name of the TLS certificate is the SPIFFE ID of the service that Envoy is acting as a proxy for. @@ -71,24 +84,37 @@ The name of the TLS certificate is the SPIFFE ID of the service that Envoy is ac Envoy uses trusted CA certificates to verify peer certificates. Validation contexts provide these trusted CA certificates. SPIRE can provide a validation context per trust domain. -To obtain a validation context for a trust domain, you can configure a validation context within the SDS configuration of a TLS context, setting the name of the validation context to the SPIFFE ID of the trust domain. +To obtain a validation context for a trust domain, you can configure a validation context within the SDS configuration of the TLS context in a `transport_socket`, setting the name of the validation context to the SPIFFE ID of the trust domain. Using a `combined_validation_context`, SPIRE supplies the trusted CA certificates via SDS while the static `default_validation_context` can restrict which peer SPIFFE IDs are accepted via `match_typed_subject_alt_names`. -For example: +For example, on a listener: ``` -tls_context: - common_tls_context: - validation_context_sds_secret_config: - name: "spiffe://example.org" - sds_config: - api_config_source: - api_type: GRPC - grpc_services: - envoy_grpc: - cluster_name: spire_agent +transport_socket: + name: envoy.transport_sockets.tls + typed_config: + "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext + common_tls_context: + combined_validation_context: + # validate the SPIFFE ID of incoming clients (optionally) + default_validation_context: + match_typed_subject_alt_names: + - san_type: URI + matcher: + exact: "spiffe://example.org/frontend" + # obtain the trust bundle from SDS + validation_context_sds_secret_config: + name: "spiffe://example.org" + sds_config: + resource_api_version: V3 + api_config_source: + api_type: GRPC + transport_api_version: V3 + grpc_services: + envoy_grpc: + cluster_name: spire_agent ``` -SPIFFE and SPIRE are focused on facilitating secure authentication as a building block for authorization, not authorization itself, and as such support for authorization-related fields in the validation context (e.g. `match_subject_alt_names`) is out of scope. Instead, we recommend you leverage Envoy’s extensive filter framework for performing authorization. +SPIFFE and SPIRE are focused on facilitating secure authentication as a building block for authorization, not authorization itself. Beyond matching the peer SPIFFE ID as shown above, we recommend you leverage Envoy’s extensive filter framework for performing authorization. Additionally, you can configure Envoy to forward client certificate details to the destination service, allowing it to perform its own authorization steps, for example by using the SPIFFE ID embedded in the URI SAN of the client X.509-SVID. From 74e0abdbcb8c1786d6386c7ccba808d6de652b29 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Volkan=20=C3=96z=C3=A7elik?= Date: Mon, 13 Jul 2026 08:01:24 -0700 Subject: [PATCH 2/2] Update content/docs/latest/microservices/envoy.md Co-authored-by: Sorin Dumitru --- content/docs/latest/microservices/envoy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/latest/microservices/envoy.md b/content/docs/latest/microservices/envoy.md index 1f42c027..6d6a67c5 100644 --- a/content/docs/latest/microservices/envoy.md +++ b/content/docs/latest/microservices/envoy.md @@ -29,7 +29,7 @@ As of SPIRE version v0.10, SDS support is enabled in SPIRE by default, so no SPI # Configuring Envoy -The following examples use the Envoy v3 API, which is required by Envoy 1.17 and later (the deprecated v2 API has been removed from Envoy). +The following examples use the Envoy v3 API, which is required by Envoy 1.17 and later. ## SPIRE Agent Cluster