Create a Terraform base template in Azure using Yeoman

Article
03/20/2023

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

In this article, you learn how to use the combination of Terraform and Yeoman. Terraform is a tool for creating infrastructure on Azure. Yeoman makes it easy to create Terraform modules.

In this article, you learn how to do the following tasks:

Create a base Terraform template using the Yeoman module generator.
Test the Terraform template using two different methods.
Run the Terraform module using a Docker file.
Run the Terraform module natively in Azure Cloud Shell.

1. Configure your environment

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

Configure Terraform: If you haven't already done so, configure Terraform using one of the following options:

Visual Studio Code: Download Visual Studio Code for your platform.
Docker: Install Docker to run the module created by the Yeoman generator.
Go programming language: Install Go as Yeoman-generated test cases are code using the Go language.
Nodejs: Install Node.js
Install Yeoman: Run the following command: npm install -g yo.
Yeoman template: Run the following command to install the Yeoman template for Terraform module: npm install -g generator-az-terra-module.

2. Create directory for Yeoman-generated module

The Yeoman template generates files in the current directory. For this reason, you need to create a directory.

This empty directory is required to be put under $GOPATH/src. For more information about this path, see the article Setting GOPATH.

Navigate to the parent directory from which to create a new directory.
Run the following command replacing the placeholder. For this example, a directory name of GeneratorDocSample is used.
```
mkdir <new-directory-name>
```
Navigate to the new directory:
```
cd <new-directory-name>
```

3. Create base module template

Run the following command:
```
yo az-terra-module
```
Follow the on-screen instructions to provide the following information:
- Terraform module project Name - A value of doc-sample-module is used for the example.
- Would you like to include the Docker image file? - Enter y. If you enter n, the generated module code will support running only in native mode.
List the directory contents to view the resulting files that are created:
```
ls
```

4. Review the generated module code

Launch Visual Studio Code
From the menu bar, select File > Open Folder and select the folder you created.

The following files were created by the Yeoman module generator:

main.tf - Defines a module called random-shuffle. The input is a string_list. The output is the count of the permutations.
variables.tf - Defines the input and output variables used by the module.
outputs.tf - Defines what the module outputs. Here, it's the value returned by random_shuffle, which is a built-in, Terraform module.
Rakefile - Defines the build steps. These steps include:
- build - Validates the formatting of the main.tf file.
- unit - The generated module skeleton doesn't include code for a unit test. If you want to specify a unit test scenario, you would you add that code here.
- e2e - Runs an end-to-end test of the module.
test
- Test cases are written in Go.
- All codes in test are end-to-end tests.
- End-to-end tests attempt to provision all of the items defined under fixture. The results in the template_output.go file are compared with the pre-defined expected values.
- Gopkg.lock and Gopkg.toml: Defines the dependencies.

For more information about the Yeoman generator for Azure https://github.com/Azure/generator-az-terra-module, see the Terratest documentation.

5. Test the Terraform module using a Docker file

This section shows how to test a Terraform module using a Docker file.

Note

This example runs the module locally; not on Azure.

Confirm Docker is installed and running

From a command prompt, enter docker version.

Docker version

The resulting output confirms that Docker is installed.

To confirm that Docker is actually running, enter docker info.

Docker info

Set up a Docker container

From a command prompt, enter

docker build --build-arg BUILD_ARM_SUBSCRIPTION_ID= --build-arg BUILD_ARM_CLIENT_ID= --build-arg BUILD_ARM_CLIENT_SECRET= --build-arg BUILD_ARM_TENANT_ID= -t terra-mod-example ..

The message Successfully built will be displayed.
From the command prompt, enter docker image ls to see your created module terra-mod-example listed.
Enter docker run -it terra-mod-example /bin/sh. After running the docker run command, you're in the Docker environment. At that point, you can discover the file by using the ls command.

Build the module

Run the following command:
```
bundle install
```
Run the following command:
```
rake build
```

Run the end-to-end test

Run the following command:
```
rake e2e
```
After a few moments, the PASS message will appear.
Enter exit to complete the test and exit the Docker environment.

6. Use Yeoman generator to create and test a module

In this section, the Yeoman generator is used to create and test a module in Cloud Shell. Using Cloud Shell instead of using a Docker file greatly simplifies the process. Using Cloud Shell, the following products are all pre-installed:

Node.js
Yeoman
Terraform

Start a Cloud Shell session

Start an Azure Cloud Shell session via either the Azure portal, shell.azure.com, or the Azure mobile app.
The Welcome to Azure Cloud Shell page opens. Select Bash (Linux).
If you have not already set up an Azure storage account, the following screen appears. Select Create storage.
Azure Cloud Shell launches in the shell you previously selected and displays information for the cloud drive it just created for you.

Prepare a directory to hold your Terraform module

At this point, Cloud Shell will have already configured GOPATH in your environment variables for you. To see the path, enter go env.
Create the $GOPATH directory, if one doesn't already exist: Enter mkdir ~/go.
Create a directory within the $GOPATH directory. This directory is used to hold the different project directories created in this example.
```
mkdir ~/go/src
```
Create a directory to hold your Terraform module replacing the placeholder. For this example, a directory name of my-module-name is used.
```
mkdir ~/go/src/<your-module-name>
```
Navigate to your module directory:
```
cd ~/go/src/<your-module-name>
```

Create and test your Terraform module

Run the following command and follow the instructions. When asked if you want to create the Docker files, you enter N.
```
yo az-terra-module
```
Run the following command to install the dependencies:
```
bundle install
```
Run the following command to build the module:
```
rake build
```
Run the following command to run the test:
```
rake e2e
```

Troubleshoot Terraform on Azure

Troubleshoot common problems when using Terraform on Azure

Next steps

Install and use the Azure Terraform Visual Studio Code extension.