CloudFront in aws-cn: path off CloudFrontWebDistribution before removal, vs Distribution + legacy ForwardedValues

[sivakova]

Hello CDK team,

We run CloudFront in AWS China (aws-cn). Today we still use the L2 CloudFrontWebDistribution construct because China does not support the newer cache / origin policy model the way commercial regions do, and ForwardedValues remains the practical way to express forwarding there.

We are now getting deprecation notices for CloudFrontWebDistribution, with messaging that it will be removed in a future major release. That puts us in an awkward spot: the deprecated API is still the one that maps most naturally to legacy ForwardedValues, while the recommended Distribution path is built around cache policies and origin request policies, which are unsupported in China (see e.g. #13584, #31033).

Questions:
What is the intended direction for China before CloudFrontWebDistribution is removed? Is first-class support for legacy ForwardedValues (or an equivalent) on Distribution on the roadmap, or should we plan on documented escape hatches long term?

What do you recommend we do between now and the major release that drops CloudFrontWebDistribution: migrate early to Distribution and maintain China-specific overrides (e.g. L1 patches for ForwardedValues), stay on CloudFrontWebDistribution until replacement is clearer, or something else?

Thank you.

[yudin-s]

For aws-cn I would be conservative with this migration.

The modern Distribution L2 is built around policy objects (CachePolicy, OriginRequestPolicy, ResponseHeadersPolicy) rather than the legacy ForwardedValues shape. That is the right direction in commercial regions, but China partitions can lag or have different CloudFront feature availability.

If you must preserve legacy ForwardedValues behavior in aws-cn, I would consider one of these paths:

1. Keep CloudFrontWebDistribution only for the China deployment path and wrap it in your own construct.
2. Use CfnDistribution for that specific distribution so you can synthesize the exact legacy CloudFormation shape.
3. Use Distribution only where the equivalent policy-based config is supported and tested.

I would not do a single blind migration across commercial and China regions. Create an internal construct like:

new AppDistribution(this, 'Distribution', {
  partition: Stack.of(this).partition,
  ...
})

and let it choose the implementation per partition. Then compare the synthesized template and test in aws-cn before removing the legacy path.

So my answer is: the deprecation is real, but for aws-cn compatibility, a small L1/legacy wrapper is a reasonable bridge until the service feature set catches up.

[DYNOSuprovo]

If you decide to migrate to the modern Distribution construct while targeting aws-cn (where legacy ForwardedValues is required and modern Cache/Origin Request Policy IDs are rejected), you don't need to stay locked to CloudFrontWebDistribution.

You can use the modern Distribution L2 construct and apply an L1 CloudFormation property override to synthesize the exact legacy forwarding configuration:

import * as cdk from 'aws-cdk-lib';
import * as cloudfront from 'aws-cdk-lib/aws-cloudfront';
import * as origins from 'aws-cdk-lib/aws-cloudfront-origins';
import { Construct } from 'constructs';

export class ChinaCloudFrontStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const isChina = this.partition === 'aws-cn';

    const distribution = new cloudfront.Distribution(this, 'AppDistribution', {
      defaultBehavior: {
        origin: new origins.HttpOrigin('origin.example.cn'),
        // In commercial regions, modern cache policies are used.
        // In aws-cn, we override with ForwardedValues below.
      },
    });

    if (isChina) {
      const cfnDist = distribution.node.defaultChild as cloudfront.CfnDistribution;

      // 1. Remove modern policy IDs that CloudFront in aws-cn rejects
      cfnDist.addPropertyDeletionOverride(
        'DistributionConfig.DefaultCacheBehavior.CachePolicyId'
      );
      cfnDist.addPropertyDeletionOverride(
        'DistributionConfig.DefaultCacheBehavior.OriginRequestPolicyId'
      );

      // 2. Re-inject legacy ForwardedValues block
      cfnDist.addPropertyOverride(
        'DistributionConfig.DefaultCacheBehavior.ForwardedValues',
        {
          QueryString: true,
          Cookies: {
            Forward: 'all',
          },
          Headers: ['Authorization', 'Host'],
        }
      );
    }
  }
}

Why this migration path works well:

1. Future-Proof against Deprecation: Your codebase immediately moves off CloudFrontWebDistribution before its removal in future major releases.
2. Deterministic Synthesis: addPropertyOverride and addPropertyDeletionOverride guarantee that the synthesized template produces the valid legacy CloudFormation schema accepted by the aws-cn control plane.
3. Single Construct: You maintain a single Distribution definition across global stacks with a clean conditional branch checking this.partition === 'aws-cn'.