Terraform 101: A Beginner's Guide 2023

Configuring your environment to start working with Terraform.

Overview

Semantic Versioning

This project uses semantic versioning for its tagging. See semver.org for more info.

The general format:

MAJOR.MINOR.PATCH, eg. 1.0.1

• MAJOR version when you make incompatible API changes
• MINOR version when you add functionality in a backward compatible manner
• PATCH version when you make backward compatible bug fixes

Prerequisites

Gitpod

To optimize your development environment you can use the open source tool Gitpod CLI. It allows you to reproduce the Cloud Development Environment (CDE) through the use of customizable "workspaces", ephemeral development environments.

Gitpod CLI

All Gitpod workspaces include a CLI (gp). For more info see the Gitpod CLI Reference Doc.

Install the Terraform CLI

1. Check your Linux Distribution. See How To Check OS Version in Linux.

   • Your version of Linux affects the type of commands you can run.

   • This project is built against Ubuntu. Example of checking Linux OS Version:

     ```
     cat /etc/os-release
     ```
     

     eg. Output:

     ```
     PRETTY_NAME="Ubuntu 22.04.3 LTS"
     NAME="Ubuntu"
     VERSION_ID="22.04"
     VERSION="22.04.3 LTS (Jammy Jellyfish)"
     VERSION_CODENAME=jammy
     ID=ubuntu
     ID_LIKE=debian
     HOME_URL="https://www.ubuntu.com/"
     SUPPORT_URL="https://help.ubuntu.com/"
     BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/"
     PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy"
     UBUNTU_CODENAME=jammy
     ```
     

2. Refer to the latest Install Terraform CLI instructions.

   • Alternatively: You can use the bash script here: ./bin/install_terraform_cli to install terraform using homebrew macOS X.

Refactoring into Bash Scripts

To address the Terraform CLI GPG deprecation issues and efficiently install the cli considering the additional steps we created a bash scirpt. The bash script: - Keeps the Gitpod Task File (gitpod.yml) tidy. - Makes it easier to debug and execute homebrew macOS X Terraform CLI install. - Allows for better portability for other project that need to install Terraform CLI.

Considerations

Shebang Considerations

On Linux, a Shebang (#!), pronounced Sha-bang, is a special line at the beginning of a script that tells the OS which program to use to run the script. eg. #!/bin/bash. It's the first line of the script and starts with #! followed by the program's path.

ChatGBT recommended this format for bash: #!/usr/bin/env bash for 1) portability for different OS distributions and to 2) search the user's PATH for the bash executable

More info on Shebang here

Execution Considerations

GitPod Lifecycle (Before, Init, Command)

Be mindful when using init because the script will not rerun if we restart an existing workspace. See Gitpod Tasks documentation for more information.

• This is why one of the changes we made to the Gitpod Task File (gitpod.yml) was replacing init with before.

When executing the bash script we can use the ./ shorthand notation to execute the bash script eg. ./bin/install_terraform_cli instead of source.

If we are using a script however in the gitpod.yml we need to point the script to a program to interpret it eg. source ./bin/install_terraform_cli

Linux Permissions Considerations

In order to make our bash scripts executable we need to change Linux permissions for the file to be executable at the user mode. For more info on changing linux permissions see this.

chomd u+x ./bin/install_terraform_cli

alternatively:

chmodn 744 ./bin/install_terraform_cli

Working with Environment Variables (Env Vars)

Bash Commands

env - to list all env vars env | grep VARIABLE - set a variable in terminal

Setting and Unsetting Env Vars

export VARIABLE= 'value' - set a variable unset VARIABLE - unset a variable

To temporarily set an env var, run the following command:

VARIABLE='value' ./bin/print_message

Within a bash script we can set an env without writing export:

#!/usr/bin/env bash

VARIABLE='value'

echo $VARIABLE

Printing Vars

We can print an env var using echo eg. echo $VARIABLE

Scoping of Env Vars

When you open a new bash terminal in VSCode it will not be aware of env vars set in another window. To persist env vars across all future terminals. You need to set env vars in your bash profile. eg. .bash_profile

Persisting Env Vars in Gitpod

Gitpod has default env vars set for every workspace. To set new env vars in Gitpod and have them persist across all your future workspaces follow this, please see this.

env | grep GITPOD - lists all default Gitpod env vars gp env VARIABLE - set a variable in gitpod echo VARIABLE - (create a new workspace to view newly set env vars

AWS CLI Installation

AWS CLI is installed for the project via the bash script ./bin/install_aws_cli

Getting Started Install (AWS CLI)

AWS CLI Env Vars

We can check if our aws credentials are configured correctly by running the following AWS CLI command:

aws sts get-caller-identity

If it is successful you should see a json payload return:

{"UserId": "AIXAU7JXXLKQXXXCXXC5",
    "Account": "335370644609",
    "Arn": "arn:aws:iam::342100630177:user/terraform-beginner-bootcamp"
}

Use aws configure when you are on a local computer and when in a cloud developer environement you'll want to set your env vars.

Create an new AWS IAM user

We'll need to generate AWS CLI credentials from an IAM user in order to use the AWS CLI. To create a new user please follow these instructions here

Terraform Basics

Terraform Registry

Terraform sources their providers and modules from the Terraform registroy which is located at registry.terraform.io

• Providers are a logical abstraction of an upstream API. They are responsible for understanding API interactions and exposing resources.
• Modules are self-contained packages of Terraform configurations that are managed as a group. They make larger amounts of terraform code modular, portable and shareable.

Random Terraform Provider

Terraform Console

We can see a list of all the Terraform commands by typing terraform

Terraform Init

At the start of a new terraform project we will run terraform init to download the binaries for the terraform providers that we'll use in this project.

Terraform Plan

terraform plan

This wll generate out a changeset about the state of our infrastructure and what will be changed.

We can output this changeset ie. "plan" to be passed to an apply, but often you can just ignore outputting

Terraform Apply

Ths will run a plan and pass the changeset to be executed by terraform. Apply should prompt 'yes' or 'no'.

To automatically approve an apply we can provide the auto approve flag eg. terraform apply --auto-approve

Terraform Destroy

terraform destroy destroy resources.

Terraform Lock Files

.terraform.lock.hcl contains the lock versioning for the providers or modules that should be used with this project

The Terraform Lock File should be commited to your Version Control System (VSC) eg. Github

Terraform State Files

.terraform.tfstate contains informations about the current state of your infrastructure. This file should not be commited to your VCS. This file can contain sensitive data. If you lose this file, you lose knowing the state of your infrastructure.

.tefraform.tfstate.backup is the previous state file's state.

Terraform Directory

.terraform directory contains binaries of terraform provders.

Issues with Terraform Cloud Login and Gitpod Workspace

terraform login launched bash in a wiswig view to generate a token, however, it does not work as expected in Gitpod VSCode Desktop app or browser.

The work around is manually generating a token in Terraform Cloud here:

https://app.terraform.io/app/settings/tokens?source=terraform-login

Then creating and opening the file manually here:

touch /home/gitpod/.terraform.d/credentials.tfrc.json/
open /home/gitpod/.terraform.d/credentials.tfrc.json/

And insert the following code (replace your token) in the file:

{
  "credentials": {
    "app.terraform.io": {
      "token": "YOUR-TERRAFORM-CLOUD-TOKEN"
    }
  }
}

We have automated this workaround with the following bash script bin/generate_tfrc_credentials

Create Bash Aliases

To make the alias persistent you need to declare it in the ~/.bash_profile or ~/.bashrc file.

open /.bash_profile - open the file in your text editor and insert:

alias alias_name="command_to_run

source ~/.bash_profile - you need to reload bash inorder for your change to be applied

For more info on creating bash aliases see How to Create Bash Aliases

Persist Aliases in Gitpod Using a Bash Script

To ensure this new bash alias is applied to future Gitpod workspace, we created the file set_tf_alias:

#!/usr/bin/env bash

#Check if the alias already ecxists in the .bash_profile
grep -q 'alias tf="terraform"' ~/.bash_profile

# $? is a special variable in bash that holds the exit status of the last command executed 

if [[ $? != 0 ]]; then
    #If the alias does not exist, append it
    echo 'alias tf="terraform"' >> ~/.bash_profile
    echo "Alias added successfully."
else 
    #Inform the user if the alias already exists
    echo "Alias already exists in .bash_profile."
fi

#Optional: soure the .bash_profile to make the alias avaliable immediately
source ~/.bash_profile

STOP - Ended course before week 1: https://app.exampro.co/student/journey/terraform-cpb