or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

admin.mdadvanced.mdclient-server.mdcredentials-security.mderrors-status.mdhealth.mdindex.mdinterceptors.mdload-balancing.mdmetadata-context.mdname-resolution.mdobservability.mdreflection.mdstreaming.mdtesting.mdxds.md
tile.json

xds.mddocs/

xDS Support

This document covers xDS (discovery service) support in gRPC-Go for advanced service mesh and traffic management features.

Overview

xDS enables gRPC to integrate with service mesh control planes like Istio, providing dynamic configuration for load balancing, routing, security, and more.

xDS Resources

gRPC-Go supports the following xDS resources:

  • LDS (Listener Discovery Service): Server-side listener configuration
  • RDS (Route Discovery Service): HTTP route configuration
  • CDS (Cluster Discovery Service): Upstream cluster configuration
  • EDS (Endpoint Discovery Service): Endpoint/backend discovery

Client-Side xDS

xDS Dial Target

import (
    "google.golang.org/grpc"
    _ "google.golang.org/grpc/xds" // Import to enable xDS
)

// Use xds:/// scheme to enable xDS-based name resolution
conn, err := grpc.NewClient("xds:///myservice",
    grpc.WithTransportCredentials(creds))

xDS Credentials

import (
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"
    "google.golang.org/grpc/credentials/xds"
)

// xDS credentials with fallback
fallback, _ := credentials.NewClientTLSFromFile("ca.pem", "")
xdsCreds, err := xds.NewClientCredentials(xds.ClientOptions{
    FallbackCreds: fallback,
})

conn, err := grpc.NewClient("xds:///myservice",
    grpc.WithTransportCredentials(xdsCreds))

Server-Side xDS

xDS Server

import (
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"
    xdscreds "google.golang.org/grpc/credentials/xds"
    "google.golang.org/grpc/xds"
)

// Create xDS-enabled server
fallback, _ := credentials.NewServerTLSFromFile("server.pem", "server.key")
xdsCreds, err := xdscreds.NewServerCredentials(xdscreds.ServerOptions{
    FallbackCreds: fallback,
})

server, err := xds.NewGRPCServer(grpc.Creds(xdsCreds))
if err != nil {
    log.Fatal(err)
}

pb.RegisterMyServiceServer(server, &myServiceImpl{})

// Listen on xDS-configured address
lis, _ := net.Listen("tcp", ":50051")
server.Serve(lis)

Serving Mode

import "google.golang.org/grpc/connectivity"

type ServingMode int

const (
    // ServingModeStarting: server is starting up
    ServingModeStarting ServingMode = iota

    // ServingModeServing: server has configuration and serving RPCs
    ServingModeServing

    // ServingModeNotServing: server not accepting new connections
    ServingModeNotServing
)

xDS Bootstrap Configuration

gRPC reads xDS configuration from bootstrap file specified by GRPC_XDS_BOOTSTRAP environment variable:

{
  "xds_servers": [
    {
      "server_uri": "xds-control-plane:18000",
      "channel_creds": [{"type": "insecure"}],
      "server_features": ["xds_v3"]
    }
  ],
  "node": {
    "id": "my-service-node",
    "cluster": "my-cluster",
    "locality": {
      "zone": "us-central1-a"
    },
    "metadata": {
      "INSTANCE_IP": "10.0.0.1"
    }
  }
}

Features

Traffic Management

  • Weighted load balancing: Distribute traffic based on weights
  • Locality-aware load balancing: Prefer local endpoints
  • Circuit breaking: Limit concurrent requests
  • Outlier detection: Remove unhealthy endpoints
  • Retry policies: Automatic retry configuration

Security

  • mTLS: Mutual TLS with certificate rotation
  • RBAC: Role-based access control
  • Authorization: Fine-grained authorization policies

Observability

  • Metrics: Automatically exported metrics
  • Tracing: Distributed tracing integration
  • Logging: Enhanced logging for xDS operations

Best Practices

  1. Bootstrap configuration: Always provide valid bootstrap file
  2. Fallback credentials: Configure fallback for non-xDS scenarios
  3. Graceful degradation: Handle xDS unavailability gracefully
  4. Testing: Test both with and without xDS control plane
  5. Monitoring: Monitor xDS connection health

Environment Variables

  • GRPC_XDS_BOOTSTRAP: Path to xDS bootstrap configuration file
  • GRPC_XDS_BOOTSTRAP_CONFIG: xDS bootstrap configuration as JSON string
  • GRPC_XDS_EXPERIMENTAL_SECURITY_SUPPORT: Enable xDS security features

For detailed xDS configuration and features, see: gRPC xDS Documentation