Merge pull request #52 from hackforla/51-update-contributing-guide

Updating documentation for clarity

Author: sudhara

.github/ISSUE_TEMPLATE/pre-work-template-devops-security.md

@@ -22,9 +22,9 @@ As a new member on the HfLA devops-security team, fill in the following fields a
 
 - [ ] Before starting to work on the below instructions, make sure to join the #ops Slack Channel. And are a member of `devops-security` repository.
 - [ ] Self-assign this issue (gear in right side panel).
-- [ ] Add this issue to the Project Board under the Projects section (gear in right side panel).
+- [ ] Add this issue to the Project Board CoP: DevOps: Project Board - under the Projects section (gear in right side panel).
 - [ ] Attend weekly team meeting, Wednesdays 6-8pm PST.
-  - [ ] Note: There are no meetings on the 1st-7th of every month.
+  - [ ] Note: There are no meetings on the 1st Wednesday of every month.
 - [ ] Complete the steps in [Creating a personal AWS account](https://github.com/hackforla/devops-security/blob/main/CONTRIBUTING.md#creating-a-personal-aws-account) and [Login as root user & setup MFA](https://github.com/hackforla/devops-security/blob/main/CONTRIBUTING.md#login-as-root-user-&-setup-mfa).
 - [ ] Read and follow the instructions in [Setting up IAM and AWS CLI](https://github.com/hackforla/devops-security/blob/main/CONTRIBUTING.md#setting-up-iam-and-aws-cli) for:
     - [ ] [Creating an IAM User](https://github.com/hackforla/devops-security/blob/main/CONTRIBUTING.md#create-an-iam-group)
@@ -35,7 +35,9 @@ As a new member on the HfLA devops-security team, fill in the following fields a
     - [ ] [Generating user access keys](https://github.com/hackforla/devops-security/blob/main/CONTRIBUTING.md#generating-access-keys-for-aws-cli)
 - [ ] Complete the instructions in [AWS Documentation](https://docs.aws.amazon.com/cli/v1/userguide/cli-chap-install.html) and choose your operating system to install AWS CLI. 
 - [ ] Complete the instruction in [AWS Documentation](https://docs.aws.amazon.com/cli/latest/userguide/cli-authentication-short-term.html) to setup the AWS CLI.
-- [ ] Read follow the instructions in [Creating a backend state](https://github.com/hackforla/devops-security/blob/main/CONTRIBUTING.md#creating-backend-state).
+- [ ] Follow the instructions in [Creating a backend state](https://github.com/hackforla/devops-security/blob/main/CONTRIBUTING.md#creating-backend-state) to create the S3 bucket and DynamoDB table.
+  - [ ] Create the S3 bucket
+  - [ ] Create the DynamoDB table
 - [ ] Install Terraform locally by following the instructions of the installation guide mentioned in [Installing Terraform](https://github.com/hackforla/devops-security/blob/main/CONTRIBUTING.md#installing-terraform)
 - [ ] Install Terraform Docs locally by following the instructions of the installation guide mentioned in [Installing Terraform docs](https://github.com/hackforla/devops-security/blob/main/CONTRIBUTING.md#installing-terraform-docs)
 - [ ] Complete the instructions in [Clone the repository](https://github.com/hackforla/devops-security/blob/main/CONTRIBUTING.md#clone-the-repository)
@@ -46,14 +48,14 @@ As a new member on the HfLA devops-security team, fill in the following fields a
     git checkout -b issue-number-add-new-iam-user
 
     ```
-- [ ] Navigate to the `aws-user.tf` file and add your user information and follow the below template.
+- [ ] Navigate to the `aws-user.tf` file and add your user information to the end of the file following the below template.
 
     ```bash
-    
-    module "iam_user_testiamuser" {
+    # Replace USERNAME with your GitHub handle
+    module "iam_user_USERNAME" {
     source = "./modules/aws-users"
 
-    user_name = "testiamuser"
+    user_name = "USERNAME" # Replace with GitHub handle
     user_tags = {
       "Project"      = "devops-security"
       "Access Level" = "1"
@@ -63,12 +65,25 @@ As a new member on the HfLA devops-security team, fill in the following fields a
 
     ```
 - [ ] In your code editor navigate to `terraform` directory. `cd terraform`
+
+Note: You must be authenticated to your AWS account via the CLI for the next commands to work. The above instructions for setting up the CLI will guide you through this process. To check to see if you are authenticated, run `aws sts get-caller-identity`. You should get a response like:
+
+```
+{
+    "UserId": "ABCDEFGHIJKLMNOPQRSTU",
+    "Account": "012345678910",
+    "Arn": "arn:aws:iam::012345678910:user/USERNAME"
+}
+```
+If you are unable to authenticate from your local machine using the CLI, post in the #ops channel in Slack so that the team can help you get unblocked.
 - [ ] Execute the command `terraform init` to initialize terraform in the directory. Address any failures that arise (if any).
 - [ ] Execute the command `terraform plan` this will output a plan replicating the same IAM resources as the devops security account. Address any failures that arise (if any).
-- [ ] Then execute the command `terraform apply` this will create all of the resources that are currently managed by Devops Security. All of the resources created here incur zero cost except for the Dynamo DB installation, which should remain in the free tier.
-      - [ ] ** If you have cost concerns, Run a Terraform Destroy to take down all of the resources you created (don't worry, you can recreate them just as quickly). **
+- [ ] Then execute the command `terraform apply` this will create all of the resources that are currently managed by Devops Security. All of the resources created here incur zero cost except for the Dynamo DB installation, which should remain in the free tier. **
+  - [ ] **If you have cost concerns, Run a Terraform Destroy to take down all of the resources you created (don't worry, you can recreate them just as quickly). If you create resources outside of what's described in this issue, you may incur charges.**
+- [ ] Update the README using Terraform Docs to document changes
+  - [ ] ```terraform-docs -c .terraform.docs.yml .```
 - [ ] Once you have tested your changes, stage them in git with 
     - [ ] `git status` command.
     - [ ] then `git add path/to/file` (you can copy from above output for the file path).
-- [ ] Commit the changes by executing `git commit -m "briefly describing the changes"`.
+- [ ] Commit the changes by executing `git commit -m "brief description of changes"`.
 - [ ] Push the changes with `git push --set-upstream origin name-of-branch`

CONTRIBUTING.md

@@ -32,6 +32,9 @@ Below are guidelines for contributing to the devops-security repository hosted o
     - [**Submitting changes via git and opening a PR**](#submitting-changes-via-git-and-opening-a-pr)
 
 ## **Setting up the local development environment**
+The below instructions will walk you through setting up your own AWS account for local development and testing before pushing changes that will effect our infrastructure. 
+
+If you've already completed these steps or you aren't making Terraform changes, skip to [Create a branch](https://github.com/hackforla/devops-security/blob/main/CONTRIBUTING.md#create-a-new-branch-where-you-will-work-on-your-issue)
 
 ### **Creating a personal AWS account**
 
@@ -132,41 +135,83 @@ Below are guidelines for contributing to the devops-security repository hosted o
     ```
   <sub>[Back to Table of Contents](#table-of-contents)</sub>
   ***
+The below steps must be completed in order to authenticate to AWS locally via the command line interface (CLI):
 - [Install AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) 
 - [Set up the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-quickstart.html)
 
 <sub>[Back to Table of Contents](#table-of-contents)</sub>
 ***
 
-### **Installing Terraform**
+### **Creating Backend State**
 
-Use the [Official HashiCorp install instructions](https://developer.hashicorp.com/terraform/install) for installing terraform.
+To facilitate AWS IAM changes using Terraform, it's essential to establish backend state storage.
 
-<sub>[Back to Table of Contents](#table-of-contents)</sub>
-***
+#### Create S3 bucket
+- Region: `us-west-2` (Oregon)
+- Name: `USERNAME-hfla-ops-terraform-state`
+- Enable versioning
+- Enable server-side encryption
 
-### **Creating Backend State**
+You can create a bucket from the AWS UI, CloudShell, or from the CLI using the following commands:
+
+##### Step 1: Create the bucket
+`aws s3api create-bucket --bucket USERNAME-hfla-ops-terraform-state --region us-west-2 --create-bucket-configuration LocationConstraint=us-west-2`
+
+##### Step 2: Enable versioning
+`aws s3api put-bucket-versioning --bucket USERNAME-hfla-ops-terraform-state --versioning-configuration Status=Enabled`
+
+##### Step 3: Enable server-side encryption
+```bash
+aws s3api put-bucket-encryption --bucket USERNAME-hfla-ops-terraform-state --server-side-encryption-configuration '{
+    "Rules": [
+        {
+            "ApplyServerSideEncryptionByDefault": {
+                "SSEAlgorithm": "AES256"
+            }
+        }
+    ]
+}'
+```
+
+#### Set up DynamoDB to store the backend state
+
+- Create table `hfla_ops_terraform_table`
+- Set partition key to `LockID` with a type of `string`
+- Choose on-demand capacity
 
-To facilitate AWS IAM changes using Terraform, it's essential to establish backend state storage. Refer to and follow the instructions outlined in this [issue](https://github.com/hackforla/ops/issues/105) to create the backend state.
+You can create the table from the AWS UI, CloudShell, or from the CLI using the following command:
 
-**Note:** Users will need to create their backend state exactly as specified (i.e. using the same naming conventions).
+```bash
+aws dynamodb create-table \
+    --table-name hfla_ops_terraform_table \
+    --attribute-definitions AttributeName=LockID,AttributeType=S \
+    --key-schema AttributeName=LockID,KeyType=HASH \
+    --billing-mode PAY_PER_REQUEST
+```
 
 <sub>[Back to Table of Contents](#table-of-contents)</sub>
 ***
 
 ### **Creating Local tfvars file**
 
-Atfer creating a backend state, create a ```backend.tfvars``` file in the ```terraform``` directory. It should have content of this format:
+After creating a backend state, create a `backend.tfvars` file in the `terraform` directory. It should have content of this format:
 
-```
-bucket         = "{developer_specific}-hfla-ops-terraform-state"
+```terraform
+bucket         = "USERNAME-hfla-ops-terraform-state"
 key            = "devops-security/terraform.tfstate"
 region         = "us-east-2"
-dynamodb_table = "{developer_specific}_hfla_ops_terraform_table"
+dynamodb_table = "hfla_ops_terraform_table"
 encrypt        = true
 ```
 
-Remeber to match these values to the ones in your backend state (and replace {developer-specific} with your actual name)
+Remember to match these values to the ones in your backend state (and replace USERNAME with your username)
+
+<sub>[Back to Table of Contents](#table-of-contents)</sub>
+***
+
+### **Installing Terraform**
+
+Use the [Official HashiCorp install instructions](https://developer.hashicorp.com/terraform/install) for installing terraform.
 
 <sub>[Back to Table of Contents](#table-of-contents)</sub>
 ***
@@ -232,35 +277,66 @@ When you've finished working on your issue, follow the steps below to prepare yo
 ***
 
 ### **Terraform Setup and Execution Instructions**
+Make the required changes and execute them to see the changes in your own AWS account
 
 - Change into `terraform` directory with 
 
 ```bash
 cd terraform
 ```
 
-- Next initilize the terraform configuration
+- Initialize the terraform configuration
 
 ```bash
 terraform init --backend-config=backend.tfvars
 ```
 
-- Then generate and run an execution plan
+- Generate and run an execution plan
 
 ```bash
 terraform plan
 ```
+
+- Apply your changes
+```bash
+terraform apply
+```
+
+- Optional: delete the resources created
+```bash
+terraform destroy
+```
+
+<sub>[Back to Table of Contents](#table-of-contents)</sub>
+***
+
+### Generate Terraform Docs
+Terraform docs allow the easy updating of README files inside of Terraform directories
+
+Navigate to the directory where the changes were made
+```bash
+cd terraform # or other directory
+```
+```bash
+terraform-docs -c .terraform.docs.yml .
+```
+
 <sub>[Back to Table of Contents](#table-of-contents)</sub>
 ***
 
 ### **Submitting changes via git and opening a PR**
 
 - We urge developers to be cautious using `git add`. In general it is not advisable to use `git add -all` or `git add .`. Rather, run `git status`, examine the output carefully, and then add only those files specifically related to the current issue. This will ensure that no extraneous files are included in the subsequent commit. 
 
+Example:
+```bash
+git add terraform/aws-users.tf
+```
+
 - Then commit the changes with a descriptive message using
 
   ```bash
-  git commit -m "your commit message"
+  git commit -m "Updating documentation" # Change the message to summarize the changes you've made
   ```
 
 - Push changes to the remote repository, replace the `branch_name` with the name of the branch you are working on

terraform/README.md

@@ -13,11 +13,13 @@ Resources created by this code repository.
 | <a name="module_iam_services_supervisor_group"></a> [iam\_services\_supervisor\_group](#module\_iam\_services\_supervisor\_group) | ./modules/aws-groups | n/a |
 | <a name="module_iam_user_JimmyJuarez10"></a> [iam\_user\_JimmyJuarez10](#module\_iam\_user\_JimmyJuarez10) | ./modules/aws-users | n/a |
 | <a name="module_iam_user_abbyz123"></a> [iam\_user\_abbyz123](#module\_iam\_user\_abbyz123) | ./modules/aws-users | n/a |
+| <a name="module_iam_user_alexe"></a> [iam\_user\_alexe](#module\_iam\_user\_alexe) | ./modules/aws-users | n/a |
 | <a name="module_iam_user_awlFCCamp"></a> [iam\_user\_awlFCCamp](#module\_iam\_user\_awlFCCamp) | ./modules/aws-users | n/a |
 | <a name="module_iam_user_brittanyms"></a> [iam\_user\_brittanyms](#module\_iam\_user\_brittanyms) | ./modules/aws-users | n/a |
 | <a name="module_iam_user_chelseyb"></a> [iam\_user\_chelseyb](#module\_iam\_user\_chelseyb) | ./modules/aws-users | n/a |
 | <a name="module_iam_user_freaky4wrld"></a> [iam\_user\_freaky4wrld](#module\_iam\_user\_freaky4wrld) | ./modules/aws-users | n/a |
 | <a name="module_iam_user_jbubar"></a> [iam\_user\_jbubar](#module\_iam\_user\_jbubar) | ./modules/aws-users | n/a |
+| <a name="module_iam_user_rsakuma"></a> [iam\_user\_rsakuma](#module\_iam\_user\_rsakuma) | ./modules/aws-users | n/a |
 | <a name="module_iam_user_samuelusc"></a> [iam\_user\_samuelusc](#module\_iam\_user\_samuelusc) | ./modules/aws-users | n/a |
 | <a name="module_iam_user_shikha0428"></a> [iam\_user\_shikha0428](#module\_iam\_user\_shikha0428) | ./modules/aws-users | n/a |
 | <a name="module_iam_user_shinjonathan"></a> [iam\_user\_shinjonathan](#module\_iam\_user\_shinjonathan) | ./modules/aws-users | n/a |