Alibaba Cloud OSS & CDN: Fix Health Check Failures for Origin Pull from Private Bucket
Quick Fix Summary
TL;DRVerify and correct the CDN domain's origin configuration and OSS bucket permissions.
CDN health checks fail when the CDN edge node cannot successfully pull the configured health check file from the private OSS origin due to authentication, network, or configuration errors.
Diagnosis & Causes
Recovery Steps
Step 1: Verify CDN Domain and Health Check Configuration
Check the CDN domain's origin settings and health check configuration in the Alibaba Cloud Console.
# 1. List your CDN domains via CLI
aliyun cdn DescribeUserDomains --PageSize 50
# 2. Get detailed config for a specific domain (replace YOUR_DOMAIN)
aliyun cdn DescribeCdnDomainConfigs --DomainName YOUR_DOMAIN --FunctionNames "origin,optimize"Step 2: Check OSS Bucket Permissions for CDN Service
Ensure the private OSS bucket has a RAM authorization policy allowing the CDN service role to perform GetObject.
# 1. Check existing RAM policies for the OSS bucket's ACL or RAM roles.
# Use the console for this: OSS Console -> Bucket -> Authorization -> RAM Policy.
# A correct policy should resemble:
# {
# "Statement": [{
# "Effect": "Allow",
# "Action": "oss:GetObject",
# "Principal": "cdn.aliyuncs.com",
# "Resource": "acs:oss:*:*:BUCKET_NAME/*"
# }],
# "Version": "1"
# }Step 3: Manually Test Origin Pull from a CDN Edge Node Perspective
Simulate the CDN health check by attempting to fetch the health check file using the origin URL and required headers.
# Construct the origin URL. Format: https://BUCKET_NAME.oss-REGION.aliyuncs.com/HEALTH_CHECK_PATH
# Use curl with verbose output to diagnose connection, TLS, and HTTP status issues.
curl -v -H "Host: BUCKET_NAME.oss-REGION.aliyuncs.com" \
'https://BUCKET_NAME.oss-REGION.aliyuncs.com/path/to/healthcheck.txt'Step 4: Validate and Correct the Health Check File Path
Ensure the health check file exists at the exact path specified in the CDN configuration and is accessible.
# 1. List files in the OSS bucket via CLI (requires your own credentials)
aliyun oss ls oss://BUCKET_NAME/ --include "healthcheck.*"
# 2. If using a subdirectory, ensure the path is correct in CDN config:
# CDN Origin: BUCKET_NAME.oss-REGION.aliyuncs.com
# Health Check Path: /subdir/healthcheck.htmlStep 5: Review CDN Back-to-Origin Host Header
If a custom back-to-origin Host is configured, ensure it matches what the OSS bucket expects for private access.
# Get the back-to-origin host configuration for your domain.
aliyun cdn DescribeCdnDomainConfigs --DomainName YOUR_DOMAIN --FunctionNames "set_req_host_header"
# The value should typically be the OSS endpoint host: BUCKET_NAME.oss-REGION.aliyuncs.comStep 6: Force Refresh and Monitor Health Status
After making corrections, refresh the CDN configuration and monitor the health check status.
# 1. Refresh the domain configuration
aliyun cdn RefreshObjectCaches --ObjectPath "https://YOUR_CDN_DOMAIN/" --ObjectType "Directory"
# 2. Check domain health status (look for 'online' status)
aliyun cdn DescribeCdnDomainDetail --DomainName YOUR_DOMAINArchitect's Pro Tip
"The most common cause is the RAM policy Principal. Using "*" or a specific RAM role ID is incorrect for service-authorization to OSS. The Principal must be the service name "cdn.aliyuncs.com". Also, health checks fail silently if the file returns a non-2xx/3xx status code (like 403 Forbidden)."
Frequently Asked Questions
My bucket is private but I have a RAM policy. Why do health checks still fail?
Verify the policy's 'Resource' field includes the exact health check file path (e.g., 'acs:oss:*:*:mybucket/health/*'). A policy granting access to 'mybucket/*' may not cover 'mybucket/health/*' if subdirectory permissions are overridden. Also, check for any Deny policies that take precedence.
Can I use a public-read file in my private bucket for health checks?
Yes, this is a valid and simpler workaround. Set the specific health check object's ACL to public-read. The CDN can then fetch it without RAM authorization, while the rest of the bucket remains private. Use: `aliyun oss set-acl oss://bucket/health.txt public-read`.