HTTP Service 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 access services. 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

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.

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 (supports 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, supports wildcards `/`, e.g. `/api/`
`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[].enableAuth`	boolean	No	Whether to enable Identity Authentication, default `false`
`routes[].enableSafeDomain`	boolean	No	Whether to enable safe domain validation, default `true`
`routes[].enablePathTransmission`	boolean	No	Whether to enable path transmission, default `false`
`routes[].pathRewrite`	object	No	Path rewrite configuration, `{ "prefix": "/newpath" }`
`routes[].qpsPolicy.qpsTotal`	number	No	Total QPS limit for the resource, maximum 500
`routes[].qpsPolicy.qpsPerClient`	object	No	Per-client rate limiting: `{ "limitBy": "ClientIP" \\| "UserID", "limitValue": N }`

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"}]}'

Caution

Duplicate paths cannot exist under the same domain
The domain must be bound via tcb domains add before creating a route

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, and 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

HTTP Service Routing Management

List routes​

Create route​

Modify route​

Delete route​

Typical Workflow​

Command Quick Reference​