ARNs and Endpoints in AWS China

Posted on 4 March 2021 by Alberto Roura.

aws chinaarnendpointsaws regionscloud architecture

AWS China presents unique considerations for developers and architects working with Amazon Resource Names (ARNs) and service endpoints. Unlike the global AWS regions, AWS China operates under different regulatory and operational requirements that affect how resources are identified and accessed. Understanding these differences is crucial for building applications that work seamlessly across AWS regions, including China.

Understanding AWS China Regions

AWS China consists of two separate regions:

cn-north-1: Beijing region (operated by Sinnet)
cn-northwest-1: Ningxia region (operated by NWCD)

These regions are isolated from the global AWS infrastructure and operate under different compliance and regulatory frameworks.

Amazon Resource Names (ARNs) in AWS China

ARN Structure

ARNs follow the standard AWS format but with China-specific partitions:

arn:partition:service:region:account-id:resource

Partition Differences

Global AWS regions: arn:aws:service:region:account-id:resource
AWS China regions: arn:aws-cn:service:region:account-id:resource

The key difference is the partition identifier:

aws for global regions
aws-cn for China regions

ARN Examples

S3 Bucket in Global AWS:

arn:aws:s3:::my-bucket

S3 Bucket in AWS China:

arn:aws-cn:s3:::my-bucket

EC2 Instance in Global AWS:

arn:aws:ec2:us-east-1:123456789012:instance/i-1234567890abcdef0

EC2 Instance in AWS China:

arn:aws-cn:ec2:cn-north-1:123456789012:instance/i-1234567890abcdef0

IAM Role in Global AWS:

arn:aws:iam::123456789012:role/MyRole

IAM Role in AWS China:

arn:aws-cn:iam::123456789012:role/MyRole

Service Endpoints in AWS China

Regional Endpoints

AWS China uses different endpoint patterns:

Global AWS Pattern:

service.region.amazonaws.com

AWS China Pattern:

service.region.amazonaws.com.cn

Common Endpoints

EC2 Endpoints:

Global: ec2.us-east-1.amazonaws.com
China: ec2.cn-north-1.amazonaws.com.cn

S3 Endpoints:

Global: s3.us-east-1.amazonaws.com
China: s3.cn-north-1.amazonaws.com.cn

CloudFormation:

Global: cloudformation.us-east-1.amazonaws.com
China: cloudformation.cn-north-1.amazonaws.com.cn

IAM:

Global: iam.amazonaws.com (global service)
China: iam.cn-north-1.amazonaws.com.cn

Special Considerations

Global Services in China: Some AWS services have different endpoint patterns in China:

CloudFront: cloudfront.amazonaws.com.cn
Route 53: route53.amazonaws.com.cn
IAM: Uses regional endpoints in China (not global)
CloudWatch: cloudwatch.cn-north-1.amazonaws.com.cn

SDK and CLI Configuration

AWS CLI Configuration for China

# Configure AWS CLI for China regions
aws configure --profile china
AWS Access Key ID: your-access-key
AWS Secret Access Key: your-secret-key
Default region name: cn-north-1
Default output format: json

# Use the profile
aws s3 ls --profile china

SDK Configuration

# Python boto3 configuration for China
import boto3

# For China regions
client = boto3.client(
    's3',
    region_name='cn-north-1',
    aws_access_key_id='your-key',
    aws_secret_access_key='your-secret'
)

# The SDK automatically uses China endpoints

Environment Variables

# Set environment variables for China
export AWS_DEFAULT_REGION=cn-north-1
export AWS_REGION=cn-north-1

Cross-Region Considerations

ARN Compatibility

ARNs from China regions cannot be used in global regions and vice versa. This affects:

IAM policies referencing resources across regions
CloudFormation templates with cross-region dependencies
Resource sharing between global and China accounts

Data Transfer

No direct connectivity between China and global regions
Separate accounts required for China and global operations
Data export restrictions may apply for certain data types

Best Practices for AWS China Development

1. Environment Separation

# Use environment-specific configurations
import os

if os.getenv('AWS_REGION', '').startswith('cn-'):
    # China region configuration
    partition = 'aws-cn'
    endpoint_url = f"https://s3.{os.getenv('AWS_REGION')}.amazonaws.com.cn"
else:
    # Global region configuration
    partition = 'aws'
    endpoint_url = None

2. ARN Construction

def build_arn(partition, service, region, account_id, resource):
    """Build ARN with correct partition"""
    return f"arn:{partition}:{service}:{region}:{account_id}:{resource}"

# For China
china_arn = build_arn('aws-cn', 's3', 'cn-north-1', '123456789012', 'bucket/my-bucket')

# For Global
global_arn = build_arn('aws', 's3', 'us-east-1', '123456789012', 'bucket/my-bucket')

3. Configuration Management

# Use configuration files for different environments
environments:
  global:
    partition: aws
    region: us-east-1
    endpoints:
      s3: s3.amazonaws.com

  china:
    partition: aws-cn
    region: cn-north-1
    endpoints:
      s3: s3.amazonaws.com.cn

Common Pitfalls and Solutions

1. Hardcoded ARNs

Problem: Using hardcoded arn:aws: prefixes that don’t work in China

# This won't work in China
policy = {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::my-bucket/*"  # Wrong for China
        }
    ]
}

Solution: Use dynamic ARN construction

def create_s3_policy(bucket_name, partition='aws'):
    return {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Action": "s3:GetObject",
                "Resource": f"arn:{partition}:s3:::{bucket_name}/*"
            }
        ]
    }

# Use appropriate partition
china_policy = create_s3_policy('my-bucket', 'aws-cn')

2. Endpoint Confusion

Problem: Using global endpoints in China or vice versa

# This will fail in China
s3_client = boto3.client('s3', region_name='cn-north-1')
# SDK will try to use global endpoints

Solution: Configure SDK properly

# Correct configuration for China
s3_client = boto3.client(
    's3',
    region_name='cn-north-1',
    endpoint_url='https://s3.cn-north-1.amazonaws.com.cn'
)

3. Account Separation Issues

Problem: Assuming resources can be shared between China and global accounts

Reality: China regions require separate AWS accounts
Impact: Cross-region resource references don’t work

Solution: Design for account separation

# Use different accounts and regions
accounts = {
    'global': {
        'account_id': '123456789012',
        'regions': ['us-east-1', 'eu-west-1']
    },
    'china': {
        'account_id': '987654321098',  # Different account
        'regions': ['cn-north-1', 'cn-northwest-1']
    }
}

Testing and Validation

Local Testing

# Use LocalStack or similar for testing
docker run -d -p 4566:4566 localstack/localstack

# Configure AWS CLI to use LocalStack
aws configure --profile localstack
AWS Access Key ID: test
AWS Secret Access Key: test
Default region name: us-east-1
Default output format: json

aws --endpoint-url=http://localhost:4566 s3 ls --profile localstack

China-Specific Testing

# Test with actual China credentials (VPN required)
aws s3 ls --profile china --region cn-north-1
aws ec2 describe-instances --profile china --region cn-north-1

Migration Strategies

From Global to China

Update ARN partitions in all policies and templates
Change endpoint URLs in application configurations
Test thoroughly with China endpoints
Update DNS and routing for China-specific domains

Multi-Region Applications

class AWSConfig:
    def __init__(self, region):
        self.region = region
        self.is_china = region.startswith('cn-')
        self.partition = 'aws-cn' if self.is_china else 'aws'
        self.endpoint_suffix = 'amazonaws.com.cn' if self.is_china else 'amazonaws.com'

    def get_endpoint(self, service):
        if self.is_china:
            return f"https://{service}.{self.region}.{self.endpoint_suffix}"
        else:
            return f"https://{service}.{self.region}.{self.endpoint_suffix}"

# Usage
config = AWSConfig('cn-north-1')
s3_endpoint = config.get_endpoint('s3')  # Returns China-specific endpoint

Compliance and Security

Data Residency

China regions: Data stays within China borders
Compliance: Meets local regulatory requirements
Encryption: Same encryption standards as global regions

Access Control

Separate accounts: China operations require separate AWS accounts
IAM policies: Must use aws-cn partition in ARNs
MFA requirements: Same security standards apply

Conclusion

Working with AWS China requires careful attention to ARN formats and service endpoints. The aws-cn partition and .com.cn domain suffix are the key differentiators that developers must account for.

By understanding these differences and implementing proper configuration management, you can build applications that work seamlessly across global and China AWS regions. The separation between China and global regions provides compliance benefits but requires careful planning for multi-region architectures.

Remember: when in doubt, test with actual China credentials and endpoints. The differences are significant enough that local development and testing can miss critical issues that only appear in the China environment.

Guztia Consulting