WIP: feat(ec2): add instance resource

packages/@aws-cdk/aws-ec2/lib/bastion-host.ts

@@ -0,0 +1,94 @@
+import { PolicyStatement } from "@aws-cdk/aws-iam";
+import { CfnOutput, Construct } from "@aws-cdk/core";
+import { AmazonLinuxGeneration, AmazonLinuxImage, InstanceClass, InstanceSize, InstanceType } from ".";
+import { Instance } from "./instance";
+import { ISecurityGroup } from "./security-group";
+import { IVpc, SubnetType } from "./vpc";
+
+/**
+ * Properties of the bastion host
+ *
+ * @experimental
+ */
+export interface BastionHostLinuxProps {
+
+  /**
+   * In which AZ to place the instance within the VPC
+   *
+   * @default - Random zone.
+   */
+  readonly availabilityZone?: string;
+
+  /**
+   * VPC to launch the instance in.
+   */
+  readonly vpc: IVpc;
+
+  /**
+   * The name of the instance
+   *
+   * @default 'BastionHost'
+   */
+  readonly instanceName?: string;
+
+  /**
+   * Use a public subnet instead of a private one.
+   * Set this to 'true' if you need to connect to this instance via the internet and cannot use SSM.
+   * You have to allow port 22 manually by using the connections field
+   *
+   * @default - false
+   */
+  readonly publicSubnets?: boolean;
+
+  /**
+   * Security Group to assign to this instance
+   *
+   * @default - create new security group with no inbound and all outbound traffic allowed
+   */
+  readonly securityGroup?: ISecurityGroup;
+
+  /**
+   * Type of instance to launch
+   * @default 't3.nano'
+   */
+  readonly instanceType?: InstanceType;
+
+}
+
+/**
+ * This creates a linux bastion host you can use to connect to other instances or services in your VPC.
+ * The recommended way to connect to the bastion host is by using AWS Systems Manager Session Manager.
+ *
+ * The operating system is Amazon Linux 2 with the latest SSM agent installed
+ *
+ * You can also configure this bastion host to allow connections via SSH
+ *
+ * @experimental
+ */
+export class BastionHostLinux extends Instance {
+  constructor(scope: Construct, id: string, props: BastionHostLinuxProps) {
+    super(scope, id, {
+      vpc: props.vpc,
+      availabilityZone: props.availabilityZone,
+      securityGroup: props.securityGroup,
+      instanceName: props.instanceName || 'BastionHost',
+      instanceType: props.instanceType || InstanceType.of(InstanceClass.T3, InstanceSize.NANO),
+      machineImage: new AmazonLinuxImage({ generation: AmazonLinuxGeneration.AMAZON_LINUX_2 }),
+      vpcSubnets: props.publicSubnets ? { subnetType: SubnetType.PUBLIC } : { subnetType: SubnetType.PRIVATE },
+    });
+    this.addToRolePolicy(new PolicyStatement({
+      actions: [
+        'ssmmessages:*',
+        'ssm:UpdateInstanceInformation',
+        'ec2messages:*'
+      ],
+      resources: ['*'],
+    }));
+    this.addUserData('yum install -y https://s3.amazonaws.com/ec2-downloads-windows/SSMAgent/latest/linux_amd64/amazon-ssm-agent.rpm');
+
+    new CfnOutput(this, 'BastionHostId', {
+      description: 'Instance ID of the bastion host. Use this to connect via SSM Session Manager',
+      value: this.instanceId,
+    });
+  }
+}

packages/@aws-cdk/aws-ec2/lib/index.ts

@@ -1,5 +1,7 @@
+export * from './bastion-host';
 export * from './connections';
 export * from './instance-types';
+export * from './instance';
 export * from './machine-image';
 export * from './port';
 export * from './security-group';

packages/@aws-cdk/aws-ec2/lib/instance.ts

@@ -0,0 +1,278 @@
+import iam = require('@aws-cdk/aws-iam');
+
+import { Construct, Duration, Fn, Lazy, Resource, Tag } from '@aws-cdk/core';
+import { Connections, IConnectable } from './connections';
+import { CfnInstance } from './ec2.generated';
+import { InstanceType } from './instance-types';
+import { IMachineImage, OperatingSystemType } from './machine-image';
+import { ISecurityGroup, SecurityGroup } from './security-group';
+import { UserData } from './user-data';
+import { IVpc, SubnetSelection } from './vpc';
+
+/**
+ * Name tag constant
+ */
+const NAME_TAG: string = 'Name';
+
+/**
+ * Properties of an EC2 Instance
+ */
+export interface InstanceProps {
+
+  /**
+   * Name of SSH keypair to grant access to instance
+   *
+   * @default - No SSH access will be possible.
+   */
+  readonly keyName?: string;
+
+  /**
+   * Where to place the instance within the VPC
+   *
+   * @default - Private subnets.
+   */
+  readonly vpcSubnets?: SubnetSelection;
+
+  /**
+   * In which AZ to place the instance within the VPC
+   *
+   * @default - Random zone.
+   */
+  readonly availabilityZone?: string;
+
+  /**
+   * Whether the instance could initiate connections to anywhere by default.
+   * This property is only used when you do not provide a security group.
+   *
+   * @default true
+   */
+  readonly allowAllOutbound?: boolean;
+
+  /**
+   * The length of time to wait for the resourceSignalCount
+   *
+   * The maximum value is 43200 (12 hours).
+   *
+   * @default Duration.minutes(5)
+   */
+  readonly resourceSignalTimeout?: Duration;
+
+  /**
+   * VPC to launch the instance in.
+   */
+  readonly vpc: IVpc;
+
+  /**
+   * Security Group to assign to this instance
+   *
+   * @default - create new security group
+   */
+  readonly securityGroup?: ISecurityGroup;
+
+  /**
+   * Type of instance to launch
+   */
+  readonly instanceType: InstanceType;
+
+  /**
+   * AMI to launch
+   */
+  readonly machineImage: IMachineImage;
+
+  /**
+   * Specific UserData to use
+   *
+   * The UserData may still be mutated after creation.
+   *
+   * @default - A UserData object appropriate for the MachineImage's
+   * Operating System is created.
+   */
+  readonly userData?: UserData;
+
+  /**
+   * An IAM role to associate with the instance profile assigned to this Auto Scaling Group.
+   *
+   * The role must be assumable by the service principal `ec2.amazonaws.com`:
+   *
+   * @example
+   *
+   *    const role = new iam.Role(this, 'MyRole', {
+   *      assumedBy: new iam.ServicePrincipal('ec2.amazonaws.com')
+   *    });
+   *
+   * @default - A role will automatically be created, it can be accessed via the `role` property
+   */
+  readonly role?: iam.IRole;
+
+  /**
+   * The name of the instance
+   *
+   * @default - CDK generated name
+   */
+  readonly instanceName?: string;
+
+}
+
+/**
+ * This represents a single EC2 instance
+ */
+export class Instance extends Resource implements IConnectable {
+
+  /**
+   * The type of OS the instance is running.
+   */
+  public readonly osType: OperatingSystemType;
+
+  /**
+   * Allows specify security group connections for the instance.
+   */
+  public readonly connections: Connections;
+
+  /**
+   * The IAM role assumed by the instance.
+   */
+  public readonly role: iam.IRole;
+
+  /**
+   * UserData for the instance
+   */
+  public readonly userData: UserData;
+
+  /**
+   * the underlying instance resource
+   * @attribute
+   */
+  public readonly instance: CfnInstance;
+  /**
+   * @attribute
+   */
+  public readonly instanceId: string;
+  /**
+   * @attribute
+   */
+  public readonly instanceAvailabilityZone: string;
+  /**
+   * @attribute
+   */
+  public readonly instancePrivateDnsName: string;
+  /**
+   * @attribute
+   */
+  public readonly instancePrivateIp: string;
+  /**
+   * @attribute
+   */
+  public readonly instancePublicDnsName: string;
+  /**
+   * @attribute
+   */
+  public readonly instancePublicIp: string;
+
+  private readonly securityGroup: ISecurityGroup;
+  private readonly securityGroups: ISecurityGroup[] = [];
+
+  constructor(scope: Construct, id: string, props: InstanceProps) {
+    super(scope, id);
+
+    if (props.securityGroup) {
+      this.securityGroup = props.securityGroup;
+    } else {
+      this.securityGroup = new SecurityGroup(this, 'InstanceSecurityGroup', {
+        vpc: props.vpc,
+        allowAllOutbound: props.allowAllOutbound !== false
+      });
+    }
+    this.connections = new Connections({ securityGroups: [this.securityGroup] });
+    this.securityGroups.push(this.securityGroup);
+    Tag.add(this, NAME_TAG, props.instanceName || this.node.path);
+
+    this.role = props.role || new iam.Role(this, 'InstanceRole', {
+      assumedBy: new iam.ServicePrincipal('ec2.amazonaws.com')
+    });
+
+    const iamProfile = new iam.CfnInstanceProfile(this, 'InstanceProfile', {
+      roles: [this.role.roleName]
+    });
+
+    // use delayed evaluation
+    const imageConfig = props.machineImage.getImage(this);
+    this.userData = props.userData || imageConfig.userData || UserData.forOperatingSystem(imageConfig.osType);
+    const userDataToken = Lazy.stringValue({ produce: () => Fn.base64(this.userData.render()) });
+    const securityGroupsToken = Lazy.listValue({ produce: () => this.securityGroups.map(sg => sg.securityGroupId) });
+
+    const { subnets } = props.vpc.selectSubnets(props.vpcSubnets);
+    let subnet;
+    if (props.availabilityZone) {
+      const selected = subnets.filter(sn => sn.availabilityZone === props.availabilityZone);
+      if (selected.length === 1) {
+        subnet = selected[0];
+      } else {
+        throw new Error('When specifying AZ there has to be exactly on subnet of the given type in this az');
+      }
+    } else {
+      subnet = subnets[0];
+    }
+
+    this.instance = new CfnInstance(this, 'Instance', {
+      imageId: imageConfig.imageId,
+      keyName: props.keyName,
+      instanceType: props.instanceType.toString(),
+      securityGroupIds: securityGroupsToken,
+      iamInstanceProfile: iamProfile.ref,
+      userData: userDataToken,
+      subnetId: subnet.subnetId,
+      availabilityZone: subnet.availabilityZone,
+    });
+    this.instance.node.addDependency(this.role);
+
+    this.osType = imageConfig.osType;
+    this.node.defaultChild = this.instance;
+
+    this.instanceId = this.instance.ref;
+    this.instanceAvailabilityZone = this.instance.attrAvailabilityZone;
+    this.instancePrivateDnsName = this.instance.attrPrivateDnsName;
+    this.instancePrivateIp = this.instance.attrPrivateIp;
+    this.instancePublicDnsName = this.instance.attrPublicDnsName;
+    this.instancePublicIp = this.instance.attrPublicIp;
+
+    this.applyUpdatePolicies(props);
+  }
+
+  /**
+   * Add the security group to the instance.
+   *
+   * @param securityGroup: The security group to add
+   */
+  public addSecurityGroup(securityGroup: ISecurityGroup): void {
+    this.securityGroups.push(securityGroup);
+  }
+
+  /**
+   * Add command to the startup script of the instance.
+   * The command must be in the scripting language supported by the instance's OS (i.e. Linux/Windows).
+   */
+  public addUserData(...commands: string[]) {
+    this.userData.addCommands(...commands);
+  }
+
+  /**
+   * Adds a statement to the IAM role assumed by the instance.
+   */
+  public addToRolePolicy(statement: iam.PolicyStatement) {
+    this.role.addToPolicy(statement);
+  }
+
+  /**
+   * Apply CloudFormation update policies for the instance
+   */
+  private applyUpdatePolicies(props: InstanceProps) {
+    if (props.resourceSignalTimeout !== undefined) {
+      this.instance.cfnOptions.creationPolicy = {
+        ...this.instance.cfnOptions.creationPolicy,
+        resourceSignal: {
+          timeout: props.resourceSignalTimeout && props.resourceSignalTimeout.toISOString(),
+        }
+      };
+    }
+  }
+}

packages/@aws-cdk/aws-ec2/lib/vpc.ts

@@ -176,7 +176,7 @@ export interface SubnetSelection {
   /**
    * If true, return at most one subnet per AZ
    *
-   * @defautl false
+   * @default false
    */
   readonly onePerAz?: boolean;
 }