To install:

npm install -g @unbill\aws-tools

Universal command line options

The following parameters can be applied to any command

--region -r - Specify region other than your default AWS settings

--profile -P - (large P) Specify profile other than your default AWS profile

--destroy -d - Destroy the resource instead of creating/updating it

Commands

cloudfront-website

Creates a cloudfront website with failover

Creates an S3 bucket in two different regions (primary and secondary). Creates a CloudFront distro that fails over from the primary S3 bucket to the secondary S3 bucket Creates a Route 53 entry for the Cloudfront distro

To run in build mode (upsert assets)

aws-tools cf-web -p ./path/to/params.json

or

aws-tools cf-web --parameters ./path/to/params.json

other cf-web aliases that can be used: cloudfront-website or cfw

To run in destroy mode (delete all assets)

aws-tools cf-web -p ./path/to/params.json -d

or

aws-tools cf-web -p ./path/to/params.json --destroy

Sample Params.json File

A sample is available in ./samples/cloudfront-website/testparams.json

[
  {
    "ParameterKey": "ProductName",
    "ParameterValue": "biller-direct"
  },
  {
    "ParameterKey": "DomainPrefix",
    "ParameterValue": "test-"
  },
  {
    "ParameterKey": "HostedZoneName",
    "ParameterValue": "unbill.io"
  },
  {
    "ParameterKey": "AccountId",
    "ParameterValue": "211130626593"
  },
  {
    "ParameterKey": "CertificateId",
    "ParameterValue": "506c69f6-4af0-4ca5-907a-0003f3c59316"
  },
  {
    "ParameterKey": "UpdateCloudFront",
    "ParameterValue": false
  }
]

• ProductName - Used in a variety of name building scenarios, basically the name of the website product you are deploying
• DomainPrefix - Added to the front of your domain and other naming locations, typically for different environments (staging/test/sandbox etc...)
• HostedZoneName - The hosted zone in Route 53 to setup the DNS entry
• AccountId - ID of the AWS account to deploy to
• CertificateId - ID of the certificate to use for DNS registration
• UpdateCloudFront - If CloudFront exists, it is not normally updated for latency reasons. This flag forces an update.

ec2-ssh-key

Imports an EC2 SSH public key into AWS

To run in build mode (upsert assets)

aws-tools ec2-ssh-key -p ./path/to/params.json

or

aws-tools ssh --parameters ./path/to/params.json

ec2-ssh-key aliases that can be used: ec2-ssh, ssh-key or ssh

To run in destroy mode (delete the key)

aws-tools ssh -p ./path/to/params.json -d

or

aws-tools ssh-key -p ./path/to/params.json --destroy

Sample Params.json File

A sample is available in ./samples/ec2-ssh-key/testparams.json

[
  {
    "ParameterKey": "KeyName",
    "ParameterValue": "unbill-dev"
  },
  {
    "ParameterKey": "Replace",
    "ParameterValue": false
  }
]

• KeyName - Name of the key to perform operations on
• Replace - Indicates that key should be replaced if it is present

secrets-manager

Imports values into the AWS secrets manager. The values to be imported must be available as environment variables. Typically, these would be stored as settings in TravisCI.

To run in build mode (upsert assets)

aws-tools secrets-manager --environment STAGING --region AWS_REGION

or

aws-tools secrets --environment STAGING --region AWS_REGION

secrets-manager aliases that can be used: secrets

To run in destroy mode (delete the secrets)

aws-tools secrets --environment STAGING -d --region AWS_REGION

or

aws-tools secrets --environment STAGING --destroy --region AWS_REGION

• environment - The environment that keys should be imported from
• prefix - The assumption is that all secrets to be uploaded will begin with AWSPARAM, if you wish to change this prefix, us this parameter

params-manager

Imports values into the AWS ssm parameter manager. The values to be imported must be available as environment variables. Typically, these would be stored as settings in TravisCI.

To run in build mode (upsert assets)

aws-tools params-manager --environment STAGING --region AWS_REGION

or

aws-tools params --environment STAGING --region AWS_REGION

params-manager aliases that can be used: params

To run in destroy mode (delete the params)

aws-tools params --environment STAGING -d --region AWS_REGION

or

aws-tools params --environment STAGING --destroy --region AWS_REGION

• environment - The environment that keys should be imported from
• prefix - The assumption is that all secrets to be uploaded will begin with AWSPARAM, if you wish to change this prefix, us this parameter

ssm-param

Imports an EC2 SSH public key into AWS

To run in build mode (upsert assets)

aws-tools ec2-ssh-key -p ./path/to/params.json

or

aws-tools ssh --parameters ./path/to/params.json

ec2-ssh-key aliases that can be used: ec2-ssh, ssh-key or ssh

To run in destroy mode (delete the key)

aws-tools ssh -p ./path/to/params.json -d

or

aws-tools ssh-key -p ./path/to/params.json --destroy

Sample Params.json File

A sample is available in ./samples/ec2-ssh-key/testparams.json

[
  {
    "ParameterKey": "KeyName",
    "ParameterValue": "unbill-dev"
  },
  {
    "ParameterKey": "Replace",
    "ParameterValue": false
  }
]

• KeyName - Name of the key to perform operations on
• Replace - Indicates that key should be replaced if it is present

s3-replica-set

Creates an S3 bucket with failover to a secondary bucket

Creates an S3 bucket in two different regions (primary and secondary). Sets up replication from the primary to the secondary

To run in build mode (upsert assets)

aws-tools s3-replica-set -p ./path/to/params.json

or

aws-tools s3-set --parameters ./path/to/params.json

other s3-replica-set aliases that can be used: s3-set or s3-replica

To run in destroy mode (delete all assets)

aws-tools s3-replica-set -p ./path/to/params.json -d

or

aws-tools s3-replica -p ./path/to/params.json --destroy

Sample Params.json File

A sample is available in ./samples/s3-replica-set/testparams.json

[
   {
    "ParameterKey": "ProductName",
    "ParameterValue": "consumer-logs"
  },
  {
    "ParameterKey": "DomainPrefix",
    "ParameterValue": "test-"
  },
  {
    "ParameterKey": "HostedZoneName",
    "ParameterValue": "unbill.io"
  },
  {
    "ParameterKey": "AccountId",
    "ParameterValue": "211130626593"
  },
  {
    "ParameterKey": "ReplicationRole",
    "ParameterValue": "bdcs-s3-replication"
  },
  {
    "ParameterKey": "ForceDelete",
    "ParameterValue": false
  }
]

• ProductName - Used in a variety of name building scenarios, basically the root name of the bucket you are deploying
• DomainPrefix - Added to the front of your bucket and other naming locations, typically for different environments (staging/test/sandbox etc...)
• HostedZoneName - The hosted zone in Route 53 to setup the DNS entry
• AccountId - ID of the AWS account to deploy to
• ReplicationRole - AWS role used to perform replication. This must be set up beforehand.
• ForceDelete - When deleting, if this is true, all bucket contents will be deleted automatically instead of preventing deletion (be careful)

rds-global

Creates an Aurora MySQL Global database cluster across two regions (us-east-1 and us-west-2)

To run in build mode (upsert assets)

aws-tools rds-global -p ./path/to/params.json --username admin --password password

or

aws-tools rds --parameters ./path/to/params.json --username admin --password password

other rds-global aliases that can be used: rds

To run in destroy mode (delete all assets)

aws-tools rds-global -p ./path/to/params.json -d --username admin --password password

or

aws-tools rds -p ./path/to/params.json --destroy --username admin --password password

Sample Params.json File

A sample is available in ./samples/s3-replica-set/testparams.json

[
   {
    "ParameterKey": "Environment",
    "ParameterValue": "staging"
  },
  {
    "ParameterKey": "AccountId",
    "ParameterValue": "211130626593"
  },
  {
    "ParameterKey": "DatabaseName",
    "ParameterValue": "ALTR"
  },
  {
    "ParameterKey": "DbInstanceClass",
    "ParameterValue": "db.r4.large"
  },
  {
    "ParameterKey": "DeletionProtection",
    "ParameterValue": false
  },
  {
    "ParameterKey": "BackupRetentionDays",
    "ParameterValue": 5
  },
  {
    "ParameterKey": "DbKmsKeyAlias",
    "ParameterValue": "unbill-db"
  },
  {
    "ParameterKey": "Port",
    "ParameterValue": 3306
  },
  {
    "ParameterKey": "PubliclyAccessible",
    "ParameterValue": true
  },
  {
    "ParameterKey": "InstancesPerRegion",
    "ParameterValue": 2
  }
]

• Environment - Used when setting up database naming (ex: prod, dev)
• AccountId - ID of the AWS account to deploy to
• DatabaseName - Name of the database to create (on cluster creation)
• DbInstanceClass - Class of database instances to create (see AWS documentation, smallest valid size is db.r4.large)
• DeletionProtection - Are the clusters protected from deletion (does not apply to instances)
• BackupRetentionDays - Length of DB backup retention
• DbKmsKeyAlias - The KMS key used to encrypt the database
• Port - Port DB is accessed from
• PubliclyAccessible - Is this database publicly accessible
• InstancesPerRegion - The number of instances that are created in each region