Quickstart: Getting started with 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 getting started with Terraform on Azure from the Azure Cloud Shell environment.


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


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

Configure Azure Cloud Shell

  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.

Log into Azure

Cloud Shell is automatically authenticated under the Microsoft account with which you logged into the Azure portal.

Also, once logged into your Microsoft account, you are automatically logged into the default Azure subscription for that account. If the current Microsoft account is correct, and you want to switch subscriptions, see the section, Specify the current Azure subscription.

If you have multiple Microsoft accounts with Azure subscriptions, you can log into one of those accounts using any of the following options:

Log into your 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


  • 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, Specify the current Azure subscription.

Log into Azure using an 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 create 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>"


  • Upon successful completion, az ad sp create-for-rbac displays several values, including the autogenerated password. 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>"


  • Upon successful login, az login displays various properties for the Azure subscription - such as id and name.

Specify the current Azure subscription

As explained in the previous section, two of the ways to log into Azure are the following scenarios:

  • Log in using a Microsoft account: A Microsoft account can be associated with multiple Azure subscriptions - one of which is the default subscription. The default subscription is the one you use if you log in and don't switch to another.
  • Log in using an Azure service principal: A service principal is specific to an Azure subscription. Remember that the subscription information displays when you log in.

The following steps address the first scenario where you do the following tasks:

  • View the current Azure subscription
  • List all available Azure subscriptions for the current Microsoft account
  • Switch to another Azure subscription
  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>"


    • 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.

Configure Terraform

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.

Create a Terraform configuration file

In this section, you learn how to create a Terraform configuration file that creates an Azure resource group.

  1. Change directories to the mounted file share where your work in Cloud Shell is persisted. For more information about how Cloud Shell persists your files, see Connect your Microsoft Azure Files storage

    cd clouddrive
  2. Create a directory to hold the Terraform files for this demo.

    mkdir QuickstartTerraformTest
  3. Change directories to the demo directory.

    cd QuickstartTerraformTest
  4. Using your favorite editor, create a Terraform configuration file. This article uses the built-in Cloud Shell editor.

    code QuickstartTerraformTest.tf
  5. Paste the following HCL into the new file.

    provider "azurerm" {
      # The "feature" block is required for AzureRM provider 2.x.
      # If you are using version 1.x, the "features" block is not allowed.
      version = "~>2.0"
      features {}
    resource "azurerm_resource_group" "rg" {
            name = "QuickstartTerraformTest-rg"
            location = "eastus"


    • The provider block specifies that the Azure provider (azurerm) is used.
    • Within the azurerm provider block, version and features attributes are set. As the comment states, their usage is version-specific. For more information about how to set these attributes for your environment, see v2.0 of the AzureRM Provider.
    • The only resource declaration is for a resource type of azurerm_resource_group. The two required arguments for azure_resource_group are name and location.
  6. Save the file (<Ctrl>S).

  7. Exit the editor (<Ctrl>Q).

Create and apply a Terraform execution plan

Once you create your configuration files, this section explains how to create an execution plan and apply it to your cloud infrastructure.

  1. Initialize the Terraform deployment with terraform init. This step downloads the Azure modules required to create an Azure resource group.

    terraform init
  2. Terraform allows you to preview the actions to be completed with terraform plan.

    terraform plan


    • 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.
    • The terraform plan command enables 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. For more information on using the -out parameter, see the section Persisting execution plans for later deployment.
  3. Apply the execution plan with terraform apply.

    terraform apply
  4. Terraform shows you what will happen if you apply the execution plan and requires you to confirm running it. Confirm the command by entering yes and pressing the Enter key.

  5. Once you confirm the execution of the play, test that the resource group was successfully created using az group show.

    az group show -n "QuickstartTerraformTest-rg"

    If successful, az group show displays various properties of the newly created resource group.

Persist an execution plan for later deployment

In the previous section, you saw how to run terraform plan to create an execution plan. You then saw that using terraform apply applies that plan. This pattern works well when the steps are interactive and sequential.

For more complex scenarios, you can persist the execution plan to a file. Later - or even from a different machine - you can apply that execution plan.

If you use this feature, it'ss recommended that you read the article Running Terraform in automation.

The following steps illustrate the basic pattern for using this feature:

  1. Run terraform init.

    terraform init
  2. Run terraform plan with the -out parameter.

    terraform plan -out QuickstartTerraformTest.tfplan
  3. Run terraform apply, specifying the name of the file from the previous step.

    terraform apply QuickstartTerraformTest.tfplan


  • To enable use with automation, running terraform apply <filename> doesn't require confirmation.
  • If you decide to use this feature, read the security warning section.

Clean up resources

When no longer needed, delete the resources created in this article.

  1. Run the terraform destroy that will reverse the current execution plan.

    terraform destroy
  2. Terraform shows you what will happen if you reverse the execution plan and requires you to confirm. Confirm by entering yes and pressing the Enter key.

  3. Once you confirm the execution of the play, the output is similar to the following example, verify that the resource group was deleted by using az group show.

    az group show -n "QuickstartTerraformTest-rg"


    • If successful, az group show displays the fact that the resource group doesn't exist.
  4. Change directories to the parent directory and remove the demo directory. The -r parameter removes the directory contents before removing the directory. The directory contents include the configuration file you created earlier and the Terraform state files.

    cd .. && rm -r QuickstartTerraformTest

Next steps