Explaining the Syntax of Terraform

The aim of this page📝 is to describe the syntax — the block syntax — of HCL (Hashicorp Configuration Language) used in Terraform configuration files. I am focusing on the example of the resource block type. See this article describing other object types apart from resource (data, output, module, or variable).

Before delving into syntax, let’s start with some warm-up notes:

HCL is a simplified version of JSON that’s easier to read and possible to comment out

• Note that JSON itself can also be used — it’s not as readable, but easier to generate programmatically.
• As opposed to JSON, HCL also supports comments.

Syntactically, the block starts with <block_type> such as resource, data, output, or variable

• Let’s look into generic syntax, the syntax for the resource (most important) block type, and a simple instance of resources.
• In the rest of the post, I’ll focus only on the resource block/object type.

Block types have a defined number of labels it expects (0 or more), with resource expecting two labels - type name and local name

• The resource block type in particular expects 2 labels: <resource_type> + <local_name>.
• Each resource declaration has exactly 1 <resource_type> which is predefined by providers (AWS in this case).
• ⟹ It is essential to work with the documentation of a provider — it is not random.
• ⟹ If in Chrome, create a custom search with the string to look up directly from the address bar with a selected shortcut (I’m using tf; btw their search kind of sucks).

https://registry.terraform.io/search/providers?q=%s

• The name_label/local_name is a unique identifier used throughout the rest of the config.
• Within the block, there is a series of key-value pairs known as arguments.
• The KV pairs make use of the available arguments for the object type.
• Each key is a string.
• Each value is any of Terraform’s different data types.

Blocks support nesting — they can contain further blocks which opens doors to much more complex configuration and recursion

• In addition, blocks support nesting, so you can add nested blocks with another series of key-value pairs.

The aws_s3_bucket_public_access_block is a resource type configuring public access to AWS S3 on bucket-level via five arguments

• This configuration helps to prevent unauthorized public access to the contents of an S3 bucket.
• This resource manages the S3 bucket-level Public Access Block configuration.
• When block_public_acls is set to true, PUT Bucket acl and PUT Object acl calls will fail if the specified ACL allows public access.
• PUT Object calls will also fail if the request includes an object ACL.
• When block_public_policy is set to true, Amazon S3 will reject calls to PUT Bucket policy if the specified bucket policy allows public access.

Finally, it is possible to refer to other resources within config files with dot . syntax

• The <attribute> is optional; without it, you're referring to the whole resource.
• The docs differentiate between argument reference vs attribute reference. In referring itself, both are attributes.
• The values from attribute reference are exported by providers without being explicitly configured.
• aws_s3_bucket_public_access_block has a single property listed in attribute reference and it is id

LINKS

• https://developer.hashicorp.com/terraform/language/syntax/configurations
• https://developer.hashicorp.com/terraform/language/resources/syntax
• https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/instance
• https://registry.terraform.io/providers/hashicorp/aws/2.35.0/docs/resources/s3_bucket_public_access_block
• https://github.com/hashicorp/hcl/tree/hcl1#why