Use a dedicated CNAME domain to decouple your custom domain's resolution path from the standard OSS endpoint (*.aliyuncs.com). This keeps OSS access available even when the standard endpoint fails to resolve or is blocked.
How it works
The dedicated CNAME domain acts as an intermediate DNS CNAME target between your custom domain and your OSS bucket:
-
Used only for DNS CNAME resolution. The domain itself is not directly accessible.
-
Must be used together with a custom domain.
Domain format
Format: <BucketName>.<Region>.<dedicated-CNAME-domain-suffix>
Examples
|
Region |
Example |
|
Chinese mainland |
|
|
Regions outside the Chinese mainland |
|
Comparison with the standard endpoint
|
Item |
Standard endpoint |
Dedicated CNAME domain |
|
Format |
|
Chinese mainland: |
|
Directly accessible |
Yes |
No (used only as a DNS CNAME target for custom domains) |
Use cases
-
Custom domains that need a stable CNAME resolution target for an OSS bucket.
-
A reliable fallback when the standard endpoint fails to resolve or is blocked.
-
Workloads that use intelligent DNS resolution to optimize access paths.
Choose a configuration method
Two methods are available. Choose the one that fits your architecture:
|
Method |
When to use |
|
Access OSS bucket resources through a custom domain without CDN. |
|
|
Accelerate access to OSS resources through CDN while using the dedicated CNAME domain as the origin for improved stability. |
Prerequisites and limitations
Prerequisites
-
An Alibaba Cloud OSS bucket
-
ICP filing for the custom domain (required only for buckets in Chinese mainland regions)
-
Permission to modify DNS records at your DNS provider
-
Permission to manage bucket domains in the OSS console
Limitations
|
Item |
Description |
|
Domain uniqueness |
A custom domain can be bound to only one bucket. |
|
Binding requirement |
The CNAME takes effect only after the custom domain is bound in the OSS console. |
|
Access method |
The dedicated CNAME domain is not directly accessible and serves only as a CNAME target. |
-
The custom domain must be bound to the target bucket in the OSS console. Configuring a CNAME record without completing the binding may lead to cross-tenant access risks.
-
Use only the dedicated CNAME domain assigned by the system for your bucket. Service guarantees apply only to system-assigned domains. Using an unofficial, guessed, or manually constructed domain is at your own risk; OSS is not responsible for any resulting losses.
Bind a custom domain directly to OSS
Access resources in an OSS bucket through a custom domain, for example static.example.com.
Step 1: Bind the custom domain in the OSS console
-
Go to the Bucket list and click the target bucket name.
-
In the left-side navigation pane, click .
-
Click Map Custom Domain Name.
-
Enter your custom domain (for example,
static.example.com) and confirm the binding.
Step 2: Retrieve the dedicated CNAME domain
After binding, the system assigns a dedicated CNAME domain in the format <BucketName>.<Region>.<dedicated-CNAME-domain-suffix>. To view the assigned domain:
-
Go to the Bucket list and click the target bucket name.
-
In the left-side navigation pane, click Overview.
Step 3: Configure the CNAME record
Log on to your DNS management platform (such as Alibaba Cloud DNS) and add a CNAME record:
|
Record type |
Host record |
Record value |
|
CNAME |
Example: static |
Example: |
Step 4: Verify the configuration
After the DNS record takes effect, verify with the following commands:
# Check that DNS resolution is correct
dig static.example.com CNAME
# Verify that access works
curl -I http://static.example.com/test.txt-
A CNAME record and an A record cannot coexist for the same host record. Delete any conflicting A record first.
-
Bind the custom domain in the OSS console before you configure the CNAME record.
Access OSS through CDN acceleration
Accelerate access to OSS resources through CDN, using the dedicated CNAME domain as the origin for improved stability. For the full CDN acceleration workflow, see Access OSS through CDN acceleration. The steps below cover only the settings specific to this solution.
Step 1: Bind the custom domain in the OSS console
-
Go to the Bucket list and click the target bucket name.
-
In the left-side navigation pane, click .
-
Click Map Custom Domain Name.
-
Enter your custom domain (for example,
static.example.com) and confirm the binding.
Step 2: Configure the CDN origin
In the CDN console, configure the Origin Information and Default Origin Host as follows:
|
Setting |
Description |
|
Origin Information |
Select Origin Domain Name and enter the dedicated CNAME domain, for example |
|
Default Origin Host |
Enter your custom domain (for example, Note
Set Default Origin Host to your custom domain. If this field is left as the standard bucket domain, origin-fetch requests inherit the same blocking risk: when the generic domain is blocked at Layer 7, your service is interrupted. |
-
When the origin is a private bucket, enable Alibaba Cloud OSS Private Bucket Access.
-
When you change Origin Information to the dedicated CNAME domain, keep the origin-fetch Host header unchanged. OSS uses the Host header to identify the target bucket, so access fails if the Host header does not match the bucket.
Step 3: Point the DNS record to the CDN
Point the CNAME record of your custom domain to the acceleration domain assigned by CDN:
|
Record type |
Host record |
Record value |
|
CNAME |
Example: static |
Example: |
Step 4: Verify the configuration
# Check that CDN acceleration is working
curl -I http://static.example.com/test.txt -v
# Confirm that response headers include CDN node info such as Via or X-Cache-
For third-party CDN (non-Alibaba Cloud CDN) that fetches from OSS, also set the origin address to the dedicated CNAME domain.
-
Keep the origin-fetch protocol consistent with the OSS setting (HTTP or HTTPS).
-
For CDN cache policies, set longer cache durations for static assets and no cache for dynamic requests.
Troubleshooting
Access returns 404 or NoSuchBucket after CNAME configuration
Cause: The custom domain is not bound in the OSS console, or is bound to the wrong bucket.
Troubleshooting steps:
-
Log on to the OSS console and confirm that the domain is bound to the target bucket.
-
Check that the CNAME record value exactly matches the dedicated CNAME domain that OSS assigned.
-
Confirm the bucket name and region are correct.
DNS resolution does not take effect
Cause: The DNS record is misconfigured or has not fully propagated.
Troubleshooting steps:
# Check the current resolution result
dig static.example.com +short
# Query a specific DNS server to bypass local cache
dig static.example.com @8.8.8.8Common causes:
-
The CNAME record conflicts with an existing A record.
-
The host record in the DNS configuration is incorrect (for example, the primary domain part was included).
-
The DNS TTL cache has not expired. Wait for the old cache to expire.
Access returns unexpected content
Cause: The custom domain is not bound in the OSS console. The system falls back to path-based resolution and may return content from a different bucket.
Troubleshooting steps:
-
Immediately bind the domain to the correct bucket in the OSS console.
-
After the binding completes, verify that the returned content is correct.
An unbound CNAME may expose users to unexpected third-party content, creating security and reputational risks.
CDN origin fetch fails (403/400)
Cause: The CDN origin-fetch Host header is not configured correctly.
Troubleshooting steps:
-
Confirm that the CDN Default Origin Host is set to the custom domain or the standard bucket domain.
-
Confirm that the origin address and Host header are not confused:
-
Origin Information: the dedicated CNAME domain, used for DNS resolution addressing.
-
Default Origin Host: the custom domain or the standard bucket domain, used for OSS to identify the bucket.
-
FAQ
Why is the dedicated CNAME domain preferred over the standard endpoint?
The dedicated CNAME domain has an independent resolution path that does not depend on the aliyuncs.com primary domain. When the standard endpoint fails to resolve or is blocked, the dedicated CNAME domain continues to resolve, keeping your applications reachable.
Can I still use the standard endpoint after configuring the dedicated CNAME domain?
Yes. The dedicated CNAME domain is an additional access path and does not affect the standard endpoint. You can use both.
Can multiple custom domains point to the same dedicated CNAME domain?
Yes. As long as all custom domains are bound to the same bucket in the OSS console, you can point their CNAME records to that bucket's dedicated CNAME domain.
How do I confirm that the dedicated CNAME domain in use is correct?
Log on to the OSS console, open the Overview page for the target bucket, and check the CNAME domain assigned by the system. The record value in your DNS configuration must exactly match the value shown in the console.
Is there an extra charge for using the dedicated CNAME domain?
No. The dedicated CNAME domain is a built-in capability of OSS and incurs no extra fees. OSS access is billed according to standard pricing.