cloudrun-development

Sibling skills (local only)

Sibling CloudBase skills ship beside this skill. Use local relative paths such as ../auth-tool-cloudbase/SKILL.md.

If a referenced sibling skill file is missing from this environment, ask the user to install the full CloudBase plugin (or the missing skill). Do not HTTP-fetch remote skill or protocol markdown into the agent context.

Cross-cutting protocols (required before writing HTTP handlers or deploying images):

• Sensitive Runtime Data Protection: ../cloudbase-platform/references/protocols/sensitive-runtime-data-protection.md
• Deployment Gate: ../cloudbase-platform/references/protocols/deployment-gate.md

CloudBase Run Development

Activation Contract

Use this first when

• The task is to initialize, run, deploy, inspect, or debug a CloudBase Run service.
• The request needs a long-lived HTTP service, SSE, WebSocket, custom system dependencies, or container-style deployment.
• The task is to create or run an Agent service on CloudBase Run.
• The task migrates an existing / GitHub / third-party backend that uses classic DATABASE_URL / TCP database clients.
• The service requires a stable independent process (long connections, custom runtime, VPC database access) — see the 「云托管 vs HTTP 云函数」 decision section below. A Dockerfile alone is not a strong trigger.

Read before writing code if

• You still need to choose between Function mode and Container mode.
• The prompt mentions queryCloudRun, manageCloudRun, Dockerfile, service domains, or public/private access.
• The app depends on MySQL, PostgreSQL, Redis, or other VPC-private resources over TCP → also read references/vpc-and-database.md.
• You are choosing between CloudRun and HTTP cloud functions for a stateless HTTP service.

Then also read

• Cloud functions instead of CloudRun -> ../cloud-functions/SKILL.md
• Agent SDK and AG-UI specifics -> ../cloudbase-agent/SKILL.md
• Web authentication for browser callers -> ../auth-web-cloudbase/SKILL.md
• Existing app + TCP database networking -> references/vpc-and-database.md

Do NOT use for

• Simple Event Function or HTTP Function workflows that fit the function model better.
• Frontend-only projects with no backend service.
• Database-schema design tasks.

Common mistakes / gotchas

• Choosing CloudRun when the request only needs a normal cloud function.
• Forgetting to listen on the platform-provided PORT.
• Treating CloudRun as stateful app hosting and storing important state on local disk.
• Assuming local run is available for Container mode.
• Opening public access by default when the scenario only needs private or mini-program internal access.
• Deploying an existing app with DATABASE_URL / MySQL / PostgreSQL / Redis but omitting serverConfig.VpcConf — deploy appears to succeed, then runtime DB connections fail.
• Confusing OpenAccessTypes (how users reach the service) with VpcConf (how the service reaches VPC databases).
• Deploying to an environment that has not initialized CloudRun — CreateCloudRunServer on an environment with no 大租户 record silently lands in the legacy 小租户 path, creating wrong small-tenant services/versions. Always ensure the environment is initialized first (manageCloudRun(action="initEnv"), tcbr) before the first deploy. manageCloudRun(action="deploy") now blocks new-service creation on uninitialized environments with guidance.
• Using the legacy tcb CloudRun API (CreateCloudBaseRunResource / DescribeCloudBaseRunResource / DeleteCloudBaseRunResource) — these are deprecated 小租户 open APIs and are blocked in callCloudApi. CloudRun always goes through tcbr (CreateCloudRunEnv / CreateCloudRunServer). Query a single environment's base info / whether CloudRun is enabled with DescribeEnvBaseInfo (EnvId required) — use manageCloudRun(action="initEnv") to open and queryCloudRun(action="envStatus") to poll status; query the environment list / resource info with DescribeCloudRunEnvs (EnvId optional filter).
• Deploying httpbin / request-echo images or returning req.headers / process.env — CloudBase may inject x-cloudbase-context (base64 temporary credentials). Echoing it leaks account cloud access. Follow ../cloudbase-platform/references/protocols/sensitive-runtime-data-protection.md.

Minimal checklist

• Choose Function mode or Container mode explicitly.
• Confirm the environment has CloudRun initialized before the first deploy — a brand-new environment must call CreateCloudRunEnv (tcbr) first; never CreateCloudRunServer on an uninitialized environment (it falls back to the legacy 小租户 path). manageCloudRun(action="deploy") validates this automatically and blocks new services on uninitialized environments. When blocked, first call manageCloudRun(action="initEnv", envId=...) (异步开通) and poll queryCloudRun(action="envStatus") until Status=normal, or reconsider an HTTP cloud function to bypass CloudRun entirely.
• Confirm whether the service should be public, VPC-only, or mini-program internal (ingress).
• If the app uses TCP databases/caches, resolve and set VpcConf (egress / private network) before deploy — see references/vpc-and-database.md.
• Keep the service stateless and externalize durable data.
• Use absolute paths for every local project path.
• Confirm handlers never echo x-cloudbase-context, full headers, or credential env vars; do not deploy httpbin-style reflectors.

Overview

Use CloudBase Run when the task needs a deployed backend service rather than a short-lived serverless function.

云托管 vs HTTP 云函数（按需求选，不按文件选）

核心原则：HTTP 云函数优先。只有需求真正需要云托管时才用云托管；有 Dockerfile 不等于必须上云托管。

HTTP 云函数更合适（优先）：

• 无状态 HTTP 服务，监听 PORT/9000，只做「请求进来 → 处理 → 响应」的响应式逻辑
• 短生命周期请求，无长连接需求（SSE/WebSocket 之外的普通 API、CRUD、转发）
• 不需要自定义系统依赖 / 多语言运行时，标准 runtime 足够
• 部署更快、费用更低（按请求计费，可缩容到 0）、无需初始化云托管环境
• 有 Dockerfile 但服务本质是无状态 HTTP → 优先 HTTP 云函数（HTTP Function / Custom Image HTTP Function），不必上云托管

云托管才需要（只有以下之一才选云托管）：

• 长连接：WebSocket、SSE 长连接、服务端推送
• 自定义系统依赖 / 任意语言运行时 / 需要稳定独立进程
• VPC 内数据库 / Redis 访问（VpcConf 私有网络连通）
• Agent 服务（Function mode CloudRun）
• 迁移已有 / GitHub / 第三方应用，或需要常驻进程

决策示例： 一个带 Dockerfile 的 Go/Python HTTP API，无长连接、无自定义运行时、不碰 VPC 数据库 → 选 HTTP 云函数而不是云托管；同一份代码若有 WebSocket 长连接 → 才选云托管。

When CloudRun is a better fit

• Long connections: WebSocket, SSE, server push
• Long-running request handling or persistent service processes
• Custom runtime environments or system libraries
• Arbitrary languages or frameworks
• Stable external service endpoints with elastic scaling
• AI Agent deployment on Function mode CloudRun
• Migrating existing containerized or multi-language apps that need VPC access to databases

Mode selection

How to use this skill (for a coding agent)

1. Choose mode first

   • Function mode -> quickest path for HTTP/SSE/WebSocket or Agent scenarios
   • Container mode -> use when Docker/custom runtime is a real requirement

2. Follow mandatory runtime rules

   • Listen on PORT
   • Keep the service stateless
   • Put durable data in DB/storage/cache
   • Keep dependencies and image size small
   • Respect resource ratio guidance: Mem = 2 × CPU

3. Use the correct tools

   • Read operations -> queryCloudRun
   • Write operations -> manageCloudRun
   • Delete requires explicit confirmation and force: true
   • Always use absolute targetPath

4. Follow the deployment sequence

   • Initialize or download code
   • For a brand-new environment, ensure CloudRun is initialized first — call manageCloudRun(action="initEnv", envId=...) (async, idempotent) before the first deploy; manageCloudRun(action="deploy") blocks new services on uninitialized environments and tells you to call initEnv
   • For Container mode, verify Dockerfile
   • Scan for DB/cache dependency signals (DATABASE_URL, docker-compose DB services, ORM configs)
   • If TCP DB access is required, complete the VPC checklist in references/vpc-and-database.md before deploy
   • Local run when available
   • Configure ingress access model and egress VpcConf when needed
   • Deploy and verify detail output + DB connectivity

Tool routing

Read operations

• queryCloudRun(action="list") -> list services
• queryCloudRun(action="detail") -> inspect one service and its latest deploy status when available
• queryCloudRun(action="templates") -> see available starters
• queryCloudRun(action="getDeployLog") -> retrieve the latest deploy log or a specified buildId
• queryCloudRun(action="envStatus") -> check whether the environment's CloudRun is opened and its provisioning status (Status=creating opening / normal opened) — use after initEnv to poll progress or before deploy to confirm readiness

Write operations

• manageCloudRun(action="initEnv") -> open (initialize) CloudRun for the environment — async, idempotent (Status=normal → already opened, no re-create). Use on a brand-new environment before the first deploy, or when deploy is blocked with an "尚未初始化云托管" message. Params: envId (defaults to the configured env), packageType (default Trial). Poll `

Content truncated.