feat(synthetics): add vpc configuration

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

@@ -173,6 +173,24 @@ new synthetics.Canary(this, 'Bucket Canary', {
 >
 > See Synthetics [docs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Synthetics_Canaries_WritingCanary.html).
 
+### VPC
+
+You can specify what VPC a canary executes in. This can allow for monitoring services that may be internal to a specific VPC. To place a canary within a VPC, you can specify the `vpc` property with the desired `VPC` to place then canary in. This will automatically attach the appropriate IAM permissions to attach to the VPC. This will also create a Security Group and attach to the default subnets for the VPC unless specified via `vpcSubnets` and `securityGroups`.
+
+```ts
+import * as ec2 from '@aws-cdk/aws-ec2';
+
+declare const vpc: ec2.IVpc;
+new synthetics.Canary(this, 'Vpc Canary', {
+ test: synthetics.Test.custom({
+ code: synthetics.Code.fromAsset(path.join(__dirname, 'canary')),
+ handler: 'index.handler',
+ }),
+ runtime: synthetics.Runtime.SYNTHETICS_NODEJS_PUPPETEER_3_3,
+ vpc,
+});
+```
+
 ### Alarms
 
 You can configure a CloudWatch Alarm on a canary metric. Metrics are emitted by CloudWatch automatically and can be accessed by the following APIs:

packages/@aws-cdk/aws-synthetics/lib/canary.ts

@@ -1,5 +1,6 @@
 import * as crypto from 'crypto';
 import { Metric, MetricOptions, MetricProps } from '@aws-cdk/aws-cloudwatch';
+import * as ec2 from '@aws-cdk/aws-ec2';
 import * as iam from '@aws-cdk/aws-iam';
 import * as s3 from '@aws-cdk/aws-s3';
 import * as cdk from '@aws-cdk/core';
@@ -179,6 +180,30 @@ export interface CanaryProps {
  * @default - No environment variables.
  */
  readonly environmentVariables?: { [key: string]: string };
+
+ /**
+ * The VPC where this canary is run.
+ *
+ * Specify this if the canary needs to access resources in a VPC.
+ *
+ * @default - Not in VPC
+ */
+ readonly vpc?: ec2.IVpc;
+
+ /**
+ * Where to place the network interfaces within the VPC.
+ *
+ * @default - the Vpc default strategy if not specified
+ */
+ readonly vpcSubnets?: ec2.SubnetSelection;
+
+ /**
+ * The list of security groups to associate with the canary's network interfaces.
+ *
+ * @default - If the function is placed within a VPC and a security group is
+ * not specified a dedicated security group will be created for this canary.
+ */
+ readonly securityGroups?: ec2.ISecurityGroup[];
 }
 
 /**
@@ -229,7 +254,7 @@ export class Canary extends cdk.Resource {
  enforceSSL: true,
  });
 
- this.role = props.role ?? this.createDefaultRole(props.artifactsBucketLocation?.prefix);
+ this.role = props.role ?? this.createDefaultRole(props);
 
  const resource: CfnCanary = new CfnCanary(this, 'Resource', {
  artifactS3Location: this.artifactsBucket.s3UrlForObject(props.artifactsBucketLocation?.prefix),
@@ -242,6 +267,7 @@ export class Canary extends cdk.Resource {
  successRetentionPeriod: props.successRetentionPeriod?.toDays(),
  code: this.createCode(props),
  runConfig: this.createRunConfig(props),
+ vpcConfig: this.createVpcConfig(props),
  });
 
  this.canaryId = resource.attrId;
@@ -289,7 +315,9 @@ export class Canary extends cdk.Resource {
  /**
  * Returns a default role for the canary
  */
- private createDefaultRole(prefix?: string): iam.IRole {
+ private createDefaultRole(props: CanaryProps): iam.IRole {
+ const prefix = props.artifactsBucketLocation?.prefix;
+
  // Created role will need these policies to run the Canary.
  // https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-synthetics-canary.html#cfn-synthetics-canary-executionrolearn
  const policy = new iam.PolicyDocument({
@@ -318,11 +346,19 @@ export class Canary extends cdk.Resource {
  ],
  });
 
+ const managedPolicies: iam.IManagedPolicy[] = [];
+
+ if (props.vpc) {
+ // Policy that will have ENI creation permissions
+ managedPolicies.push(iam.ManagedPolicy.fromAwsManagedPolicyName('service-role/AWSLambdaVPCAccessExecutionRole'));
+ }
+
  return new iam.Role(this, 'ServiceRole', {
  assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com'),
  inlinePolicies: {
  canaryPolicy: policy,
  },
+ managedPolicies,
  });
  }
 
@@ -352,22 +388,47 @@ export class Canary extends cdk.Resource {
  };
  }
 
+ private createRunConfig(props: CanaryProps): CfnCanary.RunConfigProperty | undefined {
+ if (!props.environmentVariables) {
+ return undefined;
+ }
+ return {
+ environmentVariables: props.environmentVariables,
+ };
+ }
+
  /**
-  * Returns a canary schedule object
-  */
+ * Returns a canary schedule object
+ */
  private createSchedule(props: CanaryProps): CfnCanary.ScheduleProperty {
  return {
  durationInSeconds: String(`${props.timeToLive?.toSeconds() ?? 0}`),
  expression: props.schedule?.expressionString ?? 'rate(5 minutes)',
  };
  }
 
- private createRunConfig(props: CanaryProps): CfnCanary.RunConfigProperty | undefined {
- if (!props.environmentVariables) {
+ private createVpcConfig(props: CanaryProps): CfnCanary.VPCConfigProperty | undefined {
+ if (!props.vpc) {
  return undefined;
  }
+
+ const { subnetIds } = props.vpc.selectSubnets(props.vpcSubnets);
+ let securityGroups: ec2.ISecurityGroup[];
+
+ if (props.securityGroups && props.securityGroups.length > 0) {
+ securityGroups = props.securityGroups;
+ } else {
+ const securityGroup = new ec2.SecurityGroup(this, 'SecurityGroup', {
+ vpc: props.vpc,
+ description: 'Automatic security group for Canary ' + cdk.Names.uniqueId(this),
+ });
+ securityGroups = [securityGroup];
+ }
+
  return {
- environmentVariables: props.environmentVariables,
+ vpcId: props.vpc.vpcId,
+ subnetIds,
+ securityGroupIds: securityGroups.map(sg => sg.securityGroupId),
  };
  }
 

packages/@aws-cdk/aws-synthetics/package.json

@@ -90,6 +90,7 @@
  },
  "dependencies": {
  "@aws-cdk/aws-cloudwatch": "0.0.0",
+ "@aws-cdk/aws-ec2": "0.0.0",
  "@aws-cdk/aws-iam": "0.0.0",
  "@aws-cdk/aws-s3": "0.0.0",
  "@aws-cdk/aws-s3-assets": "0.0.0",
@@ -98,6 +99,7 @@
  },
  "peerDependencies": {
  "@aws-cdk/aws-cloudwatch": "0.0.0",
+ "@aws-cdk/aws-ec2": "0.0.0",
  "@aws-cdk/aws-iam": "0.0.0",
  "@aws-cdk/aws-s3": "0.0.0",
  "@aws-cdk/aws-s3-assets": "0.0.0",

packages/@aws-cdk/aws-synthetics/test/canary.test.ts

@@ -1,4 +1,5 @@
 import { Match, Template } from '@aws-cdk/assertions';
+import * as ec2 from '@aws-cdk/aws-ec2';
 import * as iam from '@aws-cdk/aws-iam';
 import * as s3 from '@aws-cdk/aws-s3';
 import { Duration, Lazy, Stack } from '@aws-cdk/core';
@@ -441,6 +442,41 @@ test('can specify custom test', () => {
  });
 });
 
+test('can specify vpc', () => {
+ // GIVEN
+ const stack = new Stack();
+ const vpc = new ec2.Vpc(stack, 'VPC', { maxAzs: 2 });
+
+ // WHEN
+ new synthetics.Canary(stack, 'Canary', {
+ test: synthetics.Test.custom({
+ handler: 'index.handler',
+ code: synthetics.Code.fromInline(`
+ exports.handler = async () => {
+ console.log(\'hello world\');
+ };`),
+ }),
+ runtime: synthetics.Runtime.SYNTHETICS_NODEJS_2_0,
+ vpc,
+ });
+
+ // THEN
+ Template.fromStack(stack).hasResourceProperties('AWS::Synthetics::Canary', {
+ Code: {
+ Handler: 'index.handler',
+ Script: `
+ exports.handler = async () => {
+ console.log(\'hello world\');
+ };`,
+ },
+ VPCConfig: {
+ VpcId: {
+ Ref: Match.anyValue(),
+ },
+ },
+ });
+});
+
 test('Role policy generated as expected', () => {
  // GIVEN
  const stack = new Stack();