The Developer's Guide to HCL, Part 1: Introduction

Understanding the foundation and context of HCL is crucial before diving into its intricacies. This section clarifies what HCL is, its design goals, how it compares to other configuration languages, and its role within the HashiCorp ecosystem and the broader technology landscape where the "HCL" acronym might appear.

What is HCL? Purpose, Design, and Key Characteristics

HCL, or HashiCorp Configuration Language, is a toolkit and language syntax developed by HashiCorp specifically for creating structured configuration languages that are both human-readable and machine-friendly. Its primary target is DevOps tools, servers, and similar applications.

The design philosophy of HCL centers on several key characteristics:

• Readability and Writability: HCL syntax is engineered to be easy for humans to read and write, drawing inspiration from existing formats like libucl and nginx configurations. It aims for a balance, avoiding the verbosity of XML or the potential terseness of JSON when used for complex configurations.
• Declarative Approach: HCL employs a declarative syntax. This means users define the desired end-state of their infrastructure or configuration, and the HCL-processing application (like Terraform) determines the necessary steps to achieve that state. This simplifies management by abstracting the underlying complexity.
• Machine-Friendliness: While prioritizing human readability, HCL also offers a JSON-based variant, allowing configurations to be machine-generated and parsed when needed. This provides flexibility for interoperability.
• Structured Configuration: HCL is built around key-value pairs (arguments) and hierarchical blocks, allowing applications to define clear schemas for their configuration. This structure enables better error messaging and more convenient definition within the calling application.
• Extensibility: The language includes an expression syntax that supports basic inline computation and, with application support, the use of variables and functions for more dynamic configurations.

HCL is not intended to be a general-purpose programming language. Instead, it provides a specialized set of constructs for defining configurations in a clear, structured, and manageable way.

HCL vs. Other Configuration Languages: JSON and YAML

While JSON and YAML are general-purpose data serialization formats, HCL is specifically designed as a syntax and API for building structured configuration formats. This distinction leads to several differences in how they are used for Infrastructure as Code.

• JSON (JavaScript Object Notation): JSON is widely adopted for its simplicity and language independence, making it excellent for data interchange. It uses a key-value pair format.
  • Pros: Highly human-readable in its compact form (though often minified for APIs), quick to parse, and has wide tooling support including JSONPath for queries.
  • Cons: Limited data type support, no native support for comments, namespaces, or attributes, which can make complex configurations verbose or less intuitive. When used for Terraform, it can be clunky for variables and modules.
• YAML (YAML Ain't Markup Language): YAML prioritizes human readability even more than JSON, using indentation to denote structure. It is a superset of JSON, meaning a YAML file can contain JSON.
  • Pros: Exceptionally human-readable syntax, compact, supports a richer set of language-independent object types, and allows comments. Widely adopted in cloud-native tools like Kubernetes and CI/CD systems.
  • Cons: Indentation-sensitive format can be prone to syntax errors, portability of some types can be an issue, and debugging can be difficult. For Terraform, while some advocate for YAML support in OpenTofu (a Terraform fork), it's noted that YAML's type inference could be problematic, and replacing HCL entirely is not feasible due to HCL being an integral part.
• HCL: HCL strikes a compromise, offering better readability than raw JSON for configuration tasks and more structure than YAML for defining application-specific schemas.
  • Pros: Designed for configuration, more concise than JSON for this purpose, supports variables, functions, expressions, and modules natively and elegantly. Its structure allows for better error reporting by the consuming application.
  • Cons: Primarily tied to the HashiCorp ecosystem, though parsers exist for other languages. Conversion to and from JSON can have ambiguities for certain constructs.

The design of HCL by HashiCorp was deliberate to provide a domain-specific language optimized for the tasks its tools perform, particularly in defining infrastructure and application configurations.

Table 1: High-Level Comparison of HCL, JSON, and YAML for IaC

HCL in the HashiCorp Ecosystem: Terraform, Packer, Vault, Nomad

HCL is the common configuration language across HashiCorp's suite of popular DevOps tools, providing a consistent experience for users working with different aspects of infrastructure and application management.

• Terraform: Uses HCL to define infrastructure as code, allowing users to provision and manage resources across various cloud providers (AWS, Azure, GCP) and other services. This is arguably the most prominent use of HCL.
• Packer: Employs HCL (specifically HCL2 templates) to define machine image configurations for various platforms, automating the creation of identical machine images.
• Vault: Utilizes HCL for writing policies that govern access to secrets and other sensitive data.
• Nomad: Leverages HCL for defining job specifications, which describe applications and their resource requirements for scheduling and deployment.

The consistent syntax and design philosophy of HCL across these tools simplify learning and allow users to transfer knowledge from one tool to another.

Distinguishing HashiCorp HCL from HCL Technologies Offerings

It is important for developers to distinguish HashiCorp Configuration Language from products and documentation associated with HCL Technologies (HCLTech), a separate global technology company. While both use the "HCL" acronym, they refer to different things.

• HashiCorp HCL: The subject of this guide, a language syntax for tools like Terraform, Packer, Vault, and Nomad.
• HCL Technologies (HCLTech): Offers a wide range of software products and services, such as HCL AppScan (application security testing), HCL Leap (application development platform), and HCL Connections. These products have their own configuration methods, internal languages, or APIs, which are distinct from HashiCorp HCL.

For example, HCL Domino Designer has its own Formula Language which also reports "syntax errors." This is specific to that HCLTech product and should not be confused with the syntax and features of HashiCorp HCL discussed in this guide. This guide focuses exclusively on HashiCorp HCL as used in tools like Terraform.

Next up, the syntax:

The Developer’s Guide to HCL, Part 2: Mastering the Syntax

Learn the core building blocks of HCL syntax: arguments, blocks, identifiers, comments, and the primitive and complex data types used in modern IaC.

Scalr Learning CenterSebastian Stadil