Skip to main content

tcb routes add

Create one or more routes for a domain, forwarding requests by "domain + path" to functions, CloudBase Run services, or static hosting.

v3.0.0+

tcb routes has been available since v3.0.0.

Usage​

tcb routes add --data '<JSON>' [options]

Parameters​

ParameterRequiredDescriptionDefault
--data <json>YesRoute configuration JSON—
-e, --env-id <envId>NoEnvironment IDenvId in the configuration

Configuration format​

{
  "domain": "api.example.com",
  "routes": [
    {
      "path": "/api",
      "upstreamResourceType": "CBR",
      "upstreamResourceName": "my-service",
      "upstreamResourceVersion": "optional, functions only",
      "enable": true,
      "enableAuth": false,
      "enableSafeDomain": true,
      "enablePathTransmission": false,
      "pathRewrite": { "prefix": "/newpath" },
      "qpsPolicy": {
        "qpsTotal": 500,
        "qpsPerClient": { "limitBy": "ClientIP", "limitValue": 20 }
      }
    }
  ]
}
FieldTypeRequiredDescription
domainstringYesTarget domain, already bound with tcb domains add
routes[].pathstringYesPath starting with /, no wildcards. Each segment allows letters, digits, ., _, - and at most 50 characters; reserved prefixes /__auth and /.well-known are rejected
routes[].upstreamResourceTypestringYesSCF (function), CBR (CloudBase Run), STATIC_STORE (static hosting), WEB_SCF (web function), LH (lightweight server)
routes[].upstreamResourceNamestringYesUpstream service name
routes[].upstreamResourceVersionstringNoUpstream version, SCF / WEB_SCF only; see Forwarding version. Defaults to $DEFAULT when omitted (v3.8.10+)
routes[].enablebooleanNoWhether the route is enabled, default true
routes[].enableSafeDomainbooleanNoWhether to enforce the security domain check, default true

Authoritative definitions of enableAuth / enablePathTransmission / pathRewrite / qpsPolicy are in Configuration file - gateway. Differences between the imperative and declarative forms:

  • pathRewrite: the imperative form supports prefix only; the declarative form also supports staticStorePrefix
  • qpsPolicy: qpsTotal is capped at 500 here and 100–100000 declaratively; qpsPerClient.limitValue is capped at 30 declaratively
  • enableAuth / enablePathTransmission: identical semantics

Examples​

# Forward to a CloudBase Run service
tcb routes add -e <envId> --data '{"domain":"api.example.com","routes":[{"path":"/api","upstreamResourceType":"CBR","upstreamResourceName":"my-service"}]}'

# Forward to a function with authentication
tcb routes add -e <envId> --data '{"domain":"api.example.com","routes":[{"path":"/func","upstreamResourceType":"SCF","upstreamResourceName":"my-function","enableAuth":true}]}'

# Static site root
tcb routes add -e <envId> --data '{"domain":"www.example.com","routes":[{"path":"/","upstreamResourceType":"STATIC_STORE","upstreamResourceName":"website"}]}'

# With QPS limits
tcb routes add -e <envId> --data '{"domain":"api.example.com","routes":[{"path":"/v1","upstreamResourceType":"CBR","upstreamResourceName":"backend","qpsPolicy":{"qpsTotal":1000,"qpsPerClient":{"limitBy":"ClientIP","limitValue":50}}}]}'

# Several routes in one call
tcb routes add -e <envId> --data '{"domain":"api.example.com","routes":[{"path":"/v1","upstreamResourceType":"SCF","upstreamResourceName":"func-v1"},{"path":"/v2","upstreamResourceType":"CBR","upstreamResourceName":"service-v2"}]}'

# Forward to a specific function version
tcb routes add -e <envId> --data '{"domain":"api.example.com","routes":[{"path":"/func-v2","upstreamResourceType":"SCF","upstreamResourceName":"my-function","upstreamResourceVersion":"2"}]}'

Notes​

  • path rejects wildcards (/api/*, /*); to cover subpaths, declare several exact routes such as /api and /api/v1
  • STATIC_STORE supports one path level only (/ or /static), nested paths fail
  • Duplicate paths under one domain fail with INVALID_PARAM; change an existing route with tcb routes edit
  • The imperative form requires the domain to be bound first via tcb domains add; declarative tcb deploy binds it automatically