Terraform Best Practices

Building strong functionality in HighBond begins with writing high-quality Terraform code. Take steps to make your code manageable, efficient, and scalable from the early stages. This helps to ensure good performance, reduces the chances of problems, and simplifies the debugging process.

Covered in this guide:

• Terraform Resources
• Make Code Easy to Read
• Naming Conventions

Terraform Resources

Covered in this section:

• Terraform Providers
• HighBond Terraform Documentation
• HashiCorp Terraform Documentation
• Formatting
• Hard-coding
• Syntax

Terraform Providers

For the latest provider release please refer to the latest Terraform provider releases.

HighBond Terraform Documentation

Refer to our HIghBond Terraform Documentation for guides, data sources, and resources.

HashiCorp Terraform Documentation

For more information refer to the official HashiCorp style guide for Terraform.

Formatting

• Format all code using terraform fmt.

Hard-coding

• Don't hardcode values that can be passed as variables or discovered using data sources.
• Add variables and set defaults.

Syntax

• Use 2 spaces when defining resources except when defining other inline resources.
• Block contents should be indented with 2 spaces.
• When multiple arguments with single-line values appear on consecutive lines at the same nesting level, align their equals signs:

ami           = "abc123"
instance_type = "t2.micro"

Make Code Easy to Read

When writing code, remember that others may work with it in the future. Whenever possible, ensure your code is easy to read and understand. Follow any formatting standards used by your organization.

Covered in this section:

• Comment Your Code
• Use White Space

Comment Your Code

What may seem obvious today may not be clear in the future, especially on a complicated section of code. Comments should be well-written and clear, just like the code they are annotating.

Single line comments start with a hashtag (#) and can be placed anywhere on the line. Everything after the # and up to the new line is considered a comment. For example:

#highbond_attribute_type unv_name
resource highbond_attribute_type "attribute_type_unv_name" {
field_name   = "unv_name"
name         = "unv_name"
display_name = local.t.attribute_type_unv_name.display_name
data_type    = "text"
is_global    = true
is_required  = true
tooltip      = local.t.attribute_type_unv_name.tooltip
type_options {
default = ""
}

Use White Space

Use empty lines and spaces to make code more readable. The easier it is to read code, the easier it is to identify and correct issues. Empty lines help visually group blocks of code together so the reader can see the logical organization. Spaces on each line help make the items on an individual line easier to read.

#highbond_role unv_asset_manager
 resource highbond_role "role_unv_asset_manager" {
 name         = "Asset Manager"
 display_name = local.t.role_unv_asset_manager.display_name
 description  = local.t.role_unv_asset_manager.description
 role_type    = "user"
 }

#highbond_role unv_system
 resource highbond_role "role_unv_system" {
 name         = "System"
 display_name = local.t.role_unv_system.display_name
 description  = local.t.role_unv_system.description
 role_type    = "user"
 }

Naming Conventions

Covered in this section:

• Parameter, meta-parameter and variable naming
• Use data sources
• Use proper datatype
• File names
• Variables
• Outputs

Parameter, meta-parameter and variable naming

• Use lowercase.
• Use snake_case for all resources and names.
• Use underscores (_) as a separator and lowercase letters in names.
• Try not to repeat the resource type in the resource name.
• Only use an underscore (_) when naming Terraform resources like TYPE/NAME parameters and variables.

resource "highbond_resource" "example_resource" {
  # Omitted for brevity
}

This includes variables and outputs as well:

variable "highbond_access_token" 
output "attribute_id"

Use data sources

• Organize all data sources in an datasource.tf file.

Use proper datatype

Using proper datatypes in terraform makes it easier to validate inputs and document usage.

• Use null instead of empty strings ("")
• Use bool instead of strings or integers for binary true/false

File Names

Putting all code in main.tf is a good idea when you are getting started or writing an example code. In all other cases best practices recommends splitting files logically into a separate resource file for each type of HighBond resource.

Similar resources should be defined in the same file and named accordingly.

collections.tf
main.tf
variables.tf
asset_types.tf

Variables

• Declare all variables in variables.tf file.
• Organize all outputs in an outputs.tf file.
• Remove any unused variables.
• Include a type.
• Always include description on all variables even if you think it is obvious (you will need it in the future).

Each variable block should always define a description and type, even if it is of the string type (the default), in that order. E.g.:

variable "example_variable" {
  description = "This is an example"
  type        = string
  default     = "example"  # NOTE: this is optional
}

Outputs

• Organize all outputs in an outputs.tf file.
• Always include description for all outputs even if you think it is obvious.
• Output all useful values that root modules might need to refer to or share.

Each output block should always define a description, before the value:

output "output_example" {
  description = "This is a greeting for everyone."
  value       = "hello world!"
}