本文へ移動
cccskills
無料GitHub で公開

api-gateway-backend-security-and-rate-limiting

Secures and rate limits backend services behind Google Cloud API Gateway across OpenAPI 2.0 and OpenAPI 3.0.x API configurations, including MCP-enabled gateways. Use when configuring API key or JWT authentication, locking down Cloud Run or Cloud Run functions backends with a gateway service account, reading authenticated claims from X-Apigateway-Api-Userinfo, setting per-project request quotas, or diagnosing HTTP 429 and HTTP 500 Service Control Quota errors. Do not use for Apigee, GKE Gateway API, Cloud Load Balancing custom domain setup, or LLM model routing.

インストール方法を見る

含まれるファイル(6)

  • SKILL.md10.7 KB
  • references/backend-security.md7.8 KB
  • references/client-authentication.md9.0 KB
  • references/mcp-traffic-security.md9.5 KB
  • references/quotas-and-rate-limiting.md7.5 KB
  • scripts/check_quota_metrics.py15.7 KB

SKILL.md(原文)

インストールする前に、エージェントに与えられる指示の中身を確認できます。

API Gateway Backend Security and Rate Limiting

This skill configures client authentication, gateway-to-backend authentication, and per-project rate limits (quotas) for Google Cloud API Gateway across OpenAPI 2.0 (swagger: "2.0") and OpenAPI 3.0.x (openapi: 3.0.4), including gateways with Model Context Protocol (MCP) enabled (Public Preview).

Prerequisites

  1. Install the Google Cloud CLI and Python 3.10+ YAML parser:
    • Install or update the Google Cloud SDK.
    • Install PyYAML for the quota metric validation script:
      pip install "PyYAML>=6.0,<7.0"
      
  2. Authenticate your environment:
    • Local CLI session: gcloud auth login
    • Application Default Credentials (SDKs): gcloud auth application-default login
    • Service account key file (if required by CI): set GOOGLE_APPLICATION_CREDENTIALS={key_file_path}
  3. Select or create a project, verify billing, and pick a supported gateway location:
    • Select an existing project (gcloud config set project {project_id}) or create one (gcloud projects create {project_id} as an escape hatch).
    • Verify that an active billing account is linked to {project_id} (required even when staying within the API Gateway pricing free tier).
    • Use us-central1 as the default --location for API Gateway commands. For the other supported regions, see API Gateway deployment model.
  4. Enable required Google Cloud APIs:
    gcloud services enable \
      apigateway.googleapis.com \
      servicemanagement.googleapis.com \
      servicecontrol.googleapis.com \
      iam.googleapis.com \
      apikeys.googleapis.com \
      --project={project_id}
    
    API Gateway does not need the Cloud Run API. If the backend runs on Cloud Run, that API is already enabled in the backend's project.
  5. Verify required IAM roles:
    • To manage API Gateway resources and enable services: roles/apigateway.admin and roles/serviceusage.serviceUsageAdmin
    • To create the gateway service account and attach it to an API config: roles/iam.serviceAccountAdmin and roles/iam.serviceAccountUser
    • To manage API keys in consumer projects: roles/serviceusage.apiKeysAdmin
    • For the gateway service account to invoke the backend: roles/run.invoker (Cloud Run or 2nd gen functions) or roles/cloudfunctions.invoker (1st gen functions)

Decision Matrix: Client Authentication, Backend Security, and Quotas

Select the layer that matches the security requirement:

GoalMechanism to ConfigureKey ConstraintDetailed Reference
Identify the calling consumer project for quotas and billingAPI key (x-api-key header convention; key query parameter escape hatch)NEVER rely on an API key alone to authenticate end-user identity. Rationale: API keys identify a Google Cloud project rather than a user, and clients can extract them.Client Authentication
Authenticate end users or calling servicesJWT (oauth2 scheme with x-google-issuer / x-google-jwks_uri in OAS 2.0, or x-google-auth in OAS 3.x)Operation-level security overrides root security. Include api_key: [] and the JWT scheme in the same security requirement object when an endpoint needs both user identity and quotas.Client Authentication
Block direct calls to the backend serviceDedicated gateway service account (--backend-auth-service-account) + roles/run.invoker + backend --no-allow-unauthenticatedRoll out the gateway config with --backend-auth-service-account BEFORE setting --no-allow-unauthenticated on a live backend to avoid 403 downtime.Backend Security
Rate limit requests per consumer project (1/min/{project})x-google-management (OAS 2.0) or x-google-api-management (OAS 3.x) + x-google-quotaNEVER rename or remove a quota metric when creating a new API config while any gateway of the API runs an older config referencing that metric. Rationale: Creating the config immediately overwrites API-wide quotas and causes HTTP 500 Failed to call Service Control Quota on older gateways.Quotas and Rate Limiting
Secure MCP tools/list and tools/call on /mcp (Public Preview)x-google-api-management.mcp.tools-list.security (exactly one JWT or API key scheme) + operation security and x-google-mcp-tool: falsex-google-mcp-tool: false hides an operation from MCP only; the underlying REST route remains live unless secured or removed.MCP Traffic Security

Execution Workflow and Validation Loop

Follow this zero-downtime sequence when authoring or updating an API Gateway security or quota configuration:

  1. Create the gateway service account and grant backend invoker permissions:
    • Follow Steps 1–3 of Backend Security to create {gateway_sa_name} and request human approval before granting roles/run.invoker on {backend_service}.
    • Update backend handler code to decode verified user claims from X-Apigateway-Api-Userinfo (base64url-encoded JSON) instead of Authorization.
  2. Author the OpenAPI authentication and quota definitions:
    • Use the OpenAPI 2.0 or OpenAPI 3.0.x templates and provider tables in Client Authentication and Quotas and Rate Limiting.
    • If the specification enables MCP (x-google-api-management.mcp), configure exactly one JWT or API key scheme on tools-list (also list a JWT scheme in the root security list), and review operation opt-outs using MCP Traffic Security.
  3. Run the quota metric validation loop BEFORE running api-configs create:
    • If neither the active specs nor {candidate_openapi_spec} define quota metrics (x-google-management.metrics or x-google-api-management.metrics), skip this step.
    • Request human approval before creating an API config that defines or modifies quotas, because api-configs create immediately replaces quota definitions across all gateways of the API.
    • By default, run scripts/check_quota_metrics.py against all active gateways deployed for {api_id} in {project_id}:
      python3 scripts/check_quota_metrics.py \
        --spec={candidate_openapi_spec} \
        --project={project_id} \
        --api={api_id}
      
    • Escape hatch for offline environments without gcloud access (pass --baseline-spec for every config currently served by a gateway of the API):
      python3 scripts/check_quota_metrics.py \
        --spec={candidate_openapi_spec} \
        --baseline-spec={previous_openapi_spec} \
        --dry-run
      
    • If scripts/check_quota_metrics.py exits with code 1 (status: "FAIL"), add the missing metrics and limits back to {candidate_openapi_spec}, move each x-google-quota listed in ignored_quota_extensions into the operations it applies to, and re-run the script until it exits with code 0 (status: "PASS"). If the user wants to remove a limit on purpose, confirm the removal with the user, because it removes that limit from every gateway of the API. If skipped_configs is not empty, tell the user that the script did not inspect those API configs (for example, gRPC configs), and check their quota metrics and limits manually. If it exits with code 2, fix the problem printed to stderr: the CLI arguments, gcloud authentication, or an API config that the script cannot inspect.
  4. Create the API config, update the gateway, enable the managed service, and lock down the backend:
    • Follow Steps 4–5 of Backend Security to run gcloud api-gateway api-configs create and gcloud api-gateway gateways update (request human approval before updating a production gateway), enable the API's managedService in consumer projects (Client Authentication), and then restrict {backend_service} with --no-allow-unauthenticated.
    • Verify that direct calls to the backend *.run.app URL return 403, unauthenticated calls to the gateway defaultHostname return 401, and authenticated calls return 200.

Pre-Deployment Checklist

  • Dedicated {gateway_sa_name} is granted roles/run.invoker (or roles/cloudfunctions.invoker), and --no-allow-unauthenticated is applied after the gateway config is active.
  • Backend code decodes X-Apigateway-Api-Userinfo for user claims.
  • Security enforcement does not depend solely on a load balancer or Google Cloud Armor in front of the gateway, because the gateway's defaultHostname (*.gateway.dev) cannot be disabled.
  • Every quota-enforced operation requires an API key (api_key: []), and the API's managedService is enabled and allowed on the API key in each consumer project.
  • python3 scripts/check_quota_metrics.py returns status: "PASS" (exit code 0) against active gateway configs or all baseline specs before api-configs create.
  • If MCP is enabled, x-google-api-management.mcp.tools-list.security names exactly one JWT or API key scheme (a JWT scheme is also in the root security list), and administrative endpoints are secured on REST in addition to x-google-mcp-tool: false.

Resource Cleanup

To avoid ongoing charges when tearing down a test or staging environment, request human approval and delete the gateway, all API configs, the API, and the service account in dependency order:

gcloud api-gateway gateways delete {gateway_id} --location={region} --project={project_id}
gcloud api-gateway api-configs delete {config_id} --api={api_id} --project={project_id}
gcloud api-gateway apis delete {api_id} --project={project_id}
gcloud iam service-accounts delete {gateway_sa_name}@{project_id}.iam.gserviceaccount.com --project={project_id}

レビュー

まだレビューはありません。使ってみた感想をお寄せください。

同じリポジトリのスキル

概要と使いどころ

Configures best-practice alerting policies for AI agents using OpenTelemetry (OTel) metrics, generating output as Terraform (.tf) configuration files. Use when analyzing, writing, or deploying alerting policies to monitor agent latency, error rates, token usage, and quality metrics. Don't use for standard infrastructure monitoring unrelated to AI agents, or when the agent is not instrumented with OpenTelemetry (for Reliability, Cost, Safety, Security alerts). NOTE: Reliability, Cost, Safety, and Security alerts use generic OTel metrics and work across runtimes (such as Cloud Run, Vertex AI). Quality alerts rely on Vertex AI Online Monitors and are strictly bound to Vertex AI deployments.

日本語の概要は準備中です。原文の説明を表示しています。

google/skills2.1万2026年10月16日 更新

Deploy open models or custom weights from Model Garden to Agent Platform endpoints, check the status of an in-progress deployment operation, or clean up resources by undeploying models and deleting endpoints. Use when asked to actively deploy a model, list the Model Garden CATALOG of available models, check if a specific model is deployable (`gcloud ai model-garden models list-deployment-config`), query deployment cost, troubleshoot deployment errors (like quota limits), or undeploy/clean up endpoints. Also use when copying and deploying a 1P Tuned Model. Don't use for pure listing/discovery questions of the form "is X deployed?", "list my endpoints", or "which regions have models running?" — for those use `agent-platform-endpoint-management`. Don't use for running model evaluations (use `agent-platform-eval-flywheel` skill).

日本語の概要は準備中です。原文の説明を表示しています。

google/skills2.1万2026年10月16日 更新

Manages Agent Platform serving endpoints. Use when you need to create, list, describe, update, or delete serving endpoints for model deployment on Agent Platform. Also use when troubleshooting endpoint permission, quota, or resource busy errors. Don't use for deploying models to endpoints or for running model evaluations.

日本語の概要は準備中です。原文の説明を表示しています。

google/skills2.1万2026年10月16日 更新

Measures and improves the quality of AI models and agents on Google Cloud using the Eval Quality Flywheel methodology. Use when generating synthetic user scenarios, evaluating an agent or model, building an eval dataset, picking or writing evaluation metrics, analyzing failures, comparing results before and after a fix, or when guidance is needed on Agent Platform eval methodology — including dataset schema, LLM-as-judge scoring, and common failure causes. For fine-tuning, use agent-platform-tuning. For general production deployment, use agent-platform-deploy.

日本語の概要は準備中です。原文の説明を表示しています。

google/skills2.1万2026年10月16日 更新

Connects to and performs inference with Google Cloud Agent Platform GenAI models, including First-Party Gemini models and Third-Party OpenMaaS models (Llama, DeepSeek, Qwen, etc.). Use when asked to perform inference, ask a model a question, run a test prompt, execute chat completions, or generate code for calling Gemini or OpenMaaS models, authenticate with GenAI SDK, OpenAI SDK, or legacy Agent Platform SDK, configure base URLs and global/regional endpoints, or troubleshoot 429 Resource Exhausted (DSQ), 400 User Validation, or 404 Not Found errors. Don't use for deploying models to endpoints or for running model evaluations.

日本語の概要は準備中です。原文の説明を表示しています。

google/skills2.1万2026年10月16日 更新

Guides agents and users through migrating from Gemini API in Google AI Studio to Gemini Enterprise Agent Platform (formerly Vertex AI). Use this skill when moving applications to Google Cloud, to leverage Cloud credits, or to unify inferencing with other Cloud infrastructure (IAM, billing, telemetry).

日本語の概要は準備中です。原文の説明を表示しています。

google/skills2.1万2026年10月16日 更新

google のスキルをすべて見る

このスキルの問題を報告する