or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

builds.mdexecutions.mdindex.mdjobs.mdrevisions.mdservices.mdtasks.mdworker-pools.md
tile.json

index.mddocs/

Google Cloud Run

A comprehensive Python client library for Google Cloud Run, a managed compute platform that enables running containers invocable via requests or events. The library provides complete API access for managing Cloud Run services, jobs, executions, tasks, revisions, builds, and worker pools through both synchronous and asynchronous clients.

Package Information

  • Package Name: google-cloud-run
  • Language: Python
  • Installation: pip install google-cloud-run
  • Python Support: Python >= 3.7

Core Imports

from google.cloud import run_v2

Import specific clients and types:

from google.cloud.run_v2 import (
    ServicesClient, JobsClient, ExecutionsClient,
    TasksClient, RevisionsClient, BuildsClient, WorkerPoolsClient
)

Or import from the main package (which re-exports from run_v2):

from google.cloud import run
# Then use as: run.ServicesClient(), run.JobsClient(), etc.

Basic Usage

Creating a Service

from google.cloud import run_v2

# Create a client
client = run_v2.ServicesClient()

# Define service configuration
service = run_v2.Service()
service.template.containers = [
    run_v2.Container(
        image="gcr.io/my-project/my-app:latest",
        resources=run_v2.ResourceRequirements(
            limits={"cpu": "1", "memory": "1Gi"}
        )
    )
]

# Create the service
request = run_v2.CreateServiceRequest(
    parent="projects/my-project/locations/us-central1",
    service=service,
    service_id="my-service"
)

operation = client.create_service(request=request)
response = operation.result()  # Wait for completion
print(f"Service created: {response.name}")

Running a Job

from google.cloud import run_v2

# Create a client
client = run_v2.JobsClient()

# Define job configuration
job = run_v2.Job()
job.template.template.containers = [
    run_v2.Container(
        image="gcr.io/my-project/my-batch-job:latest",
        resources=run_v2.ResourceRequirements(
            limits={"cpu": "2", "memory": "4Gi"}
        )
    )
]

# Create the job
create_request = run_v2.CreateJobRequest(
    parent="projects/my-project/locations/us-central1",
    job=job,
    job_id="my-batch-job"
)

create_operation = client.create_job(request=create_request)
job_response = create_operation.result()

# Run the job
run_request = run_v2.RunJobRequest(name=job_response.name)
run_operation = client.run_job(request=run_request)
execution = run_operation.result()
print(f"Job execution started: {execution.name}")

Architecture

The Google Cloud Run API is organized around several key resource types:

  • Services: Stateless HTTP services that auto-scale to handle requests
  • Jobs: Batch workloads that run to completion
  • Executions: Individual runs of a job
  • Tasks: Individual units of work within an execution
  • Revisions: Immutable snapshots of service configurations
  • Builds: Source code builds for deployment
  • Worker Pools: Managed compute resources for builds

Each resource type has dedicated client classes with both synchronous and asynchronous versions, following Google Cloud client library patterns with support for pagination, long-running operations, and IAM management.

Capabilities

Service Management

Comprehensive management of Cloud Run services including creation, updates, traffic routing, and scaling configuration.

class ServicesClient:
    def create_service(self, request: CreateServiceRequest, **kwargs): ...
    def get_service(self, request: GetServiceRequest, **kwargs): ...
    def list_services(self, request: ListServicesRequest, **kwargs): ...
    def update_service(self, request: UpdateServiceRequest, **kwargs): ...
    def delete_service(self, request: DeleteServiceRequest, **kwargs): ...
    def get_iam_policy(self, request, **kwargs): ...
    def set_iam_policy(self, request, **kwargs): ...
    def test_iam_permissions(self, request, **kwargs): ...

Service Management

Job Management

Management of Cloud Run jobs for batch and scheduled workloads.

class JobsClient:
    def create_job(self, request: CreateJobRequest, **kwargs): ...
    def get_job(self, request: GetJobRequest, **kwargs): ...
    def list_jobs(self, request: ListJobsRequest, **kwargs): ...
    def update_job(self, request: UpdateJobRequest, **kwargs): ...
    def delete_job(self, request: DeleteJobRequest, **kwargs): ...
    def run_job(self, request: RunJobRequest, **kwargs): ...
    def get_iam_policy(self, request, **kwargs): ...
    def set_iam_policy(self, request, **kwargs): ...
    def test_iam_permissions(self, request, **kwargs): ...

Job Management

Execution Management

Management of job executions and their lifecycle.

class ExecutionsClient:
    def get_execution(self, request: GetExecutionRequest, **kwargs): ...
    def list_executions(self, request: ListExecutionsRequest, **kwargs): ...
    def delete_execution(self, request: DeleteExecutionRequest, **kwargs): ...
    def cancel_execution(self, request: CancelExecutionRequest, **kwargs): ...

Execution Management

Task Management

Management of individual tasks within executions.

class TasksClient:
    def get_task(self, request: GetTaskRequest, **kwargs): ...
    def list_tasks(self, request: ListTasksRequest, **kwargs): ...

Task Management

Revision Management

Management of service revisions and their lifecycle.

class RevisionsClient:
    def get_revision(self, request: GetRevisionRequest, **kwargs): ...
    def list_revisions(self, request: ListRevisionsRequest, **kwargs): ...
    def delete_revision(self, request: DeleteRevisionRequest, **kwargs): ...

Revision Management

Build Management

Management of source code builds and deployments.

class BuildsClient:
    def submit_build(self, request: SubmitBuildRequest, **kwargs): ...

Build Management

Worker Pool Management

Management of worker pools for builds and other compute tasks.

class WorkerPoolsClient:
    def create_worker_pool(self, request: CreateWorkerPoolRequest, **kwargs): ...
    def get_worker_pool(self, request: GetWorkerPoolRequest, **kwargs): ...
    def list_worker_pools(self, request: ListWorkerPoolsRequest, **kwargs): ...
    def update_worker_pool(self, request: UpdateWorkerPoolRequest, **kwargs): ...
    def delete_worker_pool(self, request: DeleteWorkerPoolRequest, **kwargs): ...
    def get_iam_policy(self, request, **kwargs): ...
    def set_iam_policy(self, request, **kwargs): ...
    def test_iam_permissions(self, request, **kwargs): ...

Worker Pool Management

Common Types

All clients use shared type definitions for configuration and requests.

Core Resource Types

class Service:
    """A Cloud Run service configuration."""
    
class Job:
    """A Cloud Run job configuration."""
    
class Execution:
    """A job execution instance."""
    
class Task:
    """An individual task within an execution."""
    
class Revision:
    """An immutable service configuration snapshot."""
    
class WorkerPool:
    """A managed worker pool for builds."""

Container Configuration

class Container:
    """Container specification for services and jobs."""
    image: str
    command: list[str]
    args: list[str]
    env: list[EnvVar]
    resources: ResourceRequirements
    ports: list[ContainerPort]
    volume_mounts: list[VolumeMount]
    
class ResourceRequirements:
    """CPU and memory resource specifications."""
    limits: dict[str, str]
    requests: dict[str, str]
    
class EnvVar:
    """Environment variable configuration."""
    name: str
    value: str
    value_source: EnvVarSource

Scaling and Traffic Configuration

class RevisionScaling:
    """Revision scaling configuration."""
    min_instance_count: int
    max_instance_count: int
    
class TrafficTarget:
    """Traffic routing configuration."""
    type: TrafficTargetAllocationType
    revision: str
    percent: int
    tag: str

Error Handling

The library uses standard Google Cloud client library exceptions:

from google.api_core import exceptions

try:
    response = client.get_service(request)
except exceptions.NotFound:
    print("Service not found")
except exceptions.PermissionDenied:
    print("Insufficient permissions")
except exceptions.InvalidArgument as e:
    print(f"Invalid request: {e}")

Common exception types:

  • NotFound: Resource not found
  • PermissionDenied: Insufficient permissions
  • InvalidArgument: Invalid request parameters
  • DeadlineExceeded: Request timeout
  • ResourceExhausted: Rate limits exceeded