chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,374 @@
|
||||
---
|
||||
name: cloud-run-basics
|
||||
description: Manages Cloud Run services, jobs, and worker pools. Use when you need to deploy applications responding to HTTP requests (services), run event-triggered or scheduled tasks (jobs), or handle always-on pull-based background processing (worker pools).
|
||||
source: google/skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Cloud Run Basics
|
||||
|
||||
Cloud Run is a fully managed application platform for running your code,
|
||||
function, or container on top of Google's highly scalable infrastructure. It
|
||||
abstracts away infrastructure management, providing three primary resource
|
||||
types:
|
||||
|
||||
1. **Services:** Responds to HTTP requests sent to a unique and stable
|
||||
endpoint, using stateless instances that autoscale based on a variety of key
|
||||
metrics, also responds to events and functions.
|
||||
2. **Jobs:** Executes parallelizable tasks that are executed manually, or on a
|
||||
schedule, and run to completion.
|
||||
3. **Worker pools:** Handles always-on background workloads such as pull-based
|
||||
workloads, for example, Kafka consumers, Pub/Sub pull queues, or RabbitMQ
|
||||
consumers.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. Enable the Cloud Run Admin API and Cloud Build APIs:
|
||||
|
||||
```bash
|
||||
gcloud services enable run.googleapis.com cloudbuild.googleapis.com --quiet
|
||||
```
|
||||
|
||||
1. If you are under a domain restriction organization policy [restricting](https://docs.cloud.google.com/organization-policy/restrict-domains)
|
||||
unauthenticated invocations for your project, you will need to access your
|
||||
deployed service as described under [Testing private
|
||||
services](https://docs.cloud.google.com/run/docs/triggering/https-request#testing-private).
|
||||
|
||||
### Required roles
|
||||
|
||||
You need the following roles to deploy your Cloud Run resource:
|
||||
|
||||
* Cloud Run Admin (`roles/run.admin`) on the project
|
||||
* Cloud Run Source Developer (`roles/run.sourceDeveloper`) on the project
|
||||
* Service Account User (`roles/iam.serviceAccountUser`) on the service
|
||||
identity
|
||||
* Logs Viewer (`roles/logging.viewer`) on the project
|
||||
|
||||
Cloud Build automatically uses the Compute Engine default service account as the
|
||||
default Cloud Build service account to build your source code and Cloud Run
|
||||
resource, unless you override this behavior.
|
||||
|
||||
For Cloud Build to build your sources, grant the Cloud Build service account the
|
||||
Cloud Run Builder (`roles/run.builder`) role on your project:
|
||||
|
||||
```bash
|
||||
gcloud projects add-iam-policy-binding PROJECT_ID \
|
||||
--member=serviceAccount:SERVICE_ACCOUNT_EMAIL_ADDRESS \
|
||||
--role=roles/run.builder \
|
||||
--quiet
|
||||
```
|
||||
|
||||
Replace `PROJECT_ID` with your Google Cloud project ID and
|
||||
`SERVICE_ACCOUNT_EMAIL_ADDRESS` with the email address of the Cloud Build
|
||||
service account.
|
||||
|
||||
## Deploy a Cloud Run service
|
||||
|
||||
You can deploy your service to Cloud Run by using a container image or deploy
|
||||
directly from source code using a single Google Cloud CLI command.
|
||||
|
||||
> **CRITICAL RULE:** Any deployed code MUST listen on 0.0.0.0 (not 127.0.0.1)
|
||||
> and use the injected $PORT environment variable (defaults to 8080), or it will
|
||||
> crash on boot.
|
||||
|
||||
### Deploy a container image to Cloud Run
|
||||
|
||||
Cloud Run imports your container image during deployment. Cloud Run keeps this
|
||||
copy of the container image as long as it is used by a serving revision.
|
||||
Container images are not pulled from their container repository when a new Cloud
|
||||
Run instance is started.
|
||||
|
||||
### Supported container images
|
||||
|
||||
You can directly use container images stored in the [Artifact
|
||||
Registry](https://docs.cloud.google.com/artifact-registry/docs/overview), or
|
||||
[Docker Hub](https://hub.docker.com/). Google recommends the use of Artifact
|
||||
Registry since Docker Hub images are
|
||||
[cached](https://docs.cloud.google.com/artifact-registry/docs/pull-cached-dockerhub-images)
|
||||
for up to one hour.
|
||||
|
||||
You can use container images from other public or private registries (like JFrog
|
||||
Artifactory, Nexus, or GitHub Container Registry), by setting up an [Artifact
|
||||
Registry remote
|
||||
repository](https://docs.cloud.google.com/artifact-registry/docs/repositories/remote-repo).
|
||||
|
||||
You should only consider [Docker Hub](https://hub.docker.com/) for deploying
|
||||
popular container images such as [Docker Official
|
||||
Images](https://docs.docker.com/docker-hub/official_images/) or [Docker
|
||||
Sponsored OSS images](https://docs.docker.com/docker-hub/dsos-program/). For
|
||||
higher availability, Google recommends deploying these Docker Hub images using
|
||||
an [Artifact Registry remote
|
||||
repository](https://docs.cloud.google.com/artifact-registry/docs/repositories/remote-repo).
|
||||
|
||||
To deploy a container image, run the following command:
|
||||
|
||||
```bash
|
||||
gcloud run deploy SERVICE_NAME \
|
||||
--image IMAGE_URL \
|
||||
--region us-central1 \
|
||||
--allow-unauthenticated \
|
||||
--quiet
|
||||
```
|
||||
|
||||
Replace the following:
|
||||
|
||||
* SERVICE_NAME: the name of the service you want to deploy to. Service names
|
||||
must be 49 characters or less and must be unique per region and project. If
|
||||
the service does not exist yet, this command creates the service during the
|
||||
deployment. You can omit this parameter entirely, but you will be prompted
|
||||
for the service name if you omit it.
|
||||
* IMAGE_URL: a reference to the container image, for example,
|
||||
`us-docker.pkg.dev/cloudrun/container/hello:latest`. If you use Artifact
|
||||
Registry, the repository REPO_NAME must already be created. The URL follows
|
||||
the format of `LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG`. Note
|
||||
that if you don't supply the `--image` flag, the deploy command will attempt
|
||||
to deploy from source code.
|
||||
|
||||
### Deploy from source code
|
||||
|
||||
There are two different ways to deploy your service from source:
|
||||
|
||||
* Deploy from source with build (default): This option uses Google Cloud's
|
||||
buildpacks and Cloud Build to automatically build container images from your
|
||||
source code without having to install Docker on your machine or set up
|
||||
buildpacks or Cloud Build. By default, Cloud Run uses the default machine
|
||||
type provided by Cloud Build.
|
||||
|
||||
* To deploy from source with automatic base image updates enabled, run the
|
||||
following command:
|
||||
|
||||
```bash
|
||||
gcloud run deploy SERVICE_NAME --source . \
|
||||
--base-image BASE_IMAGE \
|
||||
--automatic-updates \
|
||||
--quiet
|
||||
```
|
||||
|
||||
Cloud Run only supports automatic base images that use [Google Cloud's
|
||||
buildpacks base
|
||||
images](https://docs.cloud.google.com/docs/buildpacks/base-images).
|
||||
|
||||
* To deploy from source using a Dockerfile, run the following command:
|
||||
|
||||
```bash
|
||||
gcloud run deploy SERVICE_NAME --source . --quiet
|
||||
```
|
||||
When you provide a Dockerfile, Cloud Build runs it in the cloud, and
|
||||
deploys the service.
|
||||
|
||||
* Deploy from source without build (Preview): This option deploys artifacts
|
||||
directly to Cloud Run, bypassing the Cloud Build step. This allows for rapid
|
||||
deployment times. To deploy from source without build, run the following
|
||||
command:
|
||||
|
||||
```bash
|
||||
gcloud beta run deploy SERVICE_NAME \
|
||||
--source APPLICATION_PATH \
|
||||
--no-build \
|
||||
--base-image=BASE_IMAGE \
|
||||
--command=COMMAND \
|
||||
--args=ARG \
|
||||
--quiet
|
||||
```
|
||||
|
||||
Replace the following:
|
||||
|
||||
* SERVICE_NAME: the name of your Cloud Run service.
|
||||
* APPLICATION_PATH: the location of your application on the local file
|
||||
system.
|
||||
* BASE_IMAGE: the [runtime base image](https://docs.cloud.google.com/run/docs/configuring/services/runtime-base-images#how_to_obtain_base_images)
|
||||
you want to use for your application. For example,
|
||||
`us-central1-docker.pkg.dev/serverless-runtimes/google-24-full/runtimes/nodejs24`.
|
||||
You can also deploy a pre-compiled binary without configuring additional
|
||||
language-specific runtime components using the OS only base image, such
|
||||
as `osonly24`.
|
||||
* COMMAND: the command that the container starts up with.
|
||||
* ARG: an argument you send to the container command. If you use multiple
|
||||
arguments, specify each on its own line.
|
||||
|
||||
For examples on deploying from source without build, see [Examples of
|
||||
deploying from source without
|
||||
build](https://docs.cloud.google.com/run/docs/deploying-source-code#examples-without-build).
|
||||
|
||||
## Create and execute a Cloud Run job
|
||||
|
||||
To create a new job, run the following command:
|
||||
|
||||
```bash
|
||||
gcloud run jobs create JOB_NAME --image IMAGE_URL OPTIONS --quiet
|
||||
```
|
||||
|
||||
Alternatively, use the deploy command:
|
||||
|
||||
```bash
|
||||
gcloud run jobs deploy JOB_NAME --image IMAGE_URL OPTIONS --quiet
|
||||
```
|
||||
|
||||
Replace the following:
|
||||
|
||||
* JOB_NAME: the name of the job you want to create. If you omit this
|
||||
parameter, you will be prompted for the job name when you run the command.
|
||||
* IMAGE_URL: a reference to the container image—for example,
|
||||
`us-docker.pkg.dev/cloudrun/container/job:latest`.
|
||||
|
||||
* Optionally, replace OPTIONS with any of the following flags:
|
||||
|
||||
* `--tasks`: Accepts integers greater or equal to 1. Defaults to 1;
|
||||
maximum is 10,000. Each task is provided the environment variables
|
||||
`CLOUD_RUN_TASK_INDEX` with a value between 0 and the number of tasks
|
||||
minus 1, along with `CLOUD_RUN_TASK_COUNT`, which is the number of
|
||||
tasks.
|
||||
* `--max-retries`: The number of times a failed task is retried. Once any
|
||||
task fails beyond this limit, the entire job is marked as failed. For
|
||||
example, if set to 1, a failed task will be retried once, for a total of
|
||||
two attempts. The default is 3. Accepts integers from 0 to 10.
|
||||
* `--task-timeout`: Accepts a duration like "2s". Defaults to 10 minutes;
|
||||
maximum is 168 hours (7 days). For tasks using GPUs, the maximum
|
||||
available timeout is 1 hour.
|
||||
* `--parallelism`: The maximum number of tasks that can execute in
|
||||
parallel. By default, tasks will be started as quickly as possible in
|
||||
parallel.
|
||||
* --execute-now: If set, immediately after the job is created, a job
|
||||
execution is started. Equivalent to calling `gcloud run jobs create`
|
||||
followed by `gcloud run jobs execute`.
|
||||
|
||||
In addition to these preceding options, you also specify more configuration
|
||||
such as environment variables or memory limits.
|
||||
|
||||
For a full list of available options when creating a job, refer to the [`gcloud
|
||||
run jobs
|
||||
create`](https://docs.cloud.google.com/sdk/gcloud/reference/run/jobs/create)
|
||||
command line documentation.
|
||||
|
||||
Wait for the job creation to finish. You'll see a success message upon a
|
||||
successful completion.
|
||||
|
||||
To execute an existing job, run the following command:
|
||||
|
||||
```bash
|
||||
gcloud run jobs execute JOB_NAME --quiet
|
||||
```
|
||||
|
||||
If you want the command to wait until the execution completes, run the following
|
||||
command:
|
||||
|
||||
```bash
|
||||
gcloud run jobs execute JOB_NAME --wait --region=REGION --quiet
|
||||
```
|
||||
|
||||
Replace the following:
|
||||
|
||||
* JOB_NAME: the name of the job.
|
||||
* REGION: the region in which the resource can be found. For example,
|
||||
`europe-west1`. Alternatively, set the `run/region` property.
|
||||
|
||||
## Deploy a worker pool
|
||||
|
||||
You can deploy a Cloud Run worker pool using container images or deploy directly
|
||||
from the source.
|
||||
|
||||
### Deploy a container image
|
||||
|
||||
You can specify a container image with a tag (for example,
|
||||
`us-docker.pkg.dev/my-project/container/my-image:latest`) or with an exact
|
||||
digest (for example,
|
||||
`us-docker.pkg.dev/my-project/container/my-image@sha256:41f34ab970ee...`).
|
||||
|
||||
### Supported container images
|
||||
|
||||
You can directly use container images stored in the [Artifact
|
||||
Registry](https://docs.cloud.google.com/artifact-registry/docs/overview), or
|
||||
[Docker Hub](https://hub.docker.com/). Google recommends the use of Artifact
|
||||
Registry since Docker Hub images are
|
||||
[cached](https://docs.cloud.google.com/artifact-registry/docs/pull-cached-dockerhub-images)
|
||||
for up to one hour.
|
||||
|
||||
You can use container images from other public or private registries (like JFrog
|
||||
Artifactory, Nexus, or GitHub Container Registry), by setting up an [Artifact
|
||||
Registry remote
|
||||
repository](https://docs.cloud.google.com/artifact-registry/docs/repositories/remote-repo).
|
||||
|
||||
You should only consider [Docker Hub](https://hub.docker.com/) for deploying
|
||||
popular container images such as [Docker Official
|
||||
Images](https://docs.docker.com/docker-hub/official_images/) or [Docker
|
||||
Sponsored OSS images](https://docs.docker.com/docker-hub/dsos-program/). For
|
||||
higher availability, Google recommends deploying these Docker Hub images using
|
||||
an [Artifact Registry remote
|
||||
repository](https://docs.cloud.google.com/artifact-registry/docs/repositories/remote-repo).
|
||||
|
||||
To deploy a container image, run the following command:
|
||||
|
||||
```bash
|
||||
gcloud run worker-pools deploy WORKER_POOL_NAME --image IMAGE_URL --quiet
|
||||
```
|
||||
|
||||
Replace the following:
|
||||
|
||||
* WORKER_POOL_NAME: the name of the worker pool you want to deploy to. If the
|
||||
worker pool does not exist yet, this command creates the worker pool during
|
||||
the deployment. You can omit this parameter entirely, but you will be
|
||||
prompted for the worker pool name if you omit it.
|
||||
|
||||
* IMAGE_URL: a reference to the container image that contains the worker pool,
|
||||
such as `us-docker.pkg.dev/cloudrun/container/worker-pool:latest`. Note that
|
||||
if you don't supply the `--image` flag, the deploy command attempts to
|
||||
deploy from source code.
|
||||
|
||||
Wait for the deployment to finish. Upon successful completion, Cloud Run
|
||||
displays a success message along with the revision information about the
|
||||
deployed worker pool.
|
||||
|
||||
### Deploy a worker pool from source
|
||||
|
||||
You can deploy a new worker pool or worker pool revision to Cloud Run directly
|
||||
from source code using a single gcloud CLI command, `gcloud run worker-pools`
|
||||
deploy with the `--source` flag.
|
||||
|
||||
The deploy command defaults to source deployment if you don't supply the
|
||||
`--image` or `--source` flags.
|
||||
|
||||
Behind the scenes, this command uses [Google Cloud's
|
||||
buildpacks](https://docs.cloud.google.com/docs/buildpacks/overview) and Cloud
|
||||
Build to automatically build container images from your source code without
|
||||
having to install Docker on your machine or set up buildpacks or Cloud Build. By
|
||||
default, Cloud Run uses the default machine type provided by Cloud Build.
|
||||
|
||||
To deploy a worker pool from source, run the following command:
|
||||
|
||||
```bash
|
||||
gcloud run worker-pools deploy WORKER_POOL_NAME --source . --quiet
|
||||
```
|
||||
|
||||
Replace `WORKER_POOL_NAME` with the name you want for your worker pool.
|
||||
|
||||
### What to do if a deployment fails:
|
||||
|
||||
1. **IAM/Permission Error:** Read
|
||||
[iam-security.md](references/iam-security.md).
|
||||
2. **Crash on Boot / Healthcheck failed:** Fetch the logs immediately using
|
||||
`gcloud logging read "resource.labels.service_name=SERVICE_NAME" --limit=20`
|
||||
to find the exact runtime error.
|
||||
3. **Native Dependency Error (Node/Python):** If using `--no-build`, switch to
|
||||
`--source .` (Buildpacks) to compile native extensions properly for Linux.
|
||||
|
||||
## Reference Directory
|
||||
|
||||
- [Core Concepts](references/core-concepts.md): Services vs. Jobs vs.
|
||||
Worker pools, resource model, and auto-scaling behavior for services.
|
||||
|
||||
- [CLI Usage](references/cli-usage.md): Essential `gcloud run` commands for
|
||||
deployment and management.
|
||||
|
||||
- [Client Libraries](references/client-library-usage.md): Using Google
|
||||
Cloud client libraries to interact with Cloud Run.
|
||||
|
||||
- [MCP Usage](references/mcp-usage.md): Using the Cloud Run remote MCP
|
||||
server.
|
||||
|
||||
- [Infrastructure as Code](references/iac-usage.md): Terraform examples for
|
||||
services, jobs, worker pools, and IAM bindings.
|
||||
|
||||
- [IAM & Security](references/iam-security.md): Roles, service identities,
|
||||
and ingress/egress controls.
|
||||
|
||||
*If you need product information not found in these references, use the
|
||||
Developer Knowledge MCP server `search_documents` tool.*
|
||||
@@ -0,0 +1,119 @@
|
||||
# Cloud Run CLI
|
||||
|
||||
Use the `gcloud run` command to manage your Cloud Run applications.
|
||||
|
||||
## Basic Syntax
|
||||
|
||||
```bash
|
||||
gcloud run [GROUP] [COMMAND] [FLAGS]
|
||||
```
|
||||
|
||||
## Essential Commands
|
||||
|
||||
### Cloud Run service
|
||||
|
||||
- **Deploy a service from an image:**
|
||||
|
||||
```bash
|
||||
gcloud run deploy my-service \
|
||||
--image us-docker.pkg.dev/cloudrun/container/hello:latest \
|
||||
--quiet
|
||||
```
|
||||
|
||||
- **Deploy from source code:**
|
||||
|
||||
```bash
|
||||
gcloud run deploy my-service --source . --quiet
|
||||
```
|
||||
|
||||
- **Deploy a Cloud Run function:**
|
||||
|
||||
```bash
|
||||
gcloud run deploy my-service
|
||||
--source . --function example-hello --base-image go126 --region us-central1 --quiet
|
||||
```
|
||||
|
||||
- **List services:**
|
||||
|
||||
```bash
|
||||
gcloud run services list --quiet
|
||||
```
|
||||
|
||||
- **Update traffic split:**
|
||||
|
||||
```bash
|
||||
gcloud run services update-traffic my-service --to-revisions=REV1=50,REV2=50 --quiet
|
||||
```
|
||||
|
||||
### Cloud Run job
|
||||
|
||||
- **Create a job:**
|
||||
|
||||
```bash
|
||||
gcloud run jobs create my-job \
|
||||
--image us-docker.pkg.dev/cloudrun/container/job:latest \
|
||||
--quiet
|
||||
```
|
||||
|
||||
- **Execute a job:**
|
||||
|
||||
```bash
|
||||
gcloud run jobs execute my-job --quiet
|
||||
```
|
||||
|
||||
- **List jobs:** `gcloud run jobs list`
|
||||
|
||||
- **List job executions:**
|
||||
|
||||
```bash
|
||||
gcloud run executions list --job my-job
|
||||
```
|
||||
|
||||
### Cloud Run worker pools
|
||||
|
||||
- **Deploy a worker pool from an image:**
|
||||
|
||||
```bash
|
||||
gcloud run worker-pools deploy my-workerpool \
|
||||
--image us-docker.pkg.dev/cloudrun/container/worker-pool:latest \
|
||||
--quiet
|
||||
```
|
||||
|
||||
- **Deploy from source code:**
|
||||
|
||||
```bash
|
||||
gcloud run worker-pools deploy my-workerpool --source . --quiet
|
||||
```
|
||||
|
||||
- **List worker pools:**
|
||||
|
||||
```bash
|
||||
gcloud run worker-pools list --region us-central1 --quiet
|
||||
```
|
||||
|
||||
- **Configure scaling (manual):**
|
||||
|
||||
```bash
|
||||
gcloud run worker-pools deploy my-workerpool --instances=5 \
|
||||
--image us-docker.pkg.dev/cloudrun/container/worker-pool:latest \
|
||||
--quiet
|
||||
```
|
||||
|
||||
### Configuration and logs
|
||||
|
||||
- **View more details about a service:** `gcloud run services describe my-service`
|
||||
|
||||
- **View logs:**
|
||||
|
||||
```bash
|
||||
gcloud logging read "resource.type=cloud_run_revision AND \
|
||||
resource.labels.service_name=my-service" \
|
||||
--quiet
|
||||
```
|
||||
|
||||
## Common Flags
|
||||
|
||||
- `--region`: The region where the service or job is located.
|
||||
- `--allow-unauthenticated`: Makes the service publicly accessible.
|
||||
|
||||
- `--no-allow-unauthenticated`: Restricts access to authenticated users only.
|
||||
+146
@@ -0,0 +1,146 @@
|
||||
# Cloud Run Client Libraries
|
||||
|
||||
Google Cloud client libraries provide an idiomatic way to manage Cloud Run
|
||||
resources programmatically.
|
||||
|
||||
## Getting Started
|
||||
|
||||
Ensure you have the Google Cloud SDK installed and authenticated.
|
||||
[Install Google Cloud SDK](https://cloud.google.com/sdk/docs/install)
|
||||
|
||||
### Python
|
||||
|
||||
- **Installation:**
|
||||
|
||||
```bash
|
||||
pip install --upgrade google-cloud-run
|
||||
```
|
||||
|
||||
- **Usage Example:**
|
||||
|
||||
```python
|
||||
from google.cloud import run_v2
|
||||
client = run_v2.ServicesClient()
|
||||
request = run_v2.ListServicesRequest(
|
||||
parent="projects/my-project/locations/us-central1"
|
||||
)
|
||||
page_result = client.list_services(request=request)
|
||||
```
|
||||
|
||||
- [Python Reference](https://docs.cloud.google.com/python/docs/reference/run/latest)
|
||||
|
||||
### Java
|
||||
|
||||
- **Maven Dependency:**
|
||||
|
||||
```xml
|
||||
<dependencyManagement>
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>com.google.cloud</groupId>
|
||||
<artifactId>libraries-bom</artifactId>
|
||||
<version>26.79.0</version>
|
||||
<type>pom</type>
|
||||
<scope>import</scope>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
</dependencyManagement>
|
||||
<dependency>
|
||||
<groupId>com.google.cloud</groupId>
|
||||
<artifactId>google-cloud-run</artifactId>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
- **Usage Example:**
|
||||
|
||||
```java
|
||||
try (ServicesClient servicesClient = ServicesClient.create()) {
|
||||
ListServicesRequest request = ListServicesRequest.newBuilder()
|
||||
.setParent(LocationName.of("my-project", "us-central1").toString())
|
||||
.build();
|
||||
for (Service element : servicesClient.listServices(request).iterateAll()) {
|
||||
System.out.println(element.getName());
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- [Java Reference](https://docs.cloud.google.com/java/docs/reference/google-cloud-run/latest/overview)
|
||||
|
||||
### Node.js (TypeScript)
|
||||
|
||||
- **Installation:**
|
||||
|
||||
```bash
|
||||
npm install @google-cloud/run
|
||||
```
|
||||
|
||||
- **Usage Example:**
|
||||
|
||||
```typescript
|
||||
import {ServicesClient} from '@google-cloud/run';
|
||||
const client = new ServicesClient();
|
||||
const [services] = await client.listServices({
|
||||
parent: 'projects/my-project/locations/us-central1',
|
||||
});
|
||||
```
|
||||
|
||||
- [Node.js Reference](https://googleapis.dev/nodejs/run/latest/index.html)
|
||||
|
||||
### Go
|
||||
|
||||
- **Installation:**
|
||||
|
||||
```bash
|
||||
go get cloud.google.com/go/run/apiv2
|
||||
```
|
||||
|
||||
- **Usage Example:**
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"log" // Import the log package
|
||||
|
||||
run "cloud.google.com/go/run/apiv2"
|
||||
runpb "cloud.google.com/go/run/apiv2/runpb"
|
||||
"google.golang.org/api/iterator"
|
||||
)
|
||||
|
||||
func main() {
|
||||
ctx := context.Background()
|
||||
client, err := run.NewServicesClient(ctx)
|
||||
if err != nil {
|
||||
// Log the error and exit if the client can't be created
|
||||
log.Fatalf("Failed to create Cloud Run Services client: %v", err)
|
||||
}
|
||||
defer client.Close()
|
||||
|
||||
req := &runpb.ListServicesRequest{
|
||||
Parent: "projects/my-project/locations/us-central1", // Remember to replace my-project
|
||||
}
|
||||
it := client.ListServices(ctx, req)
|
||||
|
||||
fmt.Println("Cloud Run Services:")
|
||||
for {
|
||||
resp, err := it.Next()
|
||||
if err == iterator.Done {
|
||||
break // Finished iterating successfully
|
||||
}
|
||||
if err != nil {
|
||||
// Log the error and exit if iteration fails
|
||||
log.Fatalf("Error iterating services: %v", err)
|
||||
}
|
||||
fmt.Println(resp.GetName())
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- [Go Reference](https://docs.cloud.google.com/go/docs/reference/cloud.google.com/go/run/latest)
|
||||
|
||||
## Source Code Samples
|
||||
|
||||
For more examples across languages, visit the
|
||||
[Cloud Run Code Samples](https://cloud.google.com/run/docs/samples).
|
||||
@@ -0,0 +1,134 @@
|
||||
# Cloud Run core concepts
|
||||
|
||||
Cloud Run is a fully managed application platform for running your code,
|
||||
function, or container on top of Google's highly scalable infrastructure. On
|
||||
Cloud Run, your code can run as a service, job, or worker pool. All of these
|
||||
resource types are running sandboxed container instances in the same execution
|
||||
environment and can integrate with Google Cloud services.
|
||||
|
||||
## Services vs. Jobs vs. Worker pools
|
||||
|
||||
- **Cloud Run services:** Used for code that handles requests or events (e.g.,
|
||||
web apps, APIs). They provide an HTTPS endpoint and automatically scale
|
||||
based on traffic.
|
||||
|
||||
- **Cloud Run jobs:** Used for code that performs a specific task and then
|
||||
exits (e.g., data processing, database migrations). They can run a single
|
||||
task or an array of parallel tasks.
|
||||
|
||||
- **Cloud Run worker pools:** Designed for continuous, non-HTTP, pull-based
|
||||
background processing (e.g., Kafka consumers).
|
||||
|
||||
## Resource model
|
||||
|
||||
Cloud Run organizes resources as follows:
|
||||
|
||||
1. **Service** The top-level resource. You can deploy a service from a
|
||||
container, repository, or source code.
|
||||
1. **Revision:** An immutable snapshot of a service's
|
||||
configuration and container image. Each service
|
||||
deployment creates a new revision.
|
||||
1. **Service instances:** The running container that
|
||||
processes requests. Each service revision receiving
|
||||
requests is automatically scaled to the number of
|
||||
instances needed to handle all these requests.
|
||||
1. **Cloud Run functions**: Deploy functions as Cloud Run
|
||||
services. You can deploy single-purpose functions that
|
||||
respond to events emitted from your cloud infrastructure
|
||||
and services
|
||||
|
||||
1. **Job**: Executes one or more containers to completion. A job consists of
|
||||
one or multiple independent tasks that are executed in parallel in a given
|
||||
job execution.
|
||||
|
||||
1. **Worker pools**: If your code processes workloads from an external source
|
||||
but not from an HTTP request, such as pulling work from a message queue, you
|
||||
can deploy it to a Cloud Run worker pool .
|
||||
|
||||
## Autoscaling for Cloud Run services
|
||||
|
||||
Cloud Run services scale automatically based on:
|
||||
|
||||
- **Request concurrency:** The number of concurrent requests per instance.
|
||||
- **CPU utilization:**: The average CPU utilization of existing instances over
|
||||
a one minute window.
|
||||
- **Scale to zero:** Cloud Run autoscales from one to zero instances only
|
||||
after verifying that an instance is no longer processing requests. If you
|
||||
use instance-based billing, Cloud Run instances are charged for the entire
|
||||
lifecycle of instances, even when there are no incoming requests.
|
||||
|
||||
## Container contract
|
||||
|
||||
Your container image can run code written in the programming language
|
||||
of your choice and use any base image, provided that it respects the
|
||||
constraints listed in the [Container runtime contract](https://docs.cloud.google.com/run/docs/container-contract).
|
||||
|
||||
Executables in the container image must be compiled for
|
||||
Linux 64-bit. Cloud Run specifically supports the Linux x86_64 ABI format.
|
||||
|
||||
Cloud Run accepts container images in the Docker Imag
|
||||
Manifest V2, Schema 1, Schema 2, and OCI image formats. Cloud Run
|
||||
also accepts Zstd compressed container images.
|
||||
|
||||
If deploying a multi-architecture image, the manifest list must include
|
||||
linux/amd64.
|
||||
|
||||
For functions deployed with Cloud Run, you can use one of the
|
||||
Cloud Run runtime base images that are published by Google
|
||||
Cloud's buildpacks to receive automatic security and maintenance updates.
|
||||
For more information about the supported runtimes, see the [Runtime support schedule](https://docs.cloud.google.com/run/docs/runtime-support).
|
||||
|
||||
### Container requirements
|
||||
|
||||
When deploying containers to Cloud Run, the following requirements must be met:
|
||||
|
||||
* Container deployed to services must listen for requests on the correct port
|
||||
* A Cloud Run service starts Cloud Run instances to handle incoming
|
||||
requests. A Cloud Run instance always has one single ingress
|
||||
container that listens for requests, and optionally one or more
|
||||
sidecar containers. The following port configuration details
|
||||
apply only to the ingress container, not to sidecars.
|
||||
* The ingress container within an instance must listen for
|
||||
requests on `0.0.0.0` on the port to which requests are sent. Notably,
|
||||
the ingress container should not listen on `127.0.0.1`. By default, request
|
||||
are sent to 8080, but you can configure Cloud Run to send requests to the port of your choice.
|
||||
Cloud Run injects the PORT environment variable into the ingress container.
|
||||
|
||||
## VPC network connectivity
|
||||
|
||||
Cloud Run services and jobs support Direct VPC egress. This means
|
||||
that they can send traffic to private resources within your
|
||||
configured VPC network, such as databases or internal services. Cloud Run
|
||||
services and jobs don't support Direct VPC ingress.
|
||||
Cloud Run worker pools support both Direct VPC egress and Direct VPC
|
||||
ingress. When you configure Direct VPC for your Cloud Run worker pool
|
||||
deployment, each worker instance receives a private IP address on the
|
||||
configured network and subnet. Only resources from your VPC network can
|
||||
connect to the worker pool private IP address endpoint. For more information
|
||||
about obtaining the private IP addresses of your worker pool instance, see
|
||||
[Retrieve the private IP addresses using the metadata server (MDS)](https://docs.cloud.google.com/run/docs/configuring/vpc-direct-vpc#mds-support).
|
||||
|
||||
For Cloud Run worker pools with Direct VPC ingress, such as database
|
||||
connections or any other custom TCP-based protocol, the container must
|
||||
listen for TCP connections on the port exposed in your container image
|
||||
through the Dockerfile or specified by the PORT environment variable.
|
||||
|
||||
## AI and GPU support
|
||||
|
||||
Cloud Run supports hosting AI inference models. You can configure services with
|
||||
GPUs (e.g., NVIDIA RTX PRO 6000 Blackwell GPU, NVIDIA L4) to accelerate
|
||||
workloads like LLM inference using Gemma 3. For more information, see GPU
|
||||
support for
|
||||
[services](https://docs.cloud.google.com/run/docs/configuring/services/gpu),
|
||||
[jobs](https://docs.cloud.google.com/run/docs/configuring/jobs/gpu), and [worker
|
||||
pools](https://docs.cloud.google.com/run/docs/configuring/workerpools/gpu).
|
||||
|
||||
## Pricing
|
||||
|
||||
Cloud Run uses a pay-as-you-go model:
|
||||
|
||||
- **Request-based:** Charged for resources used during request processing.
|
||||
- **Instance-based:** Charged for the entire lifetime of an instance.
|
||||
|
||||
For the latest pricing, visit: [Cloud Run
|
||||
pricing](https://cloud.google.com/run/pricing).
|
||||
@@ -0,0 +1,76 @@
|
||||
# Cloud Run Infrastructure as Code
|
||||
|
||||
Cloud Run resources can be provisioned and managed using Terraform and other IaC
|
||||
tools.
|
||||
|
||||
## Terraform
|
||||
|
||||
The Google Cloud Terraform provider supports Cloud Run services, jobs, and worker pools.
|
||||
|
||||
### Cloud Run service example
|
||||
|
||||
```terraform
|
||||
resource "google_cloud_run_v2_service" "default" {
|
||||
name = "cloudrun-service"
|
||||
location = "us-central1"
|
||||
deletion_protection = false
|
||||
ingress = "INGRESS_TRAFFIC_ALL"
|
||||
|
||||
template {
|
||||
containers {
|
||||
image = "us-docker.pkg.dev/cloudrun/container/hello"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
resource "google_cloud_run_v2_service_iam_member" "noauth" {
|
||||
location = google_cloud_run_v2_service.default.location
|
||||
name = google_cloud_run_v2_service.default.name
|
||||
role = "roles/run.invoker"
|
||||
member = "allUsers"
|
||||
}
|
||||
```
|
||||
|
||||
### Cloud Run job example
|
||||
|
||||
```terraform
|
||||
resource "google_cloud_run_v2_job" "default" {
|
||||
name = "cloudrun-job"
|
||||
location = "us-central1"
|
||||
|
||||
template {
|
||||
template {
|
||||
containers {
|
||||
image = "us-docker.pkg.dev/cloudrun/container/job"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Cloud Run worker pool example
|
||||
|
||||
```terraform
|
||||
resource "google_cloud_run_v2_worker_pool" "default" {
|
||||
name = "cloudrun-workerpool"
|
||||
location = "us-central1"
|
||||
|
||||
template {
|
||||
containers {
|
||||
image = "us-docker.pkg.dev/cloudrun/container/worker-pool:latest"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Reference dpcumentation
|
||||
|
||||
- [Terraform Google Provider - Cloud Run v2 Service](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service)
|
||||
|
||||
- [Terraform Google Provider - Cloud Run v2 Job](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_job)
|
||||
- [Terraform Google Provider - Cloud Run v2 Worker pool](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_worker_pool)
|
||||
|
||||
## YAML
|
||||
|
||||
Cloud Run resources can also be defined using YAML. For more information, see
|
||||
[Cloud Run YAML reference](https://docs.cloud.google.com/run/docs/reference/yaml/v1).
|
||||
@@ -0,0 +1,102 @@
|
||||
# Cloud Run IAM & security
|
||||
|
||||
Cloud Run uses Identity and Access Management (IAM) to secure your resources and control who can deploy or invoke them.
|
||||
|
||||
## Predefined IAM Roles
|
||||
|
||||
| Predefined Role | Usage |
|
||||
| :--- | :--- |
|
||||
| `roles/run.admin` | Full control over all Cloud Run resources. |
|
||||
| `roles/run.invoker` | Invoke Cloud Run services and execute Cloud Run jobs. |
|
||||
| `roles/run.developer` | Read and write access to services, jobs and worker pools; cannot
|
||||
set IAM policies. |
|
||||
| `roles/run.viewer` | Read-only access to Cloud Run resources. |
|
||||
|
||||
## Types of service accounts for service identity
|
||||
|
||||
Cloud Run resources run as a specific service account (the service
|
||||
identity).
|
||||
|
||||
- **User-managed service account (recommended)**: You manually create this
|
||||
service account and determine the most minimal set of permissions that
|
||||
the service account needs to access specific Google Cloud resources. The
|
||||
user-managed service account follows the format of `SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com`.
|
||||
|
||||
- **Compute Engine default service account:** Cloud Run automatically
|
||||
provides the Compute Engine default service account as the default
|
||||
service identity. The Compute Engine default service account
|
||||
follows the format of `PROJECT_NUMBER-compute@developer.gserviceaccount.com`.
|
||||
|
||||
## Best practices
|
||||
|
||||
By default, the Compute Engine default service account is automatically
|
||||
created. If you don't specify a service account when the
|
||||
Cloud Run service or job is created, Cloud Run uses this service account.
|
||||
Depending on your organization policy configuration, the default
|
||||
service account might automatically be granted the Editor role on your
|
||||
project. We strongly recommend that you disable the automatic role
|
||||
grant by enforcing the `iam.automaticIamGrantsForDefaultServiceAccounts`
|
||||
organization policy constraint. If you created your organization after
|
||||
May 3, 2024, this constraint is enforced by default.
|
||||
|
||||
Create a user-managed service account with minimal
|
||||
permissions for each Cloud Run resource.
|
||||
|
||||
To allow a service to access another GCP resource (e.g.,
|
||||
Cloud SQL), grant the service's identity the appropriate IAM role on that
|
||||
resource.
|
||||
|
||||
## Security controls
|
||||
|
||||
- **Ingress Settings:** Control whether your service is reachable from the
|
||||
internet (`all`), only from within the VPC (`internal`), or via a load
|
||||
balancer (`internal-and-cloud-load-balancing`).
|
||||
|
||||
- **VPC Egress:** Use a VPC connector or Direct VPC egress to allow Cloud Run to
|
||||
access resources in your VPC.
|
||||
|
||||
- **Binary Authorization:** Ensure only trusted container images are deployed.
|
||||
|
||||
- **Secrets Management:** Use Secret Manager to securely pass sensitive
|
||||
information (e.g., API keys, database passwords) to your containers as
|
||||
environment variables or volumes.
|
||||
|
||||
## Public access
|
||||
|
||||
There are two ways to create a public Cloud Run service, you can either:
|
||||
|
||||
* Disable the Cloud Run Invoker IAM check (recommended).
|
||||
* Assign the Cloud Run Invoker IAM role to the `allUsers` member type.
|
||||
|
||||
For more information, see:
|
||||
[Cloud Run security overview](https://docs.cloud.google.com/run/docs/securing/managing-access#make-service-public).
|
||||
|
||||
## Configure IAP to secure access
|
||||
|
||||
By enabling IAP on Cloud Run directly, you can secure traffic with a single
|
||||
click from all ingress paths, including default `run.app` URLs and load
|
||||
balancers.
|
||||
|
||||
When you integrate IAP with Cloud Run, you can manage user or group access in
|
||||
the following ways:
|
||||
|
||||
* Inside the organization - configure access to users who are within the same
|
||||
organization as your Cloud Run service
|
||||
|
||||
* Outside the organization - configure access to users who are from
|
||||
organizations different than your Cloud Run service
|
||||
|
||||
* No organization - configure access in projects that are not part of any
|
||||
Google organization
|
||||
|
||||
Enabling IAP on a Cloud Run service can be as easy as deploying a new service with
|
||||
the following flags:
|
||||
|
||||
```bash
|
||||
gcloud run deploy SERVICE_NAME \
|
||||
--region=REGION \
|
||||
--image=IMAGE_URL \
|
||||
--no-allow-unauthenticated \
|
||||
--iap \
|
||||
--quiet
|
||||
```
|
||||
@@ -0,0 +1,43 @@
|
||||
# Cloud Run MCP Usage
|
||||
|
||||
Cloud Run is supported by a remote Model Context Protocol (MCP) server that
|
||||
enables agents to deploy, manage, and monitor serverless applications.
|
||||
|
||||
## MCP Tools for Cloud Run
|
||||
|
||||
The Cloud Run MCP server typically includes tools for:
|
||||
|
||||
- `get_service`: Get info about a Cloud Run service, such as its URI and
|
||||
whether the deploy succeeded.
|
||||
- `list_services`: List Cloud Run services in a given Google Cloud project and
|
||||
region.
|
||||
- `deploy_service_from_image`: Deploy a container image from Artifact Registry
|
||||
or Docker Hub as a Cloud Run service.
|
||||
- `deploy_service_from_archive`: Deploy a Cloud Run service directly from a
|
||||
self-contained source code archive (.tar.gz), skipping the container image
|
||||
build step for faster deployment. The archive must include all dependencies.
|
||||
- `deploy_service_from_file_contents`: Deploys a Cloud Run service directly from
|
||||
local source files. This method is suitable for scripting languages like Python
|
||||
and Node.js, of which the source code can be embedded in the request. This is
|
||||
ideal for quick tests and development feedback loops. You must include all
|
||||
necessary dependencies within the source files because it skips the build step
|
||||
for faster deployment.
|
||||
|
||||
## Setup Instructions
|
||||
|
||||
To connect to the Cloud Run MCP server:
|
||||
|
||||
1. Enable the Cloud Run API in your Google Cloud project.
|
||||
2. Configure the agent's MCP connection using the Gemini CLI extension.
|
||||
3. Follow the setup guide:
|
||||
[Setting up Cloud Run MCP](https://docs.cloud.google.com/run/docs/reference/mcp).
|
||||
|
||||
## Supported Operations
|
||||
|
||||
Agents using the Cloud Run MCP can:
|
||||
|
||||
- Automate the rollout of new revisions.
|
||||
- Troubleshoot failing deployments by inspecting logs and status.
|
||||
- Manage scheduled jobs and verify their execution history.
|
||||
|
||||
Alternatively, use the [open source Cloud Run MCP server](https://github.com/GoogleCloudPlatform/cloud-run-mcp) which runs locally.
|
||||
Reference in New Issue
Block a user