Table of Contents

• Table of Contents
• 1. Overview
• 2. Notices
  • 2.1 Public Domain Standard Notice
  • 2.2 License Standard Notice
  • 2.3 Privacy Standard Notice
  • 2.4 Contributing Standard Notice
  • 2.5 Records Management Standard Notice
  • 2.6 Additional Standard Notices
• 3. Architectural Design
• 4. Getting Started
  • 4.1 Requirements
  • 4.2 Clone DIBBS-AWS Repository
  • 4.3 Begin Using Terraform
  • 4.4 Make A New Branch
  • 4.5 Update Terraform Through The Command Line
  • 4.6 Run Terraform Code In Your Designated Environment
  • 4.7 Validate Your Terraform Changes
  • 4.8 Review Prospective Changes
  • 4.9 Apply Changes
  • 4.10 Update Variables

1. Overview

The Data Integration Building Blocks (DIBBs) project is an effort to help state, local, territorial, and tribal public health departments better make sense of and utilize their data. You can read more about the project on the main DIBBs repository.

This repository is specifically to develop an AWS "starter kit" for the DIBBs project. This will enable our jurisdictional partners to build from this repository to provision their own AWS infrastructure.

• Return to Table of Contents.

2. Notices

2.1 Public Domain Standard Notice

This repository constitutes a work of the United States Government and is not subject to domestic copyright protection under 17 USC § 105. This repository is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication. All contributions to this repository will be released under the CC0 dedication. By submitting a pull request you are agreeing to comply with this waiver of copyright interest.

• Return to Table of Contents.

2.2 License Standard Notice

The repository utilizes code licensed under the terms of the Apache Software License and therefore is licensed under ASL v2 or later.

This source code in this repository is free: you can redistribute it and/or modify it under the terms of the Apache Software License version 2, or (at your option) any later version.

This source code in this repository is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the Apache Software License for more details.

You should have received a copy of the Apache Software License along with this program. If not, see http://www.apache.org/licenses/LICENSE-2.0.html.

The source code forked from other open source projects will inherit its license.

• Return to Table of Contents.

2.3 Privacy Standard Notice

This repository contains only non-sensitive, publicly available data and information. All material and community participation is covered by the Disclaimer and Code of Conduct. For more information about CDC's privacy policy, please visit http://www.cdc.gov/other/privacy.html.

• Return to Table of Contents.

2.4 Contributing Standard Notice

Anyone is encouraged to contribute to the repository by forking and submitting a pull request. (If you are new to GitHub, you might start with a basic tutorial.) By contributing to this project, you grant a world-wide, royalty-free, perpetual, irrevocable, non-exclusive, transferable license to all users under the terms of the Apache Software License v2 or later.

All comments, messages, pull requests, and other submissions received through CDC including this GitHub page may be subject to applicable federal law, including but not limited to the Federal Records Act, and may be archived. Learn more at http://www.cdc.gov/other/privacy.html.

• Return to Table of Contents.

2.5 Records Management Standard Notice

This repository is not a source of government records, but is a copy to increase collaboration and collaborative potential. All government records will be published through the CDC web site.

• Return to Table of Contents.

2.6 Additional Standard Notices

Please refer to CDC's Template Repository for more information about contributing to this repository, public domain notices and disclaimers, and code of conduct.

• Return to Table of Contents.

3. Architectural Design

The current architectural design for dibbs-aws is as follows:

• Return to Table of Contents.

4. Getting Started

This section will assist engineers with executing Infrastructure as Code (IaC) found in the dibbs-aws repository utilizing Terraform.

Return to Table of Contents.

4.1 Requirements

Engineers will need following tools installed on their local machine:

• Terraform version 1.0.0+ See Hashicorp installation Guide
• AWS CLI version 2+ See AWS CLI Installation Guide
• AWS Profile Access
  -- Note: Engineers must have access and permissions to create AWS resources

Return to Table of Contents.

4.2 Clone DIBBS-AWS Repository

4.2.1. Create a directory to store the repository on your local machine

• Mac OS users: mkdir workspace
• Windows users: md workspace

4.2.2. Clone the dibbs-aws repository (use one of the following commands:)
    git clone [email protected]:CDCgov/dibbs-cloud.git
    git clone https://github.com/CDCgov/dibbs-cloud.git

Return to Table of Contents.

4.3 Begin Using Terraform

4.3.1. Navigate to terraform/implementation.
  Initialize your local terraform code. terraform init
4.3.2. Developing in a terraform workspace.
  Check the terraform workspaces. terraform workspace list
  Note: If you only have a default terraform workspace, you can create a terraform workspace to develop in. Skip to "Create a terraform workspace to develop in," below.

• Select the terraform workspace to develop in.
    terraform workspace select {selectEnvironmentName}
    For example, terraform workspace select dev.
• Create a terraform workspace to develop in.
    terraform workspace new {newEnvironmentName}.   For example, terraform workspace new dev.

Return to Table of Contents.

4.4 Make A New Branch

Make a new branch to store any of your amendments to ensure you keep a clean main (or master) branch clear from unapproved revisions.

4.4.1. Navigate to the dibbs-aws repository on your local machine.
  cd /workspace/dibbs-aws
4.4.2. Make a new branch.
  For example, git checkout -b setup-dibbs-aws-backend-and-services.

Return to Table of Contents.

4.5 Update Terraform Through The Command Line

This section will go over some of the sections you will need to amend or change in your local terraform branch.

4.5.1. Update And Setup Your AWS Backend

• In your terminal, navigate to the /terraform/setup folder (cd /terraform/setup).
• Run ./setup.sh.

    Note: You will be prompted to set your variable values (i.e. Region, Owner, Project, etc.). For example, the default value for Owner is Skylight. You can change this value to one that represents your organization or department. The Owner name must be less than 13 characters.

The setup.sh scripts will assist you with creating the terraform state and tfvars files, as well as check to ensure the necessary arguments or variables were created. See setup.sh file. Also see Inputs.

The setup.sh script will create the following files:

• .tfvars
• .env (will need to be created manually if prompted)
• terraform.state

4.5.2. Check What Files Changed

• Run git status to see what changes have changed.

4.5.3. Save Changes

• Save and commit changes to your working branch.

Return to Table of Contents.

4.6 Run Terraform Code In Your Designated Environment

4.6.1. Run ECS Module Locally

• It is highly recommended to create a new directory per environment that is launched, to do so run cp terraform/implementation/ecs terraform/implementation/{insertEnvironmentName}.
• To run your ECS Module Changes in your local terminal, navigate to your working directory, cd terraform/implementation/ecs/ or cd terraform/implementation/{insertEnvironmentName}
• In your terminal run the deploy script for your designated environment ./deploy.sh -e {insertEnvironmentName}.
      Note: The -e tag stands for environment and you can specify dev, stage, prod, this can match your environment naming convention.     or whatever environment your team desires.

Return to Table of Contents.

4.7 Validate Your Terraform Changes

4.7.1. Validate Changes

• Run terraform validate to ensure the new configurations are valid.
• If you receive a success, then move to 4.8.

Return to Table of Contents.

4.8 Review Prospective Changes

4.8.1. Run Terraform Plan

• Run terraform plan to see what resources will be created with the amendments you created in section 4.5.
• Resolve any conflicts that may arise. For example, target group names can only be 13 characters long. So, if you receive an error for the target group name above the limit, you may need to revise the target group name to satisfy this requirement. Once you have made the necessary changes, run terraform validate then terraform plan again.
• Review the plan and ensure things look correct before moving to 4.9.

Return to Table of Contents.

4.9 Apply Changes

4.9.1. Run Terraform Apply

• Run terraform apply to officially create the necessary resources using Terraform.
• You will first receive a plan. Review the plan to ensure it is consistent to the changes you would like to make.
• If the plan is correct, type yes to apply your terraform changes.

Return to Table of Contents.

4.10 Update Variables

4.10.1. Update Other Default Variables

• Navigate to the defaults.tfvars file cd terraform/implementation/ecs/ or cd terraform/implementation/{insertEnvironmentName}.
• In this defaults.tfvars file, you can update and override any other default values.

4.10.2. Test and Validate Your Changes

• Save your changes.
• Run terraform init.
• Validate your changes terraform validate.
• If no errors, run terraform plan to see what changes will result.
• Then run terraform apply. Fix any issues that may result until your apply is successful.
• Save, commit and push your changes to your github repository for your team to review.

Return to Table of Contents.