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 "Cloud Run vs HTTP Cloud Function" 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 → First make the database access method decision (SDK/gateway preferred, see the "Database Access Method Decision Gate" below); after confirming TCP direct connection is required → also read references/vpc-and-database.md.
You are choosing between CloudRun and HTTP cloud functions for a stateless HTTP service.
The service calls CloudBase resources (PG app.rdb(), NoSQL, storage, functions) through an SDK → First pass the "Credential Decision Gate for Compute Resources Accessing CloudBase": who issues the credentials, how they are injected, and how they are revoked must all be decided before writing code.
Container deploy fails (deploy_failed, Pod not ready, readiness/probe failed, third-party imageUrl won't stay up) → also read references/image-deploy-troubleshooting.md and follow the Container deploy failure SOP below. Do not start by raising InitialDelaySeconds.

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
Container image deploy failure / probe / deploy_failed -> references/image-deploy-troubleshooting.md
Service calls CloudBase resources through an SDK (credential source / injection / revocation) -> ../cloud-functions/references/http-function-credentials.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 in Container mode — and its mirror image in Function mode: calling app.listen() there, where the framework already owns the port and the second bind dies with EADDRINUSE.
Guessing the credential environment variable name. @cloudbase/node-sdk reads CLOUDBASE_APIKEY; an invented name (for example TCB_API_KEY) is silently ignored and only shows up later as "no credentials at runtime".
Copying a server credential out of the local client login state (auth.json, .cloudbase/) and injecting it into a deployed service. Issue the key with manageAppAuth(action="createApiKey", keyType="api_key") instead, so it has an owner, a rotation path, and a keyId you can revoke. See ../cloud-functions/references/http-function-credentials.md.
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.
New application deployments default to TCP direct database connection — data that can be accessed via SDK/gateway (PG app.rdb(), NoSQL, storage) does not need VpcConf nor database account credentials; only migration-type applications (classic drivers/ORMs that cannot be replaced) go through TCP direct connection + VpcConf. See "Database Access Method Decision Gate".
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 large-tenant record silently lands in the legacy small-tenant 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 small-tenant 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.
Seeing readiness probe failed / deploy_failed and immediately raising InitialDelaySeconds — the probe window is already ~N+150s; crash loops and loopback binds are not slow-start. Follow the Container deploy failure SOP.
Deploying a third-party image without reading its run docs — missing Cmd, bind-address env, or VolumesConf looks identical to a probe failure.
Calling getDeployLog for imageUrl deploys — that is CODING build log; use getProcessLog.
Treating startup banners as proof the service is healthy — pull getProcessLog twice and compare; a repeated boot sequence is a restart loop.

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 small-tenant path). manageCloudRun(action="deploy") validates this automatically and blocks new services on uninitialized environments. When blocked, first call manageCloudRun(action="initEnv", envId=...) (asynchronous provisioning) 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.
Settle the credential path for every CloudBase SDK call before writing code — a server API Key issued through manageAppAuth(action="createApiKey") and injected via EnvParams, never a key copied out of the local client login state.
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.
For third-party images, complete the five-item docs checklist (Cmd / port / bind env / volume / health) before deploy.

Overview

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

Cloud Run vs HTTP Cloud Function (choose by requirement, not by file)

Core principle:Prioritize HTTP Cloud Functions. Only use Cloud Run when the requirement truly needs it; having a Dockerfile does not mean Cloud Run must be used.

HTTP Cloud Functions are more suitable (preferred):

Stateless HTTP service, listening on PORT/9000, only doing responsive logic of "request comes in → process → respond"
Short-lived requests, no long-connection requirement (ordinary APIs, CRUD, forwarding other than SSE/WebSocket)
No need for custom system dependencies / multi-language runtime; standard runtime is sufficient
Faster deployment, lower cost (billed per request, can scale to 0),No need to initialize the Cloud Run environment
There is a Dockerfile but the service is essentially stateless HTTP → prioritize HTTP Cloud Functions (HTTP Function / Custom Image HTTP Function), no need for Cloud Run

Cloud Run is only needed (choose Cloud Run only if one of the following applies):

Long connections: WebSocket, SSE long connections, server-side push
Custom system dependencies / any language runtime / need for a stable independent process
Database / Redis access within VPC (VpcConf private network connectivity)
Agent service (Function mode CloudRun)
Migrating an existing / GitHub / third-party application, or needing a resident process

Decision example: A Go/Python HTTP API with a Dockerfile , no long connections, no custom runtime, no VPC database access → choose HTTP Cloud Functions instead of Cloud Run; if the same code has WebSocket long connections → then choose Cloud Run.

Database Access Method Decision Gate (must be answered before deployment: SDK preferred, TCP direct connection as fallback)

Core principle:Data that can be accessed via CloudBase SDK/gateway should always prioritize the SDK path. TCP direct connection introduces the trio of VPC, security groups, and database account credentials, all of which are problems exposed only after deployment (ETIMEDOUT、security group blocking, password injection), avoid them if you can.

Priority: SDK / gateway path (no need for VpcConf, no database account or password required)

CloudBase PG → app.rdb()(js-sdk v3 / node-sdk, going through the PG HTTP gateway; see ../postgresql-development-cloudbase/SKILL.md）
NoSQL → app.database(); object storage → app.storage
New applications / CloudBase native data → design the data layer directly along the SDK path; no VPC configuration is needed at all during deployment; if only these data planes are used, you can further eliminate Cloud Hosting by combining this with the "HTTP Cloud Functions first" from the previous section

Only in the following cases should you use TCP direct connection (you must complete the references/vpc-and-database.md full process):

Migrating existing / GitHub / third-party applications whose data layer uses classic drivers or ORMs (mysql2, pg, Prisma, SQLAlchemy, WordPress / Ghost, etc.), where the cost of converting to the SDK is high or the user explicitly requires keeping it
Need capabilities not covered by the SDK (specific SQL dialects, stored procedures, native Redis protocol, etc.)

Decision action: When scanning to DATABASE_URL / DB dependency signals, stop first and answer "can this data access be replaced with SDK/gateway", then decide whether to enter the VPC checklist—do not proceed by default with the TCP direct connection plan.

Credential decision gate for compute resources accessing CloudBase (must be answered before deployment)

Core principle:What the SDK path eliminates is the database account and password, not the CloudBase resource access credential. When service code needs to call CloudBase resources (PG app.rdb() / NoSQL / storage / functions), first determine the credential source, then write code, then deploy.

Three things must be answered first:

Who issues it — CloudBase server-side API Key:manageAppAuth(action="createApiKey", keyType="api_key", keyName="<service>-<env>"), or CLI tcb env apikey create my-key -e env-xxx。Do nottake one from the local client login state (auth.json / .cloudbase/) to use.
How to inject it — via serverConfig.EnvParams inject CLOUDBASE_APIKEY（@cloudbase/node-sdk automatically reads this variable; the explicit field is accessKey). Variable names are subject to the official ones; do not invent your own. When changing environment variables, keep existing key-value pairs; do not overwrite the whole set.
How to revoke it — one dedicated key per service, record keyName and the rotation owner; when decommissioning or rotating, manageAppAuth(action="deleteApiKey", keyId=...) andredeploy. After rotation, residual copies in old instances will not report errors; they will only silently become invalid.

Do not assume that Cloud Hosting containers automatically carry usable CloudBase credentials — after deployment, verify with one real SDK read (verify more than twice; do not just check whether the process started). For complete steps, the Tencent Cloud key pair path for the Manager SDK, and the safe way to merge environment variables, see ../cloud-functions/references/http-function-credentials.md。

api_key isenvironment-levelcredential: it can bypass RLS, and the number issued per environment is limited. Do not feed the same one to every service — if any instance is compromised, the entire environment is compromised.

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

Dimension	Function mode	Container mode
Best for	Fast start, Node.js service patterns, built-in framework, Agent flows	Existing containers, arbitrary runtimes, custom system dependencies
Port model	The function framework binds the platform port itself — your code must not call `app.listen()`	App must listen on the injected `PORT`
Dockerfile	Not required	Required — but a Dockerfile alone does not mean CloudRun; first check whether the service needs long connections / custom runtime. Stateless HTTP services with a Dockerfile may fit HTTP cloud functions better.
Local run through tools	Supported	Not supported
Typical use	Streaming APIs, low-latency backend, Agent service	Custom language stack, migrated container app

How to use this skill (for a coding agent)

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
Follow mandatory runtime rules
- Container mode: listen on the injected PORT. Function mode: the framework binds the port for you — never call app.listen()
- Settle the credential gate (who issues / how injected / how revoked) before writing any CloudBase SDK call
- Keep the service stateless
- Put durable data in DB/storage/cache
- Keep dependencies and image size small
- Respect resource ratio guidance: Mem = 2 × CPU
Use the correct tools
- Read operations -> queryCloudRun
- Write operations -> manageCloudRun
- Delete requires explicit confirmation and force: true
- Always use absolute targetPath
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
- For imageUrl / third-party images, complete the five-item docs checklist in the Container deploy failure SOP before deploy
- Deploy and verify detail output + DB connectivity
- If deploy fails, follow the Container deploy failure SOP (references/image-deploy-troubleshooting.md) — docs → getProcessLog → config; do not start with InitialDelaySeconds

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") -> Build logs（CODING / DescribeCloudRunBuildLog）。Only meaningful for cloud-side source builds; existing image deployments (imageUrl) have no build process, so do not use it to diagnose image deployment failures. Accounts not logged in to CODING will report errors (such as User not created or may not qcloud user）
queryCloudRun(action="getProcessLog") -> Runtime logs（tcbr/DescribeCloudRunProcessLog). Return deployment-stage steps (such as create_version_check_vpc / create_eks_virtual_service / check_eks_virtual_service) + container startup/runtime logs (s6-overlay, application process, readiness probe failure reasons).Both image deployment and source builds are available and do not depend on CODING. Parameters:detailServerName/serverName + optional runId(if not passed, take the latest deployed RunId；RunId can also be obtained from detail / getDeployRecords 's latestDeploy.RunId )
queryCloudRun(action="getDeployRecords") -> list deploy records (newest first; includes BuildId / RunId / FlowRatio / Status) — use to review release history and rollback context before a traffic operation
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
queryCloudRun(action="getManageTask") -> Release task status（tcbr/DescribeServerManageTask). Returns taskId / taskStatus and the latest deployment record status latestDeployStatus. Used for two things: when you hit "an existing deployment release task is running", first confirm whether the task is really progressing; and when the deployment has made no progress for a long time, distinguish between "the task is still progressing" and "the task is stuck".If you don't know the task status, don't repeatedly retry deploy

Log query SOP (build logs vs runtime logs)

When troubleshooting deployment failuresyou must distinguishthe two types of logs; don't use only getDeployLog：

Cloud source build(pass targetPath, use CODING build)
- First queryCloudRun(action="getDeployLog", detailServerName=..., buildId=...) checkbuild logs(compilation/packaging failure)
- then queryCloudRun(action="getProcessLog", detailServerName=..., runId=...) checkruntime logs(deployment steps + container startup/health check)
Existing image deployment(pass imageUrl、DeployType=image）
- skip getDeployLog(no build process; and it depends on CODING, so it will fail directly if not logged in)
- directly queryCloudRun(action="detail") or getDeployRecords get latestDeploy.RunId, then getProcessLog check runtime logs

{
  "action": "getProcessLog",
  "detailServerName": "my-svc",
  "runId": "<from latestDeploy.RunId>"
}

Deploy-task SOP (when you hit "an existing deployment release task is running")

manageCloudRun(action="deploy") reports "an existing deployment release task is running" / already has a deploy task running ,don't blindly retry, and don't repeatedly modify Dockerfile / serverConfig — first confirm the task's real status:

queryCloudRun(action="getManageTask", detailServerName=...) → read taskId / taskStatus / latestDeployStatus
queryCloudRun(action="getProcessLog") → compare two fetches 20–40 seconds apart to confirm whether the deployment phase steps are still progressing
Branch by result:

Observation	Action
`taskStatus` is still in running state, and deployment steps are progressing	continue waiting, don't resend deploy
The task has ended (not in running state), but deploy is still rejected	only then consider retrying
The task stays in a non-terminal state for a long time, and the version also stays at `creating` without moving	record `taskId` / `latestDeployStatus` / time window as evidence, don't spin retrying

force=true doesn't solve this problem: it only skips this tool's confirmation prompt; it won't cancel or override the existing release task on the server — using it as a "force override" will only cause one wasted collision.

For the log-side troubleshooting order (build logs vs runtime logs, logs before configuration), see the above Log query SOP and Container deploy failure SOP。

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 "cloud hosting not yet initialized" message. Params: envId (defaults to the configured env), packageType (default Trial). Poll queryCloudRun(action="envStatus") until Status=normal.
manageCloudRun(action="init") -> create local project
manageCloudRun(action="download") -> pull remote code
manageCloudRun(action="run") -> local run for Function mode
manageCloudRun(action="deploy") -> trigger deploy + lightweight wait for registration (does not hang for full build; pass waitRegistration=false to skip even that wait when you don't need buildId). Returns buildId / runId / taskId + DeployType-aware next_step: source → getDeployLog then getProcessLog; image (imageUrl, BuildId often 0) → skip getDeployLog, use getDeployRecords/detail for RunId then getProcessLog. Follow the returned next_step — do not always poll build logs. Existing services: RMW preserves remote VpcConf / EnvParams keys / OpenAccessTypes; new services automatically validate that the environment's CloudRun is initialized — if not, deploy is blocked with guidance to call initEnv first
manageCloudRun(action="updateConfig") -> config-only update (no code upload; VPC / EnvParams / scaling / access types)
manageCloudRun(action="traffic") -> traffic management / canary release (aligns with tcb cloudrun traffic): trafficOp="set" adjusts the stable/canary traffic ratio (stablePercent + canaryPercent must equal 100, e.g. 90/10); trafficOp="promote" promotes the canary version to full release (100%, closes gray release, irreversible); trafficOp="rollback" rolls back to the previous stable version (stops the releasing canary). Check queryCloudRun(action="getDeployRecords") first to understand current versions and traffic
manageCloudRun(action="delete") -> delete service
manageCloudRun(action="createAgent") -> create Agent service

Deploying an existing image (imageUrl)

When there is already a ready-made image (built locally, or published by a third party), no local source directory is needed; directly manageCloudRun(action="deploy") pass in imageUrl and it's fine; use DeployType="image"(container type) deployment,targetPath can be omitted. If the user explicitly mentions using a certain image or not needing to rebuild the code,imageUrl must be passed; don't fall back to source build just because there is a local source directory.

Decision path (direct fill vs local relay):

Publicly accessible anonymously(e.g. ccr.ccs.tencentyun.com/..., public Docker Hub images) → Directly fill imageUrl：manageCloudRun(action="deploy", serverName=..., imageUrl="ccr.ccs.tencentyun.com/ns/img:v1", serverConfig={...}). CloudBase will directly pull that registry address to build and deploy.If docker.io / Docker Hub repeatedly fails to pull on the node, do not spin in idle retries: switch to Dockerfile FROM <public-image> + targetPath source build (CODING pulls public images, artifacts are pulled from CCR intranet). See SOP step 4 below.
Private / registry requiring login（ghcr.io, private ECR/Harbor, etc.) → local relay to CCR：
```
docker pull ghcr.io/example/app:latest
docker tag ghcr.io/example/app:latest ccr.ccs.tencentyun.com/<ns>/app:latest
docker login ccr.ccs.tencentyun.com
docker push ccr.ccs.tencentyun.com/<ns>/app:latest
```
Then pass ccr.ccs.tencentyun.com/<ns>/app:latest as imageUrl . The relay only solves pulling,cannot replacethe startup command / environment variables / data directory in the image documentation.

Linked with initEnv: image deployment likewise requires the environment to have Cloud Hosting enabled. Before the first deployment of a new environment, first manageCloudRun(action="initEnv", envId=...), and use queryCloudRun(action="envStatus") to poll until Status=normal; when not enabled, deploy will be intercepted and guide you to first initEnv。

Example:

{
  "action": "deploy",
  "serverName": "my-image-svc",
  "imageUrl": "ccr.ccs.tencentyun.com/ns/app:latest",
  "serverConfig": {
    "OpenAccessTypes": ["PUBLIC"],
    "Cpu": 0.5,
    "Mem": 1,
    "MinNum": 1,
    "MaxNum": 3,
    "Port": 8080,
    "Cmd": ["node", "server.js"],
    "EnvParams": "{\"PORT\":\"8080\",\"BIND_HOST\":\"0.0.0.0\"}"
  }
}

Port / Cmd / EnvParams must come from the five-element checklist in the official image documentation; do not copy 3000 or omit the startup command. For a complete comparison of third-party images, see references/image-deploy-troubleshooting.md appendix.

After deployment:manageCloudRun(deploy) for the image returned by next_step defaults to getProcessLog(or first getDeployRecords to get RunId），do notswitch to calling getDeployLog. You can also use queryCloudRun(action="detail") to view imageInfo(image address and deployment type). For troubleshooting image deployment failures, follow the SOP below.

Container deploy failure SOP

Order: first check the official image documentation → then check runtime logs → only lastly touch the configuration. It is forbidden to call deploy_failed as soon as you see probe failed / InitialDelaySeconds。

Details and cases:references/image-deploy-troubleshooting.md。

1. Before deployment: confirm the five elements from the official image documentation

Do not guess based on Docker Hub tags or "common default values". Before deployment you must confirm:

Startup command EntryPoint / Cmd (how the process stays resident in the foreground) → serverConfig.EntryPoint / Cmd
Service port(the port the process actually binds; do not assume 80/3000, and do not assume the image respects PORT）→ serverConfig.Port
External listening environment variables(must be 0.0.0.0 rather than 127.0.0.1, feature switches default off, etc.) → EnvParams
Data directory mount → serverConfig.VolumesConf
Health endpoint(CloudRun readiness probes theservice port, not any arbitrary HTTP path)

If any item is missing and you deploy anyway, the failure will look like "health check failed".

2. Deployment failure: use `getProcessLog` to characterize

Image deployment (imageUrl）skip getDeployLog(that is the build log for cloud source builds). Get detail / getDeployRecords from RunId, then queryCloudRun(action="getProcessLog")。

The existence of startup logs does not mean the service is running normally. Banners, s6/tini lines, and sidecar "listening" do not prove the probe target is up.

Compare two logs to determine liveness: wait 20–40 seconds and pull getProcessLog。

Observe	characterize
Only scheduling/creating step (`create_eks_*`), no container stdout	Pod scheduling / image pulling
The same startup banner / PID 1 line appears repeatedly (timestamps advancing, content almost identical)	Container exits immediately on startup / restart loop
The process is still running, but it listens on `127.0.0.1` or port ≠ `serverConfig.Port`	port / bind address issue
The two pulls arethe same startup processis logging further along, banner does not repeat	only then could it be slow startup

3. Real readiness probe mechanism (strictly forbidden to first tune the delay)

After the deployment steps complete: first wait N seconds (InitialDelaySeconds), then approximately every 5 seconds probe the service port once, for about 30 consecutive total failures only then is this deployment judged failed. Window ≈ N+150s。not"fail immediately after N seconds".

Forbidden: upon seeing probe failed, change N to 120. Crash loops and loopback binding will not get better just because N is larger.
Increasing N is allowed only when: two logs provethe same process is still doing one-time initialization(JVM warmup, migration) and has not yet listened.

4. Public image (`docker.io`) repeatedly fails → Dockerfile source build

When the node repeatedly fails to connect directly to Docker Hub, do not spin on imageUrl. Write:

FROM docker.io/example/app:latest

Use targetPath to do cloud source build: the CODING build machine pulls the public image, the artifact goes into CCR, and the CloudBase hosting node pulls it over the internal network. This only solvespull topology, and does not replace step 1's Cmd / environment variables / volumes.

5. Supervisor image (s6 / tini / supervisord) exits immediately on startup

PID 1 is often the supervisor process, not the HTTP application. Use two logs to find the child process restart storm. If the image issue records PID 1 / pgrep -f mismatch, follow the documented workaround (absolute path Cmd, disable supervise), and do not tune probe delays. See the reference appendix for examples.

Access guidance

Web/public scenarios -> enable PUBLIC ingress intentionally and pair it with the right auth flow.
Mini Program -> prefer internal direct connection and avoid unnecessary public exposure.
Private ingress scenarios -> keep public access off unless the product requirement clearly needs it.
Database / Redis in a VPC -> this is not solved by OpenAccessTypes. You must set serverConfig.VpcConf and use the database private address. Read references/vpc-and-database.md.

Quick examples

Initialize

{ "action": "init", "serverName": "my-svc", "targetPath": "/abs/ws/my-svc" }

Local run (Function mode)

{ "action": "run", "serverName": "my-svc", "targetPath": "/abs/ws/my-svc", "runOptions": { "port": 3000 } }

Deploy (no VPC-private dependencies)

{
  "action": "deploy",
  "serverName": "my-svc",
  "targetPath": "/abs/ws/my-svc",
  "serverConfig": {
    "OpenAccessTypes": ["PUBLIC"],
    "Cpu": 0.5,
    "Mem": 1,
    "MinNum": 1,
    "MaxNum": 5
  }
}

Deploy (existing app that connects to MySQL / PostgreSQL / Redis over TCP)

{
  "action": "deploy",
  "serverName": "my-existing-app",
  "targetPath": "/abs/ws/my-existing-app",
  "serverConfig": {
    "OpenAccessTypes": ["PUBLIC"],
    "Cpu": 0.5,
    "Mem": 1,
    "MinNum": 1,
    "MaxNum": 5,
    "EnvParams": "{\"DATABASE_URL\":\"postgres://user:pass@10.x.x.x:5432/app\"}",
    "VpcConf": {
      "VpcId": "vpc-xxxxxxxx",
      "SubnetId": "subnet-xxxxxxxx"
    }
  }
}

Valid OpenAccessTypes values: OA (office network access), PUBLIC (public network access), MINIAPP (Mini Program access), VPC (VPC access). Use PUBLIC for web applications that need public HTTPS access.

MinNum: 1 is the recommended default when you want to reduce cold-start latency. If the user explicitly prefers lower cost and accepts more cold starts, explain the tradeoff and let them reduce MinNum to 0.

Best practices

Prefer PRIVATE/VPC or mini-program internal ingress when possible.
For TCP database access, always pair private DB URLs with VpcConf in the same VPC/region as the database.
Use environment variables for secrets and per-environment configuration — read them server-side only; never return them in HTTP responses. CloudBase API Keys come from manageAppAuth(action="createApiKey"), not from a local client login file.
Verify configuration before and after deployment with queryCloudRun(action="detail").
Keep startup work small to reduce cold-start impact.
For Agent scenarios, use the Agent SDK skill for protocol and adapter details instead of duplicating them here.
For smoke tests, return a fixed { "ok": true } / health payload — never deploy httpbin or any service that reflects request headers.

Troubleshooting hints

Access failure -> check ingress access type, domain setup, and whether the instance scaled to zero.
Deployment blocked with "Cloud hosting not yet initialized / not initialized" -> the environment needs CloudRun enabled first: call manageCloudRun(action="initEnv", envId=...) (asynchronous activation) and poll queryCloudRun(action="envStatus") until Status=normal; or open the console 环境 → 云托管 → 开通. For stateless HTTP services, consider an HTTP cloud function instead of CloudRun entirely.
Deployment failure -> follow the Container deploy failure SOP above (and references/image-deploy-troubleshooting.md): image deploys skip getDeployLog and use getProcessLog only; classify scheduling vs port vs exit-on-start with two log pulls. Do not raise InitialDelaySeconds until logs prove a single slow init. Also inspect Dockerfile (source) and CPU/memory ratio.
Deploy rejected with "a deploy task is already running" / "已有部署发布任务运行中" -> read the real task state with queryCloudRun(action="getManageTask") first. Do not retry blindly, and do not set force=true expecting an override — it only skips this tool's confirmation prompt. See the Deploy-task SOP above.
Deploy accepted but the version never leaves creating -> queryCloudRun(action="getManageTask") for latestDeployStatus + taskStatus, then getProcessLog for the deploy-phase steps. Only change Dockerfile / serverConfig once the logs actually point at code or config.
Local run failure -> remember only Function mode is supported by local-run tools.
Performance issues -> reduce dependencies, optimize initialization, and tune minimum instances.
DB / Redis connection failure after a successful deploy -> almost always missing or wrong VpcConf, wrong private host, or security group. Follow references/vpc-and-database.md before rewriting application code.
CloudBase SDK call fails inside the service with missing / invalid credentials -> the credential gate above was skipped, or the variable name is not the official one. Issue a key with manageAppAuth(action="createApiKey"), inject it as CLOUDBASE_APIKEY through EnvParams, redeploy, then verify a real read. See ../cloud-functions/references/http-function-credentials.md.

Reference index

All packaged reference files (required for skill lint reachability):