doc: add ALTS example readme

examples/example-alts/example-alts/README.md

@@ -0,0 +1,62 @@
+gRPC ALTS Example
+==================
+
+This example suite shows secure communication between a Hello World 
+client and a Hello World server authenticated by Google's Application Layer 
+Transport Security (ALTS). For more information about ALTS itself, see 
+[ALTS Whiltepaper](https://cloud.google.com/security/encryption-in-transit/application-layer-transport-security) or [grpc.io tutorial](https://grpc.io/docs/languages/java/alts/).
+
+In the gRPC-java context, for both the ALTS client and the ALTS server, a 
+`gRPC-client`-backed handshaker is installed in their channel protocol 
+negotiator. Once a connection is established between the ALTS Client and the 
+ALTS Server, the protocol negotiators will trigger the ALTS handshaking process, 
+which fires multiple rounds of gRPC communication between multiple parties, 
+including the ALTS client, the ALTS server and a pre-deployed handshaker 
+server. At the end, they will reach a shared secret to be used to encrypt the 
+following RPC calls.
+
+The example runs successfully in a GCP environment 
+out-of-the-box, and can be further configured to run in any environments
+with a pre-deployed handshaker service.
+
+
+### Build the example
+
+To build the example,
+
+1. **[Install gRPC Java library SNAPSHOT locally, including code generation plugin](../../COMPILING.md) (Only need this step for non-released versions, e.g. master HEAD).**
+
+2. Run in this directory:
+```
+$ ../gradlew installDist
+```
+
+This creates the scripts `hello-world-alts-server`, `hello-world-alts-client`,
+in the
+`build/install/example-atls/bin/` directory that run the example.
+
+### Run the example in a GCP environment
+ALTS handshake protocol negotiation requires a separate handshaker service. It is
+available in the GCP environment, so we can run the application directly:
+
+```bash
+# Run the server:
+./build/install/example-alts/bin/hello-world-alts-server
+
+```
+
+In another terminal run the client
+
+```
+./build/install/example-alts/bin/hello-world-alts-client
+```
+
+That's it!
+
+### Test the example in a non-GCP environment
+
+To run the example in a non-GCP environment, you should first deploy a 
+[handshaker service](https://github.com/grpc/grpc/blob/7e367da22a137e2e7caeae8342c239a91434ba50/src/proto/grpc/gcp/handshaker.proto#L224-L234) 
+and know its name. You should configure both the [ALTS client](https://github.com/grpc/grpc-java/blob/master/alts/src/main/java/io/grpc/alts/AltsChannelBuilder.java#L63-L76) 
+and [ALTS server](https://github.com/grpc/grpc-java/blob/master/alts/src/main/java/io/grpc/alts/AltsServerCredentials.java#L55-L72)
+to use the known handshaker server for testing. See [example](https://github.com/grpc/grpc-java/blob/master/interop-testing/src/test/java/io/grpc/testing/integration/AltsHandshakerTest.java#L45).