This guide explains how to deploy your agent workloads and Model Context Protocol (MCP) tools into a governed namespace and register them with Agent Registry in Gemini Enterprise Agent Platform. Before deploying agents, make sure that you set up Agent Gateway for cross-cloud on your cluster.
Label workloads for auto-registration
The agent-governance-cross-cloud-controller controller automatically registers
agents and MCP servers in Agent Registry. To register a workload,
add the apphub.cloud.google.com/functional-type label to the
metadata.labels field of its Deployment manifest:
- For agents, set the label to
AGENT. - For MCP servers, set the label to
MCP_SERVER.
For example:
metadata:
labels:
apphub.cloud.google.com/functional-type: "AGENT"
Specify the Agent Card location
When the controller registers an agent, it fetches the agent's Agent Card to
populate the agent's registry entry. To specify where the controller fetches the
Agent Card, add the a2a-protocol.org/agent-card annotation to the deployment.
If the annotation is missing, the controller uses the following defaults:
- Protocol:
HTTP - Port:
8080 - Endpoint:
/.well-known/agent-card.json
For example:
metadata:
labels:
apphub.cloud.google.com/functional-type: "AGENT"
annotations:
a2a-protocol.org/agent-card: |
card:
endpoint: /.well-known/agent-card.json
protocol: HTTP
port: 8080
Describe MCP server capabilities
For MCP servers, the controller extracts the server's capabilities from the
modelcontextprotocol.info/urls and modelcontextprotocol.info/capabilities
annotations on the deployment.
For example:
metadata:
labels:
apphub.cloud.google.com/functional-type: "MCP_SERVER"
annotations:
modelcontextprotocol.info/urls: |
- http://my-mcp-server.default.svc.cluster.local:8080/mcp
modelcontextprotocol.info/capabilities: |
card:
endpoint: "/mcp"
protocol: "HTTP"
port: 8080
In the modelcontextprotocol.info/urls annotation, list the endpoint URLs
where the controller can reach your MCP server.
If you specify only the modelcontextprotocol.info/urls annotation, the
controller uses the following default values for the MCP server capabilities:
- Protocol:
HTTP - Port:
8080 - Endpoint:
/mcp
Find the registered service resource
When the controller registers a workload, it adds the
agentregistry.cloud.google.com/service-uri annotation to the workload's
deployment. This annotation contains the URI of the service resource that's
registered in Agent Registry. To get the URI, run the following
commands:
SERVICE_URI=$(kubectl get deployment DEPLOYMENT_NAME \
--namespace=NAMESPACE \
-o jsonpath='{.metadata.annotations.agentregistry\.cloud\.google\.com/service-uri}')
echo $SERVICE_URI
Replace the following:
DEPLOYMENT_NAME: the name of your agent or MCP server deployment.NAMESPACE: the namespace of the deployment.
If the command returns no output, the controller hasn't registered the workload yet.
Attach projected KSA OIDC tokens
Your agent workloads must authenticate with Agent Gateway for cross-cloud by using a projected Kubernetes service account (KSA) OpenID Connect (OIDC) token, which is exchanged using Workload Identity Federation. The token's audience must be your workload identity pool provider.
To attach the token, do the following:
Mount a projected KSA token in your agent containers:
spec: template: spec: containers: - name: AGENT_CONTAINER_NAME volumeMounts: - name: ksa-token-vol mountPath: /var/run/secrets/tokens readOnly: true volumes: - name: ksa-token-vol projected: sources: - serviceAccountToken: path: ksa-token expirationSeconds: 3600 audience: "//iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID"Replace the following:
AGENT_CONTAINER_NAME: the name of your agent container.PROJECT_NUMBER: your Google Cloud project number.POOL_ID: the ID of the workload identity pool that you created during setup.PROVIDER_ID: the ID of the workload identity pool provider that you created during setup.
Include the token in every request that your workload sends to the Agent Gateway for cross-cloud proxy, for both HTTP and HTTPS traffic on ports
80,443, and8443. Read the token from/var/run/secrets/tokens/ksa-tokenand pass it in theProxy-Authorizationheader as a bearer token:Proxy-Authorization: Bearer KSA_TOKEN
Replace
KSA_TOKENwith the contents of/var/run/secrets/tokens/ksa-token. The kubelet refreshes the token before it expires, so read the token from the file for each request instead of caching it.
Route agent traffic through Agent Gateway for cross-cloud
The Agent Gateway for cross-cloud proxy governs outbound agent traffic, such as large language model (LLM), Model Context Protocol (MCP), and Agent-to-Agent (A2A) requests. The gateway supports the following modes:
- Forward proxy: You configure your agent workload to send traffic to the
gateway over HTTP or HTTPS
CONNECT, and the gateway forwards the traffic to the destination. For HTTPS requests, the gateway performs TLS inspection so that it can inspect and govern the request. - Transparent proxy: Outbound traffic is redirected to the gateway
without an HTTP
CONNECTtunnel—for example, by usingiptablesredirect rules or thecurl --connect-tooption.
The gateway accepts forward proxy (HTTP CONNECT) traffic only on port 8443,
and transparent proxy traffic only on port 443 for HTTPS and port 80 for
HTTP. Other ports don't work, even if you change the spec of the gateway's
Kubernetes resources, such as its Service or Deployment.
This section describes how to configure forward proxy mode.
To route traffic through the gateway, configure the HTTP client in your agent workload to use the Agent Gateway for cross-cloud Kubernetes service as its forward proxy. Many HTTP client libraries read the standard proxy environment variables. For example, you can set these variables in your deployment manifest:
spec:
template:
spec:
containers:
- name: AGENT_CONTAINER_NAME
env:
- name: HTTPS_PROXY
value: "https://GATEWAY_NAME.GATEWAY_NAMESPACE.svc:8443"
- name: HTTP_PROXY
value: "http://GATEWAY_NAME.GATEWAY_NAMESPACE.svc:8443"
- name: NO_PROXY
value: "NO_PROXY_HOSTS"
Replace the following:
AGENT_CONTAINER_NAME: the name of your agent container.GATEWAY_NAME: the name of theGCPAgentGatewayresource that you created during setup. The Kubernetes Service for the gateway has the same name as theGCPAgentGatewayresource.GATEWAY_NAMESPACE: the namespace of theGCPAgentGatewayresource.NO_PROXY_HOSTS: a comma-separated list of hosts that should bypass the gateway, such as the Kubernetes API server and in-cluster services—for example,.cluster.local,.svc,10.0.0.0/8.
The Agent Gateway for cross-cloud service accepts proxy traffic on port
8443. Use the http:// scheme for HTTP_PROXY and the https:// scheme for
HTTPS_PROXY. If your HTTP client library doesn't read these environment
variables, configure the proxy address directly in the client.
In forward proxy mode, the Proxy-Authorization header authenticates your
workload to the gateway. The gateway removes the Proxy-Authorization header
before it forwards the request, so the destination never receives your KSA
token. To authenticate to the destination, pass the destination's credentials
in the standard Authorization header, which the gateway forwards unchanged:
Authorization: Bearer DESTINATION_TOKEN
Replace DESTINATION_TOKEN with a token that the
destination accepts.
Trust the TLS inspection root CA
Because the gateway inspects TLS traffic, your agent workloads must trust the
root CA certificate that Agent Gateway for cross-cloud uses to issue
certificates. When the agent-governance-cross-cloud-controller controller
starts, it creates this CA and publishes the public root CA certificate in a
ConfigMap named air-root-ca in the geap-system namespace.
To configure your agent workloads to trust the root CA, do the following:
Copy the public root CA certificate into a
ConfigMapin each namespace where your agents run:CA_DATA="$(kubectl get configmap air-root-ca --namespace=geap-system \ -o jsonpath='{.data.ca\.crt}')" kubectl create configmap air-root-ca \ --namespace=AGENT_NAMESPACE \ --from-literal=ca.crt="${CA_DATA}" \ --dry-run=client -o yaml | kubectl apply -f -Replace
AGENT_NAMESPACEwith the namespace of your agent workload.Mount the
ConfigMapin your agent containers:spec: template: spec: containers: - name: AGENT_CONTAINER_NAME volumeMounts: - name: agent-gateway-ca mountPath: /etc/agent-gateway-ca readOnly: true volumes: - name: agent-gateway-ca configMap: name: air-root-caConfigure your workload to trust
/etc/agent-gateway-ca/ca.crt. How you do this depends on your language runtime and HTTP client library. Many runtimes and libraries read the following environment variables:spec: template: spec: containers: - name: AGENT_CONTAINER_NAME env: - name: SSL_CERT_FILE value: "/etc/agent-gateway-ca/ca.crt" - name: REQUESTS_CA_BUNDLE value: "/etc/agent-gateway-ca/ca.crt" - name: CURL_CA_BUNDLE value: "/etc/agent-gateway-ca/ca.crt" - name: NODE_EXTRA_CA_CERTS value: "/etc/agent-gateway-ca/ca.crt"
Trust private CAs for destinations
When the gateway forwards a request to a destination over TLS, it verifies the
destination's certificate. By default, the gateway trusts only public CAs. If a
destination uses a certificate that's issued by a private or self-signed CA,
add that CA to the gateway's trust bundle by modifying the gateway's
Deployment. The Deployment has the same name as the GCPAgentGateway
resource.
To add a private CA to the gateway's trust bundle, do the following:
Create a
ConfigMapthat contains the CA certificate in the gateway's namespace:kubectl create configmap DESTINATION_CA_CONFIGMAP \ --namespace=GATEWAY_NAMESPACE \ --from-file=ca.crt=CA_CERT_FILEReplace the following:
DESTINATION_CA_CONFIGMAP: a name for theConfigMap.GATEWAY_NAMESPACE: the namespace of theGCPAgentGatewayresource.CA_CERT_FILE: the path to the PEM-encoded CA certificate.
If the destination uses a certificate that's issued by your Kubernetes cluster's CA, skip this step and use the
kube-root-ca.crtConfigMapthat Kubernetes creates in each namespace.Get the image of the gateway container:
kubectl get deployment GATEWAY_NAME \ --namespace=GATEWAY_NAMESPACE \ -o jsonpath='{.spec.template.spec.containers[?(@.name=="agent-gateway")].image}'Replace
GATEWAY_NAMEwith the name of theGCPAgentGatewayresource.Edit the gateway's
Deploymentto add an init container that combines the default CA bundle with your CA, and mount the combined bundle in the gateway container. The init container uses the gateway image so that the combined bundle contains only the gateway's default CAs and your CA:spec: template: spec: initContainers: - name: init-ca-bundle image: GATEWAY_IMAGE command: ["/bin/sh", "-c"] args: - cat /etc/ssl/certs/ca-certificates.crt /etc/custom-ca/ca.crt > /var/run/envoy-certs/ca-certificates.crt volumeMounts: - name: custom-private-ca-vol mountPath: /etc/custom-ca readOnly: true - name: envoy-ca-bundle-vol mountPath: /var/run/envoy-certs containers: - name: agent-gateway volumeMounts: - name: envoy-ca-bundle-vol mountPath: /etc/ssl/certs/ca-certificates.crt subPath: ca-certificates.crt readOnly: true volumes: - name: custom-private-ca-vol configMap: name: DESTINATION_CA_CONFIGMAP - name: envoy-ca-bundle-vol emptyDir: {}Replace the following:
GATEWAY_IMAGE: the image from the previous step.DESTINATION_CA_CONFIGMAP: theConfigMapfrom the first step, orkube-root-ca.crt.
What's next
- Enforce cross-cloud governance policies
- Configure cross-cloud agent observability
- Learn more about Agent Registry