Usage Guide
Summary
This section describes usage guidance.
Subsections of Usage Guide
Concepts
Note
This page is a work in progress and will be updated as we improve & finalize the content. Please check back regularly for updates.
When developing an Azure solution using AVM modules, there are several aspects to consider. This page covers important concepts and provides guidance the technical decisions. Each concept/topic referenced here will be further detailed in the corresponding Bicep or Terraform specific guidance.
Language-agnostic concepts
Topics/concepts that are relevant and applicable for both Bicep and Terraform.
Module Sourcing
Public Registry
Leveraging the public registries (i.e., the Bicep Public Registry or the Terraform Public Registry) is the most common and recommended approach.
This allows you to leverage the latest and greatest features of the AVM modules, as well as the latest security updates. While there aren’t any prerequisites for using the public registry - no extra software component or service needs to be installed and no configuration is needed - the client machine the deployment is initiated from will need to have access to the public registry.
Private Registry (synced)
A private registry - that is hosted in your own environment - can store modules originating from the public registry. Using a private registry still grants you the latest version of AVM modules while allowing you to review each version of each module before admitting them to your private registry. You also have control over who can access your own private registry. Note that using a private registry means that you’re still using each module as is, without making any changes.
Inner-sourcing
Inner-sourcing AVM means maintaining your own, synchronized copy of AVM modules in your own internal private registry, repositories or other storage option. Customers normally look to inner-source AVM modules when they have strict security and compliance requirements, or when they want to publish their own lightly wrapped versions of the modules to meet their specific needs; for example changing some allowed or default values for parameter or variable inputs.
This is a more complex approach and requires more effort to maintain, but it can be beneficial in certain scenarios, however, it should not be the default approach as it can lead to a lot of overhead and maintenance and requires significant skills and resources to set up and maintain.
There are many ways to approach inner-sourcing AVM modules for both Bicep and Terraform. The AVM team will be publishing guidance on this topic, based on customer experience and learnings.
Tip
You can see the AVM team talking about inner-sourcing on the AVM February 2025 community call on YouTube.
Solution Development
This section provides advanced guidance for developing solutions using Azure Verified Modules (AVM). It covers technical decisions and concepts that are important for building and deploying Azure solutions using AVM modules.
Planning your solution
When implementing infrastructure in Azure leveraging IaaS and PaaS services, there are multiple options for Azure deployments. In this article we assume that a decision has been made to implement your solution, using Infrastructure-as-Code (IaC). This is best suited to allow programmatic declarative control of the target infrastructure and is ideal for projects that require repeatability and idempotency.
Choosing an Infrastructure-as-Code language
There are multiple language choices when implementing your solution using IaC in Azure. The Azure Verified Modules project currently supports Bicep and Terraform. The following guidance summarizes considerations that can help choose the option that best suits your requirements.
Reasons to choose Bicep
Bicep is the Microsoft 1st party offering for IaC deployments. It supports Generally Available (GA) and preview features for all Azure resources and allows for modular composition of resources and solution templates. The use of simplified syntax makes IaC development intuitive and the use of the Bicep extension for VSCode provides IntelliSense and syntax validation to assist with coding. Finally, Bicep is well suited for infrastructure projects and teams that don’t require management of other cloud platforms or services outside of Azure. For a more detailed read on reasons to choose Bicep, read this article from the Bicep documentation.
Reasons to choose Terraform
HashiCorp’s Terraform is an extensible 3rd party platform that can be used across multiple cloud and on-premises platforms using multiple provider plugins. It has widespread adoption due to its simplified human-readable configuration files, common functionality, and the ability to allow a project to span multiple provider spaces.
In Azure, support is provided through two primary providers called AzureRM and AzAPI respectively. The default provider for many Azure use cases is AzureRM which is co-developed between Microsoft and HashiCorp. It includes support for generally available (GA) features, while support for new and preview features might be slightly delayed following their initial release. AzAPI is developed exclusively by Microsoft and supports all preview and GA features while being more complex to use due to the more direct interaction with Azure’s APIs. While it is possible to use both providers in a single project as needed, the best practice is to standardize on a single provider as much as is reasonable.
Projects typically choose Terraform when they bridge multiple cloud infrastructure platforms or when the development team has previous experience coding in Terraform. Modern Integrated Development Environments (IDE) - such as Visual Studio Code - include extension support for Terraform features as well as additional Azure specific extensions. These extensions enable syntax validation and highlighting as well as code formatting and HashiCorp Cloud Platform (HCP) integration for HashiCorp Cloud customers. For a more detailed read on reasons to choose Terraform, read this article from the Terraform on Azure documentation.
Architecture design
Before starting the process of codifying infrastructure, it is important to develop a detailed architecture of what will be created. This should include details for:
- Organizational elements such as management groups, subscriptions, and resource groups as well as any tagging and Role Based Access (RBAC) configurations for each.
- Infrastructure services that will be created along with key configuration details like sku values, network CIDR range sizes, or other solution specific configuration.
- Any relationship between services that will be codified as part of the deployment.
- Identify inputs to your solution for designs that are intended to be used as templates.
Note
For a production grade solution, you need to
- follow the recommendations of the Cloud Adoption Framework (CAF) and have your platform and application landing zones defined, as per Azure Landing Zones (ALZ);
- follow the recommendations of the Azure Well-Architected Framework (WAF) to ensure that your solution is compliant with and integrates into your organization’s policies and standards. This includes considerations for security, identity, networking, monitoring, cost management, and governance.
Sourcing content for deployment
Once the architecture is agreed upon, it is time to plan the development of your IaC code. There are several key decision points that should be considered during this phase.
Content creation methods
The two primary methods used to create your solutions module are:
- Using base resources (“vanilla resources”) from scratch or
- Leveraging pre-created modules from the AVM library to minimize the time to value during development.
The trade-off between the two options is primarily around control vs. speed. AVM works to provide the best of both options by providing modules with opinionated and recommended practice defaults while allowing for more detailed configuration as needed. In our sample exercise we’ll be using AVM modules to demonstrate building the example solution.
AVM module type considerations
When using AVM modules for your solution, there is an additional choice that should be considered. The AVM library includes both pattern and resource module types. If your architecture includes or follows a well-known pattern then a pattern module may be the right option for you. If you determine this is the case, then search the module index for pattern modules in your chosen language to see if an option exists for your scenario. Otherwise, using resource modules from the library will be your best option.
In cases where an AVM resource or pattern module isn’t available for use, review the Bicep or Terraform provider documentation to identify how to augment AVM modules with standalone resources. If you feel that additional resource or pattern modules would be useful, you can also request the creation of a pattern or resource module by creating a module proposal issue on the AVM github repository.
Module source considerations
Once the decision has been made to use AVM modules to help accelerate solution development, a decision about where those modules will be sourced from is the next key decision point. A detailed exploration of the different sourcing options can be found in the Module Sourcing section of the Concepts page. Take a moment to review the options discussed there.
For our solution we will leverage the Public Registry option by sourcing AVM modules directly from the respective Terraform and Bicep public registries. This will avoid the need to fork copies of the modules for private use.
Subsections of Solution Development
Bicep - Solution Development
Introduction
Azure Verified Modules (AVM) for Bicep are a powerful tool that leverage the Bicep domain-specific language (DSL), industry knowledge, and an Open Source community, which altogether enable developers to quickly deploy Azure resources that follow Microsoft’s recommended practices for Azure.
In this article, we will walk through the Bicep specific considerations and recommended practices on developing your solution leveraging Azure Verified Modules. We’ll review some of the design features and trade-offs and include sample code to illustrate each discussion point.
In this tutorial, we will:
- Deploy a basic Virtual Machine architecture into Azure
- Explore recommended practices related to Bicep template development
- Demonstrate the ease with which you can deploy AVM modules
- Describe each of the development and deployment steps in detail
After completing this tutorial, you’ll have a working knowledge of:
- How to discover and add AVM modules to your Bicep template
- How to reference and use outputs across AVM modules
- Recommended practices for parameterization and structure of your Bicep file
- Configuration of AVM modules to meet Microsoft’s Well Architected Framework (WAF) principles
- How to deploy your Bicep template into an Azure subscription from your local machine
Let’s get started!
Prerequisites
You will need the following tools and components to complete this guide:
- Visual Studio Code (VS Code) to develop your solution.
- Bicep Visual Studio Code Extension to author your Bicep template and explore modules published in the Registry.
- One of the following command line tools:
- PowerShell AND Azure PowerShell
- Azure CLI to deploy your solution.
- Bicep CLI
- Azure Subscription to deploy your Bicep templates.
Before you begin, make sure you have these tools installed in your development environment.
Solution Architecture
Before we begin coding, it is important to have details about what the infrastructure architecture will include. For our example, we will be building a solution that will host a simple application on a Linux virtual machine (VM). The solution must be secure and auditable. The VM must not be accessible from the internet and its logs should be easily accessible. All azure services should utilize logging tools for auditing purposes.
Develop the Solution Code
Creating the main.bicep file
The architecture diagram shows all components needed for a successful solution deployment. Rather than building the complete solution at once, this tutorial takes an incremental approach building the Bicep file piece-by-piece and testing the deployment at each stage. This approach allows for discussion of each design decision along the way.
The development will start with core platform components: first the backend logging services (Log Analytics) and then the virtual network.
Let’s begin by creating our folder structure along with a main.bicep file. Your folder structure should be as follows:
VirtualMachineAVM_Example1/
└── main.bicepAfter you have your folder structure and main.bicep file, we can proceed with our first AVM resources!
Log Analytics
Let’s start by adding a logging service to our main.bicep since all other deployed resources will use this service for their logs.
Tip
Always begin template development by adding resources that create dependencies for other downstream services. This approach simplifies referencing these dependencies within your other modules as you develop them. For example, starting with Logging and Virtual Network services makes sense since all other services will depend on these.
The logging solution depicted in our Architecture Diagram shows we will be using a Log Analytics workspace. Let’s add that to our template! Open your main.bicep file and add the following:
Note
Always click on the “Copy to clipboard” button in the top right corner of the Code sample area in order not to have the line numbers included in the copied code.
You now have a fully functional Bicep template that will deploy a working Log Analytics workspace! If you would like to try it, run the following in your console:
Note
For keeping the example below simple, we are using the traditional deployment commands, e.g., az deployment group create or New-AzResourceGroupDeployment. However, we encourage you to look into using Deployment Stacks instead by simply replacing the previous commands with az stack group create or New-AzResourceGroupDeploymentStack as well as the other required input parameters as shown here.
Deployment Stacks allow you to deploy a Bicep file as a stack, which is a collection of resources that are deployed together. This allows you to manage the lifecycle of the stack as a single unit, making it easier to deploy, update, and now even delete resources via Bicep. You can also implement RBAC Deny Assignments on your stacks deployed resources to prevent changes to the resources or specific actions on the resources to all but an excluded list of users, groups or other principals.
Deploy with
# Log in to Azure
Connect-AzAccount
# Select your subscription
Set-AzContext -SubscriptionId '<subscriptionId>'
# Deploy a resource group
New-AzResourceGroup -Name 'avm-bicep-vmexample1' -Location '<location>'
# Invoke your deployment
New-AzResourceGroupDeployment -DeploymentName 'avm-bicep-vmexample1-deployment' -ResourceGroupName 'avm-bicep-vmexample1' -TemplateFile '/<path-to>/VirtualMachineAVM_Example1/main.bicep'# Log in to Azure
az login
# Select your subscription
az account set --subscription '<subscriptionId>'
# Deploy a resource group
az group create --name 'avm-bicep-vmexample1' --location '<location>'
# Invoke your deployment
az deployment group create --name 'avm-bicep-vmexample1-deployment' --resource-group 'avm-bicep-vmexample1' --template-file '/<path-to>/VirtualMachineAVM_Example1/main.bicep'The above commands will log you in to your Azure subscription, select a subscription to use, create a resource group, then deploy the main.bicep template to your resource group.
AVM Makes the deployment of Azure resources incredibly easy. Many of the parameters you would normally be required to define are taken care of by the AVM module itself. In fact, the location parameter is not even needed in your template—when left blank, by default, all AVM modules will deploy to the location in which your target Resource Group exists.
Now we have a Log Analytics workspace in our resource group which doesn’t do a whole lot of good on its own. Let’s take our template a step further by adding a Virtual Network that integrates with the Log Analytics workspace.
Virtual Network
We will now add a Virtual Network to our main.bicep file. This VNet will contain subnets and Network Security Groups (NSGs) for any of the resources we deploy that require IP addresses.
In your main.bicep file, add the following:
Again, the Virtual Network AVM module requires only two things: a name and an addressPrefixes parameter.
Configure Diagnostics Settings
There is an additional parameter available in most AVM modules named diagnosticSettings. This parameter allows you to configure your resource to send its logs to any suitable logging service. In our case, we are using a Log Analytics workspace.
Let’s update our main.bicep file to have our VNet send all of its logging data to our Log Analytics workspace:
Notice how the diagnosticsSettings parameter needs a workspaceResourceId? All you need to do is add a reference to the built-in logAnalyticsWorkspaceId output of the logAnalyticsWorkspace AVM module. That’s it! Our VNet now has integrated its logging with our Log Analytics workspace. All AVM modules come with a set of built-in outputs that can be easily referenced by other modules within your template.
Info
All AVM modules have built-in outputs which can be referenced using the <moduleName>.outputs.<outputName> syntax.
When using plain Bicep, many of these outputs require multiple lines of code or knowledge of the correct object ID references to get at the desired output. AVM modules do much of this heavy lifting for you by taking care of these complex tasks within the module itself, then exposing them to you through the module’s outputs. Find out more about Bicep Outputs.
Add a Subnet and NAT Gateway
We can’t use a Virtual Network without subnets, so let’s add a subnet next. According to our Architecture, we will have three subnets: one for the Virtual Machine, one for the Bastion host, and one for Private Endpoints. We can start with the VM subnet for now. While we’re at it, let’s also add the NAT Gateway, the NAT Gateway’s Public IP, the attach the NAT Gateway to the VM subnet.
Add the following to your main.bicep:
The modification adds a subnets property to our virtualNetwork module. The AVM network/virtual-network module supports the creation of subnets directly within the module itself. We can also link our NAT Gateway directly to the subnet within this submodule.
A nice feature within Bicep are the various functions available. We use the cidrSubnet() function to declare CIDR blocks without having to calculate them on your own.
Switch to Parameters and Variables
See how we are reusing the same CIDR block 10.0.0.0/16 in multiple locations? You may have noticed we are defining the same location in two different spots as well. We’re now at a point in the development where we should leverage one of our first recommended practices: using parameters and variables!
Tip
Use Bicep variables to define values that will be constant and reused with your template; use parameters anywhere you may need a modifiable value.
Let’s enhance the template by adding variables for the CIDR block and prefix, then use a location parameter with a default value. We’ll then reference those in the module:
We now have a good basis for the infrastructure to be utilized by the rest of the resources in our Architecture. We will come back to our networking in a future step, once we are ready to create some Network Security Groups. For now, let’s move on to other modules.
Key Vault
Key Vaults are one of the key components in most Azure architectures as they create a place where you can save and reference secrets in a secure manner (“secrets” in the general sense, as opposed to the secret object type in Key Vaults). The Key Vault AVM module makes it very simple to store secrets generated in your template. In this tutorial, we will use one of the most secure methods of storing and retrieving secrets by leveraging this Key Vault in our Bicep template.
The first step is easy: add the Key Vault AVM module to our main.bicep file. In addition, let’s also ensure it’s hooked into our Log Analytics workspace (we will do this for every new module from here on out).
The name of the Key Vault we will deploy uses the uniqueString() Bicep function. Key Vault names must be globally unique. We will therefore deviate from our standard naming convention thus far and make an exception for the Key Vault. Note how we are still adding a suffix to the Key Vault name, so its name remains recognizable; you can use a combination of concatenating unique strings, prefixes, or suffixes to follow your own naming standard preferences.
When we generate our unique string, we will pass in the resourceGroup().id as the seed for the uniqueString() function so that every time you deploy this main.bicep to the same resource group, it will use the same randomly generated name for your Key Vault (since resourceGroup().id will be the same).
Tip
Bicep has many built-in functions available. We used two here: uniqueString() and resourceGroup(). The resourceGroup(), subscription(), and deployment() functions are very useful when seeding uniqueString() or guid() functions. Just be cautious about name length limitations for each Azure service! Visit this page to learn more about Bicep functions.
We will use this Key Vault later on when we create a VM and need to store its password. Now that we have it, a Virtual Network, Subnet, and Log Analytics prepared, we should have everything we need to deploy a Virtual Machine!
Info
In the future, we will update this guide to show how to generate and store a certificate in the Key Vault, then use that certificate to authenticate into the Virtual Machine.
Virtual Machine
Warning
The AVM Virtual Machine module enables the EncryptionAtHost feature by default. You must enable this feature within your Azure subscription successfully deploy this example code. To do so, run the following:
Deploy with
# Wait a few minutes after running the command to allow it to propagate
Register-AzProviderFeature -FeatureName "EncryptionAtHost" -ProviderNamespace "Microsoft.Compute"az feature register --namespace Microsoft.Compute --name EncryptionAtHost
# Propagate the change
az provider register --namespace Microsoft.ComputeFor our Virtual Machine (VM) deployment, we need to add the following to our main.bicep file:
The VM module is one of the more complex modules in AVM—behind the scenes, it takes care of a lot of heavy lifting that, without AVM, would require multiple Bicep resources to be deployed and referenced.
For example, look at the nicConfigurations parameter: normally, you would need to deploy a separate NIC resource, which itself also requires an IP resource, then attach them to each other, and finally, attach them all to your VM.
With the AVM VM module, the nicConfigurations parameter accepts an object, allowing you to create any number of NICs to attach to your VM from within the VM resource deployment itself. It handles all the naming, creation of other necessary dependencies, and attaches them all together, so you don’t have to. The osDisk parameter is similar, though slightly less complex. There are many more parameters within the VM module that you can leverage if needed, that share a similar ease-of-use.
Since this is the real highlight of our main.bicep file, we need to take a closer look at some of the other changes that were made.
VM Admin Password Parameter
First, we added a new parameter. The value of this will be provided when the
main.biceptemplate is deployed. We don’t want any passwords stored as text in code; for our purposes, the safest way to do this is to prompt the end user for the password at the time of deployment.Warning
The supplied password must be between 6-72 characters long and must satisfy at least 3 of password complexity requirements from the following: Contains an uppercase character; Contains a lowercase character; Contains a numeric digit; Contains a special character. Control characters are not allowed
Also note how we are using the
@secure()decorator on the password parameter. This will ensure the value of the password is never displayed in any of the deployment logs or in Azure. We have also added the@description()decorator and started the description with “Required.” It’s a good habit and recommended practice to document your parameters in Bicep. This will ensure that VS Code’s built-in Bicep linter can provide end-users insightful information when deploying your Bicep templates.Info
Always use the
@secure()decorator when creating a parameter that will hold sensitive data!Add the VM Admin Password to Key Vault
The next thing we have done is save the value of our
vmAdminPassparameter to our Key Vault. We have done this by adding asecretsparameter to the Key Vault module. Adding secrets to Key Vaults is very simple when using the AVM module.By adding our password to the Key Vault, it will ensure that we never lose the password and that it is stored securely. As long as a user has appropriate permissions on the vault, the password can be fetched easily.
Reference the VM Subnet
1 nicConfigurations: [ 2 { 3 ipConfigurations: [ 4 { 5 name: 'ipconfig01' 6 subnetResourceId: virtualNetwork.outputs.subnetResourceIds[0] // VMSubnet 7 } 8 ] 9 nicSuffix: '-nic-01' 10 } 11 ]Here, we reference another built-in output, this time from the AVM Virtual Network module. This example shows how to use an output that is part of an array. When the Virtual Network module creates subnets, it automatically creates a set of pre-defined outputs for them, one of which is an array that contains each subnet’s
subnetResourceId. Our VM Subnet was the first one created which is position[0]in the array.Other AVM modules may make use of arrays to store outputs. If you are unsure what type of outputs a module provides, you can always reference the Outputs section of each module’s README.md.
Storage Account
The last major component we need to add is a Storage Account. Because this Storage Account will be used as a backend storage to hold blobs for the hypothetical application that runs on our VM, we’ll also create a blob container within it using the same AVM Storage Account module.
We now have all the major components of our Architecture diagram built!
The last steps we need to take to meet our requirements is to ensure our networking resources are secure and that we are using least privileged access by leveraging Role-Based Access Control (RBAC). Let’s get to it!
Network Security Groups
We’ll add a Network Security Group (NSG) to our VM subnet. This will act as a layer 3 and layer 4 firewall for networked resources. This implementation includes an appropriate inbound rule to allow SSH traffic from the Bastion host:
Disable Public Access to Storage Account
Since the Storage Account serves as a backend resource exclusively for the Virtual Machine, it will be secured as much as possible. This involves adding a Private Endpoint and disabling public internet access. AVM makes creation and assignment of Private Endpoints to resources incredibly easy. Take a look:
This implementation adds a dedicated subnet for Private Endpoints following the recommended practice of isolating Private Endpoints in their own subnet.
The addition of just a few lines of code in the privateEndpoints parameter handles the complex tasks of creating the Private Endpoint, associating it with the VNet, and attaching it to the resource. AVM drastically simplifies the creation of Private Endpoints for just about every Azure Resource that supports them.
The implementation also disables all public network connectivity to the Storage Account, ensuring it only accepts traffic via the Private Endpoint.
Finally, a Private DNS zone is added and linked to the VNet, enabling the VM to resolve the Private IP address associated with the Storage Account.
Bastion
To securely access the Virtual Machine without exposing its SSH port to the public internet, we’ll create an Azure Bastion host. The Bastion Host requires a subnet with the exact name AzureBastionSubnet which cannot contain anything other than Bastion Hosts.
This simple addition of the bastion-host AVM module completes the secure access component of our architecture. You can now access the Virtual Machine by way of the Bastion Host in the Azure Portal.
Role-Based Access Control
To complete our solution, we have one final task: to apply Role-Based Access Control (RBAC) restrictions on our services, namely the Key Vault and Storage Account. The goal is to explicitly allow only the Virtual Machine to have Create, Read, Update, or Delete (CRUD) permissions on these two services.
This is accomplished by enabling a System-assigned Managed Identity on the Virtual Machine, then granting the VM’s Managed Identity appropriate permissions on the Storage Account and Key Vault:
Info
The Azure Subscription owner will have CRUD permissions for the Storage Account but not for the Key Vault. The Key Vault requires explicit RBAC permissions assigned to a user to grant them access: Provide access to Key Vaults using RBAC. Important!: at this point, you will only be able to access the Storage Account from the Bastion Host. Remember, public internet access has been disabled!
The RBAC policies have been successfully applied using a System-assigned Managed Identity on the Virtual Machine. This identity has been granted permissions on both the Key Vault and Storage Account. Now the VM can read secrets from the Key Vault and Read, Create, or Delete blobs in the Storage Account.
In a real production environment, the principle of least privileged access should be applied, providing only the exact permissions each service needs to carry out its functions. Learn more about Microsoft’s recommendations for identity and access management.
Conclusion
In this tutorial, we’ve explored how to leverage Azure Verified Modules (AVM) to build a secure, well-architected solution in Azure. AVM modules significantly simplify the deployment of Azure resources by abstracting away much of the complexity involved in configuring individual resources.
Your final, deployable Bicep template file should now look like this:
AVM modules provide several key advantages over writing raw Bicep templates:
- Simplified Resource Configuration: AVM modules handle much of the complex configuration work behind the scenes
- Built-in Recommended Practices: The modules implement many of Microsoft’s recommended practices by default
- Consistent Outputs: Each module exposes a consistent set of outputs that can be easily referenced
- Reduced Boilerplate Code: What would normally require hundreds of lines of Bicep code can be accomplished in a fraction of the space
As you continue your journey with Azure and AVM, remember that this approach can be applied to more complex architectures as well. The modular nature of AVM allows you to mix and match components to build solutions that meet your specific needs while adhering to Microsoft’s Well-Architected Framework.
By using AVM modules as building blocks, you can focus more on your solution architecture and less on the intricacies of individual resource configurations, ultimately leading to faster development cycles and more reliable deployments.
Clean up your environment
When you are ready, you can remove the infrastructure deployed in this example. Key Vaults are set to a soft-delete state so you will also need to purge the one we created in order to fully delete it. The following commands will remove all resources created by your deployment:
Clean up with
# Delete the resource group
Remove-AzResourceGroup -Name "avm-bicep-vmexample1" -Force
# Purge the Key Vault
Remove-AzKeyVault -VaultName "<keyVaultName>" -Location "<location>" -InRemovedState -Force# Delete the resource group
az group delete --name 'avm-bicep-vmexample1' --yes --no-wait
# Purge the Key Vault
az keyvault purge --name '<keyVaultName>' --no-waitCongratulations, you have successfully leveraged AVM Bicep modules to deploy resources in Azure!
Tip
We welcome your contributions and feedback to help us improve the AVM modules and the overall experience for the community!
Terraform - Solution Development
Introduction
Azure Verified Modules (AVM) for Terraform are a powerful tool that leverage the Terraform domain-specific language (DSL), industry knowledge, and an Open Source community, which altogether enable developers to quickly deploy Azure resources that follow Microsoft’s recommended practices for Azure.
In this article, we will walk through the Terraform specific considerations and recommended practices on developing your solution leveraging Azure Verified Modules. We’ll review some of the design features and trade-offs and include sample code to illustrate each discussion point.
Prerequisites
You will need the following tools and components to complete this guide:
- Visual Studio Code (VS Code) to develop your solution.
- Terraform CLI to deploy your Terraform modules. Make sure you have a recent version installed.
- Azure CLI to authenticate to Azure.
- Azure Subscription to deploy your resources.
Before you begin, ensure you have these tools installed in your development environment.
Planning
Good module development should start with a good plan. Let’s first review the architecture and module design prior to developing our solution.
Solution Architecture
Before we begin coding, it is important to have details about what the infrastructure architecture will include. For our example, we will be building a solution that will host a simple application on a Linux virtual machine (VM).
In our design, the resource group for our solution will require appropriate tagging to comply with our corporate standards. Resources that support Diagnostic Settings must also send metric data to a Log Analytics workspace, so that the infrastructure support teams can get metric telemetry. The virtual machine will require outbound internet access to allow the application to properly function. A Key Vault will be included to store any secrets and key artifacts, and we will include a Bastion instance to allow support personnel to access the virtual machine if needed. Finally, the VM is intended to run without interaction, so we will auto-generate an SSH private key and store it in the Key Vault for the rare event of someone needing to log into the VM.
Based on this narrative, we will create the following resources:
- A resource group to contain all the resources with tagging
- A random string resource for use in resources with global naming (Key Vault)
- A Log Analytics workspace for diagnostic data
- A Key Vault with:
- Role-Based Access Control (RBAC) to allow data access
- Logging to the Log Analytics workspace
- A virtual network with:
- A virtual machine subnet
- A Bastion subnet
- Network Security Group on the VM subnet allowing SSH traffic
- Logging to the Log Analytics workspace
- A NAT Gateway for enabling outbound internet access
- Associated to the virtual machine subnet
- A Bastion service for secure remote access to the Virtual Machine
- Logging to the Log Analytics workspace
- A virtual machine resource with
- A single private IPv4 interface attached to the VM subnet
- A randomly generated admin account private key stored in the Key Vault
- Metrics sent to the log Analytics workspace
Solution template (root module) design
Since our solution template (root module) is intended to be deployed multiple times, we want to develop it in a way that provides flexibility while minimizing the amount of input necessary to deploy the solution. For these reasons, we will create our module with a small set of variables that allow for deployment differentiation while still populating solution-specific defaults to minimize input. We will also separate our content into variables.tf, outputs.tf, terraform.tf, and main.tf files to simplify future maintenance.
Based on this, our file system will take the following structure:
- Module Directory
terraform.tf- This file holds the provider definitions and versions.variables.tf- This file contains the input variable definitions and defaults.outputs.tf- This file contains the outputs and their descriptions for use by any external modules calling this root module.main.tf- This file contains the core module code for creating the solutions infrastructure.development.tfvars- This file will contain the inputs for the instance of the module that is being deployed. Content in this file will vary from instance to instance.
Note
Terraform will merge content from any file ending in a .tf extension in the module folder to create the full module content. Because of this, using different files is not required. We encourage file separation to allow for organizing code in a way that makes it easier to maintain. While the naming structure we’ve used is common, there are many other valid file naming and organization options that can be used.
In our example, we will use the following variables as inputs to allow for customization:
location- The location where our infrastructure will be deployed.name_prefix- This will be used to preface all of the resource naming.virtual_network_prefix- This will be used to ensure IP uniqueness for the deployment.tags- The custom tags to use for each deployment.
Finally, we will export the following outputs:
resource_group_name- This will allow for finding this deployment if there are multiples.virtual_machine_name- This can be used to find and login to the vm if needed.
Identifying AVM modules that match our solution
Now that we’ve determined our architecture and module configurations, we need to see what AVM modules exist for use in our solution. To do this, we will open the AVM Terraform pattern module index and check if there are any existing pattern modules that match our requirement. In this case, no pattern modules fit our needs. If this was a common pattern, we could open an issue on the AVM github repository to get assistance from the AVM project to create a pattern module matching our requirements. Since our architecture isn’t common, we’ll continue to the next step.
When a pattern module fitting our needs doesn’t exist for a solution, leveraging AVM resource modules to build our own solution is the next best option. Review the AVM Terraform published resource module index for each of the resource types included in your architecture. For each AVM module, capture a link to the module to allow for a review of the documentation details on the Terraform Registry website.
Note
Some of the published pattern modules cover multi-resource configurations that can sometimes be interpreted as a single resource. Be sure to check the pattern index for groups of resources that may be part of your architecture and that don’t exist in the resource module index. (e.g., Virtual WAN)
For our sample architecture, we have the following AVM resource modules at our disposal. Click on each module to explore its documentation on the Terraform Registry.
- Resource Group
- Log Analytics Workspace
- Key Vault
- Virtual Network
- Network Security Group
- NAT Gateway
- Bastion
- Virtual Machine
Develop the Solution Code
We can now begin coding our solution. We will create each element individually, to allow us to test our deployment as we build it out. This will also allow us to correct any bugs incrementally, so that we aren’t troubleshooting a large number of resources at the end.
Creating the terraform.tf file
Let’s begin by configuring the provider details necessary to build our solution. Since this is a root module, we want to include any provider and Terraform version constraints for this module. We’ll periodically come back and add any needed additional providers if our design includes a resource from a new provider.
Open up your development IDE (Visual studio code in our example) and create a file named terraform.tf in your root directory.
Add the following code to your terraform.tf file:
Note
Always click on the “Copy to clipboard” button in the top right corner of the Code sample area in order not to have the line numbers included in the copied code.
This specifies that the required Terraform binary version to run your module can be any version between 1.9 and 2.0. This is a good compromise for allowing a range of binary versions while also ensuring support for any required features that are used as part of the module. This can include things like newly introduced functions or support for new key words.
Since we are developing our solution incrementally, we should validate our code. To do this, we will take the following steps:
- Open up a terminal window if it is not already open. In some IDE’s this can be done as a function of the IDE.
- Change directory to the module directory by typing
cdand then the path to the module. As an example, if the module directory was namedexamplewe would runcd example. - Run
terraform initto initialize your provider file.
You should now see a message indicating that Terraform has been successfully initialized. This indicates that our code is error free and we can continue on. If you get errors, examine the provider syntax for typos, missing quotes, or missing brackets.
Creating a variables.tf file
Because our module is intended to be reusable, we want to provide the capability to customize each module call with those items that will differ between them. This is done by using variables to accept inputs into the module. We’ll define these inputs in a separate file named variables.tf.
Go back to the IDE, and create a file named variables.tf in the working directory.
Add the following code to your variables.tf file to configure the inputs for our example:
Note
Note that each variable definition includes a type definition to guide module users on how to properly define an input. Also note that it is possible to set a default value. This allows module consumers to avoid setting a value if they find the default to be acceptable.
We should now test the new content we’ve created for our module. To do this, first re-run terraform init on your command line. Note that nothing has changed and the initialization completes successfully. Since we now have module content, we will attempt to run the plan as the next step of the workflow.
Type terraform plan on your command line. Note that it now asks for us to provide a value for the var.virtual_network_cidr variable. This is because we don’t provide a default value for that input so Terraform must have a valid input before it can continue. Type 10.0.0.0/22 into the input and press enter to allow the plan to complete. You should now see a message indicating that Your infrastructure matches the configuration and that no changes are needed.
Creating a development.tfvars file
There are multiple ways to provide input to the module we’re creating. We will create a tfvars file that can be supplied during plan and apply stages to minimize the need for manual input. tfvars files are a nice way to document inputs as well as allow for deploying different versions of your module. This is useful if you have a pipeline where infrastructure code is deployed first for development, and then is deployed for QA, staging, or production with different input values.
In your IDE, create a new file named development.tfvars in your working directory.
Now add the following content to your development.tfvars file.
Note
Note that each variable has a value defined. Although, only inputs without default values are required, we include values for all of the inputs for clarity. Consider doing this in your environments so that someone looking at the tfvars files has a full picture of what values are being set.
Re-run the terraform apply, but this time, reference the .tfvars file by using the following command: terraform plan -var-file=development.tfvars. You should get a successful completion without needing to manually provide inputs.
Creating the main.tf file
Now that we’ve created the supporting files, we can start building the actual infrastructure code in our main file. We will add one AVM resource module at a time so that we can test each as we implement them.
Return to your IDE and create a new file named main.tf.
Add a resource group
In Azure, we need a resource group to hold any infrastructure resources we create. This is a simple resource that typically wouldn’t require an AVM module, but we’ll include the AVM module so we can take advantage of the Role-Based Access Control (RBAC) interface if we need to restrict access to the resource group in future versions.
First, let’s visit the Terraform registry documentation page for the resource group and explore several key sections.
- Note the
Provision Instructionsbox on the right-hand side of the page. This contains the module source and version details which allows us to copy the latest version syntax without needing to type everything ourselves. - Now review the
Readmetab in the middle of the page. It contains details about all required and optional inputs, resources that are created with the module, and any outputs that are defined. If you want to explore any of these items in detail, each element has a tab that you can review as needed. - Finally, in the middle of the page, there is a drop-down menu named
Examplesthat contains functioning examples for the AVM module. These showcase a good example of using copy/paste to bootstrap module code and then modify it for your specific purpose.
Now that we’ve explored the registry content, let’s add a resource group to our module.
First, copy the content from the Provision Instructions box into our main.tf file.
On the modules documentation page, go to the inputs tab. Review the Required Inputs tab. These are the values that don’t have defaults and are the minimum required values to deploy the module. There are additional inputs in the Optional Inputs section that can be used to configure additional module functionality. Review these inputs and determine which values you would like to define in your AVM module call.
Now, replace the # insert the 2 required variables here comment with the following code to define the module inputs. Our main.tf code should look like the following:
Note
Note how we’ve used the prefix variable and Terraform interpolation syntax to dynamically name the resource group. This allows for module customization and re-use. Also note that even though we chose to use the default module name of avm-res-resources-resourcegroup, we could modify the name of the module if needed.
After saving the file, we want to test our new content. To do this, return to the command line and first run terraform init. Notice how Terraform has downloaded the module code, as well as providers that the module requires. In this case, you can see the azurerm, random, and modtm providers were downloaded.
Let’s now deploy our resource group. First, let’s run a plan operation to review what will be created. Type terraform plan -var-file=development.tfvars and press enter to initiate the plan.
Add the features block
Notice that we get an error indicating that we are Missing required argument and that for the azurerm provider, we need to provide a features argument. The addition of the resource group AVM resource requires that the azurerm provider be installed to provision resources in our module. This provider requires a features block in its provider definition that is missing in our configuration.
Return to the terraform.tf file and add the following content to it. Note how the features block is currently empty. If we needed to activate any feature flags in our module, we could add them here.
Re-run terraform plan -var-file=development.tfvars now that we have updated the features block.
Set the subscription ID
Note that we once again get an error. This time, the error indicates that subscription_id is a required provider property for plan/apply operations. This is a change that was introduced as part of the version 4 release of the AzureRM provider. We need to supply the ID of the deployment subscription where our resources will be created.
First, we need to get the subscription ID value. We will use the portal for this exercise, but using the Azure CLI, PowerShell, or the resource graph will also work to retrieve this value.
- Open the Azure portal.
- Enter
Subscriptionsin the search field at the top middle of the page. - Select
Subscriptionsfrom the services menu in the search drop-down. - Select the subscription you wish to deploy to, from the list of subscriptions.
- Find the
Subscription IDfield on the overview page and click the copy button to copy it to the clipboard.
Secondly, we need to update Terraform so that it can use the subscription ID. There are multiple ways to provide a subscription ID to the provider including adding it to the features block or using environment variables. For this scenario we’ll use environment variables to set the values so that we don’t have to re-enter them on each run. This also keeps us from storing the subscription ID in our code since it is considered a sensitive value. Select a command from the list below based on your operating system.
- (Linux/MacOS) - Run the following command with your subscription ID:
export ARM_SUBSCRIPTION_ID=<your ID here> - (Windows) - Run the following command with your subscription ID:
set ARM_SUBSCRIPTION_ID=<your ID here>
Finally, we should now be able to complete our plan operation by re-running terraform plan -var-file=development.tfvars. Note that the plan will create three resources, two for telemetry and one for the resource group.
Deploy the resource group
We can complete testing by implementing the resource group. Run terraform apply -var-file=development.tfvars and type yes and press enter when prompted to accept the changes. Terraform will create the resource group and notify you with a Apply complete message and a summary of the resources that were added, changed, and destroyed.
Deploy the Log Analytics Workspace
We can now continue by adding the Log Analytics Workspace to our main.tf file. We will follow a workflow similar to what we did with the resource group.
- Browse to the AVM Log Analytics Workspace module page in the Terraform Registry.
- Copy the module content from the
Provision Instructionsportion of the page into themain.tffile.
This time, instead of manually supplying module inputs, we will copy module content from one of the examples to minimize the amount of typing required. In most examples, the AVM module call is located at the bottom of the example.
- Navigate to the
Examplesdrop-down menu in the documentation and select thedefaultexample from the menu. You will see a fully functioning example code which includes the module and any supporting resources. Since we only care about the workspace resource from this example, we can scroll to the bottom of the code block and find themodule "log_analytics_workspace"line. - Copy the content between the module brackets with the exception of the line defining the module source. Because these examples are part of the testing methodology for the module, they use a dot reference value (
../..) for the module source value which will not work in our module call. To work around this, we copied those values from the provision instructions section of the module documentation in a previous step. - Update the location and resource group name values to reference outputs from the resource group module. Using implicit references such as these allow Terraform to determine the order in which resources should be built.
- Update the name field using the prefix variable to allow for customization using a similar pattern to what we used on the resource group.
The Log Analytics module content should look like the following code block. For simplicity, you can also copy this directly to avoid multiple copy/paste actions.
Again, we will need to run terraform init to allow Terraform to initialize a copy of the AVM Log Analytics module.
Now, we can deploy the Log Analytics workspace by running terraform apply -var-file=development.tfvars, typing yes and pressing enter. Note that Terraform will only create the new Log Analytics resources since the resource group already exists. This is one of the key benefits of deploying using Infrastructure as Code (IAC) tools like Terraform.
Note
Note that we ran the terraform apply command without first running terraform plan. Because terraform apply runs a plan before prompting for the apply, we opted to shorten the instructions by skipping the explicit plan step. If you are testing in a live environment, you may want to run the plan step and save the plan as part of your governance or change control processes.
Deploy the Azure Key Vault
Our solution calls for a simple Key Vault implementation to store virtual machine secrets. We’ll follow the same workflow for deploying the Key Vault as we used for the previous resource group and Log Analytics workspace resources. However, since Key Vaults require data roles to manage secrets and keys, we will need to use the RBAC interface and a data resource to configure Role-Based Access Control (RBAC) during the deployment.
Note
For this exercise, we will provision the deployment user with data rights on the Key Vault. In your environment, you will likely want to either provide additional roles as inputs or statically assign users, or groups to the Key Vault data roles. For simplicity we also set the Key Vault to have public access enabled due to us not being able to dictate a private deployment environment. In your environment where your deployment machine will be on a private network it is recommended to restrict public access for the Key Vault.
Before we implement the AVM module for the Key Vault, we want to use a data resource to read the client details about the user context of the current Terraform deployment.
Add the following line to your main.tf file and save it.
Key vaults use a global namespace which means that we will also need to add a randomization resource to allow us to randomize the name to avoid any potential name intersection issues with other Key Vault deployments. We will use Terraform’s random provider to generate the random string which we will append to the Key Vault name. Add the following code to your main module to create the random_string resource we will use for naming.
Now we can continue with adding the AVM Key Vault module to our solution.
- Browse to the AVM Key Vault resource module page in the Terraform Registry.
- Copy the module content from the
Provision Instructionsportion of the page into themain.tffile. - This time, we’re going to select relevant content from the
Create secretexample to fill out our module. - Copy the
name,location,enable_telemetry,resource_group_name,tenant_id, androle_assignmentsvalue content from the example and paste it into the new Key Vault module in your solution. - Update the name value to be
"${var.prefix}-kv-${random_string.name_suffix.result}" - Update the
locationandresource_group_namevalues to the same implicit resource group module references we used in the Log Analytics workspace. - Set the
enable_telemetryvalue to true. - Leave the
tenant_idandrole_assignmentsvalues to the same values that are in the example.
Our architecture calls for us to include a diagnostic settings configuration for each resource that supports it. We’ll use the diagnostic-settings example to copy this content.
- Return to the documentation page and select the
diagnostic-settingsoption from the examples drop-down. - Locate the Key Vault resource in the example’s code block and copy the
diagnostic_settingsvalue and paste it into the Key Vault module block we’re building inmain.tf. - Update the name value to use our prefix variable to allow for name customization.
- Update the
workspace_resource_idvalue to be an implicit reference to the output from the previously implemented Log Analytics module (module.avm-res-operationalinsights-workspace.resource_idin our code).
Finally, we will allow public access, so that our deployer machine can add secrets to the Key Vault. If your environment doesn’t allow public access for Key Vault deployments, locate the public IP address of your deployer machine (this may be an external NAT IP for your network) and add it to the network_acls.ip_rules list value using CIDR notation.
- Set the
network_aclsinput tonullin your module block for the Key Vault.
Your Key Vault module definition should now look like the following:
Note
One of the core values of AVM is the standard configuration for interfaces across modules. The Role Assignments interface we used as part of the Key Vault deployment is a good example of this.
Continue the incremental testing of your module by running another terraform init and terraform apply -var-file=development.tfvars sequence.
Deploy the NAT Gateway
Our architecture calls for a NAT Gateway to allow virtual machines to access the internet. We will use the NAT Gateway resource_id output in future modules to link the virtual machine subnet.
- Browse to the AVM NAT Gateway resource module page in the Terraform Registry.
- Copy the module definition and source from the
Provision Instructionscard from the module main page. - Copy the remaining module content from the
defaultexample excluding the subnet associations map, as we will do the association when we build the vnet. - Update the
locationandresource_group_nameusing implicit references from our resource group module. - Then update each of the name values to use the
name_prefixvariables.
Review the following code to see each of these changes.
Continue the incremental testing of your module by running another terraform init and terraform apply -var-file=development.tfvars sequence.
Deploy the Network Security Group
Our architecture calls for a Network Security Group (NSG) allowing SSH access to the virtual machine subnet. We will use the NSG AVM resource module to accomplish this task.
- Browse to the AVM Network Security Group resource module page in the Terraform Registry.
- Copy the module definition and source from the
Provision Instructionscard from the module main page. - Copy the remaining module content from the
example_with_NSG_ruleexample. - Update the
locationandresource_group_nameusing implicit references from our resource group module. - Update the name value using the
name_prefixvariable interpolation as we did with the other modules. - Copy the map entry labeled
rule02from the localsnsg_rulesmap and paste it between two curly braces to create thesecurity_rulesattribute in the NSG module we’re building. - Make the following updates to the rule details:
- Rename the map key to
"rule01"from"rule02". - Update the name to use the var.prefix interpolation and SSH to describe the rule.
- Update the
destination_port_rangeslist to be["22"].
- Rename the map key to
Upon completion the code for the NSG module should be as follows:
Continue the incremental testing of your module by running another terraform init and terraform apply -var-file=development.tfvars sequence.
Deploy the Virtual Network
We can now continue the build-out of our architecture by configuring the virtual network (vnet) deployment. This will follow a similar pattern as the previous resource modules, but this time, we will also add some network functions to help us customize the subnet configurations.
- Browse to the AVM Virtual Network resource module page in the Terraform Registry.
- Copy the module definition and source from the
Provision Instructionscard from the module main page. - After looking through the examples, this time, we’ll use the
completeexample as a source to copy our content. - Copy the
resource_group_name,location,name, andaddress_spacelines and replace their values with our deployment specific variables or module references. - We’ll copy the
subnetsmap and duplicate thesubnet0map for each subnet. - Now we will update the map key and
namevalues for each subnet so that they are unique. - Then we’ll use the
cidrsubnetfunction to dynamically generate the CIDR range for each subnet. You can explore the function documentation for more details on how it can be used. - We will also populate the
nat_gatewayobject onsubnet0with theresource_idoutput from our NAT Gateway module. - To configure the NSG on the VM subnet we need to link it. Add a
network_security_groupattribute to thesubnet0definition and replace the value with theresource_idoutput from the NSG module. - Finally, we’ll copy the diagnostic settings from the example and update the implicit references to point to our previously deployed Log Analytics workspace.
After making these changes our virtual network module call code will be as follows:
Note
Note how the Log Analytics workspace reference ends in resource_id. Each AVM module is required to export its Azure resource ID with the resource_id name to allow for consistent references.
Continue the incremental testing of your module by running another terraform init and terraform apply -var-file=development.tfvars sequence.
Deploy the Bastion service
We want to allow for secure remote access to the virtual machine for configuration and troubleshooting tasks. We’ll use Azure Bastion to accomplish this objective following a similar workflow to our other resources.
- Browse to the AVM Bastion resource module page in the Terraform Registry.
- Copy the module definition and source from the
Provision Instructionscard from the module main page. - Copy the remaining module content from the
Simple Deploymentexample. - Update the
locationandresource_group_nameusing implicit references from our resource group module. - Update the name value using the
name_prefixvariable interpolation as we did with the other modules. - Finally, update the
subnet_idvalue to include an implicit reference to thebastionkeyed subnet from our virtual network module.
Our architecture calls for diagnostic settings to be configured on the Azure Bastion resource. In this case, there aren’t any examples that include this configuration. However, since the diagnostic settings interface is one of the standard interfaces in Azure Verified Modules, we can just copy the interface definition from our virtual network module.
- Locate the virtual network module and copy the
diagnostic_settingsvalue from it. - Paste the
diagnostic_settingsvalue into the code for our Bastion module. - Update the diagnostic setting’s name value from vnet to Bastion.
The new code we added for the Bastion resource will be as follows:
Note
Pay attention to the subnet_id syntax. In the virtual network module, the subnets are created as a sub-module allowing us to reference each of them using the map key that was defined in the subnets input. Again, we see the consistent output naming with the resource_id output for the sub-module.
Continue the incremental testing of your module by running another terraform init and terraform apply -var-file=development.tfvars sequence.
Deploy the virtual machine
The final step in our deployment will be our application virtual machine. We’ve had good success with our workflow so far, so we’ll use it for this step as well.
- Browse to the AVM Virtual Machine resource module page in the Terraform Registry.
- Copy the module definition and source from the
Provision Instructionscard from the module main page. - Copy the remaining module content from the
linux_defaultexample. - Update the
locationandresource_group_nameusing implicit references from our resource group module. - To be compliant with Well Architected Framework guidance we encourage defining a zone if your region supports it. Update the zone input to 1.
- Update the sku_size input to “Standard_D2s_v5”.
- Update the name values using the
name_prefixvariable interpolation as we did with the other modules and include the output from therandom_string.name_suffixresource to add uniqueness. - Set the
account_credentials.key_vault_configuration.resource_idvalue to reference theresource_idoutput from the Key Vault module. - Update the
private_ip_subnet_resource_idvalue to an implicit reference to thesubnet0subnet output from the virtual network module.
Because the default Linux example doesn’t include diagnostic settings, we need to add that content in a different way. Since the diagnostic settings interface has a standard schema, we can copy the diagnostic_settings input from our virtual network module.
- Locate the virtual network module in your code and copy the
diagnostic_settingsmap from it. - Paste the
diagnostic_settingscontent into your virtual machine module code. - Update the
namevalue to reflect that it applies to the virtual machine.
The new code we added for the virtual machine resource will be as follows:
Continue the incremental testing of your module by running another terraform init and terraform apply -var-file=development.tfvars sequence.
Creating the outputs.tf file
The final piece of our module is to export any values that may need to be consumed by module users. From our architecture, we’ll export the resource group name and the virtual machine resource name.
- Create an
outputs.tffile in your IDE. - Create an output named
resource_group_nameand set the value to an implicit reference to the resource group modules name output. Include a brief description for the output. - Create an output named
virtual_machine_nameand set the value to an implicit reference to the virtual machine module’s name output. Include a brief description for the output.
The new code we added for the outputs will be as follows:
Because no new modules were created, we don’t need to run terraform init to test this change. Run terraform apply -var-file=development.tfvars to see the new outputs that have been created.
Update the terraform.tf file
It is a recommended practice to define the required versions of the providers for your module to ensure consistent behavior when it is being run. In this case we are going to be slightly permissive and allow increases in minor and patch versions to fluctuate, since those are not supposed to include breaking changes. In a production environment, you would likely want to pin on a specific version to guarantee behavior.
- Run
terraform initto review the providers and versions that are currently installed. - Update your
terraform.tffile’s required providers field for each provider listed in the downloaded providers.
The updated code we added for the providers in the terraform.tf file will be as follows:
Conclusion
Congratulations on successfully implementing a solution using Azure Verified Modules! You were able to build out our sample architecture using module documentation and taking advantage of features like standard interfaces and pre-defined defaults to simplify the development experience.
Note
This was a long exercise and mistakes can happen. If you’re getting errors or a resource is incomplete and you want to see the final main.tf, expand the following code block to see the full file.
AVM modules provide several key advantages over writing raw Terraform templates:
- Simplified Resource Configuration: AVM modules handle much of the complex configuration work behind the scenes
- Built-in Recommended Practices: The modules implement many of Microsoft’s recommended practices by default
- Consistent Outputs: Each module exposes a consistent set of outputs that can be easily referenced
- Reduced Boilerplate Code: What would normally require hundreds of lines of Terraform code can be accomplished in a fraction of the space
As you continue your journey with Azure and AVM, remember that this approach can be applied to more complex architectures as well. The modular nature of AVM allows you to mix and match components to build solutions that meet your specific needs while adhering to Microsoft’s Well-Architected Framework.
By using AVM modules as building blocks, you can focus more on your solution architecture and less on the intricacies of individual resource configurations, ultimately leading to faster development cycles and more reliable deployments.
Additional exercises
For additional learning, it can be helpful to experiment with modifying this solution. Here are some ideas you can try if you have time and would like to experiment further.
- Use the
managed_identitiesinterface to add a system assigned managed identity to the virtual machine and give itKey Vault Administratorrights on the Key Vault. - Use the
tagsinterface to assign tags directly to one or more resources. - Add an Azure Monitoring Agent extension to the virtual machine resource.
- Add additional inputs like VM sku to your module to make it more customizable. Be sure to update the code and
tfvarsfiles to match.
Clean up your environment
Once you have completed this set of exercises, it is a good idea to clean up your resources to avoid incurring costs for them. This can be done typing terraform destroy -var-file=development.tfvars and entering yes when prompted.
Solution Development
Considerations and steps of Solution Development
- Decide on the IaC language (Bicep or Terraform)
- Decide on the module sourcing method (public registry, private registry, inner-sourcing)
- Decide on the orchestration method (template or pipeline)
- Identify the resources needed for the solution (are they all available in AVM?)
- Implement, validate, deploy, test the solution
Questions to cover on this page
- Pick a realistically complex solution and demonstrate how to build it using AVM modules
- Best practices for coding (link to official language specific guidance AND AVM specs where/if applicable)
- Best practices for input and output parameters
Next steps
To be covered in separate, future articles.
To make this solution enterprise-ready, you need to consider the following:
- Deploy with DevOps tools and practices (e.g., CI/CD in Azure DevOps, GitHub Actions, etc.)
- Deploy into Azure Landing Zones (ALZ)
- Make sure the solution follows the recommendations of the Well-Architected Framework (WAF) and it’s compliant with and integrates into your organization’s policies and standards, e.g.:
- Security & Identity (e.g., RBAC, Entra ID, service principals, secrets management, MFA, etc.)
- Networking (e.g., Azure Firewall, NSGs, etc.)
- Monitoring (e.g., Azure Monitor, Log Analytics, etc.)
- Cost management (e.g., Azure Cost Management, budgets, etc.)
- Governance (e.g., Azure Policy, etc.)
Other recommendations
- Don’t use latest, but a specific version of the module
- Don’t expose secrets in output parameters/command line/logs/etc.
- Don’t use hard-coded values, but use parameters and variables
Quickstart Guide
This QuickStart guide offers step-by-step instructions for integrating Azure Verified Modules (AVM) into your solutions. It includes the initial setup, essential tools, and configurations required to deploy and manage your Azure resources efficiently using AVM.
The AVM Key Vault resource module, used as an example in this chapter, simplifies the deployment and management of Azure Key Vaults, ensuring secure storage and access to your secrets, keys, and certificates.
Leveraging Azure Verified Modules
Using AVM ensures that your infrastructure-as-code deployments follow Microsoft’s best practices and guidelines, providing a consistent and reliable foundation for your cloud solutions. AVM helps accelerate your development process, reduce the risk of misconfigurations, and enhance the security and compliance of your applications.
Using default values
The default values provided by AVM are generally safe, as they follow best practices and ensure a secure and reliable setup. However, it is important to review these values to ensure they meet your specific requirements and compliance needs. Customizing the default values may be necessary to align with your organization’s policies and the specific needs of your solution.
Exploring examples and module features
You can find examples and detailed documentation for each AVM module in their respective code repository’s README.MD file, which details features, input parameters, and outputs. The module’s documentation also provides comprehensive usage examples, covering various scenarios and configurations. Additionally, you can explore the module’s source code repository. This information will help you understand the full capabilities of the module and how to effectively integrate it into your solutions.
Subsections of Quickstart
Bicep Quickstart Guide
Introduction
This guide explains how to use an Azure Verified Modules (AVM) in your Bicep workflow. By leveraging AVM modules, you can rapidly deploy and manage Azure infrastructure without having to write extensive code from scratch.
In this guide, you will deploy a Key Vault resource and a Personal Access Token as a secret.
This article is intended for a typical ‘infra-dev’ user (cloud infrastructure professional) who has a basic understanding of Azure and Bicep but is new to Azure Verified Modules and wants to learn how to deploy a module in the easiest way using AVM.
For additional Bicep learning resources use the Bicep documentation on the Microsoft Learn platform, or leverage the Fundamentals of Bicep learning path.
Prerequisites
You will need the following tools and components to complete this guide:
- Visual Studio Code (VS Code) to develop your solution.
- Bicep Visual Studio Code Extension to author your Bicep template and explore modules published in the Registry.
- One of the following command line tools:
- PowerShell AND Azure PowerShell
- Azure CLI to deploy your solution.
- Bicep CLI
- Azure Subscription to deploy your Bicep templates.
Make sure you have these tools set up before proceeding.
Module Discovery
Find your module
In this scenario, you need to deploy a Key Vault resource and some of its child resources, such as a secret. Let’s find the AVM module that will help us achieve this.
There are two primary ways for locating published Bicep Azure Verified Modules:
- Option 1 (preferred): Using IntelliSense in the Bicep extension of Visual Studio Code, and
- Option 2: browsing the AVM Bicep module index.
Option 1: Use the Bicep Extension in VS Code
- In VS Code, create a new file called
main.bicep. - Start typing
module, then give your module a symbolic name, such asmyModule. - Use IntelliSense to select
br/public. - The list of all AVM modules published in the Bicep Public Registry will show up. Use this to explore the published modules.
Note
The Bicep VSCode extension is reading metadata through this JSON file. All modules are added to this file, as part of the publication process. This lists all the modules marked as Published or Orphaned on the AVM Bicep module index pages.
- Select the module you want to use and the version you want to deploy. Note how you can type full or partial module names to filter the list.
- Right click on the module’s path and select
Go to definitionor hitF12to see the module’s source code. You can toggle between the Bicep and the JSON view. - Hover over the module’s symbolic name to view its documentation URL. By clicking on it, you will be directed to the module’s GitHub folder in the bicep-registry-modules (BRM) repository. There, you can access the source code and documentation, as illustrated below.
Option 2: Use the AVM Bicep Module Index
Searching the Azure Verified Modules indexes is the most complete way to discover published as well as planned (proposed) modules. As shown in the video above, use the following steps to locate a specific module on the AVM website:
- Open the AVM website in your favorite web browser: https://aka.ms/avm.
- Expand the Module Indexes menu item and select the Bicep sub-menu item.
- Select the menu item for the module type you are searching for: Resource, Pattern, or Utility.
Note
Since the Key Vault module used as an example in this guide is published as an AVM resource module, it can be found under the resource modules section in the AVM Bicep module index.
- A detailed description of module classification types can be found under the related section here.
- Select the Published modules link from the table of contents at the top of the page.
- Use the in-page search feature of your browser. In most Windows browsers you can access it using the
CTRL+Fkeyboard shortcut. - Enter a search term to find the module you are looking for - e.g., Key Vault.
- Move through the search results until you locate the desired module. If you are unable to find a published module, return to the table of contents and expand the All modules link to search both published and proposed modules - i.e., modules that are planned, likely in development but not published yet.
- After finding the desired module, click on the module’s name. This link will lead you to the module’s folder in the bicep-registry-modules (BRM) repository, where the module’s source code and documentation can be found, including usage examples.
Module details and examples
In the module’s documentation, you can find detailed information about the module’s functionality, components, input parameters, outputs and more. The documentation also provides comprehensive usage examples, covering various scenarios and configurations.
Explore the Key Vault module’s documentation for usage examples and to understand its functionality, input parameters, and outputs.
Note the mandatory and optional parameters in the Parameters section.
Review the Usage examples section. AVM modules include multiple tests that can be found under the
testsfolder. These tests are also used as the basis of the usage examples ensuring they are always up-to-date and deployable.
In this example, you will deploy a secret in a new Key Vault instance with minimal input. AVM provides default parameter values with security and reliability being core principles. These settings apply the recommendations of the Well Architected Framework where possible and appropriate.
Note how Example 2 does most of what you need to achieve.
Create your new solution using AVM
In this section, you will develop a Bicep template that references the AVM Key Vault module and its child resources and features. These include secret and role based access control configurations that grant permissions to a user.
- Start VSCode (make sure the Bicep extension is installed) and open a folder in which you want to work.
- Create a
main.bicepand adev.bicepparamfile, which will hold parameters for your Key Vault deployment. - Copy the content below into your
main.bicepfile. We have included comments to distinguish between the two different occurrences of thenamesattribute.
module myKeyVault 'br/public:avm/res/key-vault/vault:0.11.0' = {
name: // the name of the module's deployment
params: {
name: '<keyVaultName>' // the name of the Key Vault instance - length and character limits apply
}
}Note
For Azure Key Vaults, the name must be globally unique. When you deploy the Key Vault, ensure you select a name that is alphanumeric, twenty-four characters or less, and unique enough to ensure no one else has used the name for their Key Vault. If the name has been previously taken, you will get an error.
After setting the values for the required properties, the module can be deployed. This minimal configuration automatically applies the security and reliability recommendations of the Well Architected Framework where possible and appropriate. These settings can be overridden if needed.
Bicep-specific configuration
It is recommended to create a bicepconfig.json file, and enable use-recent-module-versions, which warns you to use the latest available version of the AVM module.
// This is a Bicep configuration file. It can be used to control how Bicep operates and to customize
// validation settings for the Bicep linter. The linter relies on these settings when evaluating your
// Bicep files for best practices. For further information, please refer to the official documentation at:
// https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/bicep-config
{
"analyzers": {
"core": {
"rules": {
"use-recent-module-versions": {
"level": "warning",
"message": "The module version is outdated. Please consider updating to the latest version."
}
}
}
}
}Define the Key Vault instance
In this scenario - and every other real-world setup - there is more that you need to configure. You can open the module’s documentation by hovering over its symbolic name to see all of the module’s capabilities - including supported parameters.
Note
The Bicep extension facilitates code-completion, enabling you to easily locate and utilize the Azure Verified Module. This feature also provides the necessary properties for a module, allowing you to begin typing and leverage IntelliSense for completion.
- Add parameters and values to the
main.bicepfile to customize your configuration. These parameters are used for passing in the Key Vault name and enabling purge protection. You might not want to enable the latter in a non-production environment, as it makes it harder to delete and recreate resources.
The main.bicep file will now look like this:
// the scope, the deployment deploys resources to
targetScope = 'resourceGroup'
// parameters and default values
param keyVaultName string
@description('Disable for development deployments.')
param enablePurgeProtection bool = true
// the resources to deploy
module myKeyVault 'br/public:avm/res/key-vault/vault:0.11.0' = {
name: 'key-vault-deployment'
params: {
name: keyVaultName
enablePurgeProtection: enablePurgeProtection
// more properties are not needed, as AVM provides default values
}
}Note that the Key Vault instance will be deployed within a resource group scope in our example.
- Create a
dev.bicepparamfile (this is optional) and set parameter values for your environment. You can now pass these values by referencing this file at the time of deployment (using PowerShell or Azure CLI).
using 'main.bicep'
// environment specific values
param keyVaultName = '<keyVaultName>'
param enablePurgeProtection = falseCreate a secret and set permissions
Add a secret to the Key Vault instance and grant permissions to a user to work with the secret. Sample role assignments can be found in Example 3: Using large parameter set. See Parameter: roleAssignments for a list of pre-defined roles that you can reference by name instead of a GUID. This is a key benefit of using AVM, as the code is easy to read and increases the maintainability.
You can also leverage User-defined data types and simplify the parameterization of the modules instead of guessing or looking up parameters. Therefore, first import UDTs from the Key Vault and common types module and leverage the UDTs in your Bicep and parameter files.
For a role assignment, the principal ID is needed, that will be granted a role (specified by its name) on the resource. Your own ID can be found out with az ad signed-in-user show --query id.
// the scope, the deployment deploys resources to
targetScope = 'resourceGroup'
// parameters and default values
param keyVaultName string
// the PAT token is a secret and should not be stored in the Bicep(parameter) file.
// It can be passed via the commandline, if you don't use a parameter file.
@secure()
param patToken string = newGuid()
@description('Enabled by default. Disable for development deployments')
param enablePurgeProtection bool = true
import { roleAssignmentType } from 'br/public:avm/utl/types/avm-common-types:0.4.0'
// the role assignments are optional in the Key Vault module
param roleAssignments roleAssignmentType[]?
// the resources to deploy
module myKeyVault 'br/public:avm/res/key-vault/vault:0.11.0' = {
name: 'key-vault-deployment'
params: {
name: keyVaultName
enablePurgeProtection: enablePurgeProtection
secrets: [
{
name: 'PAT'
value: patToken
}
]
roleAssignments: roleAssignments
}
}The secrets parameter references a UDT (User-defined data type) that is part of the Key Vault module and enables code completion for easy usage. There is no need to look up what attributes the secret object might have. Start typing and tab-complete what you need from the content offered by the Bicep extension’s integration with AVM.
The bicep parameter file now looks like this:
// reference to the Bicep file to set the context
using 'main.bicep'
// environment specific values
param keyVaultName = '<keyVaultName>'
param enablePurgeProtection = false
// for security reasons, the secret value must not be stored in this file.
// You can change it later in the deployed Key Vault instance, where you also renew it after expiration.
param roleAssignments = [
{
principalId: '<principalId>'
// using the name of the role instead of looking up the GUID (which can also be used)
roleDefinitionIdOrName: 'Key Vault Secrets Officer'
}
]Note
The display names for roleDefinitionIdOrName can be acquired the following two ways:
- From the parameters section of the module’s documentation.
- From the
builtInRoleNamesvariable in the module’s source code. To get there, hitF12while the cursor is on the part of the module path starting withbr/public:.
Boost your development with VS Code IntelliSense
Leverage the IntelliSense feature in VS Code to speed up your development process. IntelliSense provides code completion, possible parameter values and structure. It helps you write code more efficiently by providing context-aware suggestions as you type.
Here is how quickly you can deliver the solution detailed in this section:
Deploy your solution
Now that your template and parameter file is ready, you can deploy your solution to Azure. Use PowerShell or the Azure CLI to deploy your solution.
Deploy with
# Log in to Azure
Connect-AzAccount
# Select your subscription
Set-AzContext -SubscriptionId '<subscriptionId>'
# Deploy a resource group
New-AzResourceGroup -Name 'avm-quickstart-rg' -Location 'germanywestcentral'
# Invoke your deployment
New-AzResourceGroupDeployment -DeploymentName 'avm-quickstart-deployment' -ResourceGroupName 'avm-quickstart-rg' -TemplateParameterFile 'dev.bicepparam' -TemplateFile 'main.bicep'# Log in to Azure
az login
# Select your subscription
az account set --subscription '<subscriptionId>'
# Deploy a resource group
az group create --name 'avm-quickstart-rg' --location 'germanywestcentral'
# Invoke your deployment
az deployment group create --name 'avm-quickstart' --resource-group 'avm-quickstart-rg' --template-file 'main.bicep' --parameters 'dev.bicepparam'Use the Azure portal, Azure PowerShell, or the Azure CLI to verify that the Key Vault instance and secret have been successfully created with the correct configuration.
Clean up your environment
When you are ready, you can remove the infrastructure deployed in this example. The following commands will remove all resources created by your deployment:
Clean up with
# Delete the resource group
Remove-AzResourceGroup -Name "avm-quickstart-rg" -Force
# Purge the Key Vault
Remove-AzKeyVault -VaultName "<keyVaultName>" -Location "germanywestcentral" -InRemovedState -Force# Delete the resource group
az group delete --name 'avm-quickstart-rg' --yes --no-wait
# Purge the Key Vault
az keyvault purge --name '<keyVaultName>' --no-waitCongratulations, you have successfully leveraged an AVM Bicep module to deploy resources in Azure!
Tip
We welcome your contributions and feedback to help us improve the AVM modules and the overall experience for the community!
Next Steps
For developing a more advanced solution, please see the lab titled “Introduction to using Azure Verified Modules for Bicep”.
Terraform Quickstart Guide
Introduction
This guide explains how to use an Azure Verified Modules (AVM) in your Terraform workflow. With AVM modules, you can quickly deploy and manage Azure infrastructure without writing extensive code from scratch.
In this guide, you will deploy a Key Vault resource and generate and store a key.
This article is intended for a typical ‘infra-dev’ user (cloud infrastructure professional) who is new to Azure Verified Modules and wants to learn how to deploy a module in the easiest way using AVM. The user has a basic understanding of Azure and Terraform.
For additional Terraform resources, try a tutorial on the HashiCorp website or study the detailed documentation.
Prerequisites
You will need the following tools and components to complete this guide:
- Visual Studio Code (VS Code) to develop your solution.
- Terraform CLI to deploy your Terraform modules. Make sure you have a recent version installed.
- Azure CLI to authenticate to Azure.
- Azure Subscription to deploy your resources.
Before you begin, ensure you have these tools installed in your development environment.
Module Discovery
Find your module
In this scenario, you need to deploy a Key Vault resource and some of its child resources, such as a key. Let’s find the AVM module that will help us achieve this.
There are two primary ways for locating published Terraform Azure Verified Modules:
- Searching the official Terraform Registry, and
- Browsing theAVM Terraform module index.
Use the Terraform Registry
The easiest way to find published AVM Terraform modules is by searching the Terraform Registry. Follow these steps to locate a specific module, as shown in the video above.
- Use your web browser to go to the HashiCorp Terraform Registry
- In the search bar at the top of the screen type avm. Optionally, append additional search terms to narrow the search results. (e.g., avm key vault for AVM modules with Key Vault in the name.)
- Select see all to display the full list of published modules matching your search criteria.
- Find the module you wish to use and select it from the search results.
Note
It is possible to discover other unofficial modules with avm in the name using this search method. Look for the Partner tag in the module title to determine if the module is part of the official set.
Use the AVM Terraform Module Index
Searching the Azure Verified Modules indexes is the most complete way to discover published as well as planned modules - shown as proposed. As presented in the video above, use the following steps to locate a specific module on the AVM website:
- Use your web browser to open the AVM website at https://aka.ms/avm.
- Expand the Module Indexes menu item and select the Terraform sub-menu item.
- Select the menu item for the module type you are searching for: Resource, Pattern, or Utility.
Note
Since the Key Vault module used as an example in this guide is published as an AVM resource module, it can be found under the resource modules section in the AVM Terraform module index.
- A detailed description of each module classification type can be found under the related section here.
- Select the Published modules link from the table of contents at the top of the page.
- Use the in-page search feature of your browser (in most Windows browsers you can access it using the
CTRL+Fkeyboard shortcut). - Enter a search term to find the module you are looking for - e.g., Key Vault.
- Move through the search results until you locate the desired module. If you are unable to find a published module, return to the table of contents and expand the All modules link to search both published and proposed modules - i.e., modules that are planned, likely in development but not published yet.
- After finding the desired module, click on the module’s name. This link will lead you to the official HashiCorp Terraform Registry page for the module where you can find the module’s documentation and examples.
Module details and examples
Once you have identified the AVM module in the Terraform Registry you can find detailed information about the module’s functionality, components, input parameters, outputs and more. The documentation also provides comprehensive usage examples, covering various scenarios and configurations.
Explore the Key Vault module’s documentation and usage examples to understand its functionality, input variables, and outputs.
- Note the Examples drop-down list and explore each example
- Review the Readme tab to see module provider minimums, a list of resources and data sources used by the module, a nicely formatted version of the inputs and outputs, and a reference to any submodules that may be called.
- Explore the Inputs tab and observe how each input has a detailed description and a type definition for you to use when adding input values to your module configuration.
- Explore the Outputs tab and review each of the outputs that are exported by the AVM module for use by other modules in your deployment.
- Finally, review the Resources tab to get a better understanding of the resources defined in the module.
In this example, your will to deploy a secret in a new Key Vault instance without needing to provide other parameters. The AVM Key Vault resource module provides these capabilities and does so with security and reliability being core principles. The default settings of the module also apply the recommendations of the Well Architected Framework where possible and appropriate.
Note how the create-key example seems to do what you need to achieve.
Create your new solution using AVM
Now that you have found the module details, you can use the content from the Terraform Registry to speed up your development in the following ways:
- Option 1: Create a solution using AVM module examples: duplicate a module example and edit it for your needs. This is useful if you are starting without any existing infrastructure and need to create supporting resources like resource groups as part of your deployment.
- Option 2: Create a solution by changing the AVM module input values: add the AVM module to an existing solution that already includes other resources. This method requires some knowledge of the resource(s) being deployed so that you can make choices about optional features configured in your solution’s version of the module.
Each deployment method includes a section below so that you can choose the method which best fits your needs.
Note
For Azure Key Vaults, the name must be globally unique. When you deploy the Key Vault, ensure you select a name that is alphanumeric, twenty-four characters or less, and unique enough to ensure no one else has used the name for their Key Vault. If the name has been used previously, you will get an error.
Option 1: Create a solution using AVM module examples
Leverage the following steps as a template for how to leverage examples for bootstrapping your new solution code. The Key Vault resource module is used here as an example, but in practice you may choose any module that applies to your scenario.
- Locate and select the Examples drop down menu in the middle of the Key Vault module page.
- From the drop-down list select an example whose name most closely aligns with your scenario - e.g., create-key.
- When the example page loads, read the example description to determine if this is the desired example. If it is not, return to the module main page, and select a different example until you are satisfied that the example covers the scenario you are trying to deploy. If you are unable to find a suitable example, leverage the last two steps in the option 2 instructions to modify the inputs of the selected example to match your requirements.
- Scroll to the code block for the example and select the Copy button on the top right of the block to copy the content to the clipboard.
In your IDE - Visual Studio Code in our example - create the main.tf file for your new solution.
Paste the content from the clipboard into main.tf.
AVM examples frequently use naming and/or region selection AVM utility modules to generate deployment region and/or naming values as well as any default values for required fields. If you want to use a specific region name or other custom resource values, remove the existing region and naming module calls and replace example input values with the new desired custom input values.
Once supporting resources such as resource groups have been modified, locate the module call for the AVM module - i.e.,
module "keyvault".AVM module examples use dot notation for a relative reference that is useful during module testing. However, you will need to replace the relative reference with a source reference that points to the Terraform Registry source location. In most cases, this source reference has been left as a comment in the module example to simplify replacing the existing source dot reference. Perform the following two actions to update the source:
- Delete the existing source definition that uses a dot reference - i.e.,
source = "../../". - Uncomment the Terraform Registry source reference by deleting the
#sign at the start of the commented source line - i.e.,source = "Azure/avm-res-keyvault-vault/azurerm".
Note
If the module example does not include a commented Terraform Registry source reference, you will need to copy it from the module’s main documentation page. Use the following steps to do so:
- Use the breadcrumbs to leave the example documentation and return to the module’s primary Terraform Registry documentation page.
- Locate the Provision Instructions box on the right side of the module’s Terraform Registry page in your web browser.
- Select the second line that starts with
source =from the code block - e.g.,source = "Azure/avm-res-keyvault-vault/azurerm". Copy it onto the clipboard. - Return to your code solution and Paste the clipboard’s content where you previously deleted the source dot reference - e.g.,
source = "../../".
- Delete the existing source definition that uses a dot reference - i.e.,
AVM module examples use a variable to enable or disable the telemetry collection. Update the
enable_telemetryinput value to true or false. - e.g.enable_telemetry = trueSave your main.tf file changes and then proceed to the guide section for running your solution code.
Option 2: Create a solution by changing the AVM module input values
Click here to copy the sample code from the video.
module "avm-res-keyvault-vault" {
source = "Azure/avm-res-keyvault-vault/azurerm"
version = "0.9.1"
name = "<custom_name_here>"
resource_group_name = azurerm_resource_group.this.name
location = azurerm_resource_group.this.location
tenant_id = data.azurerm_client_config.this.tenant_id
keys = {
cmk_for_storage_account = {
key_opts = [
"decrypt",
"encrypt",
"sign",
"unwrapKey",
"verify",
"wrapKey"
]
key_type: "RSA"
name = "cmk-for-storage-account"
key_size = 2048
}
}
role_assignments = {
deployment_user_kv_admin = {
role_definition_id_or_name = "Key Vault Administrator"
principal_id = data.azurerm_client_config.current.object_id
}
}
wait_for_rbac_before_key_operations = {
create = "60s"
}
}Use the following steps as a guide for the custom implementation of an AVM Module in your solution code. This instruction path assumes that you have an existing Terraform file that you want to add the AVM module to.
- Locate the Provision Instructions box on the right side of the module’s Terraform Registry page in your web browser.
- Select the module template code from the code block and Copy it onto the clipboard.
- Switch to your IDE and Paste the contents of the clipboard into your solution’s .tf Terraform file - main.tf in our example.
- Return to the module’s Terraform Registry page in the browser and select the Inputs tab.
- Review each input and add the inputs with the desired target value to the solution’s code - i.e.,
name = "custom_name". - Once you are satisfied that you have included all required inputs and any optional inputs, Save your file and continue to the next section.
Deploy your solution
After completing your solution development, you can move to the deployment stage. Follow these steps for a basic Terraform workflow:
Open the command line and login to Azure using the Azure cli
az loginIf your account has access to multiple tenants, you may need to modify the command to
az login --tenant <tenant id>where “<tenant id>” is the guid for the target tenant.After logging in, select the target subscription from the list of subscriptions that you have access to.
Change the path to the directory where your completed terraform solution files reside.
Note
Many AVM modules depend on the AzureRM 4.0 Terraform provider which mandates that a subscription id is configured. If you receive an error indicating that
subscription_id is a required provider property, you will need to set a subscription id value for the provider. For Unix based systems (Linux or MacOS) you can configure this by runningexport ARM_SUBSCRIPTION_ID=<your subscription guid>on the command line. On Microsoft Windows, you can perform the same operation by runningset ARM_SUBSCRIPTION_ID="<your subscription guid>"from the Windows command prompt or by running$env:ARM_SUBSCRIPTION_ID="<your subscription guid>"from a powershell prompt. Replace the “<your subscription id>” notation in each command with your Azure subscription’s unique id value.Initialize your Terraform project. This command downloads the necessary providers and modules to the working directory.
terraform initBefore applying the configuration, it is good practice to validate it to ensure there are no syntax errors.
terraform validateCreate a deployment plan. This step shows what actions Terraform will take to reach the desired state defined in your configuration.
terraform planReview the plan to ensure that only the desired actions are in the plan output.
Apply the configuration and create the resources defined in your configuration file. This command will prompt you to confirm the deployment prior to making changes. Type yes to create your solution’s infrastructure.
terraform applyInfo
If you are confident in your changes, you can add the
-auto-approveswitch to bypass manual approval:terraform apply -auto-approveOnce the deployment completes, validate that the infrastructure is configured as desired.
Info
A local
terraform.tfstatefile and a state backup file have been created during the deployment. The use of local state is acceptable for small temporary configurations, but production or long-lived installations should use a remote state configuration where possible. Configuring remote state is out of scope for this guide, but you can find details on using an Azure storage account for this purpose in the Microsoft Learn documentation.
Clean up your environment
When you are ready, you can remove the infrastructure deployed in this example. Use the following command to delete all resources created by your deployment:
terraform destroyNote
Most Key Vault deployment examples activate soft-delete functionality as a default. The terraform destroy command will remove the Key Vault resource but does not purge a soft-deleted vault. You may encounter errors if you attempt to re-deploy a Key Vault with the same name during the soft-delete retention window. If you wish to purge the soft-delete for this example you can run az keyvault purge -n <keyVaultName> -l <regionName> using the Azure CLI, or Remove-AzKeyVault -VaultName "<keyVaultName>" -Location "<regionName>" -InRemovedState using Azure PowerShell.
Congratulations, you have successfully leveraged Terraform and AVM to deploy resources in Azure!
Tip
We welcome your contributions and feedback to help us improve the AVM modules and the overall experience for the community!
Next Steps
For developing a more advanced solution, please see the lab titled “Introduction to using Azure Verified Modules for Terraform”.