add example

sat-utils · Jul 19, 2018 · 68a6188 · 68a6188
1 parent ec9bf75
commit 68a6188
Show file tree

Hide file tree

Showing 8 changed files with 361 additions and 13 deletions.
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -27,4 +27,16 @@ jobs:
       - run:
           name: Build Documentation
           command: |
-            yarn docs-build
+            if [[  "$CIRCLE_BRANCH" == 'master' ]]; then
+              yarn docs-build
+            fi
+      
+      - run:
+          name: Deploy example to aws
+          command: |
+            if [[  "$CIRCLE_BRANCH" == 'master' ]]; then
+              cd example
+              yarn
+              ./node_modules/.bin/kes cf deploy --template node_modules/@sat-utils/api/template --deployment dev --region us-east-1 --role arn:aws:iam::552819999234:role/sat-api-deployer-role-DeployerRole-JBBKUABAELDR
+            fi
+
diff --git a/.gitignore b/.gitignore
@@ -3,7 +3,7 @@ dist
 .env
 build
 dist
-.kes/cloudformation.yml
+cloudformation.yml
 ddd.js
 package-lock.json
 yarn.lock

diff --git a/README.md b/README.md
@@ -28,17 +28,6 @@ Access the documenation [here](docs) or on [gitbook](https://sat-utils.gitbook.i
 
     $ yarn docs-serve
 
-## Use Unreleased Version in Deployed Instances
-
-If you need to use the latest code on the master branch that is not released to npm yet, or if you need to do live development on an instance deployed to AWS (not recommended), you should follow these steps:
-
-- Clone this repo and install requirements ([follow](#local-installation))
-- Run: `yarn linkall` (this will link packages to your local npm).
-- In the deployment repository (e.g. [sat-api-deployment](https://github.com/sat-utils/sat-api-deployment#deploy-an-instance)) run the link command with the package name you are using:
-    - `yarn link @sat-utils/api`
-- Verify packages are linked: `ls -la node_modules/@sat-utils`
-    - This show an output similar to: `lrwxr-xr-x 1 user staff 29 Jul 11 14:19 api -> ../../../sat-api/packages/api`
-
 ## Deployment
 
 To create a new version for npm:

diff --git a/example/.kes/config.yml b/example/.kes/config.yml
@@ -0,0 +1,22 @@
+default:
+  stackName: change-me
+  system_bucket: change-me
+
+  tags:
+    project: sat-api
+
+dev:
+  stackName: sat-api-v1-dev
+  system_bucket: sat-api 
+  es:
+    instanceCount: 2
+    instanceType: m3.medium.elasticsearch
+    volumeSize: 80
+
+prod:
+  stackName: sat-api-v1
+  system_bucket: sat-api 
+  es:
+    instanceCount: 2
+    instanceType: m3.medium.elasticsearch
+    volumeSize: 80
diff --git a/example/README.md b/example/README.md
@@ -0,0 +1,72 @@
+# Example sat-api Deployment
+
+This deployment powers https://sat-api.developmentseed.org/search. We use [kes](https://www.npmjs.com/package/kes) to deploy sat-api as an application to AWS.
+
+For the deployment to work we use a kes template included in the [@sat-utils/api](https://www.npmjs.com/package/@sat-utils/api) package. This package has all the necessary resources needed for a successful deployment of sat-api.
+
+You can override all the configurations and options in this template by adding override files to the `.kes/config.yml` folder.
+
+## Install
+
+     $ yarn install
+
+## Deploy with unpublished code
+
+If you need to use the latest code on the master branch that is not released to npm yet, or if you need to do live development on an instance deployed to AWS (not recommended), you should follow these steps:
+
+- Clone this repo and install requirements ([follow](../README.md#local-installation))
+- At the repo root run: `yarn linkall` (this will link packages to your local npm).
+- In the deployment repository (e.g. `example` folder) run the link command with the package name you are using:
+    - `yarn link @sat-utils/api`
+    - In the `example` folder we have included a shortcut: `yarn linkall`
+- Verify packages are linked: `ls -la node_modules/@sat-utils`
+    - This show an output similar to: `lrwxr-xr-x 1 user staff 29 Jul 11 14:19 api -> ../../../sat-api/packages/api`
+
+To restore packages from npm just run `yarn`.
+
+## Deploy an instance
+
+Make sure the you add a deployment to `.kes/config.yml` by adding the following to the file:
+
+```yaml
+name-of-my-deployment:
+  stackName: <name-of-my-stack>
+  system_bucket: <a s3 bucket I have access to>
+```
+
+Then run this command:
+
+     $ ./node_modules/.bin/kes cf deploy --region us-east-1 --profile <profile-name> --template node_modules/@sat-utils/api/template --deployment <name-of-mystack> --showOutputs
+
+The command will return the api endpoint that is created by the operation.
+
+### Deploy Devseed's Dev stack
+
+This command only works if you have access to Devseed's AWS account
+
+     $ ./node_modules/.bin/kes cf deploy --region us-east-1 --template node_modules/@sat-utils/api/template --deployment dev --profile <replace-me> --showOutputs
+
+### Deployer Role
+
+For the CI environment, we use a special IAM role that is assumed by an AWS user. This will allow us to give limited access to the user that is used inside the CI build environment.
+
+To create the deployer role run:
+
+     $ ./node_modules/.bin/kes cf deploy --kes-folder deployer --profile ds --region us-east-1 --showOutputs
+
+Then create a user on AWS and give it this policy permission. Replase the value of the resource with the output of the previous command:
+
+```json
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Effect": "Allow",
+            "Action": "sts:AssumeRole",
+            "Resource": "<arn:DeployerRole>"
+        }
+    ]
+}
+```
+
+When running the deployment command make sure to [include the `--role` flag](.circleci/config.yml#L17).
diff --git a/example/deployer/cloudformation.template.yml b/example/deployer/cloudformation.template.yml
@@ -0,0 +1,221 @@
+# Sets up an IAM role that mimics NGAP so we can test during local development to see what fails and
+# what doesn't
+Description: Deployer IAM Role for sat-api (used in CI enviornment)
+Parameters:
+  Prefix:
+    Type: String
+    Description: The prefix used for resources in the application
+Resources:
+  DeployerRole:
+    Type: AWS::IAM::Role
+    Properties:
+      AssumeRolePolicyDocument:
+        Version: '2012-10-17'
+        Statement:
+        - Effect: Allow
+          Principal:
+            AWS: !Sub ${AWS::AccountId}
+          Action:
+          - sts:AssumeRole
+      Path: "/"
+      Policies:
+      - PolicyName: DeployerRolePolicy
+        PolicyDocument:
+          Version: '2012-10-17'
+          Statement:
+            - Effect: Allow
+              Action:
+              - cloudformation:*
+              Resource:
+              - "*"
+
+            - Effect: Allow
+              Action:
+              - ec2:CreateSecurityGroup
+              - ec2:Describe*
+              - ec2:DeleteSecurityGroup
+              - ec2:RevokeSecurityGroupEgress
+              - ec2:AuthorizeSecurityGroupIngress
+              - ec2:AuthorizeSecurityGroupEgress
+              - ec2:createTags
+              Resource:
+              - "*"
+
+            - Effect: Allow
+              Action:
+              - s3:*
+              Resource:
+              - !Sub arn:aws:s3:::${Prefix}*
+              - !Sub arn:aws:s3:::${Prefix}*/*
+
+            - Effect: Allow
+              Action:
+                - logs:CreateLogGroup
+                - logs:DeleteLogGroup
+                - logs:PutRetentionPolicy
+                - logs:PutSubscriptionFilter
+                - logs:DeleteSubscriptionFilter
+              Resource:
+                - !Sub arn:aws:logs:*:*:${Prefix}*
+                - !Sub arn:aws:logs:*:*:/aws/lambda/${Prefix}*
+
+            - Effect: Allow
+              Action:
+                - logs:DescribeLogGroups
+              Resource:
+                - "*"
+
+            - Effect: Allow
+              Action:
+              - ecs:CreateCluster
+              - ecs:DeleteCluster
+              - ecs:RegisterTaskDefinition
+              - ecs:DeregisterTaskDefinition
+              - ecs:CreateService
+              - ecs:DeleteService
+              - ecs:Describe*
+              - ecs:Update*
+              - ecs:List*
+              - ecs:Stop*
+              Resource:
+              - "*"
+
+            - Effect: Allow
+              Action:
+              - dynamodb:DescribeTable
+              - dynamodb:CreateTable
+              - dynamodb:DeleteTable
+              Resource:
+                - !Sub arn:aws:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${Prefix}*
+
+            - Effect: Allow
+              Action:
+              - iam:GetRole
+              - iam:PassRole
+              Resource:
+              - !Sub arn:aws:iam::${AWS::AccountId}:role/${Prefix}*
+              - !Sub arn:aws:iam::${AWS::AccountId}:role/${Prefix}*
+
+            - Effect: Allow
+              Action:
+              - iam:CreateInstanceProfile
+              - iam:PassRole
+              - iam:DeleteInstanceProfile
+              - iam:AddRoleToInstanceProfile
+              - iam:RemoveRoleFromInstanceProfile
+              Resource:
+              - !Sub arn:aws:iam::${AWS::AccountId}:instance-profile/${Prefix}*
+
+            - Effect: Allow
+              Action:
+              - lambda:GetFunction
+              - lambda:CreateFunction
+              - lambda:DeleteFunction
+              - lambda:GetFunctionConfiguration
+              - lambda:Update*
+              - lambda:AddPermission
+              - lambda:InvokeFunction
+              - lambda:ListTags
+              - lambda:TagResource
+              - lambda:UntagResource
+              - lambda:CreateEventSourceMapping
+              - lambda:GetEventSourceMapping
+              - lambda:DeleteEventSourceMapping
+              Resource:
+              - "*"
+
+            - Effect: Allow
+              Action:
+              - events:PutRule
+              - events:DescribeRule
+              - events:DeleteRule
+              - events:RemoveTargets
+              - events:PutTargets
+              - events:ListTargetsByRule
+              Resource:
+              - "*"
+
+            - Effect: Allow
+              Action:
+              - autoscaling:CreateLaunchConfiguration
+              - autoscaling:CreateAutoScalingGroup
+              - autoscaling:DeleteLaunchConfiguration
+              - autoscaling:DeleteAutoScalingGroup
+              - autoscaling:UpdateAutoScalingGroup
+              - autoscaling:SetDesiredCapacity
+              - autoscaling:Describe*
+              Resource:
+              - "*"
+
+            - Effect: Allow
+              Action:
+                - states:CreateActivity
+                - states:CreateStateMachine
+                - states:DeleteStateMachine
+                - states:UpdateStateMachine
+              Resource:
+                "*"
+
+            - Effect: Allow
+              Action:
+                - states:DeleteActivity
+              Resource:
+                - !Sub "arn:aws:states:${AWS::Region}:${AWS::AccountId}:activity:${Prefix}*"
+
+            - Effect: Allow
+              Action:
+                - states:DeleteStateMachine
+              Resource:
+                - !Sub "arn:aws:states:${AWS::Region}:${AWS::AccountId}:stateMachine:*"
+
+            - Effect: Allow
+              Action:
+                - sqs:CreateQueue
+                - sqs:DeleteQueue
+                - sqs:SetQueueAttributes
+                - sqs:GetQueueAttributes
+              Resource:
+                - !Sub 'arn:aws:sqs:${AWS::Region}:${AWS::AccountId}:${Prefix}*'
+
+            - Effect: Allow
+              Action:
+               - lambda:RemovePermission
+              Resource:
+               - "*"
+
+            - Effect: Allow
+              Action:
+                - SNS:ListTopics
+              Resource:
+                - !Sub "arn:aws:sns:${AWS::Region}:${AWS::AccountId}:*"
+
+            - Effect: Allow
+              Action:
+                - SNS:*
+              Resource:
+                - !Sub "arn:aws:sns:${AWS::Region}:${AWS::AccountId}:${Prefix}*"
+
+            # Allow creation / management of own elasticsearch cluster
+            - Effect: Allow
+              Action:
+                - es:*
+              Resource:
+                - !Sub "arn:aws:es:${AWS::Region}:${AWS::AccountId}:domain/${Prefix}*"
+
+            - Effect: Allow
+              Action:
+                - es:AddTags
+              Resource:
+                - !Sub "arn:aws:es:${AWS::Region}:${AWS::AccountId}:domain/*"
+
+            # Allow API Gateway management. REST APIs do not use normal prefixes
+            - Effect: Allow
+              Action:
+                - apigateway:*
+              Resource:
+                - "*"
+
+Outputs:
+  DeployerRoleArn:
+    Description: The ARN of the Deployer
+    Value: !GetAtt DeployerRole.Arn
diff --git a/example/deployer/config.yml b/example/deployer/config.yml
@@ -0,0 +1,8 @@
+default:
+  prefix: sat-api
+  stackName: '{{prefix}}-deployer-role'
+  capabilities:
+    - CAPABILITY_IAM
+  params:
+    - name: Prefix
+      value: '{{prefix}}'