For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Enable TLS encryption for the control plane xDS gRPC server communications.

Enable server-side TLS encryption for the xDS gRPC server in the agentgateway control plane. For more information about the server, see the Architecture docs.

The control plane serves xDS over TLS by default (controller.xds.mode: tls) and self-manages the certificate: it generates and rotates an internal CA and serving certificate, and propagates the CA bundle to the agentgateway data plane proxies. No cert-manager setup or pre-created secret is required. Optionally, you can bring your own certificate authority.

Before you begin

Step 1: (Optional) Bring your own certificate authority

The control plane self-manages the xDS certificate, so cert-manager is not required and you can skip to Step 2. To use your own certificate authority instead of the self-signed one that the control plane generates, provide a CA key pair (certificate and key) in the agentgateway-xds-cert secret in the control plane namespace. You might use a provider such as cert-manager to automate issuance and rotation.

Step 2: Update the control plane to use TLS

Upgrade agentgateway with TLS enabled for the controller. For complete steps, review the Upgrade guide.

1. Set your version of agentgateway in an environment variable, such as the latest patch version (1.6.0-alpha.1).

   export NEW_VERSION=1.6.0-alpha.1

2. Get the Helm values file for your current version.

   helm get values agentgateway -n agentgateway-system -o yaml > values.yaml
   open values.yaml

3. Add the following values to the Helm values file to enable TLS for the xDS gRPC server.

   controller:
     xds:
       mode: tls

4. Upgrade your Helm installation.

   helm upgrade -i -n agentgateway-system agentgateway oci://cr.agentgateway.dev/charts/agentgateway \
     -f values.yaml \
     --version $NEW_VERSION 

5. Confirm that the agentgateway control plane is up and running.

   kubectl get pods -n agentgateway-system

Step 3: Verify the TLS connection

Now that the control plane is up and running, verify the TLS connection.

1. Port-forward the control plane service on port 9977.

   kubectl port-forward -n agentgateway-system svc/agentgateway 9978

2. Send a request to the control plane in plaintext without TLS authentication. You get back an authentication failed error.

   grpcurl -plaintext localhost:9978 list

   Example output:

   Failed to list services: rpc error: code = Unknown desc = authentication failed: [Authenticator KubeJWTAuthenticator: target JWT extraction error: no HTTP authorization header exists]

3. Port-forward the control plane deployment on port 9092.

   kubectl port-forward -n agentgateway-system deploy/agentgateway 9092

4. Send a request to the metrics endpoint to check for xds_auth metrics.

   curl localhost:9092/metrics | grep xds_auth

   Example output:

   # HELP kgateway_xds_auth_rq_failure_total Total number of failed xDS auth requests
   # TYPE kgateway_xds_auth_rq_failure_total counter
   kgateway_xds_auth_rq_failure_total 2
   # HELP kgateway_xds_auth_rq_success_total Total number of successful xDS auth requests
   # TYPE kgateway_xds_auth_rq_success_total counter
   kgateway_xds_auth_rq_success_total 1
   # HELP kgateway_xds_auth_rq_total Total number of xDS auth requests
   # TYPE kgateway_xds_auth_rq_total counter
   kgateway_xds_auth_rq_total 3

5. Check the certificate metrics to monitor the rotation of the xDS serving certificate. Because the control plane self-manages this certificate, these metrics are how you confirm that rotation keeps happening, and alert if it stops.

   curl -s localhost:9092/metrics | grep xds_cert

   Example output:

   # HELP agentgateway_xds_cert_expiry_seconds Expiry timestamp (Unix seconds) of the current xDS serving certificate
   # TYPE agentgateway_xds_cert_expiry_seconds gauge
   agentgateway_xds_cert_expiry_seconds 1.7895646e+09
   # HELP agentgateway_xds_cert_rotation_total Total number of successful xDS certificate rotations
   # TYPE agentgateway_xds_cert_rotation_total counter
   agentgateway_xds_cert_rotation_total 1

   Review the following metrics to monitor certificate health.

   Metric	What to watch for
   agentgateway_xds_cert_expiry_seconds	Alert when the value approaches the current time, such as agentgateway_xds_cert_expiry_seconds - time() < 21600, which is 6 hours of remaining lifetime.
   agentgateway_xds_cert_rotation_total	A counter that increases each time the certificate is rotated successfully.
   agentgateway_xds_cert_rotation_errors_total	A counter that increases each time a rotation fails. Any increase means the certificate is not being renewed. This metric appears only after the first failure.