The XDS example consists of a Hello World client and a Hello World server capable of being configured with the XDS management protocol. Out-of-the-box they behave the same as their hello-world version.
XDS support is incomplete and experimental, with limited compatibility. It will be very hard to produce a working environment just by this example. Please refer to documentation specific for your XDS management server and environment.
Build the XDS hello-world example client & server. From the grpc-java/examples/examples-xds
directory:
$ ../gradlew installDist
This creates the scripts build/install/example-xds/bin/hello-world-client-xds
and
build/install/example-xds/bin/hello-world-server-xds
.
To use XDS, you should first deploy the XDS management server in your deployment environment
and know its name. You need to set the GRPC_XDS_BOOTSTRAP
environment variable (preferred) or if that is not set then
the io.grpc.xds.bootstrap
java system property to point to the gRPC XDS bootstrap file (see
gRFC A27 for the
bootstrap format). This is needed by both build/install/example-xds/bin/hello-world-client-xds
and build/install/example-xds/bin/hello-world-server-xds
.
- To start the XDS-enabled example server, run:
$ export GRPC_XDS_BOOTSTRAP=/path/to/bootstrap.json
$ ./build/install/example-xds/bin/hello-world-server-xds 8000 my-test-xds-server
The first command line argument is the port to listen on (8000
) and the second argument is a string
id (my-test-xds-server
) to be included in the greeting response to the client.
- In a different terminal window, run the XDS-enabled example client:
$ export GRPC_XDS_BOOTSTRAP=/path/to/bootstrap.json
$ ./build/install/example-xds/bin/xds-hello-world-client xds:///yourServersName:8000 my-test-xds-client
The first command line argument (xds:///yourServersName:8000
) is the target to connect to using the
xds:
target scheme and the second argument (my-test-xds-client
) is the name you wish to include in
the greeting request to the server.
The above example used plaintext (insecure) credentials as explicitly provided by the client and server
code. We will now demonstrate how the code can authorize use of xDS provided credentials by using
XdsChannelCredentials
on the client side and using XdsServerBuilder.useXdsSecurityWithPlaintextFallback()
on the server side. This code is enabled by providing an additional command line argument.
- On the server side, add
--secure
on the command line to authorize use of xDS security:
$ export GRPC_XDS_BOOTSTRAP=/path/to/bootstrap.json
$ ./build/install/example-xds/bin/hello-world-server-xds 8000 my-test-xds-server --secure
- Similarly, add
--secure
on the command line when you run the xDS client:
$ export GRPC_XDS_BOOTSTRAP=/path/to/bootstrap.json
$ ./build/install/example-xds/bin/hello-world-client-xds xds:///yourServersName:8000 my-test-xds-client --secure
In this case, if the xDS management server is configured to provide mTLS credentials (for example) to the client and server, then they will use these credentials to create an mTLS channel to authenticate and encrypt.