Terraform best practices — how to use a consistent naming convention

Jack Roper
Apr 12 · 4 min read

When starting out with Terraform it’s hard to know what is considered ‘best practice’ in a number of areas.

This post is the third in the series which focuses on point 3 in the list, ‘use a consistent naming convention’.

  1. Use a consistent file structure across your projects
  2. Use modules wherever possible
  3. Use a consistent naming convention
  4. Use a consistent format and style
  5. Hold your state file remotely, not on your local machine
  6. Avoid hardcoding variables
  7. Less resources in a project are easier and faster to work with
  8. Limit resources in the project to reduce the blast radius
  9. Test your code

Naming convention guidance

How you name your resources is your Terraform code and in Azure is partly subjective. However by setting some principals and guidelines in your team you can avoid confusion and make you code easier to follow. Terraform code should always be written for people to read first; consistency will help when changes are required to the code at a later date. This principal should apply to all coding languages.

When writing this article, I have come across many contradictory points of view, so there are no real hard and fast rules. I’ve recommended a few points that I think make the most sense.

Naming resources in Terraform

Each resource in Terraform is assigned a name in code to enable it to be referenced from elsewhere. The name is a noun that represents a single object Terraform is managing (example for VM in Azure, given the name azurerm_desktop):

The resource type here is ‘azurerm_virtual_machine’.

You would reference the resource using

Avoid duplication

The first rule is not to include the name of the resource type in the resource name, either partially or completely, but do include the provider name first. This follows the guidance in the Hashicorp docs, some other sources may contradict this, suggesting that the provider name is not required in the name.

For example, the name desktop_virtual_machine would not be appropriate here, as this would cause unnecessary duplication when referencing it, and does not include the provider (azurerm):

This would be better:

Use underscores

Always use underscores to separate multiple words in a resource name, e.g.


Use the name ‘this’ where there is a single resource?

Some sources recommended that a resource name should be named this if a resource creates single resource of this type. At some point you will likely come across this in other people’s code and wonder what it represents like me!

Personally, I find this a bit confusing and may make the code unscalable if more types of a particular resource are added at a later time.

e.g if there was a single VM being created, it would be named:

Naming resources in Azure

So far we’ve been taking about the names of resources refenced within code, these are not the names the resources will be given in Azure. We have not been taking about Azure naming conventions, rather the Terraform code naming convention.

Dynamic naming

The actual names of resources in Azure will have restrictions on them. For example some resource names may have imposed character limits, require all lower case characters, require no spaces or special characters, or a requirement to be globally unique.

Where this is the case, dynamic naming would be a good idea.

A common example of this is to use the ‘random’ provider to include or append to a resource name. The following defines a random pet name:

This can be appended to a name, e.g:

As well as adding randomness to your resource names in Azure to ensure uniqueness, you could also use variables to define other parts of the resource name as appropriate, e.g. the environment, region, count, application etc.

A common problem with this approach comes when the format needs to change as Terraform does not track the actual names of the resources in Azure. If they are changed in the code, you will need to rename them manually in Azure to the new format, or allow Terraform to destroy and re-create them.

Azure CAF naming conventions

Rather than creating a manual naming conventions, a better approach would be to use the azurecaf_name module to name your resources consistently (this supersedes the old azurecaf_naming_convention module). This uses the default Microsoft Cloud Adoption Framework conventions and has several configurable options.

Check out the references below for more guidance and thanks for reading! 🍻


Everything connected with Tech & Code

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store