diff --git a/.travis.yml b/.travis.yml index 53f1d01f8c..c81d28675a 100644 --- a/.travis.yml +++ b/.travis.yml @@ -29,6 +29,7 @@ install: - pushd examples/example-hostname && mvn verify && popd - pushd examples/example-tls && ../gradlew clean build && popd - pushd examples/example-kotlin && ../gradlew build && popd + - pushd examples/example-xds && ../gradlew build && popd before_script: - test -z "$(git status --porcelain)" || (git status && echo Error Working directory is not clean. Forget to commit generated files? && false) diff --git a/RELEASING.md b/RELEASING.md index e476ab7e5b..3483676844 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -51,6 +51,7 @@ $ VERSION_FILES=( examples/example-kotlin/android/helloworld/app/build.gradle examples/example-tls/build.gradle examples/example-tls/pom.xml + examples/example-xds/build.gradle ) ``` diff --git a/buildscripts/kokoro/unix.sh b/buildscripts/kokoro/unix.sh index ec26500999..a559aa42ee 100755 --- a/buildscripts/kokoro/unix.sh +++ b/buildscripts/kokoro/unix.sh @@ -71,6 +71,9 @@ if [[ -z "${SKIP_TESTS:-}" ]]; then pushd examples/example-tls mvn clean verify --batch-mode popd + pushd examples/example-xds + ../gradlew build $GRADLE_FLAGS + popd # TODO(zpencer): also build the GAE examples fi diff --git a/examples/example-xds/README.md b/examples/example-xds/README.md new file mode 100644 index 0000000000..b01a9ecdac --- /dev/null +++ b/examples/example-xds/README.md @@ -0,0 +1,79 @@ +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](../../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.0 +``` + +2. Build the hello-world example server or the hostname example server. See + [the examples README](../README.md) or the + [hostname example README](../example-hostname/README.md). + +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.0" } +``` + + +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](https://github.com/grpc/proposal/pull/170) 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 +``` diff --git a/examples/example-xds/build.gradle b/examples/example-xds/build.gradle new file mode 100644 index 0000000000..b9b03a4a5a --- /dev/null +++ b/examples/example-xds/build.gradle @@ -0,0 +1,43 @@ +plugins { + id 'application' // Provide convenience executables for trying out the examples. + id 'java' +} + +repositories { + maven { // The google mirror is less flaky than mavenCentral() + url "https://maven-central.storage-download.googleapis.com/repos/central/data/" } + mavenCentral() + mavenLocal() +} + +sourceCompatibility = 1.7 +targetCompatibility = 1.7 + +// IMPORTANT: You probably want the non-SNAPSHOT version of gRPC. Make sure you +// are looking at a tagged version of the example and not "master"! + +// Feel free to delete the comment at the next line. It is just for safely +// updating the version in our release process. +def grpcVersion = '1.28.0-SNAPSHOT' // CURRENT_GRPC_VERSION + +dependencies { + // This example's client is the same as the helloworld client. We depend on the helloworld + // client's code here + implementation ':examples' + // The only change necessary is an extra runtime dependency on io.grpc:grpc-xds + runtimeOnly "io.grpc:grpc-xds:${grpcVersion}" +} + +startScripts.enabled = false + +task helloWorldClient(type: CreateStartScripts) { + mainClassName = 'io.grpc.examples.helloworld.HelloWorldClient' + applicationName = 'xds-hello-world-client' + outputDir = new File(project.buildDir, 'tmp') + classpath = startScripts.classpath +} + +applicationDistribution.into('bin') { + from(helloWorldClient) + fileMode = 0755 +} diff --git a/examples/example-xds/settings.gradle b/examples/example-xds/settings.gradle new file mode 100644 index 0000000000..9f46a95b6f --- /dev/null +++ b/examples/example-xds/settings.gradle @@ -0,0 +1,3 @@ +rootProject.name = 'example-xds' + +includeBuild '..'