OpenTofu Language Guide

• Type: the type of block that is being declared, as examples; resource, data, check
• Label: his depends on the type of block, both data and resource blocks require the use of a label as they instruct OpenTofu which service resource to operate on. As an example data "scratch_string" "" {} the label for thatdata block is scratch_string which indicates both the provider and the provider resource.
• Identifier: the unique ID that Terraform and engineers will use to reference this particular instance as an example data "scratch_string" "unique_name" {}.
• Arguments: a block will contain n-number of arguments, these are use to compose the properties of the block type.
• Body: the body of a block is demarcated by the use of a pair of curly braces { }, everything that is between those braces makes up the body.
• Blocks: inside a block can be any number of nested blocks, these apply by the same rules as their parent.

<BLOCK_TYPE> "<BLOCK_LABEL>" "<BLOCK_IDENTIFIER>" {
   <ARGUMENT_NAME> = <ARGUMENT_VALUE>
   <BLOCK_TYPE> "<BLOCK_LABEL>" {
     # ...
}
# ...
}

The Resource Block uses the same format that we defined earlier for all blocks. These blocks are responsible for provisioning resources on a platform or service, and example of this might be a workspace on a Scalr instance which would use a resource "scalr_workspace" "this" block. Let's dive a little deeper into the example:

resource "scalr_workspace" "this" {
 name = "Meowforce One"
 environment_id = "env-xxxxxxxxxxxxxxx"
working_directory = "opentofu/"
}

From the above definition of a block we can break up the resource into it's components:

• Type: resource
• Label: scalr_workspace
• Identifier: this
• Arguments: name, environment_id and working_directory

Data Source blocks are how we get information about resources that already exist on a platform, perhaps they were created by another OpenTofu definition or even manually, or we just want to query an external API to get some information. All of this would be done using a data block. As a follow on example to our above Resource Block example instead of statically putting in the environment_id we can use a Data Source to retrieve that for us, this ensure that the information is always up to date and correct.

data "scalr_environment" "dev" {
   name       = "dev"
   account_id = "acc-xxxxxxxxxx"
}

In this example we can see the type as defined by the keyword data and that it's going to be identified as dev. Taking this new data block we can refactor the resource block:

data "scalr_environment" "dev" {
   name       = "dev"
   account_id = "acc-xxxxxxxxxx"
          
 }
 resource "scalr_workspace" "this" {
     name           = "Meoforce One"
     environment_id = data.scalr_environment.dev.id
     working_directory = "opentofu/"
 }

As can now be seen instead of having that static reference to env-xxxxxxxxxxxxxxx we are using data.scalr_environment.dev.id , the data source lets us access any attributes defined on the data source, or the entire data source itself. This ability to reference between resources and data sources is part of the extreme power of OpenTofu, it enables extremely easy passing around of important information.

If we continue down our example pathway we would need to have provider block for the scalr provider, it would look like:

provider "scalr" {
   hostname = var.hostname
   token    = var.token
}

The provider and by extension the provider block is what creates a client to the external services API that we want to interact with, in the above example we are providing the scalr provider the credentials required for the provider to authenticate with Scalr so that we are able to perform operations on that platform.

When defining an Input Variable it is best practice to put those within a variables.tf file, the variable block itself has a number of properties available to us:

• default - sets a default value for the variable, this makes the variable an optional variable
• type - the data type of the variable, the following are valid types:
• string — basic string value, such as "Hello, world!"
• number - basic number value, such as 2024
• bool — basic boolean value, such as true
• list(<TYPE>) - a non-unique collection of typed mutable elements, defined as list(string) which would be ["Hello,", "World!"]
• set(<TYPE>)- a unique collection of immutable typed elements, defined as set(bool) which would have a value of [true, false]
• map(<TYPE>) — a collection of typed key-value pairs, each key in a map is unique and associated with a single value, defined as map(string) which would have a value of { cat = "meow", dog = "woof" }
• object({<PROPERTY_NAME> = <TYPE>, ...}) — similar to a map however the keys are all predefined and can have different types from each other, defined as object({ animal = string, sound = string }) which would have a value of { animal = "cat", sound = "meow" }
• tuple([<TYPE>, ...]) — a collection of ordered, immutable elements. It could be thought of as a list with multiple types, where the order matters.
• any — this type should never be used as it means that any type can be passed into the variable. As these variables are the interface to our code it should be as specific and explicit as possible.
• description - the description is extremely important this is how we inform our consumers about what is required when it comes to to the variable, these can be documented in two ways; simple strings or heredoc strings the latter allows us to have more complete documentation.
• validation - this allows us to ensure that the data being passed into the code is of the correct format, it also allows returning an error when the data does not match the validation
• sensitive — marks the variable as sensitive ensuring that it's value won't be shown in any logs
• nullable - demarcates that the variable is able to be set to null

Lets dive into some examples of declaring different types of variables, the examples we are going to look at are; environments, firewall rules. The first example is for ensuring that we have an environment passed in with the right format:

variable "environment" {
 type = string
 description = <<-DESC
 (Optional) The three letter description for the environment.
 Default:
 `dev`
 DESC
 default = "dev"
 validation {
 condition = contains(["dev", "uat", "prd"], var.environment)
 error_message = "Err: the environment value must be valid."
 }
}

variable "firewall_rules" {
 type = set(object({
 name = string
 priority = number
 source = object({
 address = string
 port = optional(number, 0)
 })
 destination = object({
 address = string
 port = number
 })
 action = string
 }))
 description = <<-DESC
 (Required) a set of firewall rules with the following properties.

 Properties:
 - `name` (Required): unique name for the rule
 - `priority` (Required): an integer for the priority, must be above 1,000
 - `source` (Required): the source object
 - `address` (Required): an IPv4 address space
 - `port` (Optional): an integer port
 - `destination` (Required): the destination object
 - `address` (Required): an IPv4 address space
 - `port` (Required): an integer port
 - `action` (Required): a valid action; `block`, `allow`
 DESC
 default = [
 {
 name = "example-rule"
 priority = 1001
 source = {
 address = "10.0.0.0/16"
 }
 destination = {
 address = "192.168.0.0/24"
 port = 443
 }
 action = "allow"
 }
 ]
 validation {
 condition = alltrue([
 for rule in var.firewall_rules :
 contains(["allow", "block"], rule.action) ? true : false
 ])
 error_message = "Err: invalid action provided, it must be: 'allow',
'block'."
 }
 validation {
 condition = alltrue([
 for rule in var.firewall_rules :
 rule.priority > 1000 ? true : false
 ])
 error_message = "Err: invalid priorty provided, the value must be over
1,000."
 }
}

locals {
 default_port = 443
}

In the above example we are defining a local variable called default_port this allows us to define what we would expect to be the default port for services that are constructed by the remaining OpenTofu. The value is never going to change, that's why making it a local variable makes sense. In the next example we will look at a mutating variable that constructs a name from a number of variables.

locals {
 resource_prefix = format(
 "%s-%s",
 var.environment,
 lower(var.project.acronym)
 )
}

You can use the string, number, bool, list and map types out of the box, it is possible to cast a list to a set using the toset() function.

Outputs allow engineers to return data/information back to the caller of the OpenTofu code, this is especially useful when your code produces some assets that are a dependency for other resources. The output block contains the following properties:

• description — a useful description of what the output is returning, given that this output forms part of the API you provide it should be descriptive as to what the output is
• sensitive— this marks the value as sensitive which then ensures it is not returned in any outputs
• value — the value of the output, this could be any from a static string to the result of a resource being created
• depends_on — a list of resource references that are required to be in existence prior to the output returning a value
• precondition — similar to variable validation this ensures that the data that is to be returned is as expected or an error is returned, you can have zero to many precondition blocks

locals {
 sounds = {
 cat = "meow"
 }
}
output "cat_sound" {
 description = "The sound a cat makes"
 value = local.sounds.cat
 precondition {
 condition = local.sounds.cat == "meow"
 error_message = "Err: the defined cat sound is incorrect."
 }
} 

• The Root Module — this term is use to refer to any directory that contains .tf files, the root module is what we call when we want to provision resources
• Child Module(s) — a child module refers to modules that are defined locally within a root module, these modules are normally declared within a modules directory and can only be consumed by that root module
• Published Modules — these are modules that have been published in some mechanism, such as; git, a registry or a filesystem. These modules are designed to be consumed by others.

• source — the source of the module, this would be a registry address, a file path, a git address amongst other things. This is how OpenTofu knows where to
• version — on sources that support versioning (e.g. registry) you can specify the explicit version or a version constraint to ensure you're getting the right version of the module
• for_each — an optional property that allows us to iterate of a map to produce multiple instances of a module, in the same way as a resource
• count — an optional property that allows us to define the number of instances to create(for_each is nearly always a better alternative)
• depends_on — a list of explicit resource references required to exist before the module will be created
• providers — a map of providers and aliases to pass to the module

module "servers" {
 for_each = var.server_config
 source = "https://registry.meowforce.one"
 version = "1.0.0"
 name = each.key
 type = each.value.type
 size = each.value.size
}

module "servers" {
 ...
 version = "~> 1.0"
 ...
}