I feel like the README here should call out the same warning from the fromDns documentation about needing to manually add the DNS records before CloudFormation can succeed. Might even be worth having the Route53 example first (as the thing people are most likely to copy/paste and use), and then call out the outside-DNS example with the warning about the need for manual intervention.

Counter-argument -- this custom resource-based approach allows for cross-region cert creation, which the native CloudFormation support doesn't allow (AFAIK). It might be worth not deprecating it, and noting this use case in the README. What do you think?

Good point. For information, it's in the CF roadmap aws-cloudformation/cloudformation-coverage-roadmap#523.

This also solves my question here #8552 (comment)

I'm trying to think of a better way to do this interface. As-is, it's not clear how to use it -- if I need to provide the hostedZones map, do I also need to provide the hostedZone? If so, does it matter which is the "main" zone and which appears in the map? One other thought -- domain names to hosted zones are N:1; you may have 10 domain names with two top-level hosted zones; flipping the map around may be slightly more usable for some customers (I don't have the data to back that up off-hand though).

Maybe breaking this into two would alleviate some of the problems:

public static fromDns(hostedZone?: route53.IHostedZone) {...}
public static fromDnsMultiZone(hostedZoneMap: { [domainName: string]: route53.IHostedZone) {...}

Open to better naming and disagreements.

Should we do:

export class CrossRegionDnsValidatedCertificate extends DnsValidatedCertificate {
  constructor(scope: cdk.Construct, id: string, props: DnsValidatedCertificateProps) {
    super(scope, id, props);
  }
}

to get a better naming?

I don't think it's worth it, especially considering cross-region support is on the roadmap for CloudFormation. Let's just leave it as-is and deprecate it once we can.

Can you un-delete this file, given we are not (yet) deprecating the DnsValidatedCertificate?