Merge branch 'main' into pahud/aws-eks-eks-cluster-logging-20779

.github/workflows/auto-approve.yml

@@ -12,6 +12,6 @@ jobs:
     permissions:
       pull-requests: write
     steps:
-    - uses: hmarr/auto-approve-action@v3.2.0
+    - uses: hmarr/auto-approve-action@v3.2.1
       with:
         github-token: "${{ secrets.GITHUB_TOKEN }}"

packages/@aws-cdk/aws-autoscaling/README.md

@@ -25,7 +25,11 @@ declare const vpc: ec2.Vpc;
 new autoscaling.AutoScalingGroup(this, 'ASG', {
   vpc,
   instanceType: ec2.InstanceType.of(ec2.InstanceClass.BURSTABLE2, ec2.InstanceSize.MICRO),
-  machineImage: new ec2.AmazonLinuxImage() // get the latest Amazon Linux image
+
+  // The latest Amazon Linux image of a particular generation
+  machineImage: ec2.MachineImage.latestAmazonLinux({
+    generation: ec2.AmazonLinuxGeneration.AMAZON_LINUX_2,
+  }),
 });
 ```
 
@@ -41,7 +45,9 @@ const mySecurityGroup = new ec2.SecurityGroup(this, 'SecurityGroup', { vpc });
 new autoscaling.AutoScalingGroup(this, 'ASG', {
   vpc,
   instanceType: ec2.InstanceType.of(ec2.InstanceClass.BURSTABLE2, ec2.InstanceSize.MICRO),
-  machineImage: new ec2.AmazonLinuxImage(),
+  machineImage: ec2.MachineImage.latestAmazonLinux({
+    generation: ec2.AmazonLinuxGeneration.AMAZON_LINUX_2,
+  }),
   securityGroup: mySecurityGroup,
 });
 ```
@@ -538,6 +544,40 @@ new autoscaling.AutoScalingGroup(this, 'ASG', {
 });
 ```
 
+## Connecting to your instances using SSM Session Manager
+
+SSM Session Manager makes it possible to connect to your instances from the
+AWS Console, without preparing SSH keys.
+
+To do so, you need to:
+
+* Use an image with [SSM agent](https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent.html) installed
+  and configured. [Many images come with SSM Agent
+  preinstalled](https://docs.aws.amazon.com/systems-manager/latest/userguide/ami-preinstalled-agent.html), otherwise you
+  may need to manually put instructions to [install SSM
+  Agent](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-manual-agent-install.html) into your
+  instance's UserData or use EC2 Init).
+* Create the AutoScalingGroup with `ssmSessionPermissions: true`.
+
+If these conditions are met, you can connect to the instance from the EC2 Console. Example:
+
+```ts
+declare const vpc: ec2.Vpc;
+
+new autoscaling.AutoScalingGroup(this, 'ASG', {
+  vpc,
+  instanceType: ec2.InstanceType.of(ec2.InstanceClass.T3, ec2.InstanceSize.MICRO),
+
+  // Amazon Linux 2 comes with SSM Agent by default
+  machineImage: ec2.MachineImage.latestAmazonLinux({
+    generation: ec2.AmazonLinuxGeneration.AMAZON_LINUX_2,
+  }),
+
+  // Turn on SSM
+  ssmSessionPermissions: true,
+});
+```
+
 ## Configuring Instance Metadata Service (IMDS)
 
 ### Toggling IMDSv1
@@ -596,13 +636,13 @@ autoScalingGroup.addWarmPool({
 
 ### Default Instance Warming
 
-You can use the default instance warmup feature to improve the Amazon CloudWatch metrics used for dynamic scaling. 
-When default instance warmup is not enabled, each instance starts contributing usage data to the aggregated metrics 
-as soon as the instance reaches the InService state. However, if you enable default instance warmup, this lets 
+You can use the default instance warmup feature to improve the Amazon CloudWatch metrics used for dynamic scaling.
+When default instance warmup is not enabled, each instance starts contributing usage data to the aggregated metrics
+as soon as the instance reaches the InService state. However, if you enable default instance warmup, this lets
 your instances finish warming up before they contribute the usage data.
 
-To optimize the performance of scaling policies that scale continuously, such as target tracking and step scaling 
-policies, we strongly recommend that you enable the default instance warmup, even if its value is set to 0 seconds. 
+To optimize the performance of scaling policies that scale continuously, such as target tracking and step scaling
+policies, we strongly recommend that you enable the default instance warmup, even if its value is set to 0 seconds.
 
 To set up Default Instance Warming for an autoscaling group, simply pass it in as a prop
 

packages/@aws-cdk/aws-autoscaling/lib/auto-scaling-group.ts

@@ -365,6 +365,23 @@ export interface CommonAutoScalingGroupProps {
    *
    */
   readonly capacityRebalance?: boolean;
+
+  /**
+   * Add SSM session permissions to the instance role
+   *
+   * Setting this to `true` adds the necessary permissions to connect
+   * to the instance using SSM Session Manager. You can do this
+   * from the AWS Console.
+   *
+   * NOTE: Setting this flag to `true` may not be enough by itself.
+   * You must also use an AMI that comes with the SSM Agent, or install
+   * the SSM Agent yourself. See
+   * [Working with SSM Agent](https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent.html)
+   * in the SSM Developer Guide.
+   *
+   * @default false
+   */
+  readonly ssmSessionPermissions?: boolean;
 }
 
 /**
@@ -1278,6 +1295,10 @@ export class AutoScalingGroup extends AutoScalingGroupBase implements
 
       this.grantPrincipal = this._role;
 
+      if (props.ssmSessionPermissions) {
+        this.role.addManagedPolicy(iam.ManagedPolicy.fromAwsManagedPolicyName('AmazonSSMManagedInstanceCore'));
+      }
+
       const iamProfile = new iam.CfnInstanceProfile(this, 'InstanceProfile', {
         roles: [this.role.roleName],
       });

packages/@aws-cdk/aws-autoscaling/test/auto-scaling-group.test.ts

@@ -2051,6 +2051,30 @@ test('add price-capacity-optimized', () => {
   });
 });
 
+test('ssm permissions adds right managed policy', () => {
+  // GIVEN
+  const stack = new cdk.Stack();
+
+  // WHEN
+  new autoscaling.AutoScalingGroup(stack, 'mip-asg', {
+    vpc: mockVpc(stack),
+    machineImage: new AmazonLinuxImage(),
+    instanceType: InstanceType.of(ec2.InstanceClass.T3, ec2.InstanceSize.LARGE),
+    ssmSessionPermissions: true,
+  });
+
+  Template.fromStack(stack).hasResourceProperties('AWS::IAM::Role', {
+    ManagedPolicyArns: [
+      {
+        'Fn::Join': ['', [
+          'arn:',
+          { Ref: 'AWS::Partition' },
+          ':iam::aws:policy/AmazonSSMManagedInstanceCore',
+        ]],
+      },
+    ],
+  });
+});
 
 function mockSecurityGroup(stack: cdk.Stack) {
   return ec2.SecurityGroup.fromSecurityGroupId(stack, 'MySG', 'most-secure');

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

@@ -788,7 +788,7 @@ AMIs control the OS that gets launched when you start your EC2 instance. The EC2
 library contains constructs to select the AMI you want to use.
 
 Depending on the type of AMI, you select it a different way. Here are some
-examples of things you might want to use:
+examples of images you might want to use:
 
 [example of creating images](test/example.images.lit.ts)
 
@@ -1039,27 +1039,27 @@ care of restarting your instance if it ever fails.
 declare const vpc: ec2.Vpc;
 declare const instanceType: ec2.InstanceType;
 
-// AWS Linux
+// Amazon Linux 1
 new ec2.Instance(this, 'Instance1', {
   vpc,
   instanceType,
-  machineImage: new ec2.AmazonLinuxImage(),
+  machineImage: ec2.MachineImage.latestAmazonLinux(),
 });
 
-// AWS Linux 2
+// Amazon Linux 2
 new ec2.Instance(this, 'Instance2', {
   vpc,
   instanceType,
-  machineImage: new ec2.AmazonLinuxImage({
+  machineImage: ec2.MachineImage.latestAmazonLinux({
     generation: ec2.AmazonLinuxGeneration.AMAZON_LINUX_2,
   }),
 });
 
-// AWS Linux 2 with kernel 5.x
+// Amazon Linux 2 with kernel 5.x
 new ec2.Instance(this, 'Instance3', {
   vpc,
   instanceType,
-  machineImage: new ec2.AmazonLinuxImage({
+  machineImage: ec2.MachineImage.latestAmazonLinux({
     generation: ec2.AmazonLinuxGeneration.AMAZON_LINUX_2,
     kernel: ec2.AmazonLinuxKernel.KERNEL5_X,
   }),
@@ -1069,7 +1069,7 @@ new ec2.Instance(this, 'Instance3', {
 new ec2.Instance(this, 'Instance4', {
   vpc,
   instanceType,
-  machineImage: new ec2.AmazonLinuxImage({
+  machineImage: ec2.MachineImage.latestAmazonLinux({
     generation: ec2.AmazonLinuxGeneration.AMAZON_LINUX_2022,
   }),
 });
@@ -1078,7 +1078,7 @@ new ec2.Instance(this, 'Instance4', {
 new ec2.Instance(this, 'Instance5', {
   vpc,
   instanceType: ec2.InstanceType.of(ec2.InstanceClass.C7G, ec2.InstanceSize.LARGE),
-  machineImage: new ec2.AmazonLinuxImage({
+  machineImage: ec2.MachineImage.latestAmazonLinux({
     generation: ec2.AmazonLinuxGeneration.AMAZON_LINUX_2,
     cpuType: ec2.AmazonLinuxCpuType.ARM_64,
   }),
@@ -1151,6 +1151,48 @@ new ec2.Instance(this, 'Instance', {
 });
 ```
 
+`InitCommand` can not be used to start long-running processes. At deploy time,
+`cfn-init` will always wait for the process to exit before continuing, causing
+the CloudFormation deployment to fail because the signal hasn't been received
+within the expected timeout.
+
+Instead, you should install a service configuration file onto your machine `InitFile`,
+and then use `InitService` to start it.
+
+If your Linux OS is using SystemD (like Amazon Linux 2 or higher), the CDK has
+helpers to create a long-running service using CFN Init. You can create a
+SystemD-compatible config file using `InitService.systemdConfigFile()`, and
+start it immediately. The following examples shows how to start a trivial Python
+3 web server:
+
+```ts
+declare const vpc: ec2.Vpc;
+declare const instanceType: ec2.InstanceType;
+
+new ec2.Instance(this, 'Instance', {
+  vpc,
+  instanceType,
+  machineImage: ec2.MachineImage.latestAmazonLinux({
+    // Amazon Linux 2 uses SystemD
+    generation: ec2.AmazonLinuxGeneration: AMAZON_LINUX_2,
+  }),
+
+  init: ec2.CloudFormationInit.fromElements([
+    // Create a simple config file that runs a Python web server
+    ec2.InitService.systemdConfigFile('simpleserver', {
+      command: '/usr/bin/python3 -m http.server 8080',
+      cwd: '/var/www/html',
+    }),
+    // Start the server using SystemD
+    ec2.InitService.enable('simpleserver', {
+      serviceManager: ec2.ServiceManager.SYSTEMD,
+    }),
+    // Drop an example file to show the web server working
+    ec2.InitFile.fromString('/var/www/html/index.html', 'Hello! It\'s working!'),
+  ]),
+});
+```
+
 You can have services restarted after the init process has made changes to the system.
 To do that, instantiate an `InitServiceRestartHandle` and pass it to the config elements
 that need to trigger the restart and the service itself. For example, the following
@@ -1669,7 +1711,9 @@ The following demonstrates how to create a launch template with an Amazon Machin
 declare const vpc: ec2.Vpc;
 
 const template = new ec2.LaunchTemplate(this, 'LaunchTemplate', {
-  machineImage: ec2.MachineImage.latestAmazonLinux(),
+  machineImage: ec2.MachineImage.latestAmazonLinux({
+    generation: ec2.AmazonLinuxGeneration.AMAZON_LINUX_2,
+  }),
   securityGroup: new ec2.SecurityGroup(this, 'LaunchTemplateSG', {
     vpc: vpc,
   }),
@@ -1699,7 +1743,42 @@ declare const instanceType: ec2.InstanceType;
 new ec2.Instance(this, 'Instance1', {
   vpc,
   instanceType,
-  machineImage: new ec2.AmazonLinuxImage(),
+  machineImage: ec2.MachineImage.latestAmazonLinux(),
   detailedMonitoring: true,
 });
 ```
+
+## Connecting to your instances using SSM Session Manager
+
+SSM Session Manager makes it possible to connect to your instances from the
+AWS Console, without preparing SSH keys.
+
+To do so, you need to:
+
+* Use an image with [SSM agent](https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent.html) installed
+  and configured. [Many images come with SSM Agent
+  preinstalled](https://docs.aws.amazon.com/systems-manager/latest/userguide/ami-preinstalled-agent.html), otherwise you
+  may need to manually put instructions to [install SSM
+  Agent](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-manual-agent-install.html) into your
+  instance's UserData or use EC2 Init).
+* Create the instance with `ssmSessionPermissions: true`.
+
+If these conditions are met, you can connect to the instance from the EC2 Console. Example:
+
+```ts
+declare const vpc: ec2.Vpc;
+declare const instanceType: ec2.InstanceType;
+
+new ec2.Instance(this, 'Instance1', {
+  vpc,
+  instanceType,
+
+  // Amazon Linux 2 comes with SSM Agent by default
+  machineImage: ec2.MachineImage.latestAmazonLinux({
+    generation: ec2.AmazonLinuxGeneration.AMAZON_LINUX_2,
+  }),
+
+  // Turn on SSM
+  ssmSessionPermissions: true,
+});
+```