Package: terrawrap
TerrawrapSet of Python-based CLI tools for working with Terraform configurations in bulkAbout AmplifyAmplify builds innovative and compelling digital educational products that empower teachers and students across the
country. We have a long history as the leading innovator in K-12 education - and have been described as the best tech
company in education and the best education company in tech. While others try to shrink the learning experience into
the technology, we use technology to expand what is possible in real classrooms with real students and teachers.Learn more athttps://www.amplify.comTable of ContentsFeaturesGoalsGetting StartedPrerequisitesInstallingBuilding From SourceRunning TestsConfiguration.tf_wrapperPluginsAutovarsBackend ConfigurationCommandstfplan_checkgraph_applyFeaturesauto.tfvarsinheritance. Terrawrap makes it easier to share variables between Terraform directories through
inheritance ofauto.tfvarsfiles.Remote backend generation. Terrawrap makes it easier to work with remote state backends by
generating configuration for them.Repository level plan/apply. Terrawrap provides commands for running plan/apply recursively on a entire
repository at once.Repository level dependency visualization. Terrawrap provides commands for displaying the order of applies in
human readable output.Automatically download third-party Terraform pluginsGoalsMake Terraform DRY for large organizations. A Terraform best practices is to break up Terraform configs
into many small state files. This leads to an explosion in boilerplate code when using Terraform in large
organizations with 100s of state files. Terrawrap reduces some boilerplate code by providingauto.tfvarsinheritance and generating backend configurations.Make Terraform code easier to manage. Terraform only runs commands on a single directory at a time. This makes
working with hundreds of terraform directories/state files hard. Terrawrap provides utilities for running
commands against an entire repository at once instead of one directory at a time.All Terraform code should be valid Terraform. Any Terraform code used with Terrawrap should be runnable with
Terraform by itself without the wrapper. Terrawrap does not provide any new syntax.Terrawrap is not a code generator. Generated code is harder to
read and understand. Code generators tend to lead to leaky abstractions that can be more trouble than they are
worth. However, Terrawrap does generate remote backend configs as a workaround to Terraform's lack of support for
variables in backend configs (Seehttps://github.com/hashicorp/terraform/issues/13022). We expect this to be
the only instance of code generation in Terrawrap.Getting StartedPrerequisitesTerrawrap requires Python 3.7.0 or higher to run.InstallingThis package can be installed usingpippip3installterrawrapYou should now be able to use thetfcommand.Building From SourceFor development,tox>=2.9.1is recommended.Running TestsTerrawrap usestox. You will need to install tox withpip install tox.
Runningtoxwill automatically execute the unit tests.You can also run them individually with the-eargument.For example,tox -e py37-unitwill run the unit tests for python 3.7To see all the available options, runtox -l.Configuration.tf_wrapperTerrawrap can be configured via a.tf_wrapperfile. The wrapper will walk the provided configuration
path and look for.tf_wrapperfiles. The files are merged in the order that they are discovered. Consider
the below example:foo
├── bar
│   └── .tf_wrapper
└── .tf_wrapperIf there are conflicting configurations between those two.tf_wrapperfiles, the.tf_wrapperfile infoo/barwill win.The following options are supported in.tf_wrapper:configure_backend:True# If true, automatically configure Terraform backends.backend_check:True# If true, require this directory to have a terraform backend configuredenvvars:<NAME_OF_ENVVAR>:source:# The source of the envvar. One of `['ssm', 'text', 'unset']`.path:# If the source of the envvar is `ssm`, the SSM Parameter Store path to lookup the value of the environment variable from.value:# if the source of the envvar is `text`, the string value to set as the environment variable.# If the source is unset, any previous value for the environment variable is removed and the environment variable will not be set.plugins:<NAME_OF_PLUGIN>:<plugin url>PluginsTerrawrap supports automatically downloading provider plugins by configuring the.tf_wrapperfile as specified above.
This is a temporary workaround until Terraform 0.13 is released with built-in support for automatically
downloading plugins and plugin registries are available for hosting private plugins.Terrawrap will first try to download platform specific versions of plugins by downloading them from<plugin url>/<system type>/<architecture type>. If Terrawrap is unable to download from the platform specific URL
then it will try to download directly from the given plugin url directly instead.For example, the following config on a Macplugins:foo:http://example.com/fooTerrawap will first try to download fromhttp://example.com/foo/Darwin/x86_64.
If that request fails then Terrawrap will tryhttp://example.com/fooinstead.AutovarsTerrawrap automatically adds-var-filearguments to any terraform command by scanning for*.auto.tfvarsfiles in the directory structure.For example, the following commandtf config/foo/bar applywith the following directory structure:config
├── foo
|   └── bar
|   │  ├── baz.tf
|   │  └── bar.auto.tfvars
|   └── foo.auto.tfvars
└── config.auto.tfvarswill generate the following command:terraformapply-var-fileconfig/config.auto.tfvars\-var-fileconfig/foo/foo.auto.tfvars\-var-fileconfig/foo/bar/bar.auto.tfvarsBackend ConfigurationTerrawrap supports automatically configuring backends by injecting the appropriate-backend-configargs when runninginitFor example, the Terrawrap commandtf config/foo/bar initwill generate a Terraform command like below if using
an AWS S3 remote state backendterraforminit-reconfigure\-backend-config=dynamodb_table=<locktablename>\-backend-config=encrypt=true\-backend-config=key=config/foo/bar.tfstate\-backend-config=region=<regionname>\-backend-config=bucket=<statebucketname>\-backend-config=skip_region_validation=true\-backend-config=skip_credentials_validation=trueTerrawrap configures the backend by looking for.tf_wrapperfiles in the directory structure.
Eithers3orgcsare supported. See the relevant Terraform documentation for the options available
for each type of backend:https://www.terraform.io/docs/backends/types/s3.html#configuration-variableshttps://www.terraform.io/docs/backends/types/gcs.html#configuration-variablesS3 Backendbackends:
    s3:
        region:
        role_arn:
        bucket:
        dynamodb_table:Option NameRequiredPurposebucketYesName of S3 BucketregionYesAWS Region that S3 state bucket and DynamoDB lock table are located indynamodb_tableNoDynamoDB table to use for state locking. Locking is disable if lock_table is not setrole_arnNoAWS role to assume when reading/writing to S3 bucket and lock tableThe S3 state file key name is generated from the directory name being used to run the terraform command.
For example,tf config/foo/bar inituses a state file with the keyconfig/foo/bar.tfstatein S3GCS Backendbackends:
    gcs:
        bucket:Option NameRequiredPurposebucketYesName of GCS BucketCommandstftf <directory> <terraform command>runs a terraform command for a given directory that contains*.tffiles.
Terrawrap automatically includes autovars as described above when running the given command. Any Terraform
command is supportedplan_checkplan_check <directory>runsterraform planrecursively for all child directories starting at the given directory.plan_checkusesgitto identify which files have changed compared with themasterbranch. It will then runplanon any directory that containstffiles with the following criteriaA directory that has files that changedA directory that is symlinked to a directory that has files changedA directory with symlinked files that are linked to files that changedA directory that that uses a Terraform module whose source changedA directory with Terraform files that refer to an autovar file that changedbackend_checkbackend_check [directory]verifies that all directories under the given directory that contain.tffiles
also have Terraform Backends defined.