tfctl 0.2.0 → 1.2.1

data/docs/control_tower.adoc

@@ -1,17 +1,37 @@
-:toc:
-
-== Control Tower integration guide
+// Settings:
+:idprefix:
+:idseparator: -
+ifndef::env-github[:icons: font]
+ifdef::env-github,env-browser[]
+:toc: macro
+:toclevels: 1
+endif::[]
+ifdef::env-github[]
+:branch: master
+:status:
+:outfilesuffix: .adoc
+:!toc-title:
+:caution-caption: :fire:
+:important-caption: :exclamation:
+:note-caption: :paperclip:
+:tip-caption: :bulb:
+:warning-caption: :warning:
+endif::[]
+
+= Control Tower integration guide
 
 This guide will help you integrate Terraform with AWS Control Tower using the
 tfctl wrapper.  This involves setting up resources for remote state tracking,
 necessary IAM roles and a tfctl project.
 
-=== Overview
+toc::[]
+
+== Overview
 
 For state tracking we're going to create a dedicated `shared-services` account
 under a `mgmt` organization unit.  We'll use S3 for state storage and DynamoDB
 for locking.  `TerraformState` IAM role will be created for cross account
-access to state resources from the primary account.
+access to state resources from the primary AWS account.
 
 In the primary account we'll create a `TfctlOrgAccess` role.  It gives tfctl
 read only access to AWS Organizations which is used to discover accounts and
@@ -26,16 +46,17 @@ account factory and can be assumed from the primary account.
 We're going to create a `live` and `test` organization units in Control Tower
 and provision a couple of accounts for testing.
 
-=== Prerequisites
+== Prerequisites
 
 Before starting you'll need:
 
- * Control Tower set up in your primary account.
- * A user with `AdministratorAccess` privileges in primary account.
- * AWS CLI tools installed on your machine.
+ * An AWS account that is part of an Organization.
+ * Control Tower set up in your primary AWS account.
+ * A user with `AdministratorAccess` privileges in your primary AWS account.
+ * AWS CLI tools installed on your local machine.
  * Terraform 0.12 or higher.
 
-=== Configure Control Tower
+== Configure Control Tower
 
 Create the following organization units in Control Tower:
 
@@ -52,30 +73,35 @@ Then provision accounts:
 NOTE: Control Tower accounts need to be provisioned one at a time.  It takes
 approximately 20 mins to provision one.
 
-=== Install tfctl
+== Install tfctl
 
+[source,shell]
 ----
 git clone git@github.com:scalefactory/tfctl.git
 cd tfctl/ && sudo make install
 ----
 
-=== Set up AWS resources
+== Set up AWS resources
 
 It's assumed you have configured AWS CLI access to the primary account.
 
 We'll use CloudFormation templates in `examples/bootstrap/`.
 
-First export configuration using environment variables making sure to change to
-values to suit your set up:
+First export configuration using environment variables, making sure to change to
+values to suit your setup:
 
+[source,shell]
 ----
-export PRIMARY_ACCOUNT_ID=11111111
-export SHARED_SERVICES_ACCOUNT_ID=22222222
+# Change these to match your setup
+export PRIMARY_ACCOUNT_ID=123456789012
+export SHARED_SERVICES_ACCOUNT_ID=345678901234
 export STATE_BUCKET_NAME='example-terraform-state'
+export AWS_REGION=eu-west-1
 ----
 
 Create the remote state resources stack set:
 
+[source,shell]
 ----
 cd examples/bootstrap/
 
@@ -87,31 +113,34 @@ aws cloudformation create-stack-set \
     --execution-role-name AWSControlTowerExecution \
     --administration-role-arn arn:aws:iam::${PRIMARY_ACCOUNT_ID}:role/service-role/AWSControlTowerStackSetRole \
     --parameters ParameterKey=PrimaryAccountId,ParameterValue=${PRIMARY_ACCOUNT_ID} \
-    ParameterKey=TerraformStateBucket,ParameterValue=${STATE_BUCKET_NAME}
+    ParameterKey=TerraformStateBucket,ParameterValue="${STATE_BUCKET_NAME}"
 ----
 
-Create a stack set instance in you shared services account:
+Create a stack set instance in your shared services account:
 
+[source,shell]
 ----
 aws cloudformation create-stack-instances \
     --stack-set-name TerraformState \
     --accounts ${SHARED_SERVICES_ACCOUNT_ID} \
-    --regions eu-west-1
+    --regions ${AWS_REGION}
 ----
 
 Check status:
 
+[source,shell]
 ----
 aws cloudformation describe-stack-instance \
     --stack-set-name TerraformState \
     --stack-instance-account ${SHARED_SERVICES_ACCOUNT_ID} \
-    --stack-instance-region eu-west-1
+    --stack-instance-region ${AWS_REGION}
 ----
 
 NOTE: Initial status will be `OUTDATED`, it should change to `CURRENT` once deployed.
 
-Deploy `TfctlOrgAccess` IAM role stack:
+Deploy the `TfctlOrgAccess` IAM role stack:
 
+[source,shell]
 ----
 aws cloudformation create-stack \
     --stack-name TfctlOrgAccess \
@@ -122,70 +151,79 @@ aws cloudformation create-stack \
 
 Check status:
 
+[source,shell]
 ----
 aws cloudformation describe-stacks --stack-name TfctlOrgAccess
 ----
 
 NOTE: Successful status should read: `CREATE_COMPLETE`.
 
-=== Configure tfctl
+== Configure tfctl
 
 Copy the example project directory `examples/control_tower` somewhere convenient
-and edit `conf/example.yaml`.
+and edit `tfctl.yaml`.
 
 You need to modify the following parameters:
 
  * `tf_state_bucket` - set to `$STATE_BUCKET_NAME`
  * `tf_state_role_arn` - set shared services account ID
  * `tfctl_role_arn` - set primary account ID
- * `primary_account` - set the primary account name.  You can find it in AWS Organizations.
+ * `primary_account` - set the primary account name.  You can find it through AWS Organizations in the console.
 
 TIP: You should keep your project directory under version control.
 
-=== Deploy example tfctl profile
+== Deploy example tfctl profile
 
 The example profile will create an S3 bucket in accounts under `test`, `live`
 and `mgmt` OUs.
 
 NOTE: Run tfctl commands from the root of you project directory.
 
-First dump the configuration to verify everything works:
+First, dump the configuration to verify everything works:
 
+[source,shell]
 ----
-tfctl -c conf/example.yaml -s
+tfctl -s
 ----
 
-This will not make any changes but will print out a yaml containing the final,
+This will not make any changes but will print out YAML containing the final,
 merged configuration data.  It should contain a list of discovered accounts and
 their configuration.
 
-Initialise terraform for all discovered accounts:
+Initialise Terraform for all discovered accounts:
 
+[source,shell]
 ----
-tfctl -c conf/example.yaml --all -- init
+tfctl --all -- init
 ----
 
 Tfctl will run Terraform against all accounts in parallel.
 
-Run plan:
+`plan` the Terraform:
 
+[source,shell]
 ----
-tfctl -c conf/example.yaml --all -- plan
+tfctl --all -- plan
 ----
 
-and apply:
+and `apply` it:
 
+[source,shell]
 ----
-tfctl -c conf/example.yaml --all -- apply
+tfctl --all -- apply
 ----
 
-To destroy created resources run:
 
+== Clean up
+
+To destroy created resources, run:
+
+[source,shell]
 ----
-tfctl -c conf/example.yaml --all -- destroy -auto-approve
+tfctl --all -- destroy -auto-approve
 ----
 
-That's it! You can now execute terraform across your Control Tower estate.
+That's it! You can now execute Terraform across your Control Tower estate.
 
 TIP: Your project directory should be under version control excluding the
 `.tfctl` directory which is automatically generated.

data/docs/creating_a_profile.adoc

@@ -1,9 +1,31 @@
-== Creating and deploying a tfctl profile
+// Settings:
+:idprefix:
+:idseparator: -
+ifndef::env-github[:icons: font]
+ifdef::env-github,env-browser[]
+:toc: macro
+:toclevels: 1
+endif::[]
+ifdef::env-github[]
+:branch: master
+:status:
+:outfilesuffix: .adoc
+:!toc-title:
+:caution-caption: :fire:
+:important-caption: :exclamation:
+:note-caption: :paperclip:
+:tip-caption: :bulb:
+:warning-caption: :warning:
+endif::[]
+
+= Creating and deploying a tfctl profile
 
 This guide will show you how to create a tfctl profile, declare some resources
 in it and deploy it to to a group of accounts in an organization unit.
 
-=== Create a new profile
+toc::[]
+
+== Create a new profile
 
 In your tfctl project directory create a new profile:
 
@@ -59,7 +81,7 @@ profile.  Tfctl configuration can be accessed using this variable. This It
 includes an array of all discovered accounts as well their parameters from
 tfctl config file.
 
-TIP: You can run `tfctl -c conf/CONFIG_FILE.yaml -s` to show the config data in
+TIP: You can run `tfctl -s` to show the config data in
 yaml format.  This exact data is available in the `config` variable in your
 profile.
 
@@ -87,7 +109,7 @@ resource "aws_s3_bucket" "example" {
 This will create an S3 bucket with a name containing the current account name
 (which will vary depending on which account it's deployed to).
 
-=== Assign profile to accounts
+== Assign profile to accounts
 
 Before you can deploy the new profile you need to tell `tfctl` which accounts
 to deploy it to.
@@ -102,7 +124,7 @@ You have few options here:
 For the sake of this example we're going to deploy our bucket to all accounts
 in `test` OU.
 
-In tfctl config file add the profile to the `test` OU:
+In `tfctl.yaml` add the profile to the `test` OU:
 
 [source, yaml]
 ----
@@ -113,13 +135,13 @@ organization_units:
 ----
 
 
-=== Plan
+== Plan
 
 To see what would happen when the change is applied run:
 
 ----
-tfctl -c conf/example.yaml -o test -- init
-tfctl -c conf/example.yaml -o test -- plan
+tfctl -o test -- init
+tfctl -o test -- plan
 ----
 
 This will run `terraform init` to initialise terraform and then `terraform
@@ -161,9 +183,9 @@ what went wrong.
 tfctl will generate a plan file automatically and use it with `apply` in the
 next step.
 
-=== Apply
+== Apply
 
 Once you're happy with the plan, apply it.
 ----
-tfctl -c conf/example.yaml -o test -- apply
+tfctl -o test -- apply
 ----

data/docs/iam_permissions.adoc

@@ -1,6 +1,26 @@
-== IAM roles
+// Settings:
+:idprefix:
+:idseparator: -
+ifndef::env-github[:icons: font]
+ifdef::env-github,env-browser[]
+:toc: macro
+:toclevels: 1
+endif::[]
+ifdef::env-github[]
+:branch: master
+:status:
+:outfilesuffix: .adoc
+:!toc-title:
+:caution-caption: :fire:
+:important-caption: :exclamation:
+:note-caption: :paperclip:
+:tip-caption: :bulb:
+:warning-caption: :warning:
+endif::[]
 
-Tfctl usually requires three IAM roles to be configured:
+= IAM roles
+
+`tfctl` usually requires three IAM roles to be configured:
 
  * `TfctlRole` - read only access to AWS Organizations set up in the primary account.
  * `TerraformStateRole` - access to remote state resources (S3, DynamoDB) in the
@@ -8,7 +28,7 @@ Tfctl usually requires three IAM roles to be configured:
  * `TerraformExecutionRole` - configured in all spoke accounts and used for executing Terraform.
 
 The user executing tfctl needs permission to assume all three roles cross
-account.  Tfctl will assume roles automatically for you.
+account. Once these are configured, tfctl automatically assumes roles for you.
 
 It's possible to configure different Terraform execution roles in different
 spoke accounts based on OU or account names.  This can be used to restrict

data/docs/project_layout.adoc

@@ -1,10 +1,29 @@
-== Project layout
+// Settings:
+:idprefix:
+:idseparator: -
+ifndef::env-github[:icons: font]
+ifdef::env-github,env-browser[]
+:toc: macro
+:toclevels: 1
+endif::[]
+ifdef::env-github[]
+:branch: master
+:status:
+:outfilesuffix: .adoc
+:!toc-title:
+:caution-caption: :fire:
+:important-caption: :exclamation:
+:note-caption: :paperclip:
+:tip-caption: :bulb:
+:warning-caption: :warning:
+endif::[]
+
+= Project layout
 
 Example project structure
 ----
 project_dir/
-├── conf
-│   └── example.yaml
+├── tfctl.conf
 ├── modules
 │   └── s3-bucket
 │       ├── main.tf
@@ -16,7 +35,9 @@ project_dir/
         └── variables.tf
 ----
 
-=== tfctl configuration file
+toc::[]
+
+== tfctl configuration file
 
 Assigns Terraform profiles and configuration to accounts based on:
 
@@ -29,7 +50,12 @@ The configuration data is exposed to terraform via a profile `config` variable.
 It also defines Terraform and tfctl configuration such as state tracking and
 what IAM roles to use.
 
-=== profiles
+By default, tfctl will use `tfctl.yaml` in its current working directory.  You
+can specify a different file using `-c`.  Multiple configurations are supported
+in the same project directory and generated data will be stored separately for
+each config file in `.tfctl/`.
+
+== `profiles`
 
 Profiles are re-usable collections of resources which can be applied to
 accounts.  They are implemented just like usual modules but provide an
@@ -38,6 +64,6 @@ other data sources).  Profiles often compose multiple modules and provide
 configuration data to them.  This approach makes it possible to re-use standard
 modules (e.g. Terraform module registry).
 
-=== modules
+== `modules`
 
 Standard Terraform modules.

data/examples/control_tower/{conf/example.yaml → tfctl.yaml}

@@ -12,8 +12,6 @@
 # Terraform configuration
 #
 
-# State management
-
 tf_state_bucket: 'CHANGEME'
 tf_state_dynamodb_table: 'terraform-lock'
 tf_state_region: 'eu-west-1'
@@ -26,47 +24,57 @@ aws_provider_version: '>= 2.14'
 tfctl_role_arn: 'arn:aws:iam::PRIMARY_ACCOUNT_ID:role/TfctlRole'
 
 #
-# Organization configuration
+# Data
+#
+# Here you can add arbitrary data which will be accessible from Terraform
+# profiles.  Data can also be defined per account in the organization sections
+# below.
 #
+# data:
+#   my_parameter: some_value
 
+#
+# Organization configuration
+#
+# Assign resources and data to accounts based on the organization structure.
+#
 # IMPORTANT: Removing a Terraform profile here will remove all of it's
-#            associated resources in AWS!
-
-# Name of the primary account.
-primary_account: CHANGEME
+#            associated resources during next apply!
 
-# Configuration to apply in all accounts
+# Configuration to apply to all accounts
 organization_root:
-
   # Role assumed by Terraform for execution in each account
   tf_execution_role: 'AWSControlTowerExecution'
   region: 'eu-west-1'
-  # Bucket name used by example profile it will be prefixed with the target
-  # account number for uniqueness across accounts.
-  example_bucket_name: 'tfctl-example-bucket'
+  data:
+    # Bucket name used by example profile it will be prefixed with the target
+    # account number for uniqueness across accounts.
+    example_bucket_name: 'tfctl-example-bucket'
   # Assign example-profile to all accounts in managed OUs
   profiles:
     - example-profile
 
 # Configuration to apply to accounts in Organization Units
-# Units not listed here will be ignored
+# OU's not listed here will be ignored.
 organization_units:
-  # Uncomment if you want to include Core OU accounts
-  # Core: {}
+  # Core: {} # Uncomment if you want to include Core OU accounts
   live: {}
   test: {}
   mgmt:
-    # Override the example bucket name in mgmt OU accounts
-    example_bucket_name: 'tfctl-ou-override-example'
+    data:
+      # Override the example bucket name in mgmt OU accounts
+      example_bucket_name: 'tfctl-ou-override-example'
 
 # Configuration to apply to individual accounts
 account_overrides:
   test-example1:
-    # Override the bucket name in a specific account
-    example_bucket_name: 'tfctl-account-override-example'
+    data:
+      # Override the bucket name in a specific account
+      example_bucket_name: 'tfctl-account-override-example'
 
 
-# Exclude individual accounts from Terraform runs.
-#exclude_accounts:
-#   - Audit
-#   - 'Log archive'
+# Exclude individual accounts from Terraform runs
+#
+# exclude_accounts:
+#    - Audit
+#    - 'Log archive'