Declarative Deployment (tcb deploy)

Version Requirement

tcb deploy declarative orchestration is available since v3.8.0 and requires cloudbaserc.json v2.1.

tcb deploy reads cloudbaserc.json (v2.1) in the project root and orchestrates deployment of cloud functions, cloud apps, static hosting, gateway routes, and database migrations in dependency order — no need to call single-resource commands one by one.

First time using CloudBase CLI?

Read the Quick Start first: install the CLI, log in to your account, and generate cloudbaserc.json, then come back to this page to use tcb deploy.

Differences from Single-Resource Commands

Dimension	`tcb deploy`	`tcb fn deploy` / `tcb hosting deploy`
Config source	One `cloudbaserc.json` declares all resources	Each command passes its own arguments
Orchestration	database → functions → app → hosting → gateway auto-ordered	Single resource
Dependencies	Functions depend on new Schema (database first), gateway depends on functions/hosting	Not aware
Idempotency	Cloud existence check; every deploy is executed	Full execution every time
Overwrite confirmation	Confirms before overwriting existing functions (`--yes` to proceed)	`--force`

Complete Workflow

The standard end-to-end workflow for declarative deployment: Initialize Configuration → validate → preview changes → deploy.

Step	Command	Purpose	Completion Signal
1 Initialize config	`tcb config init`	Auto-detects project resources (cloud function dirs / frontend framework / static hosting dirs) and interactively generates `cloudbaserc.json` (v2.1)	Valid config created in the project root
2 Validate before deploy	`tcb validate`	Validates schema version / envId / resource dirs / reference consistency	Exit code 0, resource overview printed
3 Preview changes	`tcb deploy --dry-run`	Outputs the resource-level change plan: field-level diffs (from → to) — no actual deployment	Change plan matches expectations
4 Deploy	`tcb deploy`	Orchestrates deployment in database → functions → app → hosting → gateway order	Deployment succeeds

Configuration Example

Minimal cloudbaserc.json (v2.1):

{
  "envId": "your-env-id",
  "version": "2.1",
  "functions": [
    { "name": "pay-common", "type": "Event", "handler": "index.main" }
  ],
  "hosting": [
    {
      "name": "web",
      "root": "web",
      "framework": "vite",
      "outputDir": "dist",
      "deployPath": "/web"
    }
  ],
  "gateway": {
    "routes": [
      { "path": "/api", "target": "function:pay-common" },
      { "path": "/web", "target": "hosting:web" }
    ]
  }
}

Corresponding project structure:

project/
├── cloudbaserc.json
├── functions/
│   └── pay-common/
│       └── index.js
└── web/
    └── dist/        # build output (or let tcb deploy build locally)

Directory Convention

See Project Directory Convention below for the full layout. Database migrations default to cloudbase/migrations/.

Deployment Flow

Overwrite Confirmation

Functions that already exist in the cloud (update scenario) are confirmed before overwriting
--yes proceeds directly; interactive mode confirms item by item
When no confirmation mechanism is provided, it conservatively skips (never overwrites production without consent)

Command Options

`--dry-run`

Outputs only the change plan (terraform plan mindset), without deploying:

tcb deploy --dry-run

Shows field-level changes (from → to) and database migration plans.

`--only` / `--skip`

Deploy only specified types / skip specified types:

tcb deploy --only=functions          # deploy cloud functions only
tcb deploy --only=hosting,gateway    # deploy hosting and gateway only
tcb deploy --skip=gateway            # skip gateway

Available types: database / functions / app / hosting / gateway.

`--mode` / `--env-id`

Apply environment-specific configuration:

tcb deploy --mode=production       # apply envOverrides.production + .env.production
tcb deploy --env-id=xxx            # specify environment (highest priority)

`--yes`

Proceed with function overwrite updates directly (CI / AI Agent scenarios):

tcb deploy --yes

Concurrency (`--concurrency`)

Default 1 (strictly serial), consistent with historical behavior. When set, multiple resource instances of the same type are deployed in parallel; cross-type resources still follow the dependency order (database → functions → app → hosting → gateway) serially, without breaking dependencies.

tcb deploy --concurrency 3          # parallelize across functions/hosting sites, max 3 at a time

Applies only to "consecutive instances of the same type" (e.g., multiple hosting sites, multiple functions); functions vs hosting, hosting vs gateway always run serially.
Concurrency is capped at 20 to avoid excessive pressure on backend APIs.

Failure Interruption (`--continue-on-error`)

Default is fail-fast: if any resource fails to deploy, subsequent resources are interrupted and the process exits with a non-zero exit code (for CI/CD awareness). To "run through everything and view the failure count at the end", add --continue-on-error:

tcb deploy --continue-on-error      # continue deploying the rest even if one resource fails

Exception: database failures always force interruption (regardless of --continue-on-error), because subsequent resources may depend on the newly created database schema.

Resource Configuration Overview

See the corresponding docs for full field details:

Resource	Config field	Key notes	Docs
Database migrations	`database`	`postgresql` only; migration files `14-digit-timestamp_name.sql`, default dir `cloudbase/migrations/`; conflicts abort deployment	PostgreSQL Management
Cloud functions	`functions`	Event / HTTP types; zip code or image deployment (`buildStrategy`); HTTP functions support `public` anonymous access and `gatewayPath` gateway routing	Function Configs · Deploying Functions
Cloud app	`app`	Build path decided by `framework`: `static` direct upload / others cloud build	Application Deployment
Static hosting	`hosting`	Array of multiple sites; local build (install + build) then upload	Static Website Hosting
Gateway routes	`gateway.routes`	`target`: `function:<name>` / `hosting:<name>`; pathRewrite auto-generated	Configuration File - Gateway
Environment overrides	`envOverrides`	Merged by `--mode`	Config File

Function target type

The gateway route target: function:<name> supports two function types:

HTTP type (type: "HTTP") → created as a WEB_SCF route
Event type (regular function) → created as an SCF route (verified to work; the gateway wraps the HTTP request as an event and forwards it to the function)

The CLI automatically queries function details to determine the type; both types can serve as gateway targets.

Database Migration (database)

Declarative deployment supports the database resource, applying PostgreSQL migrations in order according to the SQL files under the database.migrations directory:

Dimension	Description
Supported types	Only `type: postgresql` (`type: nosql` is passed through without orchestration)
Migration files	Named `14-digit-timestamp_lowercase-name.sql` (e.g. `20260101120000_init.sql`), default dir `cloudbase/migrations/`
Plan (`--dry-run`)	Aggregated into a single change item: `pending → create`
Conflict handling	Target database already has a migration with the same name → abort deployment
Failure policy	`database` failure always forces interruption (even with `--continue-on-error`), since subsequent resources may depend on the new schema

Database migration failure aborts the entire deployment

database is ordered first in orchestration (database → functions → app → hosting → gateway); once it fails, subsequent resources are not executed. Run tcb deploy --dry-run first to confirm the migration plan is correct.

Project Directory Convention

Recommended layout (using vibe-app as an example):

vibe-app/
├── cloudbaserc.json          # declarative config (core contract, envId/version 2.1)
├── .env                      # secrets (not in Git; reads .env.<mode> when --mode <mode>)
├── .env.example              # secrets template (in Git)
├── cloudbase/migrations/               # database migrations (SQL, default dir)
│   ├── 20260101120000_init.sql
│   └── 20260102150000_add_users.sql
├── functions/                # cloud function code (functionRoot defaults to ./functions)
│   ├── task-runner/          # Event function: exports.main(event, context)
│   └── api-server/           # HTTP function: requires scf_bootstrap
├── web/                      # frontend code (pointed by hosting[].root)
└── Dockerfile                # optional, for image deployment (inside function dir)

Path resolution rules:

Resource	Config field	Default / resolution
Database migration dir	`database.migrations`	`cloudbase/migrations/` (relative to project root)
Function root	`functionRoot`	`functions/`
Function code dir	`dir` / `functionRoot`+`name`	Explicit `dir` → `{cwd}/{dir}` (independent of functionRoot); otherwise `{cwd}/{functionRoot}/{name}`
Frontend site	`hosting[].root`	Directory relative to cloudbaserc

FAQ

1. `gateway.routes` validation failure (should NOT have additional properties)

Schema v2.1 does not allow extra fields. For example, cdnType is not a valid route field — remove it; use accessType (DIRECT / CDN / CUSTOM / EO) to control CDN access:

{ "path": "/web", "target": "hosting:web", "accessType": "DIRECT" }

2. HTTP function dependency installation rules

Function type	Runtime	Dependency installation
Event	Any	Cloud-side install (default)
HTTP	Node.js	Cloud-side install (default)
HTTP	Non-Node.js (Python/Php/Java/Go)	Must install locally and upload with the code

For HTTP non-Node.js functions, ensure dependencies are installed locally (e.g., Python pip install into the function directory).

3. Will existing functions be overwritten?

Functions that already exist (update scenario) require confirmation by default; --yes proceeds. Declarative deployment semantics align with tcb fn deploy --force.

4. Domain-level fields do not take effect on already-bound domains

certId / protocol / accessType are domain-level fields (shared by all routes under the same domain). When creating routes on an already-existing domain, these fields do not override the domain's original values (e.g. if the domain is already bound with HTTP_AND_HTTPS, setting protocol: "HTTPS" has no effect) — this is the platform's safety behavior to avoid affecting other business routes under the same domain. They only take effect when the domain is first created.

5. Gateway route idempotency semantics

tcb deploy gateway routes converge idempotently (create / update / skip):

Route does not exist → create (create)
Route exists and the explicitly declared fields match → skip (skip)
Route exists but explicitly declared fields differ → update (update, calls modifyHttpServiceRoute)

Only explicitly declared fields are compared (enableAuth / enablePathTransmission are compared only when explicitly configured; qpsPolicy / pathRewrite are compared only when the local value is present), and undeclared fields do not override the cloud configuration. Duplicate paths are not treated as errors (unlike the INVALID_PARAM of imperative tcb routes add). See Configuration File - Gateway for the authoritative field definitions.

Differences from Single-Resource Commands​

Complete Workflow​

Configuration Example​

Deployment Flow​

Overwrite Confirmation​

Command Options​

--dry-run​

--only / --skip​

--mode / --env-id​

--yes​

Concurrency (--concurrency)​

Failure Interruption (--continue-on-error)​

Resource Configuration Overview​

Database Migration (database)​

Project Directory Convention​

FAQ​

1. gateway.routes validation failure (should NOT have additional properties)​

2. HTTP function dependency installation rules​

3. Will existing functions be overwritten?​

4. Domain-level fields do not take effect on already-bound domains​

5. Gateway route idempotency semantics​

References​