0
# Client Configuration
1

2
Configuration classes for setting up Nacos clients with support for authentication, security, networking, logging, and operational parameters. The V2 API provides comprehensive configuration options through builder patterns and specialized configuration classes.
3

4
## Capabilities
5

6
### Basic Client Configuration
7

8
Main configuration class for Nacos client initialization.
9

10
```python { .api }
11
class ClientConfig:
12
    def __init__(self, server_addresses=None, endpoint=None, namespace_id='', context_path='',
13
                 access_key=None, secret_key=None, username=None, password=None, app_name='',
14
                 app_key='', log_dir='', log_level=None, log_rotation_backup_count=None,
15
                 app_conn_labels=None, credentials_provider=None):
16
        """
17
        Initialize client configuration.
18
        
19
        Args:
20
            server_addresses (str): Comma-separated list of Nacos server addresses
21
            endpoint (str): Address server endpoint for dynamic server discovery
22
            namespace_id (str): Nacos namespace ID
23
            context_path (str): Custom context path for Nacos server
24
            access_key (str): Access key for authentication
25
            secret_key (str): Secret key for authentication
26
            username (str): Username for authentication
27
            password (str): Password for authentication
28
            app_name (str): Application name
29
            app_key (str): Application key
30
            log_dir (str): Directory for log files
31
            log_level: Logging level (logging.INFO, logging.DEBUG, etc.)
32
            log_rotation_backup_count (int): Number of backup log files
33
            app_conn_labels (dict): Application connection labels
34
            credentials_provider: Custom credentials provider
35
        """
36
```
37

38
Usage example:
39

40
```python
41
from v2.nacos import ClientConfig
42
import logging
43

44
# Basic configuration with server addresses
45
client_config = ClientConfig(
46
    server_addresses="127.0.0.1:8848,127.0.0.1:8849,127.0.0.1:8850"
47
)
48

49
# Configuration with authentication
50
client_config = ClientConfig(
51
    server_addresses="127.0.0.1:8848",
52
    namespace_id="production",
53
    username="nacos",
54
    password="nacos"
55
)
56

57
# Configuration with access key authentication
58
client_config = ClientConfig(
59
    server_addresses="127.0.0.1:8848",
60
    access_key="your-access-key",
61
    secret_key="your-secret-key",
62
    namespace_id="production"
63
)
64

65
# Advanced configuration
66
client_config = ClientConfig(
67
    server_addresses="127.0.0.1:8848",
68
    namespace_id="production",
69
    username="nacos",
70
    password="nacos",
71
    app_name="MyApplication",
72
    log_dir="/var/log/nacos",
73
    log_level=logging.DEBUG,
74
    log_rotation_backup_count=10
75
)
76
```
77

78
### Configuration Builder Pattern
79

80
Builder class for creating ClientConfig instances with fluent interface.
81

82
```python { .api }
83
class ClientConfigBuilder:
84
    def server_address(self, server_address: str) -> 'ClientConfigBuilder': ...
85
    def endpoint(self, endpoint: str) -> 'ClientConfigBuilder': ...
86
    def namespace_id(self, namespace_id: str) -> 'ClientConfigBuilder': ...
87
    def context_path(self, context_path: str) -> 'ClientConfigBuilder': ...
88
    def access_key(self, access_key: str) -> 'ClientConfigBuilder': ...
89
    def secret_key(self, secret_key: str) -> 'ClientConfigBuilder': ...
90
    def username(self, username: str) -> 'ClientConfigBuilder': ...
91
    def password(self, password: str) -> 'ClientConfigBuilder': ...
92
    def app_name(self, app_name: str) -> 'ClientConfigBuilder': ...
93
    def app_key(self, app_key: str) -> 'ClientConfigBuilder': ...
94
    def log_dir(self, log_dir: str) -> 'ClientConfigBuilder': ...
95
    def log_level(self, log_level) -> 'ClientConfigBuilder': ...
96
    def log_rotation_backup_count(self, count: int) -> 'ClientConfigBuilder': ...
97
    def build(self) -> ClientConfig: ...
98
```
99

100
Usage example:
101

102
```python
103
from v2.nacos import ClientConfigBuilder
104
import logging
105

106
# Build configuration using fluent interface
107
client_config = (ClientConfigBuilder()
108
    .server_address("127.0.0.1:8848,127.0.0.1:8849")
109
    .namespace_id("production")
110
    .username("nacos")
111
    .password("nacos")
112
    .app_name("MyApplication")
113
    .log_level(logging.INFO)
114
    .build())
115

116
# Build step by step
117
builder = ClientConfigBuilder()
118
builder.server_address("127.0.0.1:8848")
119
builder.namespace_id("staging")
120
builder.access_key("staging-access-key")
121
builder.secret_key("staging-secret-key")
122
builder.app_name("StagingApp")
123

124
client_config = builder.build()
125
```
126

127
### Client Configuration Methods
128

129
Fluent methods for updating configuration after creation.
130

131
```python { .api }
132
class ClientConfig:
133
    def set_log_level(self, log_level): ...
134
    def set_cache_dir(self, cache_dir): ...
135
    def set_log_dir(self, log_dir): ...
136
    def set_timeout_ms(self, timeout_ms): ...
137
    def set_heart_beat_interval(self, heart_beat_interval): ...
138
    def set_kms_config(self, kms_config): ...
139
    def set_tls_config(self, tls_config): ...
140
    def set_grpc_config(self, grpc_config): ...
141
```
142

143
Usage example:
144

145
```python
146
import logging
147

148
# Create basic config
149
client_config = ClientConfig(server_addresses="127.0.0.1:8848")
150

151
# Update configuration
152
client_config.set_log_level(logging.DEBUG)
153
client_config.set_cache_dir("/tmp/nacos-cache")
154
client_config.set_timeout_ms(15000)  # 15 seconds
155
client_config.set_heart_beat_interval(3000)  # 3 seconds
156

157
# Chain method calls
158
client_config = (ClientConfig(server_addresses="127.0.0.1:8848")
159
    .set_log_level(logging.INFO)
160
    .set_timeout_ms(10000)
161
    .set_heart_beat_interval(5000))
162
```
163

164
### KMS Configuration
165

166
Configuration for Key Management Service encryption support.
167

168
```python { .api }
169
class KMSConfig:
170
    def __init__(self, enabled=False, endpoint='', access_key='', secret_key='',
171
                 client_key_content='', password=''):
172
        """
173
        Initialize KMS configuration.
174
        
175
        Args:
176
            enabled (bool): Whether KMS encryption is enabled
177
            endpoint (str): KMS service endpoint URL
178
            access_key (str): KMS access key
179
            secret_key (str): KMS secret key
180
            client_key_content (str): Client key content for authentication
181
            password (str): Password for key authentication
182
        """
183
```
184

185
Usage example:
186

187
```python
188
from v2.nacos import ClientConfig, KMSConfig
189

190
# Configure KMS encryption
191
kms_config = KMSConfig(
192
    enabled=True,
193
    endpoint="https://kms.us-west-1.amazonaws.com",
194
    access_key="AKIAIOSFODNN7EXAMPLE",
195
    secret_key="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
196
)
197

198
# Use KMS config in client configuration
199
client_config = ClientConfig(
200
    server_addresses="127.0.0.1:8848",
201
    kms_config=kms_config
202
)
203

204
# Alternative: Set KMS config after creation
205
client_config = ClientConfig(server_addresses="127.0.0.1:8848")
206
client_config.set_kms_config(kms_config)
207
```
208

209
### TLS Configuration
210

211
Configuration for secure TLS/SSL connections.
212

213
```python { .api }
214
class TLSConfig:
215
    def __init__(self, enabled=False, appointed=False, ca_file='', cert_file='',
216
                 key_file='', server_name_override=''):
217
        """
218
        Initialize TLS configuration.
219
        
220
        Args:
221
            enabled (bool): Whether TLS is enabled
222
            appointed (bool): Whether to use predefined configuration
223
            ca_file (str): Path to CA certificate file
224
            cert_file (str): Path to client certificate file
225
            key_file (str): Path to private key file
226
            server_name_override (str): Server name override for testing
227
        """
228
```
229

230
Usage example:
231

232
```python
233
from v2.nacos import ClientConfig, TLSConfig
234

235
# Configure TLS with certificates
236
tls_config = TLSConfig(
237
    enabled=True,
238
    ca_file="/etc/ssl/certs/ca-cert.pem",
239
    cert_file="/etc/ssl/certs/client-cert.pem",
240
    key_file="/etc/ssl/private/client-key.pem"
241
)
242

243
# Use TLS config in client configuration
244
client_config = ClientConfig(
245
    server_addresses="https://nacos.example.com:8848",
246
    tls_config=tls_config
247
)
248

249
# TLS with server name override (for testing)
250
tls_config = TLSConfig(
251
    enabled=True,
252
    appointed=True,
253
    server_name_override="localhost"
254
)
255

256
client_config = ClientConfig(
257
    server_addresses="127.0.0.1:8848",
258
    tls_config=tls_config
259
)
260
client_config.set_tls_config(tls_config)
261
```
262

263
### GRPC Configuration
264

265
Configuration for GRPC connection parameters and performance tuning.
266

267
```python { .api }
268
class GRPCConfig:
269
    def __init__(self, max_receive_message_length=4194304, max_keep_alive_ms=60000,
270
                 initial_window_size=1048576, initial_conn_window_size=1048576,
271
                 grpc_timeout=5000):
272
        """
273
        Initialize GRPC configuration.
274
        
275
        Args:
276
            max_receive_message_length (int): Maximum message size in bytes
277
            max_keep_alive_ms (int): Maximum keep-alive time in milliseconds
278
            initial_window_size (int): Initial window size for flow control
279
            initial_conn_window_size (int): Initial connection window size
280
            grpc_timeout (int): GRPC operation timeout in milliseconds
281
        """
282
```
283

284
Usage example:
285

286
```python
287
from v2.nacos import ClientConfig, GRPCConfig
288

289
# Default GRPC configuration
290
grpc_config = GRPCConfig()
291

292
# Custom GRPC configuration for high-throughput
293
grpc_config = GRPCConfig(
294
    max_receive_message_length=16777216,  # 16MB
295
    max_keep_alive_ms=30000,              # 30 seconds
296
    initial_window_size=2097152,          # 2MB
297
    initial_conn_window_size=2097152,     # 2MB
298
    grpc_timeout=10000                    # 10 seconds
299
)
300

301
# Use GRPC config in client configuration
302
client_config = ClientConfig(
303
    server_addresses="127.0.0.1:8848",
304
    grpc_config=grpc_config
305
)
306

307
# Set GRPC config after creation
308
client_config = ClientConfig(server_addresses="127.0.0.1:8848")
309
client_config.set_grpc_config(grpc_config)
310
```
311

312
### Advanced Configuration Options
313

314
Additional configuration properties for fine-tuning client behavior.
315

316
```python { .api }
317
class ClientConfig:
318
    # Core connection settings
319
    timeout_ms: int = 10000                    # Request timeout in milliseconds
320
    heart_beat_interval: int = 5000            # Heartbeat interval in milliseconds
321
    
322
    # Directory settings
323
    cache_dir: str = ''                        # Local cache directory
324
    log_dir: str = ''                          # Log directory
325
    
326
    # Logging settings
327
    log_level: int = logging.INFO              # Logging level
328
    log_rotation_backup_count: int = 7         # Number of backup log files
329
    
330
    # Cache settings
331
    load_cache_at_start: bool = True           # Load cache on startup
332
    update_cache_when_empty: bool = False      # Update cache when empty
333
    disable_use_config_cache: bool = False     # Disable configuration cache
334
    
335
    # Service discovery settings
336
    async_update_service: bool = False         # Enable async service updates
337
    update_thread_num: int = 5                 # Number of update threads
338
    
339
    # Connection settings
340
    app_conn_labels: dict = None               # Application connection labels
341
```
342

343
Usage example:
344

345
```python
346
# Performance-optimized configuration
347
client_config = ClientConfig(
348
    server_addresses="127.0.0.1:8848",
349
    timeout_ms=5000,           # Faster timeout
350
    heart_beat_interval=3000,  # More frequent heartbeats
351
    async_update_service=True, # Enable async updates
352
    update_thread_num=10       # More update threads
353
)
354

355
# Development configuration with extensive logging
356
client_config = ClientConfig(
357
    server_addresses="127.0.0.1:8848",
358
    log_level=logging.DEBUG,
359
    log_rotation_backup_count=20,
360
    cache_dir="/tmp/nacos-dev-cache",
361
    load_cache_at_start=False,  # Don't load cache on startup
362
    disable_use_config_cache=True  # Disable cache for fresh data
363
)
364

365
# Production configuration with caching
366
client_config = ClientConfig(
367
    server_addresses="nacos1.prod.com:8848,nacos2.prod.com:8848,nacos3.prod.com:8848",
368
    namespace_id="production",
369
    timeout_ms=15000,
370
    heart_beat_interval=5000,
371
    cache_dir="/var/cache/nacos",
372
    log_dir="/var/log/nacos",
373
    log_level=logging.WARN,
374
    load_cache_at_start=True,
375
    update_cache_when_empty=True,
376
    async_update_service=True
377
)
378
```
379

380
## Configuration Examples
381

382
### Minimal Configuration
383

384
```python
385
from v2.nacos import ClientConfig
386

387
# Simplest possible configuration
388
client_config = ClientConfig(server_addresses="127.0.0.1:8848")
389
```
390

391
### Development Environment
392

393
```python
394
from v2.nacos import ClientConfig, ClientConfigBuilder
395
import logging
396

397
# Development configuration with debugging
398
client_config = (ClientConfigBuilder()
399
    .server_addresses("127.0.0.1:8848")
400
    .namespace_id("dev")
401
    .username("nacos")
402
    .password("nacos")
403
    .app_name("MyApp-Dev")
404
    .log_level(logging.DEBUG)
405
    .build())
406

407
# Enable development-friendly settings
408
client_config.set_timeout_ms(30000)  # Longer timeout for debugging
409
client_config.set_cache_dir("/tmp/nacos-dev-cache")
410
client_config.disable_use_config_cache = True  # Always fetch fresh data
411
```
412

413
### Production Environment
414

415
```python
416
from v2.nacos import ClientConfig, TLSConfig, KMSConfig
417
import logging
418

419
# Production configuration with security
420
tls_config = TLSConfig(
421
    enabled=True,
422
    ca_file="/etc/ssl/certs/nacos-ca.pem",
423
    cert_file="/etc/ssl/certs/app-client.pem",
424
    key_file="/etc/ssl/private/app-client-key.pem"
425
)
426

427
kms_config = KMSConfig(
428
    enabled=True,
429
    endpoint="https://kms.us-west-1.amazonaws.com",
430
    access_key="prod-access-key",
431
    secret_key="prod-secret-key"
432
)
433

434
client_config = ClientConfig(
435
    server_addresses="nacos1.prod.com:8848,nacos2.prod.com:8848,nacos3.prod.com:8848",
436
    namespace_id="production",
437
    access_key="prod-app-access-key",
438
    secret_key="prod-app-secret-key",
439
    app_name="MyApp-Prod",
440
    tls_config=tls_config,
441
    kms_config=kms_config,
442
    log_dir="/var/log/nacos",
443
    log_level=logging.INFO,
444
    cache_dir="/var/cache/nacos",
445
    timeout_ms=10000,
446
    heart_beat_interval=5000,
447
    async_update_service=True
448
)
449
```
450

451
### High-Performance Configuration
452

453
```python
454
from v2.nacos import ClientConfig, GRPCConfig
455

456
# High-performance configuration
457
grpc_config = GRPCConfig(
458
    max_receive_message_length=33554432,  # 32MB for large configs
459
    max_keep_alive_ms=30000,
460
    initial_window_size=4194304,          # 4MB
461
    initial_conn_window_size=4194304,     # 4MB
462
    grpc_timeout=5000
463
)
464

465
client_config = ClientConfig(
466
    server_addresses="127.0.0.1:8848",
467
    grpc_config=grpc_config,
468
    timeout_ms=5000,
469
    heart_beat_interval=3000,
470
    async_update_service=True,
471
    update_thread_num=20,  # More threads for updates
472
    load_cache_at_start=True,
473
    update_cache_when_empty=True
474
)
475
```
476

477
## Authentication Methods
478

479
### Username/Password Authentication
480

481
```python
482
client_config = ClientConfig(
483
    server_addresses="127.0.0.1:8848",
484
    username="admin",
485
    password="password123"
486
)
487
```
488

489
### Access Key Authentication
490

491
```python
492
client_config = ClientConfig(
493
    server_addresses="127.0.0.1:8848",
494
    access_key="your-access-key",
495
    secret_key="your-secret-key"
496
)
497
```
498

499
### Custom Credentials Provider
500

501
```python
502
from v2.nacos.common.auth import StaticCredentialsProvider
503

504
# Custom credentials provider
505
credentials_provider = StaticCredentialsProvider(
506
    access_key="custom-access-key",
507
    secret_key="custom-secret-key"
508
)
509

510
client_config = ClientConfig(
511
    server_addresses="127.0.0.1:8848",
512
    credentials_provider=credentials_provider
513
)
514
```