Document process

.gitignore

@@ -0,0 +1,8 @@
+.envrc
+.build-harness
+build-harness
+repos/
+accounts/
+.terraform
+terraform.tfstate
+terraform.tfstate.backup

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2018 Cloud Posse, LLC
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

Makefile

@@ -0,0 +1,24 @@
+# Import the cloudposse/build-harness
+include $(shell curl -sSL -o .build-harness "https://git.io/build-harness"; echo .build-harness)
+include tasks/Makefile.*
+
+# Run time environment passed to terraform
+export TF_VAR_repos_dir ?= $(CURDIR)/repos
+export TF_VAR_templates_dir ?= $(CURDIR)/templates
+
+# The target called when calling `make` with no arguments
+export DEFAULT_HELP_TARGET = help/short
+
+# The command we'll use to start the container 
+export DOCKER_RUN = docker run -it -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -v $(CURDIR)/artifacts:/artifacts -v $(CURDIR)/scripts:/scripts 
+
+# The directory containing configs
+export CONFIGS ?= configs
+
+## Clean up 
+clean::
+	rm -rf repos accounts .terraform terraform.tfstate*
+
+fmt:
+	find $(CONFIGS) -type f -name '*.tfvars' -exec terraform fmt {} \;
+	terraform fmt modules

README.md

@@ -1,2 +1,174 @@
 # reference-architectures
-Get up and running quickly with one of our reference architecture using our cold start process.
+
+Get up and running quickly with one of our reference architecture using our cold start process. 
+
+This is still under active development and subject to change. 
+
+## Known Limitations
+
+* AWS does not support programatic deletion of accounts. This means that if you use this project to create the account structure, terraform is not able to completely destroy it.
+
+__WARNING:__ Terraform cannot remove an AWS account from an organization. Terraform will not close the account. The member account must be prepared to be a standalone account beforehand. See the [AWS Organizations documentation](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_accounts_remove.html) for more information.
+
+## High Level Overview
+
+You can provision the basic referrence architecutre in 3 "easy" steps. =)
+
+All steps leverage our [`terraform-root-modules`](https://github.com/cloudposse/terraform-root-modules/) to get started.
+
+This process involves using terraform to generate the code (`Dockerfile`, `Makefile`, `terraform.tfvar`, etc) you will use to manage your infrastructure. 
+
+This is a "bootstrap" process. You do it once and then you throw *this* repo away.
+
+## Architecture
+
+Our "reference architecture" is an opinionated approach to architecting accounts for AWS. 
+
+This process provisions (7) accounts which have different designations. 
+
+Here is what it includes.
+
+| Account | Description                                                                          |
+|---------|--------------------------------------------------------------------------------------|
+| root    | The "root" (parent) account creates all child accounts and is where users login      |
+| prod    | The "production" is account where you run your most mission critical applications    |
+| staging | The "staging" account is where you run all of your QA/UAT/Testing                    |
+| dev     | The "dev" sandbox account is where you let your developers have fun and break things |
+| audit   | The "audit" account is where all logs end up.                                        |
+| corp    | The "corp" account is where you run platform services for the company                |
+| data    | The "data" account is where the quants live =)                                       |
+
+Each account has its own [terraform state backend](https://github.com/cloudposse/terraform-aws-tfstate-backend), along with a [dedicated DNS zone](https://www.terraform.io/docs/providers/aws/r/route53_zone.html) for service discovery.
+
+The root account owns the top-level DNS zone and then delegates NS authority to each child account.
+
+### Assumptions
+
+1. We are starting with a clean AWS environment and a new "root" (top-level) AWS account. This means you need the "root" credentials, since a fresh AWS account doesn't even have any AWS roles that can be assumed.
+2. You have administrator access to this account
+3. You have [docker](https://docs.cloudposse.com/tools/docker/) installed on your workstation
+4. You have [terraform](https://www.terraform.io/downloads.html) installed on your workstation
+
+
+### Checklist
+
+Before we get started, make sure you have the following
+
+- [ ] Clone this repo on your workstation
+- [ ] Create a *temporary* pair of [Access Keys](https://console.aws.amazon.com/iam/home#/security_credential). These should be deleted afterwards.
+- [ ] Export your AWS "root" account credentials as `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` (this is *temporary* for bootstrapping)
+- [ ] An available domain we can use for DNS-base service discovery (E.g. `ourcompany.co`). This domain must not be in use else where.
+
+### 1. Provision Root Account
+
+The "root" account is the top-most AWS account from which all other AWS accounts are programatically created.
+
+This account is provisioned slightly different from the other subccounts.
+
+Update the configuration for this account by editing the `configs/root.tfvar` file.
+
+Then to get started, run:
+
+```
+make root
+```
+
+__NOTE:__ We need to know each account's `AWS_ACCOUNT_ID` for Step 2.
+
+<details>
+  <summary>Here's the pseudo code of what that roughly looks like (but automated). </summary>
+
+```
+| mkdir repo
+| cd repo
+| git init
+| Render dockerfile from template
+|   (Use multi-stage for tfstate, accounts, root-dns)
+| Build docker image
+| Docker run the image mounting `scripts/` and `artifacts/`
+|   Setup AWS vault
+|   aws-vault exec ${AWS_PROFILE} -- /scripts/init-tfstate
+|   aws-vault exec ${AWS_PROFILE} -- /scripts/init-accounts
+```
+
+</details>
+
+### 2. Provision Subaccounts
+
+Subaccounts are created by the root account, but are ultimately provisioned using the subaccount containers.
+
+Update the configuration for all the child accounts by editing the `configs/root.tfvar` file.
+
+To get started, run: 
+
+```
+make children
+```
+
+<details>
+
+<summary>Here's the pseudo code of what that roughly looks like (but automated).</summary>
+
+```
+for account in ${ACCOUNTS}; do
+  mkdir $account
+  cd $account
+  git init
+  # Render dockerfile from template
+  # Use multi-stage for tfstate and account-dns
+  # Build docker image
+  # Docker run the image -v scripts/:/scripts
+  # Setup AWS vault
+  # assume-role
+  # init tfstate
+  # init account-dns
+  cd ..
+done
+```
+</details>
+
+### 3. Delegate DNS
+
+Now that each subaccount has been provisioned, we can delegate each DNS zone to those accounts.
+
+To finish up, run:
+
+```
+make root/finalize
+```
+
+
+<details>
+<summary>Here's the pseudo code of what that roughly looks like (but automated).</summary>
+
+```
+# Docker run the image
+# assume role
+# init tfstate
+# init accounts
+```
+</details>
+
+---
+
+## Next Steps
+
+At this point, you have everything you need to start terraforming your way to success.
+
+All of your account configurations are currently in `repos/`
+
+1. Commit the changes in `repos/`. Open Pull Requests.
+
+2. Ensure that the nameservers for the service discovery domain (e.g. `ourcompany.co`) have been configured with your domain registrar (e.g. GoDaddy)
+
+3. Delete your root account credentials. They are no longer need and should not be used. Instead use IAM users.
+
+4. Consider adding some other capabilities from our service catalog.
+
+5. Create your own [`terraform-root-modules`](https://github.com/cloudposse/terraform-root-modules) service catalog for your organization
+
+__NOTE:__ *This* repo can be deleted once you're all done and pushed your changes to GitHub. The rest of your development will happen inside your infrastructure repos.
+
+## Getting Help?
+
+Did you get stuck? Find us on [slack](https://sweetops.cloudposse.com) in the `#geodesic` channe channell

configs/README.md

@@ -0,0 +1 @@
+Update these configurations to suit your environment

configs/audit.tfvars

@@ -0,0 +1,15 @@
+# This is a terraform configuration file
+
+stage = "testing"
+
+# List of templates to install
+templates = ["Dockerfile.child", ".gitignore", ".dockerignore", "Makefile", "conf/Makefile"]
+
+# List of terraform root modules to enable
+terraform_root_modules = [
+  "aws/tfstate-backend",
+  "aws/account-dns",
+  "aws/chamber",
+  "aws/audit-cloudtrails",
+  "aws/cloudtrails",
+]

configs/corp.tfvars

@@ -0,0 +1,14 @@
+# This is a terraform configuration file
+
+stage = "corp"
+
+# List of templates to install
+templates = ["Dockerfile.child", ".gitignore", ".dockerignore", "Makefile", "conf/Makefile"]
+
+# List of terraform root modules to enable
+terraform_root_modules = [
+  "aws/tfstate-backend",
+  "aws/account-dns",
+  "aws/chamber",
+  "aws/cloudtrails",
+]

configs/data.tfvars

@@ -0,0 +1,14 @@
+# This is a terraform configuration file
+
+stage = "data"
+
+# List of templates to install
+templates = ["Dockerfile.child", ".gitignore", ".dockerignore", "Makefile", "conf/Makefile"]
+
+# List of terraform root modules to enable
+terraform_root_modules = [
+  "aws/tfstate-backend",
+  "aws/account-dns",
+  "aws/chamber",
+  "aws/cloudtrails",
+]

configs/dev.tfvars

@@ -0,0 +1,14 @@
+# This is a terraform configuration file
+
+stage = "dev"
+
+# List of templates to install
+templates = ["Dockerfile.child", ".gitignore", ".dockerignore", "Makefile", "conf/Makefile"]
+
+# List of terraform root modules to enable
+terraform_root_modules = [
+  "aws/tfstate-backend",
+  "aws/account-dns",
+  "aws/chamber",
+  "aws/cloudtrails",
+]

configs/prod.tfvars

@@ -0,0 +1,14 @@
+# This is a terraform configuration file
+
+stage = "prod"
+
+# List of templates to install
+templates = ["Dockerfile.child", ".gitignore", ".dockerignore", "Makefile", "conf/Makefile"]
+
+# List of terraform root modules to enable
+terraform_root_modules = [
+  "aws/tfstate-backend",
+  "aws/account-dns",
+  "aws/chamber",
+  "aws/cloudtrails",
+]

configs/root.tfvars

@@ -0,0 +1,63 @@
+# This is a terraform configuration file
+
+# The "apex" service discovery domain for *all* infrastructure
+domain = "test.co"
+
+# The global namespace that should be shared by all accounts
+namespace = "test"
+
+# The default region for this account
+aws_region = "us-west-2"
+
+# The docker registry that will be used for the images built (nothing will get pushed)
+docker_registry = "cloudposse"
+
+# The templates to use for this account
+templates = [
+  "Dockerfile.root",
+  ".gitignore",
+  ".dockerignore",
+  "Makefile",
+  "conf/Makefile",
+  "conf/accounts/terraform.tfvars",
+  "conf/iam/terraform.tfvars",
+  "conf/root-dns/terraform.tfvars",
+]
+
+# Account email address format (e.g. `ops+%s@example.co`). This is not easily changed later.
+account_email = "ops+%s@test.co"
+
+# List of accounts to enable
+accounts_enabled = [
+  "dev",
+  "staging",
+  "prod",
+  "testing",
+  "data",
+  "corp",
+  "audit",
+]
+
+# Terraform Root Modules Image (don't change this unless you know what you're doing)
+#   https://github.com/cloudposse/terraform-root-modules
+terraform_root_modules_image = "cloudposse/terraform-root-modules:0.11.0"
+
+# Geodesic Base Image (don't change this unless you know what you're doing)
+#   https://github.com/cloudposse/geodesic
+geodesic_base_image = "cloudposse/geodesic:0.46.0"
+
+# List of terraform root modules to enable
+terraform_root_modules = [
+  "aws/tfstate-backend",
+  "aws/root-dns",
+  "aws/root-iam",
+  "aws/organization",
+  "aws/accounts",
+  "aws/account-settings",
+  "aws/iam",
+  "aws/users",
+  "aws/cloudtrail",
+]
+
+# Message of the Day
+motd_url = "https://geodesic.sh/motd"

configs/staging.tfvars

@@ -0,0 +1,14 @@
+# This is a terraform configuration file
+
+stage = "staging"
+
+# List of templates to install
+templates = ["Dockerfile.child", ".gitignore", ".dockerignore", "Makefile", "conf/Makefile"]
+
+# List of terraform root modules to enable
+terraform_root_modules = [
+  "aws/tfstate-backend",
+  "aws/account-dns",
+  "aws/chamber",
+  "aws/cloudtrails",
+]

configs/testing.tfvars

@@ -0,0 +1,14 @@
+# This is a terraform configuration file
+
+stage = "testing"
+
+# List of templates to install
+templates = ["Dockerfile.child", ".gitignore", ".dockerignore", "Makefile", "conf/Makefile"]
+
+# List of terraform root modules to enable
+terraform_root_modules = [
+  "aws/tfstate-backend",
+  "aws/account-dns",
+  "aws/chamber",
+  "aws/cloudtrails",
+]

modules/README.md

@@ -0,0 +1 @@
+This directory contains modules used to create all the scaffolding. It's basically a code generator which creates directories, `Dockerfiles` and builds docker images.