LEARNING.md

Learning 🎓

This project's primary audience is experienced cloud infrastructure folks looking to production-ize a modern Serverless stack in a single AWS account. But, it's also an appropriate place to learn the various parts along the way!

Contents

• Projects
• Getting Started
• Exercises
  • Environments
  • Lambda Exercises
  • Infrastructure Exercises

Projects

We have three main reference projects from which to learn:

• aws-lambda-serverless-reference: Our most basic Serverless reference with a full production infrastructure.
• aws-lambda-dogs: (This project!) A simple REST API Serverless reference using json-server. If you don't need VPC or are unsure of where to begin, start here.
• badges: Our advanced reference project that includes more complex enhancements like: per-PR environments, github-flow support, promote-to-production artifacts, etc. Once you've mastered manual CF + TF + SLS deploys, come over here and see how far automation can take us!

Getting Started

1. (For Formidables only). Contact Roemer to get three AWS IAM users. The -developer and -admin users will be manually attached to the appropriate sandbox stage groups (tf-dogs-sandbox-developer, tf-dogs-sandbox-admin) for use with serverless commands.

   1. FIRST.LAST user: An AWS superadmin that can do things like deploy the bootstrap CloudFormation and service Terraform infrastructures. This user reflects a DevOps lead in a client project. Should only be used for yarn cf:* and yarn tf:* commands.
   2. FIRST.LAST-developer user: A user with IAM group permissions for the specific serverless project + STAGE to update an existing deployment. This reflects an engineer on a client project with limited privileges or maybe a CI system for staging or whatnot. Should only be used for yarn lambda:* commands.
   3. FIRST.LAST-admin user: A user with IAM group permissions for the specific serverless project + STAGE to update + create/delete any deployment. This reflects an engineer on a client project with full privileges over the serverless application, but not the supporting cloud infrastructure. Should only be used for yarn lambda:* commands.

2. Then, follow all the basic directions for installation in the aws-lambda-serverless-reference README.

   1. (For Formidables only). Please set up aws-vault per the instructions for your authentication method.

3. Check that your credentials are set up for all appropriate work:

   # 1. Check CloudFormation as superadmin
   $ STAGE=sandbox \
     aws-vault exec FIRST.LAST --no-session -- \
     yarn cf:bootstrap:status
   ...
   "UPDATE_COMPLETE" # (or some other status)
   
   # 2. Check Terraform as superadmin
   # 2.a. Init to appropriate stage backend.
   $ STAGE=sandbox \
     aws-vault exec FIRST.LAST --no-session -- \
     yarn tf:service:init --reconfigure
   ...
   Terraform has been successfully initialized!
   
   # 2.b. Run plan to see any changes from our code vs. actual infrastructure.
   $ STAGE=sandbox \
     aws-vault exec FIRST.LAST --no-session -- \
     yarn tf:service:plan
   ...
   No changes. Infrastructure is up-to-date.
   
   # 3. Check Serverless as `-developer`
   $ STAGE=sandbox \
     aws-vault exec FIRST.LAST-developer --no-session -- \
     yarn lambda:info
   ...
   Service Information
   service: sls-dogs
   stage: sandbox
   region: us-east-1
   stack: sls-dogs-sandbox
   ...

Exercises

Environments

tl:dr: use sandbox and only do yarn lambda:* commands for intro exercises.

Lambda

All of the introductory exercises are performed in the pre-existing sandbox environment using only yarn lambda:* commands to do serverless deployments as an -admin or -developer user. This means that you should just let folks know in an appropriate channel that you are "taking over" the environment.

Infrastructure (CloudFormation + Terraform)

Your superadmin user should be reserved only for work on new environments. If you choose to do a new environment, it is important that you talk to Tyler or Roemer.

Lambda Exercises

1. Completely review and read the README.md one more time and ask questions in a slack channel!

2. Do a deployment of the serverless branch as-is off master branch. (For Formidables only) The API_KEY_SECRET value can be found in our 1Password IC vault under the entry aws-lambda-dogs keys:

   $ STAGE=sandbox \
     API_KEY_SECRET=<sandbox key> \
     aws-vault exec FIRST.LAST-developer --no-session -- \
     yarn lambda:deploy

   ... then go and kick the tires on a URL!

   The endpoints created will be listed under endpoints in the console output. Please note that the endpoints MUST end with /. If the output is https://ii178wi5hi.execute-api.us-east-1.amazonaws.com/sandbox/base, then you must use https://ii178wi5hi.execute-api.us-east-1.amazonaws.com/sandbox/base/ (notice the trailing /) in your browser.

3. Delete the serverless application and re-deploy it as-is off master branch:

   # Be careful!
   $ STAGE=sandbox \
     aws-vault exec FIRST.LAST-admin --no-session -- \
     yarn lambda:_delete
   
   # Now, the `lambda:deploy` command needs an `-admin` user to create.
   $ STAGE=sandbox \
     API_KEY_SECRET=<sandbox key> \
     aws-vault exec FIRST.LAST-admin --no-session -- \
     yarn lambda:deploy

4. Create a temporary branch and edit something in src/server/base.js that will be visible from a public URL. Then deploy it and check the results!

   $ STAGE=sandbox \
     API_KEY_SECRET=<sandbox key> \
     aws-vault exec FIRST.LAST-developer --no-session -- \
     yarn lambda:deploy

5. See if there are any open issues that need just a serverless / application code fix and try to open a pull request! Or, be a saint and update all the root project dependencies in package.json to keep us up to date, verify everything still works, and open a pull request.

Infrastructure Exercises

Once you've got the basics of serverless deployment down, you can move on to doing things with your AWS superadmin user to the infrastructure.

1. Check the status of the CloudFormation bootstrap stack and attempt an update:

   # Check the existing status.
   $ STAGE=sandbox \
     aws-vault exec FIRST.LAST --no-session -- \
     yarn cf:bootstrap:status
   ...
   "UPDATE_COMPLETE"
   
   # Attempt an update. If everything is up-to-date on master, you'll get an expected error.
   $ STAGE=sandbox \
     aws-vault exec FIRST.LAST --no-session -- \
     yarn cf:bootstrap:update
   ...
   An error occurred (ValidationError) when calling the UpdateStack operation: No updates are to be performed.

2. Check the status of the Terraform service stack and attempt an update:

   # Init to appropriate stage backend.
   $ STAGE=sandbox \
     aws-vault exec FIRST.LAST --no-session -- \
     yarn tf:service:init --reconfigure
   ...
   Terraform has been successfully initialized!
   
   # Run plan to see any changes from our code vs. actual infrastructure.
   $ STAGE=sandbox \
     aws-vault exec FIRST.LAST --no-session -- \
     yarn tf:service:plan
   ...
   No changes. Infrastructure is up-to-date.
   
   
   # Run apply to make changes (or no-op) from our code vs. actual infrastructure.
   $ STAGE=sandbox \
     aws-vault exec FIRST.LAST --no-session -- \
     yarn tf:service:apply
   ...
   Apply complete! Resources: 0 added, 0 changed, 0 destroyed.
   
   # **NOTE**: If there are changes needed, you will type "yes" at the prompt.

3. Create a new environment named sandbox-FIRST-LAST, just for you!

   1. Create a new temporary branch off the repo (not a fork) so that other Formidables can easily jump in and help you.

   2. Per the instructions above, make sure to talk to Tyler or Roemer and have them review and approve the tentative changes before trying any real AWS provisioning actions.

   3. Once everything is ready, go ahead and provision your entire infrastructure!

      # Create the CloudFormation bootstrap stack
      $ STAGE=sandbox-FIRST-LAST \
        aws-vault exec FIRST.LAST --no-session -- \
        yarn cf:bootstrap:create
      
      # Confirm done in `CREATE|UPDATE_COMPLETE` status.
      $ STAGE=sandbox-FIRST-LAST \
        aws-vault exec FIRST.LAST --no-session -- \
        yarn cf:bootstrap:status
      
      # Create the Terraform service stack
      $ STAGE=sandbox-FIRST-LAST \
        aws-vault exec FIRST.LAST --no-session -- \
        yarn tf:service:init --reconfigure
      
      $ STAGE=sandbox-FIRST-LAST \
        aws-vault exec FIRST.LAST --no-session -- \
        yarn tf:service:apply
      # Type "yes" at prompt for resource creation after a review
      

   4. Using the AWS console, add your FIRST.LAST-admin user to the newly created IAM Group tf-dogs-sandbox-FIRST-LAST-admin.

   5. And then deploy the application with the -admin user!

      # Deploy the serverless app as `-admin`
      $ STAGE=sandbox-FIRST-LAST \
        API_KEY_SECRET=<sandbox key> \
        aws-vault exec FIRST.LAST-admin --no-session -- \
        yarn lambda:deploy

   6. Go kick the tires on your new service or get help in Slack if things are going wrong. Experiment with the app or the Terraform infastructure with suggestions from your colleagues.

   7. When you're finished, remove your FIRST.LAST-admin user from the IAM group listed in step 4 via the AWS Console.

   8. Then, tear everything down in reverse order:

      # Delete the serverless app as `-admin`
      $ STAGE=sandbox-FIRST-LAST \
        API_KEY_SECRET=<sandbox key> \
        aws-vault exec FIRST.LAST-admin --no-session -- \
        yarn lambda:_delete
      
      # Delete Terraform support stack
      # You will need to manually delete the following before running terraform destroy
      # 1) db.json inside of the tf-fmd-dogs-sandbox-FIRST-LAST-us-east-1-data (S3) otherwise you will encounter a BucketNotEmpty exception
      # 2) `FIRST.LAST-admin` inside of the IAM Group `tf-dogs-sandbox-FIRST-LAST-admin` otherwise you will encounter a DeleteConflict exception
      $ STAGE=sandbox-FIRST-LAST \
        aws-vault exec FIRST.LAST --no-session -- \
        yarn tf:service:_delete
      # Type "yes" if prompted
      
      # Delete the CloudFormation bootstrap stack
      $ STAGE=sandbox-FIRST-LAST \
        aws-vault exec FIRST.LAST --no-session -- \
        yarn cf:bootstrap:_delete

4. See if there are any open issues that need an infrastructure code fix. Talk to your peers in Slack channel as to how best to develop the changes (a separate dedicated environment, or just YOLO-ing it in sandbox), then try to open a pull request!

5. Once you're comfortable with all the infrastructure parts in this project, head on over to our badges project to learn the advanced next steps of a whole lot more automation and cloud infrastructure complexity!