cloudmason 0.0.1 → 1.0.2

package/.github/workflows/CODEOWNERS

@@ -0,0 +1 @@
+*   @kai-harvey

package/.github/workflows/main.yml

@@ -1,27 +1,27 @@
-name: Node.js Package
-
-on:
-  pull_request:
-    types:
-      - closed
-    branches:
-      - 'release/**'
-
-jobs:
-  if_merged:
-    if: github.event.pull_request.merged == true
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
-        with:
-          node-version: 16
-          registry-url: https://registry.npmjs.org/
-      - run: npm run build
-        env: 
-          branch: ${{ github.base_ref }}
-          build: ${{ github.run_number }}
-      - run: npm ci
-      - run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{secrets.npm_token}}
+name: Publish Node.js Package
+
+on:
+  pull_request:
+    types:
+      - closed
+    branches:
+      - 'release/**'
+
+jobs:
+  if_merged:
+    if: github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 16
+          registry-url: https://registry.npmjs.org/
+      - run: npm run build
+        env: 
+          branch: ${{ github.base_ref }}
+          build: ${{ github.run_number }}
+      - run: npm ci
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

package/README.md

@@ -1,25 +1,373 @@
-# Introduction 
-TODO: Give a short introduction of your project. Let this section explain the objectives or the motivation behind this project. 
-
-## Sub Introduction
-
-### Sub2 Introduction
-
-
-# Getting Started
-TODO: Guide users through getting your code up and running on their own system. In this section you can talk about:
-1.	Installation process
-2.	Software dependencies
-3.	Latest releases
-4.	API references
-
-# Build and Test
-TODO: Describe and show how to build your code and run the tests. 
-
-# Contribute
-TODO: Explain how other users and developers can contribute to make your code better. 
-
-If you want to learn more about creating good readme files then refer the following [guidelines](https://docs.microsoft.com/en-us/azure/devops/repos/git/create-a-readme?view=azure-devops). You can also seek inspiration from the below readme files:
-- [ASP.NET Core](https://github.com/aspnet/Home)
-- [Visual Studio Code](https://github.com/Microsoft/vscode)
-- [Chakra Core](https://github.com/Microsoft/ChakraCore)
+Set up an AWS organization from scratch and deploy a static site or AMI-based EC2 application in just 4 commands.
+
+The tool will handle everything from obtaining ACM certificates to building AMIs and deploying cloudformation stacks.
+
+Can be used as a command line tool, or in a CI/CD pipeline.
+
+## Contents
+- [Quick Start](##quick-start)
+- [Important Notes](##important)
+- [Commands](##commands)
+
+
+
+## Quick Start
+
+Get an Ec2 nodejs app up and running in 4 commands.
+
+1. **Prereqs**
+      1. Open an AWS account
+      2. Download and set up the AWS CLI (or just set your AWS credentials with enviroment variables)
+      3. Buy a domain to deploy apps to
+      4. Run the following command to set up your org: 
+         - `init-org -name MyOrg -region us-east-1`
+2. **Set up a Local App Template**
+      1. Get a sample nodejs app template: 
+         - `mason starter -p ./myDesktop/MyFirstApp -type asg`
+3. **Add an App**
+```
+mason new-app -name MyFirstApp -type asg
+mason new-instance -app MyFirstApp -domain myfirstapp.com -region us-east-2 -admin me@gmail.com
+mason update-app -app MyFirstApp -v 1.0 -path ./myDesktop/HelloWorld
+mason list-apps
+```
+4.  **Launch it**
+```
+mason launch -app MyFirstApp -v 1.0 -domain myfirstapp.com
+mason inspect -app MyFirstApp -domain myfirstapp.com -boot
+```
+5. **Review It**
+      1. Visit the domain you specified. You'll see a login page.
+      2. Check the email address you specified for a temp password. Use it to log in.
+      3. After logging in, you'll see a "Hello World" page.
+
+#### All Together
+
+```
+init-org -name MyOrg -region us-east-1
+mason starter -p ./myDesktop/MyFirstApp -type asg
+mason new-app -name MyFirstApp -type asg
+mason new-instance -app MyFirstApp -domain myfirstapp.com -region us-east-2 -admin me@gmail.com
+mason update-app -app MyFirstApp -v 1.0 -path ./myDesktop/MyFirstApp
+mason launch -app MyFirstApp -v 1.0 -domain myfirstapp.com
+mason inspect -app MyFirstApp -domain myfirstapp.com -boot
+```
+
+
+## IMPORTANT!!!
+
+- THIS APP DEPLOYS EC2 INSTANCES THAT ARE NOT FREE! IT WILL RESULT IN AWS CHARGES!
+- Make sure to run `delete-instance` when you're done to avoid major surprises
+- update-app will build an AMI, which may not be immediately available. Leave a few minutes between running update-app and launch
+- Your web application must serve on localhost:8080
+- Use `inspect` ! It will return all console output of your application - very useful for debugging
+
+
+
+
+
+# Commands
+
+Run `mason [command] -<options>`
+
+| Command      | Description                     |
+| ---------------------------- | ------------------------------ |
+| [init-org](###init-org)                 | Set up a new organization                           |
+| [set-org](###set-org)                   | Set default org to an existing org                  |
+| [new-app](###new-app)                   | Create a new application                            |
+| [new-instance](###new-instance)         | Create a new instance of an application             |
+| [update-app](###update-app)             | Update the code and/or stack of an app version      |
+| [launch](###launch)                     | Deploy an app version to an instance                |
+| [inspect](###inspect)                   | Get cloudformation stack status and boot logs for an instance |
+| [starter](###starter)                   | Get a starter template for a specified architecture type      |
+| [delete-instance](###delete-instance)   | Delete an instance                                  |
+| [delete-app](###delete-app)             | Delete an app                                       |
+| [update-stack](###update-stack)         | Update cloudformation stack                          |
+| [list-apps](###list-apps)               | List all apps                                       |
+
+
+
+### init-org
+
+
+`mason init-org -name -domain -region `
+
+Sets up base infrastructure in a new AWS organization. This command should only be run once. To set up the tool with an existing org, use set-org.
+
+|   Parameter    | Required     |  Type                 | Description                   |
+| -------------- | ------------ | ----------------      | ----------------------------  |
+| **name**           |   Y          |  String               |  Unique org Name. Letters only, no spaces   |
+| **domain**      | Y | Valid domain | A base domain to use for core resources (e.g., cmason.io) |
+| **region** | Y | AWS Region | Default AWS region for core resources (e.g., us-east-1) |
+
+
+#### What it does
+
+1. Retrieves the default VPC ID
+2. Deploys a basic org infra stack
+      1. S3 Bucket + policies for infra resources at `infra.[domain]`
+      2. IAM Role, Instance Profile, and Security Group for Ec2 build agent
+      3. SSM Parameters for oprg name, domain, instance profile, and security group
+
+
+
+
+### new-app
+
+`mason new-app -name -type -node -py`
+
+#### Params
+
+|   Parameter    | Required     |  Type                 | Description                   |
+| -------------- | ------------ | ----------------      | ----------------------------  |
+| **name** | Y | String | Application name. Letters only |
+| **type** | Y | Application Type | (Application architecture)[##Architectures]. See below for options. |
+| node | n | Number | Version of nodejs to install on the base AMI. If set, app will run using nodejs |
+| py | n | Number | Version of python to install on the base AMI. If set, app will run using python |
+
+
+**Architecture Options**
+
+- asg: autoscaling group 
+- static: static site
+
+#### Examples
+
+```
+mason new-app -name MyFirstApp -type asg -node
+```
+
+#### What it does
+
+1. Builds a cloudformation stack with the appropriate boot script for nodejs or python
+2. Uploads the cloudformation template to the S3 infrastructure bucket
+3. Records the app name, type, and other key detail in SSM params
+
+
+
+
+### new-instance
+
+`mason new-instance -app -name -domain -region -admin -max -ins -env`
+
+Creates a new instance in a specified region. An instance is a deployment of an application. For example, MyFirstApp could have a test, UAT, and prod instance in us-east-1,us-east-2,and us-west-1.
+
+Use -admin to specify the first admin user who will have access to set up other users.
+
+#### Params
+
+|   Parameter    | Required     |  Type                 | Description                   |
+| -------------- | ------------ | ----------------      | ----------------------------  |
+| **app** | Y | string | Name of existing application |
+| **name** | Y | string | Instance name (ex., test, uat, etc). Letters only |
+| **domain** | Y | string | Name of a subdomain or domain to deploy behind |
+| **region** | Y | AWS region | region to deploy the instance in |
+| **admin** | Y | email | email adress of first admin user |
+| max | N | int | Maximum number of Ec2 instance to allow in the ASG. Higher number will result in better performance but possibly higher charges. Minimum is 2 to allow for proper refresh. |
+| ins | N | string | Ec2 instance type. Default is t3.small |
+| env | N | string | Enviroment (dev,test,prod). This value will be passed to the application. |
+
+
+#### Examples
+
+```
+mason new-app -name MyFirstApp -type asg -node
+mason new-instance -app MyFirstApp -name uat -domain test.cmason.io -region us-east-2
+mason new-instance -app MyFirstApp -name beta -domain beta.cmason.io -region us-west-1
+```
+
+
+#### What it does
+
+1. Requests an ACM certificate for the domain if none exists (for HTTPS)
+2. Gets the default VPC ID and Subnets for the target region
+3. Saves deployment params to SSM for use when deploying the cloud formation template:
+      1. ACM Certificate ID
+      2. VPC Id
+      3. Subnets and hosted zone ID
+
+
+
+### update-app
+
+`mason update -app -v -path`
+
+Updates the code for the specified application. This command will build a new AMI and update cloudformation stacks to point to the new AMI.
+Path must lead to the root folder of your application. The bootscript will run with that directory as the root.
+
+#### Params
+
+|   Parameter    | Required     |  Type                 | Description                   |
+| -------------- | ------------ | ----------------      | ----------------------------  |
+| **app** | Y | string | Name of the existing app to update |
+| **v** | Y | number | Version number to update |
+| **path** | Y | Path to a folder or zip file containing the updated app code |
+
+
+#### Examples
+
+```
+mason update -app MyFirstApp -v 1.1 -path ./myfirstapp/src -stack ./myfirstapp/stack.json
+```
+
+#### What it does
+
+1. Zips the folder (if not already zipped)
+2. Updates the cloudformation stack.yml file and uploads to S3
+3. Identifies the appropriate AWS Linux AMI ID for the base region
+4. Launches an EC2 instance, waits until it's ready, and then builds an AMI with the updated code package
+5. Terminates the EC2 instance
+6. Updates SSM with the updated AMI ID and build number
+
+
+
+
+### launch
+
+`mason launch -app -v -i`
+
+Launches a specific version of an application to an instance. For example, launch (deploy) MyFirstApp version 1.2 to test.cmason.io.
+
+
+#### Params
+
+|   Parameter    | Required     |  Type                 | Description                   |
+| -------------- | ------------ | ----------------      | ----------------------------  |
+| **app** | Y | string | Name of existing application to launch |
+| **v** | Y | number | Version of the app to launch |
+| **i** | Y | string | Name of the instance to deploy to | 
+
+
+#### Examples
+
+```
+mason new-instance -app MyFirstApp -name uat -domain test.cmason.io -region us-east-2
+mason update -app MyFirstApp -v 1.1 -path ./myfirstapp/src -stack ./myfirstapp/stack.jso
+mason launch -app MyFirstApp -v 1.1 -i uat
+```
+
+
+#### What it does
+
+1. Copies the AMI version created in the `update` command to the instance region
+2. Deploys the updated cloudformation stack
+
+
+
+### update-stack
+
+`mason update-stack -app -v -default -stack`
+
+Updates the default cloudformation template, or updates the template for a specific version.
+
+#### Params
+
+|   Parameter    | Required     |  Type                 | Description                   |
+| -------------- | ------------ | ----------------      | ----------------------------  |
+| **app** | Y | string | Name of the app to update  |
+| **stack**  | Y | path | File path to updated cloudformation template | 
+| -v | N | number | Version number to update. Leave blank to update the default template |
+| -default | flag | Include this flag to update the default cloudformation template for the app |
+
+
+#### Examples
+
+Update version 5 with a new stack
+
+```
+mason update-stack -app MyFirstApp -v 1.0 -stack ../myfirstapp/stack.json
+```
+
+Update the default cloduformation template for all future versions
+
+```
+mason update-stack -app MyFirstApp -default -stack ../myfirstapp/stack.json
+```
+
+#### What it does
+
+1. Uploads the specified stack file to S3
+
+
+
+### inspect
+
+`mason inspect -app -domain [-run or -boot]`
+
+Get stack status and EC2 console logs for an instance.
+Useful for debugging issues with application boot up. Console output will 
+
+To get run logs, the application must write logs to S3 in the logs/run folder. See the starter nodejs app for an example. 
+
+#### Params
+
+|   Parameter    | Required     |  Type                 | Description                   |
+| -------------- | ------------ | ----------------      | ----------------------------  |
+| **-app** | Y | string | App name |
+| **-domain** | Y | string | Domain to inspect | 
+| -boot | N | null | If included, returns logs from the instance start up | 
+| -run | N | null | If included, returns run logs stored by the application in the s3 bucket at logs/run/* | 
+
+#### Examples
+
+```
+mason inspect -app MyFirstApp -domain myfirstapp.com
+```
+
+
+### starter
+
+`mason starter -type -l -path`
+
+Sets up a starter application template for the specified architecture and language
+
+#### Params
+
+|   Parameter    | Required     |  Type                 | Description                   |
+| -------------- | ------------ | ----------------      | ----------------------------  |
+| **-type** | Y | string | Architecture of the application (asg, static, etc) |
+| **-p** | Y | string | Path to output the project to |
+| -l | Y | string | Language. py or node | 
+
+#### Examples
+
+```
+mason starter -type asg -l node -path ../myfirstapp
+```
+
+
+
+
+
+## TODO
+
+- [x] Run logs 
+- [x] Read token
+- [x] Verify token
+- [x] Get user groups
+- [x] DDB connect
+- [x] Fix starter routes
+- [x] Add arguments for max ec2 instance and instance type
+- [X] Customize boot script
+- [x] Secure param permissions
+- [X] Pass node/py versions
+- [X] Pass version info to instance
+- [X] Fix Delete App
+- [X] Update default instance
+- [X] Pass Env to instance
+- [] Custom SES Config
+- [X] Fix logs
+- [] Add dev
+- [] Add Admin
+- [] Cloudtrails
+- [] Static site
+- [] Deregistering in home region
+- [] cf-templates s3 bucket creation
+
+## OPEN ITEMS
+
+- Custom auth domain
+    - AWS requires ACM cert in us-east-1 for custom Cognito auth domain. Cloudformation does not allow for cross-region resource creation
+    - [Github AWS Issue](https://github.com/aws-cloudformation/cloudformation-coverage-roadmap/issues/523)
+
+

package/build.js

@@ -1,21 +1,21 @@
-const fs = require('fs');
-
-const pckg = JSON.parse(fs.readFileSync('./package.json'));
-
-const branch = process.env.branch;
-const build = process.env.build;
-
-console.log(`Branch: ${branch}`);
-console.log(`Build: ${build}`);
-
-const branchParts = branch.split('/');
-const lastPart = branchParts[branchParts.length - 1];
-const majorVersion = lastPart.replaceAll(/[^0-9\.]/g, '');
-
-const version = `${majorVersion}.${build}`;
-
-pckg.version = version;
-
-console.log(`Version: ${version}`);
-
+const fs = require('fs');
+
+const pckg = JSON.parse(fs.readFileSync('./package.json'));
+
+const branch = process.env.branch;
+const build = process.env.build;
+
+console.log(`Branch: ${branch}`);
+console.log(`Build: ${build}`);
+
+const branchParts = branch.split('/');
+const lastPart = branchParts[branchParts.length - 1];
+const majorVersion = lastPart.replaceAll(/[^0-9\.]/g, '');
+
+const version = `${majorVersion}.${build}`;
+
+pckg.version = version;
+
+console.log(`Version: ${version}`);
+
 fs.writeFileSync('./package.json', JSON.stringify(pckg));

package/commands/delete.js

@@ -1,29 +1,68 @@
-const CF = require('./helpers/cf');
-const Params = require('./helpers/params');
-
-
-exports.delete_instance = async function(args){
-    // Get App
-    const app = await Params.getApp(args.app);
-    if (!app){
-        console.log('Err: No app named ' + args.app);
-        throw new Error('Err: No app named ' + args.app)
-    }
-    //  Get Instance
-    const targetInstance = app.instances.find(ins=>{ return ins.name.toLowerCase() == args.i.toLowerCase() });
-    if (!targetInstance){ console.log(`No instance of ${args.app} named ${args.i}`); throw new Error('Invalid Instance')}
-    
-    //  Delete Stack
-    const stackName = (`${args.app}-${args.i}`).toLowerCase();
-    console.log(`Deleting ${args.app} instance ${args.i} in ${targetInstance.region}`)
-    const delOK = await CF.delete(stackName, targetInstance.region);
-    if (delOK){
-        console.log('Delete Successful')
-    } else {
-        return;
-    }
-
-    //  Update Params
-    await Params.deleteInstance(args.app,args.i);
-    return true;
+const CF = require('./helpers/cf');
+const Params = require('./helpers/params');
+const S3 = require('./helpers/s3');
+const Common = require('./helpers/common');
+
+exports.delete_app = async function(args){
+    // Get App
+    const app = await Params.getApp(args.app);
+    if (!app){
+        console.log('Err: No app named ' + args.app);
+        throw new Error('Err: No app named ' + args.app)
+    }
+    //  Check Instances
+    if (app.instances.length > 0){
+        console.log('Err: App has instances. Delete instances first');
+        throw new Error('Err: App has instances. Delete instances first')
+    }
+
+    // Delete S3 Files
+    console.log('Deleting S3 Content for ' + args.app)
+    await S3.deleteAppFolder(args.app);
+
+    // Deregister AMIs
+    await Common.remove_app_amis(args.app,process.env.orgRegion);
+
+    //  Update Params
+    console.log('Updating SSM Params')
+    await Params.deleteApp(args.app);
+    console.log('Succesfully Deleted ' + args.app)
+    return true;
+}
+
+exports.delete_instance = async function(args){
+    // Get App
+    const app = await Params.getApp(args.app);
+    if (!app){
+        console.log('Err: No app named ' + args.app);
+        throw new Error('Err: No app named ' + args.app)
+    }
+    //  Get Instance
+    const targetInstance = app.instances.find(ins=>{ return ins.domain.toLowerCase() == args.domain.toLowerCase() });
+    if (!targetInstance){ console.log(`No instance of ${args.app} named ${args.domain}`); throw new Error('Invalid Instance')}
+    
+    // Check if Stack Exists
+    const stackExists = await CF.stackExists(targetInstance.stackName,targetInstance.region);
+    console.log(`Stack Exists: ${stackExists}`)
+    if (stackExists === true){
+        // Delete S3 App Bucket
+        const bucketName = await CF.getStackResource('s3',targetInstance.stackName,targetInstance.region);
+        console.log('Emptying S3 Bucket for ' + bucketName)
+        await S3.emptyBucket(bucketName,targetInstance.region);
+        //  Delete Stack
+        const stackName = targetInstance.stackName;
+        console.log(`Deleting ${args.app} instance ${args.domain} in ${targetInstance.region}`)
+        const delOK = await CF.delete(stackName, targetInstance.region);
+        if (delOK){
+            console.log('Delete Successful')
+        } else {
+            return;
+        }
+        // Deregister AMIs
+        await Common.prune_amis(args.app,targetInstance.version,targetInstance.region,true);
+    }
+
+    //  Update Params
+    await Params.deleteInstance(args.app,args.domain);
+    return true;
 }