Google Cloud Run Client Library

0.16.0 · active · verified Sun Mar 29

The `google-cloud-run` Python library is the official client library for interacting with the Google Cloud Run Admin API. It enables developers to programmatically manage Cloud Run services and jobs, including deployment, configuration, and monitoring. Currently at version 0.16.0, this library is part of the larger `google-cloud-python` monorepo and receives frequent updates, typically with a release cadence aligning with other Google Cloud client libraries.

Warnings

gotcha The `google-cloud-run` library primarily targets the Cloud Run Admin API v2. Ensure you are using the correct client for the API version you intend to interact with, as API object structures and methods may differ significantly between v1 and v2, potentially leading to `TypeError` or unexpected behavior.
Fix: Consult the official client library documentation (e.g., `google.cloud.run_v2`) and the Cloud Run Admin API documentation to confirm the correct API version and client methods for your use case.
gotcha When constructing resource names for services or jobs (e.g., in `get_service` or `create_service` calls), ensure they follow the expected format: `projects/{project_id}/locations/{location}/services/{service_id}`. Incorrect formatting can result in `NotFound` or `InvalidArgument` errors.
Fix: Always use f-strings or `.format()` to construct resource names dynamically, ensuring all path components (project ID, location, service ID) are correctly included and ordered. For example, `parent = f"projects/{project_id}/locations/{location}"`.
gotcha The library uses standard Python logging, but by default, logging events are not handled, and logs may contain sensitive information. For visibility and security, you must explicitly configure logging or set the `GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable.
Fix: To enable default logging, set the `GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable to `google` or `google.cloud.run_v2`. For advanced configuration, use Python's `logging` module to set up handlers and formatters, e.g., `logging.basicConfig(level=logging.INFO)`.
gotcha Using the client library to manage Cloud Run resources requires appropriate IAM permissions on the Google Cloud project and specific resources. Lack of permissions will result in `PermissionDenied` errors.
Fix: Grant the service account or user credentials used by your application the necessary IAM roles, such as 'Cloud Run Admin' (`roles/run.admin`) or more granular roles like 'Cloud Run Developer' (`roles/run.developer`) for deployment, or 'Cloud Run Viewer' (`roles/run.viewer`) for read-only access.

Install

pip install google-cloud-run Install stable version

Imports

ServicesClient

from google.cloud.run_v2 import ServicesClient

JobsClient

from google.cloud.run_v2 import JobsClient

Quickstart

This quickstart demonstrates how to instantiate the `ServicesClient` and list existing Cloud Run services within a specified Google Cloud project and location. Ensure your environment is authenticated (e.g., via `gcloud auth application-default login` or by setting `GOOGLE_APPLICATION_CREDENTIALS`) and that `GOOGLE_CLOUD_PROJECT_ID` and `GOOGLE_CLOUD_LOCATION` environment variables are set.

import os
from google.cloud.run_v2 import ServicesClient

def list_cloud_run_services(project_id: str, location: str):
    """Lists Cloud Run services in a given project and location."""
    client = ServicesClient()
    parent = f"projects/{project_id}/locations/{location}"

    try:
        # Paged iteration over services
        print(f"Fetching services for parent: {parent}")
        for service in client.list_services(parent=parent):
            print(f"Service Name: {service.name}")
            print(f"  URI: {service.uri}")
            # You can access more service attributes here, e.g., service.traffic
            print("-" * 20)
    except Exception as e:
        print(f"Error listing services: {e}")

if __name__ == "__main__":
    # Set your Google Cloud Project ID and desired location
    # Ensure GOOGLE_APPLICATION_CREDENTIALS is set or you are running in a GCP environment
    # e.g., 'export GOOGLE_CLOUD_PROJECT_ID="your-project"'
    # e.g., 'export GOOGLE_CLOUD_LOCATION="us-central1"'
    project_id = os.environ.get("GOOGLE_CLOUD_PROJECT_ID", "your-project-id")
    location = os.environ.get("GOOGLE_CLOUD_LOCATION", "us-central1")

    if project_id == "your-project-id":
        print("Please set the GOOGLE_CLOUD_PROJECT_ID environment variable or replace 'your-project-id' in the script.")
    else:
        list_cloud_run_services(project_id, location)

view raw JSON →