canonical: https://jentic.com/apis/googleapis.com/trafficdirector # Google Traffic Director API Traffic Director is Google Cloud's managed control plane for service mesh and proxyless gRPC architectures. Its single discovery endpoint reports the runtime status of connected Envoy proxies and gRPC clients - which clusters, listeners, routes, and endpoints each xDS client has accepted, and which versions are in use. Operators query this surface to debug mesh propagation, verify configuration roll-outs across thousands of sidecars, and confirm that a new route or endpoint update has reached every workload. ## For AI agents Inspect runtime xDS client status across an Envoy or proxyless gRPC service mesh managed by Traffic Director. ## Scope Does not configure routes, clusters, or endpoints - use for inspecting runtime xDS client status of an existing Traffic Director mesh only. ## Capabilities - Query the runtime configuration accepted by each connected Envoy proxy - List xDS resource versions currently active across mesh clients - Diagnose configuration propagation lag between control plane and proxies - Filter client status by node ID, locality, or resource type - Inspect listeners, clusters, routes, and endpoints from a client's perspective ## Use cases ### Mesh Rollout Verification After pushing a new routing configuration through Traffic Director, platform engineers query the discovery client_status endpoint to confirm that every Envoy and proxyless gRPC client has accepted the latest version. The endpoint returns the resource versions currently in use per client, making it straightforward to surface laggard proxies still on the previous configuration. This shortens rollout verification from minutes of UI drilling to a single API call. Example prompt: POST /v3/discovery:client_status with no node_matchers to receive the full mesh client status, then group results by accepted resource version. ### Mesh Health Auditor Reliability teams build a continuous auditor that polls the client_status endpoint and alerts when any mesh client falls more than two configuration versions behind, fails to ack a resource type, or disconnects for longer than a threshold. The auditor turns Traffic Director's runtime state into a Prometheus metric stream consumable by SRE dashboards. Example prompt: Poll /v3/discovery:client_status every 60 seconds and emit a metric per node with the highest accepted version timestamp. ### Targeted Debugging by Node ID When a single workload reports stale routing behaviour, an operator queries the client_status endpoint with a node_matcher targeting that workload's node ID. The response returns exactly that proxy's current xDS state, including which clusters and routes are loaded, eliminating the need to ssh into the workload and exec into Envoy's admin port. Example prompt: POST /v3/discovery:client_status with node_matchers containing the node ID of the affected workload. ### Agent-Driven Mesh Diagnostics via Jentic An on-call agent receives an alert about a routing anomaly, queries Traffic Director through Jentic to identify which clients have the wrong route version, and posts a diagnosis to the incident channel. Jentic isolates the GCP credential and exposes the discovery operation as a single tool call. Example prompt: Through Jentic, search 'check traffic director client status', execute the discovery operation, and summarise nodes whose accepted resource versions differ from the latest pushed. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /v3/discovery:client_status | Return the runtime xDS configuration accepted by mesh clients, optionally filtered by node matchers | ## Key resources - **ClientStatus** — Runtime xDS state of every connected Envoy or proxyless gRPC client in the mesh ## Why Jentic - **Setup:** Wiring the Traffic Director API by hand means setting up a Google service account, granting the cloud-platform scope, and assembling the xDS node_matchers and field_selectors for the client-status request yourself. Through Jentic you install once, import the Traffic Director API from the API Directory, store the service-account credential once, and your agent calls it. - **Permission scoping:** This API exposes a single client-status operation and its node and field selectors travel in the request body, so scope by operation: limit the agent to the discovery client-status operation it needs. You choose the operations it may call, so nothing beyond that status read is included unless you add it. - **Credential handling:** Your Traffic Director service-account credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'check traffic director client status', and Jentic returns the v3 discovery client-status operation with its input schema, including node_matchers, excluded_node_matchers, and field_selectors, so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Google Compute Engine API** — Manages the URL maps, backend services, and target proxies that Traffic Director propagates - **Network Services API** — Newer mesh and gateway resources (Mesh, Gateway, HttpRoute) for service-mesh configuration - **Network Security API** — TLS, server TLS policies, and authorization policies attached to Traffic Director-managed traffic ## FAQ ### What authentication does the Traffic Director API use? OAuth 2.0 with the cloud-platform scope. Service-account credentials with the trafficdirector.admin or compute.viewer role are typical for ops integrations. Through Jentic, the service-account JSON is held in the encrypted vault and short-lived tokens are minted on demand. ### Can I list all connected mesh clients with the Traffic Director API? Yes. POST /v3/discovery:client_status without node_matchers returns the runtime status of every Envoy and proxyless gRPC client connected to the project's Traffic Director instance, including the xDS resource versions each has accepted. ### What are the rate limits for the Traffic Director API? The discovery client_status endpoint is intended for diagnostic queries rather than continuous high-frequency polling. Reasonable polling intervals (every 30-60 seconds) stay well within the standard Cloud project read quota; high-cardinality filters across many node_matchers are billed against the same quota. ### How do I check mesh propagation through Jentic? Search Jentic for 'check traffic director client status', load POST /v3/discovery:client_status, and execute it with optional node_matchers. The response groups runtime xDS state per node so the agent can compute lag against the most recent control-plane push. Get started with Jentic One, the self-hosted execution layer. ### Does the Traffic Director API configure routes and clusters? No - the discovery endpoint is read-only and returns runtime client status only. Routing configuration (URL maps, backend services, target proxies) is managed through Compute Engine API resources such as urlMaps, backendServices, and targetGrpcProxies. The Traffic Director discovery surface reports what those resources look like once propagated to clients. ### Is the Traffic Director API free? The API itself is free to call. Traffic Director pricing is per-Envoy-endpoint per-hour, billed against the project that runs the service mesh; the discovery surface for inspecting client status is not separately metered. ### Can I limit what my agent is allowed to do with the Traffic Director API? Yes. Because you run Jentic One yourself, your own rules decide which operations and credentials the agent may use, and this API exposes only a single discovery client-status operation. You scope by operation, granting the agent nothing beyond that read of runtime xDS client status unless you explicitly add more. The service-account credential you store is injected at execution time and never enters the agent's prompt, logs, or context.