0
# Google Cloud Run
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: google-cloud-run
7
- **Language**: Python
8
- **Installation**: `pip install google-cloud-run`
9
- **Python Support**: Python >= 3.7
10

11
## Core Imports
12

13
```python
14
from google.cloud import run_v2
15
```
16

17
Import specific clients and types:
18

19
```python
20
from google.cloud.run_v2 import (
21
    ServicesClient, JobsClient, ExecutionsClient,
22
    TasksClient, RevisionsClient, BuildsClient, WorkerPoolsClient
23
)
24
```
25

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

28
```python
29
from google.cloud import run
30
# Then use as: run.ServicesClient(), run.JobsClient(), etc.
31
```
32

33
## Basic Usage
34

35
### Creating a Service
36

37
```python
38
from google.cloud import run_v2
39

40
# Create a client
41
client = run_v2.ServicesClient()
42

43
# Define service configuration
44
service = run_v2.Service()
45
service.template.containers = [
46
    run_v2.Container(
47
        image="gcr.io/my-project/my-app:latest",
48
        resources=run_v2.ResourceRequirements(
49
            limits={"cpu": "1", "memory": "1Gi"}
50
        )
51
    )
52
]
53

54
# Create the service
55
request = run_v2.CreateServiceRequest(
56
    parent="projects/my-project/locations/us-central1",
57
    service=service,
58
    service_id="my-service"
59
)
60

61
operation = client.create_service(request=request)
62
response = operation.result()  # Wait for completion
63
print(f"Service created: {response.name}")
64
```
65

66
### Running a Job
67

68
```python
69
from google.cloud import run_v2
70

71
# Create a client
72
client = run_v2.JobsClient()
73

74
# Define job configuration
75
job = run_v2.Job()
76
job.template.template.containers = [
77
    run_v2.Container(
78
        image="gcr.io/my-project/my-batch-job:latest",
79
        resources=run_v2.ResourceRequirements(
80
            limits={"cpu": "2", "memory": "4Gi"}
81
        )
82
    )
83
]
84

85
# Create the job
86
create_request = run_v2.CreateJobRequest(
87
    parent="projects/my-project/locations/us-central1",
88
    job=job,
89
    job_id="my-batch-job"
90
)
91

92
create_operation = client.create_job(request=create_request)
93
job_response = create_operation.result()
94

95
# Run the job
96
run_request = run_v2.RunJobRequest(name=job_response.name)
97
run_operation = client.run_job(request=run_request)
98
execution = run_operation.result()
99
print(f"Job execution started: {execution.name}")
100
```
101

102
## Architecture
103

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

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

114
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.
115

116
## Capabilities
117

118
### Service Management
119

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

122
```python { .api }
123
class ServicesClient:
124
    def create_service(self, request: CreateServiceRequest, **kwargs): ...
125
    def get_service(self, request: GetServiceRequest, **kwargs): ...
126
    def list_services(self, request: ListServicesRequest, **kwargs): ...
127
    def update_service(self, request: UpdateServiceRequest, **kwargs): ...
128
    def delete_service(self, request: DeleteServiceRequest, **kwargs): ...
129
    def get_iam_policy(self, request, **kwargs): ...
130
    def set_iam_policy(self, request, **kwargs): ...
131
    def test_iam_permissions(self, request, **kwargs): ...
132
```
133

134
[Service Management](./services.md)
135

136
### Job Management
137

138
Management of Cloud Run jobs for batch and scheduled workloads.
139

140
```python { .api }
141
class JobsClient:
142
    def create_job(self, request: CreateJobRequest, **kwargs): ...
143
    def get_job(self, request: GetJobRequest, **kwargs): ...
144
    def list_jobs(self, request: ListJobsRequest, **kwargs): ...
145
    def update_job(self, request: UpdateJobRequest, **kwargs): ...
146
    def delete_job(self, request: DeleteJobRequest, **kwargs): ...
147
    def run_job(self, request: RunJobRequest, **kwargs): ...
148
    def get_iam_policy(self, request, **kwargs): ...
149
    def set_iam_policy(self, request, **kwargs): ...
150
    def test_iam_permissions(self, request, **kwargs): ...
151
```
152

153
[Job Management](./jobs.md)
154

155
### Execution Management
156

157
Management of job executions and their lifecycle.
158

159
```python { .api }
160
class ExecutionsClient:
161
    def get_execution(self, request: GetExecutionRequest, **kwargs): ...
162
    def list_executions(self, request: ListExecutionsRequest, **kwargs): ...
163
    def delete_execution(self, request: DeleteExecutionRequest, **kwargs): ...
164
    def cancel_execution(self, request: CancelExecutionRequest, **kwargs): ...
165
```
166

167
[Execution Management](./executions.md)
168

169
### Task Management
170

171
Management of individual tasks within executions.
172

173
```python { .api }
174
class TasksClient:
175
    def get_task(self, request: GetTaskRequest, **kwargs): ...
176
    def list_tasks(self, request: ListTasksRequest, **kwargs): ...
177
```
178

179
[Task Management](./tasks.md)
180

181
### Revision Management
182

183
Management of service revisions and their lifecycle.
184

185
```python { .api }
186
class RevisionsClient:
187
    def get_revision(self, request: GetRevisionRequest, **kwargs): ...
188
    def list_revisions(self, request: ListRevisionsRequest, **kwargs): ...
189
    def delete_revision(self, request: DeleteRevisionRequest, **kwargs): ...
190
```
191

192
[Revision Management](./revisions.md)
193

194
### Build Management
195

196
Management of source code builds and deployments.
197

198
```python { .api }
199
class BuildsClient:
200
    def submit_build(self, request: SubmitBuildRequest, **kwargs): ...
201
```
202

203
[Build Management](./builds.md)
204

205
### Worker Pool Management
206

207
Management of worker pools for builds and other compute tasks.
208

209
```python { .api }
210
class WorkerPoolsClient:
211
    def create_worker_pool(self, request: CreateWorkerPoolRequest, **kwargs): ...
212
    def get_worker_pool(self, request: GetWorkerPoolRequest, **kwargs): ...
213
    def list_worker_pools(self, request: ListWorkerPoolsRequest, **kwargs): ...
214
    def update_worker_pool(self, request: UpdateWorkerPoolRequest, **kwargs): ...
215
    def delete_worker_pool(self, request: DeleteWorkerPoolRequest, **kwargs): ...
216
    def get_iam_policy(self, request, **kwargs): ...
217
    def set_iam_policy(self, request, **kwargs): ...
218
    def test_iam_permissions(self, request, **kwargs): ...
219
```
220

221
[Worker Pool Management](./worker-pools.md)
222

223
## Common Types
224

225
All clients use shared type definitions for configuration and requests.
226

227
### Core Resource Types
228

229
```python { .api }
230
class Service:
231
    """A Cloud Run service configuration."""
232
    
233
class Job:
234
    """A Cloud Run job configuration."""
235
    
236
class Execution:
237
    """A job execution instance."""
238
    
239
class Task:
240
    """An individual task within an execution."""
241
    
242
class Revision:
243
    """An immutable service configuration snapshot."""
244
    
245
class WorkerPool:
246
    """A managed worker pool for builds."""
247
```
248

249
### Container Configuration
250

251
```python { .api }
252
class Container:
253
    """Container specification for services and jobs."""
254
    image: str
255
    command: list[str]
256
    args: list[str]
257
    env: list[EnvVar]
258
    resources: ResourceRequirements
259
    ports: list[ContainerPort]
260
    volume_mounts: list[VolumeMount]
261
    
262
class ResourceRequirements:
263
    """CPU and memory resource specifications."""
264
    limits: dict[str, str]
265
    requests: dict[str, str]
266
    
267
class EnvVar:
268
    """Environment variable configuration."""
269
    name: str
270
    value: str
271
    value_source: EnvVarSource
272
```
273

274
### Scaling and Traffic Configuration
275

276
```python { .api }
277
class RevisionScaling:
278
    """Revision scaling configuration."""
279
    min_instance_count: int
280
    max_instance_count: int
281
    
282
class TrafficTarget:
283
    """Traffic routing configuration."""
284
    type: TrafficTargetAllocationType
285
    revision: str
286
    percent: int
287
    tag: str
288
```
289

290
## Error Handling
291

292
The library uses standard Google Cloud client library exceptions:
293

294
```python
295
from google.api_core import exceptions
296

297
try:
298
    response = client.get_service(request)
299
except exceptions.NotFound:
300
    print("Service not found")
301
except exceptions.PermissionDenied:
302
    print("Insufficient permissions")
303
except exceptions.InvalidArgument as e:
304
    print(f"Invalid request: {e}")
305
```
306

307
Common exception types:
308
- `NotFound`: Resource not found
309
- `PermissionDenied`: Insufficient permissions
310
- `InvalidArgument`: Invalid request parameters
311
- `DeadlineExceeded`: Request timeout
312
- `ResourceExhausted`: Rate limits exceeded