Forem: Luke Orellana

Getting Started with Terraform on Azure: Tips and Tricks

Luke Orellana — Sun, 16 Aug 2020 19:46:27 +0000

Modules
Remote State
Source Control
Keeping Designs Simple and Reusable
Conclusion

Infrastructure development is complex, and there can be many hoops to jump through. Making changes to live infrastructure code always involves some risk and can feel like a game of Jenga. While Terraform is relatively new (initial release in 2014), several proven practices are known in the Terraform community that help deal with some hurdles and complexities. Understanding the trial and errors of those who used Terraform early on allows us to learn from them and be more efficient when we are just starting. This knowledge increases the chance of success in implementing and using Terraform.

In this guide, we will review some practical tips and tricks to be mindful of when developing with Terraform. Although these are community proven practices, keep in mind that there is more than one way to do something, and it doesn't necessarily mean that's the best and most efficient way for you.

Modules

In the software development world, we break up reusable segments of our code into parameterized functions and reuse them. This practice allows us to write tests for these functions and maintain them. In Terraform, we use modules in the same manner. We make templates of infrastructure and convert them into modules, which allows the code in each module to be reusable, maintainable, and testable.

Do not create Terraform configurations that are thousands of lines of code. It reduces code quality and clarity when debugging or making changes. Splitting up your infrastructure code into modules will also prevent you from copying and pasting code between environments, which can introduce many errors.

Version Providers and Modules

The Azure Terraform provider is changing extremely fast. Check out the change log for the Azure provider. The amount of changes made every month is extreme, and many code-breaking changes appear in many updates. To guard yourself against this, version your provider and save yourself the headache:

provider "azurerm" {
  version = "1.38.0"
}

Additionally, version your modules, especially ones from the Terraform Registry. If you're developing private modules, version those as well. Versioning modules allow for introducing module changes without affecting the infrastructure that is currently using them. For example, let's say my current environment uses version 1.1 of my server module, which is stored in a repo and tagged with v1.1:

#Create Server
module "server" {
  source    = "git::https://allanore@dev.azure.com/allanore/terraform-azure-server/_git/terraform-azure-server?ref=v1.1"

  servername    = "myserver123"
  rgname    = azurerm_resource_group.rg.name
  location  = azurerm_resource_group.rg.location
}

I need to add a new feature to the module that includes Private Link functionality. In this case, I can use module versioning to safely deploy infrastructure using the new version without affecting infrastructure using version 1.1 by tagging it as version 1.2 and sourcing the specific module version:

#Create Server
module "server" {
  source    = "git::https://allanore@dev.azure.com/allanore/terraform-azure-server/_git/terraform-azure-server?ref=v1.2"

  servername    = "myserver211"
  rgname    = azurerm_resource_group.rg.name
  location  = azurerm_resource_group.rg.location
  private_link = true
}

Using versioning for both providers and modules is a must in Terraform, and you will quickly find out why if your not using them.

Use Dependency Injections

When reusing modules throughout different environments, some environments may contain required components that already exist. For example, if I write a module that requires a storage account for the service that it's deploying, there may be some environments where this storage account already exists. This scenario may cause some people to attempt to write logic into their code to check if a resource exists or not and perform X action if it does. Introducing complex logic like this is not in line with the declarative methodology that Terraform uses. The resource either exists or not.

Instead, use dependency injections. Create the module to allow input from resources that either already exist or are created in the configuration.
Take a look at the code below, for example. We have a Network Security Group module that requires a subnet ID to associate the NSG to a subnet. In this example, we are creating the subnet within the same configuration and passing it along. The subnet does not exist prior, so we are creating one to assign to the NSG:

# Subnet is directly managed in the Terraform configuration

resource "azurerm_subnet" "snet" {
  name                 = "snet-cloudapp-1"
  resource_group_name  = azurerm_resource_group.rg.name
  virtual_network_name = azurerm_virtual_network.vnet.name
  address_prefix       = "10.0.2.0/24"
}

module "nsg" {
  source                = "./modules/nsg"
  resource_group_name   = azurerm_resource_group.rg.name
  nsg_name              = "nsg-${var.system}-httpsallow"
  source_address_prefix = ["VirtualNetwork"]
  predefined_rules = [
    {
      name     = "HTTPS"
      priority = "500"
    },
    {
      name     = "RDP"
      priority = "501"
    }
  ]

  subnet_id = azurerm_subnet.snet.id

Alternatively, we have another environment where a subnet is already existing. We would use the azurerm_subnet data source to collect the subnet id information and pass it through to our module using data.arurerm_subnet.snet.id:

#Subnet already exists and is called with a data source block

data "azurerm_subnet" "snet" {
  name                 = "snet-coudapp-1"
  virtual_network_name = "production"
  resource_group_name  = "rg-networking"
}

module "nsg" {
  source                = "../../modules/nsg"
  resource_group_name   = azurerm_resource_group.rg.name
  nsg_name              = "nsg-${var.system}-httpsallow"
  source_address_prefix = ["VirtualNetwork"]
  predefined_rules = [
    {
      name     = "HTTPS"
      priority = "500"
    },
    {
      name     = "RDP"
      priority = "501"
    }
  ]

  subnet_id = data.azurerm_subnet.snet.id
}

We are not hard coding logic into the module to check for an existing subnet in these two examples. Instead, we take the declarative approach that Terraform is designed for and state in our configuration if it already exists or if it doesn't. Our module can now be reusable in different situations, and we are not complicating the module. We also have better visibility in the module code. Another co-worker on the team can look at the module and get a clear distinction between the two environments.

Remote State

Try to use remote state as soon as possible in your Terraform development. It can save many headaches later on, especially when multiple people become involved with deploying and managing the same Terraform code.

Using remote state allows us to secure sensitive variables in our configurations. The Terraform state file is not encrypted, so keeping it on a local workstation may quickly become a security issue. Also, don't make a habit of storing Terraform state files in source control. It increases the chance of exposing sensitive variables, especially if the repository is public. Instead, use a gitignore file to omit any tf.state files from accidentally getting committed automatically.

Split Up Terraform States

Terraservices is a popular term coined a few years ago which involves splitting up Terraform state into different environments to reduce the blast radius on changes made. You don't want to keep all your eggs in one basket. Let's say a team member makes a change to resize a VM. They end up fat fingering the resource group name, and their pipeline workflow auto applies the incorrect change. Terraform rebuilds the resource group and deletes all items causing catastrophic failures to the environment. This situation is not uncommon.

Also, be aware that your Terraform plan becomes longer and longer if you don't split up a reasonably large environment into separate states. It introduces a new type of risk. Now, the Terraform plan can take longer to run and become harder to read as there are more resources affected by the change. It also means unwanted changes can be easily missed. It's easier to catch a mistake in a few lines of code vs. 10000 lines.

Ideally, you want to separate high-risk components from components that are typically changed and modified. Don't keep all the eggs in one basket. Below is a Terraform project folder structure inspired by Gruntwork's recommended setup:

prod
  └ rg
    └ main.tf
    └ variables.tf
    └ output.tf
  └ networking
  └ services
      └ frontend-app
          └ main.tf
          └ variables.tf
          └ output.tf
      └ backend-app
  └ data-storage
      └ sql
      └ redis

In the folder structure above, each folder separates out the Terraform states. The resource group has its own state, limiting the risk of daily changes made to the resource group. Services like SQL and Redis are also separated to reduce the risk of accidentally modifying the databases on any change. Splitting up environment states like this reduces a lot of risks. However, it adds a lot of complexity to the infrastructure code. We now have to design ways to feed information between each state and deal with dependencies. Terraform currently doesn't allow for an easy way to manage this. But, tools like Terragrunt, developed by Gruntwork, address handling the complexities with splitting up Terraform state.

Source Control

Terraform and source control go together hand in hand. If you're not storing your Terraform code in source control, you're missing out on the following benefits:

Change Tracking: The historical data of all infrastructure changes is extremely powerful and a great bonus for auditors or compliance requirements.
Rollback: One of the major benefits of infrastructure as code is the ability to "rollback" to the previous configuration or state. However, depending on the environment, that rollback may mean a rebuild. Storing the Terraform configuration in source control makes it easier to re-deploy a pre-existing working state of the environment.
Collaboration Among Teams: Most source control tools like Azure DevOps, Github, or Bitbucket provide a form of access control. This role-based access allows for separate teams to manage their infrastructure code or provide read-only access to other teams for increased visibility of how the environment works. No more guessing if a firewall port is open or not; look at the code and see if it is.
Automation: There are many CI/CD tools available that hook into source control. These tools amplify the development and deployment of Terraform.

There is also the concept of GitOps, where processes are automated through Git workflows like submitting a pull request. There are community tools out there like Atlantis that are amazing for GitOps with Terraform and can increase efficiency among teams.

Structure Repo to Business Needs

Designing the source control repo structure for infrastructure can be an intimidating task, especially for those making the jump from a traditional systems engineer to an infrastructure developer role. There are various strategies for storing Terraform code. Some companies put all their Terraform configurations into a single repository, some store configurations with each project's application source code. So which one should I pick?

This short answer is, it depends on your environment. Large environments are going to have a completely different set up than start-up environments. Also, team structure comes largely into play here. Do you have a team that manages all the infrastructure, or is it the developers and DevOps engineers who manage the infrastructure for their application? You will see many DevOps experts and thought leaders in the community talk about Conway's Law, which states that the communication structure of organizations is the limiter on the way that they develop and design software. This concept is pretty evident when implementing Terraform into your organization. Analyze how your teams are structured and structure your Terraform configuration repos in a way that compliments that structure.

Here are several common repo strategies:

Single Repo:: All live infrastructure code is in one single repository managed by a governing team.
One Repo Per Project: Every application has its own Terraform folder, and code is stored in a folder of the application source code.
One Repo Per Environment: Environments are split up into their own repository and managed by separate teams. For example, code managing the company firewalls are in a separate repo and managed by the security or networking team. This strategy allows each team to own and manage their infrastructure responsibilities and delegate out lesser permissions for other teams to request changes or view the environment.

Don't stress out over getting your Terraform repo structure right when your first starting out. This will most likely change several times due to business needs, scaling up, or finding a better solution for your environment. Starbucks changed up its repo structure three times over several years and ended up settling on a repo per component strategy.

Keep All Live Infrastructure in the Master Branch

All live infrastructure changes should always stay in the master branch. Storing the same infrastructure code in multiple branches can cause conflicts and create headaches. For example, let's say a team member branches off of master and adjusts the Terraform configuration to change a VM's size. They make their change and deploy it, but don't merge their branch back into master because they are still making changes. A few minutes later, someone else modifies the same VM's tags but creates a different branch off of master that hasn't been updated yet with the new VM size. The change to the tags is deployed, and now the VM size is reverted back to its original size because it didn't contain the VM resize code. This is why it's important to make sure the master branch is always a live representation of the environment.

Execute Terraform Code Through a Pipeline

When first starting on Terraform, it is typical to have each infrastructure developer manage the infrastructure by authenticating locally on their machine with the Azure provider (either with AZ Cli or some environment variables). They execute the Terraform code with their local install of Terraform. Long term, this can cause a few headaches like inconsistent Terraform versions among developers. It's best to shift to deploying code with a pipeline by storing Terraform configurations in source control and running a Continuous Integration process that executes the Terraform code on pull requests. A pipeline significantly increases automation capabilities and has a few advantages:

Terraform code is run on the same platform every time, reducing errors due to inconsistent dependencies like Terraform versions.
Pipelines can introduce configuration error checking and Terraform policy, preventing insecure or destructive configurations changes from being made.
Automated testing can run to perform regression tests against modules when a new change is made to the modules.
Many pipeline tools provide some sort of secret store functionality that makes it easy to securely pass variables through to Terraform configurations.

Keeping Designs Simple and Reusable

It's essential to keep the right balance between creating conditional logic and introducing too many complexities. For example, it may be useful to add logic into a networking module that will automatically choose the next available subnet space on a Virtual Network and create a subnet. While this logic prevents a user from having to specify a subnet address when they use the module, it also adds more complexity and can make the module more brittle. It may be better to design the module to contain an argument to take in input for the subnet address, requiring the user to calculate a subnet address for the module input beforehand. These are trade-offs with pros and cons to each.

A code review is a software development practice where multiple developers check each other's code for mistakes. With infrastructure development, this is starting to become a more common practice. Complex Terraform code will take away from the benefits of code reviews. When peers cannot easily understand the code to review, errors can be easily missed.

Complex Terraform code will also make it harder to troubleshoot issues and onboard new people to the team. One of the benefits of IaC is the living documentation that it provides. Don't put in logic that makes infrastructure code too complex to use for documentation.

Connecting inputs and outputs between modules and states can introduce many complexities and can grow to become a dependency nightmare. When passing data between modules or state files, be mindful of the purpose and limit the dependencies involved in your design.

Use Provisioners Sparingly

Most provisioners introduce platform or network constraints into our Terraform code. For example, using a provisioner to SSH into a server once it's provisioned and run a script will now require the node executing the Terraform code to have network access to the VM during deployment.

Instead, take advantage of Azure's custom script extension for VMs to pass a script through to the VM without any network constraints.

The goal is to create infrastructure code that you can execute from anywhere. Aim to achieve this as much as possible to give your design even more reusability.

Use Terraform Graph to Troubleshoot Dependency Issues

During Terraform development, you may run into resource timing errors where a resource is deployed but relies on another resource that hasn't completed provisioning yet. Maybe a disk or a storage account provisions too fast half of the time or a subnet isn't deployed before a network interface. Typically this is due to a dependency issue in the configuration and is usually solved using interpolation between the proper resources or using a "depends on" block. However, these can be difficult to track down. With terraform graph, you can run this command against a configuration directory, and it will produce a DOT format output. You can then copy and paste the output into a website like WebGraphViz to generate a visual representation of the configuration dependencies to help troubleshoot.

Use the Terraform Registry

Especially when first starting out, don't try to reinvent the wheel. The State of the DevOps report shows that highly efficient teams re-use other people's code. There are many Azure modules already created on the Terraform Registry. If you need to deploy a specific Azure service, take the time to search the registry and see if a module has already been created for the service you need. If the modules that are in the Terraform registry don't meet your needs, you can fork these modules and customize them to your own.

Conclusion

When getting started with Terraform, don't try to do everything all at once. Start small and try to make minor improvements to your infrastructure little by little. Only focus on making one quality change at a time, instead of building one big massive project from the start with pipelines, modules, tests, and remote state storage. In the end, you will achieve faster results and create a higher quality design overall.

Also, keep in mind that every environment is different. Not all of these tips will fit every Terraform use case. For example, if your environment is very simple and extremely small, it may not be worth it to split up the Terraform state files. Having good judgment and design for your infrastructure code comes into play. Learn the different concepts in the community and explore how other people are using Terraform, and then do what works best for your environment.

Infrastructure as code has not yet reached its maturity and has yet to become the standard way of operating for most companies. Over the years, research has shown that companies adopting infrastructure as code are functioning at significantly higher speeds than those that are still running on traditional methods. This research is making skillsets with tools like Terraform high in demand for companies. Taking the time to learn it is well worth it. Terraform is still in its infancy stage, and the game will continue to evolve and always get better each year. Enjoy the creativity and embrace the complexity and learning that comes with infrastructure development.

Getting Started with Terraform on Azure: Testing

Luke Orellana — Sun, 16 Aug 2020 19:41:30 +0000

Prerequisites
Step 1 — Module Repo Folder Structure
Step 2 — Types of Testing
Step 3 — Static Analysis
Step 4— Unit Testing
Step 5 — Integration Testing
Step 6 — End-to-End Testing
Conclusion

In software development, testing code is a common practice. Software developers need to be able to validate parts of their code to ensure it is working in an automated fashion. The realm of infrastructure development takes software best practices to create and manage infrastructure code, and with that comes testing. You should be writing tests for your Terraform code.

Writing tests for Terraform provides many benefits that make life easier as an infrastructure developer. Automated tests provide faster loop feedback. No more making a change to a Terraform configuration and manually running terraform apply and then checking the Azure portal to ensure that the change is there. Instead, we can use tools like Terratest to perform these steps for us and allow us to test our modules much faster than we could manually. Not only do we get faster feedback, but also fewer bugs. Automating tests for every possible scenario in a Terraform configuration provides better code coverage and can catch bugs much quicker. Tests give us increased confidence in our changes and provide us with greater predictability for our change. We can now accurately predict that our code deploys what we designed it to deploy without destroying other resources.

One common misconception is that because Terraform is declarative, we don't need to write tests for it. We are already declaring the resource that needs to exist. If there is an issue with provisioning that resource, Terraform automatically provides the error. This is a valid point, which is why when we talk about testing our Terraform code, we want to write tests for sanity checks, conditional logic, and variable outcomes in our code. For example, writing a test for the following code to create a resource group would add minimal benefit:

resource "azurerm_resource_group" "rg" {
    name     = "rg-myrg"
    location = var.location
}

If we wrote in a check to ensure that the resource group deploys to the proper location, this would be a redundant check. The resource group will automatically be built in the location we specify, and if it's not successful, an error event occurs natively through Terraform. Writing hundreds of tests in this way could become more of a maintenance burden since we would have to continually modify the test to keep up with changes to the module.

On the other hand, writing a test for the example below would be more beneficial since it contains more variance in the outcome and could potentially become altered when changes are made to the module:

resource "azurerm_resource_group" "rg" {
    name     = "rg-myrg"
    location = var.environment != "Production" ? "southcentralus" : "northcentralus"
}

In this guide, we are going to clone a module repository and walk through writing and running tests for it.

Prerequisites

Before you begin, you'll need to set up the following:

Azure subscription.

Since we will be writing tests in GO, we will need an environment set up to write these tests. We are going to use Visual Studio Codespaces to walk through this guide. Visual Studio Codespaces is an online version of Visual Studio Code. It allows us to automatically deploy an environment with a code repository so we can dive into creating tests with minimal setup.

Note: We will be using the basic sized environment for our Visual Studio Codespace. The compute for this service will be hosted in your Azure tenant, so there will be some charges associated. The average cost for a basic environment is around $0.08 per hour. Also, environments can be in a "suspended" and "active" state, which reduces pricing even further. For more information on VSC billing, check out the pricing page.

To create the Codespaces environment, navigate to the Visual Studio Codespaces login page and sign in with your Azure credentials. Make sure to use Google Chrome as FireFox and Edge are not yet supported. Once logged in, we will be presented with the following page below. Select Create Codespace:

Next, we need to create a billing plan. The billing plan connects the Visual Studio Codespace environment to our Azure subscription. Select a location that makes sense for you. Also, you can input a plan name according to your Azure naming standards. The plan name is the name of the Azure resource that deploys to your subscription. Next, we need to specify the resource group to host the Visual Studio Codespace resource. When done configuring these settings select Create:

Now we can set up our Codespace; this is the Visual Studio environment. We could have multiple Codespaces in our plan if we wanted to. Input a Codespace Name for the Codespace. Under Git Repository paste in the following GitHub repo:

https://github.com/allanore/terraform-azure-testing

The GitHub repo contains the code for the Terraform module that we will create tests for in this guide. There is also a post-create.sh script in this repo that automatically installs the tools we want for our environment, like Go and Terraform. Under Instance Type, select the Basic type. Next, select Create to build out our VSC environment finally:

We should see our environment starting to build and the post-create.sh script automatically executes and installs our tools and extensions. We are installing GO, Terraform, and a few other tools:

Note: You may need to refresh your browser at some point to get this screen to show up.

Once the Configure Codespace section shows complete, we are ready to move on to reviewing the folder structure of this repository:

Step 1 — Module Repo Folder Structure

Before we can write our tests, we need to know a little more about what this module does and the structure of the repo. The function of this Terraform module is to deploy a virtual network. There are also submodules for creating a network security group and virtual network peer. In Visual Studio Codespaces, you should see the following folder structure on the left-hand side:

At the root of this repo we can see several files, we have our .gitignore file, which contains a list of file types that we don't want to save into source control, like .tfstate. Next, we have our .pre-commit-config.yaml file, which contains a list of tools to execute on each git commit. We will go deeper into this in a later step. Last, we have our Terraform configuration files main.tf, output.tf, and variables.tf. These are the root Terraform files and perform the base function of our module, which is to create a virtual network and subnet.

Now that we've gone over the files in the root folder of this module, let's go over each folder so we have a better understanding:

.devcontainer - This folder is only used to automate the Visual Studio Codespace environment. It does not affect our terraform module.
.azuredevops - Contains our CI pipeline for Azure DevOps. We won't be going over Azure DevOps in this guide, but if you wanted to take this guide a step further and add this repository into an Azure DevOps pipeline, this is the yml file with all the steps needed.
examples - The examples folder serves two purposes. First, it serves as documentation on how to use the module. Second, it serves as Terraform code that we can use for testing. We can execute these examples in our test files to stand up resources that we can test against. There are two subfolders in the examples folder. Each one has code for performing different tasks of the module. The network folder contains code for standing up a Virtual Network and Network Security Group. The vnet-peering folder contains code for standing up two virtual networks and then peering them together.
modules - The modules folder contains our sub-modules or helper modules that provide additional features like creating a Network Security Group or Virtual Network Peer. These are optional modules that provide more flexibility and options for those that are using the module.
test - This is where our test files will live.

It is best practice in Terraform to split up tasks or services into modules. We want to use our modules as building blocks to build infrastructure one piece at a time. From a developer perspective, one might think of modules like functions. Where each module is performing the heavy lifting of a specific task:

Having our infrastructure built in smaller units like modules allows us to write tests for them. You can't write a test for a Terraform configuration that is thousands of lines of code. This also provides us with a smaller blast radius when making changes to code. If I make a change to my web app module, I don't put the entire application at risk.

Even though there is a smaller blast radius, there is still potential to destroy infrastructure when making changes to modules, which is why there needs to be a thorough automated way to test our modules and test them often. Next, we will go over the different types of tests we can write.

Step 2 — Types of Testing

There are four basic types of testing. These terms are loosely categorized in the infrastructure as code world. We are still in the infant stages, and there hasn't been a standardized definition for each category. We will be going over the way that Gruntwork defines testing in Terraform. Gruntwork is a company that provides Terraform modules to companies that desire to have IaC in their environment but don't have the skillset or time to create their own. They have years of experience developing infrastructure in Terraform and are also the creators of Terratest, which is the tool we will be using for some of our tests.

These are the four basic types of tests:

Static Analysis - Testing code without running it.
Unit Testing - Testing a single unit.
Integration Testing - Testing the functionality between two or more units.
End-to-End Testing - Testing an entire application infrastructure from the ground up.

Below is a diagram demonstrating the cost of each test. We want to run most of our tests at the bottom because that is the quickest and least costly to run. Each test will also catch different types of bugs. If we aim to catch most bugs with static analysis and unit tests, we will gain much more speed in development than if we are testing for the same bug in an end-to-end test.

Step 3 — Static Analysis

Static analysis tests involve testing our code without running it. We want to run a tool that can look at our code and analyze if there is a bug in it. A great way to perform static analysis testing is by using a tool called pre-commit. Pre-commit packages git hooks together to allow for tools to be run after each commit. If we look at the contents of the .pre-commit-config.yaml file in our repo, we can see it's configured to run several hooks. We can also see the repository URL, which contains all the git hook scripts for these hooks. This allows us to manage our git hooks and distribute them amongst team members in a much more manageable fashion. This pre-commit repo is from Gruntwork, they've done all the work to create the hooks and bundle them up into a pre-commit repository for community use:

repos:
  - repo: https://github.com/gruntwork-io/pre-commit
    rev: v0.1.4
    hooks:
      - id: terraform-fmt
      - id: terraform-validate
      - id: gofmt
      - id: golint

In the .precommit-config.yaml, there are two hooks for Terraform and two for GO. Terraform-fmt is a hook that runs the terraform fmt command, which automatically formats code to look pretty with proper spacing. Terraform-validate runs the terraform validate command against our code to ensure it is syntactically correct by checking for no misplaced { } or invalid Terraform syntax.

Let's give these two hooks a test by modifying some Terraform code. Open the variables.tf file in the root of the repo and add a description to the system variable. Let's purposely use the argument descriptions instead of description in our variable to catch the error in the pre-commit hook. Copy the snippet below and overwrite the content currently there for the system variable:

variable "system" {
  type         = string
  descriptions = "Name of the system or environment"
  default      = "terratest"
}

Save the changes by entering CTRL + S on the keyboard. Before pre-commit can run, we need to configure the hooks for this repository. Open up the terminal by entering CTRL + ~ on the keyboard and run the following command:

pre-commit install

Now let's try to commit our change we made to the system variable in the variables.tf file. When we run our commit, the pre-commit hooks for terraform fmt and terraform validate are triggered:

git add .
git commit -m "this is a test commit to trigger our pre-commit hooks"

We should see in the output that terraform validate has run and failed. We should also see the error message describing why it failed, which is because we used the argument descriptions instead of description which is the correct argument:


Terraform has installed the required providers to support the configuration
upgrade process. To begin upgrading your configuration, run the following:
    terraform 0.12upgrade

To see the full set of errors that led to this message, run:
    terraform validate

Error: Unsupported argument

  on variables.tf line 3, in variable "system":
   3:   descriptions = "Name of the system or environment"

An argument named "descriptions" is not expected here. Did you mean
"description"?

To fix the change, rename thedescriptions argument to description, which should clear our invalid syntax error. But this time, add a large number of spaces in the default argument. This unsightly formatting will trigger our terraform fmt pre-commit hook:

variable "system" {
  type         = string
  description = "Name of the system or environment"
  default      =                        "terratest"
}

Now, let's add and commit the changes again in git:

git add .
git commit -m "this is a test commit to trigger our pre-commit hooks"

This time we see that terraform fmt failed. We added that additional spaces in there which goofed up the formatting in our code. Terraform fmt automatically runs and corrects these changes when the pre-commit hook runs, if it detects any formatting changes made, it will cause a failure like so:

Note: The gofmt and golint hooks display as skipped. This is because we did not modify any GO files. The pre-commit hooks only run against the files that have been modified and will only trigger against each one's respective file type.

Terraform fmt............................................................Failed
- hook id: terraform-fmt
- files were modified by this hook

variables.tf

Terraform validate.......................................................Passed
gofmt................................................(no files to check)Skipped
golint...............................................(no files to check)Skipped

If we look at our variables.tf file, we can see that terraform fmt has corrected our spaces. Now we can run our add and commit again to save all our changes finally. In the output we can see that both checks pass this time:

vsonline:~/workspace/terraform-azure-testing$ git add .
vsonline:~/workspace/terraform-azure-testing$ git commit -m "this is a test commit to trigger our pre-commit hooks"
Terraform fmt............................................................Passed
Terraform validate.......................................................Passed
gofmt................................................(no files to check)Skipped
golint...............................................(no files to check)Skipped
[master 9b67894] this is a test commit to trigger our pre-commit hooks
 1 file changed, 3 insertions(+), 2 deletions(-)

Now our commit is complete. With pre-commit hooks, we can catch bugs before they are committed to code. This process makes our commits much cleaner and prevents silly mistakes from getting committed to source control. It also helps out with code reviews by weeding out syntactical mistakes. We can catch errors quicker in development, where if we just made a change and ran Terraform apply to test, we would have to wait for that process to kick-off before we realized our configuration wasn't syntactically correct. We can iterate through our code quicker, which speeds up development. We could also perform static analysis testing within a CI/CD pipeline to analyze our Terraform plan.

Terraform validate is a basic static analysis test that we can perform. There are many other static analysis tools in the community that provide great benefits. Below are a few to note:

TFlint - Catch provider specific bugs like incorrect Azure VM sizes.
ConfTest - Analyze TF plan files and enforces defined policies and governance.
CheckOV - Security and compliance on the Terraform configuration level.

Step 4— Unit Testing

A unit test involves testing a single unit or individual component. This is the smallest testable piece of code that can be achieved. In Terraform, we could write tests that check the resource blocks in our Terraform configuration, however many in the Terraform community agree that it offers very little value. To write a valuable unit test, we need to communicate with the provider and stand up infrastructure, which by software development testing standards is technically not a true unit test. Its an integration test. In infrastructure development with Terraform, Gruntwork defines a unit test as testing a single module by itself.

We are going to write a unit test for our networking module. We will create a test that uses Terratest. Terratest is a GO library, built by Gruntwork, for testing Terraform. Our unit test will automatically deploy the Terraform code from the examples/network folder, test to ensure the desired outcome is achieved in Azure using the Azure API, then run a terraform destroy and tear down our test infrastructure at the end. The process is the same as if we were manually testing the module, except we are automating it.

First, we need to create a GO test file called terraform_azure_network_test.go. To make this file, right-click on the test folder in Visual Studio Codespace and select new file. Then name the file terraform_azure_network_test.go. Notice that file ends in _test.go. This format indicates that the file is a GO test file. Go will automatically see this file as a test file and execute it when we run our test command later. Now we will create the foundational code for our unit test.

Base Setup

Below is the code for a base test setup. I typically use this as a starting point for creating a test and then expand from there. Copy this code to the terraform_azure_network_test.go file:

package test

import (
  "github.com/gruntwork-io/terratest/modules/terraform"
  "testing"
)


func TestTerraformAzureNetworkingExample(t *testing.T) {
    t.Parallel()

    terraformOptions := &terraform.Options{
    }

    // At the end of the test, run `terraform destroy` to clean up any resources that were created
    defer terraform.Destroy(t, terraformOptions)

    // This will run `terraform init` and `terraform apply` and fail the test if there are any errors
    terraform.InitAndApply(t, terraformOptions)

}

Let's review all the parts and pieces of the code. Starting from the top we have package test declaring that the name of our package is test (which describes the purpose of our package):

package test

Next, we have our import declaration. The import declaration contains libraries or packages used in the Golang code. In Golang, libraries and packages are similar to modules in PowerShell. We can reference packages native to GO, or we can reference ones from source control repos like GitHub. We will be adding more libraries as we build out our unit test, for now, we are using the testing GO package and the github.com/gruntwork-io/terratest/modules/terraform library created by Gruntwork, which allows us to automate deploying code with Terraform during the test:

import (
  "github.com/gruntwork-io/terratest/modules/terraform"
  "testing"
)

After our import declaration, we have our testing function, which we called TestTerraformAzureNetworkingExample. Testing functions in GO have the following format; they also need to start with the word Test with a capital T followed by a capitalized letter after Test. We also are using t.Parallel() which indicates that we want to run this test in parallel with other tests. This parallel statement is a big deal because we can run multiple tests at once to test our module in several different ways:

func TestTerraformAzureNetworkingExample(t *testing.T) {
    t.Parallel()

Inside our function is a variable called terraformOptions. In GO, we can declare variables by using :=, which is different than in PowerShell, where we would use $variables = somevalue to declare a variable. Inside our variable declaration, we are using the github.com/gruntwork-io/terratest/modules/terraform library by referencing the package name of our library terraform. Then we are referencing the object inside the library called Options. This object is called a struct in Golang. A struct is similar to an object in PowerShell. We are essentially making an options object that we can add a collection of settings to and pass them through to Terraform. For now, we have no options defined in our struct, but in the next step, we will add them:

    terraformOptions := &terraform.Options{
    }

To finish out our testing function, we have two more lines of code. We are using the Terratest library again by referencing terraform. However, this time we are using the Destroy and InitAndApply functions from the Terratest library to perform the standard terraform init, apply, and destroy commands using our defined options in the terraformOptions variables. Note, the defer in GO is similar to a finally in PowerShell. The defer means GO will run this function at the end and will always run it even if the test were to error out:

defer terraform.Destroy(t, terraformOptions)

terraform.InitAndApply(t, terraformOptions)

Configure Terraform Options

Let's add some options to our terraformOptions variable. Our Terraform code in the examples/network folder has a variables.tf file that allows us to input several parameters and customize our network infrastructure when deployed:

variable "system" {
  type        = string
  description = "Name of the system or environment"
  default     = "terratest"
}
variable "location" {
  type        = string
  description = "Azure location of terraform server environment"
  default     = "westus2"
}
variable "vnet_address_space" {
  description = "Address space for Virtual Network"
}

variable "subnet_prefix" {
  type = string
  description = "Prefix of subnet address"
}

We need to define the values for these variables in our unit test and then pass them through to Terraform using the terraformOptions variable.

If you notice in our variables.tf file, we have a variable for location. For the location variable value, we want to be able to randomly test deploying into different regions that could be a possibility for us to use. This randomization allows us to have a thorough test since each test can deploy infrastructure into one of the listed regions. We will do this by providing a list of possible regions to deploy to in our test and then randomly pick one when the test runs. Doing this can also help sniff out any region-specific incidents occurring in Azure when we run our tests.

To create a list of regions, we are declaring a variable called regions and setting the variable type to []string which stands for a list of strings. Then, we are filling out that list with various regions in Azure that we want to test in:

    var regions = []string{
        "centralus",
        "eastus",
        "eastus2",
        "northcentralus",
        "southcentralus",
        "westcentralus",
        "westus",
        "westus2",
    }

Next, we create a variable for our regions that uses the function RandomString to pick a region from our list of regions randomly:

azureRegion := random.RandomString(regions)

Now that we have a variable created for the Terraform location input variable, we can configure the values for the rest of the input variables. For the system variable, we are going to use a similar concept that we used for the Azure region. We are going to generate a random name for the system name.

systemName := strings.ToLower(random.UniqueId())

This random name generation allows us to run this test several times at the same time without overlapping within the same resource name. It is useful when multiple people are adding features to a module on their branches and are running the tests. Next, we have hardcoded values for our virtual network address and subnet prefix:

vnetAddress := "10.0.0.0/16"
subnetPrefix := "10.0.0.0/24"

Now that we have values for our input variables, we need to pass them into terraformOptions. We add the TerraformDir argument to specify the directory of the code we want to execute is the code in the examples/network folder of our repo. Next, we are importing a map of variables, which allows us to pass values through to Terraform as if we were using the -var option in the command line. We are passing through all four variables that we just set up in GO:

terraformOptions := &terraform.Options{

        TerraformDir: "../examples/network",

        Vars: map[string]interface{}{
            "system":             systemName,
            "location":           azureRegion,
            "vnet_address_space": vnetAddress,
            "subnet_prefix":      subnetPrefix,
        },
    }

We need to add two more packages and libraries to our import declaration since we are now using them to create a random string for the system name and to choose our Azure region randomly:

import (
    "strings"
    "testing"


    "github.com/gruntwork-io/terratest/modules/random"
    "github.com/gruntwork-io/terratest/modules/terraform"
)

Now we have our test configured to run our Terraform code in the examples/network folder with values for the variables.tf file. At this point, our unit test in terraform_azure_network_test.go should look like the following:

package test

import (
    "strings"
    "testing"

    "github.com/gruntwork-io/terratest/modules/random"
    "github.com/gruntwork-io/terratest/modules/terraform"
)

// An example of how to test the Terraform module in examples/terraform-azure-example using Terratest.
func TestTerraformAzureNetworkingExample(t *testing.T) {
    t.Parallel()

    var regions = []string{
        "centralus",
        "eastus",
        "eastus2",
        "northcentralus",
        "southcentralus",
        "westcentralus",
        "westus",
        "westus2",
    }

    // Pick a random Azure region to test in.
    azureRegion := random.RandomString(regions)

    // Network Settings for Vnet and Subnet
    systemName := strings.ToLower(random.UniqueId())
    vnetAddress := "10.0.0.0/16"
    subnetPrefix := "10.0.0.0/24"

    terraformOptions := &terraform.Options{

        // The path to where our Terraform code is located
        TerraformDir: "../examples/network",

        // Variables to pass to our Terraform code using -var options
        Vars: map[string]interface{}{
            "system":             systemName,
            "location":           azureRegion,
            "vnet_address_space": vnetAddress,
            "subnet_prefix":      subnetPrefix,
        },
    }

    // At the end of the test, run `terraform destroy` to clean up any resources that were created
    defer terraform.Destroy(t, terraformOptions)

    // This will run `terraform init` and `terraform apply` and fail the test if there are any errors
    terraform.InitAndApply(t, terraformOptions)
}

Add In The Tests

Now we are ready to add in some tests. We want to write tests that are meaningful and don't want the process to become a burden to maintain. Determining if a test is meaningful depends on the situation and environment. A meaningful test for someone else doesn't mean it is meaningful for your case. For this example, we are going to keep things simple. We want to test that our virtual network subnet is truly associated with an NSG after our Terraform example is deployed. This test ensures that any change to our module in the future won't interrupt this desired outcome, which could result in a potential security risk if the NSG was not assigned to the subnet.

Our Terraform code in the examples/network folder contains the following in the output.tf file. These are values we want to use to perform our tests:

output "vnet_rg" {
  description = "Location of vnet"
  value       = module.vnet.vnet_rg
}

output "subnet_id" {
  description = "Subnet ID"
  value       = module.vnet.subnet_id
}

output "nsg_name" {
  description = "Name of vnet Security Group"
  value       = module.nsg.nsg_name
}

Note: We want to make sure our modules are not too large to be tested. We don't want a 10,000 line module because it's not possible to unit test. The more you write tests for your modules, the more structured your modules become for testing. This practice becomes a great benefit as it allows for a more stable and better structured Terraform code.

The terraform.Output function allows us to collect output values from our Terraform deployment after the init and apply has completed. We are referencing the terraformOptions variable which contains our Terraform environment settings. Also we include each output value from output.tf. Then we save each output value into a variable in GO:

vnetRG := terraform.Output(t, terraformOptions, "vnet_rg")
subnetID := terraform.Output(t, terraformOptions, "subnet_id")
nsgName := terraform.Output(t, terraformOptions, "nsg_name")

Now we will use the output variables we created to directly check our Azure environment using the Azure API and confirm that the NSG we create is assigned to the subnet. We perform a lookup of all subnet IDs assigned to the NSG using the azure.GetAssociationsforNSG function, which requires the virtual network resource group and NSG name. Then we run a test using the assert GO package, which allows us to compare all the resources IDs in our nsgAssociations variable with the subnetID variable, which contains the output information from our Terraform code. This comparison allows us to take the subnet ID output from Terraform and look into Azure using the API and verify that it's assigned to the NSG we created:

    // Look up Subnet and NIC ID associations of NSG
    nsgAssociations := azure.GetAssociationsforNSG(t, vnetRG, nsgName, "")

    //Check if subnet is associated with NSG
    assert.Contains(t, nsgAssociations, subnetID)

If the subnet ID is in the list of NSG associations, our test will pass, if it is missing, the test will fail.

Lastly, we will need to add two more libraries to our import declaration. We are using assert to perform a comparison and validate our subnet ID is associated with the NSG, and we are using the function azure.GetAssociationsforNSG from the GO library aztest. The azure.GetAssociationsforNSG function allows us to quickly authenticate with our Azure environment and look up assigned resources to an NSG. It is just a helper function for working with the Azure GO SDK which communicates with the Azure API:

Note: The Azure test library in Terratest right now is fairly limited compared to AWS. Gruntwork has been heavily focused on building out the AWS and GCP modules. In the current state, most companies are just making their own private libraries for testing their resources in Azure. To help people get started writing tests for Terraform code in Azure, I have expanded upon the Terratest Azure testing functions and created a public GO library called AzTest, feel free to use it.

import (
    "strings"
    "testing"

    "github.com/allanore/aztest/modules/azure"
    "github.com/gruntwork-io/terratest/modules/random"
    "github.com/gruntwork-io/terratest/modules/terraform"
    "github.com/stretchr/testify/assert"
)

Now that we have our test written, our entire unit test is as follows. Copy the following to terraform_azure_network_test.go:

package test

import (
    "strings"
    "testing"

    "github.com/allanore/aztest/modules/azure"
    "github.com/gruntwork-io/terratest/modules/random"
    "github.com/gruntwork-io/terratest/modules/terraform"
    "github.com/stretchr/testify/assert"
)

// An example of how to test the Terraform module in examples/terraform-azure-example using Terratest.
func TestTerraformAzureNetworkingExample(t *testing.T) {
    t.Parallel()

    var regions = []string{
        "centralus",
        "eastus",
        "eastus2",
        "northcentralus",
        "southcentralus",
        "westcentralus",
        "westus",
        "westus2",
    }

    // Pick a random Azure region to test in.
    azureRegion := random.RandomString(regions)

    // Network Settings for Vnet and Subnet
    systemName := strings.ToLower(random.UniqueId())
    vnetAddress := "10.0.0.0/16"
    subnetPrefix := "10.0.0.0/24"

    terraformOptions := &terraform.Options{

        // The path to where our Terraform code is located
        TerraformDir: "../examples/network",

        // Variables to pass to our Terraform code using -var options
        Vars: map[string]interface{}{
            "system":             systemName,
            "location":           azureRegion,
            "vnet_address_space": vnetAddress,
            "subnet_prefix":      subnetPrefix,
        },
    }

    // At the end of the test, run `terraform destroy` to clean up any resources that were created
    defer terraform.Destroy(t, terraformOptions)

    // This will run `terraform init` and `terraform apply` and fail the test if there are any errors
    terraform.InitAndApply(t, terraformOptions)

    // Run `terraform output` to get the value of an output variable
    vnetRG := terraform.Output(t, terraformOptions, "vnet_rg")
    subnetID := terraform.Output(t, terraformOptions, "subnet_id")
    nsgName := terraform.Output(t, terraformOptions, "nsg_name")

    // Look up Subnet and NIC ID associations of NSG
    nsgAssociations := azure.GetAssociationsforNSG(t, vnetRG, nsgName, "")

    //Check if subnet is associated with NSG
    assert.Contains(t, nsgAssociations, subnetID)

}

Whew! We just built our first unit test in GO. Now, let's run it. First, we need to authenticate to Azure. The easiest way is to use Azure CLI. Type in the following command in the terminal while in the ~/workspace/terraform-azure-testing/test directory. Log in with your Azure account:

az login

Now, we need to set the ARM_SUBSCRIPTION_ID environment variable which is used for several functions in Terratest when deploying to Azure:

export ARM_SUBSCRIPTION_ID=$(az account show | jq '.id' -r)

Once logged in with Azure CLI, we need to download all of our dependencies for our tests. The dependencies include the packages that we specified during the import declaration. This concept is similar to running install-module in PowerShell to install all the external modules used in a script. Type the following command using go get while in the test directory:

go get -t -v

We see the libraries and packages download. This process may take a minute. Once complete, we are ready to run our test. To kick off the test, type in the following command. We are using the go test command with -v to specify verbose output. Also, we are specifying the GO test file that we just created:

go test -v terraform_azure_network_test.go

We will start to see Terraform executing our example code in the output display:

=== RUN   TestTerraformAzureNetworkingExample
=== PAUSE TestTerraformAzureNetworkingExample
=== CONT  TestTerraformAzureNetworkingExample
TestTerraformAzureNetworkingExample 2020-05-09T14:30:17Z retry.go:72: terraform [init -upgrade=false]
TestTerraformAzureNetworkingExample 2020-05-09T14:30:17Z command.go:86: Running command terraform with args [init -upgrade=false]
TestTerraformAzureNetworkingExample 2020-05-09T14:30:17Z command.go:168: Initializing modules...
TestTerraformAzureNetworkingExample 2020-05-09T14:30:17Z command.go:168: 
TestTerraformAzureNetworkingExample 2020-05-09T14:30:17Z command.go:168: Initializing the backend...
TestTerraformAzureNetworkingExample 2020-05-09T14:30:17Z command.go:168: 
TestTerraformAzureNetworkingExample 2020-05-09T14:30:17Z command.go:168: Initializing provider plugins...
TestTerraformAzureNetworkingExample 2020-05-09T14:30:19Z command.go:168: 
TestTerraformAzureNetworkingExample 2020-05-09T14:30:19Z command.go:168: Terraform has been successfully initialized!
TestTerraformAzureNetworkingExample 2020-05-09T14:30:19Z command.go:168:

Don't hit CTRL + C during the test; this will prevent resources from being cleaned up in Azure. If the test should error out, the defer stage runs and executes Terraform destroy to remove anything that was provisioned.

The test is executing the Terraform code in the examples/network folder, running a test to ensure that the NSG is associated with the subnet, and running Terraform destroy at the end. Once the test run completes, we see the result like below:

TestTerraformAzureNetworkingExample 2020-05-09T14:32:01Z command.go:168: azurerm_resource_group.rg: Destruction complete after 47s
TestTerraformAzureNetworkingExample 2020-05-09T14:32:01Z command.go:168: 
TestTerraformAzureNetworkingExample 2020-05-09T14:32:01Z command.go:168: Destroy complete! Resources: 7 destroyed.
--- PASS: TestTerraformAzureNetworkingExample (103.78s)
PASS
ok      command-line-arguments  103.783s

Now our unit test is complete! In the next step, we will add an integration test.

Step 5 — Integration Testing

An integration test with infrastructure code is defined as testing the functionality of two components interacting together. This could be a Webapp with a SQL database or two microservices interacting with each other. For demonstration purposes, we are going to keep it very simple and stand up two virtual networks and test that we can peer them together. The example code for each vnet is in the examples/vnet-peering directory. Our integration test will execute the Terraform code in vnet1 to deploy the first virtual network. Once complete, the test will execute the code in vnet2 to deploy a second virtual network and peer them together. We will then write a test that validates that the peering was successful:

examples
    └──networking
    └──vnet-peering
      └─vnet1
          └─main.tf
          └─output.tf
          └─variables.tf
      └─vnet2
          └─main.tf
          └─output.tf
          └─variables.tf

In our test directory, let's create another GO test file called terraform_azure_network_peering_test.go.

Base Test

We will copy the following code below and paste it in as our base test configuration. Notice we now have two sets of terraform.options as well as two sets of the destroy and apply steps:

package test

import (

    "testing"


    "github.com/gruntwork-io/terratest/modules/terraform"
)

// An example of how to test the Terraform module in examples/terraform-azure-example using Terratest.
func TestTerraformAzureNetworkingPeeringExample(t *testing.T) {
    t.Parallel()


    vnet1Opts := &terraform.Options{

    }

    // Deploy VNet1
    defer terraform.Destroy(t, vnet1Opts)
    terraform.InitAndApply(t, vnet1Opts)

    vnet2Opts := &terraform.Options{

    }

    // Deploy VNet2
    defer terraform.Destroy(t, vnet2Opts)
    terraform.InitAndApply(t, vnet2Opts)
}

Add in Terraform Options

Next, we will add in the Terraform options. We include the steps for randomized Azure regions as well as using random system names for our virtual networks. The big difference from our unit test is that we are passing the Terraform output values after deploying VNet1 to the terraform.options of VNet2, this allows us to configure the peering between them:

package test

import (
    "strings"
    "testing"

    "github.com/gruntwork-io/terratest/modules/random"
    "github.com/gruntwork-io/terratest/modules/terraform"
)

// An example of how to test the Terraform module in examples/terraform-azure-example using Terratest.
func TestTerraformAzureNetworkingPeeringExample(t *testing.T) {
    t.Parallel()

    var regions = []string{
        "centralus",
        "eastus",
        "eastus2",
        "northcentralus",
        "southcentralus",
        "westcentralus",
        "westus",
        "westus2",
    }

    // Pick a random Azure region to test in.
    azureRegion := random.RandomString(regions)

    // Network Settings for Vnet and Subnet
    vnet1Sysname := strings.ToLower(random.UniqueId())
    vnet1Address := "10.0.0.0/16"
    vnet1SubnetPrefix := "10.0.0.0/24"
    vnet2Sysname := strings.ToLower(random.UniqueId())
    vnet2Address := "10.1.0.0/16"
    vnet2SubnetPrefix := "10.1.0.0/24"

    vnet1Opts := &terraform.Options{

        // The path to where our Terraform code is located
        TerraformDir: "../examples/vnet-peering/vnet1",

        // Variables to pass to our Terraform code using -var options
        Vars: map[string]interface{}{
            "system":             vnet1Sysname,
            "location":           azureRegion,
            "vnet_address_space": vnet1Address,
            "subnet_prefix":      vnet1SubnetPrefix,
        },
    }

    // Deploy VNet1
    defer terraform.Destroy(t, vnet1Opts)
    terraform.InitAndApply(t, vnet1Opts)
    vnetOutRG := terraform.Output(t, vnet1Opts, "vnet_rg")
    vnetOutName := terraform.Output(t, vnet1Opts, "vnet_name")

    vnet2Opts := &terraform.Options{

        // The path to where our Terraform code is located
        TerraformDir: "../examples/vnet-peering/vnet2",

        // Variables to pass to our Terraform code using -var options
        Vars: map[string]interface{}{
            "system":             vnet2Sysname,
            "location":           azureRegion,
            "vnet_address_space": vnet2Address,
            "subnet_prefix":      vnet2SubnetPrefix,
            "peer_vnet_rg":       vnetOutRG,
            "peer_vnet_name":     vnetOutName,
        },
    }

    // Deploy VNet2
    defer terraform.Destroy(t, vnet2Opts)
    terraform.InitAndApply(t, vnet2Opts)
}

Add In The tests

Next, we will add in the tests. We are collecting the resource group and virtual network name from the output of deploying VNet2. Then we are using those values to look up the virtual network with the azure.GetVnetbyName function and storing them in the vnet2Properties variable. We are taking the virtual network peering properties from the vnet2Properties variable and using a for loop in GO to loop through all of the values within the VirtualNetworkPeerings property, which contains a list of all peerings made on the virtual network. We are then validating that all peerings in that property are in a Succeeded state, ensuring that they peered properly:

    // Collect RG and Virtual Network name from VNet2 Output
    vnet2RG := terraform.Output(t, vnet2Opts, "vnet_rg")
    vnet2Name := terraform.Output(t, vnet2Opts, "vnet_name")

    // Look up Virtual Network 2 by Name
    vnet2Properties := azure.GetVnetbyName(t, vnet2RG, vnet2Name, "")

    //Check if VNet Peering in VNet2 Provisioned Successfully
    for _, vnet := range *vnet2Properties.VirtualNetworkPeerings {
        assert.Equal(t, "Succeeded", string(vnet.VirtualNetworkPeeringPropertiesFormat.ProvisioningState), "Check if Peerings provisioned successfully")
    }

Our final integration test file should look like the following:

package test

import (
    "strings"
    "testing"

    "github.com/allanore/aztest/modules/azure"
    "github.com/gruntwork-io/terratest/modules/random"
    "github.com/gruntwork-io/terratest/modules/terraform"
    "github.com/stretchr/testify/assert"
)

// An example of how to test the Terraform module in examples/terraform-azure-example using Terratest.
func TestTerraformAzureNetworkingPeeringExample(t *testing.T) {
    t.Parallel()

    var regions = []string{
        "centralus",
        "eastus",
        "eastus2",
        "northcentralus",
        "southcentralus",
        "westcentralus",
        "westus",
        "westus2",
    }

    // Pick a random Azure region to test in.
    azureRegion := random.RandomString(regions)

    // Network Settings for Vnet and Subnet
    vnet1Sysname := strings.ToLower(random.UniqueId())
    vnet1Address := "10.0.0.0/16"
    vnet1SubnetPrefix := "10.0.0.0/24"
    vnet2Sysname := strings.ToLower(random.UniqueId())
    vnet2Address := "10.1.0.0/16"
    vnet2SubnetPrefix := "10.1.0.0/24"

    vnet1Opts := &terraform.Options{

        // The path to where our Terraform code is located
        TerraformDir: "../examples/vnet-peering/vnet1",

        // Variables to pass to our Terraform code using -var options
        Vars: map[string]interface{}{
            "system":             vnet1Sysname,
            "location":           azureRegion,
            "vnet_address_space": vnet1Address,
            "subnet_prefix":      vnet1SubnetPrefix,
        },
    }

    // Deploy VNet1
    defer terraform.Destroy(t, vnet1Opts)
    terraform.InitAndApply(t, vnet1Opts)
    vnetOutRG := terraform.Output(t, vnet1Opts, "vnet_rg")
    vnetOutName := terraform.Output(t, vnet1Opts, "vnet_name")

    vnet2Opts := &terraform.Options{

        // The path to where our Terraform code is located
        TerraformDir: "../examples/vnet-peering/vnet2",

        // Variables to pass to our Terraform code using -var options
        Vars: map[string]interface{}{
            "system":             vnet2Sysname,
            "location":           azureRegion,
            "vnet_address_space": vnet2Address,
            "subnet_prefix":      vnet2SubnetPrefix,
            "peer_vnet_rg":       vnetOutRG,
            "peer_vnet_name":     vnetOutName,
        },
    }

    // Deploy VNet2
    defer terraform.Destroy(t, vnet2Opts)
    terraform.InitAndApply(t, vnet2Opts)

    // Collect RG and Virtual Network name from VNet2 Output
    vnet2RG := terraform.Output(t, vnet2Opts, "vnet_rg")
    vnet2Name := terraform.Output(t, vnet2Opts, "vnet_name")

    // Look up Virtual Network 2 by Name
    vnet2Properties := azure.GetVnetbyName(t, vnet2RG, vnet2Name, "")

    //Check if VNet Peering in VNet2 Provisioned Successfully
    for _, vnet := range *vnet2Properties.VirtualNetworkPeerings {
        assert.Equal(t, "Succeeded", string(vnet.VirtualNetworkPeeringPropertiesFormat.ProvisioningState), "Check if Peerings provisioned successfully")
    }
}

Now, let's run our integration test. No need to download the dependencies because we downloaded them already when we ran the unit test. Run the following command in the terminal specifying the terraform_azure_network_peering_test.go file:

go test -v terraform_azure_network_peering_test.go

We should see both virtual networks get deployed, followed by our test to verify the peering state between them. Then a terraform destroy is ran to tear down our test infrastructure. At the end we should see that our test has passed:

TestTerraformAzureNetworkingPeeringExample 2020-05-10T13:22:40Z command.go:168: azurerm_resource_group.rg: Destruction complete after 48s
TestTerraformAzureNetworkingPeeringExample 2020-05-10T13:22:41Z command.go:168: 
TestTerraformAzureNetworkingPeeringExample 2020-05-10T13:22:41Z command.go:168: Destroy complete! Resources: 7 destroyed.
--- PASS: TestTerraformAzureNetworkingPeeringExample (347.89s)
PASS
ok      command-line-arguments  347.890s

For an extra challenge, we could run both tests at the same time using the following command. Because we have t.Parallel() in our test functions, each test can be run in parallel. This is incredibly powerful because we can test our modules in several different ways at the same time:

Note: In a typical continuous integration pipeline for our module, we would ideally be running all tests in our test folder at the same time when we commit our changes to the module repo. This allows us to get a full amount of test coverage against our module.

go test -v

In the next step we go over how to perform end to end testing.

Step 6 — End-to-End Testing

End-to-end testing involves standing up the entire application composed of multiple modules. This can take hours, depending on how big the application is, which can make it incredibly time-consuming to run end-to-end tests. If the application takes a significant amount of time to deploy, it is recommended to deploy a copy of the entire application in a separate test environment and keep it deployed for a specific amount of time. Then, when we make a change to any of the modules in the application, we can re-deploy that module out to the application and then test the application functionality as a whole with automated tests.

Conclusion

As you can see, writing tests can take a bit of work. Because IaC is such a newly adopted concept, the tooling and concepts for writing tests can be awkward and complex. However, the rewards are worth it. A module with thorough tests will have much more stability and provides greater confidence when teams are executing that code.

Infrastructure code typically "rots" quickly. There are constantly new updates made to Azure, Terraform providers, and Terraform itself, which can make it a full-time task to ensure modules are always working as they should. To help with this, consider scheduling tests to run nightly to catch these types of bugs as early as possible.

It is strongly encouraged to run your tests in an Azure subscription separate from production and even development. When developing and testing modules, there is always a risk of destroying other resources. Also, this allows for safely configuring automated cleanup on the testing subscription to ensure any tests that bombed-out arent leaving remnants of infrastructure.

There is also the concept of test-driven development (TDD), which is a software development practice where tests are written first before the code is written. This is not very common in the infrastructure development world yet because of its infancy stage. However, IaC veterans like Kief Morris are huge advocates for TDD and describe that performing TDD for infrastructure code drives better design as it requires one to think through the outcome and function of their infrastructure when developing.

Tests for infrastructure code are critical to the stability of the infrastructure. Jacob Kaplan-Moss, software developer and co-creator of Django said it best, "Code without tests is broken as designed". Writing tests for IaC can be time-consuming and difficult because of the immaturity of the tooling; however, it is an essential piece of infrastructure development that shouldn't be overlooked.

In the next article, we will complete out this series by reviewing best practices when using Terraform.

Getting Started with Terraform on Azure: Importing Existing Infrastructure

Luke Orellana — Sun, 16 Aug 2020 19:14:11 +0000

Prerequisites
Step 1 — Simple Import
Step 2 — Complex Imports
Step 3 — Import Modules
Step 4 — Remote State
Conclusion

When first introduced to Terraform, we can see how easy it is to build new environments and manage them with software development practices. We start to experience the numerous benefits that come with infrastructure as code such as deployment speed, stability through templatized environments, and transparency through code documentation. However, all these benefits emerge from the new infrastructure we are creating with Terraform. What about our old pre-existing infrastructure? How can we manage the environments we've already built by hand with code?

One of the main principles with infrastructure as code is to "define everything in code". If this principle only applies to new environments, we are greatly diminishing the benefits gained by limiting this process to only a small scope of the environment. This is why it's essential to retroactively return to pre-existing environments and convert them over to code.

Terraform can import pre-existing resources into a state file, which then allows Terraform to manage those resources with a configuration file. However, this process is still in its infancy stage and is actively being improved upon by Hashicorp. As of right now, Terraform cannot automatically generate code based on existing infrastructure. The import process included creating configuration files by hand, then importing the existing resources via the Terraform command line. Another caveat currently is that only a single resource can be imported into a state file at a time.

In this guide, we walk through the process of importing pre-existing infrastructure into Terraform. First, we deploy some infrastructure with Azure CLI and then import it into a state file to be managed by Terraform.

Prerequisites

Before you begin, you'll need to set up the following:

Azure subscription.
Azure Cloud Shell. Be sure to check out the prerequisites on "Getting Started with Terraform on Azure: Deploying Resources" for a guide on setting up Azure Cloud Shell.

In this guide, we will be importing some pre-existing infrastructure into Terraform. Before we can walk through the import process, we will need some existing infrastructure in our Azure account. Below is a list of commands to run in Azure CloudShell using Azure CLI in the Bash environment. The Azure CLI commands deploy a resource group, network security group, virtual network, and subnets. You can copy the entire configuration below and paste it directly into Azure CloudShell to deploy everything all at once:

az group create --name rg-terraform --location eastus

az network vnet create \
  --name vnet-terraform-eastus-1 \
  --resource-group rg-terraform \
  --address-prefix 10.0.0.0/16 \
  --subnet-name subnet-terraform-10.0.0.0_24 \
  --subnet-prefix 10.0.0.0/24

az network nsg create -g rg-terraform -n nsg-terraform

az network nsg rule create -g rg-terraform --nsg-name nsg-terraform -n Allow-HTTPS --priority 100 \
    --source-address-prefixes '*' --source-port-ranges 443 \
    --destination-address-prefixes '*' --destination-port-ranges 443 --access Allow \
    --protocol Tcp --description "Allow HTTPS"

az network nsg rule create -g rg-terraform --nsg-name nsg-terraform -n Allow-HTTP --priority 110 \
    --source-address-prefixes '*' --source-port-ranges 80 \
    --destination-address-prefixes '*' --destination-port-ranges 80 --access Allow \
    --protocol Tcp --description "Allow HTTP"

az network vnet subnet create -g rg-terraform --vnet-name vnet-terraform-eastus-1 \
    -n subnet-terraform-10.0.1.0_24 \
    --address-prefixes 10.0.1.0/24  \
    --network-security-group nsg-terraform

We should now have a resource group with a network security group, virtual network, and two subnets. In the next steps we will walk through how to import this infrastructure into Terraform.

Step 1 — Simple Import

We will start by importing a resource group into Terraform. Remember, we can only import one resource at a time. To import a resource, we need to have a Terraform configuration file already built for that resource. The configuration file allows us to link the resource identifier used by Terraform to the resource identifier used in Azure. To import our resource group, we will create the following configuration in a main.tf file within Azure CloudShell:

provider "azurerm" {
    version="1.38.0"
}

# create resource group
resource "azurerm_resource_group" "rg"{
    name = "rg-terraform"
    location = "eastus"
}

The syntax to perform an import with Terraform uses the following format for Azure resources using the terraform import command:

terraform import <Terraform Resource Name>.<Resource Label> <Azure Resource ID>

We already have the resource block name of our resource group, which is azurerm_resource_group, according to the Azure Terraform provider. We also need to reference the given local name that we are calling our resource group block, which in our example is rg. Now we need the resource ID of the resource group in Azure to tell Terraform we want to import this item from Azure. To retrieve the resource ID, we can look up the properties of the rg-terraform resource group in the Azure portal, or we can use the following command in the Azure CloudShell to display the ID:

az group show --name rg-terraform

The output looks like the following, copy the ID of the resource group:

{
  "id": "/subscriptions/c8f32571-82db-4a89-923b-7e149764bae3/resourceGroups/rg-terraform",
  "location": "eastus",
  "managedBy": null,
  "name": "rg-terraform",
  "properties": {
    "provisioningState": "Succeeded"
  },
  "tags": null,
  "type": "Microsoft.Resources/resourceGroups"
}

Now we have all the information we need to import our resource group into a Terraform state file. In the same directory as our main.tf file, we need to run terraform init to download the plugin for the Azure provider before we can perform the import:

terraform init

After terraform init has completed, we are good to run terraform import with our Terraform and Azure identifiers. The import command inspects the main.tf file and the Azure environment to ensure those IDs are relevant. Then imports information about the resource into a state file:

terraform import azurerm_resource_group.rg /subscriptions/c8f32571-82db-4a89-923b-7e149764bae3/resourceGroups/rg-terraform

We can see the output indicating the import was successful:

azurerm_resource_group.rg: Importing from ID "/subscriptions/c8f32571-82db-4a89-923b-7e149764bae3/resourceGroups/rg-terraform"...
azurerm_resource_group.rg: Import prepared!
  Prepared azurerm_resource_group for import
azurerm_resource_group.rg: Refreshing state... [id=/subscriptions/c8f32571-82db-4a89-923b-7e149764bae3/resourceGroups/rg-terraform]

Import successful!

Now, let's confirm that our resource group is indeed in the state file by running cat terraform.tfstate to display the contents. We can see that the resource group is in the state file with the resource ID that we specified:

{
  "version": 4,
  "terraform_version": "0.12.23",
  "serial": 1,
  "lineage": "1377f481-dc7d-7da9-45aa-a40f007ebb3d",
  "outputs": {},
  "resources": [
    {
      "mode": "managed",
      "type": "azurerm_resource_group",
      "name": "rg",
      "provider": "provider.azurerm",
      "instances": [
        {
          "schema_version": 0,
          "attributes": {
            "id": "/subscriptions/c8f32571-82db-4a89-923b-7e149764bae3/resourceGroups/rg-terraform",
            "location": "eastus",
            "name": "rg-terraform",
            "tags": {}
          },
          "private": "eyJzY2hlbWFfdmVyc2lvbiI6IjAifQ=="
        }
      ]
    }
  ]
}

After using terraform import, it is a good idea to run terraform plan to validate that the configuration in the main.tf file matches the resource that imported. When we run terraform plan we want to see output indicating that there are no changes in the plan:

No changes. Infrastructure is up-to-date.

This means that Terraform did not detect any differences between your
configuration and real physical resources that exist. As a result, no
actions need to be performed.

Once the plan has been successfully validated and reports no changes between our main.tf and the current state, we can now deem this configuration as good and store it in our source control repo, as it now contains the configuration for live infrastructure.

Had we configured our main.tf to specify a resource group in the westus2 location, even though the actual resource is in eastus, we would still be allowed to import the resource, and the state file would contain the correct eastus location of our resource group in Azure. However, if we ran terraform plan, the plan would indicate that a rebuild of the resource group would need to occur to match the resource configuration in the main.tf file:

An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
-/+ destroy and then create replacement

Terraform will perform the following actions:

  # azurerm_resource_group.rg must be replaced
-/+ resource "azurerm_resource_group" "rg" {
      ~ id       = "/subscriptions/c8f32571-82db-4a89-923b-7e149764bae3/resourceGroups/rg-terraform" -> (known after apply)
      ~ location = "eastus" -> "westus2" # forces replacement
        name     = "rg-terraform"
      ~ tags     = {} -> (known after apply)
    }

Plan: 1 to add, 0 to change, 1 to destroy.

This is why it's crucial to run a terraform plan after the terraform import to validate that the configuration and infrastructure are up to date. If the main.tf displays changes when running the terraform plan, there is a risk with using that configuration file to apply changes in the future.

Step 2 — Complex Imports

The example of importing a resource group is defined as a simple import. However, resources that contain several resources within them are deemed as complex imports. An example of this would be a virtual network that contains subnets or a network security group that contains security rules. Both of these resources contain multiple child resources. It is important to be aware of child resources when importing these components. We must capture all the child resources for each resource in the main.tf terraform configuration file, or they will be removed when running terraform apply.

Below is the Terraform configuration for importing our network security group and virtual network. Notice the child resources they both contain. Copy the configuration below and save over the previous main.tf we used to import the resource group in step 1:

provider "azurerm" {
    version="1.38.0"
}

# create resource group
resource "azurerm_resource_group" "rg"{
    name = "rg-terraform"
    location = "eastus"
}


resource "azurerm_network_security_group" "nsg" {
  name                = "nsg-terraform"
  location            = azurerm_resource_group.rg.location
  resource_group_name = azurerm_resource_group.rg.name


  security_rule {
    name                       = "Allow-HTTPS"
    description                = "Allow HTTPS"
    priority                   = 100
    direction                  = "Inbound"
    access                     = "Allow"
    protocol                   = "Tcp"
    source_port_range          = "443"
    destination_port_range     = "443"
    source_address_prefix      = "*"
    destination_address_prefix = "*"
  }

  security_rule {
    name                       = "Allow-HTTP"
    description                = "Allow HTTP"
    priority                   = 110
    direction                  = "Inbound"
    access                     = "Allow"
    protocol                   = "Tcp"
    source_port_range          = "80"
    destination_port_range     = "80"
    source_address_prefix      = "*"
    destination_address_prefix = "*"
  }
}



resource "azurerm_virtual_network" "vnet" {
  name                = "vnet-terraform-eastus-1"
  location            = azurerm_resource_group.rg.location
  resource_group_name = azurerm_resource_group.rg.name
  address_space       = ["10.0.0.0/16"]


  subnet {
    name           = "subnet-terraform-10.0.0.0_24"
    address_prefix = "10.0.0.0/24"
  }

  subnet {
    name           = "subnet-terraform-10.0.1.0_24"
    address_prefix = "10.0.1.0/24"
    security_group = azurerm_network_security_group.nsg.id
  }
}

We need the resource IDs of our network security group and virtual network. We could retrieve this information from the Azure portal, or we can type in the following two commands to get them from Azure CloudShell:

az network nsg show -g rg-terraform -n nsg-terraform

az network vnet show -g rg-terraform -n vnet-terraform-eastus-1

Next, we use terraform import for each resource specifying their Terraform resource block identifier and Azure resource ID:

terraform import azurerm_network_security_group.nsg /subscriptions/c8f32571-82db-4a89-923b-7e149764bae3/resourceGroups/rg-terraform/providers/Microsoft.Network/networkSecurityGroups/nsg-terraform

terraform import azurerm_virtual_network.vnet /subscriptions/c8f32571-82db-4a89-923b-7e149764bae3/resourceGroups/rg-terraform/providers/Microsoft.Network/virtualNetworks/vnet-terraform-eastus-1

Once terraform import is successful for our network security group and virtual network, we can run cat terraform.tfstate to confirm they are now in the state file. The last test is to run terraform plan to validate that our main.tf holds the correct configuration settings for our resources:

Refreshing Terraform state in-memory prior to plan...
The refreshed state will be used to calculate this plan, but will not be
persisted to local or remote state storage.

azurerm_resource_group.rg: Refreshing state... [id=/subscriptions/c8f32571-82db-4a89-923b-7e149764bae3/resourceGroups/rg-terraform]
azurerm_network_security_group.nsg: Refreshing state... [id=/subscriptions/c8f32571-82db-4a89-923b-7e149764bae3/resourceGroups/rg-terraform/providers/Microsoft.Network/networkSecurityGroups/nsg-terraform]
azurerm_virtual_network.vnet: Refreshing state... [id=/subscriptions/c8f32571-82db-4a89-923b-7e149764bae3/resourceGroups/rg-terraform/providers/Microsoft.Network/virtualNetworks/vnet-terraform-eastus-1]

------------------------------------------------------------------------

No changes. Infrastructure is up-to-date.

The plan output shows no changes, which means our main.tf is solid and can now be used to manage this infrastructure.

Step 3 — Import Modules

Now that we know how to import existing resources into Terraform, how do we go about importing a module?

Let's set up a module folder to create a module for the configuration we made in step 2 and test importing it into a state file. In the current directory where we performed the tasks in step 2, we will create a subfolder called module using the following directory structure:

testingimportfolder
    └── main.tf
    └── terraform.tfstate
    └── terraform.tfstate.backup
    └───module
          └── main.tf

The main.tf consists of a resource block for the Azure provider and a module resource block with the source argument pointing to the parent directory. The source argument is telling our module to use the main.tf in the directory above it. This is not the ideal folder structure for a normal in production module, but for the sake of demonstrating importing a module with very little pre-setup, the module subfolder works:

provider "azurerm" {
    version="1.38.0"
}

module "importlab" {
    source = "../"
}

Importing a module into a state file is similar to importing resources. However, we need to import each resource that the module configures. For our example, since we are just re-using the main.tf file that we created in step 2, we need to import the same three resources. But, we need to change the resource identifier on the Terraform configuration side to declare that we are using a module to manage these resources. We can do this by appending our module name to the beginning of each resource identifier, which ends up looking like module.importlab.<resource>. While in the module folder directory, run terraform init to initialize the directory and pull down the Azure provider. Then run terraform import with the following syntax to import the three resources managed by the importlab module:

terraform import module.importlab.azurerm_resource_group.rg /subscriptions/c8f32571-82db-4a89-923b-7e149764bae3/resourceGroups/rg-terraform

terraform import module.importlab.azurerm_network_security_group.nsg /subscriptions/c8f32571-82db-4a89-923b-7e149764bae3/resourceGroups/rg-terraform/providers/Microsoft.Network/networkSecurityGroups/nsg-terraform

terraform import module.importlab.azurerm_virtual_network.vnet /subscriptions/c8f32571-82db-4a89-923b-7e149764bae3/resourceGroups/rg-terraform/providers/Microsoft.Network/virtualNetworks/vnet-terraform-eastus-1

After importing the three module resources, we can run cat terraform.tfstate to see the contents of the state file. We see our module resource is present along with the resources that it manages:

{
  "version": 4,
  "terraform_version": "0.12.23",
  "serial": 3,
  "lineage": "919aec3c-da13-c83a-a846-c7d1838e13ef",
  "outputs": {},
  "resources": [
    {
      "module": "module.importlab",
      "mode": "managed",
      "type": "azurerm_network_security_group",
      "name": "nsg",
      "provider": "module.importlab.provider.azurerm",
      "instances": [
        {
...

Now we can validate our configuration by running terraform plan. The plan output should state no changes in infrastructure, indicating that we now have our module configuration imported into Terraform state.

Step 4 — Remote State

We can use terraform import with either a local or remote state. Initially, we could have configured a remote backend at the beginning of this guide and imported all of our resources into a remote state file. However, some might like to manipulate a state file locally and then copy it up to their remote state location after they have a valid configuration. For this purpose, we will demonstrate migrating our newly imported local state over to an Azure storage account backend. To create an Azure storage account with a storage container, run the following commands in Azure CloudShell:

Note: Make sure to use an externally unique name for the storage account, or Azure will error out when deploying one.

az group create --location eastus --name rg-terraformstate

az storage account create --name terrastatestorage2134 --resource-group rg-terraformstate --location eastus --sku Standard_LRS

az storage container create --name terraformstate --account-name terrastatestorage2134

To copy our state file over to the storage account, we will create an additional file called backend.tf in the modules folder:

module
   └── main.tf
   └── backend.tf

The backend.tf file contains the following code to direct our Terraform configuration to save its state to our storage container. Copy the code below and save it to backend.tf inside the module folder:

terraform {
  backend "azurerm" {
    resource_group_name  = "rg-terraformstate"
    storage_account_name = "terrastatestorage2134"
    container_name       = "terraformstate"
    key                  = "testimport.terraform.tfstate"
  }
}

Next, we run terraform init in the modules folder and select yes to copy our current state file over to the Azure storage account:

Initializing modules...

Initializing the backend...
Do you want to copy existing state to the new backend?
  Pre-existing state was found while migrating the previous "local" backend to the
  newly configured "azurerm" backend. No existing state was found in the newly
  configured "azurerm" backend. Do you want to copy this state to the new "azurerm"
  backend? Enter "yes" to copy and "no" to start with an empty state.

  Enter a value: yes


Successfully configured the backend "azurerm"! Terraform will automatically
use this backend unless the backend configuration changes.

Initializing provider plugins...

Terraform has been successfully initialized!

Our state is now safely stored in the Azure storage account, where the state files for our other infrastructure should be (don't use local state in production). If we wanted to double check, we can use the terraform state list command to display the resources in our remote state:

module.importlab.azurerm_network_security_group.nsg
module.importlab.azurerm_resource_group.rg
module.importlab.azurerm_virtual_network.vnet

Our pre-existing infrastructure has now been imported and saved in our remote state container to be managed by Terraform going forward.

Conclusion

As you can see, importing existing infrastructure into Terraform can be awkward and tedious. There is not a fully ironed out process for it yet. However, converting pre-existing infrastructure over to be managed by Terraform is worth the time. The benefits gained through "everything in code" will most likely outweigh the time spent on importing infrastructure.

This process can also be used as a learning experience for employees or team members just starting with Terraform. Following documented procedures for onboarding infrastructure into Terraform can get them well acquainted with how Terraform works with the state file and Azure infrastructure.

In the next article, we will go deep into the weeds of testing and walk through how to get started with testing our Terraform code.

Getting Started with Terraform on Azure: Functions, Expressions, and Loops

Luke Orellana — Sun, 16 Aug 2020 19:08:49 +0000

Prerequisites
Step 1 — Functions
Step 2 — Complex Expressions
Step 3 — Loops
Conclusion

As we start building out infrastructure with Terraform, the logic used to build interlinking modules becomes more complicated. This is why it's essential to understand the options and capabilities of HCL (Hashicorp Configuration Language). Not only will this make it easier to create the necessary logic flow in our code, but we can also optimize our configurations. Writing a Terraform configuration in a different way can potentially provide a performance boost in deployment.

Understanding how to create loops and advanced expressions can give our code a cleaner look and provide our teammates with a more precise understanding of the infrastructure when reading the Terraform configuration. Remember, our Terraform code is not meant to just deploy our infrastructure and get the job done. The goal of HCL is to bridge the gap between human and machine-friendly interfaces by providing code that is easy to read and work well with the command line at the same time.

In this guide, we are going to create a module and learn how to use functions, expressions, and loops in our Terraform configurations.

Prerequisites

If you'd like to follow along with the concepts in this guide, you'll need to set up the following:

Azure subscription.
Azure Cloud Shell. Be sure to check out the prerequisites on "Getting Started with Terraform on Azure: Deploying Resources" for a guide on how to set this up.

Step 1 — Functions

HCL contains built-in functions that can be called within an expression to logically create values for our arguments. With Terraform, we can use an interactive console for testing our Terraform expressions instead of having to run our Terraform configuration each time. Simply type in the following syntax where Terraform is installed. This works in Azure Cloud Shell as well:

terraform console

You will be directed to the Terraform console, which will display a >. You may test some of these function examples in this guide in your own Terraform console. There are many built-in functions, but we will go over the most commonly used ones:

Lower is useful for values that need to always be lowercased like storage account names:

> lower("TFStoragesta")
tfstoragesta

Replace is useful for manipulating naming schemes or number formats of certain values. The format is the following:

replace(string, substring, replacement)

A simple use case would be replacing a string in a text:

> replace("Luke likes CloudSkills", "likes", "loves")
Luke loves CloudSkills

A more practical use case would be using the replace function with a regex query to swap out any subscription ID on a resource ID string with a specific subscription:

> replace("/subscriptions/f8c37571-4325-4a97-977b-7a216e64bae3/resourceGroups/rg-remotestatetfc", "/[0-9A-Fa-f]{8}-(?:[0-9A-Fa-f]{4}-){3}[0-9A-Fa-f]{12}/", "c1c37531-2355-4a57-947b-4e236e64bae3")
/subscriptions/c1c37531-2355-4a57-947b-4e236e64bae3/resourceGroups/rg-remotestatetfc

Min and max are used to find the highest and lowest values in a set of numbers, which can be useful for determining the largest or smallest resource:

> max(32,64,99)
99

> min (32,128,1024)
32

Split can be used to get two string values out of a single value. For example, a Standard_LRS storage type string can be split up for the azurerm_storage_account resource that takes the following two arguments for account_teir and account_replication_type:

resource "azurerm_storage_account" "example" {
  name                = "storageaccountname"
  resource_group_name = azurerm_resource_group.example.name

  location                 = azurerm_resource_group.example.location
  account_tier             = "Standard"
  account_replication_type = "LRS"
}

We could take a variable input of Standard_LRS and use split to get each value reducing the number of variables needed:

> split("_","Standard_LRS")
[
  "Standard",
  "LRS",
]

Element can then be used to access each index of the list by wrapping our split function with an element function and specifying the index value:

> element(split("_","Standard_LRS"), 0)
Standard

We could then write our resource block like the following if we created an input variable for the Standard_LRS string:

resource "azurerm_storage_account" "example" {
  name                = "storageaccountname"
  resource_group_name = azurerm_resource_group.example.name

  location                 = azurerm_resource_group.example.location
  account_tier             = element(split("_","var.storage_type"), 0)
  account_replication_type = element(split("_","var.storage_type"), 1)
}

Coalesce will take a series of arguments and return the first one that isn't null or an empty string "":

> coalesce("40", "50", "20")
40

> coalesce( "", "50", "20")
50

This can be useful for creating a set of optional variables and selecting the one that contains a value:

Note: There are several configurations in this article that will be truncated by a ... to reduce the amount of code in this article.

resource "azurerm_virtual_machine" "main" {
  name                  = "${var.prefix}-vm"
  location              = azurerm_resource_group.main.location
  resource_group_name   = azurerm_resource_group.main.name
  network_interface_ids = [azurerm_network_interface.main.id]
  vm_size               = coalesce( var.small, var.medium, var.large)
...

Length returns the numerical length of a string, list, or map:

> length(["32GB", "64GB"])
2

This is very useful to get the number of an item. For the example above, we can determine that we have two disk sizes, and we will be requiring 2 disks to be created. We could then feed this value into a loop that we will demo later in this guide.

Setproduct will display all possible combinations of a given set:

> setproduct(["development", "staging", "production"], ["EastUS", "WestUS"])
[
  [
    "development",
    "EastUS",
  ],
  [
    "development",
    "WestUS",
  ],
  [
    "staging",
    "EastUS",
  ],
  [
    "staging",
    "WestUS",
  ],
  [
    "production",
    "EastUS",
  ],
  [
    "production",
    "WestUS",
  ],
]

File will read the contents of a file and return it as a string:

> file("${path.module}/test.ps1")
#This is an empty PS1

This is very useful when using the template_file data source type, which allows you to insert variables into your files and then pass them into another resource for use. Below we have a test.ps1 file that will set the DNS addresses of a server. We have two variables inserted into our PowerShell script represented by ${DNS_Server1} and ${DNS_Server2}:

# test.ps1
Set-DnsClientServerAddress -InterfaceIndex 12 -ServerAddresses ("${DNS_Server1}","{DNS_Server2}")

Next, we can use the template_file resource to specify the test.ps1 script and replace the ${DNS_Server1} and ${DNS_Server2} variables inside the script with their respective values declared in the vars block. We can then reference the newly transformed test.ps1 file that includes the proper values for the DNS servers by using data.template_file.init.rendered in the custom_data attribute of a virtual machine resource block:

data "template_file" "init" {
  template = "${file("./test.ps1")}"
  vars = {
    DNS_Server1 = "10.0.0.1"
    DNS_Server2 = "10.0.0.2"
  }

resource "azurerm_virtual_machine" "main" {
...
  os_profile {
      computer_name  = "myserver"
      admin_username = "adminuser"
      admin_password = "badpassword123"
      custom_data = data.template_file.init.rendered
    }
...
}

Functions are a great way to manipulate the data in our configurations, however, sometimes there is a need to include more logic into our code. This is where expressions come into play.

Step 2 — Complex Expressions

Expressions are used to compute the values in our HCL configurations. Complex expressions allow us to provide additional logic to our resources deployed. Below are some examples of popular expressions we can use in our code:

Operators

Operators either combine the result of two values and produce a third or take one value and transform it. The typical operators used in configurations are the following:

Equal a==b if a is equal to b then the result is true.
Not Equal a != b if a does not equal b then the result is true.
Either Or a || b if either a or b is true then the result is true.
Both True a && b if both a and b are true then the result is true.
Not True !a if a is false then the result is true.

Conditions

Conditions determine the value based on the result of two bool (true or false) expressions:

condition ? true : false

This is typically used to set up a default value in a Terraform configuration. For example, if we have a virtual machine module and would like to provide the option to deploy a VM to a different location than it's resource group, we could create a variable for vm_location and set a default for "" like below:

variable "vm_location" {
    type = string
    description = "Azure location of terraform server environment"
    default = ""

}

In our virtual machine resource block, we could then use a conditional expression for the location argument. The condition expression provides the logic to use the value for var.vm_location if it is not an empty string. If var.vm_location is still an empty string because the user of the module never specified one, then the condition expression provides the logic to default to the location of our resource group:

resource "azurerm_virtual_machine" "main" {
  name                  = "MyVMName"
  location              = var.vm_location != "" ? var.vm_location : azurerm_resource_group.main.location
  ...

For Expressions

For expressions allow us to take a value and change it. We can use this to iterate over a list of values and modify them. For example, we can obtain a list of subnets from the azurerm_virtual_network data source and use a for expression to iterate over each subnet and change the output formatting it with a lowercase:

data "azurerm_virtual_network" "example" {
  name                = "LukeLab-NC-Prod-Vnet"
  resource_group_name = "NetworkingTest-RG"
}

output "subnets" {
  value = [for s in data.azurerm_virtual_network.example.subnets : lower(s)]
}

When running this config the output is the following:

Outputs:

subnets = [
  "lukeapp-nc-prod-subnet",
  "lukeapp5-nc-prod-subnet",
  "lukeapp4-nc-prod-subnet",
  "lukeapp3-nc-prod-subnet",
  "lukeapp2-nc-prod-subnet",
]

Notice the for expression is wrapped in []. This will give us a tuple output. We can also change the output type to an object by wrapping our for expression in {} instead. Also we must include two result expressions using the => symbol to separate them:

data "azurerm_virtual_network" "example" {
  name                = "LukeLab-NC-Prod-Vnet"
  resource_group_name = "NetworkingTest-RG"
}

output "subnets" {
  value = {for s in data.azurerm_virtual_network.example.subnets : s => lower(s)}
}

The output then changes to an object type with out two results:

Outputs:

subnets = {
  "LukeApp-NC-Prod-Subnet" = "lukeapp-nc-prod-subnet"
  "LukeApp2-NC-Prod-Subnet" = "lukeapp2-nc-prod-subnet"
  "LukeApp3-NC-Prod-Subnet" = "lukeapp3-nc-prod-subnet"
  "LukeApp4-NC-Prod-Subnet" = "lukeapp4-nc-prod-subnet"
  "LukeApp5-NC-Prod-Subnet" = "lukeapp5-nc-prod-subnet"
}

We can also perform more advanced logic with our for expressions. We can filter out our results by including an if statement followed by some logic. In this example, we are only listing subnets that are not an empty string:

[for s in data.azurerm_virtual_network.example.subnets : lower(s) if s != ""

For a more advanced example of this, we can use regexall to filter our results to only include subnets that meet our regex requirements. In this example, we are selecting only subnets with LukeApp 2-4 in the name. Also, note we are wrapping our regexall function with a length function and then checking to ensure that it is greater than 0. This is the recommended way to validate a string that matches the regex requirements. If we were to skip using length the if expression would error out when the regex query doesn't match the other subnets:

data "azurerm_virtual_network" "example" {
  name                = "LukeLab-NC-Prod-Vnet"
  resource_group_name = "NetworkingTest-RG"
}

output "subnets" {
  value = [for s in data.azurerm_virtual_network.example.subnets : s if length(regexall("LukeApp[2-4]-NC-Prod-Subnet", s)) > 0]

}

When we run this, we get only the subnets that matched our regex statement:

Outputs:

subnets = [
  "LukeApp4-NC-Prod-Subnet",
  "LukeApp3-NC-Prod-Subnet",
  "LukeApp2-NC-Prod-Subnet",
]

Splat Expressions

Splat expressions are a cleaner way of performing some of the same tasks that we can do with a for expression. In our previous for expression example, we listed subnets of a virtual network like the following:

[for s in data.azurerm_virtual_network.example.subnets : s]

Instead, we can use a splat expression like so. The [*] symbol directs us to iterate over all the elements in the list:

data.azurerm_virtual_network.example[*].subnets

We could also reference the index of the attribute to select the first subnet in the list:

data.azurerm_virtual_network.example[*].subnets[0]

Complex expressions are a great way to add logic to our Terraform configurations and allow us to create modules that can be versatile. For example, if we wanted all VMs deployed in the development environment to use slower, less expensive disk types, we could code the logic with a conditional expression. Using a variable var.environment to state the environment we want to deploy to, we could then reference that variable to conditionally decide to use either the Standard_LRS or Premium_LRS disk type:

resource "azurerm_virtual_machine" "main" {
  ...

  storage_os_disk {
    name              = "myosdisk1"
    caching           = "ReadWrite"
    create_option     = "FromImage"
    managed_disk_type = var.environment == "Development" ? "Standard_LRS" :  "Premium_LRS"
  }
  ...

Functions and complex expressions can do a lot of our heavy lifting, however there is one more tool in our tool belt that can help simplify our code. In the next section we will cover loops.

Step 3 — Loops

Loops in Terraform can help us in many ways. We can quickly iterate through a collection of components with a loop. We can also scale our resources efficiently using loops. Here are some of the ways we can loop through resources in Terraform:

Count

Count is a very popular technique in Terraform configurations. It allows us to create multiple instances of a resource block. Almost all resource blocks can use the count attribute. Below is an example of an azurerm_resource_group resource block that has the count attribute set to 3. This tells Terraform to create this resource three times. Also note, we are modifying the name of the resource group each time; otherwise, our code would error out because we can't have resource groups with duplicate names. We are using the count.index variable, which is accessible only when the count argument is used. count.index specifies the index value of our resource, which is the number assigned to that resource's "spot in the list". The index numbering starts at 0. So if we are deploying a resource with a count of 3 we will have three indexes of 0,1, and 2:

provider "azurerm" {
  features {}
}

resource "azurerm_resource_group" "main" {
  count = 3
  name     = "rg-MyResourceGroup-${count.index}"
  location = "West US 2"
}

When we run terraform plan against this configuration we can see that we will be deploying three resource groups:

Terraform will perform the following actions:

  # azurerm_resource_group.main[0] will be created
  + resource "azurerm_resource_group" "main" {
      + id       = (known after apply)
      + location = "westus2"
      + name     = "rg-MyResourceGroup-0"
    }

  # azurerm_resource_group.main[1] will be created
  + resource "azurerm_resource_group" "main" {
      + id       = (known after apply)
      + location = "westus2"
      + name     = "rg-MyResourceGroup-1"
    }

  # azurerm_resource_group.main[2] will be created
  + resource "azurerm_resource_group" "main" {
      + id       = (known after apply)
      + location = "westus2"
      + name     = "rg-MyResourceGroup-2"
    }

Plan: 3 to add, 0 to change, 0 to destroy.

Count is used for conditional logic as well. If we set the count value of a resource to 0, Terraform will deploy 0 copies of that resource. This is handy for creating the logic to deploy resources only in certain circumstances. In the example below, we have a bool variable for bootdiag_storage. We also have a resource block for azure storage to be used for our boot diagnostic storage. Notice the count argument now has a conditional expression to evaluate if the bootdiag_storage variable is true or not. If the variable is set to true, set the count argument to 1, indicating that we will deploy this resource. If the variable is set to false, count is then set to 0 indicating that the azure_storage_account resource will not be deployed:

provider "azurerm" {
  features {}
}

variable "bootdiag_storage" {
  type = bool
  description = "Enter the name of the boot diagnostic storage account if one is desired"
  default = false
}

resource "azurerm_resource_group" "rg" {

  name     = "rg-MyResourceGroup"
  location = "West US 2"
}

resource "azurerm_storage_account" "bootdiag" {
  count = var.bootdiag_storage ? 1 : 0

  name                     = "myterraformvmsadiag"
  resource_group_name      = azurerm_resource_group.rg.name
  location                 = azurerm_resource_group.rg.location
  account_tier             = "Standard"
  account_replication_type = "GRS"
}

For_each

For_each loops allow us to iterate through a list or map. This allows us to have cleaner code. For example, instead of creating an azurerm_network_security_rule resource for each rule we want to create for our NSG, we can simply create a map variable called inbound_rules. We can then use for_each to loop through each item in our map and create a rule for each one. Also, note we are using each.key and each.value variables in our configuration to specify the key and value pairs in our map:

provider "azurerm" {
  features {}
}

variable "inbound_rules" {
  type = map
  description = "A map of allowed inbound ports and their priority value"
  default = {
    101 = 3389
    102 = 22
    103 = 443

  }
}

resource "azurerm_resource_group" "rg" {

  name     = "rg-mytesourcegroup"
  location = "West US 2"
}

resource "azurerm_network_security_group" "nsg" {
  name                = "nsg-mysecuritygroup"
  location            = azurerm_resource_group.rg.location
  resource_group_name = azurerm_resource_group.rg.name
}

resource "azurerm_network_security_rule" "nsg_rule" {
  for_each = var.inbound_rules
  name                        = "port_${each.value}"
  priority                    = each.key
  direction                   = "Inbound"
  access                      = "Allow"
  protocol                    = "Tcp"
  source_port_range           = "*"
  destination_port_range      = each.value
  source_address_prefix       = "*"
  destination_address_prefix  = "*"
  resource_group_name         = azurerm_resource_group.rg.name
  network_security_group_name = azurerm_network_security_group.nsg.name
}

When we run terraform plan we can see all our NSG rule resource blocks will be created with the values from our map:

Terraform will perform the following actions:

  # azurerm_network_security_group.nsg will be created
  + resource "azurerm_network_security_group" "nsg" {
      + id                  = (known after apply)
      + location            = "westus2"
      + name                = "nsg-mysecuritygroup"
      + resource_group_name = "rg-mytesourcegroup"
      + security_rule       = (known after apply)
    }

  # azurerm_network_security_rule.nsg_rule["101"] will be created
  + resource "azurerm_network_security_rule" "nsg_rule" {
      + access                      = "Allow"
      + destination_address_prefix  = "*"
      + destination_port_range      = "3389"
      + direction                   = "Inbound"
      + id                          = (known after apply)
      + name                        = "port_3389"
      + network_security_group_name = "nsg-mysecuritygroup"
      + priority                    = 101
      + protocol                    = "Tcp"
      + resource_group_name         = "rg-mytesourcegroup"
      + source_address_prefix       = "*"
      + source_port_range           = "*"
    }

  # azurerm_network_security_rule.nsg_rule["102"] will be created
  + resource "azurerm_network_security_rule" "nsg_rule" {
      + access                      = "Allow"
      + destination_address_prefix  = "*"
      + destination_port_range      = "22"
      + direction                   = "Inbound"
      + id                          = (known after apply)
      + name                        = "port_22"
      + network_security_group_name = "nsg-mysecuritygroup"
      + priority                    = 102
      + protocol                    = "Tcp"
      + resource_group_name         = "rg-mytesourcegroup"
      + source_address_prefix       = "*"
      + source_port_range           = "*"
    }

  # azurerm_network_security_rule.nsg_rule["103"] will be created
  + resource "azurerm_network_security_rule" "nsg_rule" {
      + access                      = "Allow"
      + destination_address_prefix  = "*"
      + destination_port_range      = "443"
      + direction                   = "Inbound"
      + id                          = (known after apply)
      + name                        = "port_443"
      + network_security_group_name = "nsg-mysecuritygroup"
      + priority                    = 103
      + protocol                    = "Tcp"
      + resource_group_name         = "rg-mytesourcegroup"
      + source_address_prefix       = "*"
      + source_port_range           = "*"
    }

  # azurerm_resource_group.rg will be created
  + resource "azurerm_resource_group" "rg" {
      + id       = (known after apply)
      + location = "westus2"
      + name     = "rg-mytesourcegroup"
    }

Plan: 5 to add, 0 to change, 0 to destroy.

Dynamic Blocks

Resources that contain repeatable configuration blocks can make use of dynamic blocks. For example, the azurerm_virtual_machine resource includes a storage_data_disk block for defining the configuration of our VM data disks. This block can be used multiple times within azurerm_virtual_machine to specify multiple data disks. Instead of repeating the same block structure over and over again, we can use dynamic blocks to simplify our code. This is done by prefixing the block with dynamic and using for_each to iterate through our storage_data_disk block.

In this example, we have a variable disk_size_gb that can accept a string of comma-separated numbers to indicate the size of the disks to add. So if we wanted three disks that are sized as 32GB, 64GB, and 128GB we would set this variable to "32,64,128" in our terraform.tfvars file.

In the for_each argument underneath our dynamic storage_data_disk block, we are using the split function to separate our disk size values and iterate through each one. We are using storage_data_disk.value to reference the value of each number in disk_size_gb fo each disk size. Also, we are using storage_data_disk.key to reference the index number of our storage_data_disk block and using that value in the name and lun arguments to provide unique values:


variable "disk_size_gb" {
  description = "Size of disks in GBs. Choose multiple disks by comma separating each size"
  type        = string
  default = "64"
}

# Create virtual machine
resource "azurerm_virtual_machine" "vm" {
  name                  = var.servername
  location              = azurerm_resource_group.rg.location
  resource_group_name   = azurerm_resource_group.rg.name
  network_interface_ids = [azurerm_network_interface.nic.id]
  vm_size               = "Standard_D2s_v3"
...
  dynamic storage_data_disk {
    for_each = split(",", var.disk_size_gb)
      content {
        name              = "${var.servername}_datadisk_${storage_data_disk.key}"
        create_option     = "Empty"
        lun               = storage_data_disk.key
        disk_size_gb      = storage_data_disk.value
        managed_disk_type = "StandardSSD_LRS"
      }
  }
...

When we run terraform plan against this configuration we get the following output specifying the storage_data_disk blocks for our three disks:

 # azurerm_virtual_machine.vm will be created
  + resource "azurerm_virtual_machine" "vm" {
      + availability_set_id              = (known after apply)
      + delete_data_disks_on_termination = false
      + delete_os_disk_on_termination    = false
      + id                               = (known after apply)
      + license_type                     = (known after apply)
      + location                         = "westus2"
      + name                             = "vmterraform"
      + network_interface_ids            = (known after apply)
      + resource_group_name              = "rg-terraexample"
      + tags                             = (known after apply)
      + vm_size                          = "Standard_D2s_v3"

      + identity {
          + identity_ids = (known after apply)
          + principal_id = (known after apply)
          + type         = (known after apply)
        }

      + os_profile {
          + admin_password = (sensitive value)
          + admin_username = "joeblow"
          + computer_name  = "vmterraform"
          + custom_data    = "c991e3a089d3ad26ec85af93f698c375db0933f2"
        }

      + os_profile_windows_config {
          + enable_automatic_upgrades = false
          + provision_vm_agent        = true

          + additional_unattend_config {
              + component    = "Microsoft-Windows-Shell-Setup"
              + content      = (sensitive value)
              + pass         = "oobeSystem"
              + setting_name = "FirstLogonCommands"
            }
          + additional_unattend_config {
              + component    = "Microsoft-Windows-Shell-Setup"
              + content      = (sensitive value)
              + pass         = "oobeSystem"
              + setting_name = "AutoLogon"
            }
        }

      + storage_data_disk {
          + caching                   = (known after apply)
          + create_option             = "empty"
          + disk_size_gb              = 32
          + lun                       = 0
          + managed_disk_id           = (known after apply)
          + managed_disk_type         = "StandardSSD_LRS"
          + name                      = "vmterraform_datadisk_0"
          + write_accelerator_enabled = false
        }
      + storage_data_disk {
          + caching                   = (known after apply)
          + create_option             = "empty"
          + disk_size_gb              = 64
          + lun                       = 1
          + managed_disk_id           = (known after apply)
          + managed_disk_type         = "StandardSSD_LRS"
          + name                      = "vmterraform_datadisk_1"
          + write_accelerator_enabled = false
        }
      + storage_data_disk {
          + caching                   = (known after apply)
          + create_option             = "empty"
          + disk_size_gb              = 128
          + lun                       = 2
          + managed_disk_id           = (known after apply)
          + managed_disk_type         = "StandardSSD_LRS"
          + name                      = "vmterraform_datadisk_2"
          + write_accelerator_enabled = false
        }

      + storage_image_reference {
          + offer     = "WindowsServer"
          + publisher = "MicrosoftWindowsServer"
          + sku       = "2019-Datacenter"
          + version   = "latest"
        }

      + storage_os_disk {
          + caching                   = "ReadWrite"
          + create_option             = "FromImage"
          + disk_size_gb              = (known after apply)
          + managed_disk_id           = (known after apply)
          + managed_disk_type         = "Premium_LRS"
          + name                      = "stvmvmterraformos"
          + os_type                   = (known after apply)
          + write_accelerator_enabled = false
        }
    }

Loops are great for reducing repetitive code and creating scalable resources. However, they can also add additional complexity for others reading the Terraform configuration, so choose wisely when using loops within Terraform code.

Conclusion

In this article, we learned about functions, complex expressions, and loops. We reviewed examples and discussed their benefits and use-cases within our Terraform code. The HCL language is both human-readable and machine-friendly enough to perform complex logic described in this guide. However, there is a balance to writing infrastructure code that will not only get the job done but also provide documentation to another team member. Use them where it makes sense but not to the point where code is hard to understand. Remember, simplicity is a crucial component of creating long-lasting automated solutions.

Getting Started with Terraform on Azure: Modules

Luke Orellana — Sun, 16 Aug 2020 19:01:58 +0000

Prerequisites
Step 1 — Module Architecture
Step 2 — Creating Modules
Step 3 — Module Outputs
Step 4 — Git Modules
Conclusion

When creating production-grade Terraform configurations, modules are an absolute must. One of the more apparent benefits of using them is that they allow our code to be DRY. DRY is a software development term that stands for Don't Repeat Yourself. The idea is to reduce the amount of repetition in our code. In Terraform, we can create modules to build re-usable components of our infrastructure. For example, we can have a module for SQL servers and a separate one for Virtual Machines. We can then re-use each module to deploy services and build out the infrastructure for various environments.

Modules should also be used as a way to split up a large environment into smaller components. We don't want to have a single main.tf file with over 1000 lines of code. Splitting up our code into smaller modules allows us to make changes to our environment safely without affecting large chunks of code. Also, by splitting our environment up into modules, we now have pieces of our infrastructure separated into a testable module. The ability to use software development testing practices to test our Terraform code is an enormous benefit of having infrastructure defined in code in the first place.

Lastly, modules also provide a way for Terraform users to share their configurations either privately or within the Terraform community. In 2019 HCL was the 3rd fastest-growing programming language on GitHub, which validates the accelerated adoption of the HashiCorp product stack.

In this guide, we are going to create a module and learn how to integrate it into our Terraform configurations.

Prerequisites

Before you begin, you'll need to set up the following:

Azure subscription.
Azure Cloud Shell. Be sure to check out the prerequisites on "Getting Started with Terraform on Azure: Deploying Resources" for a guide on how to set this up.

Step 1 — Module Architecture

In a real-world Terraform environment, we wouldn't want to re-create the same code over and over again for deploying infrastructure. This would create a large amount of redundancy in our Terraform code. Instead, we would want to break up our Terraform configurations into modules; typically, the best practice is a module for each component. For example, we could create a module for SQL databases that contain all of our configurations for deploying SQL with our needs. We could then re-use that module whenever a SQL database is needed and call it within our Terraform configurations.

The diagram below demonstrates the strategy of splitting up the various Azure services by component modules. By creating four modules for each service in this environment, we can also re-use the same code in both Dev, QA, and Prod. This practice ensures accurate infrastructure comparisons between each environment throughout each stage of development. We are no longer copying and pasting our code from dev to QA to Prod. Instead, we parameterize our modules to allow us to customize slightly for each environment, such as resource names and networking subnets:

Creating a module for each cloud service also allows us to re-use modules in other projects as well. Our Terraform modules turn into building blocks that can be used over and over again to create infrastructure on demand.

Step 2 — Creating Modules

Creating modules in Terraform is very easy; all we need are input variables and a standard configuration of resources. In the example, we are going to create our first module for a storage account. We will start by creating a module folder and then reference that module in another Terraform configuration. We will begin with a folder hierarchy like the following:

terraformdemo
    └──modules 
            └──storage-account
                    └── main.tf
                    └── variables.tf

Copy the code for the main.tf and variables.tf configurations and create each file. We'll place each file according to the directory structure above.

The variables.tf file contains our input variables. The input variables are the parameters that our module accepts to customize its deployment. For our storage account module, we are keeping it as simple as possible for the example by receiving inputs for the storage account name, location, and resource group:

variables.tf

variable "saname" {
    type = string
    description = "Name of storage account"
}
variable "rgname" {
    type = string
    description = "Name of resource group"
}
variable "location" {
    type = string
    description = "Azure location of storage account environment"
    default = "westus2"
}

The main.tf file contains the code for creating a storage account. In the example we only have a small set of arguments for our storage account to keep things simple. However, in a real production environment, we would possibly want to implement network policies as well as logging options. We could then use our module to define the 'standards' for how we want all our storage accounts to be configured:

main.tf

resource "azurerm_storage_account" "sa" {
  name                     = var.saname
  resource_group_name      = var.rgname
  location                 = var.location
  account_tier             = "Standard"
  account_replication_type = "GRS"

}

Next, we will create another main.tf file at the root of our terraformdemo folder which will reference our newly created storage account module directory:

terraformdemo
    └── main.tf
    └──modules 
            └──storage-account
                    └── main.tf
                    └── variables.tf

In the root main.tf, we call our module using a module block followed by a string parameter. Inside the block, we need to reference the module that we are using by declaring a source argument. In this example, we are merely referencing the module in our modules subfolder, so the path is ./modules/storage-account. We also need to include any required variable inputs for our storage account module. These are the same variables that we created in the variables.tf file in our storage account modules directory:

Note: The storage account name must be unique and no more than 24 characters long or you may run into failures during deployment.

main.tf

provider "azurerm" {
  version = "1.38.0"
}

#create resource group
resource "azurerm_resource_group" "rg" {
    name     = "rg-MyFirstTerraform"
    location = "westus"
}

#Create Storage Account
module "storage_account" {
  source    = "./modules/storage-account"

  saname    = "statfdemosa234"
  rgname    = azurerm_resource_group.rg.name
  location  = azurerm_resource_group.rg.location
}

In our main.tf file, we also include the azurerm provider block. It is best practice to specify the provider at the root module file; that way, all modules that are called will then inherit this provider. When creating modules, try not to include a provider inside the module itself as much as possible. This can cause further complexity and make modules brittle. When we run our terraform init in the terraformdemo directory we can see that the module is initialized:

Initializing modules...
- storage_account in modules/storage-account

Initializing the backend...

Initializing provider plugins...
- Checking for available provider plugins...
- Downloading plugin for provider "azurerm" (hashicorp/azurerm) 1.38.0...

When we run terraform apply, it will reference the storage-account module to create our storage account with the settings we declared in the module input. Also, we can use the same module multiple times in a configuration with a different parameter string:

provider "azurerm" {
  version = "1.38.0"
}

#create resource group
resource "azurerm_resource_group" "rg" {
    name     = "rg-MyFirstTerraform"
    location = "westus"
}

#Create Storage Account
module "storage_account" {
  source    = "./modules/storage-account"

  saname    = "statfdemosa234"
  rgname    = azurerm_resource_group.rg.name
  location  = azurerm_resource_group.rg.location
}

#Create Storage Account
module "storage_account2" {
  source    = "./modules/storage-account"

  saname    = "statfdemosa241"
  rgname    = azurerm_resource_group.rg.name
  location  = azurerm_resource_group.rg.location
}

We just created our first module. This module is straightforward, however, for more complex scenarios like deploying a Virtual Machine with encrypted disks, a module can be perfect for abstracting all the complexity away with just a few inputs.

Step 3 — Module Outputs

Variable inputs are not the only important part of a module. Outputs are just as important as well. They allow us to transfer information to and from modules so that they can build off of each other. Creating an output for a module is the same process as with a regular Terraform configuration. Create an output.tf file and use an output block to declare our output values. Below we are creating an output block for our storage account primary access key so we can store it in an Azure Key Vault after it is created:

output "primary_key" {
    description = "The primary access key for the storage account"
    value = azurerm_storage_account.sa.primary_access_key
    sensitive   = true
}

Also note, we are using the sensitive argument to specify that the primary_access_key output for our storage account contains sensitive data. Terraform will treat this information as confidential and hide it from the console display when running terraform apply. This does not protect the value from within a Terraform's state file; it will still be in cleartext, which is why in a real-world production scenario, we would want to use remote state.

To use a module's output values in another resource, specify the values by referencing it in the module.<modulename>.<outputname> format:

resource "azurerm_key_vault_secret" "stasecret" {
  name         = "statfdemosa234-secret"
  value        = module.storage_account.primary_key
  key_vault_id = azurerm_key_vault.kv.id

}

Step 4 — Git Modules

If we plan to share this module throughout multiple environments, its best practice to put the module in a source control repository, we then get all the benefits of source control for our module like change tracking. Additionally, we also get version tagging. Tagging modules is a best practice because it allows us to "pin" a stable working version of our module to a Terraform configuration. This prevents any breaking changes from affecting configurations that are already in production.

To use a Terraform module from a git repository, change the source argument to the git URL. In our example, I have uploaded our storage account module to an Azure DevOps Repo. This is a public git repo and will not require any authentication configuration. We can use the https URL and prefix it with git:::

#Create Storage Account
module "storage_account" {
  source    = "git::https://allanore@dev.azure.com/allanore/TerraformModulesExample/_git/TerraformModulesExample?ref=v0.1"

  saname    = "tfdemosa23432"
  rgname    = azurerm_resource_group.rg.name
  location  = azurerm_resource_group.rg.location
}

If we run a terraform init we can see in the console output that the module is downloaded from the git repo and saved to the .terraform/modules local directory:

...
Please install a compatible extension version or remove it.
Initializing modules...
Downloading git::https://allanore@dev.azure.com/allanore/TerraformModulesExample/_git/TerraformModulesExample?ref=v0.1 for storage_account...
- storage_account in .terraform/modules/storage_account
Downloading git::https://allanore@dev.azure.com/allanore/TerraformModulesExample/_git/TerraformModulesExample?ref=v0.1 for storage_account2...
- storage_account2 in .terraform/modules/storage_account2

Initializing the backend...
...

Also, if we wanted to use a private Azure Repo with SSH, we could reference our module in the source argument via an SSH URL like below. We would also need to generate and install the SSH certificate for authentication:

git::git@ssh.dev.azure.com:v3/allanore/TerraformModulesExample/TerraformModulesExample?ref=v0.1

For using a Terraform module source from a GitHub repo, use the URL to the GitHub project. In the example below, I uploaded our module over to a Github repo:

#Create Storage Account
module "storage_account" {
  source    = "github.com/allanore/TerraformModulesExample"

  saname    = "tfdemosa23432"
  rgname    = azurerm_resource_group.rg.name
  location  = azurerm_resource_group.rg.location
}

The recommended folder structure for a Terraform module repo looks like the following. We have our root module configuration files at the root of our repository directory, which in this example, is storage-account. We also have a README.md at the root folder. This is a markdown file that contains the information about our module. It's recommended to have README.md files for every Terraform configuration to describe what it is and how it is used. Next, we have our modules folder, which contains any sub-modules that would be needed to perform additional tasks, for example, configuring Private Link or setting up a Static Website. We also have our examples directory, which should contain examples of every possible scenario of our module. Lastly, we have our test folder, which includes test files written in Golang to test our module using the examples from the example folder; we will go more into testing modules in a later article in this series:

storage-account
    └── README.md
    └── main.tf
    └── variables.tf
    └── outputs.tf
    ├───modules 
    │     ├──private-link
    │     │       └── README.md
    │     │       └── main.tf
    │     │       └── outputs.tf
    │     │       └── variables.tf
    │     └──static-website
    │             └── README.md
    │             └── main.tf
    │             └── outputs.tf
    │             └── variables.tf 
    ├───examples
    │     ├───public
    │     │       └── README.md
    │     │       └── main.tf
    │     │       └── outputs.tf
    │     │       └── variables.tf
    │     ├──private-link
    │     │       └── README.md
    │     │       └── main.tf
    │     │       └── outputs.tf
    │     │       └── variables.tf 
    │     └──static-website
    │             └── README.md
    │             └── main.tf
    │             └── outputs.tf
    │             └── variables.tf
    └───test
         └── sa_public_test.go
         └── sa_private_test.go
         └── sa_static_website_test.go

This module structure is how we can create production-grade Terraform modules that can be used for every project. It seems like a lot of work for creating a module and can be overwhelming; however, start small and slowly build out your module. A complex module can take an experienced developer several months to build.

Step 5 - Terraform Registry

Building a module can take a long time; however, there are thousands of modules shared by the community that you can take advantage of by using them as a base or just using them on their own. The Terraform Registry is a centralized place for community-made Terraform modules. It is a good idea to check the Terraform Registry before building your own module to save time. This is also a great learning tool since you can also view the project on GitHub and see how the module is done and the logic used behind it.

A Terraform Registry can also be private and used via Terraform Cloud. The modules that are on the public Terraform Registry can be used by referencing them in the <namespace>/<name>/<provider> format. In the example below, we are using a module to deploy Azure Functions from the Terraform Registry:

resource "azurerm_resource_group" "rg" {
  name     = "rg-MyFirstTerraform"
  location = "westus"
}

module "function-app" {
  source  = "InnovationNorway/function-app/azurerm"
  version = "0.1.2"

  function_app_name = "func-terrademo"
  resource_group_name = azurerm_resource_group.rg.name
  location = azurerm_resource_group.rg.location
}

When we run Terraform init, the module is automatically downloaded and used during the terraform apply.

Conclusion

In this article, we learned about modules and how we can use them to abstract our Terraform configurations. We went over how to create a module and how to reference the output from a module. We also looked at how to store our modules in a git repository like GitHub and Azure Repos. Lastly, we learned about the Terraform Registry and the community-made modules stored there.

In the next article, we will learn about more advanced HCL concepts like for loops, operators, and functions, which will allow us to perform more advanced infrastructure deployments.

Getting Started with Terraform on Azure: Remote State

Luke Orellana — Wed, 18 Mar 2020 01:21:13 +0000

Introduction

Prerequisites
Step 1 — Remote State with Storage Account
Step 2 — Remote State with Terraform Cloud
Step 3 — Accessing Outputs from Remote State
Step 4 — Partial State Configuration
Conclusion

In Terraform, the state file keeps track of the current state of the infrastructure that is being deployed and managed. All infrastructure details are recorded, which means sensitive information like passwords and secrets may also be stored in the state file. Because of this, it is vital to store the state file in a secure place, not locally on a laptop. This is where remote state comes into play. Remote state allows Terraform to store the state file in a remote location like an AWS S3 bucket or Azure Storage Account. HashiCorp also offers their own free remote state storage solution in Terraform Cloud. Most of these remote state locations provide some sort of authentication method and encryption at rest, which is much more secure than storing the state file locally on a laptop.

Not only does storing state remotely provide the benefit of security, but it also provides state locking. When teams using Terraform start to grow, it's common for multiple users to be applying Terraform code against the same state. This can turn into a conflict and cause the state to become corrupt. State locking is a feature that locks the state file when someone is applying changes so that multiple users can't modify the state at the same time.

In this guide, we will go over how to set up remote state with an Azure Storage Account and Terraform Cloud.

Prerequisites

Before you begin, you'll need to set up the following:

Azure subscription.
Azure Cloud Shell. Be sure to check out the prerequisites on "Getting Started with Terraform on Azure: Deploying Resources" for a guide on setting up Azure Cloud Shell.

Step 1 — Remote State with Storage Account

When you store the Terraform state file in an Azure Storage Account, you get the benefits of RBAC (role-based access control) and data encryption. To set up the resource group for the Azure Storage Account, open up an Azure Cloud Shell session and type in the following command:

az group create --location westus2 --name rg-terraformstate

Next, we create our Storage Account using az storage account create:

Note: Make sure to use an externally unique name for the storage account, or Azure will error out when deploying one.

az storage account create --name terrastatestorage2134 --resource-group rg-terraformstate --location westus2 --sku Standard_LRS

Now that we have the Storage Account created, we can create a blob storage container to store the state file:

az storage container create --name terraformdemo --account-name terrastatestorage2134

Now that our Azure Storage Account is set up, we will need to create a backend block in our Terraform configuration file. The backend tells Terraform where to store the state, either locally or in a remote location. If a backend is not declared, the state is stored locally by default.

We start with a terraform block, which is used for providing instructions to the Terraform tool. In our case, we are telling Terraform to store it's state file remotely. Next is the backend block with the azurerm backend type. This backend type requires the resource group for the storage account, the storage account name, the blob container name, and the name of the state file:

terraform {
  backend "azurerm" {
    resource_group_name  = "rg-terraformstate"
    storage_account_name = "terrastatestorage2134"
    container_name       = "terraformdemo"
    key                  = "dev.terraform.tfstate"
  }
}

Note: Since we are using Azure Cloud Shell and are automatically authenticated to Azure CLI, there is no need to configure any sort of additional steps for accessing the Azure Storage Account. We could also authenticate to the storage account with an MSI, Storage Key, or SAS token. Check out the azurerm backend documentation for the configuration arguments for authenticating with these methods.

We will save the configuration below to a main.tf file in Azure Cloud Shell:

#Set up remote state
terraform {
  backend "azurerm" {
    resource_group_name  = "rg-terraformstate"
    storage_account_name = "terrastatestorage2134"
    container_name       = "terraformdemo"
    key                  = "dev.terraform.tfstate"
  }
}

#configure azurerm provider
provider "azurerm" {
  version = "1.38"
}

#create resource group
resource "azurerm_resource_group" "rg" {
    name     = "rg-remotestatedemo"
    location = "westus2"
}

Now when we run a terraform init and then terraform apply we can see our resource group is created and the state file is saved in the Azure Storage Account:

Now that we've set up remote state with an Azure Storage account let's take a look at setting up a remote state in Terraform Cloud.

Step 2 — Remote State with Terraform Cloud

Terraform Cloud is a hosted service that allows for Terraform users to store their state files remotely as well as collaborate on their Terraform code in a team setting. It is also free for small teams. If you don't have a Terraform Cloud account, go ahead and set one up. Once you sign up and verify your account, you will be prompted to create an organization:

Next, select the user profile in the upper right corner and choose User Settings:

Select Tokens on the left hand side to create a user token. Click the Create an API token button:

Now we will need to label our API token. In this example, since we are using the token to authenticate the backend to Terraform Cloud, we will name this API token "Terraform Backend". Select Create API token to obtain the key:

Copy the key. Best practices would be to store this key in an Azure Key Vault or a secret management system. We will not be able to look up the value of this token, HashiCorp does not save this part of the key in their system. Select Done once you have copied the key to use for later:

Now that we set up our Terraform Cloud environment and created an API token for authenticating the backend, we should have everything we need to store our state in Terraform Cloud. Let's take a look at what the backend configuration looks like in our Terraform configuration.

The backend configuration looks similar to when we configured Terraform to use an Azure Storage Account for remote state. However, this time the backend type will be set to remote. We will also need an organization argument to specify that we want to use the Terraform Cloud organization that we just created as the remote state location. Lastly, we will need to use a workspace block to specify the name of the workspace that we want to create:

terraform {
  backend "remote" {
    organization = "lukelabdemo"

    workspaces {
      name = "terraformdemo"
    }
  }
}

Workspaces in Terraform Cloud are the way that the system organizes infrastructure. When running Terraform locally, we split up environments by folders, and Terraform executes against the files in that folder. There is not an elegant way to do this with a hosted solution like Terraform Cloud, which is why workspaces are needed. Use workspaces to separate an environment just like you would use directories to split up a Terraform environment locally:

lukeapp-dev
    └── main.tf
    └── variables.tf
    └── terraform.tfvars
lukeapp-prod
    └── main.tf
    └── variables.tf
    └── terraform.tfvars

Now that we have our backend configuration defined, how do we use the API token to authenticate? Previously in Terraform, there used to be an environment variable called TFE_TOKEN that we could just set the token key as and Terraform would automatically use it to authenticate to Terraform Cloud. However, this solution is no longer recommended because there is also a Terraform Enterprise on-premise solution. There is not a built-in way to distinguish between the two, and the token could potentially be sent to Terraform Cloud when it was meant for the on-premise Terraform Enterprise server. Aso, interpolations are not allowed in backend configurations. So using a variable for the token in the backend config and referencing the variable in the token argument would not be an option in this case.

HashiCorp recommends using the Terraform CLI configuration file to store the token. The CLI configuration file is a .terraformrc file or terraform.rc file in Windows. It contains per-user setting configurations for the Terraform CLI. In Windows, this file is located in the %APPDATA% location of the user. In all other platforms, the file is in the $HOME directory of the user. In many cases, this file will need to be manually created since it doesn't usually already exist.

In Azure Cloud Shell we can configure this file through the bash command line. This syntax is also handy for automating the configuration of the Terraform CLI in a CI/CD pipeline. We are using tee to create a ./terraformrc file in the $HOME directory. The ./terraformrc file is configured with the token code set as an argument in a credentials block:

tee -a $HOME/.terraformrc << END
credentials "app.terraform.io" {
  token = "TR2LrFWwfzzqfg.atlasv1.zH5UbacqWMKL1GzzPM6DFwK4qUy3HpZypyiBXJczi8Qy4El1m0N1xUVG3sduEX3TgUo"
}
END

When we run cat against the file, we can see that our token is now in the Terraform CLI file for authenticating to app.terraform.io. This tells Terraform to use the API token for that hostname:

Note: Since the token is stored in plain text, it is best practice to secure the endpoint that is using the token. In a CI/CD pipeline, we would want to create a task to remove the .terraformrc file as a cleanup task.

Below is the complete Terraform configuration for using Terraform Cloud as remote state. Save the code below to a main.tf file in its own directory in Azure Cloud Shell:

#Set up remote state
terraform {
  backend "remote" {
    organization = "lukelabdemo"

    workspaces {
      name = "terraformdemo"
    }
  }
}

#configure azurerm provider
provider "azurerm" {
  version = "1.38"
}

#create resource group
resource "azurerm_resource_group" "rg" {
    name     = "rg-remotestatetfc"
    location = "westus2"
}

When we run terraform init we can see that the workspace is automatically created in Terraform Cloud by selecting the Workspaces menu:

At this moment, if we do a terraform apply on our current configuration. We would see the following error:

Error: Error building AzureRM Client: Azure CLI Authorization Profile was not found. Please ensure the Azure CLI is installed and then log-in with `az login`.

  on main.tf line 13, in provider "azurerm":
  13: provider "azurerm" {

This is because Terraform Cloud doesn't just store remote state; it will also remotely execute the Terraform code on its own disposable VM environment, which is called a run. We have two options for executing our Terraform configuration. We can remotely execute our Terraform code in Terraform Cloud; or we can choose to disable this feature and execute our code in Azure Cloud Shell, which will only use the remote state feature of Terraform Cloud. Below are the steps on how to do either a local execution or a Terraform Cloud execution:

Local Execution

To execute our Terraform code in the Azure Cloud Shell session, we need to change the setting on our newly created Terraform Cloud workspace to local execution. By default, all Terraform Cloud workspaces default to remote execution. To change this setting, navigate to the Workspaces menu and select the workspace to modify. In our case, its terraformdemo. On the right-hand side select Settings and choose General:

In General Settings under Execution Mode select Local and click the Save settings button:

When we return to Azure CloudShell and run our terraform apply on our configuration, it will execute in the local shell like normal. Now we can apply Terraform code in this workspace locally unless we change it back to remote. The change we just made to the Terraform Cloud workspace must be made for every new workspace created if the intent is just to use Terraform Cloud to store remote state. There is currently no way to configure this through the Terraform command line yet. This is a pain for automating as it requires manual intervention to change the execution mode settings each time. A trick that can be used to work around this awkward stage with Terraform Cloud is to create another directory called init:

init
    └── main.tf
lukeapp-prod
    └── main.tf
    └── variables.tf
    └── terraform.tfvars

Inside the init folder is a main.tf file that includes the following configuration, which will create the Terraform Cloud workspace if it doesn't exist and change it to local execution mode upon creation:

variable "workspace"{}

terraform {
  backend "local" {
  }
}

#Terraform Cloud provider
provider "tfe" {
  hostname = "app.terraform.io"
}

#Collect all Terraform Cloud workspaces
data "tfe_workspace_ids" "all" {
  names        = ["*"]
  organization = "lukelabdemo"
}

#Check if Workspace still exists
locals{
  check =  lookup(data.tfe_workspace_ids.all.ids, var.workspace, "None")
}

#Create Workspace if it does not exist
resource "tfe_workspace" "test" {
  count = local.check == "None" ? "1" : "0"
  name         = var.workspace
  organization = "lukelabdemo"
  operations = false
}

Using this workaround in a CI/CD pipeline, we could add a step for setting up the workspace separately and run terraform apply first using -var to specify the workspace name to create:

terraform apply -var='workspace=lukeapp-prod'

We could then run the standard configuration of our code using the newly created workspace as the remote state, and the workspace will already be configured with local execution mode.

Terraform Cloud Execution

To remotely execute our Terraform code through Terraform Cloud's environment, we need to configure Azure Authentication in Terraform Cloud. This can be done through environment variables. We will also need to set up a service principal account to authenticate as. To set up a service principal account open up an Azure Cloud Shell session and type in the following command:

az ad sp create-for-rbac -n "TerraformSP" --role contributor \
  --scopes /subscriptions/f7c32571-81bd-4e97-977b-sf2s8s4bae3

Note: In this example, we are configuring the service principal with contributor rights at the root of the subscription. In a real-world production environment, it's best practice to use the least privileges and smallest scope where possible.

We should get the following output:

{
  "appId": "ee38c4bf-1c1a-41df-82c8-5bdb1e7be8be",
  "displayName": "TerraformSP",
  "name": "http://TerraformSP",
  "password": "98fc8ef0-6451-40ad-b0f7-89de76911f0a",
  "tenant": "24e2975c-af72-454e-8dc0-234F3S342"
}

The output corresponds to the following environment variables that are required for the azurerm Terraform provider to authenticate with Azure:

ARM_CLIENT_ID="ee38c4bf-1c1a-41df-82c8-5bdb1e7be8be"
ARM_CLIENT_SECRET="98fc8ef0-6451-40ad-b0f7-89de76911f0a"
ARM_SUBSCRIPTION_ID="f7c32571-81bd-4e97-977b-sf2s8s4bae3"
ARM_TENANT_ID="24e2975c-af72-454e-8dc0-234F3S342"

To set up these environment variables in Terraform Cloud, select the terraformdemo workspace and then select the Variables tab. Under Environment Variables choose Add Variable:

We will need to add each variable, its best practice to mark these as sensitive with the checkbox. Click Save variable to save it. Then add the rest of the required environment variables:

We should have four environment variables saved when complete:

Now we are ready to run our configuration in Terraform Cloud. In Azure Cloud Shell run terraform apply on the configuration that is using the Terraform Cloud remote state. We will see the following output with a link:

Preparing the remote apply...

To view this run in a browser, visit:
https://app.terraform.io/app/lukelabdemo/terraformdemo/runs/run-tDkgKaJcyskSd2QQ

Waiting for the plan to start...

If we navigate to the provided link, we will be able to see the current run of our configuration in Terraform Cloud. The run will display the plan output of our configuration. We can also either Confirm & Apply from within Terraform Cloud, or confirm from the Azure Cloud Shell session. The output in the Azure Cloud Session is streamed back to the local console, so we could either manage the terraform apply through either Terraform Cloud or Azure Cloud Shell:

Terraform Cloud shell has additional features like providing costs of resources during terraform plan. There is also a configuration governance feature called Sentinel, which is very powerful. However, a significant confining element of using the Terraform Cloud for runs is that there are networking constraints. If we were using Terraform provisioners that require access to some network components like SSH into a VM, it would not be possible to use Terraform runs since the Terraform code is executed in HashiCorp's own VM environment.

Step 3 — Accessing Outputs from Remote State

Not only can remote state be used for storing information. But it can also be used for retrieving it as well. Terraform can reference the output information from other states.

We can use a data source block to allow for information to be collected and used within the Terraform configuration. Each provider typically offers its own set of data sources. To reference other state files from Terraform Cloud, we would need to modify our current configuration to include an output. In this example, we created an output block containing the resource group that is created in the configuration:

#Set up remote state
terraform {
  backend "remote" {
    organization = "lukelabdemo"

    workspaces {
      name = "terraformdemo"
    }
  }
}

#configure azurerm provider
provider "azurerm" {
  version = "1.38"
}

#create resource group
resource "azurerm_resource_group" "rg" {
    name     = "rg-remotestatetfc"
    location = "westus2"
}

#output
output "rg" {
  value = azurerm_resource_group.rg
}

To reference that output from another Terraform configuration. We will use a data source block for the terraform_remote_state type and name it terraformdemo. We also need to include the backend type that we are sourcing from along with the required arguments for the specific backend type. In this case, we need the organization and workspace. In our example, we are creating a virtual network and referencing the resource group information from the Terraform Cloud remote state in the previous configuration. We are referencing the output in our expression using data.terraform_remote_state.terraformdemo.outputs:

data "terraform_remote_state" "terraformdemo" {
  backend = "remote"
  config = {
    organization = "lukelabdemo"
    workspaces = {
      name = "terraformdemo"
    }
  }
}

#Create virtual network
resource "azurerm_virtual_network" "vnet" {
    name                = "vnet-terraformtfctest"
    address_space       = ["10.0.0.0/22"]
    location            = data.terraform_remote_state.terraformdemo.outputs.rg.location
    resource_group_name = data.terraform_remote_state.terraformdemo.outputs.rg.name
}

The same concepts apply for an Azure Storage Account backend type. To access the backend of our Azure Storage Account, we follow the same format but reference the azurerm backend type with it's required arguments:

data "terraform_remote_state" "terraformdemo" {
  backend = "azurerm"
  config = {
    resource_group_name  = "rg-terraformstate"
    storage_account_name = "terrastatestorage2134"
    container_name       = "terraformdemo"
    key                  = "dev.terraform.tfstate"
  }

}

#Create virtual network
resource "azurerm_virtual_network" "vnet" {
    name                = "vnet-terraformsatest"
    address_space       = ["10.1.0.0/22"]
    location            = data.terraform_remote_state.terraformdemo.outputs.rg.location
    resource_group_name = data.terraform_remote_state.terraformdemo.outputs.rg.name
}

Referencing remote state outputs can make it easier to combine resources from separate environments or projects. However, this causes a tight coupling between the state files and can cause issues with the maintenance of our configurations. This forces us to ensure that both projects are compatible with each other and always have the proper outputs. This is not practical or scalable in large environments managed by Terraform. Instead, have the config look up the data source by name or tag or another means. This also helps when building integrations tests for your Terraform configurations.

Step 4 — Partial State Configuration

When omitting required arguments in a Terraform backend configuration, this puts the state into what is called a partial configuration. This is extremely useful for keeping sensitive information out of source control. It is also great for configuring a Terraform backend in a CI/CD pipeline. For example, if we were to configure an Azure Storage Account remote state backend, we could simply use the following in our backend block:

terraform {
  backend "azurerm" {}
}

We could then fill in the necessary arguments through variables in our CI/CD system to populate a backend.hcl file:

#backend.hcl
resource_group_name  = "rg-terraformstate"
storage_account_name = "terrastatestorage2134"
container_name       = "terraformdemo"
key                  = "dev.terraform.tfstate"

We can then specify that file during the terraform init using the -backend-config option to specify the location of our backend.hcl:

terraform init -backend-config=backend.hcl

This will feed all of the required backend arguments into the empty backend "azurerm" block without having to state them in the configuration itself. We could also take the command line approach as well:

terraform init \
    -backend-config="resource_group_name=rg-terraformstate" \
    -backend-config="storage_account_name=terrastatestorage2134" \
    -backend-config="container_name=terraformdemo" \
    -backend-config="key=dev.terraform.tfstate"

Partial backend configurations are meant to separate sensitive authentication information from our Terraform code. Use them wisely!

Conclusion

In this article, we learned about Terraform Remote State. It is the backbone of Terraform and requires careful consideration when planning where and how to manage the Terraform state file. We also learned how to use an Azure Storage Account for storing our state files remotely. We also explored using Terraform Cloud for just remote state as well as remotely executing our code in Hashicorp's environment.

In the next article, we will dig into modules which are an absolute must when developing-production grade Terraform code.

Getting Started with Terraform on Azure: Variables

Luke Orellana — Tue, 11 Feb 2020 01:37:38 +0000

Introduction

Prerequisites
Step 1 — Input Variables
Step 2 — Maps, Lists, and Objects
Step 3 — Output Values
Step 4 — Deploying the Complete Configuration
Conclusion

Reusability is one of the major benefits of Infrastructure as Code. When we codify our networking, storage, and compute in a way that allows for us to reuse the same code to deploy our resources, we can move very fast. Requests for infrastructure that normally take a week or two to complete now take a couple hours because we already have a standard template mapped out for that infrastructure. We also gain the ability to allow for teammates of any skill set to deploy complex infrastructure that's already been defined in code. For example, we no longer need a SQL expert to install and configure SQL services each time it is needed. Now a standard build can be defined in code and re-deployed by anyone.

This is why it is important to keep in mind the reusability of our code when designing Terraform configurations. In Terraform, we can use variables to allow our configurations to become more dynamic. This means we are no longer hard coding every value straight into the configuration. In this guide we will use the different types of input variables to parameterize our configuration that we created in the first article of this series.

Prerequisites

Before you begin, you'll need to set up the following:

Azure subscription.
Azure Cloud Shell. Be sure to check out the prerequisites on "Getting Started with Terraform on Azure: Deploying Resources" for a guide on how to set this up.

Step 1 — Input Variables

Input variables serve the same purpose as a parameter would for a script. They allow us to parameterize the Terraform configuration so that we can input the values that are required upon deployment to customize our build.

When creating Terraform configurations, it's best practice to separate out parts of our configuration into individual .tf files. This gives us better organization and readability. Remember, the code we are creating is also a form of living documentation, so make it pretty for the next person that needs to read it. For defining input variables, it's typical to create a separate variables.tf file and store the variable configurations in there:

development
└── server
    └── main.tf
    └── variables.tf

With the folder structure above, if we ran Terraform in the server directory, it would scan through any .tf files in that directory and see them as one whole configuration. We could put everything all in one main.tf file but as our configuration gets bigger this would cause the configuration to be harder to understand and debug.

A variable is defined in Terraform by using a variable block with a label. The label must be a unique name, you cannot have variables with the same name in a configuration. It is also good practice to include a description and type. The variable type specifies the type constraint that the defined variable will accept. This allows us to validate that we aren't using a string value for a variable that needs to be a number or bool type. Below are two variable blocks for system and location both of the type string. The location variable has an additional default argument with the westus2 expression. This means that if a value for the location variable is not specified when we run our terraform apply, it will default to westus2:

variable "system" {
    type = string
    description = "Name of the system or environment"
}

variable "location" {
    type = string
    description = "Azure location of terraform server environment"
    default = "westus2"

}

Now that we've declared our variables in the variables.tf file. We can use the variables in our main.tf file by calling that variable in the var.<name> format. So the system variable would be represented as var.system and the value of our system variable that is is assigned during a terraform apply or terraform plan can then be referenced in our azurerm_resource_group resource block:

provider "azurerm" {
  version = "1.38.0"
}

#create resource group
resource "azurerm_resource_group" "rg" {
    name     = "rg-${var.system}"
    location = var.location
    tags      = {
      Environment = var.system
    }
}

Also note that we can also include our variable name as part of a string by wrapping it in curly brackets like ${var.system}. In the example above, this would cause our name argument to be the value of var.system but prefixed with rg-. This is extremely useful when dynamically naming resources like a storage account or subnet that should have a naming scheme that includes the system name.

So now we've declared some variables in our variables.tf file and we are referencing them in the main.tf file. How do we actually assign values to these variables we've created? In Terraform, there are several methods for assigning variable values and they all have their use case. The most simple way to assign a value to a variable is using the -var option in the command line when running our terraform apply or terraform plan:

terraform apply -var="system=terraformdemo" -var="location=eastus"

If we have many variable values to input we can define them in a variable definition file named terraform.tfvars in the following format:

system ="terraformdemo"
location = "eastus"

Terraform will automatically load the variable values from the variable definition file if it is named terraform.tfvars or ends in .auto.tvfars and placed in the same directory as the other configuration files like below:

development
└── server
    └── main.tf
    └── variables.tf
    └── terraform.tfvars

We can also place variable values in environment variables of the OS that is going to be executing the Terraform config. Terraform will scan the system for any variables that start with TF_VAR_ and use those as variable values for Terraform. This is useful if you are going to be running multiple Terraform configurations on a system. If we were to set the value for the system variable, we would create an environment variable that looks like the following:

 export TF_VAR_system=terraformdemo

For our PowerShell friends it would look more like this:

$Env:TF_VAR_system="terraformdemo"

Now that we know how to declare variables in our configurations and assign values, let's take a look at more complex variable types.

Step 2 — Maps, Lists, and Objects

A map is a collection of values, each value is labeled by a string. The values can be various element types like bool, int, string. However, they must all be of the same type. In the example below is a map variable named managed_disk_type. In the default block are two string values, "Premium_LRS" and "Standard_LRS" with a named label to identify each one westus2 and eastus. This allows us to choose a value based on the label name. So, for our example, we have a string key value for westus2 and eastus. We can use this grouping to define the type of storage we want to use based on the region in Azure. The example use case would be if we wanted servers in westus2 to host our production workloads and use Premium_LRS disk for fast performance while servers hosted in eastus would be used for disaster recovery workloads and use Standard_LRS disk to save on costs:

variable "managed_disk_type" { 
    type = map
    description = "Disk type Premium in Primary location Standard in DR location"

    default = {
        westus2 = "Premium_LRS"
        eastus = "Standard_LRS"
    }
}

Now that we have our map variable defined, we still need to create the logic for which disk to use in our main.tf file. In the storage_os_disk block of the azurerm_virtual_machine resource we would use the lookup function, which follows the lookup(map, key, default) format. First, we declare the map variable that we want to lookup, which would be var.managed_disk_type in this example. Next, we will retrieve our map value based on the key we specify which is var.location. This variable should resolve to westus2 or whatever location value we input for that variable. If it matches with its key value pair in our map it will retrieve that value. So our example should retrieve Premium_LRS if our var.location variable is configured with the westus2 value. If the key value pair does not exist because the var.location variable doesn't contain either westus2 or eastus it will default to Standard_LRS:

 storage_os_disk {
    name              = "stvm${var.servername}os"
    caching           = "ReadWrite"
    create_option     = "FromImage"
    managed_disk_type = lookup(var.managed_disk_type, var.location, "Standard_LRS")
  }

Now that we've created a map variable, we'll create another variable type, list variables. List variable types are a sequence of values that can be any element type as long as they are all of the same type. Variable lists are useful for assigning values that require a list type. In the example below we are using a list variable for vnet_address_space this attribute can take list values, so declaring a list for the variable allows us to specify a list of addresses to configure:

variable "vnet_address_space" { 
    type = list
    description = "Address space for Virtual Network"
    default = ["10.0.0.0/16"]
}

We specified a default argument with [10.0.0.0/16] as the default address space. Notice that it is wrapped in square brackets. This represents a value that is a list. To pass this variable on to our main.tf we would simply use the var.vnet_address_space expression just like with a regular string variable.

Another variable type is the object type. Object types are a structural type that allow for each attribute to have it's own unique type, unlike a map or list. In this example we are declaring an OS variable with the object type for the OS image that we want our VM to use. Object type variables are great for transferring a common set of variable values between modules. We could potentially have another module that outputs this required image information and easily pass it into the OS variable reducing the number of variable blocks needed:

variable "os" {
    description = "OS image to deploy"
    type = object({
        publisher = string
        offer = string
        sku = string
        version = string
  })
}

When we use the object type variable in our main.tf configuration. We will need to specify the os variable and each attribute inside of it in order to reference each value:

storage_image_reference {
    publisher = var.os.publisher
    offer     = var.os.offer
    sku       = var.os.sku
    version   = var.os.version
  }

Lists, maps, and objects are the three most common complex variable types. They are all great for their specific use cases. In the next section, we will look at how to create an output for our configuration.

Step 3 — Output Values

Outputs allow for us to define values in the configuration that we want to share with other resources or modules. For example, we could pass on the output information for the public IP address of a server to another process like building a firewall rule. Even if we are using a dynamic public IP, after the configuration is successfully deployed, the value of the public IP address is retrieved and defined as an output. An output block is defined with the following syntax:

output "pip" {
    description = "Public IP Address of Virtual Machine"
    value = azurerm_public_ip.publicip.ip_address
}

Note, the output parameter string must be unique in the configuration. We could then reference this output from the state file and use it in another configuration which we will go into more detail in the next post in this series.

Step 4 — Deploying the Complete Configuration

Now that we know how variables and outputs works, lets refactor our configuration for deploying a Virtual Machine and convert it into a dynamic configuration with variables. In Azure Cloud Shell, we will create the four files for our variables and outputs. The directory and file structure will look like this:

terraformdemo
    └── main.tf
    └── variables.tf
    └── terraform.tfvars
    └── output.tf

Below are the complete configurations for each file including the changes to make our configuration more dynamic. Copy each configuration and paste it into the Azure Cloud Shell editor using the code <filename> command to create each file:

main.tf

provider "azurerm" {
  version = "1.38.0"
}

#create resource group
resource "azurerm_resource_group" "rg" {
    name     = "rg-${var.system}"
    location = var.location
    tags      = {
      Environment = var.system
    }
}

#Create virtual network
resource "azurerm_virtual_network" "vnet" {
    name                = "vnet-dev-${var.location}-001"
    address_space       = var.vnet_address_space
    location            = azurerm_resource_group.rg.location
    resource_group_name = azurerm_resource_group.rg.name
}

# Create subnet
resource "azurerm_subnet" "subnet" {
  name                 = "snet-dev-${var.location}-001 "
  resource_group_name  = azurerm_resource_group.rg.name
  virtual_network_name = azurerm_virtual_network.vnet.name
  address_prefix       = "10.0.0.0/24"
}

# Create public IP
resource "azurerm_public_ip" "publicip" {
  name                = "pip-${var.servername}-dev-${var.location}-001"
  location            = azurerm_resource_group.rg.location
  resource_group_name = azurerm_resource_group.rg.name
  allocation_method   = "Static"
}


# Create network security group and rule
resource "azurerm_network_security_group" "nsg" {
  name                = "nsg-sshallow-${var.system}-001 "
  location            = azurerm_resource_group.rg.location
  resource_group_name = azurerm_resource_group.rg.name

  security_rule {
    name                       = "SSH"
    priority                   = 1001
    direction                  = "Inbound"
    access                     = "Allow"
    protocol                   = "Tcp"
    source_port_range          = "*"
    destination_port_range     = "22"
    source_address_prefix      = "*"
    destination_address_prefix = "*"
  }
}

# Create network interface
resource "azurerm_network_interface" "nic" {
  name                      = "nic-01-${var.servername}-dev-001 "
  location                  = azurerm_resource_group.rg.location
  resource_group_name       = azurerm_resource_group.rg.name
  network_security_group_id = azurerm_network_security_group.nsg.id

  ip_configuration {
    name                          = "niccfg-${var.servername}"
    subnet_id                     = azurerm_subnet.subnet.id
    private_ip_address_allocation = "dynamic"
    public_ip_address_id          = azurerm_public_ip.publicip.id
  }
}

# Create virtual machine
resource "azurerm_virtual_machine" "vm" {
  name                  = var.servername
  location              = azurerm_resource_group.rg.location
  resource_group_name   = azurerm_resource_group.rg.name
  network_interface_ids = [azurerm_network_interface.nic.id]
  vm_size               = "Standard_B1s"

  storage_os_disk {
    name              = "stvm${var.servername}os"
    caching           = "ReadWrite"
    create_option     = "FromImage"
    managed_disk_type = lookup(var.managed_disk_type, var.location, "Standard_LRS")
  }

  storage_image_reference {
    publisher = var.os.publisher
    offer     = var.os.offer
    sku       = var.os.sku
    version   = var.os.version
  }

  os_profile {
    computer_name  = var.servername
    admin_username = var.admin_username
    admin_password = var.admin_password
  }

  os_profile_linux_config {
    disable_password_authentication = false
  }
}

variables.tf

variable "system" {
    type = string
    description = "Name of the system or environment"
}

variable "servername" {
    type = string
    description = "Server name of the virtual machine"
}

variable "location" {
    type = string
    description = "Azure location of terraform server environment"
    default = "westus2"

}

variable "admin_username" {
    type = string
    description = "Administrator username for server"
}

variable "admin_password" {
    type = string
    description = "Administrator password for server"
}

variable "vnet_address_space" { 
    type = list
    description = "Address space for Virtual Network"
    default = ["10.0.0.0/16"]
}

variable "managed_disk_type" { 
    type = map
    description = "Disk type Premium in Primary location Standard in DR location"

    default = {
        westus2 = "Premium_LRS"
        eastus = "Standard_LRS"
    }
}

variable "vm_size" {
    type = string
    description = "Size of VM"
    default = "Standard_B1s"
}

variable "os" {
    description = "OS image to deploy"
    type = object({
        publisher = string
        offer = string
        sku = string
        version = string
  })
}

terraform.tfvars

system = "terraexample"
servername = "vmterraform"
location = "westus2"
admin_username = "terraadmin"
vnet_address_space = ["10.0.0.0/16","10.1.0.0/16"]
os = {
    publisher = "Canonical"
    offer     = "UbuntuServer"
    sku       = "16.04.0-LTS"
    version   = "latest"
}

output.tf

output "pip" {
    description = "Public IP Address of Virtual Machine"
    value = azurerm_public_ip.publicip.ip_address
}

Now that we have our directory created with the four configuration files, we will run our terraform init to initialize the directory and download our provider plugins. We will follow it up with a terraform apply. Notice that we are now prompted for the Administrator password variable. This because we followed best practices and left the local admin password value out of the terraform.tfvars file and never set a default value in the variables.tf file. Terraform will automatically prompt for variables that aren't defined and do not have a default value configured:

After typing in a password, confirm the apply to start deploying the infrastructure:

azurerm_resource_group.rg: Creating...
azurerm_resource_group.rg: Creation complete after 2s [id=/subscriptions/f7c32571-81bd-4e23-5321-7e216164bae3/resourceGroups/rg-terraexample]
azurerm_network_security_group.nsg: Creating...
azurerm_virtual_network.vnet: Creating...
azurerm_public_ip.publicip: Creating...
azurerm_public_ip.publicip: Creation complete after 3s [id=/subscriptions/f7c32571-81bd-4e23-5321-7e216164bae3/resourceGroups/rg-terraexample/providers/Microsoft.Network/publicIPAddresses/pip-vmterraform-dev-westus2-001]
...

When our VM is successfully built, we will see the public IP address assigned to our VM is generated in the output:

Apply complete! Resources: 7 added, 0 changed, 0 destroyed.

Outputs:

pip = 52.183.4.46

We now have a reusable Terraform configuration for deploying virtual machines into Azure! We can now modify the terraform.tfvars with different values to customize our deployments.

Conclusion

In this article we learned about variables and how we can use them to make our Terraform configurations reusable. We also went over complex variable types like lists, maps, and objects that can be used to populate data dynamically into our Terraform configurations. Variables are a core part of Terraform and should be heavily utilized in most Terraform configurations. Hard coding values into Terraform configurations should be discouraged if they are preventing the code from becoming a reusable tool.

In the next article we will dig into remote state which must be thoroughly understood before using Terraform in production.

Getting Started with Terraform on Azure: Provisioners

Luke Orellana — Tue, 11 Feb 2020 01:18:56 +0000

Introduction

Prerequisites
Step 1 — Resource Provisioners
Step 2 — Destroy Provisioners
Step 3 — Null Resource Provisioners
Conclusion

Provisioners provide the ability to run additional steps or tasks when a resource is created or destroyed. This is not to be confused as a replacement for configuration management. Tools like Chef, Puppet, and Ansbile are much better suited for configuration management and it's best to leave the heavy lifting to those tools. Provisioners are used to fill the gaps in between.

Before we go into how to use provisioners in Terraform, let's first discuss the differences between configuration management and Terraform. Configuration management is typically used to enforce desired settings on an operating system or cloud resource. The settings are defined in code and that code is re-applied again and again to enforce those settings for the rest of the resource's life. Terraform is more likened to an orchestrator where it deploys the infrastructure components and then relies on the configuration management to deploy the desired settings onto the operating system. Terraform is also not designed for configurations to repeatedly run every 15 minutes to maintain it's state. This could be done with a scheduled task or script, however it's not necessary with Terraform as any changes made should be done through the code anyways.

Unlike configuration management tools, Terraform really shines with immutable infrastructure designs. Building infrastructure that is immutable means building infrastructure that is designed to simply be rebuilt instead of reconfigured or updated. This means that a web server will never be patched or changed, instead it is rebuilt with the new patches or changes and is deployed back into production replacing the old server. Building systems this way reduces the requirement for configuration management since changes are made to the image before deployment, not after the fact. Tools like Packer, which allow for images to be created and defined in code, are used to automate the configuration changes to the image which Terraform is then used to deploy. The idea is that with configuration management, you will never be able to configure an OS 100% to enforce every change on that system, it's much more efficient to rebuild an image to desired state and re-deploy the system.

However, not all environments can fit into this immutable infrastructure design. Sometimes we are already stuck with a solution in place or are working with an application that can't exist with an immutable infrastructure design. For those cases we need to lean on our configuration management tools to ensure that our servers are not drifting away from the desired state. Provisioners can be used in Terraform to assist with bootstrapping or initializing a configuration management tool onto a server. They can also be used to perform additional customization tasks where the Azure provider is missing the capability.

Note that provisioners should be a last resort as they can make our Terraform configurations brittle. However, there are some cases where it is still necessary to create a provisioner in order to accomplish a task. In this exercise we will take a look at how to use provisioners in Terraform. We will start by using a provisioner to add a virtual machine into Azure Desired State Configuration, or Azure DSC. This is a configuration management technology in Azure that uses PowerShell to enforce OS settings on a server.

Prerequisites

Before you begin, you'll need to set up the following:

Azure subscription.
Azure Cloud Shell. Be sure to check out the prerequisites on "Getting Started with Terraform on Azure: Deploying Resources" for a guide on how to set this up.

We will also need to set up an Azure Automation account and upload a DSC configuration. We can easily do this in a matter of minutes in Azure Cloud Shell. Open up an Azure Cloud Shell session by going to shell.azure.com. In this example I will be using the PowerShell version since all the syntax in this guide is meant for PowerShell. Start by changing the directory to $home:

cd $home

Next, we will need to setup a resource group for our Azure Automation account. Run the command below:

New-AzResourceGroup -name rg-terraformaa -location westus2

Then we will create an Azure Automation account in that resource group using the New-AzAutomationAccount PowerShell cmdlet:

New-AZAutomationAccount -name aa-terraformdemo -ResourceGroupName rg-terraformaa -location 'westus2'

We are going to be making a DSC configuration for installing the IIS role. Copy the following code below and paste it into the Azure Cloud Shell. This will create a WebserverConfig.ps1 file on our $home directory which we will import into our Azure Automation account:

"
Configuration WebserverConfig {

    # Import the module for dsc
    Import-DscResource -ModuleName PsDesiredStateConfiguration

    Node 'vmterraform' {

        #ensures that the Web-Server (IIS) feature is enabled.
        WindowsFeature WebServer {
            Ensure = 'Present'
            Name   = 'Web-Server'
        }


    }
}
" > WebserverConfig.ps1

Now that we have the DSC configuration file created, we will import it into the Azure Automation account and immediately start a compilation job. This job takes our configuration file and turns it into a MOF file which contains all the configuration information. The compiled configuration can then be assigned to a node:

Import-AzAutomationDscConfiguration -AutomationAccountName "aa-terraformdemo"-ResourceGroupName "rg-terraformaa" -SourcePath ".\WebserverConfig.ps1" -force -published | Start-AzureRmAutomationDscCompilationJob

The compilation job will immediately start. It will take a few minutes to complete, you can check the status with the following command:

Get-AzureRmAutomationDscCompilationJob -AutomationAccountName "aa-terraformdemo" -ResourceGroupName "rg-terraformaa"

The status will change to completed if the compile job is successful:

ResourceGroupName      : rg-terraformaa
AutomationAccountName  : aa-terraformdemo
Id                     : 09743f32-7bfb-4e0b-b18b-db2cc5cb7ead
CreationTime           : 1/25/20 11:29:42 PM +00:00
Status                 : Completed
StatusDetails          :
StartTime              : 1/25/20 11:30:24 PM +00:00
EndTime                : 1/25/20 11:30:32 PM +00:00
Exception              :
LastModifiedTime       : 1/25/20 11:30:32 PM +00:00
LastStatusModifiedTime : 1/1/01 12:00:00 AM +00:00
JobParameters          : {}
ConfigurationName      : WebserverConfig

Once the compile job is complete, we now have our Azure Automation account set up with a DSC configuration for installing IIS. We are ready to deploy a VM and automatically assign the DSC configuration during deployment. If you want to read more on Azure DSC be sure to check out the documentation.

Step 1 — Resource Provisioners

Provisioners can be tied to a resource which causes them to run after that resource has been successfully created. There are several provisioner types that allow for various actions to be taken such as copying a file to a resource, remotely executing a script or command, as well a locally executing a command or script on the endpoint that is running the terraform code. There are also provisioner types that are specifically meant for configuration management tools like Chef, Puppet, and Saltstack. Provisioners are created with a provisioner resource block followed by a provisioner type in the first parameter string. Below is an example of a provisioner block using the file provisioner type to copy a PowerShell script to the deployed resource. Inside the provisioner block is a connection block. This is used to define how to connect to the resource, in the example winrm is used but we could also do SSH as well:

provisioner "file" {
  source      = "./setup.ps1"
  destination = "C:/temp/setup.ps1"

  connection {
    type     = "winrm"
    user     = "Administrator"
    password = "P@ssw0rd"
    host     = "webserver1"
  }
}

Creating connections inside provisioners creates a limitation in our Terraform code. We then have to think about network connectivity between the device running the Terraform code and the resources we are deploying. Therefore it's best to avoid using connection blocks when possible. In our example we are going to make use of the AZ PowerShell module cmdlets to assign our VM a DSC configuration. Because we are using Azure Cloud Shell, we are automatically authenticated with Azure and there is no need for additional authentication steps in the provisioner block. If we were to run this code elsewhere, we would need to plan for that in our design.

We will be running a local-exec provisioner type since we are running our Terraform configuration from Azure Cloud Shell. On the command argument we will be using <<- which allows for us to create a multi-line string. The text EOT stands for end of text. This serves as our marker for when the string ends. We could essentially use any text for this, but EOT is the most commonly used and it's best to stick to standards for readability of code. We are using the Register-AzAutomationDSCNode cmdlet to register our newly deployed VM with Azure DSC and assign the web server configuration. The @params is a Powershell technique called splatting used for formatting and easy readability of the cmdlet parameters. Lastly, the interpreter argument defines the executable or application we want to run. This could be any application on the machine that is running the Terraform code. In our case we are running the configuration from Azure Cloud Shell so we will be using Powershell Core. The strings after pwsh are the arguments used for the application which will be -command in our example:

provisioner "local-exec" {
    command = <<-EOT
        $params = @{
        AutomationAccountName = "aa-terraformdemo"
        AzureVMName = "${azurerm_virtual_machine.vm.name}"
        ResourceGroupName = "rg-terraformaa"
        NodeConfigurationName = "WebserverConfig.localhost"
        azureVMLocation = "${azurerm_resource_group.rg.location}"
        AzureVMResourceGroup = "${azurerm_resource_group.rg.name}"
        }
        Register-AzAutomationDscNode @params 
   EOT
   interpreter = ["pwsh", "-Command"]
  }

Below is the entire configuration for deploying our VM. Copy the config below and paste it into a main.tf file in Azure Cloud Shell using the code main.tf command:

provider "azurerm" {
  version = "1.38.0"
}

#create resource group
resource "azurerm_resource_group" "rg" {
    name     = "rg-MyFirstTerraform"
    location = "westus2"
    tags      = {
      Environment = "Terraform Demo"
    }
}

#Create virtual network
resource "azurerm_virtual_network" "vnet" {
    name                = "vnet-dev-westus2-001"
    address_space       = ["10.0.0.0/16"]
    location            = "westus2"
    resource_group_name = azurerm_resource_group.rg.name
}

# Create subnet
resource "azurerm_subnet" "subnet" {
  name                 = "snet-dev-westus2-001"
  resource_group_name  = azurerm_resource_group.rg.name
  virtual_network_name = azurerm_virtual_network.vnet.name
  address_prefix       = "10.0.0.0/24"
}

# Create public IP
resource "azurerm_public_ip" "publicip" {
  name                = "pip-vmterraform-dev-westus2-001"
  location            = "westus2"
  resource_group_name = azurerm_resource_group.rg.name
  allocation_method   = "Static"
}


# Create network security group and rule
resource "azurerm_network_security_group" "nsg" {
  name                = "nsg-sshallow-001 "
  location            = "westus2"
  resource_group_name = azurerm_resource_group.rg.name

  security_rule {
    name                       = "HTTP"
    priority                   = 1001
    direction                  = "Inbound"
    access                     = "Allow"
    protocol                   = "Tcp"
    source_port_range          = "*"
    destination_port_range     = "80"
    source_address_prefix      = "*"
    destination_address_prefix = "*"
  }
}

# Create network interface
resource "azurerm_network_interface" "nic" {
  name                      = "nic-01-vmterraform-dev-001 "
  location                  = "westus2"
  resource_group_name       = azurerm_resource_group.rg.name
  network_security_group_id = azurerm_network_security_group.nsg.id

  ip_configuration {
    name                          = "niccfg-vmterraform"
    subnet_id                     = azurerm_subnet.subnet.id
    private_ip_address_allocation = "dynamic"
    public_ip_address_id          = azurerm_public_ip.publicip.id
  }
}

# Create virtual machine
resource "azurerm_virtual_machine" "vm" {
  name                  = "vmterraform"
  location              = "westus2"
  resource_group_name   = azurerm_resource_group.rg.name
  network_interface_ids = [azurerm_network_interface.nic.id]
  vm_size               = "Standard_B2s"

  storage_os_disk {
    name              = "stvmpmvmterraformos"
    caching           = "ReadWrite"
    create_option     = "FromImage"
    managed_disk_type = "Premium_LRS"
  }

  storage_image_reference {
    publisher = "MicrosoftWindowsServer"
    offer     = "WindowsServer"
    sku       = "2019-Datacenter"
    version   = "latest"
  }

  os_profile {
    computer_name  = "vmterraform"
    admin_username = "terrauser"
    admin_password = "Password1234!"
  }
  os_profile_windows_config{
    provision_vm_agent = true
  }

  #Add Virtual Machine to Azure DSC after deployment.
  provisioner "local-exec" {
    command = <<EOT
        $params = @{
        AutomationAccountName = "aa-terraformdemo"
        AzureVMName = "${azurerm_virtual_machine.vm.name}"
        ResourceGroupName = "rg-terraformaa"
        NodeConfigurationName = "WebserverConfig.vmterraform"
        azureVMLocation = "${azurerm_resource_group.rg.location}"
        AzureVMResourceGroup = "${azurerm_resource_group.rg.name}"
        }
        Register-AzAutomationDscNode @params 
   EOT
   interpreter = ["pwsh", "-Command"]
  }


}

We will run terraform init and then terraform apply to deploy our server. The following output will be displayed:

azurerm_resource_group.rg: Creating...
azurerm_resource_group.rg: Creation complete after 1s [id=/subscriptions/5c80ecff-4dfe-4fa0-abd4-3c15c2e3be31/resourceGroups/rg-MyFirstTerraform]
azurerm_public_ip.publicip: Creating...
azurerm_virtual_network.vnet: Creating...
azurerm_network_security_group.nsg: Creating...
azurerm_network_security_group.nsg: Creation complete after 3s [id=/subscriptions/5c80ecff-4dfe-4fa0-abd4-3c15c2e3be31/resourceGroups/rg-MyFirstTerraform/providers/Microsoft.Network/networkSecurityGroups/nsg-sshallow-001]
azurerm_public_ip.publicip: Creation complete after 4s [id=/subscriptions/5c80ecff-4dfe-4fa0-abd4-3c15c2e3be31/resourceGroups/rg-MyFirstTerraform/providers/Microsoft.Network/publicIPAddresses/pip-vmterraform-dev-westus2-001]

During the deployment, after our VM is created, we can see the provisioner block runs and our PowerShell command is executed:

azurerm_virtual_machine.vm: Still creating... [2m0s elapsed]
azurerm_virtual_machine.vm: Still creating... [2m10s elapsed]
azurerm_virtual_machine.vm: Provisioning with 'local-exec'...
azurerm_virtual_machine.vm (local-exec): Executing: ["pwsh" "-Command" "        $params = @{\n        AutomationAccountName = \"aa-terraformdemo\"\n        AzureVMName = \"vmterraform\"\n        ResourceGroupName = \"rg-terraformaa\"\n        NodeConfigurationName = \"WebserverConfig.vmterraform\"\n        azureVMLocation = \"westus2\"\n        AzureVMResourceGroup = \"rg-MyFirstTerraform\"\n        }\n        Register-AzAutomationDscNode @params \n"]

azurerm_virtual_machine.vm (local-exec): MOTD: Save files to $home/clouddrive for persistence across sessions

azurerm_virtual_machine.vm (local-exec): VERBOSE: Authenticating to Azure ...
azurerm_virtual_machine.vm (local-exec): VERBOSE: Building your Azure drive ...
azurerm_virtual_machine.vm: Still creating... [2m20s elapsed]
azurerm_virtual_machine.vm: Still creating... [2m30s elapsed]

Once the Terraform deployment has finished, we can check in the Azure Portal and search for Automation Accounts. After selecting the Automation Account aa-terraformdemo, we can select State Configuration (DSC) on the left hand side and see our newly provisioned VM with the WebServer configuration assigned:

When we go to the assigned Public IP Address in a web browser, we can see that the IIS role is already installed:

We've successfully created a Terraform configuration that deploys a VM and assigns a DSC configuration. But what happens when we destroy this VM? Provisioner blocks like the one we created are only deployed when the VM or resource is first created. If we changed the size of the VM or another attribute, the Provisioner block would not run again. If we ran a terraform destroy on this configuration right now, our VM would not be removed from Azure DSC. In the next section we will look at what we can do to fix this with a destroy provisioner.

Step 2 — Destroy Provisioners

Destroy provisioners are only executed during a terraform destroy. This can be useful in cases where additional cleanup is needed for a resource such as VM decommission tasks. A destroy provisioner block looks the same as a regular provisioner block except that there is an additional when = destroy argument. Below is a snippet of the destroy provisioner that we will be adding :

#Remove Virtual Machine from Azure DSC when destroying.
  provisioner "local-exec" {
    when = destroy
    command = <<EOT
        Get-AzAutomationDscNode -ResourceGroupName "rg-terraformaa" -AutomationAccountName "aa-terraformdemo" -Name "${self.name}" | Unregister-AzAutomationDscNode -force
    EOT
   interpreter = ["pwsh", "-Command"]
  }

The provisioner block uses the Get-AzAutomationDscNode PowerShell cmdlet to find our VM by name and then pipes it to the Unregister-AzAutomationDSCNode cmdlet to unregister the VM from Azure DSC. Also notice that we are using the ${self.name} expression to reference our VM name instead of ${azurerm_virtual_machine.vm.name} like we did in the first provisioner block. Terraform does not like destroy provisioner blocks to have dependencies on external resources. This allows for us to have a more stable provisioner because it is not relying upon other resources to exist before the destroy provisioner can be run. The local named value self references attributes from the resource that the provisioner block resides in. We will add the snippet above to our main.tf Terraform configuration. The complete configuration should look like the following:

provider "azurerm" {
  version = "1.38.0"
}

#create resource group
resource "azurerm_resource_group" "rg" {
    name     = "rg-MyFirstTerraform"
    location = "westus2"
    tags      = {
      Environment = "Terraform Demo"
    }
}

#Create virtual network
resource "azurerm_virtual_network" "vnet" {
    name                = "vnet-dev-westus2-001"
    address_space       = ["10.0.0.0/16"]
    location            = "westus2"
    resource_group_name = azurerm_resource_group.rg.name
}

# Create subnet
resource "azurerm_subnet" "subnet" {
  name                 = "snet-dev-westus2-001 "
  resource_group_name  = azurerm_resource_group.rg.name
  virtual_network_name = azurerm_virtual_network.vnet.name
  address_prefix       = "10.0.0.0/24"
}

# Create public IP
resource "azurerm_public_ip" "publicip" {
  name                = "pip-vmterraform-dev-westus2-001"
  location            = "westus2"
  resource_group_name = azurerm_resource_group.rg.name
  allocation_method   = "Static"
}


# Create network security group and rule
resource "azurerm_network_security_group" "nsg" {
  name                = "nsg-sshallow-001 "
  location            = "westus2"
  resource_group_name = azurerm_resource_group.rg.name

  security_rule {
    name                       = "HTTP"
    priority                   = 1001
    direction                  = "Inbound"
    access                     = "Allow"
    protocol                   = "Tcp"
    source_port_range          = "*"
    destination_port_range     = "80"
    source_address_prefix      = "*"
    destination_address_prefix = "*"
  }
}

# Create network interface
resource "azurerm_network_interface" "nic" {
  name                      = "nic-01-vmterraform-dev-001 "
  location                  = "westus2"
  resource_group_name       = azurerm_resource_group.rg.name
  network_security_group_id = azurerm_network_security_group.nsg.id

  ip_configuration {
    name                          = "niccfg-vmterraform"
    subnet_id                     = azurerm_subnet.subnet.id
    private_ip_address_allocation = "dynamic"
    public_ip_address_id          = azurerm_public_ip.publicip.id
  }
}

# Create virtual machine
resource "azurerm_virtual_machine" "vm" {
  name                  = "vmterraform"
  location              = "westus2"
  resource_group_name   = azurerm_resource_group.rg.name
  network_interface_ids = [azurerm_network_interface.nic.id]
  vm_size               = "Standard_B2s"

  storage_os_disk {
    name              = "stvmpmvmterraformos"
    caching           = "ReadWrite"
    create_option     = "FromImage"
    managed_disk_type = "Premium_LRS"
  }

  storage_image_reference {
    publisher = "MicrosoftWindowsServer"
    offer     = "WindowsServer"
    sku       = "2019-Datacenter"
    version   = "latest"
  }

  os_profile {
    computer_name  = "vmterraform"
    admin_username = "terrauser"
    admin_password = "Password1234!"
  }
  os_profile_windows_config{
    provision_vm_agent = true
  }

  #Add Virtual Machine to Azure DSC after deployment.
  provisioner "local-exec" {
    command = <<EOT
        $params = @{
        AutomationAccountName = "aa-terraformdemo"
        AzureVMName = "${azurerm_virtual_machine.vm.name}"
        ResourceGroupName = "rg-terraformaa"
        NodeConfigurationName = "WebserverConfig.localhost"
        azureVMLocation = "${azurerm_resource_group.rg.location}"
        AzureVMResourceGroup = "${azurerm_resource_group.rg.name}"
        }
        Register-AzAutomationDscNode @params 
   EOT
   interpreter = ["pwsh", "-Command"]
  }

  #Remove Virtual Machine from Azure DSC when destroying.
  provisioner "local-exec" {
    when = destroy
    command = <<EOT
        Get-AzAutomationDscNode -ResourceGroupName "rg-terraformaa" -AutomationAccountName "aa-terraformdemo" -Name "${self.name}" | Unregister-AzAutomationDscNode -force
    EOT
   interpreter = ["pwsh", "-Command"]
  }

}

Now let's run Terraform destroy. We will see that before the VM is destroyed, the destroy provisioner block is executed:

azurerm_virtual_machine.vm: Destroying... [id=/subscriptions/5c80ecff-4dfe-4fa0-abd4-3c15c2e3be31/resourceGroups/rg-MyFirstTerraform/providers/Microsoft.Compute/virtualMachines/vmterraform2]
azurerm_virtual_machine.vm: Provisioning with 'local-exec'...
azurerm_virtual_machine.vm (local-exec): Executing: ["pwsh" "-Command" "        Get-AzAutomationDscNode -ResourceGroupName \"rg-terraformaa\" -AutomationAccountName \"aa-terraformdemo\" -Name \"vmterraform\" |Unregister-AzAutomationDscNode -force\n"]

azurerm_virtual_machine.vm (local-exec): MOTD: Connect to a remote Azure VM: Enter-AzVM

azurerm_virtual_machine.vm (local-exec): VERBOSE: Authenticating to Azure ...
azurerm_virtual_machine.vm (local-exec): VERBOSE: Building your Azure drive ...
azurerm_virtual_machine.vm: Still destroying... [id=/subscriptions/5c80ecff-4dfe-4fa0-abd4-...t.Compute/virtualMachines/vmterraform, 10s elapsed]
azurerm_virtual_machine.vm: Still destroying... [id=/subscriptions/5c80ecff-4dfe-4fa0-abd4-...t.Compute/virtualMachines/vmterraform, 20s elapsed]
azurerm_virtual_machine.vm: Still destroying... [id=/subscriptions/5c80ecff-4dfe-4fa0-abd4-...t.Compute/virtualMachines/vmterraform, 30s elapsed]
azurerm_virtual_machine.vm: Still destroying... [id=/subscriptions/5c80ecff-4dfe-4fa0-abd4-...t.Compute/virtualMachines/vmterraform, 40s elapsed]
azurerm_virtual_machine.vm: Still destroying... [id=/subscriptions/5c80ecff-4dfe-4fa0-abd4-...t.Compute/virtualMachines/vmterraform, 50s elapsed]
azurerm_virtual_machine.vm: Still destroying... [id=/subscriptions/5c80ecff-4dfe-4fa0-abd4-...t.Compute/virtualMachines/vmterraform, 1m0s elapsed]
...

Once the destroy process is complete, we will see that the VM is removed from Azure DSC.

Now we have a complete VM configuration automated from deployment to decommission.

Step 3 — Null Resource Provisioners

Not only can we put provisioner blocks inside of resources like we did with our virtual machine resource. But we can also have them run independently of resource blocks. This can be used for scenarios where we need to run a script or process after several resources are created or if we want to design a provisioner that does not depend on a single resource.

We will deploy two Azure Container Registries in this example, one for Production and one for Development. Azure Container Registry is a service in Azure that is used for housing container images. We will use a provisioner to import the hello world image from Docker Hub, a public container registry, to our Azure Container Registries once they have been deployed.

A provisioner block must still technically reside inside a resource so we will create a null_resource resource block. Null_resource resource blocks are used as a "do nothing" type of resource that allow us to run provisioner tasks independently of a resource. Below is a snippet of what our null_resource resource block will look like:

resource "null_resource" "import_image" {

  provisioner "local-exec" {
    command = <<EOT
       az acr import --name ${azurerm_container_registry.acr-prod.name} --source docker.io/library/hello-world:latest --image hello-world:latest
       az acr import --name ${azurerm_container_registry.acr-dev.name} --source docker.io/library/hello-world:latest --image hello-world:latest
   EOT
   interpreter = ["pwsh", "-Command"]
  }

The resource block is declared just like any other resource with the resource type and label. Next, we have our standard provisioner block using local-exec to run our AZ Cli commands locally from our Cloud Shell session since that's where we will be running our Terraform code in this example. The AZ Cli commands are used to import the hello world container image to each Azure Container Registry.

The complete configuration will look like the following. Copy the configuration and paste it into a new main.tf. Make sure that you've either removed the terraform contents created from the previous steps or you are using a new directory for this Terraform code:

#Create Resource Group
resource "azurerm_resource_group" "rg" {
  name     = "rg-acrdemo"
  location = "West US"
}

#Create Azure Container Registry
resource "azurerm_container_registry" "acr-prod" {
  name                     = "acrprodregistrycloudskillslab001"
  resource_group_name      = azurerm_resource_group.rg.name
  location                 = azurerm_resource_group.rg.location
  sku                      = "Standard"
  admin_enabled            = false

}

#Create Azure Container Registry
resource "azurerm_container_registry" "acr-dev" {
  name                     = "acrdevregistrycloudskillslab001"
  resource_group_name      = azurerm_resource_group.rg.name
  location                 = azurerm_resource_group.rg.location
  sku                      = "Standard"
  admin_enabled            = false

}

#Import Container Image to Azure Container Registries
resource "null_resource" "image" {

  provisioner "local-exec" {
    command = <<EOT
       az acr import --name ${azurerm_container_registry.acr-prod.name} --source docker.io/library/hello-world:latest --image hello-world:latest
       az acr import --name ${azurerm_container_registry.acr-dev.name} --source docker.io/library/hello-world:latest --image hello-world:latest
   EOT
   interpreter = ["pwsh", "-Command"]
  }
}

We will run the standard sequence of terraform init followed by terraform apply to deploy our resources. Notice that during terraform init the null provider is downloaded. This is because we are using the null_resource resource block which requires the provider:

To prevent automatic upgrades to new major versions that may contain breaking
changes, it is recommended to add version = "..." constraints to the
corresponding provider blocks in configuration, with the constraint strings
suggested below.

* provider.azurerm: version = "~> 1.41"
* provider.null: version = "~> 2.1"

Terraform has been successfully initialized!

After running terraform apply we can see that our two Azure Container Registries are created, and the hello world image is automatically imported to each of them:

Now, what happens if we changed the location of these Azure Container Registries? The resources would be re-created, but the provisioner task would not run again because it only runs the first time we deploy our resources. When designing infrastructure with Terraform, we want to make our configurations as stable as possible for any scenario. To improve this configuration, we will use a triggers argument to declare that we want our provisioner to run again if any of our Azure Container Registries are modified. The code will look like the following:

triggers = {
     prod = azurerm_container_registry.acr-prod.id
     dev = azurerm_container_registry.acr-dev.id
  }

We will add this to our current configuration and the main.tf should look like the following. Copy and paste the code below and overwrite the current main.tf to include the triggers argument. We are also going to change the location of our resources to West US 2 by modifying the location of the azurerm_resource_group resource block:

#Create Resource Group
resource "azurerm_resource_group" "rg" {
  name     = "rg-acrdemo"
  location = "West US 2"
}

#Create Azure Container Registry
resource "azurerm_container_registry" "acr-prod" {
  name                     = "acrprodregistrycloudskillslab001"
  resource_group_name      = azurerm_resource_group.rg.name
  location                 = azurerm_resource_group.rg.location
  sku                      = "Standard"
  admin_enabled            = false


}

#Create Azure Container Registry
resource "azurerm_container_registry" "acr-dev" {
  name                     = "acrdevregistrycloudskillslab001"
  resource_group_name      = azurerm_resource_group.rg.name
  location                 = azurerm_resource_group.rg.location
  sku                      = "Standard"
  admin_enabled            = false


}

#Import Container Image to Azure Container Registries
resource "null_resource" "image" {

  triggers = {
     prod = azurerm_container_registry.acr-prod.id
     dev = azurerm_container_registry.acr-dev.id
  }  

  provisioner "local-exec" {
    command = <<EOT
       az acr import --name ${azurerm_container_registry.acr-prod.name} --source docker.io/library/hello-world:latest --image hello-world:latest
       az acr import --name ${azurerm_container_registry.acr-dev.name} --source docker.io/library/hello-world:latest --image hello-world:latest
   EOT
   interpreter = ["pwsh", "-Command"]
  }
}

Now we will test this out. Run terraform apply against this new configuration. Our resources will be destroyed and recreated in the West US 2 region. During the deployment, we will now see our provisioner is re-executed again because of our triggers argument. In the triggers argument we specified to re-run the provisioner if any modifications are made to our Azure Container Registry resources.

Conclusion

In this article we learned about provisioners in Terraform. We reviewed the concepts of immutable infrastructure and configuration management, and successfully deployed a virtual machine using provisioners to automatically configure Azure DSC on the node. We also created a null_resource block and used it to execute additional tasks when provisioning two Azure Container Registries. Provisioners are a useful way to provide additional configuration beyond what the provider can perform. However, provisioners should be considered a last resort. As you can see in our examples, they complicate the deployment process and can make our configurations more complex and brittle. The provisioner blocks cannot truly be accounted for when running terraform plan since the actions we are taking inside the provisioner block can be anything we specify. Provisioners can also implement network dependencies that prevent Terraform code from being deployed from any environment. Best practice is to lean on the capabilities of Terraform providers or configuration management systems before resorting to using provisioners.

In the next article we will dig into variables which are a core part of creating long lasting reusable and secure Terraform configurations.

Getting Started with Terraform on Azure: Deploying Resources

Luke Orellana — Mon, 13 Jan 2020 13:40:13 +0000

Introduction

Terraform is an open source command line tool that allows users to deploy infrastructure to multiple environments and systems including AWS, Azure, GCP, and even on-premise vSphere. It has a platform agnostic approach that doesn't require programming knowledge. This makes it easy enough for most people to become proficient with Terraform in just 3 - 5 days.

Not only is Terraform easy to learn, but it is also very universal. Terraform uses providers to interact with the API's of various Cloud providers, PaaS services, SaaS services, and on premise resources. There are currently 121 providers on Terraform's official website and the number is increasing steadily. One of the key benefits of Terraform is that it allows for teams to have the power to declaratively deploy infrastructure to multiple systems with a single tool.

Terraform is a great way to start your Infrastructure as Code journey in Azure. It's an agentless tool, meaning agent software is never installed on deployed resources. It is also masterless, so no need to set up a management server, you can get started within just minutes. In this guide we are going use Terraform to deploy resources to Azure using Azure CloudShell.

Prerequisites

Before you begin, you'll need an Azure subscription. Create a free account or use an existing sandbox subscription.

We will be using the Azure Cloud Shell as Terraform already comes preinstalled in this environment and is the fastest way to get started. To launch Azure Cloud Shell, browse to shell.azure.com. Select either Bash or PowerShell. This will bring up a Linux container environment with a command line interface to either tool you select. In this example we will use Bash:

Next, choose the desired subscription to store our Cloud Shell resources in and select Create Storage. This will create a storage account in that subscription which will be used to store our user session data for CloudShell:

Wait a few minutes for Azure to provision the storage account. Once completed, we will be redirected to our Azure Cloud Shell environment. To verify the subscription our Cloud Shell environment is using, we can type the following command:

az account show

If your using the incorrect subscription, or would like to deploy infrastructure to another subscription, type in the following syntax and specify the name or ID of the desired subscription to switch to in the Azure Cloud Shell console:

az account set -s "my subscription name"

Now we are ready to start deploying infrastructure using Terraform

Step 1 — Create a Terraform Config File

Terraform code is written in HCL, also known as Hashicorp Configuration Language, which is designed to be human readable and simple to understand. It's also a declarative language, meaning that we declare what we want to be built and Terraform figures out how to build it and "makes it so". For example, if we declare in HCL code that we want two virtual machines, Terraform will build them. However, if we change our mind later and decide we only need one, we simply remove the 2nd virtual machine from the code. Terraform will then remove the 2nd virtual machine from the environment because it is no longer in code. This is important to understand when designing your Terraform configurations.

The Terraform code is stored in configuration files that are files with a *.tf extension. These files can be created in any text editor, in this example we will be using the integrated file editor inside of Azure Cloud Shell to create and edit our configuration files.

To get started lets make a directory in our Azure Cloud Shell called terraform and then change our directory to that folder:

mkdir terraform && cd $_

Next, we will create a main.tf file to deploy a resource group to our Azure subscription. In Azure Cloud Shell type the following command while in the newly created terraform directory:

code main.tf

This creates a file named main.tf and opens an integrated file editor that we can use to create our configuration file in Azure Cloud Shell. There are more efficient ways to develop Terraform configurations, like using Visual Studio Code with the Terraform extension. However, for the ease of this guide, we will use the integrated file editor in Azure Cloud Shell:

In Terraform the syntax is simple. We declare the components we want to create by defining blocks and arguments in the following format:

<BLOCK TYPE> "<BLOCK LABEL>" "<BLOCK LABEL>" {
  # Block body
  <IDENTIFIER> = <EXPRESSION> # Argument
}

The first block we are going to create is the provider block. This block specifies the provider we will use. Like I mentioned previously, providers allow for Terraform to interact with the API's of the environment we are deploying to. In this case we are using the Azure provider. Many providers are maintained by the vendors themselves. However, the Azure provider has a small team of developers at Hashicorp that are dedicated to maintaining it. In our Terraform configuration, we need to specify that we want to use the Azure provider to deploy our resources. A basic Azure provider block looks like the following:

provider "azurerm" {
  version = "1.38.0"
}

The provider block contains the information on the type of provider we would like to use. It also only requires a single block label. The auzrerm provider is the name of the provider we will be specifying in the parameter string. In this example version = "1.38.01 is our only argument. We are stating that we only want version 1.38 of the provider. It is recommended to always include the version on your provider blocks as future releases of the provider may break Terraform code.

Typically the provider is also the way that we authenticate with that system. In our example we are using Azure Cloud Shell and are already authenticated so there is no need to specify any sort of additional arguments for authenticating. However, if we were running Terraform in a different environment like a laptop or CI/CD pipeline, we would need to either use Azure CLI, a Service Principle Account, or Managed Service Identity for authentication. Check out the documentation for more information on ways to authenticate with the azurerm provider. Also, we can use multiple providers in a single configuration file. So if we needed to span multiple systems or clouds in one configuration we would start by specifying the provider and authentication arguments for each system.

Now that we've gone over the provider block, our next block to create is the resource block. Resource blocks are for the infrastructure objects that we want to declare. In our example we want to create a resource group named rg-MyFirstTerraform in the westus region. We are defining this infrastructure in a resource block and the syntax looks like the following:

resource "azurerm_resource_group" "rg" {
    name     = "rg-MyFirstTerraform"
    location = "westus"
}

The resource block contains two sets of string parameters. The first string parameter represents the resource type, which in our case is the azurerm_resource_group type. For a list of available types of resources to create, check out the azurerm provider documentation. The second string parameter is the resource name. The resource name is the name that we are labeling that resource within the Terraform configuration and must be unique for each resource type that is created. So we can't have two azurerm_resource_group resource types with the name rg in a single configuration.

Now we have a complete Terraform configuration that enables us to deploy our resource group into Azure. Copy the following configuration file syntax below and paste it into our Azure Cloud Shell editor:

provider "azurerm" {
  version = "1.38.0"
}

#create resource group
resource "azurerm_resource_group" "rg" {
    name     = "rg-MyFirstTerraform"
    location = "westus"
}

To save our code to the main.tf file in the Cloud Shell integrated editor, press the CTRL + S keys. Next, press CTRL + Q to close out of the editor. We've now created our first configuration file. In the next section we will deploy it.

Step 2 — Init, Apply, Plan, and Destroy

The first step to deploying our configuration is to initialize our configuration. This process will create a hidden .terraform folder that contains our plugins. Our providers will automatically be downloaded and as you will see, each provider in Terraform has its own binary file. Run the following command inside the terraform directory to perform the initialization:

terraform init

We can see that the azurerm provider plugin binary for version 1.38 is downloaded:

Initializing the backend...

Initializing provider plugins...
- Checking for available provider plugins...
- Downloading plugin for provider "azurerm" (hashicorp/azurerm) 1.38.0...

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

Since our terraform init was successful, we will now run our plan. A plan is a way for terraform to essentially do a "dry run" on the configuration and provide detailed information on what the deployment would look like. This is a similar concept to running a "-whatif" in PowerShell. To run our plan, we will type in the following syntax:

terraform plan

We should now see our plan in the output. Each resource that will be affected is identified and listed in the output. Anything that is a new resource to be created will have a + next to it. You will see later when we destroy this resource it will have a - instead. Towards the bottom we can see the number of items added, changed, or destroyed is specified:

Refreshing Terraform state in-memory prior to plan...
The refreshed state will be used to calculate this plan, but will not be
persisted to local or remote state storage.


------------------------------------------------------------------------

An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # azurerm_resource_group.rg will be created
  + resource "azurerm_resource_group" "rg" {
      + id       = (known after apply)
      + location = "westus"
      + name     = "rg-MyFirstTerraform"
      + tags     = (known after apply)
    }

Plan: 1 to add, 0 to change, 0 to destroy.

------------------------------------------------------------------------

Note: You didn't specify an "-out" parameter to save this plan, so Terraform
can't guarantee that exactly these actions will be performed if
"terraform apply" is subsequently run.

Finally, we can deploy our infrastructure by running our apply. This will display output similar to terraform plan and ask for confirmation to apply the configuration. To start, run the following syntax in the terraform directory:

terraform apply

A plan will be generated the same as when we ran terraform plan, review the plan and type yes to continue. The following output will be displayed indicating that our resource group was created:

azurerm_resource_group.rg: Creating...
azurerm_resource_group.rg: Creation complete after 2s [id=/subscriptions/5c80ecff-4dfe-4fa0-abd4-3c15c2e3be31/resourceGroups/rg-MyFirstTerraform]

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Now that our resource group has been deployed, let's take a look at the state file that was created. The state file is a *.tfstate file that holds the current "state" of the resource we just created. This is how Terraform can keep track of changes that it has made or needs to make.

$ dir
main.tf  terraform.tfstate

When we type cat terraform.tfstate to display its contents we can see the format and contents of our state file:

[secondary_label Output]
{
  "version": 4,
  "terraform_version": "0.12.18",
  "serial": 1,
  "lineage": "74f54b5d-2150-0d28-8631-2330f08a1586",
  "outputs": {},
  "resources": [
    {
      "mode": "managed",
      "type": "azurerm_resource_group",
      "name": "rg",
      "provider": "provider.azurerm",
      "instances": [
        {
          "schema_version": 0,
          "attributes": {
            "id": "/subscriptions/5c80ecff-4dfe-4fa0-abd4-3c15c2e3be31/resourceGroups/rg-MyFirstTerraform",
            "location": "westus2",
            "name": "rg-MyFirstTerraform",
            "tags": {}
          },
          "private": "bnVsbA=="
        }
      ]
    }
  ]
}

The state file is meant to live for the entire life cycle of the resource and contains data on the infrastructure that has been provisioned. Because of this, it is highly recommended to store the state file in a remote location. This is a process called remote state which we will cover in a later article.

Let's try modifying our configuration and see what happens. We will add a tag to our resource group by modifying our main.tf file like so:

provider "azurerm" {
  version = "1.38.0"
}

#create resource group
resource "azurerm_resource_group" "rg" {
    name     = "rg-MyFirstTerraform"
    location = "westus"
    tags      = {
      Environment = "Terraform Demo"
    }
}

When we run our terraform plan we can see the plan output which shows any resources that are changed:

An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
  ~ update in-place

Terraform will perform the following actions:

  # azurerm_resource_group.rg will be updated in-place
  ~ resource "azurerm_resource_group" "rg" {
        id       = "/subscriptions/5c80ecff-4dfe-4fa0-abd4-3c15c2e3be31/resourceGroups/rg-MyFirstTerraform"
        location = "westus"
        name     = "rg-MyFirstTerraform"
      ~ tags     = {
          + "Environment" = "Terraform Demo"
        }
    }

Plan: 0 to add, 1 to change, 0 to destroy.

The ~ indicates a resource that will be updated in place meaning an argument will be modified without having to remove the resource and rebuild it. Before we apply the change. Let's modify the config file again and change our resource group to exist in the westus2 region:

provider "azurerm" {
  version = "1.38.0"
}

#create resource group
resource "azurerm_resource_group" "rg" {
    name     = "rg-MyFirstTerraform"
    location = "westus2"
    tags      = {
      Environment = "Terraform Demo"
    }
}

Now when we run terraform plan we can see the output:

An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
-/+ destroy and then create replacement

Terraform will perform the following actions:

  # azurerm_resource_group.rg must be replaced
-/+ resource "azurerm_resource_group" "rg" {
      ~ id       = "/subscriptions/5c80ecff-4dfe-4fa0-abd4-3c15c2e3be31/resourceGroups/rg-MyFirstTerraform" -> (known after apply)
      ~ location = "westus" -> "westus2" # forces replacement
        name     = "rg-MyFirstTerraform"
      ~ tags     = {
          + "Environment" = "Terraform Demo"
        }
    }

Plan: 1 to add, 0 to change, 1 to destroy.

We can see a -/+ next to the azurerm_resource_group.rg resource. This indicates that terraform will destroy this resource and then re-create it. Terraform already knows that we need to delete the resource group and build it in another region, and it will automatically handle the logistics for us. The # forces replacement note states that the location is the argument that is causing the resource to be completely replaced.

It is extremely important to understand how to properly read plan files when modifying infrastructure that is already deployed. Make sure you understand the effects of the changes you are making and if any downtime of the resource is required from the change. It is highly recommended to test changes in a development environment first since it's easy to copy the terraform code and deploy in another environment to test.

We run terraform apply and see that our resource group is moved to westus2 (logs truncated for brevity):

...
azurerm_resource_group.rg: Still destroying... [id=/subscriptions/5c80ecff-4dfe-4fa0-abd4-...e31/resourceGroups/rg-MyFirstTerraform, 40s elapsed]
azurerm_resource_group.rg: Destruction complete after 48s
azurerm_resource_group.rg: Creating...
azurerm_resource_group.rg: Creation complete after 2s [id=/subscriptions/5c80ecff-4dfe-4fa0-abd4-3c15c2e3be31/resourceGroups/rg-MyFirstTerraform]

Let's tear down our newly deployed resource by running a destroy. This will delete all the items that we deployed using our Terraform configuration. So, in our example the resource group will be destroyed. Note that a destroy is not yet considered an action that should be performed on infrastructure that is in production. When running a destroy, there is no "undo button", the infrastructure is completely removed. We run a destroy by typing in the following command:

terraform destroy

We get another plan output indicating which resources will be destroyed indicated by a - next to them. Also we can see the 1 to destroy in the plan section at the bottom:

An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
  - destroy

Terraform will perform the following actions:

  # azurerm_resource_group.rg will be destroyed
  - resource "azurerm_resource_group" "rg" {
      - id       = "/subscriptions/5c80ecff-4dfe-4fa0-abd4-3c15c2e3be31/resourceGroups/rg-MyFirstTerraform" -> null
      - location = "westus2" -> null
      - name     = "rg-MyFirstTerraform" -> null
      - tags     = {} -> null
    }

Plan: 0 to add, 0 to change, 1 to destroy.

Type yes to confirm the destroy. We should then get the following output displaying our resource group being destroyed:

azurerm_resource_group.rg: Destroying... [id=/subscriptions/5c80ecff-4dfe-4fa0-abd4-3c15c2e3be31/resourceGroups/rg-MyFirstTerraform]
azurerm_resource_group.rg: Still destroying... [id=/subscriptions/5c80ecff-4dfe-4fa0-abd4-...e31/resourceGroups/rg-MyFirstTerraform, 10s elapsed]
azurerm_resource_group.rg: Still destroying... [id=/subscriptions/5c80ecff-4dfe-4fa0-abd4-...e31/resourceGroups/rg-MyFirstTerraform, 20s elapsed]
azurerm_resource_group.rg: Still destroying... [id=/subscriptions/5c80ecff-4dfe-4fa0-abd4-...e31/resourceGroups/rg-MyFirstTerraform, 30s elapsed]
azurerm_resource_group.rg: Still destroying... [id=/subscriptions/5c80ecff-4dfe-4fa0-abd4-...e31/resourceGroups/rg-MyFirstTerraform, 40s elapsed]
azurerm_resource_group.rg: Destruction complete after 47s

Destroy complete! Resources: 1 destroyed.

Now we have successfully created and destroyed a resource group in Azure using Terraform. Let's move on to deploying something more exciting. In the next step we will deploy a virtual machine.

Step 3 — Deploying a Virtual Machine

In Azure, a virtual machine has a few resources that are required in order to build one. We will create a resource in Terraform for the following resources:

Resource group
Virtual network
Subnet
Network Interface
Virtual Machine

We already have the code for the resource group from the previous step. Let's add the following code to the main.tf for our virtual network:

resource "azurerm_virtual_network" "vnet" {
    name                = "vnet-dev-westus2-001"
    address_space       = ["10.0.0.0/16"]
    location            = "westus2"
    resource_group_name = azurerm_resource_group.rg.name
}

We are using the azurerm_virtual_network resource type with the vnet resource name. Notice the address_space value is surrounded in bracket squares []. This indicates that the value type is a list and can contain multiple comma separated values. For example we could put in more than one address space such as ["10.0.0.0/16,10.1.0.0/16"] however for this example we will just be using one. Lastly, we will point out the azurerm_resource_group.rg.name expression. It is referencing the value of another resource's attributes. In this case we are referencing our azurerm_resource_group type with the resource name of rg and its name attribute. The value of the name attribute is rg-MyFirstTerraform in our example. Referencing the attribute of our resource like this allow us to build upon information within our resources. Because we are referencing the name value of our resource group, Terraform will automatically know to build the resource group first. This is called an implicit dependency.

Next, we will add the subnet, network security group, public IP, and virtual machine resources to our config. The complete configuration should look like this. Copy the following below and paste it into the Azure Cloud Shell editor to overwrite our main.tf to include these changes:

provider "azurerm" {
  version = "1.38.0"
}

#create resource group
resource "azurerm_resource_group" "rg" {
    name     = "rg-MyFirstTerraform"
    location = "westus2"
    tags      = {
      Environment = "Terraform Demo"
    }
}

#Create virtual network
resource "azurerm_virtual_network" "vnet" {
    name                = "vnet-dev-westus2-001"
    address_space       = ["10.0.0.0/16"]
    location            = "westus2"
    resource_group_name = azurerm_resource_group.rg.name
}

# Create subnet
resource "azurerm_subnet" "subnet" {
  name                 = "snet-dev-westus2-001 "
  resource_group_name  = azurerm_resource_group.rg.name
  virtual_network_name = azurerm_virtual_network.vnet.name
  address_prefix       = "10.0.0.0/24"
}

# Create public IP
resource "azurerm_public_ip" "publicip" {
  name                = "pip-vmterraform-dev-westus2-001"
  location            = "westus2"
  resource_group_name = azurerm_resource_group.rg.name
  allocation_method   = "Static"
}


# Create network security group and rule
resource "azurerm_network_security_group" "nsg" {
  name                = "nsg-sshallow-001 "
  location            = "westus2"
  resource_group_name = azurerm_resource_group.rg.name

  security_rule {
    name                       = "SSH"
    priority                   = 1001
    direction                  = "Inbound"
    access                     = "Allow"
    protocol                   = "Tcp"
    source_port_range          = "*"
    destination_port_range     = "22"
    source_address_prefix      = "*"
    destination_address_prefix = "*"
  }
}

# Create network interface
resource "azurerm_network_interface" "nic" {
  name                      = "nic-01-vmterraform-dev-001 "
  location                  = "westus2"
  resource_group_name       = azurerm_resource_group.rg.name
  network_security_group_id = azurerm_network_security_group.nsg.id

  ip_configuration {
    name                          = "niccfg-vmterraform"
    subnet_id                     = azurerm_subnet.subnet.id
    private_ip_address_allocation = "dynamic"
    public_ip_address_id          = azurerm_public_ip.publicip.id
  }
}

# Create virtual machine
resource "azurerm_virtual_machine" "vm" {
  name                  = "vmterraform"
  location              = "westus2"
  resource_group_name   = azurerm_resource_group.rg.name
  network_interface_ids = [azurerm_network_interface.nic.id]
  vm_size               = "Standard_B1s"

  storage_os_disk {
    name              = "stvmpmvmterraformos"
    caching           = "ReadWrite"
    create_option     = "FromImage"
    managed_disk_type = "Premium_LRS"
  }

  storage_image_reference {
    publisher = "Canonical"
    offer     = "UbuntuServer"
    sku       = "16.04.0-LTS"
    version   = "latest"
  }

  os_profile {
    computer_name  = "vmterraform"
    admin_username = "terrauser"
    admin_password = "Password1234!"
  }

  os_profile_linux_config {
    disable_password_authentication = false
  }
}

Notice we have our password in plain text in the configuration file. This is not best practice and we are only doing it to demonstrate deploying the virtual machine. We will fix that issue in a later article. Now, let's run terraform init to initialize our directory. Next, we will run our plan, but we will use the -out parameter to output our plan to a file. Typically, this is the best practice for automating Terraform in a CI/CD pipeline. This allows for additional unit testing steps to be run against the plan file before deployment. It also guarantees our actions in the plan when we run terraform apply against the plan file. In this example we named the plan file tfvm, but it can be named anything that makes logical sense for the environment we are deploying. We will run terraform plan and create our plan file. The syntax is below:

terraform plan -out=tfvm

Once the plan is successful, the plan file is created. With the command terraform show we can specify our plan file name and review the plan or even have another team member review it:

terraform show tfvm

An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # azurerm_network_interface.nic will be created
  + resource "azurerm_network_interface" "nic" {
      + applied_dns_servers           = (known after
...

We could also take this plan file and use terraform show -json tfvm to get our plan in a JSON format. This opens a lot of doors for automating the review of our plan. For example, we could then take the JSON file of our plan and use PowerShell's convertfrom-json cmdlet to convert it into a PowerShell Object and perform customized Pester testing against our plan files. Also note that these plan files are not encrypted and may possibly contain secrets or passwords in them. It's not best practice to store these and they should only temporarily exist. There are plans on the Terraform roadmap to make these plan files more secure in the future.

Next, we will run our terraform apply against the actions in the plan file by specifying the file name. Notice that we won't be prompted to confirm that we want to apply the changes when we run apply this way:

terraform apply tfvm

We should immediately see the infrastructure starting to build:

azurerm_resource_group.rg: Creating...
azurerm_resource_group.rg: Creation complete after 1s [id=/subscriptions/5c80ecff-4dfe-4fa0-abd4-3c15c2e3be31/resourceGroups/rg-MyFirstTerraform]
azurerm_virtual_network.vnet: Creating...
azurerm_public_ip.publicip: Creating...
azurerm_network_security_group.nsg: Creating...
azurerm_public_ip.publicip: Creation complete after 6s [id=/subscriptions/5c80ecff-4dfe-4fa0-abd4-3c15c2e3be31/resourceGroups/rg-MyFirstTerraform/providers/Microsoft.Network/publicIPAddresses/pip-vmterraform-dev-westus2-001]

When our deployment is complete, we will see the following message:

Apply complete! Resources: 7 added, 0 changed, 0 destroyed.

This is where you can start to see the power of Terraform. In a few minutes we have deployed a Virtual Machine with a subnet, virtual network, and public IP address.

Now that our virtual machine is deployed, lets destroy our infrastructure using a destroy. Like I stated before, this typically is only done in dev and sandbox environments. Now let's destroy our infrastructure, but this time we will use a different method. We will create a destroy plan which will create a plan file, meant for destroying infrastructure, which we will then run terraform apply against. To do this run the following commands:

terraform plan -destroy -out=tfvmdestroy

After carefully reviewing our destroy, we can apply the destroy plan file:

terraform apply tfvmdestroy

Now our infrastructure will start to tear down displaying snippets of output like below:

...
azurerm_virtual_machine.vm: Still destroying... [id=/subscriptions/5c80ecff-4dfe-4fa0-abd4-...ft.Compute/virtualMachines/vmterraform, 1m30s elapsed]
azurerm_virtual_machine.vm: Destruction complete after 1m31s
azurerm_network_interface.nic: Destroying... [id=/subscriptions/5c80ecff-4dfe-4fa0-abd4-3c15c2e3be31/resourceGroups/rg-MyFirstTerraform/providers/Microsoft.Network/networkInterfaces/nic-01-vmterraform-dev-001]
azurerm_network_interface.nic: Still destroying... [id=/subscriptions/5c80ecff-4dfe-4fa0-abd4-...kInterfaces/nic-01-vmterraform-dev-001, 10s elapsed]
azurerm_network_interface.nic: Still destroying... [id=/subscriptions/5c80ecff-4dfe-4fa0-abd4-...kInterfaces/nic-01-vmterraform-dev-001, 20s elapsed]
...

Once all of our infrastructure is completely destroyed, we will see the following message:

Apply complete! Resources: 0 added, 0 changed, 7 destroyed.

Now you can see how quickly we can build and tear down infrastructure with Terraform in a matter of minutes.

Conclusion

In this article we learned how to create Terraform configuration files. We reviewed the concepts of the init, plan, apply, and destroy commands that are most commonly used for deploying Terraform configuration files. We also successfully deployed a virtual machine into Azure with all its networking components. Terraform is a very powerful tool and greatly improves consistency and efficiency with managing infrastructure. Now imagine using the same process we used to deploy infrastructure in Azure with another cloud or on-premise VMware environment (using different providers and resource blocks).

In the next article we will go even further into deploying virtual machines by using provisioners to customize resources after they are deployed.

How to Use Pipeline Templates to Manage Infrastructure with Terraform on Azure DevOps

Luke Orellana — Wed, 08 Jan 2020 17:14:02 +0000

Introduction

Infrastructure as Code is considered a best practice when managing infrastructure in the cloud. Tools like Terraform are becoming increasingly popular due to their ease of use and multi cloud nature. However, adopting the Infrastructure as Code model can become hectic and unmanageable if not organized strategically. With designing any automated process, simplicity is key to creating long lasting solutions. In Azure DevOps, one way of simplifying code for Terraform configurations is by using pipeline templates to represent our infrastructure. Each value in the template parameters is used to customize our configuration which is then built dynamically during the build pipeline. We can go from the traditional repository structure of storing our Terraform configuration files in folders to representing our infrastructure with pipeline template parameters:

Structuring our source code repositories this way allow us to scale our solution much easier and provides some of the following benefits:

No more one-off changes can be made to Terraform configuration files since all configurations are built dynamically during the build pipeline and will all be the same. This prevents issues where team members are making changes to one system's Terraform configuration causing us to have separate one-off configurations to maintain.
We can now separate our Terraform code from the team that deploys the configurations. All the Terraform modules and files are stored in another repository which we can limit access to and allow just our Terraform team to manage them.
Change tracking of infrastructure resources is much more simplified now since we are just looking at template parameter value changes in a single file.
Each deployment is going to be more consistent since we are using the same base Terraform configurations in each deployment. This also allows us to treat our Terraform configurations as cattle.

In this guide, we will use the Azure DevOps Demo Generator to import an Azure DevOps project. This project has been pre-configured to deploy Azure Container Instances with Terraform using pipeline templates as code. We will deploy some resources to our Azure subscription and review the innerworkings of this concept.

Prerequisites

Before you begin this guide you'll need the following:

An Azure Subscription, you can get started with a free account.
An Azure DevOps Organization. The basic plan is free for the first 5 users.

Step 1 — Importing the Project with Azure DevOps Demo Generator

First, we are going to import an Azure DevOps template project into our Azure DevOps organization. This will allow us to get started as fast as possible. To get started, navigate to the Azure DevOps Demo Generator website.

Sign in with your Azure DevOps account. Select Accept to authorize the Azure DevOps Demo Generator application to access your account. Now we are ready to import our template. Select Choose Template:

A pop-up window will appear, choose the Private tab and select the GitHub option. Paste in the following GitHub URL which hosts the template for our project:

https://raw.githubusercontent.com/allanore/AzDevOpsYamlAsCode/master/TemplatesAsCode.zip

Next, select Submit:

Select your organization from the drop-down menu and type in a name for the new project that we are creating. In the example I will be naming the project TemplateAsCode. Check the box for The extension(s) are offered to you... and select Create Project:

Notice that the Replace Tokens and Terraform extensions are required for this project. Extensions are add-ons for Azure DevOps that provide an enhancement to the service. In this case we will be using the Replace Tokens extension to build our Terraform configuration files during the build pipeline. Additionally, we are using the Terraform extension as well to easily deploy our configurations to Azure. These two extensions will automatically be installed when we import the project via the Azure DevOps Demo Generator.

Finally, after the import is successful, we will get the following message. Select Navigate to Project to be directed straight to our new project:

In the next step we will review the innerworkings of the project that we just imported.

Step 2 — Reviewing the Template as Code Design

Let's look at how the code repositories for this project are set up. On the left-hand side select Repos then choose Files. By selecting the drop down, we can see that there are two source code repositories or repos in our project. Select the ACI repo:

The ACI repo for this project contains the infrastructure code for the Azure Container Instances in our Azure environment with folders for Development and Production. In this project, instead of creating a repository for each application, or one for Dev and Prod, we are creating a repository for each cloud service or component. This allows for our infrastructure deployments to be simplified and as "cookie cutter" as possible which really shines with large environments. The environment size and business needs will really play a role on the most effective repo structure design. But, for this demonstration we are going to go this route to keep things simple.

The pipelineconfig.yml is our build pipeline yaml file. If we look at the contents of this file, we can see it starts with the resources section. This is sourcing the code from our 2nd repo, templates, and allows us to use that repo code in our build pipeline. Next, is the stages section which contains our job and tasks for building the Terraform configurations. In the template section we are calling the template that we want to build which is pointing to the aci-prod-sampleapp2.yml file. When we deploy this pipeline, it will deploy the components in that template file which we will look at next:

The other three yaml files in the ACI repo represent the Azure Container Instance infrastructure in our Production and Development environments. If we look at aci-prod-sampleapp2.yml, we can see that it's a series of pipeline templates sourcing from the templates repo. The template parameters are what is making up the configuration of our components, in this example we have two templates, one for the resource group and one for the actual ACI component. Breaking up the resource group and the ACI resource into separate templates allows us to deploy more than one ACI resource to a resource group:

In our templates repo we can see our two yaml files for our pipeline templates along with a Terraform folder. This folder is where we keep our "templatized" terraform configuration files. These files contain generic Terraform configuration files with variables that are surrounded by a double "". This tells our Replace Tokens task, which runs during the build pipeline, to replace any strings in our container.tf and main.tf files that are surrounded by "" with it's respective environment variable. So `CPU_` will be replaced by the CPU environment variable that we declare in the pipeline template:

When looking at the azure-aci-rg.yml template, we can see at the top we are listing our parameters and then setting those as environment variables in the cmdline@2 task. Next is the CopyFiles@2 task. We are copying the Terraform configuration template file, main.tf, from the \Terraform\ACI directory of our source control repo to our $(Build.ArtifactStagingDirectory). This is where we are building our Terraform files to produce as an artifact. An artifact, from a developer perspective, typically contains the compiled binaries and libraries used to run an application. These application files are then deployed to an environment in the release pipeline. With our IaC build pipeline, our Terraform configuration files are the artifacts in this case; and we will be deploying them with the release pipeline. In the last task we run the replacetokens@3 task to swap out the variables surrounded by __ with our associated environment variable. This entire template allows us to take in parameter values and generate a Terraform configuration file from it:

If we look at the azure-aci-container.yml template, we can see the same structure as azure-aci-rg.yml. Since Azure Container Instances require many more values to create than a resource group, we have many more parameters declared at the beginning and in the CmdLine@2 task, where we declare our environment variables. The key difference in this template is the extra CmdLine@2 task at the end that renames the container.tf file to the name of the ACI resource. This allows us to create additional ACI resources in the same Terraform configuration by providing a unique name to the configuration file, so we don't copy over any files:

Now that we've reviewed our two repos, let's wrap our head around the workflow in this build pipeline. Our pipelineconfig.yml file is our build pipeline file, which references the desired infrastructure yml file to build such as aci-prod-sampleapp1.yml. This file then points to several pipeline templates located in the templates repository which each build out the Terraform configuration files according to the parameter values specified in aci-prod-sampleapp1.yml. Finally, once our Terraform configuration files are built, they are published as an artifact which will then be used by our release pipeline to deploy to Azure:

In the next step we are going to deploy the Azure Container Instance infrastructure described in the aci-prod-sampleapp2.yml file.

Step 3 — Deploying Resources

First, let's run our build pipeline. On the left-hand side select Pipelines to expand the options underneath it. Then, once again, select Pipelines to see our build pipelines. Select Terraform-ACI-CI and select Run pipeline:

Select Run in the pop-up window to start our build pipeline. It will run for a minute or so and the artifacts will then be generated for our sampleapp2 infrastructure. We can view these artifacts by selecting 1 published under the artifacts section:

We can see our Terraform configuration files for both ACI resources are there:

Let's deploy the infrastructure to our Azure subscription by running the release pipeline, but first we need to edit the release pipeline to configure a connection to our Azure subscription. On the left hand side expand Pipelines and select Releases. We can see our Terraform-ACI-CD pipeline has been imported, select Edit:

Under our Build stage select 1 job, 5 tasks to edit our tasks to include our Azure subscription:

Select the first task Set up Azure Storage Account... and click on the drop-down box under Azure subscription. A list of subscriptions associated with your tenant will appear in this box. Select one that you would like to deploy the example Azure Container Instances too and select Authorize. You may be prompted to login to your Azure account. This process will create a Service Principal account in your Azure tenant and assign permissions to that subscription with that account. Azure DevOps will set this up as a service connection and use that to connect to Azure:

Next, we need to configure the remaining Terraform tasks with the same Azure service connection. The new connection that we made should now show up in the drop-down menu under Available Azure service connections. Select this for all 3 of the Terraform tasks that say some settings need attention this is because they are missing their Azure subscription settings:

Select the Variables tab at the top. We will need to rename the statestorageaccount variable value. You can set this to anything you want. This because we are storing the Terraform state in an Azure storage account which is required to have a publicly unique name. If we don't rename this, we will get an error during the release pipeline deployment:

Once complete, select Save at the top. Now we are ready to deploy our infrastructure. Select Create Release and then select Create to initiate the release pipeline. We will see a new message in green indicating that the release has been created. Select Release-1 to view the release process for deploying the ACI resources into our Azure subscription:

We will see that the release is running and can view the different steps of our release pipeline. This is a typical pipeline for deploying Terraform code, we provision a storage account to store our Terraform state, run a terraform init to initialize our Terraform environment and connect to our remote state (azure storage account in this case). Then we run a terraform plan to verify our configuration files have no issues. Finally if all the previous tasks are successful we run our terraform apply -auto-approve to deploy the infrastructure:

Once our release has run successfully, we will see a Succeeded message:

If we look in our Azure portal, we can see the resources are in fact there:

Next, we will add another ACI resource to our sampleapp2 application and redeploy our configuration with a pull request.

Step 4 — Modifying Resources with Pull Request

We need to set up a branch policy for our master branch, this will allow us to automatically kick off a build if a Pull Request is initiated. To do this expand Repos and select Branches. On the master branch select the ... all the way on the right side and select Branch policies:

Select + Add build policy. In the pop-up window, select our build pipeline Terraform-ACI-CI and keep the defaults for everything else. Select Save to create the build policy:

Now we are ready to submit a Pull Request and trigger a new build. Let's create a new branch to make our changes in. In the ACI repository select the dropdown labeled master and select + New Branch:

In our example we will name the new branch deploysampleapp2. Select Create. We are now actively using the new branch we just created in Azure DevOps. Select the aci-prod-sampleapp2.yml file and select Edit to edit the file. We are going to add another ACI resource by adding in another ACI template with the required parameters:

#Build Azure Container Group
- template: azure-aci-container.yml@templates
  parameters:
    ContainerGroupName: 'sampleapp2-3'
    DNSName: 'cloudskillssampleapp2-3'
    OS: 'Linux'
    ContainerName: 'helloworld'
    Image: 'microsoft/aci-helloworld:latest'
    CPU: '1'
    Memory: '4'
    Port: '80'
    Protocol: 'TCP'

Next, select Commit to save our changes:

Select Commit again. Now there will be a pop up for a pull request, select Create a pull request:

In the next window we can write in some information on our pull request and description. This provides great documentation for our deployments:

Select Create, and in the next windows select Set auto-complete. This will complete the Pull Request if our build runs successfully:

Then select set auto-complete again to confirm. Our build pipeline is now running with the changes from our new branch. If the build is successful, our branch will merge with the master branch with our new changes. Also note, if we look back at our pull request history, we can see a very simple outline of the new infrastructure that was added. This is one of the benefits of using the template parameters to define our infrastructure. Our pull requests get much easier to review:

Now let's go ahead and deploy our new resources. Expand Pipelines on the left-hand side and select Releases. Then select the Terraform-ACI-CD pipelines and select Create Release. Select Create to start deploying.

In our second release our additional ACI resource will be deployed. Once the release has been completed, we can double check in the Azure portal:

Conclusion

In this article we imported a project that utilizes pipeline templates to generate Terraform configurations during the build pipeline. We also successfully deployed Azure Container Instance resources from these pipeline templates and even added additional resources using a Pull Request.

As you can see, this model can greatly simplify Infrastructure as Code environments and provide greater management and consistency. However, keep in mind that this strategy might not fit all scenarios. For example, a tiny environment might not need to go this far with only a few resources. They may be fine with just a few repositories with Terraform configurations stored inside them. Also, an extremely complex environment could be too limited by the templatized configurations and may require a much more complex set up.

The Infrastructure as Code model can become difficult to manage at large scale, using pipeline templates instead of treating our Terraform config files like sheep prevents us from creating snowflake infrastructure and allows us to scale our infrastructure rapidly and in a stable way. For more information on Azure DevOps templates be sure to check out Microsoft's documentation. Also, if you're interested in learning more about Terraform take a look at their website for more material.

Forem: Luke Orellana

Getting Started with Terraform on Azure: Tips and Tricks

Table Of Contents

Modules

Version Providers and Modules

Use Dependency Injections

Remote State

Split Up Terraform States

Source Control

Structure Repo to Business Needs

Keep All Live Infrastructure in the Master Branch

Execute Terraform Code Through a Pipeline

Keeping Designs Simple and Reusable

Use Provisioners Sparingly

Use Terraform Graph to Troubleshoot Dependency Issues

Use the Terraform Registry

Conclusion

Getting Started with Terraform on Azure: Testing

Table Of Contents

Prerequisites

Step 1 — Module Repo Folder Structure

Step 2 — Types of Testing

Step 3 — Static Analysis

Step 4— Unit Testing

Base Setup

Configure Terraform Options

Add In The Tests

Step 5 — Integration Testing

Base Test

Add in Terraform Options

Add In The tests

Step 6 — End-to-End Testing

Conclusion

Getting Started with Terraform on Azure: Importing Existing Infrastructure

Table Of Contents

Prerequisites

Step 1 — Simple Import

Step 2 — Complex Imports

Step 3 — Import Modules

Step 4 — Remote State

Conclusion

Getting Started with Terraform on Azure: Functions, Expressions, and Loops

Table Of Contents

Prerequisites

Step 1 — Functions

Step 2 — Complex Expressions

Operators

Conditions

For Expressions

Splat Expressions

Step 3 — Loops

Count

For_each

Dynamic Blocks

Conclusion

Getting Started with Terraform on Azure: Modules

Table Of Contents

Prerequisites

Step 1 — Module Architecture

Step 2 — Creating Modules

variables.tf

main.tf

main.tf

Step 3 — Module Outputs

Step 4 — Git Modules

Step 5 - Terraform Registry

Conclusion

Getting Started with Terraform on Azure: Remote State

Introduction

Table Of Contents

Prerequisites

Step 1 — Remote State with Storage Account

Step 2 — Remote State with Terraform Cloud

Local Execution

Terraform Cloud Execution

Step 3 — Accessing Outputs from Remote State

Step 4 — Partial State Configuration

Conclusion

Getting Started with Terraform on Azure: Variables

Introduction