0
# Universe Domain Support
1

2
Universe domain configuration and validation for multi-environment Google Cloud deployments. This module enables Google API clients to operate across different Google Cloud universes (environments) with proper domain validation and configuration management.
3

4
## Capabilities
5

6
### Domain Determination
7

8
Determine the appropriate universe domain based on client configuration and environment variables with fallback to default behavior.
9

10
```python { .api }
11
def determine_domain(client_universe_domain, universe_domain_env): ...
12

13
DEFAULT_UNIVERSE = "googleapis.com"
14
```
15

16
### Domain Validation
17

18
Compare and validate universe domains between client configuration and authentication credentials to ensure compatibility.
19

20
```python { .api }
21
def compare_domains(client_universe, credentials): ...
22
```
23

24
### Error Handling
25

26
Specialized exceptions for universe domain configuration errors and validation failures.
27

28
```python { .api }
29
class EmptyUniverseError(ValueError): ...
30

31
class UniverseMismatchError(ValueError): ...
32
```
33

34
## Usage Examples
35

36
### Basic Universe Domain Configuration
37

38
```python
39
from google.api_core import universe
40
import os
41

42
# Determine universe domain from multiple sources
43
client_universe = None  # Not explicitly configured
44
env_universe = os.getenv("GOOGLE_CLOUD_UNIVERSE_DOMAIN")
45

46
# Get the effective universe domain
47
effective_domain = universe.determine_domain(client_universe, env_universe)
48
print(f"Using universe domain: {effective_domain}")
49
# Output: "Using universe domain: googleapis.com" (default)
50

51
# With explicit client configuration
52
client_universe = "my-universe.googleapis.com"
53
effective_domain = universe.determine_domain(client_universe, env_universe)
54
print(f"Using universe domain: {effective_domain}")  
55
# Output: "Using universe domain: my-universe.googleapis.com"
56
```
57

58
### Environment Variable Configuration
59

60
```python
61
import os
62
from google.api_core import universe
63

64
# Set universe domain via environment variable
65
os.environ["GOOGLE_CLOUD_UNIVERSE_DOMAIN"] = "staging.googleapis.com"
66

67
# Determine domain (environment variable takes precedence over default)
68
domain = universe.determine_domain(None, os.getenv("GOOGLE_CLOUD_UNIVERSE_DOMAIN"))
69
print(f"Universe domain: {domain}")
70
# Output: "Universe domain: staging.googleapis.com"
71
```
72

73
### Credentials Validation
74

75
```python
76
from google.api_core import universe
77
from google.auth import credentials
78

79
# Assume we have credentials with a universe domain
80
# credentials.universe_domain = "staging.googleapis.com"
81

82
client_universe = "staging.googleapis.com"
83

84
try:
85
    # Validate that client and credentials use the same universe
86
    is_compatible = universe.compare_domains(client_universe, credentials)
87
    print("Universe domains are compatible")
88
except universe.UniverseMismatchError as e:
89
    print(f"Universe mismatch: {e}")
90
    # Handle the mismatch appropriately
91
```
92

93
### Error Handling
94

95
```python
96
from google.api_core import universe
97

98
# Handle empty universe domain
99
try:
100
    invalid_domain = universe.determine_domain("", None)
101
except universe.EmptyUniverseError as e:
102
    print(f"Error: {e}")
103
    # Output: "Error: Universe Domain cannot be an empty string."
104

105
# Handle universe mismatch
106
try:
107
    universe.compare_domains("prod.googleapis.com", mock_credentials_with_staging)
108
except universe.UniverseMismatchError as e:
109
    print(f"Mismatch detected: {e}")
110
    # Output details about the client vs credentials universe domains
111
```
112

113
### Client Integration Pattern
114

115
```python
116
from google.api_core import universe
117
from google.auth import default
118
import os
119

120
def create_client_with_universe_validation():
121
    # Get default credentials
122
    credentials, project = default()
123
    
124
    # Determine client universe domain
125
    client_universe = universe.determine_domain(
126
        client_universe_domain=None,  # Could come from client options
127
        universe_domain_env=os.getenv("GOOGLE_CLOUD_UNIVERSE_DOMAIN")
128
    )
129
    
130
    # Validate compatibility
131
    try:
132
        universe.compare_domains(client_universe, credentials)
133
        print(f"Creating client for universe: {client_universe}")
134
        # Proceed with client creation
135
    except universe.UniverseMismatchError:
136
        print("Universe domain mismatch - cannot create client")
137
        raise
138
```
139

140
## Domain Resolution Priority
141

142
The universe domain is determined using the following priority order:
143

144
1. **Client Configuration**: Explicitly set universe domain in client options
145
2. **Environment Variable**: `GOOGLE_CLOUD_UNIVERSE_DOMAIN` environment variable  
146
3. **Default**: `googleapis.com` (production Google Cloud)
147

148
```python
149
# Priority demonstration
150
def demonstrate_priority():
151
    # Scenario 1: Client config takes highest priority
152
    domain1 = universe.determine_domain("custom.googleapis.com", "env.googleapis.com")
153
    assert domain1 == "custom.googleapis.com"
154
    
155
    # Scenario 2: Environment variable used when client config is None
156
    domain2 = universe.determine_domain(None, "env.googleapis.com") 
157
    assert domain2 == "env.googleapis.com"
158
    
159
    # Scenario 3: Default when both are None
160
    domain3 = universe.determine_domain(None, None)
161
    assert domain3 == "googleapis.com"
162
```
163

164
## Multi-Universe Deployment Patterns
165

166
### Development/Staging/Production Environments
167

168
```python
169
import os
170
from google.api_core import universe
171

172
def get_environment_universe():
173
    """Get universe domain based on deployment environment."""
174
    env = os.getenv("DEPLOYMENT_ENV", "production")
175
    
176
    universe_mappings = {
177
        "development": "dev.googleapis.com",
178
        "staging": "staging.googleapis.com", 
179
        "production": "googleapis.com"
180
    }
181
    
182
    configured_universe = universe_mappings.get(env, universe.DEFAULT_UNIVERSE)
183
    
184
    return universe.determine_domain(
185
        configured_universe,
186
        os.getenv("GOOGLE_CLOUD_UNIVERSE_DOMAIN")
187
    )
188
```
189

190
### Custom Universe Configuration
191

192
```python  
193
from google.api_core import universe
194

195
class UniverseConfig:
196
    def __init__(self, environment="production"):
197
        self.environment = environment
198
        self._universe_domain = None
199
    
200
    @property
201
    def universe_domain(self):
202
        if self._universe_domain:
203
            return self._universe_domain
204
            
205
        return universe.determine_domain(
206
            client_universe_domain=self._get_environment_domain(),
207
            universe_domain_env=os.getenv("GOOGLE_CLOUD_UNIVERSE_DOMAIN")
208
        )
209
    
210
    def _get_environment_domain(self):
211
        if self.environment == "staging":
212
            return "staging.googleapis.com"
213
        elif self.environment == "development":
214
            return "dev.googleapis.com"
215
        return None  # Use default for production
216
```
217

218
## Import Patterns
219

220
```python
221
from google.api_core import universe
222

223
# Use constants
224
default_domain = universe.DEFAULT_UNIVERSE
225

226
# Domain determination
227
domain = universe.determine_domain(client_config, env_config)
228

229
# Validation
230
universe.compare_domains(client_domain, credentials)
231

232
# Exception handling
233
try:
234
    domain = universe.determine_domain("", None)
235
except universe.EmptyUniverseError:
236
    # Handle empty domain error
237
    pass
238
except universe.UniverseMismatchError:
239
    # Handle universe mismatch
240
    pass
241
```
242

243
## Types
244

245
```python { .api }
246
from typing import Any, Optional
247

248
# Function signatures
249
UniverseDomain = str
250
CredentialsType = Any  # Credentials object with optional universe_domain attribute
251

252
# Configuration types
253
ClientUniverseDomain = Optional[str]
254
EnvironmentUniverseDomain = Optional[str]
255
```
256

257
## Error Categories
258

259
### EmptyUniverseError
260
- **Cause**: Universe domain is an empty string or whitespace-only
261
- **Resolution**: Provide a valid non-empty universe domain
262
- **Prevention**: Validate configuration before passing to determine_domain()
263

264
### UniverseMismatchError  
265
- **Cause**: Client universe domain doesn't match credentials universe domain
266
- **Resolution**: Ensure client and credentials use the same universe
267
- **Prevention**: Validate universe compatibility during client initialization
268

269
## Architecture Considerations
270

271
### Universe Domain Hierarchy
272
- **Production**: `googleapis.com` (default)
273
- **Staging**: `staging.googleapis.com` 
274
- **Development**: `dev.googleapis.com`
275
- **Custom**: Organization-specific domains
276

277
### Configuration Sources
278
1. **Explicit Client Options**: Highest priority, set programmatically
279
2. **Environment Variables**: System-level configuration
280
3. **Default Values**: Fallback to production universe
281

282
### Security Implications
283
- Universe domains control which Google Cloud environment is accessed
284
- Mismatched domains can lead to authentication failures
285
- Proper validation prevents accidental cross-environment access
286
- Environment isolation is maintained through domain separation
287

288
This module ensures proper universe domain handling for Google API clients operating across different Google Cloud environments while maintaining security and configuration consistency.