Skip to content

Commit d6162cc

Browse files
lqiu96lqiu96
committed
docs: Create a guide for endpoint and universe domain
1 parent 2d717d7 commit d6162cc

2 files changed

Lines changed: 204 additions & 0 deletions

File tree

‎docs/endpoint.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Client Library Endpoint
2+
Google Client libraries will automatically resolve an endpoint to connect to Google Cloud services.
3+
The default resolved endpoint will be to Google servers (i.e. `https://speech.googleapis.com:443`).
4+
5+
## Anatomy of an Endpoint
6+
Using the default java-speech endpoint as an example: `https://speech.googleapis.com:443`:
7+
8+
| Scheme | Service Name | Universe Domain | Port |
9+
|---------- |-------------- |----------------- |------ |
10+
| https:// | speech | googleapis.com | 443 |
11+
12+
Default values for Java SDK Client libraries:
13+
- Scheme: https://
14+
- [Universe Domain](universe_domain.md): googleapis.com
15+
- Port: 443
16+
17+
Note: Service Name does not have a default value and is different for each cloud service.
18+
19+
## Configuring a Specific Endpoint
20+
There are two ways to configure the endpoint in Java Cloud Client Libraries: ServiceSettings and
21+
TransportChannelProvider.
22+
23+
### (Recommended) Set through the generated {Service}Settings
24+
The following example is using Java-KMS v2.42.0 as an example:
25+
26+
1. Set the endpoint in {Service}Settings.Builder and create the Settings object
27+
```java
28+
String endpoint = "settingsEndpoint.com";
29+
KeyManagementServiceSettings keyManagementServiceSettings =
30+
KeyManagementServiceSettings.newBuilder()
31+
.setEndpoint(endpoint)
32+
.build();
33+
```
34+
2. Create the client with the Settings
35+
```java
36+
try (KeyManagementServiceClient keyManagementServiceClient =
37+
KeyManagementServiceClient.create(keyManagementServiceSettings)) {
38+
...
39+
}
40+
```
41+
The endpoint will be resolved to `settingsEndpoint.com`.
42+
43+
### Set through the Instantiating{Transport}ChannelProvider
44+
The following example is using Java-KMS v2.42.0 as an example:
45+
46+
1. Create the transport specific TransportChannelProvider
47+
```java
48+
String endpoint = "transportEndpoint.com";
49+
InstantiatingGrpcChannelProvider instantiatingGrpcChannelProvider =
50+
InstantiatingGrpcChannelProvider.newBuilder()
51+
.setEndpoint(endpoint)
52+
// ... Other required configurations
53+
.build();
54+
```
55+
2. Pass the TransportChannelProvider to the Settings
56+
```java
57+
KeyManagementServiceSettings keyManagementServiceSettings =
58+
KeyManagementServiceSettings.newBuilder()
59+
.setTransportChannelProvider(instantiatingGrpcChannelProvider)
60+
.build();
61+
```
62+
3. Create the client with the Settings
63+
```java
64+
try (KeyManagementServiceClient keyManagementServiceClient =
65+
KeyManagementServiceClient.create(keyManagementServiceSettings)) {
66+
...
67+
}
68+
```
69+
The endpoint will be resolved to `transportEndpoint.com`.
70+
71+
### Set through ServiceSettings and TransportChannelProvider
72+
If you are setting an endpoint via both methods above, like:
73+
```java
74+
String endpoint1 = "transportEndpoint.com";
75+
InstantiatingGrpcChannelProvider instantiatingGrpcChannelProvider =
76+
InstantiatingGrpcChannelProvider.newBuilder()
77+
.setEndpoint(endpoint1)
78+
// ... Other required configurations
79+
.build();
80+
81+
String endpoint2 = "settingsEndpoint.com";
82+
KeyManagementServiceSettings keyManagementServiceSettings =
83+
KeyManagementServiceSettings.newBuilder()
84+
.setEndpoint(endpoint2)
85+
.setTransportChannelProvider(instantiatingGrpcChannelProvider)
86+
.build();
87+
```
88+
The endpoint will be resolved to `transportEndpoint.com`.
89+
90+
### Endpoint Hierarchy
91+
1. If set in the TransportChannelProvider, use this value. Otherwise, go to the next step.
92+
2. If set via the ClientSettings, use this value. Otherwise, go to the next step.
93+
3. Use the default endpoint (i.e. `https://{serviceName}.googleapis.com:443`)
94+
95+
#### How can I check which endpoint the client library is using
96+
Assuming you have configured a custom endpoint, like:
97+
```java
98+
String endpoint = "...";
99+
KeyManagementServiceSettings keyManagementServiceSettings =
100+
KeyManagementServiceSettings.newBuilder()
101+
.setEndpoint(endpoint)
102+
.build();
103+
try (KeyManagementServiceClient keyManagementServiceClient =
104+
KeyManagementServiceClient.create(keyManagementServiceSettings)) {
105+
...
106+
}
107+
```
108+
109+
Retrieve the resolved endpoint from the Setting's `getEndpoint()` method
110+
```java
111+
keyManagementServiceClient.getSettings().getEndpoint();
112+
```
113+
114+
## When should I specify my custom endpoint
115+
There are a few use cases:
116+
1. Service offers [regional endpoints](https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library) and you do not want the default endpoint.
117+
2. Service can't use https (i.e. local testing to hit localhost)

‎docs/universe_domain.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Universe Domain
2+
See [Anatomy of an Endpoint](endpoint.md#anatomy-of-an-endpoint) for more information about how the Universe Domain is used
3+
as part of an endpoint.
4+
5+
Universe Domain default value: `googleapis.com`. This is known as the Google Default
6+
Universe (GDU). If the Universe Domain value is not specified, the GDU value is used.
7+
8+
## Configuring a Specific Universe Domain
9+
There are two ways to configure the endpoint in Java Client Libraries: ServiceSettings and
10+
Environment Variable.
11+
12+
### Set through the generated {Service}Settings
13+
Configuring the Universe Domain is done via the generated {Service}Settings. The following example
14+
is using Java-KMS v2.42.0 as an example:
15+
16+
1. Set the endpoint in {Service}Settings.Builder and create the Settings object
17+
```java
18+
String universeDomain = "myUniverseDomain.com";
19+
KeyManagementServiceSettings keyManagementServiceSettings =
20+
KeyManagementServiceSettings.newBuilder()
21+
.setUniverseDomain(universeDomain).build();
22+
```
23+
2. Create the client with the Settings
24+
```java
25+
try (KeyManagementServiceClient keyManagementServiceClient =
26+
KeyManagementServiceClient.create(keyManagementServiceSettings)) {
27+
...
28+
}
29+
```
30+
31+
With this configuration, the client library will resolve the endpoint to be:
32+
`https://cloudkms.myUniverseDomain.com:443`.
33+
34+
### Set through an Environment Variable
35+
Set the Universe Domain to the `GOOGLE_CLOUD_UNIVERSE_DOMAIN`. If set, Java client libraries
36+
use this value.
37+
38+
### Universe Domain Hierarchy
39+
1. If set in the ClientSettings, use this value. Otherwise, go to the next step.
40+
2. If set via the Environment Variable, use this value. Otherwise, go to the next step.
41+
3. Use the GDU value (i.e Universe Domain is set to be `googleapis.com`)
42+
43+
### Configuring a Specific Universe Domain and a Custom Endpoint
44+
The following example is using Java-KMS v2.42.0 as an example:
45+
46+
1. Set the endpoint in {Service}Settings.Builder and create the Settings object
47+
```java
48+
String endpoint = "settingsEndpoint.com:443";
49+
String universeDomain = "universeDomain.com";
50+
KeyManagementServiceSettings keyManagementServiceSettings =
51+
KeyManagementServiceSettings.newBuilder()
52+
.setEndpoint(endpoint)
53+
.setUniverseDomain(universeDomain)
54+
.build();
55+
```
56+
57+
- The resolved endpoint is: `settingsEndpoint.com:443`
58+
- The resolved Universe Domain is: `universeDomain.com`
59+
60+
The custom set endpoint triumphs over any other configurations.
61+
62+
### How can I confirm the universe domain the library is using
63+
Assuming you have configured a custom endpoint, like:
64+
```java
65+
String universeDomain = "...";
66+
KeyManagementServiceSettings keyManagementServiceSettings =
67+
KeyManagementServiceSettings.newBuilder()
68+
.setUniverseDomain(universeDomain)
69+
.build();
70+
try (KeyManagementServiceClient keyManagementServiceClient =
71+
KeyManagementServiceClient.create(keyManagementServiceSettings)) {
72+
...
73+
}
74+
```
75+
76+
Retrieve the endpoint from the Setting's `getUniverseDomain()` method.
77+
```java
78+
keyManagementServiceClient.getSettings().getUniverseDomain();
79+
```
80+
81+
## Universe Domain Compatibility with
82+
### ... DirectPath
83+
Currently, DirectPath code only works in the GDU. If the Universe Domain is configured to not be in the
84+
GDU, DirectPath will not be used.
85+
### ... GDC-H
86+
Universe Domain is incompatible with [GDC-H](https://cloud.google.com/distributed-cloud/hosted/docs/latest/gdch/overview).
87+
Do not set the Universe Domain if you are using GDC-H Credentials.

0 commit comments

Comments
 (0)