Terraform CLI - Part 1

Till now we have dealt quite a lot with Terraform CLI directly and indirectly in our previous posts. But Terraform CLI was never the focus of those introductory discussions. If you missed the introduction, please feel free to read the same here.

The introductory post also contains information about the workflow (init - plan - apply - destroy). In all the examples till now we have used this workflow from CLI. It is safe to say we have used a CLI-based workflow. In this post, we take a moment to understand the significance of Terraform CLI.

Directories

By now it should already be clear that the CLI interface for Terraform is terraform. Every command related to Terraform CLI starts with terraform  command.

A Terraform project is essentially a set of .tf files. All the IaC should be written into these files and saved in a particular directory. This forms the root directory of any Terraform project. It can also contain sub-directories. Terraform automatically interprets these configuration files as part of the project. However, there are other files and sub-directories which are created by Terraform to maintain states and downloaded plugins.

Terraform never works directly with configuration files (.tf). To successfully apply the configuration Terraform works with plugins which it needs to download before apply can happen. This is where an initialization command (below) needs to be executed into the same directory where configuration files are placed.

terraform init

This command should be run every time a new provider is introduced in the configuration. By running this command, Terraform identifies the providers required by the configuration along with their versions and downloads the appropriate plugin from the repository. These plugins are downloaded in a directory .terraform created by Terraform in the same root directory.

Note: Remember to specify .terraform the directory into .gitignore a file to avoid unnecessary transportation of modules.

There is no harm in reinitializing the repository every time. By doing this it makes sure all the required plugins are downloaded and available for use. It does not start a new download for the same.

Infrastructure lifecycle

Some of the most important and most used Terraform CLI commands are plan, apply, and destroy which manage the planning, creation, modification, and deletion of cloud infrastructure.

Plan

Once the written configuration is ready (in case of an update or create) to be deployed - and the root directory initialized, the next action is to run terraform plan command. Running terraform plan into the root directory of Terraform project evaluates and validates the configuration provided in configuration files. It makes sure the correct syntax is used, appropriate plugins are installed, the state is not corrupted, checks the actual deployment and finds differences, lists out dependencies, etc.

Simply navigate to the root directory and run the below command. If successful, it would lay down the plan listing all the target resources which will be created or updated. In the end, it would beautifully tell us how many resources are planned for creation, modification, and deletion.

terraform plan

Apply

Once the configuration is validated successfully using terraform plan, it is time to put that plan into action. This is done by running the below command:

terraform apply

Terraform works on the given configuration in the backend. Terraform internally uses the access credentials set up for the cloud providers to consume their APIs for the creation, modification, and destruction of the resources.

Note: Having successfully run the plan command, doesn't mean there won't be any errors during the apply phase.

Destroy

Perhaps, one of the most important commands during the learning phase, if you want to avoid huge bills. :)

After the configuration is applied (created, modified, destroy), appropriate changes are reflected in the Terraform state file. terraform destroy reads the state file to understand which resources currently exist and deletes the same. All you need to do is navigate to the root directory and run:

terraform destroy

These are basic resource lifecycle management CLI commands but they are the most important when working with Terraform. As we go through more details of Terraform's state management, modules, and backend - the significance of these commands would arise.

Formatting code

There are certain Terraform CLI commands which are very useful while writing the configuration itself. Let us take a look at some important ones which you can start using right away.

console

If you ever find yourself using complex expressions and functions, and wonder if this is the right syntax, or would it return the expected value at a certain point in the configuration? Well, terraform console can help you do a quick check. Run terraform console and it would open an interactive session where you can print and try out expression values.

Optionally you can pass in a path to state files to refer to values and experiment with expressions to derive a correct one. This is similar to the javascript console which is available in the latest web browsers like Google Chrome or Mozilla Firefox.

fmt

Terraform has its own style convention - refer to it here. But you don’t really have to worry about it because we can make sure all the conventions are followed by simply executing the below command in the root Terraform directory.

terraform fmt

Running terraform fmt rewrites the configuration files after the code is adjusted to follow conventions.

validate

I know we talked about validations when we discussed the terraform plan. However, terraform validate is another kind of validation where it takes care of syntax errors. It has nothing to do with the verification of remote states or resources. It is a simple validation command to check the syntax of Terraform configuration. Run this command in the root module as below, if successful, be sure about the syntax.

terraform validate

Inspecting infrastructure

Terraform state contains a lot of useful structure information, which can be queried to understand current situations with cloud resource deployment. This part describes a few commands which help us in this regard.

Before we discuss the actual commands, do take a look at any existing terraform.tfstate file. Do note that it is just a JSON file that has the information of the currently applied configuration.

show

terraform show simply prints the current state on the console. By default, it prints the information in the form of formatted HCL, but if you want to get a JSON output, that is possible as well by running the below command. JSON output can prove to be more useful when we have to pass the information to other interfaces.

terraform show -json

state list and state show

terraform show gives us the verbose output, in the sense that it prints everything that’s present in the state file. However, if you need specific details about the state, running terraform state list will present you with the resource titles of the created resources.

terraform state show helps in getting the details of a particular resource.

graph

Terraform CLI also has the ability to generate output in the form of a graph. Simply running terraform graph in the root directory will help you with a digraph. However, if you want a graphical representation you need to install GraphViz (sudo apt install graphviz on Linux).

terraform graph | dot -Tsvg > graph.svg

Authentication

Terraform CLI is also used in conjunction with Terraform Cloud. Terraform Cloud is used to maintain workspaces, states, private modules and to enforce access control on the infrastructure being managed. These are topics for later, but for now, just assume that we have to deal with Terraform Cloud in the future so that we can proceed with the first CLI commands related to authentication.

Login

Authentication between Terraform Cloud and CLI is token-based. You can log in to your Terraform Cloud by mentioning the hostname while executing the below command. If you attempt to login without providing a hostname, it is assumed that you are looking to log in to app.terraform.io.

terraform login [hostname]

Running the above login command in the terminal window, Terraform CLI asks for confirmation about 2 things:

1. A request for API token using your browser

2. A request to store the token in /home/<username>/.terraform.d/credentials.tfrc.json file

By typing in yes, you confirm the same and the browser window opens up and asks you to log in to app.terraform.io. You will be presented with a token to be copied and pasted into the terminal window. That is it - you are successfully logged into Terraform Cloud using Terraform CLI.

Logout

To log out of Terraform Cloud from Terraform CLI, all you need to do is run terraform logout from the terminal window.

That completes the introduction of basic and important commands. Of course, this post is not meant to list all the available commands on Terraform CLI documentation. Above are the most used commands and if you are looking forward to being a Terraform developer, you ought to know them. In the next part, we would go through some of the more advanced CLI concepts which form the building blocks for upcoming topics.