1gRPC XDS Example 2================ 3 4The XDS example consists of a Hello World client and a Hello World server capable of 5being configured with the XDS management protocol. Out-of-the-box the client 6behaves the same the hello-world version and the server behaves similar to the 7example-hostname but with a required dependency on xDS. 8 9__XDS support is incomplete and experimental, with limited compatibility. It 10will be very hard to produce a working environment just by this example. Please 11refer to documentation specific for your XDS management server and 12environment.__ 13 14### Build the example 15 16Build the XDS hello-world example client & server. From the `grpc-java/examples/examples-xds` 17directory: 18``` 19$ ../gradlew installDist 20``` 21 22This creates the scripts `build/install/example-xds/bin/xds-hello-world-client` and 23`build/install/example-xds/bin/xds-hello-world-server`. 24 25### Run the example without using XDS Credentials 26 27To use XDS, you should first deploy the XDS management server in your deployment environment 28and know its name. You need to set the `GRPC_XDS_BOOTSTRAP` environment variable (preferred) or if that is not set then 29the `io.grpc.xds.bootstrap` java system property to point to the gRPC XDS bootstrap file (see 30[gRFC A27](https://github.com/grpc/proposal/blob/master/A27-xds-global-load-balancing.md#xdsclient-and-bootstrap-file) for the 31bootstrap format). This is needed by both `build/install/example-xds/bin/xds-hello-world-client` 32and `build/install/example-xds/bin/xds-hello-world-server`. 33 341. To start the XDS-enabled example server on its default port of 50051, run: 35``` 36$ export GRPC_XDS_BOOTSTRAP=/path/to/bootstrap.json 37$ ./build/install/example-xds/bin/xds-hello-world-server 38``` 39 402. In a different terminal window, run the XDS-enabled example client: 41``` 42$ export GRPC_XDS_BOOTSTRAP=/path/to/bootstrap.json 43$ ./build/install/example-xds/bin/xds-hello-world-client "xds world" xds:///yourServersName 44``` 45The first command line argument (`xds world`) is the name you wish to include in 46the greeting request to the server and the second argument 47(`xds:///yourServersName`) is the target to connect to using the `xds:` target 48scheme. 49 50### Run the example with xDS Credentials 51 52The above example used plaintext (insecure) credentials as explicitly provided by the client and server 53code. We will now demonstrate how the code can authorize use of xDS provided credentials by using 54`XdsChannelCredentials` on the client side and using `XdsServerCredentials` on the server side. 55This code is enabled by providing an additional command line argument. 56 571. On the server side, add `--xds-creds` on the command line to authorize use of xDS security: 58``` 59$ export GRPC_XDS_BOOTSTRAP=/path/to/bootstrap.json 60$ ./build/install/example-xds/bin/xds-hello-world-server --xds-creds 61``` 62 632. Similarly, add `--xds-creds` on the command line when you run the xDS client: 64``` 65$ export GRPC_XDS_BOOTSTRAP=/path/to/bootstrap.json 66$ ./build/install/example-xds/bin/xds-hello-world-client --xds-creds "xds world" xds:///yourServersName 67``` 68 69In this case, if the xDS management server is configured to provide mTLS credentials (for example) to the client and 70server, then they will use these credentials to create an mTLS channel to authenticate and encrypt. 71