Naming

Most names in a Terraform provider will be drawn from the upstream API/SDK that the provider is using. The upstream API names will likely need to be modified for casing or changing between plural and singular to make the provider more consistent with the common Terraform practices below.

Resource Names

Resource names are nouns, since resource blocks each represent a single object Terraform is managing. Resource names must always start with their containing provider's name followed by an underscore, so a resource from the provider postgresql might be named postgresql_database.

It is preferable to use resource names that will be familiar to those with prior experience using the service in question, e.g. via a web UI it provides.

Data Source Names

Similar to resource names, data source names should be nouns. The main difference is that in some cases data sources are used to return a list and can in those cases be plural. For example the data source aws_availability_zones in the AWS provider returns a list of availability zones.

Function Names

Function names are verbs, since they encapsulate computational logic for usage in practitioner configurations. Unlike resource and data source naming, function names should NOT include the provider name since the configuration language syntax for calling the function must already specify the provider name separately. For example, a time provider-defined function that parses RFC3339 timestamp strings should be named parse_rfc3339 since it would be called via provider::time::parse_rfc3339.

Function names should be all lowercase and use underscores to separate words. The built-in functions in the Terraform language do not use underscores for historical reasons, but all functions defined in providers should use underscores to improve readability.

Attribute Names

Below is an example of a resource configuration block which illustrates some general design patterns that can apply across all plugin object types:

resource "aws_instance" "example" {
  ami                    = "ami-408c7f28"
  instance_type          = "t1.micro"
  monitoring             = true
  vpc_security_group_ids = [
      "sg-1436abcf",
  ]
  tags          = {
    Name        = "Application Server"
    Environment = "production"
  }
  root_block_device {
    delete_on_termination = false
  }
}

Attribute names within Terraform configuration blocks are conventionally named as all-lowercase with underscores separating words, as shown above.

Simple single-value attributes, like ami and instance_type in the above example, are given names that are singular nouns, to reflect that only one value is required and allowed.

Boolean attributes like monitoring are usually written also as nouns describing what is being enabled. However, they can sometimes be named as verbs if the attribute is specifying whether to take some action, as with the delete_on_termination flag within the root_block_device block.

Boolean attributes are ideally oriented so that true means to do something and false means not to do it; it can be confusing to have "negative" flags that prevent something from happening, since they require the user to follow a double-negative in order to reason about what value should be provided.

Some attributes expect list, set or map values. In the above example, vpc_security_group_ids is a set of strings, while tags is a map from strings to strings. Such attributes should be named with plural nouns, to reflect that multiple values may be provided.

List and set attributes use the same bracket syntax, and differ only in how they are described to and used by the user. In lists, the ordering is significant and duplicate values are often accepted. In sets, the ordering is not significant and duplicated values are usually not accepted, since presence or absence is what is important.

Map blocks use the same syntax as other configuration blocks, but the keys in maps are arbitrary and not explicitly named by the plugin, so in some cases (as in this tags example) they will not conform to the usual "lowercase with underscores" naming convention.

Configuration blocks may contain other sub-blocks, such as root_block_device in the above example. The patterns described above can also apply to such sub-blocks. Sub-blocks are usually introduced by a singular noun, even if multiple instances of the same-named block are accepted, since each distinct instance represents a single object.