CDK GoLang Library – Upcoming Backward Incompatible Change

[gasolima]

AWS CDK Library will be making a change that requires code changes for Golang users on October 15, 2025.

If you are not using AWS CDK library in GoLang, you can stop reading.

What is the change?

The CDK Team is working on an initiative to enhance the interoperability of L1 and L2 constructs. L1 construct properties that previously accepted only strings (such as resource names or ARNs) will now also accept resource objects. For example:

role := NewCfnRole(...)

NewCfnFunction(stack, jsii.String("MyFunction"), &CfnFunctionProps{
  // Before
  Role: role.RoleArn,
  
  // After
  Role: role,
})

What is the impact to Go users?

To achieve the ability to pass in different types, we are turning the construct properties that represent references into type unions, which allow passing in either a string or the resource type. In Go, the effect of this change will be that the type will go from *string to any (alternatively known as interface {}), which allows passing in multiple types. In cases where the input property represents a list of references, the type will change from *[]*string to *[]any.

Because of the Go type system, *[]*string is not assignable to *[]any, and so code changes are necessary to convert the old type to the new type. We are providing helper functions (jsii.AnyStrings(), jsii.AnyNumbers(), jsii.AnySlice()) to make this conversion easier.

Example

As an example: today, CfnUserProps.ManagedPolicyArns accepts *[]*string.

After the update, it will accept *[]any to allow both strings and L1/L2 references. You need to change your code to convert the old type into the new type.

Option 1: Migrating from jsii.Strings() or jsii.Numbers()

If you are already using jsii.Strings() or jsii.Numbers(), there are two new helper functions you can use instead to assign to a *[]any: jsii.AnyStrings() and jsii.AnyNumbers().

&CfnUserProps{
  // Before
  ManagedPolicyArns: jsii.Strings("arn:aws:s3:::bucket1", "arn:aws:s3:::bucket2"),

  // After
  ManagedPolicyArns: jsii.AnyStrings("arn:aws:s3:::bucket1", "arn:aws:s3:::bucket2"),
}

Option 2: Migrating from pre-existing string slices coming from elsewhere

For a *[]*string slice coming from any other source, you can call jsii.AnySlice() to convert it to *[]any.

func Arns() *[]*string {
    a := "arn:aws:s3:::bucket1"
    b := "arn:aws:s3:::bucket2"
    return &[]*string{&a, &b}
}

&CfnUserProps{
  // Before
  ManagedPolicyArns: Arns(),
  
  // After
  ManagedPolicyArns: jsii.AnySlice(Arns()),  
}

Where is this change coming from?

This effect comes from the representation of union types in Go; any time a single type changes into a union type, its type will turn into any, and if the type happens to be inside a slice there will be a type mismatch. During the design of the Go language bindings for CDK we carefully evaluated different approaches, and we did not see a different way of representing type unions in Go that would not have this unfortunate side effect.

For this reason, traditionally CDK has eschewed the use of union types. After weighing the pros and cons of various approaches, we have ultimately decided that the better ergonomics of using union types for the new object references in most languages and most call sites are worth the downsides in Go and a few call sites.

This change will be rolled out in a single release to minimize its impact on your codebase.

How do I know my CDK Go project is affected?

Only L1 construct properties that accept arrays of relationships are affected. Below is a list of impacted resources and properties.

You can recognize this situation if you see the following error from the Go compiler:

Cannot use 'jsii.Strings("some string", "some other string")' (type *[]*string) as the type *[]interface{}

List of affected L1 constructs

Service	Resource Class	Property
ApiGateway	CfnAuthorizer	ProviderARNs
ApiGateway	CfnVpcLink	TargetArns
ApiGatewayV2	CfnVpcLink	SubnetIds; SecurityGroupIds
AppRunner	CfnVpcConnector	SecurityGroups
AppSync	CfnResolver	PipelineConfig.Functions
AutoScaling	CfnLaunchConfiguration	SecurityGroups
AutoScaling	CfnAutoScalingGroup	LoadBalancerNames; TargetGroupARNs; VPCZoneIdentifier
Backup	CfnBackupSelection	BackupSelection.Resources
Batch	CfnComputeEnvironment	ComputeResources.SecurityGroupIds; ComputeResources.Subnets
CE	CfnAnomalySubscription	MonitorArnList
Chatbot	CfnSlackChannelConfiguration	SnsTopicArns
CloudFront	CfnDistribution	DistributionConfig.CacheBehaviors.TrustedKeyGroups; DistributionConfig.DefaultCacheBehaviors.TrustedKeyGroups
CloudFront	CfnKeyGroup	KeyGroupConfig.Items
CloudTrail	CfnTrail	EventSelectors.DataResources.Values
CloudWatch	CfnAlarm	OKActions; AlarmActions; InsufficientDataActions
CloudWatch	CfnCompositeAlarm	OKActions; AlarmActions
CodeArtifact	CfnRepository	Upstreams
CodeGuruProfiler	CfnProfilingGroup	AgentPermissions.Principals
Cognito	CfnIdentityPool	OpenIdConnectProviderARNs
DataSync	CfnLocationNFS	OnPremConfig.AgentArns
DirectoryService	CfnSimpleAD	VpcSettings.SubnetIds
DocDBElastic	CfnCluster	VpcSecurityGroupIds
EC2	CfnLaunchTemplate	LaunchTemplateData.NetworkInterfaces.Groups; LaunchTemplateData.SecurityGroupIds
EC2	CfnNetworkInterface	GroupSet
EC2	CfnVPCEndpoint	RouteTableIds; SecurityGroupIds; SubnetIds
EC2	CfnInstance	NetworkInterfaces.GroupSet; SecurityGroupIds
EC2	CfnVPCEndpointService	NetworkLoadBalancerArns
EC2	CfnTransitGatewayAttachment	SubnetIds
ECS	CfnCluster	CapacityProviders
ECS	CfnClusterCapacityProviderAssociations	CapacityProviders
ECS	CfnService	NetworkConfiguration.AwsvpcConfiguration.SecurityGroups; NetworkConfiguration.AwsvpcConfiguration.Subnets; DeploymentConfiguration.Alarms.AlarmNames
EFS	CfnMountTarget	SecurityGroups
EKS	CfnNodegroup	Subnets
EKS	CfnCluster	ResourcesVpcConfig.SecurityGroupIds; ResourcesVpcConfig.SubnetIds
ElastiCache	CfnSubnetGroup	SubnetIds
ElastiCache	CfnUserGroup	UserIds
ElastiCache	CfnServerlessCache	SecurityGroupIds; SubnetIds
ElasticLoadBalancing	CfnLoadBalancer	SecurityGroups; Instances; Subnets
ElasticLoadBalancingV2	CfnLoadBalancer	SecurityGroups; Subnets
EMR	CfnStudio	SubnetIds
Events	CfnRule	(under Targets) Values; SecurityGroups; Subnets
IAM	CfnRole	ManagedPolicyArns
IAM	CfnManagedPolicy	Groups; Roles; Users
IAM	CfnInstanceProfile	Roles
IAM	CfnUser	ManagedPolicyArns; Groups
IAM	CfnGroup	ManagedPolicyArns
IVSChat	CfnRoom	LoggingConfigurationIdentifiers
KinesisFirehose	CfnDeliveryStream	(in a number of properties) SubnetIds; SecurityGroupIds
Lambda	CfnCodeSigningConfig	AllowedPublishers.SigningProfileVersionArns
Lambda	CfnFunction	VpcConfig.SecurityGroupIds; VpcConfig.SubnetIds; Layers
Logs	CfnQueryDefinition	LogGroupNames
MemoryDB	CfnCluster	SecurityGroupIds
MemoryDB	CfnSubnetGroup	SubnetIds
MSK	CfnCluster	BrokerNodeGroupInfo.SecurityGroups; BrokerNodeGroupInfo.ClientSubnets; ClientAuthentication.Tls.CertificateAuthorityArnList
MSK	CfnServerlessCluster	VpcConfigs.SecurityGroups; VpcConfigs.SubnetIds
MWAA	CfnEnvironment	NetworkConfiguration.SubnetIds; NetworkConfiguration.SecurityGroupIds
Neptune	CfnDBCluster	VpcSecurityGroupIds
OpenSearchServerless	CfnVpcEndpoint	SecurityGroupIds
OpenSearchService	CfnDomain	VPCOptions.SecurityGroupIds; VPCOptions.SubnetIds
RDS	CfnDBSubnetGroup	SubnetIds
RDS	CfnDBProxyTargetGroup	DBClusterIdentifiers
RDS	CfnEventSubscription	SourceIds
RDS	CfnDBProxy	VpcSecurityGroupIds; VpcSubnetIds
RDS	CfnDBProxyEndpoint	VpcSecurityGroupIds; VpcSubnetIds
RDS	CfnDBCluster	VpcSecurityGroupIds
RDS	CfnDBInstance	VPCSecurityGroups
Redshift	CfnCluster	IamRoles; VpcSecurityGroupIds
Redshift	CfnClusterSubnetGroup	SubnetIds
Redshift	CfnEndpointAccess	VpcSecurityGroupIds
RedshiftServerless	CfnNamespace	IamRoles
RedshiftServerless	CfnWorkgroup	SecurityGroupIds; SubnetIds
RolesAnywhere	CfnProfile	RoleArns
Route53	CfnHealthCheck	HealthCheckConfig.ChildHealthChecks
Route53RecoveryControl	CfnSafetyRule	AssertionRule.AssertedControls
SageMaker	CfnDomain	DefaultUserSettings.SecurityGroups; SubnetIds
SageMaker	CfnUserProfile	UserSettings.SecurityGroups
SSM	CfnAssociation	Values
Synthetics	CfnCanary	VPCConfig.SubnetIds
WAFv2	CfnLoggingConfiguration	LogDestinationConfigs

Running into issues?

Are you encountering a case not covered by the examples above? Please let us know by opening a GitHub issue in the aws/aws-cdk repository.

When creating an issue, please include:

• A description of your use case
• Code snippets that show how you are currently using the affected properties
• Any errors you encounter after the change

This will help us better understand your scenario and provide guidance or possible workarounds.