canonical: https://jentic.com/apis/googleapis.com/networkservices

# Google Network Services API

The Network Services API manages Google Cloud's application-aware networking resources - gateways, meshes, endpoint policies, HTTP/gRPC/TCP/TLS routes, service bindings, and authorization extensions. It is the control plane for Cloud Service Mesh and managed networking resources that route traffic to backend services with L7 logic. Use it to configure traffic routing, attach service extensions for custom request/response processing, and bind services to meshes. The spec exposes 38 endpoints across regional locations.

## For AI agents

Configure Google Cloud application networking - gateways, service mesh, HTTP/gRPC routes, and traffic extensions - through 38 control-plane endpoints.

## Scope

Does not handle VPC firewall enforcement, DNS resolution, or backend service compute provisioning - use for application-layer routing and extension resources only.

## Capabilities

- Provision gateways and meshes that front backend services with L7 routing
- Author HTTP, gRPC, TCP, and TLS routes that map traffic to backend service buckets
- Attach service and authz extensions that mutate requests or call external auth servers
- Bind individual services into a mesh with service bindings for east-west routing
- Define endpoint policies that apply security and routing rules to mesh sidecars
- Track regional rollouts via long-running operations and cancel changes that go wrong

## Use cases

### L7 traffic routing for Cloud Service Mesh

Define HTTP, gRPC, TCP, and TLS routes that direct traffic into backend services based on host, path, headers, and SNI. The Network Services API stores these routes as first-class resources tied to meshes and gateways, enabling progressive delivery patterns like header-based canaries and traffic splits without restarting workloads. Best for teams running gRPC microservices behind Cloud Service Mesh.

Example prompt: Create an HTTP route in us-central1 that sends 90 percent of /checkout traffic to backend service checkout-stable and 10 percent to checkout-canary.

### Service extensions for request mutation and auth

Attach lb-traffic and authz extensions that intercept traffic at the load balancer and either mutate headers or call an external authorization server before the request hits the backend. Useful for centralised header injection, custom WAF logic, or zero-trust auth that needs to consult an OPA or external IDP. The extension model means you write the policy logic once and apply it across many routes.

Example prompt: Create an lbTrafficExtension that calls a Cloud Run service to add a custom request-id header, then attach it to forwarding rule fr-prod-https.

### Mesh service binding and endpoint policy

Bind individual backend services into a mesh via service bindings and apply endpoint policies that govern how sidecars in the mesh treat traffic for those endpoints. The API treats mesh, service binding, and endpoint policy as separate resources so teams can independently manage membership, routing, and per-endpoint security overrides. Useful for multi-cluster GKE deployments managed centrally.

Example prompt: Create a service binding that attaches the service projects/p/locations/global/services/payments to mesh prod-mesh, then list all bindings on the mesh.

### Agent-driven traffic policy automation via Jentic

An AI agent responding to a deployment event can use Jentic to find the right Network Services operation - for example, updating an HTTP route to flip the canary split - and execute it without holding raw OAuth tokens. This lets release bots and SRE chatbots steer production traffic with auditable, scoped credentials. Jentic returns the operation schema so the agent can construct the request body correctly.

Example prompt: Use Jentic to find the operation that updates an HTTP route, load its schema, and shift the traffic weight for backend checkout-canary from 10 to 50.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /v1/{+parent}/httpRoutes | Create an HTTP route |
| POST | /v1/{+parent}/grpcRoutes | Create a gRPC route |
| POST | /v1/{+parent}/gateways | Create a managed gateway |
| POST | /v1/{+parent}/meshes | Create a service mesh |
| POST | /v1/{+parent}/serviceBindings | Bind a service into a mesh |
| POST | /v1/{+parent}/authzExtensions | Create an authz extension |
| GET | /v1/{+name}/operations | List long-running operations |

## Key resources

- **gateways** — Managed L7 gateway resources that terminate traffic
- **meshes** — Cloud Service Mesh control-plane resources
- **httpRoutes** — HTTP routing rules attached to gateways or meshes
- **grpcRoutes** — gRPC routing rules with method-level matching
- **tcpRoutes** — TCP-level routing for non-HTTP workloads
- **tlsRoutes** — TLS SNI-based routing rules
- **serviceBindings** — Bindings that register services into a mesh
- **endpointPolicies** — Per-endpoint security and routing policy
- **lbTrafficExtensions** — Load balancer traffic mutation extensions
- **authzExtensions** — External authorization callout extensions

## Why Jentic

- **Setup:** Wiring the Network Services API by hand means configuring Google OAuth 2.0 from a service account, minting scoped tokens, and polling long-running operations against networkservices.googleapis.com yourself. Through Jentic you install once, import the Network Services API from the API Directory, store the OAuth credential once, and your agent calls it.
- **Permission scoping:** The Network Services API puts the parent location and resource in the URL path (/v1/{+parent}/httpRoutes, /v1/{+name}), so a rule can pin your agent to one parent location: it can create the routing and mesh resources you allow there and nothing else. You choose the operations it may call, so you can allow route creation while leaving gateway or mesh changes out of the allowed set.
- **Credential handling:** Your Google OAuth credential for the Network Services API 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 'create an HTTP route' or 'attach an authz extension', and Jentic returns the matching Network Services operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Compute Engine API** — Compute Engine manages backend services and forwarding rules referenced by Network Services routes
- **Network Security API** — Network Security defines TLS and authorization policies that bind into Network Services gateways
- **Cloud DNS API** — Cloud DNS resolves the hostnames that Network Services gateways serve

## FAQ

### What authentication does the Network Services API use?

The API uses Google OAuth 2.0 with the cloud-platform scope. Through Jentic, tokens are minted from a service account stored in your Jentic One instance and never exposed to the agent.

### Can I create traffic splits with HTTP routes?

Yes. POST to /v1/{+parent}/httpRoutes with destinations carrying weight values to split traffic across multiple backend services for canary or blue/green rollouts.

### What are the rate limits for the Network Services API?

Google Cloud applies per-project quotas for mutating control-plane operations, generally a few hundred per minute. Treat large fan-outs as long-running by polling the returned operation rather than retrying writes.

### How do I attach an authz extension through Jentic?

Search Jentic for create authz extension, load the schema for the POST on /v1/{+parent}/authzExtensions, and execute it with the extension body. The Jentic SDK returns the long-running operation handle for status polling.

### Does this API enforce TLS termination on packets?

No - the API is a control plane that registers route, gateway, and extension resources. The actual TLS termination and routing happens inside Google's load balancer and Envoy data planes.

### How do I bind a service into a mesh?

POST to /v1/{+parent}/serviceBindings with the service resource name and the target mesh; existing bindings are listed via GET on the same path.

### Can I limit what my agent is allowed to do with the Network Services API?

Yes. Because you self-host Jentic One, your own rules decide which Network Services operations and credentials the agent may use. Since this API carries the parent location and resource in the URL path (/v1/{+parent}/httpRoutes, /v1/{+name}), you can pin the agent to a single parent location and hand it only the operations you approve. For example, you can allow it to create HTTP or gRPC routes while leaving gateway and mesh creation out of the allowed set, and the OAuth credential stays with your instance rather than the agent.