volc-tos-storage-domain

Bind and verify a public custom domain for an existing Volcengine TOS bucket. Use when users mention TOS/object-storage custom domains, storage., bucket public URLs, ICP filing passed but the storage domain still cannot be reached, local ve lacking tos, TOS HTTPS certificate binding, Volcengine DNS records, or checking whether a storage domain is direct TOS versus CDN/DCDN.

Volcengine TOS Storage Domain

Use this workflow to connect an ICP-ready storage domain such as storage.example.com to an existing TOS bucket, issue or find a DV certificate, bind HTTPS, and prove object URLs work.

This is for direct TOS custom-domain mode. If the user wants edge caching, WAF behavior, or CDN logs, treat that as a separate CDN/DCDN setup instead of silently adding CDN.

Required inputs

Collect or infer these before changing cloud state:

• Storage domain, for example storage.example.com
• TOS bucket name, region, and endpoint
• DNS zone owner and Zone ID, usually via ve dns ListZones
• Volcengine organization ID for DV certificate requests
• Whether the desired result is direct TOS or CDN/DCDN

Workflow

1. Read existing state first: CDN/DCDN, DNS records, bucket info, bucket ACL, and current TOS custom-domain rules.
2. If ve tos is unavailable, use @volcengine/tos-sdk for TOS APIs. Use ve for DNS, CDN/DCDN, and certificate-service APIs.
3. Bind the custom domain to the bucket before relying on the CNAME; TOS uses this Host binding to accept the custom domain.
4. Add the DNS CNAME from the storage host to the bucket endpoint returned by TOS.
5. Apply or locate a DV certificate, confirm _dnsauth.<host> TXT validation, and poll until the certificate is Issued.
6. Bind the cert to the TOS custom-domain rule with Protocol: "tos" and verify CertStatus: "CertBound".
7. Prove the result with dig, curl -I, openssl s_client, and at least one real object URL.

Read references/tos-custom-domain-runbook.md for the exact commands, SDK calls, OpenAPI fallback, validation checks, and landmines.

First response for unreachable ICP-ready domains

When the user says an ICP-ready storage.<domain> host still cannot be reached, do not jump straight to DNS writes. First outline these read-only checks:

• ve cdn ListCdnDomains and ve dcdn ListDomainConfig to decide whether CDN/DCDN is involved.
• ve dns ListZones, ve dns ListRecords, and authoritative dig to confirm the current CNAME.
• TOS SDK reads with @volcengine/tos-sdk, especially getBucketInfo, getBucketAcl, and getBucketCustomDomain.
• curl -I and openssl s_client to separate HTTP reachability from HTTPS certificate binding.

After discovery, propose writes in order: putBucketCustomDomain, ve dns CreateRecord, QuickApplyCertificate, CertificateGetDcvParam, _dnsauth.<host> TXT, CertificateGetInstanceList, then TOS cert binding with Protocol: "tos".

When the user asks whether CDN is required, answer directly: direct TOS custom-domain mode is valid for public object URLs, and CDN/DCDN is optional and separate. Only recommend CDN/DCDN when the user asks for edge caching, acceleration, logs, WAF behavior, or bandwidth optimization.

When the user says local ve has no tos namespace, be explicit:

• Use @volcengine/tos-sdk / TosClient for getBucketCustomDomain and putBucketCustomDomain.
• Keep using ve dns CreateRecord for DNS and ve certificateservice QuickApplyCertificate plus CertificateGetInstanceList for certificate lifecycle.
• If ve cannot call CertificateGetDcvParam, use OpenAPI version 2021-06-01 with GET query instance_id to fetch DNS validation parameters.
• Bind the certificate back to the TOS custom-domain rule with Protocol: "tos" and CertId; do not use http or https as the TOS Protocol.

Behavior rules

• Do not guess cloud state. Inspect first, then write.
• Do not churn DNS TXT records during certificate validation; propagation delays can make retries slower.
• Do not treat ICP approval as sufficient. ICP only removes the filing blocker; TOS binding, DNS, and HTTPS still need to be configured.
• Do not assume CDN exists. Direct TOS custom-domain mode is valid and should show zero CDN/DCDN domains.
• Never print or persist AK/SK, private keys, certificate private keys, or one-off validation secrets in user-facing docs.