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
```