Skip to content

Module Template

Jump to bottom
Anna edited this page Jun 25, 2026 · 1 revision

Module: Cloud Run

Module flag: cloudrun Enabled by default: yes

Overview

The Cloud Run module provides read and write access to Cloud Run services and jobs in your GCP project. Use it to inspect traffic splits, diagnose revision rollouts, audit job execution history, and — with explicit confirmation — update traffic routing between revisions.

Enable This Module

Cloud Run is included when you start the server without --modules (all modules enabled). To load only the Cloud Run tools:

GCP_PROJECT_ID=my-project ./aura-tracker-gcp --modules cloudrun

Combine with related modules:

GCP_PROJECT_ID=my-project ./aura-tracker-gcp --modules cloudrun,aura,monitoring,logging,iam

Required GCP APIs

Enable these APIs in your project before using this module:

gcloud services enable run.googleapis.com monitoring.googleapis.com
API Used by
run.googleapis.com All Cloud Run tools
monitoring.googleapis.com Aura Score health signals for Cloud Run

Required IAM Permissions

Role Tools that need it
roles/run.viewer All read-only tools
roles/run.admin gcp_cloudrun_update_traffic (mutation)

See Security and Safety for how to grant these to a dedicated service account.

Tools

gcp_cloudrun_list_services

Lists all Cloud Run services across one or all regions.

Parameters:

Name Required Description
project_id yes GCP project ID
region no Filter to a single region; omit for all regions

Returns: Service name, region, URL, latest revision name, traffic splits, labels, creation time.

gcp_cloudrun_get_service_details

Gets the full configuration snapshot for a single Cloud Run service.

Parameters:

Name Required Description
project_id yes GCP project ID
region yes Region the service is deployed in
service_name yes Service name

Returns: Traffic allocation per revision, container image, CPU/memory limits, concurrency, ingress setting, VPC connector, environment variable names, service account, labels.

gcp_cloudrun_update_traffic

Updates the traffic split percentages across revisions. Mutation — requires two-step confirmation.

Parameters:

Name Required Description
project_id yes GCP project ID
region yes Region
service_name yes Service name
traffic yes Array of {revision, percent} — must sum to 100
dry_run no true → preview only (Step 1)
confirm_plan_id no Plan ID from dry-run response (Step 2)

Returns (dry_run=true): Human-readable change description, plan_id, expires_in (10 minutes).

Returns (confirmed): Before/after traffic split comparison.

See Security and Safety#Two-Step Confirmation Flow for the full confirmation workflow.

gcp_cloudrun_list_jobs

Lists Cloud Run Jobs across one or all regions.

Parameters:

Name Required Description
project_id yes GCP project ID
region no Filter by region; "-" or omit for all regions

Returns: Job name, region, container image, task count, parallelism, service account.

gcp_cloudrun_get_job_details

Gets full configuration for a Cloud Run Job.

Parameters:

Name Required Description
project_id yes GCP project ID
region yes Region
job_name yes Job name

Returns: Container image, task count, parallelism, timeout, service account, VPC connector, latest execution summary.

gcp_cloudrun_list_job_executions

Lists recent executions of a Cloud Run Job with their outcomes.

Parameters:

Name Required Description
project_id yes GCP project ID
region yes Region
job_name yes Job name
limit no Max executions to return (default: 10)

Returns: Execution ID, state (SUCCEEDED / FAILED / RUNNING / CANCELLED), start time, completion time, task failure count.

MCP Resources

These resources are available without a tool call. An LLM can read them directly for context:

Resource URI Contents
gcp://{project}/cloudrun/services All Cloud Run services across all regions
gcp://{project}/cloudrun/{region}/{service} Single service: URL, traffic splits
gcp://{project}/cloudrun/{region}/{service}/revisions Revision list with traffic allocation

Prompt Examples

Use these directly with Claude Desktop or any MCP-compatible host.

Inventory

"List all Cloud Run services in my-project and show their current revision and traffic split."

Cross-region audit

"Which Cloud Run services in my-project are deployed in more than one region?"

Stale revision check

"Which Cloud Run services in us-central1 are still sending traffic to a revision that is more than 5 revisions behind the latest?"

Traffic rollback — two-step safe

"I need to roll back payments-api in us-central1 to revision payments-api-00023-abc. Show me what the traffic update would look like before making any changes."

Public ingress audit

"Which Cloud Run services in my-project have their ingress set to all (publicly reachable from the internet)?"

Job failure monitoring

"Show me the last 20 executions of the nightly-report job in us-east1. How many failed, and when did they fail?"

Cost investigation (combined with Aura)

"List all Cloud Run services with an Aura Score below 50 and explain the top issue for each one."

Related Modules

Module flag Why you'd combine it
aura Health/efficiency score (0–100) for each Cloud Run service
topology Discover what each service depends on (Cloud SQL, Pub/Sub, Secrets, VPC)
monitoring Pull request rate, error rate, and P99 latency metrics
logging Fetch recent error logs for a specific revision
iam Audit IAM bindings on Cloud Run resources
eventarc See which Eventarc triggers invoke this service
networking See the NEG and load balancer fronting this service

Clone this wiki locally