Terraform_Notes.txt

--------------
Terrform Notes
--------------

Docs
----
v12+
- https://github.com/hashicorp/terraform/blob/v0.12.0/CHANGELOG.md
# Configuration
- [Configuration Language](https://www.terraform.io/docs/configuration/index.html)
# Expressions are used to refer to or compute values within a configuration
- [Expressions](https://www.terraform.io/docs/configuration/expressions.html)
# Type constraints: validate user-provided values for their input variables and resource arguments
- [Type Constraints](https://www.terraform.io/docs/configuration/types.html)
# Functions: built-ins that you can call from within expressions to transform and combine values
- [Functions](https://www.terraform.io/docs/configuration/functions.html)

Installation
------------
- standalone binary: find it and install it - easy!

MacOS
  - brew install terraform

Commands
--------
terraform version
---
terraform init
terraform init -backend=true -backend-config="$PATH" -backend-config="$KEY=$VAL" $DIR
terraform init -backend=true -backend-config="key=baas/dev/data-tier.tfstate" baas-3.0/data-tier
terraform init -reconfigure \
     -backend-config "bucket=$TF_VAR_tf_state_bucket" \
     -backend-config "dynamodb_table=$TF_VAR_tf_state_table" \
     -backend-config "region=$TF_VAR_region" \
     -backend-config "key=$TF_VAR_application/$TF_VAR_environment"
terraform init -backend-config backend-foo-blue-us-east-1.tfvars -reconfigure

terraform plan (< .11)

# see some sensitive data
   - v.0.15.x and above, use the 'nonsensitive' function around the value
   - otherwise
      $ terraform plan -out FILE
      $ terraform show -json FILE

terraform plan (< .11)

terraform apply \
  -var 'var1=foo' \
  -var 'var2=bar'
    or
  -var-file="path/to/file.tfvars"  # if not "terraform.tfvars | *.auto.tfvars"
    or
  export TF_VAR_var1=foo
  export TF_VAR_var2=bar

  variable "var1" {
    type = "string
  }
  variable "amis" {
    default = {
      "us-west-1" = "ami-12345"
      "us-west-2" = "ami-67890"
    }
    type = "map"
  }

  setting = "${var.var1}"
  ami = "${lookup(var.amis, var.region)}"
---
terraform show

terraform output [output]

terraform destroy [-target=RESOURCE_TYPE.RESOURCE_ID]
terraform apply \
   [-var-file=./qa.us-west-2.tfvars] \
   [-target=RESOURCE_TYPE.RESOURCE_ID]
terraform destroy -var-file=./qa.us-west-2.tfvars -target=module.bos_sql_1
terraform destroy -var-file=qa.us-west-2.tfvars -target module.asg

examples
-------
terraform apply -var-file=local.tfvars -var='name="*SQL*"'

-------------
Backends
------------
- terraform init
  - when adding, changing or removing backend configs
- terraform state pull
- terraform state push [-force] (extremely dangerous)
- terraform force-unlock [-force] LOCK_ID [DIR]
- terraform state mv [options] SOURCE DESTINATION
   simple resource renaming, moving items to and from a module
- terraform state replace-provider registry.terraform.io/chanzuckerberg/snowflake registry.terraform.io/snowflake-labs/snowflake

-------------
Modules
------------
versioning not available with local modules

(local)  source = "../modules/$MODULE_NAME"
(GutHub) source = "git@github.com:$USER_NAME/$REPO_NAME.git?ref=$TAG"

 - terraform init [-upgrade]  # upgrade module versions

-------------
Workspaces
------------
Technically equivalent to renaming the state file.
- Local state
  - workspace states stored in directory: terraform .tfstate.d
- Remote state
  - S3 Backend
    - workspace stored in:

      ${bucket}/${workspace_key_prefix}/${workspace}/${key}

- terraform workspace [delete|list|new|select|show]
- interpolate with:
    ${terraform.workspace}
  e.g.:
    count = "${terraform.workspace == "prod" ? 5 : 2}"

  resource "aws_instance" "example" {
    tags {
      Name = "web - ${terraform.workspace}"
    }
    # ... other arguments
  }
-

###########################
tags = "${merge(var.tags, map("Name", var.instance_count > 1 ? format("%s-%d", var.name, count.index+1) : var.name))}"

-------- -------- --------
Workflow (environments and deployments)
-------- -------- --------

Presteps/Prep
-------------
1. create s3 bucket to hold state files
2. create dynamodb table to lock state file access
3. setup terraform workspaces
  $ terraform workspace new blue
  $ terraform workspace new green

backend config location/name:

  $REPO/terraform/projects/$PROJECT/$TIER/backend.tf

backend config contents:
(partially configured to allow remaining configs via command line arguments)

  ---
  | terraform {
  |     required_version = ">= 0.11.0"
  |     backend "s3" {}
  | }
  ---

backend configuration file location/name:
(used to configure backend via command line arguments)

  $REPO/terraform/projects/$PROJECT/backend.config

backend configuration file contents:

  ---
  | bucket = "${var.state_file_bucket}"
  | region = "${var.region}"
  | encrypt = "true"
  | dynamodb_table = "${var.state_file_lock_table}"
  | workspace_key_prefix = "deployment"
  ---
  ---
  | bucket = "${var.state_file_bucket}"
  | region = "${var.region}"
  | encrypt = "true"
  | dynamodb_table = "${var.state_file_lock_table}"
  | workspace_key_prefix = "deployment"
  ---
  ---
  | bucket = "onica-praco-lab-gd-terraform"
  | key = "baas-3-0/qa/data-tier.tfstate"
  | key = "${var.project}/${var.environment}/data-tier.tfstate"
  | region = "us-west-2"
  | encrypt = true
  | dynamodb_table = "terraform-locks-qa"  # for state file locking
  | workspace_key_prefix = "deployment"    # default: 'env:'
  ---

  I. Launch "blue" in QA
    1. cd to root directory of project
      $ cd $REPO/terraform/projects/$PROJECT
    2. switch to "qa" `git` branch
      $ git checkout qa
    3. switch to blue workspace
      $ terraform workspace select blue
    4. initialize the backend
      $ terraform init -backend=true \ -backend-config="backend.config" \
         -backend-config="key=$PROJECT/$ENV/$TIER.tfstate" $TIER
    4. launch infrastructure
      $ terraform apply -var-file=$TIER/$ENVIRONMENT.$REGION.tfvars]
 II. Launch "green" in QA
III. Launch "blue" in PROD
 IV. Launch "green" in PROD

------------
for_each
------------

Outputs

splat operators don't work with maps, are for lists only and just a shorthand
for a 'for' expression

When using for_each we must use a full 'for' expression:

output key/value pairs (creates a map/object):

   value = { for k, v in aws_eip.this : k => v.id }

output list of values (in lexical order by the keys):

   value = [ for v in aws_eip.this : v.id ]

output a set of strings, values are not ordered
(more convenient to use with for_each elsewhere):

   value = toset([ for v in aws_eip.this : v.id ])

tags: terraform, tf