Custom Domain Management

v3.0.0+

The tcb domains command has been available since v3.0.0, replacing the custom domain feature of the original tcb service domain.

The tcb domains is used to manage custom domains for HTTP access services. After binding a custom domain, you can access the TCB HTTP service via your own domain and route traffic to upstream services such as SCF, Cloud Run, and Static Hosting via routing rules.

The difference between cors and domains

• tcb cors: Manages the allowlist for Web SDK security domains (CORS authentication), controlling which web domains can access TCB resources. See Security Domain Management.
• tcb domains: Manages custom domains for HTTP access services, requiring SSL certificate binding and working in conjunction with tcb routes routing rules.

Prerequisites

Before binding a custom domain, ensure that:

1. The domain has completed ICP filing.
2. You have applied for and uploaded a valid SSL certificate in the Tencent Cloud SSL Certificate Console and obtained the certificate ID.
3. After binding is successful, you need to point the domain's DNS resolution CNAME record to the TCB environment domain name.

View Custom Domain List

View bound custom domains in the current environment:

tcb domains ls -e <envId>

Supports pagination and filtering:

# Pagination Query
tcb domains ls -e <envId> --limit 50 --offset 0

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

# Filter by Access Method
tcb domains ls -e <envId> --filter "AccessType=CDN"

# Multi-condition Combination (AND relationship, connected by &)
tcb domains ls -e <envId> --filter "DomainType=HTTPSERVICE&AccessType=DIRECT"

--filter filterable fields:

Field	Description	Optional Values
Domain	Domain	Any domain name string
DomainType	Domain Type	HTTPSERVICE (default), CBR, ANYSERVICE, AI_AGENT, VM, INTEGRATION_CALLBACK
AccessType	Access Method	DIRECT, CDN, CUSTOM

tip

By default, only displays HTTPSERVICE domain names manually bound by users. To view other domain types, use --filter "DomainType=CBR" etc.

Bind Custom Domain

Bind a custom domain to the HTTP access service:

# Basic Usage (Direct Access, Default)
tcb domains add api.example.com --certid <certId> -e <envId>

# CDN Access
tcb domains add api.example.com --certid <certId> --access-type CDN -e <envId>

# Custom Access (Requires specifying CNAME origin)
tcb domains add api.example.com --certid <certId> --access-type CUSTOM --custom-cname origin.example.com -e <envId>

# Disabled After Binding (Enabled by Default)
tcb domains add api.example.com --certid <certId> --disable -e <envId>

Command Parameters:

Parameter	Description	Required
<domain>	Domain to be bound	Required
--certid <certId>	SSL Certificate ID, obtained from the Tencent Cloud SSL Certificate Console	Required
--access-type <type>	Access method: DIRECT (Direct, default), CDN (Access TCB CDN), CUSTOM (Custom)	No
--custom-cname <cname>	Custom CNAME, available only when --access-type CUSTOM	No
--disable	Disable the domain after binding (enabled by default)	No

Caution

• Duplicate domains cannot be bound
• After successful binding, you need to configure the DNS CNAME record for normal access.

Unbind Custom Domain

Unbind bound custom domains:

tcb domains rm api.example.com -e <envId>

Caution

If there are still routes bound to the domain, the unbinding operation will fail. First, use tcb routes delete to delete all routes under this domain, then perform the unbinding operation.

# List routes under the domain
tcb routes list -e <envId> --filter "Domain=api.example.com"

# Delete routes and then unbind the domain
tcb routes delete api.example.com -e <envId> -p /api/*
tcb domains rm api.example.com -e <envId>

Typical Workflow

# 1. Bind Custom Domain (requires an existing SSL certificate)
tcb domains add api.example.com --certid abc123 -e <envId>

# 2. Add routing rules for the domain (forward traffic to the Cloud Run service)
tcb routes add -e <envId> --data '{"domain":"api.example.com","routes":[{"path":"/*","upstreamResourceType":"CBR","upstreamResourceName":"my-service"}]}'

# 3. Configure DNS: Point the CNAME resolution of api.example.com to the TCB environment domain name

# 4. Verify Access
curl https://api.example.com/

Command Quick Reference

Command	Description
tcb domains ls	View custom domain list
tcb domains add <domain> --certid <certId>	Bind custom domain
tcb domains rm <domain>	Unbind custom domain