From 44cb566fb3e14fe64196bb6fc63af928f15eccf3 Mon Sep 17 00:00:00 2001 From: Lawrence Qiu Date: Fri, 29 Mar 2024 19:40:56 -0400 Subject: [PATCH 1/4] docs: Add guide for configuring an endpoint --- docs/endpoint.md | 91 +++++++++++++++++++++++++++++++++++++++++ docs/universe_domain.md | 0 2 files changed, 91 insertions(+) create mode 100644 docs/endpoint.md create mode 100644 docs/universe_domain.md diff --git a/docs/endpoint.md b/docs/endpoint.md new file mode 100644 index 000000000000..ac3da421ff7c --- /dev/null +++ b/docs/endpoint.md @@ -0,0 +1,91 @@ +# Client Library Endpoint +Client libraries will automatically resolve an endpoint for the client to use. +The default endpoint will attempt to connect to Google servers. + +## Anatomy of an Endpoint +Using a sample Java-Speech endpoint as an example: `https://speech.googleapis.com:443`: + +| Scheme | Service Name | Universe Domain | Port | +|---------- |-------------- |----------------- |------ | +| https:// | speech | googleapis.com | 443 | + +Default Values: +- 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. + +### 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 = "mycoolendpoint.com"; +KeyManagementServiceSettings keyManagementServiceSettings = + KeyManagementServiceSettings.newBuilder().setEndpoint(endpoint).build(); +``` +2. Create the client with the Settings +```java +try (KeyManagementServiceClient keyManagementServiceClient = + KeyManagementServiceClient.create(keyManagementServiceSettings)) { +``` + +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 = "mycoolendpoint.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)) { +``` + +### 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(endpoint2) + // ... Other required configurations + .build(); + +String endpoint2 = "settingsEndpoint.com"; +KeyManagementServiceSettings keyManagementServiceSettings = + KeyManagementServiceSettings.newBuilder() + .setEndpoint(endpoint1) + .setTransportChannelProvider(instantiatingGrpcChannelProvider) + .build(); +``` + +The endpoint that the client library uses will be the from the TransportChannelProvider. +If set, the endpoint passed in the TransportChannelProvider is used. + +### 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 (Request will hit Google servers) + +## 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) \ No newline at end of file diff --git a/docs/universe_domain.md b/docs/universe_domain.md new file mode 100644 index 000000000000..e69de29bb2d1 From 9ce8ce827871f8337e59c298c7890165b45e6fca Mon Sep 17 00:00:00 2001 From: Lawrence Qiu Date: Fri, 29 Mar 2024 19:50:29 -0400 Subject: [PATCH 2/4] docs: Add Universe Domain section --- docs/endpoint.md | 13 +++++++++++++ docs/universe_domain.md | 36 ++++++++++++++++++++++++++++++++++++ 2 files changed, 49 insertions(+) diff --git a/docs/endpoint.md b/docs/endpoint.md index ac3da421ff7c..972a88024536 100644 --- a/docs/endpoint.md +++ b/docs/endpoint.md @@ -85,6 +85,19 @@ If set, the endpoint passed in the TransportChannelProvider is used. 2. If set via the ClientSettings, use this endpoint. Otherwise, go to the next step. 3. Use the default endpoint (Request 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) diff --git a/docs/universe_domain.md b/docs/universe_domain.md index e69de29bb2d1..130290bcf4ad 100644 --- a/docs/universe_domain.md +++ b/docs/universe_domain.md @@ -0,0 +1,36 @@ +# 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. + +## Configuring a Specific Universe Domain +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`. + +### 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. \ No newline at end of file From adbc689a2ac238ab614e75c4025715d09e038e04 Mon Sep 17 00:00:00 2001 From: Lawrence Qiu Date: Fri, 29 Mar 2024 19:52:16 -0400 Subject: [PATCH 3/4] docs: Clean up endpoint guide --- docs/endpoint.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/endpoint.md b/docs/endpoint.md index 972a88024536..bae78a65af23 100644 --- a/docs/endpoint.md +++ b/docs/endpoint.md @@ -3,13 +3,13 @@ Client libraries will automatically resolve an endpoint for the client to use. The default endpoint will attempt to connect to Google servers. ## Anatomy of an Endpoint -Using a sample Java-Speech endpoint as an example: `https://speech.googleapis.com:443`: +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: +Default Values for client libraries: - Scheme: https:// - [Universe Domain](universe_domain.md): googleapis.com - Port: 443 @@ -24,7 +24,9 @@ The following example is using Java-KMS v2.42.0 as an example: ```java String endpoint = "mycoolendpoint.com"; KeyManagementServiceSettings keyManagementServiceSettings = - KeyManagementServiceSettings.newBuilder().setEndpoint(endpoint).build(); + KeyManagementServiceSettings.newBuilder() + .setEndpoint(endpoint) + .build(); ``` 2. Create the client with the Settings ```java @@ -83,9 +85,9 @@ If set, the endpoint passed in the TransportChannelProvider is used. ### 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 (Request will hit Google servers) +3. Use the default endpoint (Default endpoint will hit Google servers) -### How can I confirm the endpoint the library is using? +### How can I confirm the endpoint the library is using Assuming you have configured a custom endpoint, like: ```java String endpoint = "..."; From 5da3db68e8d968e9185db88f164da7472c5a55be Mon Sep 17 00:00:00 2001 From: Lawrence Qiu Date: Mon, 1 Apr 2024 11:58:12 -0400 Subject: [PATCH 4/4] docs: Clean up Universe Domain guide --- docs/endpoint.md | 28 +++++++++++++++----------- docs/universe_domain.md | 44 ++++++++++++++++++++++++++++++++++++++++- 2 files changed, 59 insertions(+), 13 deletions(-) diff --git a/docs/endpoint.md b/docs/endpoint.md index bae78a65af23..e430fe54141f 100644 --- a/docs/endpoint.md +++ b/docs/endpoint.md @@ -1,6 +1,6 @@ # Client Library Endpoint -Client libraries will automatically resolve an endpoint for the client to use. -The default endpoint will attempt to connect to Google servers. +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`: @@ -9,20 +9,24 @@ Using the default Java-Speech endpoint as an example: `https://speech.googleapis |---------- |-------------- |----------------- |------ | | https:// | speech | googleapis.com | 443 | -Default Values for client libraries: +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. +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 = "mycoolendpoint.com"; +String endpoint = "settingsendpoint.com"; KeyManagementServiceSettings keyManagementServiceSettings = KeyManagementServiceSettings.newBuilder() .setEndpoint(endpoint) @@ -33,15 +37,16 @@ KeyManagementServiceSettings keyManagementServiceSettings = try (KeyManagementServiceClient keyManagementServiceClient = KeyManagementServiceClient.create(keyManagementServiceSettings)) { ``` +The endpoint will be resolved to `settingsendpoint.com`. -This is the recommend way to set the endpoint. +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 = "mycoolendpoint.com"; +String endpoint = "transportendpoint.com"; InstantiatingGrpcChannelProvider instantiatingGrpcChannelProvider = InstantiatingGrpcChannelProvider.newBuilder() .setEndpoint(endpoint) @@ -60,6 +65,7 @@ KeyManagementServiceSettings keyManagementServiceSettings = 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: @@ -67,20 +73,18 @@ If you are setting an endpoint via both methods above, like: String endpoint1 = "transportEndpoint.com"; InstantiatingGrpcChannelProvider instantiatingGrpcChannelProvider = InstantiatingGrpcChannelProvider.newBuilder() - .setEndpoint(endpoint2) + .setEndpoint(endpoint1) // ... Other required configurations .build(); String endpoint2 = "settingsEndpoint.com"; KeyManagementServiceSettings keyManagementServiceSettings = KeyManagementServiceSettings.newBuilder() - .setEndpoint(endpoint1) + .setEndpoint(endpoint2) .setTransportChannelProvider(instantiatingGrpcChannelProvider) .build(); ``` - -The endpoint that the client library uses will be the from the TransportChannelProvider. -If set, the endpoint passed in the TransportChannelProvider is used. +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. diff --git a/docs/universe_domain.md b/docs/universe_domain.md index 130290bcf4ad..bfc9f4d37f45 100644 --- a/docs/universe_domain.md +++ b/docs/universe_domain.md @@ -2,7 +2,14 @@ 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: @@ -22,6 +29,34 @@ try (KeyManagementServiceClient keyManagementServiceClient = 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 @@ -33,4 +68,11 @@ KeyManagementServiceSettings keyManagementServiceSettings = ``` You can retrieve the endpoint from the Setting's `getUniverseDomain()` method. This will return -the resolved Universe Domain back. \ No newline at end of file +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. \ No newline at end of file