Endpoint universe domain guide

docs/endpoint.md

@@ -0,0 +1,110 @@
+# Client Library Endpoint
+Client libraries will automatically resolve an endpoint to use. The default resolved endpoint
+will be to Google servers (i.e. `https://{serviceName}.googleapis.com:443`).
+
+## Anatomy of an Endpoint
+Using the default Java-Speech endpoint as an example: `https://speech.googleapis.com:443`:
+
+| Scheme   	| Service Name 	| Universe Domain 	| Port 	|
+|----------	|--------------	|-----------------	|------	|
+| https:// 	| speech       	| googleapis.com  	| 443  	|
+
+Default values for client libraries:
+- Scheme: https://
+- [Universe Domain](universe_domain.md): googleapis.com
+- Port: 443
+
+## Configuring a Specific Endpoint
+There are two ways to configure the endpoint in Java Client Libraries. Configuring the endpoint
+will update the entire endpoint value. Currently, you cannot change the individual sections of the
+endpoint (i.e. set the scheme or port value individually). 
+
+Note: You may configure the [Universe Domain](universe_domain.md) in a separate Setter.
+
+### Set through the generated {Service}Settings
+The following example is using Java-KMS v2.42.0 as an example:
+
+1. Set the endpoint in {Service}Settings.Builder and create the Settings object
+```java
+String endpoint = "settingsendpoint.com";
+KeyManagementServiceSettings keyManagementServiceSettings =
+  KeyManagementServiceSettings.newBuilder()
+    .setEndpoint(endpoint)
+    .build();
+```
+2. Create the client with the Settings
+```java
+try (KeyManagementServiceClient keyManagementServiceClient =
+  KeyManagementServiceClient.create(keyManagementServiceSettings)) {
+```
+The endpoint will be resolved to `settingsendpoint.com`.
+
+Note: This is the recommend way to set the endpoint.
+
+### Set through the Instantiating{Transport}ChannelProvider
+The following example is using Java-KMS v2.42.0 as an example:
+
+1. Create the transport specific TransportChannelProvider
+```java
+String endpoint = "transportendpoint.com";
+InstantiatingGrpcChannelProvider instantiatingGrpcChannelProvider =
+    InstantiatingGrpcChannelProvider.newBuilder()
+    .setEndpoint(endpoint)
+    // ... Other required configurations
+    .build();
+```
+2. Pass the TransportChannelProvider to the Settings
+```java
+KeyManagementServiceSettings keyManagementServiceSettings =
+  KeyManagementServiceSettings.newBuilder()
+    .setTransportChannelProvider(instantiatingGrpcChannelProvider)
+    .build();
+```
+3. Create the client with the Settings
+```java
+try (KeyManagementServiceClient keyManagementServiceClient =
+  KeyManagementServiceClient.create(keyManagementServiceSettings)) {
+```
+The endpoint will be resolved to `transportendpoint.com`.
+
+### Set through both ways
+If you are setting an endpoint via both methods above, like:
+```java
+String endpoint1 = "transportEndpoint.com";
+    InstantiatingGrpcChannelProvider instantiatingGrpcChannelProvider =
+    InstantiatingGrpcChannelProvider.newBuilder()
+    .setEndpoint(endpoint1)
+    // ... Other required configurations
+    .build();
+
+String endpoint2 = "settingsEndpoint.com";
+KeyManagementServiceSettings keyManagementServiceSettings =
+  KeyManagementServiceSettings.newBuilder()
+    .setEndpoint(endpoint2)
+    .setTransportChannelProvider(instantiatingGrpcChannelProvider)
+    .build();
+```
+The endpoint will be resolved to `transportendpoint.com`.
+
+### Endpoint Hierarchy
+1. If set in the TransportChannelProvider, use this endpoint. Otherwise, go to the next step.
+2. If set via the ClientSettings, use this endpoint. Otherwise, go to the next step.
+3. Use the default endpoint (Default endpoint will hit Google servers)
+
+### How can I confirm the endpoint the library is using
+Assuming you have configured a custom endpoint, like: 
+```java
+String endpoint = "...";
+KeyManagementServiceSettings keyManagementServiceSettings =
+  KeyManagementServiceSettings.newBuilder()
+    .setEndpoint(endpoint)
+    .build();
+```
+
+You can retrieve the endpoint from the Setting's `getEndpoint()` method. This will return
+the resolved endpoint back.
+
+## When should I specify my custom endpoint
+There are a few use cases:
+1. Service offers [regional endpoints](https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library)
+2. You do not want to use https (i.e. local testing)

docs/universe_domain.md

@@ -0,0 +1,78 @@
+# Universe Domain
+See [Anatomy of an Endpoint](endpoint.md#anatomy-of-an-endpoint) for more information
+about how the Universe Domain is used as part of an endpoint.
+
+Universe Domain default value: `googleapis.com`. This is known as the Google Default
+Universe (GDU). If the Universe Domain value is not specified in the settings, the GDU
+value is the one used.
+
+## Configuring a Specific Universe Domain
+There are two ways to configure the endpoint in Java Client Libraries.
+
+### Set through the generated {Service}Settings
+Configuring the Universe Domain is done via the generated {Service}Settings. The following example
+is using Java-KMS v2.42.0 as an example:
+
+1. Set the endpoint in {Service}Settings.Builder and create the Settings object
+```java
+String universeDomain = "myuniversedomain.com";
+KeyManagementServiceSettings keyManagementServiceSettings =
+  KeyManagementServiceSettings.newBuilder()
+    .setUniverseDomain(universeDomain).build();
+```
+2. Create the client with the Settings
+```java
+try (KeyManagementServiceClient keyManagementServiceClient =
+  KeyManagementServiceClient.create(keyManagementServiceSettings)) {
+```
+
+With this configuration, the client library will resolve the endpoint to be:
+`https://cloudkms.myuniversedomain.com:443`.
+
+### Set through an Environment Variable
+Set the Universe Domain to the `GOOGLE_CLOUD_UNIVERSE_DOMAIN`. Java client libraries will attempt
+to read this value.
+
+### Universe Domain Hierarchy
+1. If set in the ClientSettings, use this value. Otherwise, go to the next step.
+2. If set via the Environment Variable, use this value. Otherwise, go to the next step.
+3. Use the GDU value
+
+### Configuring a Specific Universe Domain and a Custom Endpoint
+The following example is using Java-KMS v2.42.0 as an example:
+
+1. Set the endpoint in {Service}Settings.Builder and create the Settings object
+```java
+String endpoint = "settingsendpoint.com";
+String universeDomain = "universeDomain.com";
+KeyManagementServiceSettings keyManagementServiceSettings =
+  KeyManagementServiceSettings.newBuilder()
+    .setEndpoint(endpoint)
+    .setUniverseDomain(universeDomain)
+    .build();
+```
+
+- The resolved endpoint is: `settingsendpoint.com`
+- The resolved Universe Domain is: `universeDomain.com`
+
+The custom set endpoint triumphs over other configurations.
+
+### How can I confirm the universe domain the library is using?
+Assuming you have configured a custom endpoint, like:
+```java
+String universeDomain = "...";
+KeyManagementServiceSettings keyManagementServiceSettings =
+  KeyManagementServiceSettings.newBuilder()
+    .setUniverseDomain(universeDomain)
+    .build();
+```
+
+You can retrieve the endpoint from the Setting's `getUniverseDomain()` method. This will return
+the resolved Universe Domain back.
+
+## Compatibility with ...
+### ... DirectPath
+Currently, DirectPath code only works in the GDU
+### ... GDC-H
+Universe Domain is incompatible with GDC-H. Do not set the Universe Domain if you are using GDC-H
+Credentials.