HTTP Gateway Routing Management

v3.0.0+

The tcb routes command has been available since v3.0.0.

The tcb routes command is used to manage routing rules for HTTP Gateways. Routing rules define how HTTP requests (by domain + path) are forwarded to upstream services such as SCF, Cloud Run, and Static Hosting.

Relationship between Routing and Domain Names

When using tcb routes (imperative), routes must be bound to an existing custom domain. If you have not bound a custom domain yet, please first use tcb domains add to add one. See Custom Domain Management for details.

Difference: declarative deployment (tcb deploy + gateway.routes in cloudbaserc.json) automatically binds the custom domain (idempotently), no need to run tcb domains add first. See Declarative Deployment Gateway and Configuration File - Gateway.

List routes

List all routing configurations in the current environment:

tcb routes list -e <envId>

Supports pagination and filtering:

# Pagination Query
tcb routes list -e <envId> --limit 50 --offset 0

# Filter by Domain
tcb routes list -e <envId> --filter "Domain=api.example.com"

# Filter by Upstream Service Type
tcb routes list -e <envId> --filter "UpstreamResourceType=CBR"

# Multi-condition Combination (AND relationship, connected by &; multiple values separated by commas, OR relationship)
tcb routes list -e <envId> --filter "UpstreamResourceType=SCF&Domain=api.example.com,api2.example.com"

--filter filterable fields:

Field	Description	Optional Values
`Domain`	Domain	Any domain name string, multiple values separated by commas (OR relationship)
`Path`	Route path	Any path string
`UpstreamResourceType`	Upstream service type	`SCF`, `CBR`, `STATIC_STORE`, `WEB_SCF`, `LH`

Create route

Create one or more routing rules for the specified domain by passing JSON configuration via the --data parameter:

tcb routes add -e <envId> --data '<JSON>'

JSON data format:

{
  "domain": "Required, domain",
  "routes": [
    {
      "path": "Required, path (must start with /, no wildcards)",
      "upstreamResourceType": "Required, upstream type",
      "upstreamResourceName": "Required, upstream service name",
      "enable": true,
      "enableAuth": false,
      "enableSafeDomain": true,
      "enablePathTransmission": false,
      "pathRewrite": { "prefix": "/newpath" },
      "qpsPolicy": {
        "qpsTotal": 500,
        "qpsPerClient": {
          "limitBy": "ClientIP",
          "limitValue": 20
        }
      }
    }
  ]
}

Routing configuration field description:

Field	Type	Required	Description
`domain`	string	Yes	Target domain, must have been bound via `tcb domains add`
`routes[].path`	string	Yes	Route path, must start with `/`, *no wildcards `/`**. Each segment allows only letters/digits/`.`/`_`/`-`, each segment ≤ 50 chars; system-reserved prefixes `/__auth` and `/.well-known` are not allowed
`routes[].upstreamResourceType`	string	Yes	Upstream service type: `SCF` (Cloud Function), `CBR` (Cloud Run), `STATIC_STORE` (Static Hosting), `WEB_SCF` (Web Cloud Function), `LH` (Lightweight Application Server)
`routes[].upstreamResourceName`	string	Yes	Upstream service name
`routes[].enable`	boolean	No	Whether to enable route, default `true`
`routes[].enableSafeDomain`	boolean	No	Whether to enable safe domain validation, default `true`

The authoritative definitions of enableAuth / enablePathTransmission / pathRewrite / qpsPolicy are in Configuration File - Gateway. Semantic differences between imperative tcb routes and declarative cloudbaserc.json:

pathRewrite: imperative only supports prefix; declarative additionally supports staticStorePrefix (auto-generated for hosting routes when not configured)
qpsPolicy: qpsTotal max 500 in imperative, 100–100000 in declarative; qpsPerClient.limitValue 0–30 in declarative
enableAuth / enablePathTransmission: same semantics in both

Usage Example:

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

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

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

# Route with QPS Rate Limiting
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}}}]}'

# Create multiple routes at once
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"}]}'

No Wildcards in Paths

path does not support wildcards (e.g. /api/* and /* will be rejected). To match all sub-paths under a first-level path, configure multiple exact-path routes (e.g. /api, /api/v1, /api/v2). Static Hosting (STATIC_STORE) only supports first-level paths (e.g. / or /static); multi-level paths will be rejected.

Note

Duplicate paths cannot exist under the same domain: duplicate paths are rejected (reports INVALID_PARAM); to adjust an existing route, use tcb routes edit
The domain must be bound via tcb domains add before creating a route (imperative tcb routes; declarative tcb deploy binds automatically, see the note at the top)

Modify route

Incrementally update existing routing configurations. Locate the route by domain + path, and only update the fields that are passed in:

tcb routes edit -e <envId> --data '<JSON>'

JSON data format (same as for creation; path is a required key for locating, other fields are passed in as needed):

# Change the upstream service of the route
tcb routes edit -e <envId> --data '{"domain":"api.example.com","routes":[{"path":"/api","upstreamResourceName":"new-service"}]}'

# Disable route
tcb routes edit -e <envId> --data '{"domain":"api.example.com","routes":[{"path":"/api","enable":false}]}'

# Enable Identity Authentication and path transmission
tcb routes edit -e <envId> --data '{"domain":"api.example.com","routes":[{"path":"/api","enableAuth":true,"enablePathTransmission":true}]}'

# Update QPS Rate Limiting Configuration
tcb routes edit -e <envId> --data '{"domain":"api.example.com","routes":[{"path":"/v1","qpsPolicy":{"qpsTotal":200,"qpsPerClient":{"limitBy":"ClientIP","limitValue":20}}}]}'

tip

Modification is an incremental update; only the fields passed in will be updated, while fields not passed in remain unchanged.

Delete route

Delete routing rules under the specified domain:

# Delete a single route
tcb routes delete api.example.com -e <envId> -p /api

# Delete multiple routes simultaneously (comma-separated)
tcb routes delete api.example.com -e <envId> -p "/api/v1,/api/v2"

Command Parameters:

Parameter	Description	Required
`<domain>`	Target domain	Required
`-p, --path <paths>`	Route paths to delete, multiple paths separated by commas	Required

Typical Workflow

# 1. First, bind a custom domain (see the domains documentation)
tcb domains add api.example.com --certid <certId> -e <envId>

# 2. Create routing rules
tcb routes add -e <envId> --data '{"domain":"api.example.com","routes":[{"path":"/api","upstreamResourceType":"CBR","upstreamResourceName":"my-service"}]}'

# 3. View routing configuration
tcb routes list -e <envId> --filter "Domain=api.example.com"

# 4. Update route (if needed)
tcb routes edit -e <envId> --data '{"domain":"api.example.com","routes":[{"path":"/api","enableAuth":true}]}'

# 5. Delete route (if needed)
tcb routes delete api.example.com -e <envId> -p /api

Command Quick Reference

Command	Description
`tcb routes list`	List routes with filtering and pagination support
`tcb routes add --data <json>`	Create routing rules
`tcb routes edit --data <json>`	Incrementally update routing configuration
`tcb routes delete <domain> -p <paths>`	Delete route

List routes​

Create route​

Modify route​

Delete route​

Typical Workflow​

Command Quick Reference​