feat(ec2): SSM sessions (#24673)

rix0rrr · web-flow · commit 9744a8295fab · 2023-03-20T13:41:30.000Z
It's not too hard to enable SSM Session Manager to Instances and AutoScalingGroups (it's a matter of picking the right AMI and adding the right managed policy to the instance role).

This PR adds a single boolean to turn on the policy directly and advertises the feature in the README for people who might otherwise not know this feature exists.

Also consistentize the use and explanation of `MachineImage.latestAmazonLinux` a bit.

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
diff --git a/packages/@aws-cdk/aws-autoscaling/README.md b/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
 
diff --git a/packages/@aws-cdk/aws-autoscaling/lib/auto-scaling-group.ts b/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],
       });
diff --git a/packages/@aws-cdk/aws-autoscaling/test/auto-scaling-group.test.ts b/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');
diff --git a/packages/@aws-cdk/aws-ec2/README.md b/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,
   }),
@@ -1669,7 +1669,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 +1701,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,
+});
+```
diff --git a/packages/@aws-cdk/aws-ec2/lib/instance.ts b/packages/@aws-cdk/aws-ec2/lib/instance.ts
@@ -254,6 +254,23 @@ export interface InstanceProps {
    * @default - false
    */
   readonly detailedMonitoring?: 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;
 }
 
 /**
@@ -342,6 +359,10 @@ export class Instance extends Resource implements IInstance {
     });
     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],
     });
diff --git a/packages/@aws-cdk/aws-ec2/lib/machine-image.ts b/packages/@aws-cdk/aws-ec2/lib/machine-image.ts
@@ -39,6 +39,20 @@ export abstract class MachineImage {
    * deployment. Be aware this will cause your instances to be replaced when a
    * new version of the image becomes available. Do not store stateful information
    * on the instance if you are using this image.
+   *
+   * N.B.: "latest" in the name of this function indicates that it always uses the most recent
+   * image of a particular generation of Amazon Linux, not that it uses the "latest generation".
+   * For backwards compatibility, this function uses Amazon Linux 1 if no generation
+   * is specified.
+   *
+   * Specify the desired generation using the `generation` property:
+   *
+   * ```ts
+   * ec2.MachineImage.latestAmazonLinux({
+   *   // Use Amazon Linux 2
+   *   generation: ec2.AmazonLinuxGeneration.AMAZON_LINUX_2,
+   * })
+   * ```
    */
   public static latestAmazonLinux(props?: AmazonLinuxImageProps): IMachineImage {
     return new AmazonLinuxImage(props);
diff --git a/packages/@aws-cdk/aws-ec2/test/instance.test.ts b/packages/@aws-cdk/aws-ec2/test/instance.test.ts
@@ -602,3 +602,26 @@ test('cause replacement from s3 asset in userdata', () => {
     }),
   }));
 });
+
+test('ssm permissions adds right managed policy', () => {
+  // WHEN
+  new Instance(stack, 'InstanceOne', {
+    vpc,
+    machineImage: new AmazonLinuxImage(),
+    instanceType: InstanceType.of(InstanceClass.T3, InstanceSize.LARGE),
+    ssmSessionPermissions: true,
+  });
+
+  Template.fromStack(stack).hasResourceProperties('AWS::IAM::Role', {
+    ManagedPolicyArns: [
+      {
+        'Fn::Join': ['', [
+          'arn:',
+          { Ref: 'AWS::Partition' },
+          ':iam::aws:policy/AmazonSSMManagedInstanceCore',
+        ]],
+      },
+    ],
+  });
+});
+
