0
# Google Cloud Container
1
2
Google Cloud Container API client library for managing Google Kubernetes Engine (GKE) clusters. This library provides comprehensive tools for creating, configuring, managing, and monitoring Kubernetes clusters on Google Cloud Platform through both stable (v1) and beta (v1beta1) APIs.
3
4
## Package Information
5
6
- **Package Name**: google-cloud-container
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install google-cloud-container`
10
11
## Core Imports
12
13
```python
14
from google.cloud import container
15
```
16
17
For direct v1 API access:
18
19
```python
20
from google.cloud import container_v1
21
```
22
23
For beta features (v1beta1 API with experimental functionality):
24
25
```python
26
from google.cloud import container_v1beta1
27
28
# Create beta client with additional features
29
beta_client = container_v1beta1.ClusterManagerClient()
30
```
31
32
## Basic Usage
33
34
```python
35
from google.cloud import container
36
37
# Create a client using application default credentials
38
client = container.ClusterManagerClient()
39
40
# List all clusters in a project and zone
41
project_id = "my-project"
42
zone = "us-central1-a"
43
clusters = client.list_clusters(project_id=project_id, zone=zone)
44
45
for cluster in clusters.clusters:
46
print(f"Cluster: {cluster.name}")
47
print(f"Status: {cluster.status}")
48
print(f"Node count: {cluster.current_node_count}")
49
50
# Get details of a specific cluster
51
cluster = client.get_cluster(
52
project_id=project_id,
53
zone=zone,
54
cluster_id="my-cluster"
55
)
56
57
print(f"Cluster location: {cluster.location}")
58
print(f"Kubernetes version: {cluster.current_master_version}")
59
60
# For async operations
61
import asyncio
62
from google.cloud import container
63
64
async def async_example():
65
async_client = container.ClusterManagerAsyncClient()
66
67
# List clusters asynchronously
68
clusters = await async_client.list_clusters(
69
project_id=project_id,
70
zone=zone
71
)
72
73
for cluster in clusters.clusters:
74
print(f"Async - Cluster: {cluster.name}")
75
76
# asyncio.run(async_example())
77
```
78
79
## Architecture
80
81
The Google Cloud Container client library is built on Google's GAPIC (Google API Client Generator) framework, providing:
82
83
- **Auto-generated clients** from Protocol Buffer service definitions
84
- **Consistent patterns** across all Google Cloud services
85
- **Multiple transport options** (gRPC, HTTP/1.1 REST)
86
- **Async and sync clients** for different programming models
87
- **Comprehensive type definitions** with full IDE support
88
89
Key components:
90
91
- **ClusterManagerClient**: Primary service client for cluster operations
92
- **Data types**: Complete set of request/response objects and configuration classes
93
- **Transport layer**: Pluggable transport supporting gRPC and REST protocols
94
- **Authentication**: Integration with Google Cloud authentication and service accounts
95
96
## Capabilities
97
98
### Cluster Management
99
100
Core cluster lifecycle operations including creation, updates, deletion, and configuration management. Supports both basic and advanced cluster configurations with comprehensive node pool management.
101
102
```python { .api }
103
def list_clusters(self, request=None, *, project_id=None, zone=None, parent=None, retry=..., timeout=..., metadata=...) -> ListClustersResponse: ...
104
def get_cluster(self, request=None, *, project_id=None, zone=None, cluster_id=None, name=None, retry=..., timeout=..., metadata=...) -> Cluster: ...
105
def create_cluster(self, request=None, *, project_id=None, zone=None, cluster=None, parent=None, retry=..., timeout=..., metadata=...) -> Operation: ...
106
def update_cluster(self, request=None, *, project_id=None, zone=None, cluster_id=None, update=None, name=None, retry=..., timeout=..., metadata=...) -> Operation: ...
107
def delete_cluster(self, request=None, *, project_id=None, zone=None, cluster_id=None, name=None, retry=..., timeout=..., metadata=...) -> Operation: ...
108
```
109
110
[Cluster Management](./cluster-management.md)
111
112
### Node Pool Operations
113
114
Node pool lifecycle management including creation, scaling, updates, and configuration. Supports autoscaling, management policies, and rolling updates for node pools within clusters.
115
116
```python { .api }
117
def list_node_pools(self, request=None, *, project_id=None, zone=None, cluster_id=None, parent=None, retry=..., timeout=..., metadata=...) -> ListNodePoolsResponse: ...
118
def get_node_pool(self, request=None, *, project_id=None, zone=None, cluster_id=None, node_pool_id=None, name=None, retry=..., timeout=..., metadata=...) -> NodePool: ...
119
def create_node_pool(self, request=None, *, project_id=None, zone=None, cluster_id=None, node_pool=None, parent=None, retry=..., timeout=..., metadata=...) -> Operation: ...
120
def delete_node_pool(self, request=None, *, project_id=None, zone=None, cluster_id=None, node_pool_id=None, name=None, retry=..., timeout=..., metadata=...) -> Operation: ...
121
def update_node_pool(self, request=None, *, project_id=None, zone=None, cluster_id=None, node_pool_id=None, node_version=None, image_type=None, name=None, retry=..., timeout=..., metadata=...) -> Operation: ...
122
def set_node_pool_autoscaling(self, request=None, *, retry=..., timeout=..., metadata=...) -> Operation: ...
123
def set_node_pool_management(self, request=None, *, retry=..., timeout=..., metadata=...) -> Operation: ...
124
def set_node_pool_size(self, request=None, *, retry=..., timeout=..., metadata=...) -> Operation: ...
125
def rollback_node_pool_upgrade(self, request=None, *, project_id=None, zone=None, cluster_id=None, node_pool_id=None, name=None, retry=..., timeout=..., metadata=...) -> Operation: ...
126
def complete_node_pool_upgrade(self, request=None, *, retry=..., timeout=..., metadata=...) -> None: ...
127
```
128
129
[Node Pool Operations](./node-pool-operations.md)
130
131
### Cluster Configuration
132
133
Advanced cluster configuration including addons, networking, security, logging, monitoring, and maintenance policies. Covers both basic settings and enterprise-grade configurations.
134
135
```python { .api }
136
def set_addons_config(self, request=None, *, project_id=None, zone=None, cluster_id=None, addons_config=None, name=None, retry=..., timeout=..., metadata=...) -> Operation: ...
137
def set_logging_service(self, request=None, *, project_id=None, zone=None, cluster_id=None, logging_service=None, name=None, retry=..., timeout=..., metadata=...) -> Operation: ...
138
def set_monitoring_service(self, request=None, *, project_id=None, zone=None, cluster_id=None, monitoring_service=None, name=None, retry=..., timeout=..., metadata=...) -> Operation: ...
139
def set_network_policy(self, request=None, *, project_id=None, zone=None, cluster_id=None, network_policy=None, name=None, retry=..., timeout=..., metadata=...) -> Operation: ...
140
def set_labels(self, request=None, *, project_id=None, zone=None, cluster_id=None, resource_labels=None, label_fingerprint=None, name=None, retry=..., timeout=..., metadata=...) -> Operation: ...
141
def set_legacy_abac(self, request=None, *, project_id=None, zone=None, cluster_id=None, enabled=None, name=None, retry=..., timeout=..., metadata=...) -> Operation: ...
142
def set_locations(self, request=None, *, project_id=None, zone=None, cluster_id=None, locations=None, name=None, retry=..., timeout=..., metadata=...) -> Operation: ...
143
def set_maintenance_policy(self, request=None, *, project_id=None, zone=None, cluster_id=None, maintenance_policy=None, name=None, retry=..., timeout=..., metadata=...) -> Operation: ...
144
def update_master(self, request=None, *, project_id=None, zone=None, cluster_id=None, master_version=None, name=None, retry=..., timeout=..., metadata=...) -> Operation: ...
145
```
146
147
[Cluster Configuration](./cluster-configuration.md)
148
149
### Operations Management
150
151
Long-running operation monitoring and management for tracking cluster and node pool changes. Includes operation listing, status checking, and cancellation capabilities.
152
153
```python { .api }
154
def list_operations(self, request=None, *, project_id=None, zone=None, parent=None, retry=..., timeout=..., metadata=...) -> ListOperationsResponse: ...
155
def get_operation(self, request=None, *, project_id=None, zone=None, operation_id=None, name=None, retry=..., timeout=..., metadata=...) -> Operation: ...
156
def cancel_operation(self, request=None, *, project_id=None, zone=None, operation_id=None, name=None, retry=..., timeout=..., metadata=...) -> None: ...
157
```
158
159
[Operations Management](./operations-management.md)
160
161
### Authentication and Security
162
163
Authentication configuration, security policies, and access control including master authentication, client certificates, workload identity, and network security policies.
164
165
```python { .api }
166
def set_master_auth(self, request=None, *, project_id=None, zone=None, cluster_id=None, action=None, update=None, name=None, retry=..., timeout=..., metadata=...) -> Operation: ...
167
def set_legacy_abac(self, request=None, *, project_id=None, zone=None, cluster_id=None, enabled=None, name=None, retry=..., timeout=..., metadata=...) -> Operation: ...
168
def get_json_web_keys(self, request=None, *, parent=None, retry=..., timeout=..., metadata=...) -> GetJSONWebKeysResponse: ...
169
```
170
171
[Authentication and Security](./authentication-security.md)
172
173
### IP Rotation Management
174
175
Control plane IP address rotation for enhanced security, allowing gradual rotation of cluster master IP addresses while maintaining connectivity.
176
177
```python { .api }
178
def start_ip_rotation(self, request=None, *, project_id=None, zone=None, cluster_id=None, name=None, retry=..., timeout=..., metadata=...) -> Operation: ...
179
def complete_ip_rotation(self, request=None, *, project_id=None, zone=None, cluster_id=None, name=None, retry=..., timeout=..., metadata=...) -> Operation: ...
180
```
181
182
### Service Information
183
184
Retrieve GKE service configuration and server information including supported Kubernetes versions and available features.
185
186
```python { .api }
187
def get_server_config(self, request=None, *, project_id=None, zone=None, name=None, retry=..., timeout=..., metadata=...) -> ServerConfig: ...
188
def get_json_web_keys(self, request=None, *, retry=..., timeout=..., metadata=...) -> GetJSONWebKeysResponse: ...
189
```
190
191
### Resource Discovery
192
193
Discover available network resources and subnets for cluster configuration and regional cluster deployment.
194
195
```python { .api }
196
def list_usable_subnetworks(self, request=None, *, retry=..., timeout=..., metadata=...) -> ListUsableSubnetworksPager: ...
197
```
198
199
### Autopilot Management
200
201
Autopilot cluster compatibility checking and management for hands-off cluster operations.
202
203
```python { .api }
204
def check_autopilot_compatibility(self, request=None, *, retry=..., timeout=..., metadata=...) -> CheckAutopilotCompatibilityResponse: ...
205
```
206
207
### Upgrade Information
208
209
Retrieve detailed upgrade information for clusters and node pools including available versions and upgrade paths.
210
211
```python { .api }
212
def fetch_cluster_upgrade_info(self, request=None, *, name=None, retry=..., timeout=..., metadata=...) -> ClusterUpgradeInfo: ...
213
def fetch_node_pool_upgrade_info(self, request=None, *, name=None, retry=..., timeout=..., metadata=...) -> NodePoolUpgradeInfo: ...
214
```
215
216
## Core Types
217
218
```python { .api }
219
class ClusterManagerClient:
220
"""Google Kubernetes Engine Cluster Manager v1 (stable API)"""
221
def __init__(self, *, credentials=None, transport=None, client_options=None, client_info=None): ...
222
223
class ClusterManagerAsyncClient:
224
"""Asynchronous client for Cluster Manager service v1"""
225
def __init__(self, *, credentials=None, transport=None, client_options=None, client_info=None): ...
226
227
# Beta API clients (v1beta1) with additional experimental features
228
class container_v1beta1.ClusterManagerClient:
229
"""Google Kubernetes Engine Cluster Manager v1beta1 (beta API with experimental features)"""
230
def __init__(self, *, credentials=None, transport=None, client_options=None, client_info=None): ...
231
def list_locations(self, request=None, *, parent=None, retry=..., timeout=..., metadata=...) -> ListLocationsResponse: ...
232
233
class container_v1beta1.ClusterManagerAsyncClient:
234
"""Asynchronous client for Cluster Manager service v1beta1"""
235
def __init__(self, *, credentials=None, transport=None, client_options=None, client_info=None): ...
236
237
class Cluster:
238
"""A Google Kubernetes Engine cluster"""
239
name: str
240
description: str
241
initial_node_count: int
242
node_config: NodeConfig
243
master_auth: MasterAuth
244
logging_service: str
245
monitoring_service: str
246
network: str
247
cluster_ipv4_cidr: str
248
addons_config: AddonsConfig
249
subnetwork: str
250
node_pools: MutableSequence[NodePool]
251
locations: MutableSequence[str]
252
enable_kubernetes_alpha: bool
253
resource_labels: MutableMapping[str, str]
254
label_fingerprint: str
255
legacy_abac: LegacyAbac
256
network_policy: NetworkPolicy
257
ip_allocation_policy: IPAllocationPolicy
258
master_authorized_networks_config: MasterAuthorizedNetworksConfig
259
maintenance_policy: MaintenancePolicy
260
binary_authorization: BinaryAuthorization
261
autoscaling: ClusterAutoscaling
262
network_config: NetworkConfig
263
default_max_pods_constraint: MaxPodsConstraint
264
resource_usage_export_config: ResourceUsageExportConfig
265
authenticator_groups_config: AuthenticatorGroupsConfig
266
private_cluster_config: PrivateClusterConfig
267
database_encryption: DatabaseEncryption
268
vertical_pod_autoscaling: VerticalPodAutoscaling
269
shielded_nodes: ShieldedNodes
270
release_channel: ReleaseChannel
271
workload_identity_config: WorkloadIdentityConfig
272
notification_config: NotificationConfig
273
confidential_nodes: ConfidentialNodes
274
self_link: str
275
zone: str
276
endpoint: str
277
initial_cluster_version: str
278
current_master_version: str
279
current_node_version: str
280
create_time: str
281
status: str
282
status_message: str
283
node_ipv4_cidr_size: int
284
services_ipv4_cidr: str
285
instance_group_urls: MutableSequence[str]
286
current_node_count: int
287
expire_time: str
288
location: str
289
enable_tpu: bool
290
tpu_ipv4_cidr_block: str
291
conditions: MutableSequence[StatusCondition]
292
autopilot: Autopilot
293
id: str
294
node_pool_defaults: NodePoolDefaults
295
logging_config: LoggingConfig
296
monitoring_config: MonitoringConfig
297
node_pool_auto_config: NodePoolAutoConfig
298
etag: str
299
fleet: Fleet
300
security_posture_config: SecurityPostureConfig
301
enable_k8s_beta_apis: K8sBetaAPIConfig
302
enterprise_config: EnterpriseConfig
303
secret_manager_config: SecretManagerConfig
304
compliance_posture_config: CompliancePostureConfig
305
306
class NodePool:
307
"""NodePool contains the name and configuration for a cluster's node pool"""
308
name: str
309
config: NodeConfig
310
initial_node_count: int
311
locations: MutableSequence[str]
312
network_config: NodeNetworkConfig
313
self_link: str
314
version: str
315
instance_group_urls: MutableSequence[str]
316
status: str
317
status_message: str
318
autoscaling: NodePoolAutoscaling
319
management: NodeManagement
320
max_pods_constraint: MaxPodsConstraint
321
conditions: MutableSequence[StatusCondition]
322
pod_ipv4_cidr_size: int
323
upgrade_settings: UpgradeSettings
324
placement_policy: PlacementPolicy
325
update_info: UpdateInfo
326
etag: str
327
queued_provisioning: QueuedProvisioning
328
best_effort_provisioning: BestEffortProvisioning
329
330
class Operation:
331
"""Represents an operation resource"""
332
name: str
333
zone: str
334
operation_type: str
335
status: str
336
detail: str
337
status_message: str
338
self_link: str
339
target_link: str
340
location: str
341
start_time: str
342
end_time: str
343
progress: OperationProgress
344
cluster_conditions: MutableSequence[StatusCondition]
345
nodepool_conditions: MutableSequence[StatusCondition]
346
error: Status
347
348
# Core Configuration Types
349
class NodeConfig:
350
"""Parameters that describe the nodes in a cluster"""
351
machine_type: str
352
disk_size_gb: int
353
oauth_scopes: MutableSequence[str]
354
service_account: str
355
metadata: MutableMapping[str, str]
356
image_type: str
357
labels: MutableMapping[str, str]
358
local_ssd_count: int
359
tags: MutableSequence[str]
360
preemptible: bool
361
disk_type: str
362
min_cpu_platform: str
363
workload_metadata_config: WorkloadMetadataConfig
364
taints: MutableSequence[NodeTaint]
365
shielded_instance_config: ShieldedInstanceConfig
366
linux_node_config: LinuxNodeConfig
367
kubelet_config: NodeKubeletConfig
368
369
class MasterAuth:
370
"""Master authentication configuration"""
371
username: str
372
password: str
373
client_certificate_config: ClientCertificateConfig
374
cluster_ca_certificate: str
375
client_certificate: str
376
client_key: str
377
378
class AddonsConfig:
379
"""Configuration for the addons that can be automatically spun up in the cluster"""
380
http_load_balancing: HttpLoadBalancing
381
horizontal_pod_autoscaling: HorizontalPodAutoscaling
382
kubernetes_dashboard: KubernetesDashboard
383
network_policy_config: NetworkPolicyConfig
384
cloud_run_config: CloudRunConfig
385
dns_cache_config: DnsCacheConfig
386
config_connector_config: ConfigConnectorConfig
387
gce_persistent_disk_csi_driver_config: GcePersistentDiskCsiDriverConfig
388
389
class NetworkPolicy:
390
"""Configuration options for the NetworkPolicy feature"""
391
provider: str
392
enabled: bool
393
394
class IPAllocationPolicy:
395
"""Configuration for controlling how IPs are allocated in the cluster"""
396
use_ip_aliases: bool
397
create_subnetwork: bool
398
subnetwork_name: str
399
cluster_ipv4_cidr: str
400
node_ipv4_cidr: str
401
services_ipv4_cidr: str
402
cluster_secondary_range_name: str
403
services_secondary_range_name: str
404
cluster_ipv4_cidr_block: str
405
node_ipv4_cidr_block: str
406
services_ipv4_cidr_block: str
407
408
class ServerConfig:
409
"""Kubernetes Engine service configuration"""
410
default_cluster_version: str
411
valid_node_versions: MutableSequence[str]
412
default_image_type: str
413
valid_image_types: MutableSequence[str]
414
valid_master_versions: MutableSequence[str]
415
channels: MutableSequence[ReleaseChannelConfig]
416
417
# Request/Response Types
418
class ListClustersResponse:
419
"""Response for listing clusters"""
420
clusters: MutableSequence[Cluster]
421
missing_zones: MutableSequence[str]
422
423
class ListNodePoolsResponse:
424
"""Response for listing node pools"""
425
node_pools: MutableSequence[NodePool]
426
427
class ListOperationsResponse:
428
"""Response for listing operations"""
429
operations: MutableSequence[Operation]
430
missing_zones: MutableSequence[str]
431
432
class GetJSONWebKeysResponse:
433
"""Response for getting JSON Web Keys"""
434
keys: MutableSequence[Jwk]
435
436
class CheckAutopilotCompatibilityResponse:
437
"""Response for checking Autopilot compatibility"""
438
issues: MutableSequence[AutopilotCompatibilityIssue]
439
summary: str
440
441
class ClusterUpgradeInfo:
442
"""Cluster upgrade information"""
443
upgrade_type: str
444
current_version: str
445
target_version: str
446
447
class NodePoolUpgradeInfo:
448
"""Node pool upgrade information"""
449
upgrade_type: str
450
current_version: str
451
target_version: str
452
453
# Additional Essential Types
454
class ClusterUpdate:
455
"""ClusterUpdate describes an update to the cluster"""
456
desired_node_version: str
457
desired_monitoring_service: str
458
desired_addons_config: AddonsConfig
459
desired_node_pool_id: str
460
desired_image_type: str
461
desired_database_encryption: DatabaseEncryption
462
desired_workload_identity_config: WorkloadIdentityConfig
463
desired_shielded_nodes: ShieldedNodes
464
desired_private_cluster_config: PrivateClusterConfig
465
466
class NodePoolAutoscaling:
467
"""NodePoolAutoscaling contains information required by cluster autoscaler"""
468
enabled: bool
469
min_node_count: int
470
max_node_count: int
471
autoprovisioned: bool
472
473
class NodeManagement:
474
"""NodeManagement defines the set of node management services"""
475
auto_upgrade: bool
476
auto_repair: bool
477
upgrade_options: AutoUpgradeOptions
478
479
# Additional Supporting Types
480
class StatusCondition:
481
"""StatusCondition describes why a cluster or a node pool has a certain status"""
482
code: str
483
message: str
484
485
class OperationProgress:
486
"""Information about operation (or operation stage) progress"""
487
name: str
488
status: str
489
stages: MutableSequence[OperationProgress]
490
491
class Status:
492
"""The Status type defines a logical error model"""
493
code: int
494
message: str
495
details: MutableSequence[Any]
496
497
class ListUsableSubnetworksPager:
498
"""Pager for list_usable_subnetworks results"""
499
def __iter__(self) -> Iterator[UsableSubnetwork]: ...
500
501
class Jwk:
502
"""JSON Web Key as specified by RFC 7517"""
503
kty: str
504
alg: str
505
use: str
506
kid: str
507
n: str
508
e: str
509
510
class AutopilotCompatibilityIssue:
511
"""AutopilotCompatibilityIssue contains information about a specific compatibility issue"""
512
last_observation: str
513
constraint_type: str
514
incompatibility_type: str
515
subjects: MutableSequence[str]
516
documentation: str
517
518
# Type aliases for common generic types
519
MutableSequence = typing.MutableSequence
520
MutableMapping = typing.MutableMapping
521
```