tfctl 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6f58a8ef8569aaec8cc41ad269adf690caca7d13472a26ed65ed846c835273c
-  data.tar.gz: '013649daccb576adbe4c0c95c8fe64347b641dcb07ad2f0d3e5ca1420188489c'
+  metadata.gz: b7a1d287bce54f0203c80b4814f67ddb3d5f38319796a185a69ccf1fe1b65f02
+  data.tar.gz: 924e81046fde7a921f66959893429c10fbcffd8a3f32e1b6257cde2935c1b5d1
 SHA512:
-  metadata.gz: 2a65943659c0dabe88c40d76d46a99ed23f1ef335486c719729ca599e10e60b2abc0bc81577f2490ca7bbbe64e479ab641b0197a1160b7a1e061f274f224419b
-  data.tar.gz: 8c0cebbab4bc2738357979d1fa013bbf485ea398a3c5ecfdbb4ab9bf670060660a890b900cfca8425764c1387d4ffe5c0d0c50d3a59a10f16ba4f20f3687a303
+  metadata.gz: 044ad7209c428aa8c1f7eaf11258089ed6ce304a2943b79739ba1b8337fbd6487f4cda758c73acfc9de35f17fc272ef98d74fe64c274ea4d5e0112bc1749329b
+  data.tar.gz: 22a221bb105a66c5b9512a604886eb458ff1ec2876ee8d3599f7c6c0cc5e6abb5fafd0d47aa2cd61fbc979b0ba5ca33a8f18a47a5afacfd27515ea5e333f0868

data/.rubocop.yml

@@ -1,6 +1,6 @@
 ---
 AllCops:
-  TargetRubyVersion: 2.3
+  TargetRubyVersion: 2.5
   DisplayCopNames: true
 
 Layout/IndentationWidth:
@@ -45,7 +45,7 @@ Metrics/BlockLength:
 Metrics/MethodLength:
   Enabled: false
 
-Metrics/LineLength:
+Layout/LineLength:
   Max: 140
 
 Metrics/AbcSize:
@@ -77,3 +77,7 @@ Style/TrailingCommaInHashLiteral:
 
 Style/RedundantReturn:
   Enabled: false
+
+# don't break older Rubies just because of style
+Style/RedundantBegin:
+  Enabled: false

data/.travis.yml

@@ -1,6 +1,7 @@
 rvm:
-- 2.3
+- 2.5
 - 2.6
+- 2.7
 os: linux
 language: ruby
 script: make test

data/CHANGELOG.adoc

@@ -1,5 +1,13 @@
 = Changelog
 
+== Upcoming
+
+== 1.1.1
+
+ * fix: handle empty response from Organizations API containing children (thanks @grothja)
+ * chore: stopped testing on EOL Rubies 2.3 and 2.4 (but should still currently work)
+ * chore: dependencies minimum version bump
+
 == 1.1.0
 
 * feat: look for configuration in `tfctl.yaml` by default.

data/README.adoc

@@ -28,15 +28,16 @@ toc::[]
 
 == Overview
 
-Tfctl is a small Terraform wrapper for working with multi-account AWS
+`tfctl` is a small Terraform wrapper for working with multi-account AWS
 infrastructures where new accounts may be created dynamically and on-demand.
 
-It discovers accounts by reading the AWS Organizations API and can assign
+It discovers accounts by reading the AWS Organizations API, and can assign
 Terraform resources to multiple accounts based on the organization hierarchy.
 Resources can be assigned globally, based on organization unit or to individual
-accounts.  It supports nested OU hierarchies and helps keep your Terraform DRY.
+accounts.  It supports hierarchies of nested Organizational Units (OUs),
+and helps keep your Terraform DRY.
 
-Tfctl was originally developed to integrate Terraform with
+The Scale Factory originally created tfctl to integrate Terraform with
 https://aws.amazon.com/solutions/aws-landing-zone/[AWS Landing Zone] and
 https://aws.amazon.com/controltower/[Control Tower] but should work with most
 other ways of managing accounts in AWS Organizations.
@@ -57,7 +58,7 @@ other ways of managing accounts in AWS Organizations.
 == Requirements
 
  * Terraform >= 0.12
- * Ruby >= 2.3
+ * Ruby >= 2.4
  * Accounts managed in AWS Organizations (by Landing Zone, Control Tower, some
    other means)
 
@@ -65,17 +66,19 @@ other ways of managing accounts in AWS Organizations.
 
 To install the latest release from RubyGems run:
 
+[source,shell]
 ----
 gem install tfctl
 ----
 
-Alternatively you can build and install from this repo with:
+Alternatively, you can build and install from this repo with:
 
+[source,shell]
 ----
 make install
 ----
 
-== Docs
+== Documentation
 
  * https://github.com/scalefactory/tfctl/tree/master/docs/control_tower.adoc[Control Tower quick start guide]
  * https://github.com/scalefactory/tfctl/tree/master/docs/project_layout.adoc[Project layout]
@@ -85,11 +88,12 @@ make install
 
 == Running tfctl
 
-tfctl should be run from the root of the project directory.  It will generate
-Terraform configuration in `.tfctl/`.
+You should run `tfctl` from the root of your project directory.  It will generate
+Terraform configuration in `.tfctl/` (add this to your `.gitignore`).
 
 Anatomy of a tfctl command:
 
+[source,shell]
 ----
 tfctl -c CONFIG_FILE TARGET_OPTIONS -- TERRAFORM_COMMAND
 ----
@@ -102,7 +106,7 @@ tfctl -c CONFIG_FILE TARGET_OPTIONS -- TERRAFORM_COMMAND
   options.  See https://www.terraform.io/docs/commands/index.html[Terraform
   commands] for details.
 
-NOTE: You must have your AWS credentials configured before running tfctl or run
+NOTE: You must have your AWS credentials configured before you run `tfctl`, or run
 it using an AWS credentials helper such as
 https://github.com/99designs/aws-vault[aws-vault].
 
@@ -110,18 +114,21 @@ https://github.com/99designs/aws-vault[aws-vault].
 
 Show help:
 
+[source,shell]
 ----
 tfctl -h
 ----
 
 Show merged configuration:
 
+[source,shell]
 ----
 tfctl -s
 ----
 
 List all discovered accounts:
 
+[source,shell]
 ----
 tfctl --all -l
 ----
@@ -129,49 +136,56 @@ tfctl --all -l
 TIP: This can be narrowed down using targeting options and is a good way to
 test what accounts match.
 
-Run Terraform init across all accounts:
+Run `terraform init` across all accounts:
 
+[source,shell]
 ----
 tfctl --all -- init
 ----
 
-Run plan in `test` OU accounts:
+Plan Terraform across all accounts in the `test` OU:
 
+[source,shell]
 ----
 tfctl -o test -- plan
 ----
 
-Run plan in `live` accounts assuming that `live` is a child OU in multiple
+Plan Terraform in `live` accounts, assuming that `live` is a child OU in multiple
 organization units:
 
+[source,shell]
 ----
 tfctl -o '.*/live' -- plan
 ----
 
-Run plan in an individual account:
+Run a plan for an individual account:
 
+[source,shell]
 ----
 tfctl -a example-account - plan
 ----
 
-Run apply in all accounts:
+Apply Terraform changes across all accounts:
 
+[source,shell]
 ----
 tfctl --all -- apply
 ----
 
-Run destroy in `test` OU accounts:
+Destroy Terraform-managed resources in all the `test` OU accounts:
 
+[source,shell]
 ----
 tfctl -o test -- destroy -auto-approve
 ----
 
 Don't buffer the output:
 
+[source,shell]
 ----
 tfctl -a example-account -u -- plan
 ----
 
 This will show output in real time.  Usually output is buffered and displayed
-after Terraform command finishes to make it more readable when running across
-multiple accounts in parallel.
+after the Terraform command finishes, to make it more readable when running
+across multiple accounts in parallel.

data/docs/configuration.adoc

@@ -24,8 +24,8 @@ toc::[]
 
 == Overview
 
-Tfctl retrieves initial account configuration from AWS Organizations and merges
-it with configuration specified in a yaml file (`tfctl.yaml` by default).
+`tfctl` retrieves initial account configuration from AWS Organizations and merges
+it with configuration specified in YAML format (`tfctl.yaml` by default).
 
 The configuration is merged in the following order:
 
@@ -83,14 +83,16 @@ above.
 
 == Handling secrets
 
-No secrets should be committed into Terraform or tfctl configuration.  Use AWS
-Secrets Manager instead and retrieve in Terraform profiles using
+CAUTION: Do not commit secrets into your Terraform or tfctl configuration.
+
+Instead, use AWS Secrets Manager and retrieve secrets in Terraform profiles using
+the
 https://www.terraform.io/docs/providers/aws/d/secretsmanager_secret.html[secrets
-manager data source]
+manager data source].
 
 == Configuration Schema
 
-Config file is validated using https://json-schema.org/[JSON Schema].
+The configuration file is validated using https://json-schema.org/[JSON Schema].
 
 The schema is defined in
 https://github.com/scalefactory/tfctl/blob/master/lib/tfctl/schema.rb[lib/tfctl/schema.rb]

data/docs/control_tower.adoc

@@ -31,7 +31,7 @@ toc::[]
 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
@@ -50,9 +50,10 @@ and provision a couple of accounts for testing.
 
 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
@@ -74,6 +75,7 @@ approximately 20 mins to provision one.
 
 == Install tfctl
 
+[source,shell]
 ----
 git clone git@github.com:scalefactory/tfctl.git
 cd tfctl/ && sudo make install
@@ -85,17 +87,21 @@ 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/
 
@@ -107,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 \
@@ -142,6 +151,7 @@ aws cloudformation create-stack \
 
 Check status:
 
+[source,shell]
 ----
 aws cloudformation describe-stacks --stack-name TfctlOrgAccess
 ----
@@ -158,7 +168,7 @@ 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.
 
@@ -169,43 +179,51 @@ 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 -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 --all -- init
 ----
 
 Tfctl will run Terraform against all accounts in parallel.
 
-Run plan:
+`plan` the Terraform:
 
+[source,shell]
 ----
 tfctl --all -- plan
 ----
 
-and apply:
+and `apply` it:
 
+[source,shell]
 ----
 tfctl --all -- apply
 ----
 
-To destroy created resources run:
 
+== Clean up
+
+To destroy created resources, run:
+
+[source,shell]
 ----
 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/iam_permissions.adoc

@@ -20,7 +20,7 @@ endif::[]
 
 = IAM roles
 
-Tfctl usually requires three IAM roles to be configured:
+`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
@@ -28,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

@@ -50,12 +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.
 
-By default tfctl will use `tfctl.yaml` in it's current working directory.  You
+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`
 
 Profiles are re-usable collections of resources which can be applied to
 accounts.  They are implemented just like usual modules but provide an
@@ -64,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/lib/tfctl/aws_org.rb

@@ -71,23 +71,25 @@ module Tfctl
             @aws_org_client.list_children(
                 child_type: 'ORGANIZATIONAL_UNIT',
                 parent_id:  parent_id,
-            ).children.each do |child|
-
-                begin
-                    ou = @aws_org_client.describe_organizational_unit(
-                        organizational_unit_id: child.id,
-                    ).organizational_unit
-                rescue Aws::Organizations::Errors::TooManyRequestsException
-                    # FIXME: - use logger
-                    puts 'AWS Organizations: too many requests.  Retrying in 5 secs.'
-                    sleep 5
-                    retries += 1
-                    retry if retries < 10
-                end
+            ).each do |resp|
+                resp.children.each do |child|
+
+                    begin
+                        ou = @aws_org_client.describe_organizational_unit(
+                            organizational_unit_id: child.id,
+                        ).organizational_unit
+                    rescue Aws::Organizations::Errors::TooManyRequestsException
+                        # FIXME: - use logger
+                        puts 'AWS Organizations: too many requests.  Retrying in 5 secs.'
+                        sleep 5
+                        retries += 1
+                        retry if retries < 10
+                    end
 
-                ou_name = parent_name == :root ? ou.name.to_sym : "#{parent_name}/#{ou.name}".to_sym
+                    ou_name = parent_name == :root ? ou.name.to_sym : "#{parent_name}/#{ou.name}".to_sym
 
-                output[ou_name] = ou.id
+                    output[ou_name] = ou.id
+                end
             end
             output
         end

data/lib/tfctl/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Tfctl
-    VERSION = '1.1.0'
+    VERSION = '1.1.1'
 end

data/tfctl.gemspec

@@ -25,12 +25,12 @@ Gem::Specification.new do |spec|
 
     # Think when adding new dependencies.  Is it really necessary?
     # "The things you own end up owning you" etc.
-    spec.add_dependency 'aws-sdk-organizations', '~> 1.13'
+    spec.add_dependency 'aws-sdk-organizations', '~> 1.40'
     spec.add_dependency 'json_schemer',          '~> 0.2'
-    spec.add_dependency 'parallel',              '~> 1.17'
+    spec.add_dependency 'parallel',              '~> 1.19'
     spec.add_dependency 'terminal-table',        '~> 1.8'
 
     spec.add_development_dependency 'guard-rspec', '~> 4.7'
-    spec.add_development_dependency 'rspec',       '~> 3.8'
-    spec.add_development_dependency 'rubocop',     '~> 0.76'
+    spec.add_development_dependency 'rspec',       '~> 3.9'
+    spec.add_development_dependency 'rubocop',     '~> 0.84'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tfctl
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Andrew Wasilczuk
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-01-15 00:00:00.000000000 Z
+date: 2020-05-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk-organizations
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.13'
+        version: '1.40'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.13'
+        version: '1.40'
 - !ruby/object:Gem::Dependency
   name: json_schemer
   requirement: !ruby/object:Gem::Requirement
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.17'
+        version: '1.19'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.17'
+        version: '1.19'
 - !ruby/object:Gem::Dependency
   name: terminal-table
   requirement: !ruby/object:Gem::Requirement
@@ -86,28 +86,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.8'
+        version: '3.9'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.8'
+        version: '3.9'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.76'
+        version: '0.84'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.76'
+        version: '0.84'
 description: 
 email:
 - akw@scalefactory.com