gRPC XDS Example

The XDS example is a Hello World client capable of being configured with the XDS management protocol. Out-of-the-box it behaves the same as hello world client.

XDS support is incomplete and experimental, with limited compatibility. It will be very hard to produce a working enviornment just by this example. Please refer to documentation specific for your XDS management server and environment.

The example requires grpc-xds, but grpc-xds is not currently being published. You will thus need to build it yourself. This should guide you, but if you encounter issues please consult COMPILING.md.

Build the example

1. The server does not use XDS, so recent releases work fine. Building using recent releases is much easier, so check out the most recent release tag:

$ git checkout v1.27.2

2. Build the hello-world example server or the hostname example server. See the examples README or the hostname example README.

3. Since XDS is still developing rapidly, XDS-using code should be built from master:

$ git checkout master

4. Building protoc-gen-grpc-java (the protoc plugin) requires a bit of work and isn't necessary. So change the hello-world example to use the last released version of the plugin. In grpc-java/examples/build.gradle, change:

        grpc { artifact = "io.grpc:protoc-gen-grpc-java:${grpcVersion}" }

To:

        grpc { artifact = "io.grpc:protoc-gen-grpc-java:1.27.2" }

5. Build this client. From the grpc-java/examples/examples-xds directory:

$ ../gradlew -PskipCodegen=true -PskipAndroid=true --include-build ../.. installDist

This creates the script build/install/example-xds/bin/xds-hello-world-client that runs the example.

To start the server, run:

$ ../build/install/hostname/bin/hello-world-server
$ # or
$ ../example-hostname/build/install/hostname/bin/hostname-server

And in a different terminal window run this client:

$ ./build/install/example-xds/bin/xds-hello-world-client

However, that didn't use XDS! To use XDS we assume you have deployed the server in your deployment environment and know its name. You need to set the GRPC_XDS_BOOTSTRAP environment variable to point to a gRPC XDS bootstrap file (see gRFC A27 for the bootstrap format). Then use the xds-experimental: target scheme during channel creation.

$ export GRPC_XDS_BOOTSTRAP=/path/to/bootstrap.json
$ ./build/install/example-xds/bin/xds-hello-world-client "XDS world" xds-experimental:///yourServersName