(aws-apigatewayv2): Add support for ipAddressType in DomainName

[schabe77]

Describe the feature

API Gateway now supports ipAddressType DUAL_STACK.

https://aws.amazon.com/blogs/aws/amazon-api-gateway-now-supports-dual-stack-ipv4-and-ipv6-endpoints/

CDK should fully support Dualstack ApiGateway endpoints.

With the current CDK (2.195.0) it's not possible to fully set up a DualStack-HttpApi-Gateway. The option is already available for software.amazon.awscdk.services.apigatewayv2.HttpApi, but it's not possible to set the ipAddressType for the software.amazon.awscdk.services.apigatewayv2.DomainName even though software.amazon.awscdk.services.apigatewayv2.CfnDomainName.DomainNameConfigurationPropertysupports a IpAddressType-parameter.

When deploying it with a DUAL_STACK ipAddressType for the HttpApi, the "IP address type" at "API details" for the created API is set to Dualstack, but the "Endpoint configuration > IP address type" at AWS console's "API Gateway > Custom domain names" isn't set. Even if I set an AAAA-Record, the IPv6 address doesn't get resolved.

Use Case

Create or add IPv6 support for API Gateway

Proposed Solution

const dn = new apigwv2.DomainName(this, 'DN', {
  domainName: domainName,
  certificate: acm.Certificate.fromCertificateArn(this, 'cert', certArn),
  ipAddressType: apigwv2.IpAddressType.DUAL_STACK,
});

Other Information

No response

Acknowledgements

• I may be able to implement this feature request
• This feature might incur a breaking change

AWS CDK Library version (aws-cdk-lib)

2.195.0

AWS CDK CLI version

2.1014.0 (build e4c6a17)

Environment details (OS name and version, etc.)

macOS Sequoia 15.4.1 (24E263)

[ykethan]

Hey @schabe77, thank you for reaching out. The issue is related to #33998.

From the packages/aws-cdk-lib/aws-apigatewayv2/lib/common/domain-name.ts the current implementation of the DomainName construct doesn't provide a way to set the ipAddressType but is supported on the underlying CloudFormation resource (CfnDomainName.DomainNameConfigurationProperty).

additionally, this is supported on HttpApi

aws-cdk/packages/aws-cdk-lib/aws-apigatewayv2/lib/http/api.ts

Lines 183 to 190 in b1165e4

	/**
	* The IP address types that can invoke the API.
	*
	* @see https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-ip-address-type.html
	*
	* @default undefined - AWS default is IPV4
	*/
	readonly ipAddressType?: IpAddressType;

aws-cdk/packages/aws-cdk-lib/aws-apigatewayv2/lib/common/api.ts

Lines 31 to 41 in b1165e4

	export enum IpAddressType {
	/**
	* IPv4 address type
	*/
	IPV4 = 'ipv4',
	/**
	* IPv4 and IPv6 address type
	*/
	DUAL_STACK = 'dualstack',
	}

Proposed Solution

Off the top, we could update the current implementation to:

1. Add the ipAddressType property to the EndpointOptions interface:

/**
 * properties for creating a domain name endpoint
 */
export interface EndpointOptions {
  /**
   * The ACM certificate for this domain name.
   * Certificate can be both ACM issued or imported.
   */
  readonly certificate: ICertificate;

  /**
   * The user-friendly name of the certificate that will be used by the endpoint for this domain name.
   * @default - No friendly certificate name
   */
  readonly certificateName?: string;

  /**
   * The type of endpoint for this DomainName.
   * @default EndpointType.REGIONAL
   */
  readonly endpointType?: EndpointType;

  /**
   * The Transport Layer Security (TLS) version + cipher suite for this domain name.
   * @default SecurityPolicy.TLS_1_2
   */
  readonly securityPolicy?: SecurityPolicy;

  /**
   * The IP address types that can invoke this domain name.
   * Use 'ipv4' to allow only IPv4 addresses to invoke the domain name, or use 'dualstack'
   * to allow both IPv4 and IPv6 addresses to invoke the domain name.
   * @default undefined - API Gateway default is 'ipv4'
   */
  readonly ipAddressType?: IpAddressType;

  /**
   * A public certificate issued by ACM to validate that you own a custom domain. This parameter is required
   * only when you configure mutual TLS authentication and you specify an ACM imported or private CA certificate
   * for `certificate`. The ownership certificate validates that you have permissions to use the domain name.
   * @default - only required when configuring mTLS
   */
  readonly ownershipCertificate?: ICertificate;
}

2. Then update the addEndpoint method in the DomainName class to use this property:

@MethodMetadata()
public addEndpoint(options: EndpointOptions): void {
  const domainNameConfig: CfnDomainName.DomainNameConfigurationProperty = {
    certificateArn: options.certificate.certificateArn,
    certificateName: options.certificateName,
    endpointType: options.endpointType ? options.endpointType?.toString() : 'REGIONAL',
    ownershipVerificationCertificateArn: options.ownershipCertificate?.certificateArn,
    securityPolicy: options.securityPolicy?.toString(),
    ipAddressType: options.ipAddressType,
  };

  this.validateEndpointType(domainNameConfig.endpointType);
  this.domainNameConfigurations.push(domainNameConfig);
}

With these changes, users will be able to create a dual-stack domain name with code like:

const dn = new apigwv2.DomainName(this, 'DN', {
  domainName: domainName,
  certificate: acm.Certificate.fromCertificateArn(this, 'cert', certArn),
  ipAddressType: apigwv2.IpAddressType.DUAL_STACK,
});

Workaround: #33998 (comment)

const cfnDomainName = domainName.node.defaultChild as CfnDomainName;
cfnDomainName.addPropertyOverride(
  "DomainNameConfigurations.0.IpAddressType",
  IpAddressType.DUAL_STACK,
);

We welcome new PR contribution on this repository. Please refer to the Contributing Guidelines for information on how to contribute.

Marking this as feature request P2

[ykethan]

It appear a PR #34111 was merged 2 days ago which should add this functionality. This should be available in the upcoming releases.

[github-actions]

Comments on closed issues and PRs are hard for our team to see.
If you need help, please open a new issue that references this one.