Quickstart: Configure Terraform using Azure Cloud Shell

Terraform enables the definition, preview, and deployment of cloud infrastructure. Using Terraform, you create configuration files using HCL syntax. The HCL syntax allows you to specify the cloud provider - such as Azure - and the elements that make up your cloud infrastructure. After you create your configuration files, you create an execution plan that allows you to preview your infrastructure changes before they're deployed. Once you verify the changes, you apply the execution plan to deploy the infrastructure.

This article describes how to get started with Terraform on Azure.

In this article, you learn how to:

  • Authenticate to Azure
  • Create an Azure service principal using the Azure CLI
  • Authenticate to Azure using a service principal
  • Set the current Azure subscription - for use if you have multiple subscriptions
  • Create a base Terraform configuration file
  • Create and apply a Terraform execution plan
  • Reverse an execution plan

Prerequisites

  • Azure subscription: If you don't have an Azure subscription, create a free account before you begin.

Configure your environment

  1. Browse to the Azure portal.

  2. If you aren't already logged in, the Azure portal displays a list of available Microsoft accounts. Select a Microsoft account associated with one or more active Azure subscriptions and enter your credentials to continue.

  3. Open Cloud Shell.

    Accessing Cloud Shell

  4. If you haven't previously used Cloud Shell, configure the environment and storage settings. This article uses the Bash environment.

Key points:

  • Cloud Shell automatically has the latest version of Terraform installed. Also, Terraform automatically uses information from the current Azure subscription. As a result, there's no installation or configuration required.

Authenticate to Azure

Cloud Shell is automatically authenticated under the Microsoft account you used to log into the Azure portal. If your account has multiple Azure subscriptions, you can switch to one of your other subscriptions.

Terraform supports several options for authenticating to Azure. The following techniques are covered in this article:

Authenticate via Microsoft account

Calling az login without any parameters displays a URL and a code. Browse to the URL, enter the code, and follow the instructions to log into Azure using your Microsoft account. Once you're logged in, return to the portal.

az login

Key points:

  • Upon successful login, az login displays a list of the Azure subscriptions associated with the logged-in Microsoft account.
  • A list of properties displays for each available Azure subscription. The isDefault property identifies which Azure subscription you're using. To learn how to switch to another Azure subscription, see the section, Set the current Azure subscription.

Authenticate via Azure service principal

Create an Azure service principal: To log into an Azure subscription using a service principal, you first need access to a service principal. If you already have a service principal, you can skip this part of the section.

Automated tools that deploy or use Azure services - such as Terraform - should always have restricted permissions. Instead of having applications log in as a fully privileged user, Azure offers service principals. But, what if you don't have a service principal with which to log in? In that scenario, you can log in using your user credentials and then create a service principal. Once the service principal is created, you can use its information for future login attempts.

There are many options when creating a service principal with the Azure CLI. For this article, we'll use az ad sp create-for-rbac to create a service principal with a Contributor role. The Contributor role (the default) has full permissions to read and write to an Azure account. For more information about Role-Based Access Control (RBAC) and roles, see RBAC: Built-in roles.

Enter the following command, replacing <subscription_id> with the ID of the subscription account you want to use.

az ad sp create-for-rbac --role="Contributor" --scopes="/subscriptions/<subscription_id>"

Key points:

  • Upon successful completion, az ad sp create-for-rbac displays several values. The name, password, and tenant values are used in the next step.
  • The password can't be retrieved if lost. As such, you should store your password in a safe place. If you forget your password, you'll need to reset the service principal credentials.

Log in using an Azure service principal: In the following call to az login, replace the placeholders with the information from your service principal.

az login --service-principal -u <service_principal_name> -p "<service_principal_password>" --tenant "<service_principal_tenant>"

Set the current Azure subscription

A Microsoft account can be associated with multiple Azure subscriptions. The following steps outline how you can switch between your subscriptions:

  1. To view the current Azure subscription, use az account show.

    az account show
    
  2. If you have access to multiple available Azure subscriptions, use az account list to display a list of subscription name ID values:

    az account list --query "[].{name:name, subscriptionId:id}"
    
  3. To use a specific Azure subscription for the current Cloud Shell session, use az account set. Replace the <subscription_id> placeholder with the ID (or name) of the subscription you want to use:

    az account set --subscription="<subscription_id>"
    

    Key points:

    • Calling az account set doesn't display the results of switching to the specified Azure subscription. However, you can use az account show to confirm that the current Azure subscription has changed.

Create a base Terraform configuration file

A Terraform configuration file starts off with the specification of the provider. When using Azure, you'll specify the Azure provider (azurerm) in the provider block.

terraform {
  required_providers {
    azurerm = {
      source = "hashicorp/azurerm"
      version = "~>2.0"
    }
  }
}
provider "azurerm" {
  features {}
}
resource "azurerm_resource_group" "rg" {
  name = "<resource_group_name>"
  location = "<location>"
}

# Your Terraform code goes here...

Key points:

  • While the version attribute is optional, HashiCorp recommends pinning to a given version of the provider.
  • If you're using Azure provider 1.x, the features block isn't allowed.
  • If you're using Azure provider 2.x, the features block is required.
  • The resource declaration of azurerm_resource_group has two arguments: name and location. Set the placeholders to the appropriate values for your environment.
  • The local named value of rg for the resource group is used throughout the how-to and tutorial articles when referencing the resource group. This value is independent of the resource group name and only refers to the variable name in your code. If you change this value in the resource group definition, you'll need to also change it in the code that references it.

Create and apply a Terraform execution plan

In this section, you learn how to create an execution plan and apply it to your cloud infrastructure.

  1. To initialize the Terraform deployment, run terraform init. This command downloads the Azure modules required to create an Azure resource group.

    terraform init
    
  2. After initialization, you create an execution plan by running terraform plan.

    terraform plan -out <terraform_plan>.tfplan
    

    Key points:

    • The terraform plan command creates an execution plan, but doesn't execute it. Instead, it determines what actions are necessary to create the configuration specified in your configuration files. This pattern allows you to verify whether the execution plan matches your expectations before making any changes to actual resources.
    • The optional -out parameter allows you to specify an output file for the plan. Using the -out parameter ensures that the plan you reviewed is exactly what is applied.
    • To read more about persisting execution plans and security, see the security warning section.
  3. Once you're ready to apply the execution plan to your cloud infrastructure, you run terraform apply.

    terraform apply <terraform_plan>.tfplan
    

Reverse a Terraform execution plan

  1. To reverse, or undo, the execution plan, you run terraform plan and specify the destroy flag as follows:

    terraform plan -destroy -out <terraform_plan>.destroy.tfplan
    

    Key points:

    • The terraform plan command creates an execution plan, but doesn't execute it. Instead, it determines what actions are necessary to create the configuration specified in your configuration files. This pattern allows you to verify whether the execution plan matches your expectations before making any changes to actual resources.
    • The optional -out parameter allows you to specify an output file for the plan. Using the -out parameter ensures that the plan you reviewed is exactly what is applied.
    • To read more about persisting execution plans and security, see the security warning section.
  2. Run terraform apply to apply the execution plan.

    terraform apply <terraform_plan>.destroy.tfplan
    

Troubleshooting

For Terraform-specific support, use one of HashiCorp's community support channels to Terraform:

Next steps