Google Cloud Container API Client Library

Warnings

• gotcha Always use Application Default Credentials (ADC) for authentication. Avoid hardcoding service account key files, embedding them in Docker images, or committing them to source control. For local development, use `gcloud auth application-default login`. For deployed services, rely on attached service accounts or Workload Identity.
  Fix: Configure ADC properly for your environment. Use environment variables like `GOOGLE_APPLICATION_CREDENTIALS` only when absolutely necessary (e.g., CI/CD outside GCP with temporary keys), and ensure they are securely managed.
• gotcha When interacting with GKE regional clusters, the `get_cluster` or `list_clusters` methods require specifying the `name` or `parent` field with the region, not the `zone` field. Using `zone` for a regional cluster will result in an `InvalidArgument` error.
  Fix: For regional clusters, construct the `parent` parameter as `projects/{project_id}/locations/{region}`. For example, `client.list_clusters(parent='projects/my-project/locations/us-central1')`.
• breaking The `google-cloud-container` library, like other `google-cloud-python` libraries, no longer supports Python versions older than 3.7. Attempting to use it with Python 3.6 or earlier will lead to installation or runtime errors.
  Fix: Upgrade your Python environment to version 3.7 or newer. Python 3.7 is the minimum requirement, but generally, it's recommended to use actively maintained Python versions.
• gotcha The logging events from this library (and other `google-cloud-python` libraries) are subject to change. Google may refine the occurrence, level, and content of various log messages without flagging these changes as breaking. Do not depend on the immutability of specific logging events for application logic.
  Fix: While logging can be useful for debugging, avoid building critical application logic that relies on the exact format or content of log messages from the client library. Implement robust error handling based on API responses and exceptions.
• deprecated It is not recommended to install the monolithic `google-api-python-client` package if you only need specific Google Cloud services. This approach leads to larger distribution sizes and can complicate dependency management.
  Fix: Install only the specific `google-cloud-*` client libraries your application requires, such as `google-cloud-container` for GKE interactions.

Install

• pip install google-cloud-container Install stable version

Imports

• ContainerServiceClient

  from google.cloud.container_v1 import ContainerServiceClient

  While `ClusterManagerClient` might appear in older examples or internal contexts, `ContainerServiceClient` from the versioned `_v1` module is the idiomatic and recommended client for the GKE API.

Quickstart

Initializes the Google Kubernetes Engine client and lists all clusters within a specified Google Cloud project and location (zone/region), demonstrating basic connectivity and resource retrieval. Authentication is handled automatically via Application Default Credentials (ADC) from the environment or `gcloud` CLI.

import os
from google.cloud.container_v1 import ContainerServiceClient
from google.api_core.exceptions import GoogleAPIError

def list_gke_clusters(project_id: str, location: str = "-"):
    """Lists all Google Kubernetes Engine clusters in a given project and location.

    Args:
        project_id: Your Google Cloud project ID.
        location: The Google Cloud location (e.g., "us-central1" for a region,
                  or "us-central1-a" for a zone). Use "-" for all locations.
    """
    try:
        client = ContainerServiceClient()
        parent = f"projects/{project_id}/locations/{location}"
        
        # The list_clusters method is paginated, iterate through the responses
        response = client.list_clusters(parent=parent)
        
        if response.clusters:
            print(f"Clusters in project '{project_id}' and location '{location}':")
            for cluster in response.clusters:
                print(f"- Name: {cluster.name}")
                print(f"  Location: {cluster.location}")
                print(f"  Status: {cluster.status.name}")
                print(f"  Endpoint: {cluster.endpoint}")
        else:
            print(f"No clusters found in project '{project_id}' and location '{location}'.")

    except GoogleAPIError as e:
        print(f"An API error occurred: {e}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

if __name__ == "__main__":
    # Set your Google Cloud Project ID as an environment variable
    # For local development, ensure GOOGLE_APPLICATION_CREDENTIALS is set
    # or you've run `gcloud auth application-default login`
    project_id = os.environ.get("GOOGLE_CLOUD_PROJECT", "your-gcp-project-id")
    
    # Optionally specify a specific region or zone, e.g., "us-central1" or "us-central1-a"
    # Use "-" to list clusters across all regions/zones
    target_location = os.environ.get("GKE_LOCATION", "-")

    if project_id == "your-gcp-project-id":
        print("Please set the 'GOOGLE_CLOUD_PROJECT' environment variable to your project ID.")
        print("For example: export GOOGLE_CLOUD_PROJECT='my-project-123'")
    else:
        list_gke_clusters(project_id, target_location)