A beginner's guide to the terraform init command

This post is part of a series on Terraform State & Backends: The Complete Guide.

At the core of every Terraform deployment is the terraform init command - the step in the Terraform workflow that sets the stage for all subsequent operations. In this blog post, we'll dive deep into what terraform init is and what it does for your Terraform deployments.

All of the commands below for Terraform also apply to OpenTofu. When using the command, replace terraform with tofu.

What is terraform init?

The terraform init command is what needs to be executed after writing new Terraform configuration files. It initializes a working directory containing Terraform configuration files and prepares it for use with Terraform.

After executing the terraform init command, the working directory will contain, at a minimum, the following:

• A .terraform directory that contains the cached modules and providers that were initiated during terraform init.
• The Terraform state file, named terraform.tfstate. This only applies if Terraform is used without a remote backend. If a remote backend is used, like Scalr or HCP Terraform, the state file will be located in that backend.

Terraform init in the Terraform core pipeline

Terraform init serves as the foundation upon which all other terraform commands are built. The typical Terraform sequence to follow is:

1. terraform init: Initialize the working directory
2. terraform plan: Preview changes before applying
3. terraform apply: Apply the proposed changes
4. terraform destroy: Tear down the created infrastructure

As you can see, terraform init is the first step that enables all subsequent operations.

What Does terraform init Do?

Terraform Providers

Providers are plugins that Terraform uses to manage resources. The terraform init command ensures that the correct provider plugins are downloaded and installed. It checks the provider version specified in your configuration and downloads the appropriate version from the Terraform Registry or a specified custom provider source.

Example provider version specification:

Module Installation

If your Terraform configuration uses modules, considered a best practice, terraform init will download these modules and set them up in your working directory.

When you run terraform init, it will download the specified VPC module from the Terraform Registry for use in the run.

Backend Configuration

One of the primary functions of terraform init is to configure the backend. The backend determines where Terraform stores its state data files. By default, Terraform uses a local backend, which stores the state on the local filesystem. However, you can configure remote backends like Scalr, Terraform Cloud, Amazon S3, or Google Cloud Storage for better collaboration and security.

Example backend configuration in your Terraform code:

When you run terraform init, it performs backend initialization, setting up the specified backend and preparing it to store the state file.

State File

While terraform init doesn't create the state file (that happens when you first run terraform apply), it does set up the infrastructure for managing the state file. This includes configuring state locking mechanisms to prevent concurrent modifications when using a remote backend.

Verifying Configuration

The terraform init command also performs a basic check of your configuration files for syntax errors. While it doesn't catch all possible issues, it can identify obvious syntax problems, helping you catch errors early in the development process.

Advanced Commands

The terraform init command comes with some advanced options. For example, you may want to change backends, upgrade modules, or make changes to an existing backend:

• terraform init -reconfigure: The reconfigure command essentially starts the configuration from scratch by ignoring the working directory configuration and re-initializing the backend block.
• terraform init -migrate-state: The migrate-state command will migrate your state from one backend to another. For example, your state file might be local and you can use the migrate-state command to migrate it to a backend such as Scalr or Terraform Cloud.
• terraform init -upgrade: The upgrade command will ignore provider versions that are located in your lock file and upgrade your providers to the latest version depending on the constraints defined in your provider blocks.

Best Practices for Using terraform init

To use the terraform init command properly, consider these best practices:

1. Run terraform init after changes: Whenever you modify your backend configuration, add new providers, or update provider versions, re-run terraform init to ensure the changes take.
2. Version control your configuration: Store your Terraform configuration in version control, but exclude the .terraform directory created by terraform init.
3. Use consistent provider versions: Specify provider versions in your configuration to ensure consistency across different environments and team members. If versions are not pinned, terraform init will pull the latest.
4. Leverage remote backends: For teams, use a remote backend to enable collaboration and maintain a single source of truth for your terraform infrastructure, such as Scalr or Terraform Cloud.

Conclusion

The terraform init command is a fundamental part of the Terraform core workflow. By initializing your working directory, downloading necessary plugins, setting up backends, and performing basic verification, it lays the groundwork for all your Terraform operations.

Understanding what happens when you run terraform init can help you better manage your infrastructure-as-code projects, troubleshoot issues more effectively, and leverage Terraform's full potential in your DevOps practices.