@mapbox/magic-cfn-resources

magic-cfn-resources

Builds Lambda-backed custom Cloudformation resources. When you use magic-cfn-resources's build method, a Lambda function is created in your stack and used to build a custom resource. Resources that can be built with magic-cfn-resources are: SnsSubscription, DynamoDBStreamLabel, StackOutputs, and SpotFleet.

Provided resources in detail:

SNS Subscriptions

This allows you to manage SNS subscriptions as though they are first-class CloudFormation resources.

DynamoDB Stream Labels

This does not actually create any backend resource, but looks up the label for the stream associated with a DynamoDB table.

This resource will use the stream's label as its PhysicalResourceId, so you can then access the label itself in your template via:

{ "Ref": "LogicalNameOfYourCustomResource" }

CloudFormation StackOutputs

Looks up the Outputs for an existing CloudFormation stack.

You can access the values of the stack's outputs with Fn::GetAtt

{ "Fn::GetAtt": ["LogicalNameOfYourCustomResource", "LogicalNameOfStackOutput"] }

SpotFleet

Makes SpotFleet requests.

DefaultVpc

Looks up the default VPC in the region you've launched your stack in, and provides information about the VPC via Fn::GetAtt.

{ "Fn::GetAtt": ["LogicalNameOfYourCustomResource", "VpcId"] }

You can use Fn::GetAtt to obtain the following data:

• VpcId: the default VPC's ID
• AvailabilityZones: an array of strings representing the VPC's availability zones
• AvailabilityZoneCount: the number of availability zones
• PublicSubnets: an array of strings representing the VPC's public subnets
• RouteTable: the ID for the first route table in the VPC

S3NotificationTopicConfig

Creates a notification topic configuration on an S3 bucket.

S3Inventory

Creates an InventoryConfiguration for an existing S3 bucket that is not defined in CloudFormation. If you are defining an S3 bucket in CloudFormation, you can use the native CloudFormation support for this configuration.

To create a magical resource in your own CloudFormation template:

In an existing script or in a new script (i.e. sns-subscription.js):

// Purpose: create a handler for your Lambda function to reference

const magicCfnResources = require('@mapbox/magic-cfn-resources');
// export the custom function needed for your stack.
module.exports.SnsSubscription = magicCfnResources.SnsSubscription;

Another example: module.exports.SpotFleet = magicCfnResources.SpotFleet;

In the CloudFormation template of your stack:

const magicCfnResources = require('@mapbox/magic-cfn-resources');

Then, pass in the necessary parameters to magicCfnResources.build. These are the parameters needed for each resource:

SnsSubscription

const SnsSubscription = magicCfnResources.build({
  CustomResourceName: 'SnsSubscription',
  LogicalName: 'Logical Name', // a name to refer to the custom resource being built
  S3Bucket: 'Bucket Name', // the S3 bucket the code for the handler lives in
  S3Key: 'Key', // the S3 key for where the handler lives
  Handler: 'sns-subscription.SnsSubscription', // references the handler created in the repository
  Properties: {
    SnsTopicArn: 'Topic Arn', // the ARN of the SNS Topic you are subscribing to
    Protocol: 'Protocol', // the SNS protocol, i.e. 'sqs', 'email'
    Endpoint: 'Endpoint' // the endpoint you are subscribing
  }
});

DynamoDBStreamLabel

const DynamoDBStreamLabel = magicCfnResources.build({
  CustomResourcenName: 'DynamoDBStreamLabel',
  LogicalName: 'Logical Name', // a name to refer to the custom resource being built
  S3Bucket: 'Bucket Name', // the S3 bucket the code for the handler lives in
  S3Key: 'Key', // the S3 key for where the handler lives
  Handler: 'dynamodb-stream-label.DynamoDBStreamLabel', // references the handler created in the repository
  Properties: {
    TableName: 'Name of Table', // the name of the DynamoDB table
    TableRegion: 'Region' // the region of the DynamoDB table i.e.: 'us-east-1'
  }
});

StackOutputs

const StackOutputs = magicCfnResources.build({
  CustomResourceName: 'StackOutputs',
  LogicalName: 'Logical Name', // a name to refer to the custom resource being built
  S3Bucket: 'Bucket Name', // the S3 bucket the code for the handler lives in
  S3Key: 'Key', // the S3 key for where the handler lives
  Handler: 'stack-outputs.StackOutputs', // references the handler created in the repository
  Properties: {
    StackName: 'Name', // name of the CloudFormation stack
    StackRegion: 'region' // region of the CloudFormation stack i.e.: 'us-east-1'
  }
});

SpotFleet

const SpotFleet = magicCfnResources.build({
  CustomResourceName: 'SpotFleet',
  LogicalName: 'Logical Name', // a name to refer to the custom resource being built
  S3Bucket: 'Bucket Name', // the S3 bucket the code for the handler lives in
  S3Key: 'Key', // the S3 key for where the handler lives
  Handler: 'spot-fleet.SpotFleet', // references the handler created in the repository
  Properties: {
    SpotFleetRequestConfigData: { }, // object with SpotFleet configuration specifics
    Region: 'region', // region of the SpotFleet i.e.: 'us-east-1'
  }
});

DefaultVpc

const DefaultVpd = magicCfnResources.build({
  CustomResourceName: 'DefaultVpc',
  LogicalName: 'Logical Name', // a name to refer to the custom resource being built
  S3Bucket: 'Bucket Name', // the S3 bucket the code for the handler lives in
  S3Key: 'Key', // the S3 key for where the handler lives
  Handler: 'index.DefaultVpc', // references the handler created in the repository
  Properties: {}
});

S3NotificationTopicConfig

const S3TopicConfig = magicCfnResources.build({
  CustomResourceName: 'S3NotificationTopicConfig',
  LogicalName: 'Logical Name', // a name to refer to the custom resource being built
  S3Bucket: 'Bucket Name', // the S3 bucket the code for the handler lives in
  S3Key: 'Key', // the S3 key for where the handler lives
  Handler: 'index.DefaultVpc', // references the handler created in the repository
  Properties: {
    Id: 'notif-id', // an id to identify your notification config
    SnsTopicArn: 'topic arn', // topic arn to subscribe (must be in the same region as bucket)
    Bucket: 'bucket name', // name of bucket configuration is placed on,
    BucketRegion: 'us-east-1', // the region the bucket is in
    EventTypes: ['s3:ObjectCreated:*'], // the types of event to notify about
    PrefixFilter: 'prefix', // a prefix to filter notifications on (optional)
    SuffixFilter: '.jpg', // a suffix to filter notifications on (optional)
    BucketNotificationResources: [ 'bucket Arn' ] 
    // if Bucket permissions need to be scoped, default is access to all resources (optional)
  } 
});

S3Inventory

const S3InventoryConfig = magic.build({
  CustomResourceName: 'S3Inventory',
  LogicalName: 'Logical Name', // a name to refer to the custom resource being built
  S3Bucket: 'Bucket Name', // the S3 bucket the code for the handler lives in
  S3Key: 'Key', // the S3 key for where the handler lives
  Handler: 'index.S3Inventory', // references the handler created in the repository
  Properties: { // Properties here are identical to those in the CloudFormation-native InventoryConfiguration
    BucketRegion: 'us-east-1', // the only additional property required
    Bucket: 'my-bucket',
    Id: 'my-inventory-id',
    InventoryConfiguration: {
      Schedule: { Frequency: 'Daily' },
      IsEnabled: true,
      Destination: {
        S3BucketDestination: {
          Bucket: cf.getAtt('my-inventory-bucket', 'Arn'),
          Format: 'ORC'
        }
      },
      OptionalFields: ['Size', 'LastModifiedDate', 'EncryptionStatus'],
      IncludedObjectVersions: 'Current',
      Id: 'my-inventory-id'
    }
  }
});

Optional Condition

A Condition from your template can also be passed into build. i.e.:

const SpotFleet = magicCfnResources.build({
  CustomResourceName: 'SpotFleet',
  LogicalName: 'Logical Name', // a name to refer to the custom resource being built
  S3Bucket: 'Bucket Name', // the S3 bucket the code for the handler lives in
  S3Key: 'Key', // the S3 key for where the handler lives
  Handler: 'spot-fleet.SpotFleet', // references the handler created in the repository
  Properties: {
    SpotFleetRequestConfigData: { }, // object with SpotFleet configuration specifics
    Region: 'region', // region of the SpotFleet i.e.: 'us-east-1'
  },
  Condition: 'Condition' // the Logical ID of a condition
});

Merge the resources created with build with the resources already in the stack's template:. i.e.:

const cloudfriend = require('@mapbox/cloudfriend');
const magicCfnResources = require('@mapbox/magic-cfn-resources');

module.exports = cloudfriend.merge(SnsSubscription, <Stack Resources>);

To build new functions

Check out contributing.md for a discussion of the framework this library provides for writing other functions.