From d449179c236ebad3881a2a82caad17a29990f4ae Mon Sep 17 00:00:00 2001 From: anita-flegg Date: Thu, 25 Jun 2026 11:01:06 -0700 Subject: [PATCH] docs: add identity-aware routing cross-links and access log fields (RFC-0055) [ai-assisted] --- _gorouter_client_cert_oss.html.md.erb | 4 ++++ instance-identity.html.md.erb | 2 ++ routing-index.html.md.erb | 1 + troubleshooting-router-error-responses.html.md.erb | 10 ++++++++++ 4 files changed, 17 insertions(+) diff --git a/_gorouter_client_cert_oss.html.md.erb b/_gorouter_client_cert_oss.html.md.erb index e0099033..1628174b 100644 --- a/_gorouter_client_cert_oss.html.md.erb +++ b/_gorouter_client_cert_oss.html.md.erb @@ -6,6 +6,10 @@ You might change this behavior with the property `router.client_cert_validation` The behavior controlled by this property is global; it applies to all requests received by Gorouters so configured. +

+Identity-aware routing uses a separate, per-domain mTLS mechanism that is configured through router.domains and enforces route policies independently of this global setting. For more information, see Enabling identity-aware routing. +

+ If Gorouter is the first point of TLS termination (your load balancer does not stop TLS, and passes the request through to Gorouter over TCP), consider the following: diff --git a/instance-identity.html.md.erb b/instance-identity.html.md.erb index e8d02c28..391770b6 100644 --- a/instance-identity.html.md.erb +++ b/instance-identity.html.md.erb @@ -24,6 +24,8 @@ You can also install the Instance Identity CA certificate as a trusted system ce For information about how developers can use the Instance Identity credentials in apps on <%= vars.app_runtime_abbr %>, see [Using Instance Identity Credentials](../devguide/deploy-apps/instance-identity.html). +The Instance Identity CA is also used by the Gorouter for per-domain mutual TLS (mTLS). For information about enabling this feature, see [Enabling identity-aware routing](../deploying/cf-deployment/enable-identity-aware-routing.html). + ## Configuring Instance Identity validity period diff --git a/routing-index.html.md.erb b/routing-index.html.md.erb index 40006139..48e10049 100644 --- a/routing-index.html.md.erb +++ b/routing-index.html.md.erb @@ -20,3 +20,4 @@ These topics are your source for information about managing routes and domains i * [Securing traffic into <%= vars.app_runtime_abbr %>](securing-traffic.html) * [Enabling and configuring TCP routing](enabling-tcp-routing.html) * [Configuring HTTP/2 support](supporting-http2.html) +* [Enabling identity-aware routing](../deploying/cf-deployment/enable-identity-aware-routing.html) diff --git a/troubleshooting-router-error-responses.html.md.erb b/troubleshooting-router-error-responses.html.md.erb index 81326404..6fe123b5 100644 --- a/troubleshooting-router-error-responses.html.md.erb +++ b/troubleshooting-router-error-responses.html.md.erb @@ -173,6 +173,16 @@ When Gorouter is configured to log additional request attempt details, the follo * `TLS Time` is the time spent during TLS handshake with the backend. * `Backend Time` is the time spent waiting on the backend to respond to the request. +When identity-aware routing is enabled on a domain, the Gorouter records additional fields for each request. These fields appear in `` in the access log format above and show `-` when the request did not go through an identity-aware domain: + +* `tls_sni` is the TLS Server Name Indication (SNI) value the caller requested. +* `caller_cf_app` is the caller's app GUID, extracted from the validated client certificate. +* `caller_cf_space` is the caller's space GUID. +* `caller_cf_org` is the caller's org GUID. +* `route_policy` is the route-policy rule that matched the request, for example `cf:app:`. It is `-` when no rule matched or enforcement is disabled. + +For more information about identity-aware routing and how these fields are used for observability, see [Identity-aware routing](../concepts/identity-aware-routing.html). + ## Diagnose Gorouter errors This section describes the basic structure of Gorouter logs and how to diagnose Gorouter errors.