feat(ec2): lookup security group by name

allowed-breaking-changes.txt

@@ -77,4 +77,8 @@ strengthened:@aws-cdk/aws-lambda-event-sources.ManagedKafkaEventSourceProps
 
 # Remove IO2 from autoscaling EbsDeviceVolumeType. This value is not supported 
 # at the moment and was not supported in the past.
-removed:@aws-cdk/aws-autoscaling.EbsDeviceVolumeType.IO2
+removed:@aws-cdk/aws-autoscaling.EbsDeviceVolumeType.IO2
+
+# Changed property securityGroupId to optional because either securityGroupId or 
+# securityGroupName is required. Therefore securityGroupId is no longer mandatory.
+weakened:@aws-cdk/cloud-assembly-schema.SecurityGroupContextQuery

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

@@ -577,6 +577,33 @@ const mySecurityGroupWithoutInlineRules = new ec2.SecurityGroup(this, 'SecurityG
 mySecurityGroupWithoutInlineRules.addIngressRule(ec2.Peer.anyIpv4(), ec2.Port.tcp(22), 'allow ssh access from the world');
 ```
 
+### Importing an existing security group
+
+If you know the ID and the configuration of the security group to import, you can use `SecurityGroup.fromSecurityGroupId`:
+
+```ts
+const sg = ec2.SecurityGroup.fromSecurityGroupId(this, 'SecurityGroupImport', 'security-group-import', {
+  allowAllOutbound: true,
+});
+```
+
+Alternatively, use method `SecurityGroup.fromLookupAttributes` to import security groups if you do not know the ID or the configuration details. You can lookup a security group by `securityGroupId` or by `securityGroupName`.
+
+The result of the `SecurityGroup.fromLookupAttributes` operation will be written to a file called `cdk.context.json`. You must commit this file to source control so that the lookup values are available in non-privileged environments such as CI build steps, and to ensure your template builds are repeatable.
+
+```ts fixture=with-vpc
+const sg = ec2.SecurityGroup.fromLookupAttributes(
+  this, 'SecurityGroupLookup', {
+    // This imports a security group by name but you can also
+    // specify a 'securityGroupId.
+    securityGroupName: 'security-group-lookup',
+
+    // optional, lookup in specified VPC
+    vpc,
+  }
+);
+```
+
 ## Machine Images (AMIs)
 
 AMIs control the OS that gets launched when you start your EC2 instance. The EC2

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

@@ -12,6 +12,7 @@ export * from './network-acl';
 export * from './network-acl-types';
 export * from './port';
 export * from './security-group';
+export * from './security-group-lookup';
 export * from './subnet';
 export * from './peer';
 export * from './volume';

packages/@aws-cdk/aws-ec2/lib/security-group-lookup.ts

@@ -0,0 +1,35 @@
+import { IVpc } from '.';
+
+/**
+ * Properties for looking up an existing SecurityGroup.
+ *
+ * Either `securityGroupName` or `securityGroupId` hast to be specified, otherwise an error is raised.
+ */
+export interface SecurityGroupLookupOptions {
+  /**
+   * The name of the security group
+   *
+   * If given, will import the SecurityGroup with this name.
+   *
+   * @default Don't filter on securityGroupName
+   */
+  readonly securityGroupName?: string;
+
+  /**
+   * The ID of the security group
+   *
+   * If given, will import the SecurityGroup with this ID.
+   *
+   * @default Don't filter on securityGroupId
+   */
+  readonly securityGroupId?: string;
+
+  /**
+   * The VPC of the security group
+   *
+   * If given, will filter the SecurityGroup based on the VPC.
+   *
+   * @default Don't filter on VPC
+   */
+  readonly vpc?: IVpc,
+}

packages/@aws-cdk/aws-ec2/lib/security-group.ts

@@ -6,6 +6,7 @@ import { Connections } from './connections';
 import { CfnSecurityGroup, CfnSecurityGroupEgress, CfnSecurityGroupIngress } from './ec2.generated';
 import { IPeer, Peer } from './peer';
 import { Port } from './port';
+import { SecurityGroupLookupOptions } from './security-group-lookup';
 import { IVpc } from './vpc';
 
 const SECURITY_GROUP_SYMBOL = Symbol.for('@aws-cdk/iam.SecurityGroup');
@@ -318,13 +319,32 @@ export class SecurityGroup extends SecurityGroupBase {
    * Look up a security group by id.
    */
   public static fromLookup(scope: Construct, id: string, securityGroupId: string) {
-    if (Token.isUnresolved(securityGroupId)) {
+    return this.fromLookupAttributes(scope, id, { securityGroupId });
+  }
+
+  /**
+   * Look up a security group.
+   */
+  public static fromLookupAttributes(scope: Construct, id: string, options: SecurityGroupLookupOptions) {
+    if (Token.isUnresolved(options.securityGroupId) || Token.isUnresolved(options.securityGroupName) || Token.isUnresolved(options.vpc?.vpcId)) {
       throw new Error('All arguments to look up a security group must be concrete (no Tokens)');
     }
 
+    if (options.securityGroupId && options.securityGroupName) {
+      throw new Error('\'securityGroupId\' and \'securityGroupName\' can not be specified both when looking up a security group');
+    }
+
+    if (!options.securityGroupId && !options.securityGroupName) {
+      throw new Error('\'securityGroupId\' or \'securityGroupName\' must be specified to look up a security group');
+    }
+
     const attributes: cxapi.SecurityGroupContextResponse = ContextProvider.getValue(scope, {
       provider: cxschema.ContextProvider.SECURITY_GROUP_PROVIDER,
-      props: { securityGroupId },
+      props: {
+        securityGroupId: options.securityGroupId,
+        securityGroupName: options.securityGroupName,
+        vpcId: options.vpc?.vpcId,
+      },
       dummyValue: {
         securityGroupId: 'sg-12345',
         allowAllOutbound: true,

packages/@aws-cdk/aws-ec2/test/security-group.test.ts

@@ -326,8 +326,177 @@ describe('security group', () => {
     expect(securityGroup.securityGroupId).toEqual('sg-12345');
     expect(securityGroup.allowAllOutbound).toEqual(true);
 
+  });
+
+  test('can look up a security group by id', () => {
+    // GIVEN
+    const app = new App();
+    const stack = new Stack(app, 'stack', {
+      env: {
+        account: '1234',
+        region: 'us-east-1',
+      },
+    });
+
+    // WHEN
+    const securityGroup = SecurityGroup.fromLookupAttributes(stack, 'stack', {
+      securityGroupId: 'sg-12345',
+    });
+
+    // THEN
+    expect(securityGroup.securityGroupId).toEqual('sg-12345');
+    expect(securityGroup.allowAllOutbound).toEqual(true);
+
+  });
+
+  test('can look up a security group by name', () => {
+    // GIVEN
+    const app = new App();
+    const stack = new Stack(app, 'stack', {
+      env: {
+        account: '1234',
+        region: 'us-east-1',
+      },
+    });
+
+    // WHEN
+    const securityGroup = SecurityGroup.fromLookupAttributes(stack, 'stack', {
+      securityGroupName: 'my-security-group',
+    });
+
+    // THEN
+    expect(securityGroup.securityGroupId).toEqual('sg-12345');
+    expect(securityGroup.allowAllOutbound).toEqual(true);
+
+  });
+
+  test('can look up a security group by name and vpc', () => {
+    // GIVEN
+    const app = new App();
+    const stack = new Stack(app, 'stack', {
+      env: {
+        account: '1234',
+        region: 'us-east-1',
+      },
+    });
+
+    const vpc = Vpc.fromVpcAttributes(stack, 'VPC', {
+      vpcId: 'vpc-1234',
+      availabilityZones: ['dummy1a', 'dummy1b', 'dummy1c'],
+    });
+
+    // WHEN
+    const securityGroup = SecurityGroup.fromLookupAttributes(stack, 'stack', {
+      securityGroupName: 'my-security-group',
+      vpc,
+    });
+
+    // THEN
+    expect(securityGroup.securityGroupId).toEqual('sg-12345');
+    expect(securityGroup.allowAllOutbound).toEqual(true);
+
+  });
+
+  test('throws when securityGroupId and securityGroupName are specified both', () => {
+    // GIVEN
+    const app = new App();
+    const stack = new Stack(app, 'stack', {
+      env: {
+        account: '1234',
+        region: 'us-east-1',
+      },
+    });
+
+    // WHEN
+    expect(() => {
+      SecurityGroup.fromLookupAttributes(stack, 'stack', {
+        securityGroupId: 'sg-12345',
+        securityGroupName: 'my-security-group',
+      });
+    }).toThrow(/\'securityGroupId\' and \'securityGroupName\' can not be specified both when looking up a security group/);
+
+  });
+
+  test('throws when neither securityGroupId nor securityGroupName are specified', () => {
+    // GIVEN
+    const app = new App();
+    const stack = new Stack(app, 'stack', {
+      env: {
+        account: '1234',
+        region: 'us-east-1',
+      },
+    });
+
+    // WHEN
+    expect(() => {
+      SecurityGroup.fromLookupAttributes(stack, 'stack', {});
+    }).toThrow(/\'securityGroupId\' or \'securityGroupName\' must be specified to look up a security group/);
+
+  });
+
+  test('throws if securityGroupId is tokenized', () => {
+    // GIVEN
+    const app = new App();
+    const stack = new Stack(app, 'stack', {
+      env: {
+        account: '1234',
+        region: 'us-east-1',
+      },
+    });
+
+    // WHEN
+    expect(() => {
+      SecurityGroup.fromLookupAttributes(stack, 'stack', {
+        securityGroupId: Lazy.string({ produce: () => 'sg-12345' }),
+      });
+    }).toThrow('All arguments to look up a security group must be concrete (no Tokens)');
 
   });
+
+  test('throws if securityGroupName is tokenized', () => {
+    // GIVEN
+    const app = new App();
+    const stack = new Stack(app, 'stack', {
+      env: {
+        account: '1234',
+        region: 'us-east-1',
+      },
+    });
+
+    // WHEN
+    expect(() => {
+      SecurityGroup.fromLookupAttributes(stack, 'stack', {
+        securityGroupName: Lazy.string({ produce: () => 'my-security-group' }),
+      });
+    }).toThrow('All arguments to look up a security group must be concrete (no Tokens)');
+
+  });
+
+  test('throws if vpc id is tokenized', () => {
+    // GIVEN
+    const app = new App();
+    const stack = new Stack(app, 'stack', {
+      env: {
+        account: '1234',
+        region: 'us-east-1',
+      },
+    });
+
+    const vpc = Vpc.fromVpcAttributes(stack, 'VPC', {
+      vpcId: Lazy.string({ produce: () => 'vpc-1234' }),
+      availabilityZones: ['dummy1a', 'dummy1b', 'dummy1c'],
+    });
+
+    // WHEN
+    expect(() => {
+      SecurityGroup.fromLookupAttributes(stack, 'stack', {
+        securityGroupName: 'my-security-group',
+        vpc,
+      });
+    }).toThrow('All arguments to look up a security group must be concrete (no Tokens)');
+
+  });
+
 });
 
 function testRulesAreInlined(contextDisableInlineRules: boolean | undefined | null, optionsDisableInlineRules: boolean | undefined) {

packages/@aws-cdk/cloud-assembly-schema/lib/cloud-assembly/context-queries.ts

@@ -416,8 +416,24 @@ export interface SecurityGroupContextQuery {
 
   /**
    * Security group id
+   *
+   * @default - None
+   */
+  readonly securityGroupId?: string;
+
+  /**
+   * Security group name
+   *
+   * @default - None
    */
-  readonly securityGroupId: string;
+  readonly securityGroupName?: string;
+
+  /**
+   * VPC ID
+   *
+   * @default - None
+   */
+  readonly vpcId?: string;
 }
 
 /**

packages/@aws-cdk/cloud-assembly-schema/schema/cloud-assembly.schema.json

@@ -761,14 +761,21 @@
                     "type": "string"
                 },
                 "securityGroupId": {
-                    "description": "Security group id",
+                    "description": "Security group id (Default - None)",
+                    "type": "string"
+                },
+                "securityGroupName": {
+                    "description": "Security group name (Default - None)",
+                    "type": "string"
+                },
+                "vpcId": {
+                    "description": "VPC ID (Default - None)",
                     "type": "string"
                 }
             },
             "required": [
                 "account",
-                "region",
-                "securityGroupId"
+                "region"
             ]
         },
         "KeyContextQuery": {

packages/@aws-cdk/cloud-assembly-schema/schema/cloud-assembly.version.json

@@ -1 +1 @@
-{"version":"14.0.0"}
+{"version":"15.0.0"}