Merge pull request #1 from sheeriot/feature-awsvm-docs

Feature awsvm docs

.github/workflows/vmhostaws.yml

@@ -0,0 +1,74 @@
+name: AWS VM Host - Terraform
+
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: 'Environment to Deploy'
+        type: environment
+        required: true
+      component:
+        description: 'Component to Deploy'
+        type: choice
+        options:
+          - 'tfstore'
+          - 'network'
+          - 'vmhost'
+      action:
+        description: 'Terraform Action to Perform'
+        type: choice
+        options:
+          - 'plan'
+          - 'apply'
+          - 'destroy'
+
+run-name: ${{ github.event.inputs.environment }} - Terraform ${{ github.event.inputs.component }} ${{ github.event.inputs.action }}
+
+jobs:
+
+  terraform-infra:
+
+    runs-on: ubuntu-latest
+    environment: ${{ github.event.inputs.environment }}
+    env:
+      ENV_NAME: ${{ github.event.inputs.environment }}
+      COMPONENT: ${{ github.event.inputs.component }}
+      TERRAFORM_ACTION: ${{ github.event.inputs.action }}
+      AWS_ACCESS_KEY_ID: ${{ vars.AWS_ACCESS_KEY_ID }}
+      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+      AWS_REGION: ${{ vars.AWS_REGION }}
+      CIDR_BLOCK: ${{ vars.CIDR_BLOCK }}
+      INFRA_NAME: ${{ vars.INFRA_NAME }}
+      OPS_IP1: ${{ vars.OPS_IP1 }}
+      PUBKEY1: ${{ vars.PUBKEY1 }}
+      STATE_SUFFIX: ${{ vars.STATE_SUFFIX }}
+      VM_NAME: ${{ vars.VM_NAME }}
+      VM_SIZE: ${{ vars.VM_SIZE }}
+
+    steps:
+
+      - name: Check Environment
+        run: |
+          echo "ENV_NAME: ${ENV_NAME}"
+          echo "TERRAFORM_ACTION: ${TERRAFORM_ACTION}"
+          echo "COMPONENT: $COMPONENT"
+          echo "AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}"
+          echo "AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}"
+          echo "AWS_REGION: ${AWS_REGION}"
+          echo "CIDR_BLOCK: ${CIDR_BLOCK}"
+          echo "INFRA_NAME: ${INFRA_NAME}"
+          echo "OPS_IP1: ${OPS_IP1}"
+          echo "PUBKEY1: ${PUBKEY1}
+          echo "STATE_SUFFIX: ${STATE_SUFFIX}"
+          echo "VM Name/Size: ${VM_NAME}/${VM_SIZE}"
+
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Terraform Action
+        env:
+          ARM_SKIP_PROVIDER_REGISTRATION: true
+        run: |
+          cd aws
+          echo "ENV_NAME: ${ENV_NAME}"
+          ./terraform_runner.sh aws $COMPONENT $TERRAFORM_ACTION

.github/workflows/vmhost.yml → .github/workflows/vmhostazure.yml

@@ -1,4 +1,4 @@
-name: VM Host - Terraform an Azure VM
+name: Azure VM Host - Terraform
 
 on:
   workflow_dispatch:

README.md

@@ -1,10 +1,9 @@
-# Terraform: Azure VM Deploy
+# Terraform: VM Deploy - Azure and AWS
 
-This project (AzureVmDeploy) uses Terraform to plan, deploy, and destory a Linux VM. This is setup to be run as a manual GitHub Actions Workflow.
+This repository (AwsVmDeploy) uses Terraform to plan, deploy, and destory a Linux VM. This is setup to be run as a manual GitHub Actions Workflow.
 
-This repository uses GitHub environment variables and secrets to deploy Virtual Machines (VMs) to Azure using GitHub Actions for Terraform automation.
+This repository uses GitHub environment variables and secrets to deploy Virtual Machines (VMs) to AWS using GitHub Actions for Terraform automation.
 
 Note this README is expanded in the README folder:
 
 - [README/docs/01_overview.md](README/docs/01_overview.md)
-

README/AWS/docs/01_overview.md

@@ -0,0 +1,61 @@
+# Azure VM Deploy DocSet
+
+## Overview
+
+This project (AwsVmDeploy) uses Terraform to plan, deploy, and destory a Linux VM. This is setup to be run as a manual GitHub Actions Workflow.
+
+![diagrams/structurizr-1-AzureVM.png](diagrams/structurizr-1-AzureVM.png)
+
+Manually initiate the GitHub Action Workflow in the order below to build the VM.
+
+1. an AWS (S3) storage account to store the Terraform state file
+1. a virtual network (VPC) for hosting
+1. a linux VM with a public IP address
+
+![diagrams/structurizr-1-GitHub.png](diagrams/structurizr-1-GitHub.png)
+
+### AWS Prep
+
+Create a Service Account to run Terraform via GitHub Actions.
+
+![diagrams/structurizr-1-AzureAD.png](diagrams/structurizr-1-AzureAD.png)
+
+* [02_awsprep.md](02_awsprep.md)
+
+### GitHub Prep
+
+Numerous variables and a couple of secrets need to be setup in the GitHub environment (settings).
+
+More Info: [03_githubprep](03_githubprep)
+
+### Create TF State Storage
+
+Deploy Terraform (TF) State Storage Account using the GitHub Action workflow.
+
+* one secret: 
+   * AWS_SECRET_ACCESS_KEY
+* several variables: tenant, subsciption, location, etc.
+   * AWS_ACCESS_KEY_ID
+   * AWS_REGION
+   * CIDR_BLOCK
+   * OPS_IP1
+   * PUBKEY1
+   * STATE_SUFFIX
+   * VM_SIZE
+
+### Create Virtual Network
+
+Run the GitHub Action workflow to create (apply) the Network (AWS VPC). Use a unique CIDR block for each environment to aid administration.
+
+### Create Virtual Machine
+
+Run the GitHub Actions Worfklow to create the new VM (Virtual Machine). Variables can be used to set VM Size, the source IP address for SSH connection from the administrator, and an Authorized SSH Public Key (a new authorized SSH Key-Pair is also created by the terraform).
+
+The VM uses an Elastic (Public) IP Adress(EIP), a Network Security Group (NSG), and a Network Interface Card (NIC) to route, filter, and connect internet to the VM.
+** check this
+
+![diagrams/structurizr-1-AzureNetwork.png](diagrams/structurizr-1-AzureNetwork.png)
+
+### Connect to the VM
+
+Using the powers of SSH Keys, connect to the VM!

README/AWS/docs/02_awsprep.md

@@ -0,0 +1,30 @@
+# AWS VM Deploy DocSet
+
+## AWS Prep
+
+To deploy to AWS using Automation, some prep work is require setup a Service Account in IAM (Identity and Access Management) on AWS.
+
+GitHub Actions drive Terraform Deployments.
+
+[Login at AWS Console](https://aws.amazon.com/console/)
+
+### Create the Terraform Service Account on AWS
+
+Using the AWS (Web) Console, as needed, create a new IAM user to be used as the Service account for Terraform actions.
+
+To create a Terraform service account on AWS, you can follow the steps outlined in this [Medium article](https://gmusumeci.medium.com/how-to-create-an-iam-account-and-configure-terraform-to-use-aws-static-credentials-a8ea4dd4fdfc).
+
+The screenshot below shows the IAM User and the Access Key created for the Terraform access from Github. Scoping of permissions for that user is beyond the scope of this article. Scoping permissions is a critical part of system security.
+
+Screen Shot
+
+This command will output an application ID and password to use for this service account. Document the details in your password safe and add them to the GitHub enviornment, as needed.
+
+- AWS_ACCESS_KEY_ID - a GitHub environment variable
+- AWS_SECRET_ACCESS_KEY - a GitHub environment secret
+
+![github.env](images/github_env.png)
+
+### AWS IAM Policies
+
+Setup needed policies on user as need.

README/AWS/docs/03_githubprep.md

@@ -0,0 +1,43 @@
+# AWS VM Deploy - DocSet
+
+## GitHub Prep
+
+### On GitHub Environments
+
+Public GitHub repos and paid-for private repos can use Environments.
+
+Free and private repo do not support Environments, but you need the workflow to accept the ENV_NAME as a Variable name, as it cannot be inherited from the environment.
+
+### Setup each GitHub Environment
+
+Access the repository Settings page to setup each environment variable and secret.
+
+![github repo environments](images/github-repo-environments.png)
+
+### Variables and Secrets
+
+The following variables are needed to complete the workflow tasks (tfstate, network, vm).
+
+| Variables          | Description               |
+|--------------------|---------------------------|
+| AWS_ACCESS_KEY_ID  |                           |
+| AWS_REGION         |  AWS region name          |
+| CIDR_BLOCK         | 10.x.0.0./20 - pick x     |
+| OPS_IP1            | IP address got SSH        |
+| PUBKEY1            | Public SSH Key to Connect |
+| STATE_SUFFIX       | TF State Suffix           |
+| VM_SIZE            | Azure VM size name        |
+
+The following secrets are needed to complete the workflow tasks.
+
+| Secret            | Description                                         |
+|-------------------|-----------------------------------------------------|
+| AWS_SECRET_ACCESS_KEY | password for Terraform service account          |
+
+After the TF State account is created, retrieve a Key and add it as the secret: ARM_TFSTATE_KEY.
+
+### Example of Environment Variables
+
+The screenshot below shows the _variables_ setup for an environment in GitHub Settings.
+
+![GitHub Environment Variables](images/github-environment-variables.png)