Merge pull request #4 from d3b-center/develop

Develop

.github/workflows/continuous_integration.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - master
+      - develop
+      - feature/jrb/bootstrap
+  pull_request:
+
+jobs:
+  build:
+    name: build
+    runs-on: ubuntu-latest
+    container: hashicorp/terraform:latest
+    env:
+      DOCKER_BUILDKIT: 1
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Install Bash
+        run: apk add --no-cache bash
+
+      - name: Execute cibuild
+        run: ./scripts/cibuild

.gitignore

@@ -0,0 +1,34 @@
+# Local .terraform directories
+**/.terraform/*
+
+# .tfstate files
+*.tfstate
+*.tfstate.*
+
+# Crash log files
+crash.log
+crash.*.log
+
+# Exclude all .tfvars files, which are likely to contain sensitive data, such as
+# password, private keys, and other secrets. These should not be part of version 
+# control as they are data points which are potentially sensitive and subject 
+# to change depending on the environment.
+*.tfvars
+*.tfvars.json
+
+# Ignore override files as they are usually used to override resources locally and so
+# are not checked in
+override.tf
+override.tf.json
+*_override.tf
+*_override.tf.json
+
+# Include override files you do wish to add to version control using negated pattern
+# !example_override.tf
+
+# Include tfplan files to ignore the plan output of command: terraform plan -out=tfplan
+*tfplan*
+
+# Ignore CLI configuration files
+.terraformrc
+terraform.rc

README.md

@@ -0,0 +1,76 @@
+# terraform-aws-vpc [![CI](https://github.com/d3b-center/terraform-aws-vpc/workflows/CI/badge.svg?branch=master)](https://github.com/d3b-center/terraform-aws-vpc/actions?query=workflow%3ACI)
+
+A Terraform module to create a dual-stack (IPv4/IPv6) Amazon Web Services (AWS) Virtual Private Cloud (VPC).
+
+- [Usage](#usage)
+- [Variables](#variables)
+- [Outputs](#outputs)
+
+## Usage
+
+This module creates a VPC alongside a variety of related resources, including:
+
+- Public and private subnets.
+- Public and private route tables.
+- Elastic IPs.
+- Network interfaces.
+- NAT gateways.
+- An internet gateway and an egress-only internet gateway (for private IPv6 traffic).
+- An S3 VPC endpoint.
+- VPC endpoints to support AWS Session Manager.
+
+Example usage:
+
+```hcl
+module "vpc" {}
+  source = "github.com/d3b-center/terraform-aws-vpc"
+
+  name                               = "Default"
+  region                             = "us-east-1"
+  cidr_block                         = "10.0.0.0/16"
+  private_subnet_cidr_blocks         = ["10.0.1.0/24", "10.0.3.0/24"]
+  private_subnet_ipv6_prefix_indices = [1, 3]
+  public_subnet_cidr_blocks          = ["10.0.0.0/24", "10.0.2.0/24"]
+  public_subnet_ipv6_prefix_indices  = [0, 2]
+  availability_zones                 = ["us-east-1a", "us-east-1b"]
+
+  tags = {}
+}
+```
+
+See the [examples](./examples/) directory for a complete implementation.
+
+### Connecting to the Bastion with Session Manager
+
+After copying the bastion instance ID from the AWS Console, you can start a session:
+
+```console
+$ aws ssm start-session --target i-0471c64f8747dadae
+
+Starting session with SessionId: iamuser-0f4532b020626b7be
+sh-4.2$
+```
+
+For information about accessing other VPC resources, see [How can I use an SSH tunnel through AWS Systems Manager to access my private VPC resources?](https://aws.amazon.com/premiumsupport/knowledge-center/systems-manager-ssh-vpc-resources/)
+
+
+## Variables
+
+- `name` - A name for the VPC (default: `Default`).
+- `region` - A valid AWS region to house VPC resources.
+- `cidr_block` - The CIDR range for the entire VPC (default: `10.0.0.0/16`).
+- `public_subnet_cidr_blocks` - A list of CIDR ranges for public subnets (default: `["10.0.0.0/24", "10.0.2.0/24"]`).
+- `public_subnet_ipv6_prefix_indices` - A list of indices corresponding to IPv6 prefixes for public subnets (default: `[0, 2]`).
+- `private_subnet_cidr_blocks` - A list of CIDR ranges for private subnets (default: `["10.0.1.0/24", "10.0.3.0/24"]`).
+- `private_subnet_ipv6_prefix_indices` - A list of indices corresponding to IPv6 prefixes for public subnets (default: `[1, 3]`).
+- `availability_zones` - A list of availability zones for subnet placement (default: `["us-east-1a", "us-east-1b"]`).
+- `tags` - A mapping of keys and values to apply as tags to all resources that support them (default: `{}`).
+
+## Outputs
+
+- `id` - ID of the VPC.
+- `public_subnet_ids` - A list of VPC public subnet IDs.
+- `private_subnets_ids` - A list of VPC private subnet IDs.
+- `cidr_block` - The CIDR range for the entire VPC.
+- `ipv6_cidr_block` - The IPv6 CIDR range for the entire VPC.
+- `nat_gateway_ips` - Public IP addresses of the VPC NAT gateways.

examples/README.md

@@ -0,0 +1,61 @@
+# Example Project
+
+This directory contains an example project demonstrating usage of our VPC module, including:
+
+* Provider-level tagging using [`default_tags`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/guides/resource-tagging#propagating-tags-to-all-resources).
+* A security group rule that allows the bastion instance to make HTTPS requests.
+* Changing the default working directory and shell for AWS Systems Manager to `~` and `/bin/bash`.
+
+- [Overview](#overview)
+- [Getting Started](#getting-started)
+  - [Dependencies](#dependencies)
+  - [Instructions](#instructions)
+
+## Overview
+
+The `terraform` directory contains a Terraform project.
+
+The `scripts` directory contains one script:
+- `infra` is a wrapper for the `terraform` command that also manages initialization.
+
+## Getting Started
+
+### Dependencies
+
+- AWS CLI 2.4+
+- Docker 20.10+
+- Docker Compose 2.2+
+
+### Instructions
+
+First, copy the following file, renaming it to `terraform-aws-vpc.tfvars` in the process:
+
+```console
+cp terraform/terraform-aws-vpc.tfvars.example terraform/terraform-aws-vpc.tfvars
+```
+
+Then, customize its contents with a text editor:
+
+- For project, use your name in title case.
+
+Here's an example of a customized `terraform-aws-vpc.tfvars`:
+
+```hcl
+project = "JohnAmazon"
+environment = "Staging"
+region = "us-east-1"
+```
+
+Next, launch an instance of the included Terraform container image:
+
+```console
+export AWS_PROFILE=sandbox
+docker-compose run --rm terraform
+bash-5.1#
+```
+
+Once inside the context of the container image, use `infra` to generate a Terraform plan:
+
+```console
+bash-5.1# ./scripts/infra plan
+```

examples/docker-compose.yml

@@ -0,0 +1,11 @@
+services:
+  terraform:
+    image: ghcr.io/d3b-center/terraform:1.1.6
+    volumes:
+      - ../:/usr/local/src
+      - $HOME/.aws:/.aws
+    environment:
+      - AWS_PROFILE
+      - TERRAFORM_AWS_VPC_DEBUG=1
+    working_dir: /usr/local/src/examples
+    entrypoint: bash

examples/scripts/infra

@@ -0,0 +1,50 @@
+#!/bin/bash
+
+set -e
+
+if [[ -n "${TERRAFORM_AWS_VPC_DEBUG}" ]]; then
+    set -x
+fi
+
+function usage() {
+    echo -n \
+        "Usage: $(basename "$0") COMMAND OPTION[S]
+Execute Terraform subcommands.
+"
+}
+
+if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
+    if [[ "${1:-}" == "--help" ]]; then
+        usage
+    else
+        TERRAFORM_DIR="$(dirname "$0")/../terraform"
+
+        pushd "${TERRAFORM_DIR}"
+
+        case "${1}" in
+        plan)
+            # Clear stale modules, then re-initialize.
+            rm -rf .terraform
+            terraform init
+
+            terraform plan \
+                -var-file="terraform-aws-vpc.tfvars" \
+                -out="terraform-aws-vpc.tfplan"
+            ;;
+        apply)
+            terraform apply "terraform-aws-vpc.tfplan"
+            ;;
+        destroy)
+            terraform destroy \
+                -var-file="terraform-aws-vpc.tfvars" \
+                -auto-approve
+            ;;
+        *)
+            echo "ERROR: I don't have support for that Terraform subcommand!"
+            exit 1
+            ;;
+        esac
+
+        popd
+    fi
+fi

examples/terraform/config.tf

@@ -0,0 +1,10 @@
+provider "aws" {
+  region = var.region
+
+  default_tags {
+    tags = {
+      Project     = var.project
+      Environment = var.environment
+    }
+  }
+}

examples/terraform/firewall.tf

@@ -0,0 +1,13 @@
+#
+# Bastion security group resources
+#
+resource "aws_security_group_rule" "bastion_https_egress" {
+  type             = "egress"
+  from_port        = 443
+  to_port          = 443
+  protocol         = "tcp"
+  cidr_blocks      = ["0.0.0.0/0"]
+  ipv6_cidr_blocks = ["::/0"]
+
+  security_group_id = module.vpc.bastion_security_group_id
+}

examples/terraform/network.tf

@@ -0,0 +1,36 @@
+#
+# VPC resources
+#
+data "aws_ami" "amazon_linux" {
+  most_recent = true
+  owners      = ["amazon"]
+
+  filter {
+    name   = "name"
+    values = ["amzn2-ami-hvm*"]
+  }
+}
+
+module "vpc" {
+  source = "../../"
+
+  name        = join("", ["vpc", var.environment, var.project])
+  region      = var.region
+  bastion_ami = data.aws_ami.amazon_linux.id
+}
+
+resource "aws_ssm_document" "default" {
+  name          = "SSM-SessionManagerRunShell"
+  document_type = "Session"
+
+  content = jsonencode({
+    schemaVersion = "1.0"
+    description   = "Document to hold regional settings for Session Manager"
+    sessionType   = "Standard_Stream"
+    inputs = {
+      shellProfile = {
+        linux = "cd ~ && /usr/bin/env bash"
+      }
+    }
+  })
+}

examples/terraform/terraform-aws-vpc.tfvars.example

@@ -0,0 +1,3 @@
+project = "Example"
+environment = "Staging"
+region = "us-east-1"

examples/terraform/variables.tf

@@ -0,0 +1,15 @@
+variable "project" {
+  type        = string
+  description = "A project namespace for the infrastructure."
+}
+
+variable "environment" {
+  type        = string
+  description = "An environment namespace for the infrastructure."
+}
+
+variable "region" {
+  type        = string
+  default     = "us-east-1"
+  description = "A valid AWS region to configure the underlying AWS SDK."
+}

examples/terraform/versions.tf

@@ -0,0 +1,10 @@
+terraform {
+  required_version = ">= 1.1.6"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 4.2.0"
+    }
+  }
+}