Add IAM role management documentation

amaalzohny · Sep 22, 2018 · 80f82e8 · 80f82e8
1 parent 6d92670
commit 80f82e8
Show file tree

Hide file tree

Showing 3 changed files with 57 additions and 16 deletions.
diff --git a/.chalice/config.json b/.chalice/config.json
@@ -1,9 +1,19 @@
 {
   "stages": {
     "dev": {
-      "api_gateway_stage": "api"
+      "api_gateway_stage": "api",
+      "iam_policy_file": "policy-dev.json",
+      "lambda_memory_size": 256,
+      "lambda_timeout": 30,
+      "environment_variables": {
+        "EXAMPLE_VAR": "example-value"
+      },
+      "tags": {
+        "created-from": "chalice-app-template"
+      }
     }
   },
   "version": "2.0",
-  "app_name": "chalice-app-template"
+  "app_name": "chalice-app-template",
+  "autogen_policy": false
 }
diff --git a/.chalice/policy-dev.json b/.chalice/policy-dev.json
@@ -0,0 +1,21 @@
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "logs:CreateLogGroup",
+        "logs:CreateLogStream",
+        "logs:PutLogEvents"
+      ],
+      "Resource": "arn:aws:logs:*:*:*"
+    },
+    {
+      "Effect": "Allow",
+      "Action": [
+        "s3:ListAllMyBuckets"
+      ],
+      "Resource": "*"
+    }
+  ]
+}
diff --git a/README.md b/README.md
@@ -33,35 +33,45 @@ the [Terraform S3 backend](https://www.terraform.io/docs/backends/types/s3.html)
 
 To deploy the app, type `make deploy` in this directory.
 
-Filename              | Purpose                                 | Information links
-----------------------|-----------------------------------------|------------------------------------------
-`app.py`              | The application entry point             | [Chalice](https://github.com/aws/chalice)
-`requirements.txt`    | Application dependencies                | [Pip requirements files](https://pip.readthedocs.io/en/1.1/requirements.html)
-`requirements-dev.txt`| Developer environment dependencies      | [Pip requirements files](https://pip.readthedocs.io/en/1.1/requirements.html)
-`Makefile`            | Tools for packaging and deploying       |
-`terraform-deploy.tf` | Terraform config file for deploying     | [Terraform Configuration](https://www.terraform.io/docs/configuration/)
-`.chalice/config.json`| Chalice config file for the app         | [Chalice](https://github.com/aws/chalice)
-`test/test.py`        | Test suite template                     | [Python unittest](https://docs.python.org/3/library/unittest.html)
-`.travis.yml`         | Travis CI (CI/CD) configuration         | [Travis CI](https://docs.travis-ci.com/user/customizing-the-build/)
+Filename                  | Purpose                           | Information links
+--------------------------|-----------------------------------|------------------------------------------
+`app.py`                  |The application entry point        | [Chalice Docs](https://chalice.readthedocs.io/en/latest/)
+`requirements-dev.txt`    |Developer environment dependencies | [Pip requirements files](https://pip.readthedocs.io/en/1.1/requirements.html)
+`requirements.txt`        |Application dependencies           | [Chalice App Packaging](https://chalice.readthedocs.io/en/latest/topics/packaging.html)
+`Makefile`                |Tools for packaging and deploying  | [Automation and Make](https://swcarpentry.github.io/make-novice/)
+`terraform-deploy.tf`     |Terraform config file for deploying| [Terraform Configuration](https://www.terraform.io/docs/configuration/)
+`.chalice/config.json`    |Chalice config file for the app    | [Chalice Configuration File](https://chalice.readthedocs.io/en/latest/topics/configfile.html)
+`.chalice/policy-dev.json`|IAM policy for the app's IAM role  | [Lambda Permissions](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html)
+`test/test.py`            |Test suite template                | [Python unittest](https://docs.python.org/3/library/unittest.html)
+`.travis.yml`             |Travis CI (CI/CD) configuration    | [Travis CI](https://docs.travis-ci.com/user/customizing-the-build/)
 
 ## How to create a new app from this template
 1. Install the dependencies: `pip install -r requirements-dev.txt` and Terraform (`brew install terraform` or
    https://www.terraform.io/downloads.html)
 1. Configure the AWS CLI (`pip install awscli`; `aws configure`).
 1. Ensure the S3 bucket `tfstate-<YOUR_AWS_ACCOUNT_ID>` exists, or modify the Makefile to reference a different bucket.
 1. Fork or copy the contents of this repo to a new directory.
-1. Replace the name of your app in `.chalice/config.json`.
+1. Edit `.chalice/config.json` to set the name of your app and Lambda settings like memory, timeout, reserved
+   concurrency, tags, and environment variables.
 1. Edit `app.py` and `requirements.txt` to create your app.
 1. Deploy your app by running `make deploy`. The deployment results, including your Lambda's EndpointURL, will be
-   printed to the terminal.
+   printed to the terminal. You can immediately test your app by running
+   `http https://your-api-id.execute-api.us-east-1.amazonaws.com/api/` or opening the EndpointURL in a browser.
+1. If needed, assign
+   a [Custom Domain Name](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-custom-domains.html) to
+   your app in the [AWS Console for API Gateway](https://console.aws.amazon.com/apigateway/home#/custom-domain-names).
 
 To redeploy your app after updating, run `make deploy` again. To undeploy the app and delete all associated resources,
 run `make destroy`.
 
 ## Testing
-The test suite in `test/test.py` runs Chalice in local mode for unit testing. You can invoke it using `make test`.
+The test suite in `test/test.py` runs Chalice in local mode for unit testing. You can invoke it using `make test`. This
+test is also configured to run on [Travis CI](https://travis-ci.com).
 
 ## Managing the Lambda IAM role and assume role policy
-TODO
+Your Lambda function is assigned an IAM role that controls the permissions given to the Lambda's AWS credentials. This
+IAM role is set from the file `.chalice/policy-dev.json`. Edit this policy and repeat the deployment if your Lambda
+needs access to other AWS APIs. You can also edit the Makefile to parameterize this file or generate it from a template
+as needed. (The setting `autogen_policy` must be set to `false` in `.chalice/config.json` for Chalice to use this file.)
 
 [![Build Status](https://travis-ci.com/chanzuckerberg/chalice-app-template.svg?token=iPJHxi7MxMYqJkBxfGCC&branch=master)](https://travis-ci.com/chanzuckerberg/chalice-app-template)