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 Gateways. After binding a custom domain, you can access CloudBase resources via your own domain and route traffic to upstream services such as SCF, Cloud Run, and Static Hosting via routing rules.
Platform Edition Support
The domains ls / add / edit / rm commands support the Platform Edition: specifying --platform-id <platformId> (the Platform Edition resource pool ID) operates domains under the Platform Edition resource pool, mutually exclusive with -e <envId>; without it, environment-level behavior remains unchanged. Cache purge commands (cache purge / cache task) do not support the Platform Edition. The Platform Edition is an account-level package solution. For more information, see Platform Edition Overview.
The difference between cors and domains
tcb cors: Manages the allowlist for Web SDK security domains (CORS authentication), controlling which web domains can access CloudBase resources. See Security Domain Management.tcb domains: Manages custom domains for HTTP Gateways, requiring SSL certificate binding and working in conjunction withtcb routesrouting rules.
Prerequisites
Before binding a custom domain, ensure that:
- The domain has completed ICP filing.
- You have applied for and uploaded a valid SSL certificate in the Tencent Cloud SSL Certificate Console and obtained the certificate ID.
- After binding is successful, you need to point the domain's DNS resolution CNAME record to the CloudBase 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"
# Query domains under a Platform Edition resource pool (v3.8.3+)
tcb domains ls --platform-id <platformId>
--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, EO |
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 Gateway:
# 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>
# Bind a domain under a Platform Edition resource pool (v3.8.3+)
tcb domains add api.example.com --certid <certId> --platform-id <platformId>
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 CloudBase CDN), CUSTOM (Custom), EO (Access CloudBase EdgeOne) | No |
--custom-cname <cname> | Custom CNAME, available only when --access-type CUSTOM | No |
--disable | Disable the domain after binding (enabled by default) | No |
--platform-id <platformId> | Platform Edition resource pool ID. When specified, the domain is bound under the Platform Edition resource pool, mutually exclusive with -e (v3.8.3+) | No |
Caution
- Duplicate domains cannot be bound
- After successful binding, you need to configure the DNS CNAME record for normal access.
Update Custom Domain Configuration
v3.8.3+
Update domain-level fields (certificate, access type, enable status, etc.) of a bound custom domain, without modifying route configuration. Only explicitly specified fields are updated:
# Update the SSL certificate
tcb domains edit api.example.com --certid <certId> -e <envId>
# Change the access type to CDN
tcb domains edit api.example.com --access-type CDN -e <envId>
# Custom access (requires specifying the CNAME origin)
tcb domains edit api.example.com --access-type CUSTOM --custom-cname origin.example.com -e <envId>
# Disable the domain
tcb domains edit api.example.com --disable -e <envId>
# Preview the configuration to be updated (without actual execution)
tcb domains edit api.example.com --certid <certId> --dry-run -e <envId>
# Update a domain under a Platform Edition resource pool (v3.8.3+)
tcb domains edit api.example.com --platform-id <platformId> --access-type EO --certid <certId> --enable
Command Parameters:
| Parameter | Description | Required |
|---|---|---|
<domain> | Domain to be updated | Required |
--certid <certId> | SSL Certificate ID to update, obtained from the Tencent Cloud SSL Certificate Console | No |
--access-type <type> | Access type to update: DIRECT (Direct), CDN (Access TCB CDN), CUSTOM (Custom), EO (Access TCB EdgeOne) | No |
--custom-cname <cname> | Custom CNAME to update, available only when --access-type CUSTOM | No |
--enable | Update the domain to enabled status, mutually exclusive with --disable | No |
--disable | Update the domain to disabled status, mutually exclusive with --enable | No |
--dry-run | Preview mode, only displays the configuration to be updated without actual execution | No |
--platform-id <platformId> | Platform Edition resource pool ID. When specified, the domain is updated under the Platform Edition resource pool, mutually exclusive with -e (v3.8.3+) | No |
Caution
- At least one field to update must be specified (
--certid/--access-type/--custom-cname/--enable/--disable) - The domain must already be bound (viewable via
tcb domains ls); to add a new domain, usetcb domains add - Only domain-level configuration is updated; to modify routing rules, use
tcb routes edit
Unbind Custom Domain
Unbind bound custom domains:
tcb domains rm api.example.com -e <envId>
# Unbind a domain under a Platform Edition resource pool (v3.8.3+)
tcb domains rm api.example.com --platform-id <platformId>
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>
Purge Cache
Purge the CDN or EdgeOne (EO) cache of an HTTP service domain. The domain must be connected to CDN or EdgeOne before purging.
Purge granularity
url(exact URL): supported by both CDN and EO, targets must include thehttp://orhttps://protocol prefixprefix(directory): EO only, targets must include the protocol prefix, e.g.https://example.com/static/host(entire domain): EO only, targets can be a bare domain or a domain with protocol
Submit a purge task
# Purge a single URL (CDN or EO)
tcb domains cache purge https://example.com/index.html -d example.com -e <envId>
# Purge multiple URLs
tcb domains cache purge https://example.com/a.js https://example.com/b.css -d example.com -e <envId>
# Purge a directory (EO only)
tcb domains cache purge https://example.com/static/ -d example.com -e <envId> -t prefix
# Purge an entire domain (EO only)
tcb domains cache purge https://example.com -d example.com -e <envId> -t host
# Explicitly specify the cache type and wait for completion
tcb domains cache purge https://example.com/index.html -d example.com -e <envId> -c eo --wait
Command parameters:
| Parameter | Description | Required |
|---|---|---|
<targets...> | List of purge targets, up to 20 at a time, each up to 2048 characters | Yes |
-d, --domain <domain> | HTTP service domain | Yes |
-t, --type <type> | Purge granularity: url (default) / prefix (directory) / host (domain). Targets ending with / are automatically recognized as prefix | No |
-c, --cache-type <cacheType> | Cache type: cdn / eo. Auto-detected from the domain access type by default, usually no need to specify | No |
-w, --wait | Wait for the purge to complete before returning (suitable for CI/CD) | No |
Caution
- The domain must be connected to CDN or EdgeOne (EO) before purging its cache
- CDN domains only support URL-granularity purge; directory (prefix) and domain (host) purge are EO-only capabilities
- URL / directory targets must include the
http://orhttps://protocol prefix
Query purge tasks
# Query the progress of a single task
tcb domains cache task <taskId> -d example.com -e <envId>
# List the purge history of the domain for the past 7 days
tcb domains cache task -d example.com -e <envId>
# Filter by purge granularity
tcb domains cache task -d example.com -e <envId> -t prefix
Command parameters:
| Parameter | Description | Required |
|---|---|---|
[taskId] | Task ID returned by the purge task; when provided, query the progress of a single task, otherwise list the history | No |
-d, --domain <domain> | HTTP service domain | Yes |
-t, --type <type> | Filter by purge granularity: url / prefix / host | No |
-c, --cache-type <cacheType> | Cache type: cdn / eo | No |
--limit <limit> | Page size, default 20, maximum 1000 | No |
--offset <offset> | Pagination offset, default 0 | No |
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 edit <domain> | Update custom domain configuration |
tcb domains rm <domain> | Unbind custom domain |
tcb domains cache purge <targets...> -d <domain> | Submit a cache purge task |
tcb domains cache task [taskId] -d <domain> | Query cache purge tasks |
domains ls/add/edit/rmsupport operating on Platform Edition resource pools via--platform-id <platformId>(v3.8.3+).