chore(ec2): NatInstanceProviderV2 security group example (#29769)

### Issue # (if applicable)

Closes #27527

### Reason for this change

The current `NatInstanceProviderV2.securityGroup` property is unusable, given the dependency loop between the construct props (`NatInstanceProviderV2` > `VPC` > `SecurityGroup` > `NatInstanceProviderV2`).
When creating the integration for #29729, adding a getter for the instances generated by the provider to update the instance role was required to test the `userData` overload. This solution also allows to bypass the circular dependency describe above, given that both the VPC and the instances are generated once the VPC is created with the `natGatewayProvider`.

### Description of changes

* Deprecate `NatInstanceProviderV2.securityGroup`
  * Add `@example` tag to demo `NatInstanceProviderV2.gatewayInstances`
* Update `README` to demo setting the security group
* Update integ to test the demo

### Description of how you validated changes

Updated integration test

### Checklist
- [x] My code adheres to the [CONTRIBUTING GUIDE](https:/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https:/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md)

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

packages/@aws-cdk-testing/framework-integ/test/aws-ec2/test/integ.nat-instances-v2-custom.js.snapshot/aws-cdk-vpc-nat-instance-v2-custom.template.json

@@ -350,6 +350,12 @@
  "MyVpcNatSecurityGroupAA76397E",
  "GroupId"
  ]
+ },
+ {
+ "Fn::GetAtt": [
+ "SecurityGroupDD263621",
+ "GroupId"
+ ]
  }
  ],
  "SourceDestCheck": false,
@@ -566,6 +572,12 @@
  "MyVpcNatSecurityGroupAA76397E",
  "GroupId"
  ]
+ },
+ {
+ "Fn::GetAtt": [
+ "SecurityGroupDD263621",
+ "GroupId"
+ ]
  }
  ],
  "SourceDestCheck": false,
@@ -763,9 +775,11 @@
  "GroupDescription": "Security Group for NAT instances",
  "SecurityGroupEgress": [
  {
- "CidrIp": "0.0.0.0/0",
- "Description": "Allow all outbound traffic by default",
- "IpProtocol": "-1"
+ "CidrIp": "255.255.255.255/32",
+ "Description": "Disallow all traffic",
+ "FromPort": 252,
+ "IpProtocol": "icmp",
+ "ToPort": 86
  }
  ],
  "Tags": [
@@ -779,6 +793,24 @@
  }
  }
  },
+ "SecurityGroupDD263621": {
+ "Type": "AWS::EC2::SecurityGroup",
+ "Properties": {
+ "GroupDescription": "aws-cdk-vpc-nat-instance-v2-custom/SecurityGroup",
+ "SecurityGroupEgress": [
+ {
+ "CidrIp": "0.0.0.0/0",
+ "Description": "Allow egress to S3",
+ "FromPort": 443,
+ "IpProtocol": "tcp",
+ "ToPort": 443
+ }
+ ],
+ "VpcId": {
+ "Ref": "MyVpcF9F0CA6F"
+ }
+ }
+ },
  "ALBAEE750D2": {
  "Type": "AWS::ElasticLoadBalancingV2::LoadBalancer",
  "Properties": {

packages/@aws-cdk-testing/framework-integ/test/aws-ec2/test/integ.nat-instances-v2-custom.ts

@@ -32,18 +32,21 @@ class NatInstanceStack extends cdk.Stack {
  const natGatewayProvider = ec2.NatProvider.instanceV2({
  instanceType: new ec2.InstanceType('t3.small'),
  creditSpecification: ec2.CpuCredits.UNLIMITED,
- defaultAllowedTraffic: ec2.NatTrafficDirection.OUTBOUND_ONLY,
+ defaultAllowedTraffic: ec2.NatTrafficDirection.NONE,
  keyPair,
  userData,
  });
 
- const vpc = new ec2.Vpc(this, 'MyVpc', {
- natGatewayProvider,
- natGateways: 2,
- });
+ const vpc = new ec2.Vpc(this, 'MyVpc', { natGatewayProvider });
 
+ const securityGroup = new ec2.SecurityGroup(this, 'SecurityGroup', {
+ vpc,
+ allowAllOutbound: false,
+ });
+ securityGroup.addEgressRule(ec2.Peer.anyIpv4(), ec2.Port.tcp(443), 'Allow egress to S3');
  for (const gateway of natGatewayProvider.gatewayInstances) {
  bucket.grantWrite(gateway);
+ gateway.addSecurityGroup(securityGroup);
  }
 
  Array.isArray(vpc);
@@ -70,7 +73,6 @@ const stack = new NatInstanceStack(app, 'aws-cdk-vpc-nat-instance-v2-custom');
 
 const integ = new IntegTest(app, 'nat-instance-v2-custom-integ-test', {
  testCases: [stack],
-
 });
 
 integ.assertions.httpApiCall(stack.apiUrl, {})

packages/aws-cdk-lib/aws-ec2/README.md

@@ -218,7 +218,8 @@ new ec2.Vpc(this, 'TheVPC', {
 provider.connections.allowFrom(ec2.Peer.ipv4('1.2.3.4/8'), ec2.Port.tcp(80));
 ```
 
-You can also customize the characteristics of your NAT instances, as well as their initialization scripts:
+You can also customize the characteristics of your NAT instances, including their security group,
+as well as their initialization scripts:
 
 ```ts
 declare const bucket: s3.Bucket;
@@ -233,15 +234,19 @@ userData.addCommands(
 const provider = ec2.NatProvider.instanceV2({
  instanceType: new ec2.InstanceType('t3.small'),
  creditSpecification: ec2.CpuCredits.UNLIMITED,
+ defaultAllowedTraffic: ec2.NatTrafficDirection.NONE,
 });
 
-new ec2.Vpc(this, 'TheVPC', {
+const vpc = new ec2.Vpc(this, 'TheVPC', {
  natGatewayProvider: provider,
  natGateways: 2,
 });
 
+const securityGroup = new ec2.SecurityGroup(this, 'SecurityGroup', { vpc });
+ securityGroup.addEgressRule(ec2.Peer.anyIpv4(), ec2.Port.tcp(443));
 for (const gateway of provider.gatewayInstances) {
  bucket.grantWrite(gateway);
+ gateway.addSecurityGroup(securityGroup);
 }
 ```