Nectar of the Programming Masses

    @mapbox/magic-cfn-resources

    1.9.0 • Public • Published

    magic-cfn-resources

    Build Status

    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.

    Keywords

    none

    Install

    npm i @mapbox/magic-cfn-resources

    DownloadsWeekly Downloads

    66

    Version

    1.9.0

    License

    ISC

    Unpacked Size

    516 kB

    Total Files

    26

    Last publish

    Collaborators

    • mapbox-admin
    • mapbox-machine-user
    • mapbox-npm
    • mapbox-npm-01
    • mapbox-npm-02
    • mapbox-npm-03
    • mapbox-npm-04
    • mapbox-npm-05
    • mapbox-npm-06
    • mapbox-npm-07
    • mapbox-npm-08
    • mapbox-npm-09
    • mapbox-npm-advanced-actions
    • mapbox-npm-ci