{"id":986,"library":"google-cloud-container","title":"Google Cloud Container API Client Library","description":"The `google-cloud-container` Python client library provides programmatic access to the Google Kubernetes Engine (GKE) API. It allows developers to build and manage container-based applications using the open-source Kubernetes technology. The current version is 2.63.0, and it follows a frequent release cadence as part of the broader `google-cloud-python` monorepo.","status":"active","version":"2.63.0","language":"python","source_language":"en","source_url":"https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-container","tags":["google-cloud","gcp","kubernetes-engine","gke","container","cloud-native"],"install":[{"cmd":"pip install google-cloud-container","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core library for Google API clients","package":"google-api-core"},{"reason":"Handles authentication with Google Cloud services (implicitly via Application Default Credentials)","package":"google-auth"}],"imports":[{"note":"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.","wrong":"from google.cloud.container import ClusterManagerClient","symbol":"ContainerServiceClient","correct":"from google.cloud.container_v1 import ContainerServiceClient"}],"quickstart":{"code":"import os\nfrom google.cloud.container_v1 import ContainerServiceClient\nfrom google.api_core.exceptions import GoogleAPIError\n\ndef list_gke_clusters(project_id: str, location: str = \"-\"):\n    \"\"\"Lists all Google Kubernetes Engine clusters in a given project and location.\n\n    Args:\n        project_id: Your Google Cloud project ID.\n        location: The Google Cloud location (e.g., \"us-central1\" for a region,\n                  or \"us-central1-a\" for a zone). Use \"-\" for all locations.\n    \"\"\"\n    try:\n        client = ContainerServiceClient()\n        parent = f\"projects/{project_id}/locations/{location}\"\n        \n        # The list_clusters method is paginated, iterate through the responses\n        response = client.list_clusters(parent=parent)\n        \n        if response.clusters:\n            print(f\"Clusters in project '{project_id}' and location '{location}':\")\n            for cluster in response.clusters:\n                print(f\"- Name: {cluster.name}\")\n                print(f\"  Location: {cluster.location}\")\n                print(f\"  Status: {cluster.status.name}\")\n                print(f\"  Endpoint: {cluster.endpoint}\")\n        else:\n            print(f\"No clusters found in project '{project_id}' and location '{location}'.\")\n\n    except GoogleAPIError as e:\n        print(f\"An API error occurred: {e}\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")\n\nif __name__ == \"__main__\":\n    # Set your Google Cloud Project ID as an environment variable\n    # For local development, ensure GOOGLE_APPLICATION_CREDENTIALS is set\n    # or you've run `gcloud auth application-default login`\n    project_id = os.environ.get(\"GOOGLE_CLOUD_PROJECT\", \"your-gcp-project-id\")\n    \n    # Optionally specify a specific region or zone, e.g., \"us-central1\" or \"us-central1-a\"\n    # Use \"-\" to list clusters across all regions/zones\n    target_location = os.environ.get(\"GKE_LOCATION\", \"-\")\n\n    if project_id == \"your-gcp-project-id\":\n        print(\"Please set the 'GOOGLE_CLOUD_PROJECT' environment variable to your project ID.\")\n        print(\"For example: export GOOGLE_CLOUD_PROJECT='my-project-123'\")\n    else:\n        list_gke_clusters(project_id, target_location)\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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')`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"breaking","affected_versions":"<= 3.6"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Install only the specific `google-cloud-*` client libraries your application requires, such as `google-cloud-container` for GKE interactions.","message":"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.","severity":"deprecated","affected_versions":"All"},{"fix":"Upgrade your Python environment to an actively supported version. Google recommends Python 3.10 or newer.","message":"Python 3.9 has reached its end-of-life and is no longer actively supported by `google-cloud-container` and its core dependencies (`google.api_core`, `google.auth`). Using the library with Python 3.9 will result in `FutureWarning` messages regarding unsupported Python versions and can lead to critical runtime errors, such as `ImportError`, preventing the library from functioning correctly.","severity":"breaking","affected_versions":"3.9"},{"fix":"Update your import statement. For example, replace `from google.cloud.container_v1 import ContainerServiceClient` with `from google.cloud.container import ClusterManagerClient` or `from google.cloud.container_v1.services.cluster_manager import ClusterManagerClient`, and adjust subsequent code accordingly.","message":"The `ContainerServiceClient` class is no longer directly importable from `google.cloud.container_v1`. This class has been renamed to `ClusterManagerClient` and is typically imported from `google.cloud.container` or `google.cloud.container_v1.services.cluster_manager`.","severity":"breaking","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-05-12T22:14:24.095Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"fix":"Install the library using pip: `pip install google-cloud-container`","cause":"The `google-cloud-container` Python client library, or a dependency, is not installed in the active Python environment.","error":"ModuleNotFoundError: No module named 'google.cloud.container_v1'"},{"fix":"Grant the 'Kubernetes Engine Cluster Viewer' role (`roles/container.viewer`) or a more permissive role (like 'Kubernetes Engine Developer' or 'Owner') to the user or service account on the Google Cloud project or specific cluster.","cause":"The authenticated Google Cloud user or service account lacks the necessary IAM permissions to access or retrieve credentials for the specified GKE cluster.","error":"ERROR: (gcloud.container.clusters.get-credentials) ResponseError: code=403, message=Required \"container.clusters.get\" permission(s)"},{"fix":"Ensure your application is configured to listen on `0.0.0.0:$PORT` (where `$PORT` is the environment variable Cloud Run/GKE provides) and that it starts successfully and responds to health checks within the configured timeout. Inspect container logs for application-specific errors.","cause":"The application inside the deployed container (e.g., on GKE or Cloud Run) did not start a web server or an I/O-bound application that listens on the port specified by the `PORT` environment variable (default 8080) or failed its startup health checks.","error":"Container failed to start. Failed to start and then listen on the port defined by the PORT environment variable."}],"ecosystem":"pypi","meta_description":null,"install_score":0,"install_tag":"stale","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.64.0","cli_name":"","install_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"72.4M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":6.1,"import_time_s":null,"mem_mb":null,"disk_size":"70M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"77.5M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":5.2,"import_time_s":null,"mem_mb":null,"disk_size":"75M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"68.9M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":4.3,"import_time_s":null,"mem_mb":null,"disk_size":"67M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"68.5M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":4.5,"import_time_s":null,"mem_mb":null,"disk_size":"66M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"72.5M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":6.8,"import_time_s":null,"mem_mb":null,"disk_size":"70M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}