Declarative Deployment Orchestrator

Version Notice

Declarative deployment orchestration (app.deployOrchestrator) is available since v5.1.0, corresponding to CLI tcb deploy (≥ v3.8.0).

DeployOrchestrator provides one-shot orchestrated deployment: reads a single cloudbaserc.json (v2.1) config and deploys all resources in dependency order (database → functions → app → hosting → gateway), with dry-run plan preview, function overwrite confirmation, and local state snapshot for true incremental skips.

Access via app.deployOrchestrator (same implementation as CLI tcb deploy — capability is hosted in manager-node).

No Interactive UI

manager-node does not bundle any interactive UI. Function overwrite confirmation is fully externalized: pass yes: true to proceed, or inject a confirmUpdate callback to decide per item.

---

deployPlan

1. Description

Computes the deployment plan (dry-run) without performing any actual deployment.

Signature: app.deployOrchestrator.deployPlan(options): Promise<IDeployPlanItem[]>

2. Parameters

Field	Required	Type	Description
config	Yes	Record<string, any>	Parsed cloudbaserc config (envOverrides already merged)
envId	Yes	String	Environment ID
only	No	ResourceType[]	Deploy only these types
skip	No	ResourceType[]	Skip these types
refresh	No	Boolean	Ignore local state skip decisions, force cloud comparison (drift detection)
cwd	No	String	Project root, default process.cwd()

ResourceType: database / functions / app / hosting / gateway

3. Returns

IDeployPlanItem[]:

Field	Type	Description
type	ResourceType	Resource type
name	String	Resource name
status	String	create / update / skip / conflict (database, aborts) / deploy
action	String	Human-readable action
changes	Array	Field-level changes (from → to)
fileDiff	Object	hosting file diff (added/modified/deleted + totalChanged)

4. Example

import CloudBase from '@cloudbase/manager-node'

const app = CloudBase.init({
  secretId: 'Your SecretId',
  secretKey: 'Your SecretKey',
  envId: 'Your envId'
})

const plan = await app.deployOrchestrator.deployPlan({
  config: { envId: 'xxx', functions: [{ name: 'fn-a' }] },
  envId: 'xxx',
  cwd: process.cwd()
})

for (const item of plan) {
  console.log(`[${item.type}] ${item.name}: ${item.action}`)
}

---

deploy

1. Description

Executes the deployment (with overwrite confirmation).

Signature: app.deployOrchestrator.deploy(options): Promise<IDeployResult>

2. Parameters

Field	Required	Type	Description
config	Yes	Record<string, any>	Parsed cloudbaserc config
envId	Yes	String	Environment ID
dryRun	No	Boolean	When true, only outputs the plan without deploying
yes	No	Boolean	Proceed with existing function (update) overwrites (AI Agent / CI)
confirmUpdate	No	(item) => Promise<boolean>	Callback per update item; return true to execute / false to skip
only / skip	No	ResourceType[]	Type filters
refresh	No	Boolean	Force cloud comparison (drift detection)
cwd	No	String	Project root
log	No	Object	Log callbacks (info/success/warn/error)

3. Returns

IDeployResult:

Field	Type	Description
plan	IDeployPlanItem[]	Full deployment plan
results	Array	Each item: { type, name, ok, url?, error?, reason? }

results semantics:

• ok: true → success; url is the access URL (if any)
• ok: false + error → deployment failure reason
• ok: false + reason: 'no-confirm' → no confirmation mechanism, conservatively skipped (never overwrites production)
• ok: false + reason: 'skipped-by-user' → user cancelled the overwrite

4. Example

import CloudBase from '@cloudbase/manager-node'

const app = CloudBase.init({
  secretId: 'Your SecretId',
  secretKey: 'Your SecretKey',
  envId: 'Your envId'
})

// AI Agent / CI: proceed with all overwrites
const result = await app.deployOrchestrator.deploy({
  config: { envId: 'xxx', functions: [{ name: 'fn-a' }] },
  envId: 'xxx',
  yes: true,
  cwd: process.cwd()
})

if (result.results.every(r => r.ok)) {
  console.log('Deploy complete')
} else {
  for (const r of result.results.filter(r => !r.ok)) {
    console.error(`[${r.type}] ${r.name} failed: ${r.error || r.reason}`)
  }
}

---

Notes

Idempotency and True Incrementality

• Functions: cloud existence check (ListFunctions) → create / update; no local hash
• hosting: local .cloudbase/state.json fingerprint snapshot; skip when identical
• app: local state config snapshot; skip when identical
• refresh: true forces re-comparison against the cloud, ignoring the local snapshot

database Conflict Aborts

When a database migration has conflicts, deployment aborts (later resources may depend on the new Schema). The plan item appears with status: 'conflict'.

Version Mapping

manager-node	CLI	Description
≥ v5.1.0	≥ v3.8.0	Declarative deployment orchestration available

References

• Declarative Deployment (tcb deploy)
• Pre-deploy Validation (tcb validate)