README.yaml

---
#
# This is the canonical configuration for the `README.md`
# Run `make readme` to rebuild the `README.md`
#

# Name of this project
name: tfenv

# Logo for this project
#logo: docs/logo.png

# License of this project
license: "APACHE2"

# Canonical GitHub repo
github_repo: cloudposse/tfenv

# Badges to display
badges:
  - name: "Build Status"
    image: "https://travis-ci.org/cloudposse/tfenv.svg?branch=master"
    url: "https://travis-ci.org/cloudposse/tfenv"
  - name: "Latest Release"
    image: "https://img.shields.io/github/release/cloudposse/tfenv.svg"
    url: "https://github.com/cloudposse/tfenv/releases/latest"
  - name: "Slack Community"
    image: "https://slack.cloudposse.com/badge.svg"
    url: "https://slack.cloudposse.com"

# Short description of this project
description: |-
  Command line utility to transform environment variables for use with Terraform.
  (e.g. `HOSTNAME` → `TF_VAR_hostname`)
 
  It can also intelligently map environment variables to terraform command line arguments (e.g. `TF_CLI_INIT_BACKEND_CONFIG_BUCKET=example` → `TF_CLI_ARGS_init=-backend-config=bucket=example`).

  __NOTE__: `tfenv` is **not** a [terraform version manager](#history). It strictly manages environment variables much like `env` or `direnv`.

introduction: |-

  If you answer "yes" to any of these questions, then look no further!

  * Have you ever wished you could easily pass environment variables to terraform *without* adding the `TF_VAR_` prefix?
  * Do you use [`chamber`](https://github.com/segmentio/chamber) and get annoyed when it transforms environment variables to uppercase?
  * Would you like to use common environment variables names with terraform? (e.g. `USER` or `AWS_REGION`)
  * Is there some argument to `terraform init` you want to specify with an environment variable? (e.g. a `-backend-config` property)

  **Yes?** Great! Then this utility is for you.

  The `tfenv` utility will perform the following transformations:

    1. Lowercase all envs (Terraform convention)
    2. Strip leading or trailing underscores (`_`)
    3. Replace consecutive underscores with a single underscore (`_`)
    4. Prepend prefix (`TF_VAR_`)

  __NOTE__: `tfenv` will preserve the existing environment and add the new environment variables with `TF_VAR_`. This is because some terraform providers expect non-`TF_VAR_*` prefixed environment variables. Additionally, when using the `local-exec` provisioner, it's convenient to use regular environment variables. See our [`terraform-null-smtp-mail`](https://github.com/cloudposse/terraform-null-smtp-mail) module for an example of using this pattern.


  **But wait, there's more!**

  With `tfenv` we can surgically assign a value to any terraform argument using per-argument environment variables.

  ## History
  

  **Why is this project called `tfenv`?**

  This `tfenv` project borrows its naming convention from popular tools like [`env`](https://en.wikipedia.org/wiki/Env), [`direnv`](http://direnv.net), and [`autoenv`](https://github.com/kennethreitz/autoenv). These tools provide various ways to export variables in the environment. 
  
  The `env` command has been [around since the early 90s](http://pdplab.it.uom.gr/project/sysadm/unix.pdf), while [environment variables](https://en.wikipedia.org/wiki/Environment_variable) were first conceived of in 1979. On the other hand there are tools like `rbenv` Et al., which are ["version managers"](https://en.wikipedia.org/wiki/Ruby_Version_Manager) that were conceived of sometime around 2010.

# How to use this project
usage: |-

  __NOTE__: The utility supports a number of configuration settings which can be passed via environment variables.

    * `TFENV_PREFIX` - Prefix used for all normalized environment variables (default is `TF_VAR_`, but you could do something like `TF_VAR_app_`)
    * `TFENV_WHITELIST` - Whitelist of allowed environment variables. Processed *after* blacklist. Regular expression should match wanted environment variables (by default `.*`)
    * `TFENV_BLACKLIST` - Blacklist of excluded environment variables. Processed *before* whitelist. Regular expression should exclude unwanted/dangerous environment variables (e.g. AWS credentials)

  The basic usage looks like this. We're going to run some `command` and pass it `arg1` ... `argN`:

  ```sh
  tfenv command arg1 arg2 arg3 ... argN
  ```

  So for example, we can pass our current environment to terraform by simply running:

  ```sh
  tfenv terraform plan
  ```

  ### Direnv
  
  You can use `tfenv` with [`direnv`](https://direnv.net/) very easily. Running `tfenv` without any arguments will emit `export` statements.

  Example `.envrc`:

  ```sh
  # Export terraform environment
  source <(tfenv)
  ```

  or...
  ```sh
  # Export terraform environment
  eval "$(tfenv)"
  ```

  ### Bash
  
  Load the terraform environment into your shell.

  Just add the following into your shell script:

  ```sh
  source <(tfenv)
  ```

  ### Terraform Args
  
  With `tfenv` we can populate the [`TF_CLI_ARGS` and `TF_CLI_ARGS_*` environment variables](https://www.terraform.io/docs/configuration/environment-variables.html#tf_cli_args-and-tf_cli_args_name) automatically. This makes it easy to toggle settings. 

  For example, if you want to pass `-backend-config=bucket=terraform-state-bucket` to `terraform init`, then you would do the following:

  ```sh
  export TF_CLI_INIT_BACKEND_CONFIG_BUCKET=terraform-state-bucket
  ```

  Running `tfenv` will populate the `TF_CLI_ARGS_init=-backend-config=bucket=terraform-state-bucket`

  Multiple arguments can be specified and they will be properly concatenated.

  ### Initializing Modules
  
  Terraform has the built-in capability to initialize "root modules" from a remote sources by passing the `-from-module` argument to `terraform init`.

  We can turn this into a 12-factor style invocation using `tfenv`.

  ```sh
  export TF_CLI_INIT_FROM_MODULE=git::https://github.com/cloudposse/terraform-root-modules.git//aws/tfstate-backend?ref=tags/x.y.z
  source <(tfenv)
  terraform init
  ```

  Learn more about `TF_CLI_ARGS` and `TF_CLI_ARGS_*` in the [official documentation](https://www.terraform.io/docs/configuration/environment-variables.html#tf_cli_args-and-tf_cli_args_name).


references:
  - name: "Terraform Without Wrappers is AWESOME!"
    description: "Reddit discussion regarding this project."
    url: "https://www.reddit.com/r/Terraform/comments/afznb2/terraform_without_wrappers_is_awesome/"

related:
  - name: "Packages"
    description: "Cloud Posse installer and distribution of native apps"
    url: "https://github.com/cloudposse/packages"
  - name: "build-harness"
    description: "Collection of Makefiles to facilitate building Golang projects, Dockerfiles, Helm charts, and more"
    url: "https://github.com/cloudposse/build-harness"
  - name: "geodesic"
    description: "Geodesic is the fastest way to get up and running with a rock solid, production grade cloud platform built on strictly Open Source tools."
    url: "https://github.com/cloudposse/geodesic"
  - name: "direnv"
    description: "Unclutter your .profile with an environment switcher for the shell"
    url: "https://direnv.net/"
  - name: "env"
    description: "Used to either print a list of environment variables or run another utility in an altered environment without having to modify the currently existing environment."
    url: "https://en.wikipedia.org/wiki/Env"

examples: |-

  ### Compiling the Binary

  ```sh
  make go/build
  ```

  ### Use with Chamber

  ```sh
  chamber exec foobar -- tfenv terraform plan
  ```

  ### Use with Terragrunt

  ```sh
  tfenv terragrunt plan
  ```

  ### Print Environment

  ```sh
  tfenv printenv
  ```

  ### Use with Direnv

  You can easily integrate `tfenv` with [`direnv`](https://github.com/direnv/direnv) so that your environment is automatically setup for Terraform.

  Add the following to your `.envrc`:

  ```sh
  source <(tfenv)
  ```

  <details>
    <summary>Example Output</summary>

    ```sh
    direnv: loading .envrc
    direnv: export +TF_VAR_aws_profile +TF_VAR_aws_vault_backend +TF_VAR_colorterm +TF_VAR_dbus_session_bus_address +TF_VAR_desktop_session +TF_VAR_direnv_diff +TF_VAR_direnv_in_envrc +TF_VAR_direnv_watches +TF_VAR_display +TF_VAR_fzf_orig_completion_git +TF_VAR_github_token +TF_VAR_gtk_overlay_scrolling +TF_VAR_histcontrol +TF_VAR_histsize +TF_VAR_home +TF_VAR_hostname +TF_VAR_lang +TF_VAR_lessopen +TF_VAR_logname +TF_VAR_ls_colors +TF_VAR_mail +TF_VAR_mate_desktop_session_id +TF_VAR_okta_user +TF_VAR_oldpwd +TF_VAR_path +TF_VAR_pwd +TF_VAR_qt_auto_screen_scale_factor +TF_VAR_qt_scale_factor +TF_VAR_session_manager +TF_VAR_sessiontype +TF_VAR_shell +TF_VAR_shlvl +TF_VAR_ssh_auth_sock +TF_VAR_term +TF_VAR_user +TF_VAR_vte_version +TF_VAR_windowid +TF_VAR_xauthority +TF_VAR_xdg_current_desktop +TF_VAR_xdg_runtime_dir +TF_VAR_xdg_seat +TF_VAR_xdg_session_id +TF_VAR_xdg_vtnr
    ```

  </details>


# Contributors to this project
contributors:
  - name: "Erik Osterman"
    homepage: "https://github.com/osterman"
    github: "osterman"