cfdeployer

    2.2.13 • Public • Published

    CFDeployer

    npm Build Status codecov dependencies Status devDependencies Status JavaScript Style Guide

    Node.js command line tool for deploying Cloudformation templates.

    Only supports deployment into StackSets as this seemed to be a general gap in the community, but may be extended in the future to include regular Stacks.

    Stacksets

    Uploads the referenced Cloudformation in the cfdeploy file to the given bucket and creates/updates the stack set per the given name.

    • For creations, it will create stackset instances per specified targets (AWS account/region)
    • For updates, it will update existing stackset instances first and then remove/create stackset instances per specified targets (AWS account/region)

    The stack set itself is created in the account that it is being run under in the region specified in the AWS config or us-east-1 if a region is not specified.

    Requirements

    • NodeJS 10+
    • Linux/UNIX
    • R/W access to /tmp and template locations

    Installation

    npm install -g cfdeployer

    Usage

    cfdeploy <options>
    Option Description Default (if omitted)
    -f, --file Path to the cfdeploy file cfdeploy.yml
    -d, --direct Skip artifact processing and directly use
    the base template body vs uploading to S3
    Artifacts are uploaded
    -e, --environment Passes environment in an Environment parameter
    to the stack(set) and appends to stack(set) name
    No environment
    Exit Code Description
    0 All deployments successful
    1 1 or more deployments failed

    CFDeploy File Structure and Notes

    • Languages
      • Only YAML is supported.
    • File Naming / Location
      • cfdeploy.yml, placed in the root (like e.g. .travis.yml) for easiest use and recognition
      • Can be named anything and placed wherever, but must specify file option (see above)
    • S3 bucket base just specifies the base. The full bucket name is as follows:
      • No environment provided: --
      • Environment provided: ---
    • Cloudformation Template Restrictions
      • Template must be YAML
    deployments:
      - 
        type: stackSet
        name: <name of stackset/deployment>
        templatePath: <path to Cloudformation template>
        adminS3Bucket: <S3 bucket name for the administrator account. The base template is placed here. -[environment] is appended if an environment is provided>
        adminS3Prefix: <S3 prefix (with or without trailing slash) in the adminS3Bucket where the uploaded base template is placed. e.g. thisIs/aPrefix/>
        targetsS3BucketBase: <S3 bucket base used to create the full bucket names where the base template artifacts are uploaded to>
        targetsS3Prefix: <S3 prefix (with or without trailing slash) in the targets S3 Buckets where the template artifacts are placed. e.g. thisIs/aPrefix/ >
        targets:
          <AWS account number or "default" for current user's AWS account number>:
            <region 1>: true
            <region 2>: true
            ...Additional regions as needed
          ...Additional AWS account numbers with regions as needed
      -
        ...Additional deployments as needed

    Breaking change from 1.x to 2.x: s3Bucket and s3Prefix have been removed and replaced with the adminS3Bucket/targetsS3BucketBase and adminS3Prefix/targetsS3Prefix settings

    Automatic Artifact Upload

    Similar to the Cloudformation CI package command, CFDeployer automatically uploads locally referenced artifacts to the S3 bucket and prefix specified in the CFDeploy file. It supports all of the resource types that the package command supports, except types that are not supported in stack sets. It packages the artifact as appropriate to the resource type (e.g. if zipping is required as for Lambda Function resources). Folders will be automatically zipped.

    Nested stacks are supported. The resource name name of the nested stack is used to construct the path.

    S3 key limitations of 1024 bytes apply, so be sure to avoid very long resource and/or file names.

    Uploaded Artifact S3 Key Structure

    Template Files

    <prefix>/<nested paths (if any)>/<template file name>/<256 bit file hash>/<template file name>
    s3Prefix/template.yml/0ff5ef46180f4430eaa816fb239b4f3fc4c06db8f246e90a7c444ee25016e29d/template.yml - base or non-nested template
    s3Prefix/_nestedStack1/_nestedNestedStack1/template.yml/0ff5ef46180f4430eaa816fb239b4f3fc4c06db8f246e90a7c444ee25016e29d/template.yml - nested template
    

    Non-Template Files

    <prefix>/<nested paths (if any)>/<resource service>/<resource service type>/<file or directory name>/<256 bit file hash>/<file or zipped directory name>
    s3Prefix/lambda/function/index.js/0ff5ef46180f4430eaa816fb239b4f3fc4c06db8f246e90a7c444ee25016e29d/index.js.zip - file in non-nested template
    s3Prefix/lambda/function/codeDirectory/0ff5ef46180f4430eaa816fb239b4f3fc4c06db8f246e90a7c444ee25016e29d/codeDirectory.zip - directory in non-nested template
    s3Prefix/_nestedStack1/_nestedNestedStack1/lambda/function/codeDirectory/0ff5ef46180f4430eaa816fb239b4f3fc4c06db8f246e90a7c444ee25016e29d/codeDirectory.zip - file in nested template
    

    Contributing

    I welcome pull requests, especially for bugfixes, and issue submissions. Please reach out if a larger feature is being considered so we can discuss prior to a PR.

    License

    MIT

    Install

    npm i cfdeployer

    DownloadsWeekly Downloads

    20

    Version

    2.2.13

    License

    MIT

    Unpacked Size

    166 kB

    Total Files

    60

    Last publish

    Collaborators

    • avatar
    • avatar