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 Hosting vs HTTP Cloud Functions" 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 decide the database access method (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 (where classic drivers/ORMs cannot be replaced) use 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 Hosting vs HTTP Cloud Functions (choose by requirements, not by files)

Core principle:HTTP Cloud Functions preferred. Use Cloud Hosting only when the requirements truly need it; having Dockerfile does not mean Cloud Hosting is mandatory.

HTTP Cloud Functions are more suitable (preferred):

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

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

Long connections: WebSocket, SSE long connections, server-side push
Custom system dependencies / arbitrary language runtime / need for a stable independent process
Database / Redis access within a 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 Dockerfile , no long connections, no custom runtime, and no VPC database access → choose HTTP Cloud Functions instead of Cloud Hosting; if the same code has WebSocket long connections → then choose Cloud Hosting.

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

Core principle:For data that can be accessed via CloudBase SDK/gateway, always prefer 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 possible.

Preferred: SDK / gateway path (no need for VpcConf, no need for database account credentials)

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 CloudBase Run by combining with the "HTTP cloud functions first" from the previous section

Only go with TCP direct connection in the following cases (the full references/vpc-and-database.md process must be completed):

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

Decision action: When DATABASE_URL / DB dependency signals are scanned, stop first and answer "can this data access be switched to the SDK/gateway", then decide whether to enter the VPC checklist—do not proceed by default along 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 credentials, not the CloudBase resource access credentials. When service code needs to call CloudBase resources (PG app.rdb() / NoSQL / storage / functions), first determine the credential source, then write the 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 make up your own. When changing environment variables, keep the 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 taking it offline or rotating, manageAppAuth(action="deleteApiKey", keyId=...) andredeploy. After rotation, leftover copies in old instances will not report errors; they will only silently become invalid.

Do not assume that the CloudBase Run container automatically carries usable CloudBase credentials — after deployment, verify with one real SDK read (verify more than twice; do not just check whether the process started). For the 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 is anenvironment-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 the deployment phase 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 it does not depend on CODING. Params: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 hitting "an existing deployment release task is running", first confirm whether the task is really progressing; and when 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 only use getDeployLog：

cloud source build(pass targetPath, use CODING build)
- first queryCloudRun(action="getDeployLog", detailServerName=..., buildId=...) querybuild logs(compile/package failure)
- then queryCloudRun(action="getProcessLog", detailServerName=..., runId=...) queryruntime logs(deployment steps + container startup/health check)
existing image deployment(pass imageUrl、DeployType=image）
- skip getDeployLog(no build process; and depends on CODING, will fail directly if not logged in)
- directly queryCloudRun(action="detail") or getDeployRecords get latestDeploy.RunId, then getProcessLog query runtime logs

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

Deploy-task SOP (when hitting "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, deployment steps are progressing	keep waiting, don't resend deploy
task has ended (not in running state), but deploy is still rejected	only then consider retrying
task has been stuck in a non-terminal state for a long time, and the version is also stuck at `creating` not moving	record `taskId` / `latestDeployStatus` / time window as evidence, don't spin retrying

force=true does not solve this problem: it only skips this tool's confirmation prompt, it will not cancel or override the existing release task on the server side —— using it as a "force override" will only cause one wasted attempt.

For the troubleshooting order on the log side (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 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 is enough, 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,must pass imageUrl, don't fall back to source build just because there is a local source directory.

Decision path (direct fill vs local relay):

Publicly pullable anonymously(such as 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 from that registry address to build and deploy.If docker.io / Docker Hub repeatedly fails to pull on the node, do not idle-loop retries: switch to Dockerfile FROM <public-image> + targetPath source build (CODING pulls public images, artifacts are pulled from CCR on the intranet). See step 4 of the SOP below.
Private / login-required registries（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 take ccr.ccs.tencentyun.com/<ns>/app:latest and pass it 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 in a new environment, first manageCloudRun(action="initEnv", envId=...), and use queryCloudRun(action="envStatus") to poll until Status=normal; when not enabled, deploy will be blocked and you will be guided 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 image's official documentation; do not apply 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) the next_step returned for the image defaults to pointing 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 image's official documentation → then check the runtime logs → only then 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 image's official 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 runs persistently 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 flags off by default, etc.) → EnvParams
Data directory mount → serverConfig.VolumesConf
Health endpoint(CloudRun readiness probesservice port, not any arbitrary HTTP path)

If any item is missing before deployment, 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")。

Startup logs existing ≠ the service running normally. banners, s6/tini lines, and sidecar "listening" cannot prove the probe target has come up.

Compare two logs to determine liveness: Pull again after 20–40 seconds getProcessLog。

Observe	Characterize
Only scheduling/creation steps (`create_eks_*`), no container stdout	Pod scheduling / image pulling
The same startup banner / PID 1 line appears repeatedly (timestamps advance, content is almost identical)	Container exits immediately on startup / restart loop
The process is still there, but listening on `127.0.0.1` or port ≠ `serverConfig.Port`	Port / bind address issue
The two pulls arethe same startup processLogs continue to be emitted afterward, banner does not repeat	Only then could it be slow startup

3. Actual Readiness probe mechanism (do not adjust latency first under any circumstances)

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

Prohibited: If you see 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 → build from Dockerfile source

When nodes repeatedly fail to connect directly to Docker Hub, do not spin on imageUrl. Write:

FROM docker.io/example/app:latest

Use targetPath to build from cloud source: the CODING build machine pulls the public image, the artifact goes into CCR, and cloud-hosted nodes pull 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 the two logs to find the child process restart storm. If the image issue records PID 1 / pgrep -f false match, follow the documented workaround (absolute path Cmd, disable supervise), and do not adjust the probe latency. 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 "not initialized yet / not initialized" -> the environment needs CloudRun enabled first: call manageCloudRun(action="initEnv", envId=...) (asynchronous provisioning) 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" / "a deploy and release 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):