502 lines
9.5 KiB
Markdown
502 lines
9.5 KiB
Markdown
---
|
|
gitea: none
|
|
include_toc: true
|
|
---
|
|
|
|
# HCL
|
|
|
|
The HashiCorp Configuration Language (HCL) is a specialized configuration language developed by HashiCorp, primarily designed for use with its suite of tools, including Terraform, Vault, and Nomad.
|
|
|
|
Since Rougail is designed to centralize the variables from your various projects, it may be useful to export the variables and values defined in Rougail to an HCL file.
|
|
|
|
Please note that the goal here is not to manage all your HCL files, but to export the variables and values to them.
|
|
|
|
## Attributes
|
|
|
|
Attributes assigns a value to a particular name.
|
|
|
|
An attribute is therefore the name of a variable or a family to which a value is assigned.
|
|
|
|
### Primitive Types
|
|
|
|
Value has those primitive types: `string`, `integer`, `bool` or `null`
|
|
|
|
```hcl
|
|
a_string = "a value"
|
|
an_integer = 1
|
|
a_boolean = true
|
|
null_value = null
|
|
```
|
|
|
|
Nothing particular in Rougail:
|
|
|
|
```yaml
|
|
%YAML 1.2
|
|
---
|
|
version: 1.1
|
|
|
|
a_string: a value # An attribute with a string
|
|
|
|
an_integer: 1 # An attribute with a integer
|
|
|
|
a_boolean: true # A boolean attribute
|
|
|
|
null_value:
|
|
description: A nullable value
|
|
mandatory: false
|
|
...
|
|
```
|
|
|
|
### Complex Types
|
|
|
|
Value could be `list`, `set`, `tuple`, `map` or `object`.
|
|
|
|
#### `list`, `set` or `tuple`
|
|
|
|
The `set` type is an unordered `list` (the elements are all of the same type) with no duplicates. Rougail lists also do not allow duplicates by default (though this can be enabled), but their values are ordered.
|
|
|
|
The type `tuple` (where each element has its own type) is not allowed in Rougail, so hasn't equivalent for now.
|
|
|
|
Syntactically, there is no difference between a list, a set, and a tuple.
|
|
|
|
In Rougail, you must therefore declare a variable of a specific type and set the “multi” parameter to True.
|
|
|
|
```hcl
|
|
a_list = [
|
|
"value 1",
|
|
"value 2",
|
|
]
|
|
an_integer_list = [
|
|
1,
|
|
2,
|
|
]
|
|
```
|
|
|
|
```yaml
|
|
%YAML 1.2
|
|
---
|
|
version: 1.1
|
|
|
|
a_list: ["value 1", "value 2"] # An attribute with a list of strings
|
|
|
|
an_integer_list: [1, 2] # An attribute with a list of integer
|
|
...
|
|
```
|
|
|
|
#### `map` or `object`
|
|
|
|
The difference between `map` and `object` in HCL is analogous to that between `list` and `tuple`: the values in a `map` are all of the same type, whereas the values in an `object` can be of different.
|
|
|
|
In Rougail, this corresponds to a family.
|
|
|
|
```hcl
|
|
a_map = {
|
|
key_1 = "value 1"
|
|
key_2 = "value 2"
|
|
key_3 = "value 3"
|
|
}
|
|
an_object = {
|
|
a_string = "a value"
|
|
an_integer = 1
|
|
a_boolean = true
|
|
}
|
|
```
|
|
|
|
```yaml
|
|
%YAML 1.2
|
|
---
|
|
version: 1.1
|
|
|
|
a_map: # A map is simply a collection of variables of the same type
|
|
|
|
key_1: value 1 # A first attribute
|
|
|
|
key_2: value 2 # A second attribute
|
|
|
|
key_3: value 3 # A third attribute
|
|
|
|
an_object: # A object is just a family
|
|
|
|
a_string: a value # An attribute with a string
|
|
|
|
an_integer: 1 # An attribute with a integer
|
|
|
|
a_boolean: true # A boolean attribute
|
|
...
|
|
```
|
|
|
|
### Variable
|
|
|
|
```hcl
|
|
a_first_string: "a value"
|
|
a_second_string: a_first_string
|
|
```
|
|
|
|
A string, for now, must be enclosed in quotes. But a variable must not be enclosed in quotes.
|
|
|
|
You need to calculate the value directly in Rougail.
|
|
|
|
```yaml
|
|
%YAML 1.2
|
|
---
|
|
version: 1.1
|
|
|
|
a_first_string: "a value" # Take a first value
|
|
|
|
a_second_string:
|
|
description: An expressions is just a string
|
|
default:
|
|
variable: _.a_first_string
|
|
...
|
|
```
|
|
|
|
Or use basic expression (see after).
|
|
|
|
### Expressions
|
|
|
|
Expressions allow for dynamic configuration.
|
|
|
|
#### Basic
|
|
|
|
```hcl
|
|
a_first_string = "a value"
|
|
a_second_string = a_first_string
|
|
a_third_string = "combine ${a_first_string}"
|
|
```
|
|
|
|
A string, for now, must be enclosed in quotes. But a variable must not be enclosed in quotes (see below).
|
|
|
|
You have tu use basic expression in this case:
|
|
|
|
```yaml
|
|
%YAML 1.2
|
|
---
|
|
version: 1.1
|
|
|
|
a_first_string: "a value" # Take a first value
|
|
|
|
a_second_string:
|
|
description: A variable could also use expression to get value
|
|
hcl_quoted_string: false
|
|
default: a_first_string
|
|
|
|
a_third_string: combine ${a_first_string} # An expressions is just a string
|
|
...
|
|
```
|
|
|
|
#### Conditional Expressions
|
|
|
|
```hcl
|
|
a_first_string = "a value"
|
|
a_second_string = a_first_string == "a value" ? 2 : 1
|
|
```
|
|
|
|
A string, for now, must be enclosed in quotes. But a conditional expression must not be enclosed in quotes.
|
|
|
|
You need to calculate the value directly in Rougail.
|
|
|
|
```yaml
|
|
%YAML 1.2
|
|
---
|
|
version: 1.1
|
|
|
|
a_first_string: "a value" # Take a first value
|
|
|
|
a_second_string:
|
|
description: An expressions is just a string
|
|
hcl_quoted_string: false
|
|
default: "a_first_string == \"a value\" ? 2 : 1"
|
|
...
|
|
```
|
|
|
|
#### Function
|
|
|
|
HCL includes a variety of built-in functions that you can use to manipulate data and perform calculations.
|
|
|
|
```hcl
|
|
content = file("config.json")
|
|
```
|
|
|
|
A string, for now, must be enclosed in quotes. But a conditional expression must not be enclosed in quotes.
|
|
|
|
## Block
|
|
|
|
A `block` is a container for configuration.
|
|
|
|
### A basic block
|
|
|
|
There is no equivalent to a `block` in Rougail. To define a `block`, you must define a family and add an `hcl_type` parameter set to `block`.
|
|
|
|
[!NOTE] The `hcl` structural module must be loaded for this type to be recognized.
|
|
|
|
```hcl
|
|
a_block {
|
|
an_attribute = "a value"
|
|
}
|
|
```
|
|
|
|
```yaml
|
|
%YAML 1.2
|
|
---
|
|
version: 1.1
|
|
|
|
a_block:
|
|
description: A block is a family with hcl_type attribute
|
|
hcl_type: block
|
|
|
|
an_attribute: a value # An attribute in a block
|
|
...
|
|
```
|
|
|
|
### A block in a block
|
|
|
|
Blocks can have a tree-like structure, like family in Rougail.
|
|
|
|
```hcl
|
|
a_block {
|
|
a_second_block {
|
|
an_attribute = "a value"
|
|
}
|
|
}
|
|
```
|
|
|
|
```yaml
|
|
%YAML 1.2
|
|
---
|
|
version: 1.1
|
|
|
|
a_block:
|
|
description: A block is a family with hcl_type attribute
|
|
hcl_type: block
|
|
|
|
a_second_block:
|
|
description: We can add a block inside a block
|
|
hcl_type: block
|
|
|
|
an_attribute: a value # An attribute in a block
|
|
...
|
|
```
|
|
|
|
### A block with a label
|
|
|
|
Blocks have a block type and can have zero or more labels.
|
|
|
|
There is no equivalent to a `label` in Rougail. To define a `label`, you must define a family and add an `hcl_type` parameter set to `label`. A `label` must be defined within a `block`.
|
|
|
|
[!NOTE] The `hcl` structural module must be loaded for this type to be recognized.
|
|
|
|
```hcl
|
|
a_block "a_label" {
|
|
an_attribute = "a value"
|
|
}
|
|
```
|
|
|
|
```yaml
|
|
%YAML 1.2
|
|
---
|
|
version: 1.1
|
|
|
|
a_block:
|
|
description: A block is a family with hcl_type attribute
|
|
hcl_type: block
|
|
|
|
a_label:
|
|
description: A label is also a family with hcl_type attribute
|
|
hcl_type: label
|
|
|
|
an_attribute: a value # An attribute in a block
|
|
...
|
|
```
|
|
|
|
### A block with some labels
|
|
|
|
```hcl
|
|
a_block "a_first_label" "a_second_label" {
|
|
an_attribute = "a value"
|
|
}
|
|
```
|
|
|
|
```yaml
|
|
%YAML 1.2
|
|
---
|
|
version: 1.1
|
|
|
|
a_block:
|
|
description: A block is a family with hcl_type attribute
|
|
hcl_type: block
|
|
|
|
a_first_label:
|
|
description: A label is also a family with hcl_type attribute
|
|
hcl_type: label
|
|
|
|
a_second_label:
|
|
description: A label is also a family with hcl_type attribute
|
|
hcl_type: label
|
|
|
|
an_attribute: a value # An attribute in a block
|
|
...
|
|
```
|
|
|
|
### Block inside a label block
|
|
|
|
A `block` could be in a `label` block.
|
|
|
|
```hcl
|
|
a_block "a_first_label" "a_second_label" {
|
|
a_sub_block {
|
|
a_string = "a value"
|
|
}
|
|
}
|
|
```
|
|
|
|
```yaml
|
|
%YAML 1.2
|
|
---
|
|
version: 1.1
|
|
|
|
a_block:
|
|
description: A block is a family with hcl_type attribute
|
|
hcl_type: block
|
|
|
|
a_first_label:
|
|
description: A label is also a family with hcl_type attribute
|
|
hcl_type: label
|
|
|
|
a_second_label:
|
|
description: A label is also a family with hcl_type attribute
|
|
hcl_type: label
|
|
|
|
a_sub_block:
|
|
description: A block insible label block
|
|
hcl_type: block
|
|
|
|
a_string: a value # An attribute in a block
|
|
...
|
|
```
|
|
|
|
### Block with a label inside a block
|
|
|
|
And a `label` block could be in a `block`.
|
|
|
|
```hcl
|
|
a_block {
|
|
a_sub_block "a_first_label" "a_second_label" {
|
|
a_string = "a value"
|
|
}
|
|
}
|
|
```
|
|
|
|
```yaml
|
|
%YAML 1.2
|
|
---
|
|
version: 1.1
|
|
|
|
a_block:
|
|
description: A block is a family with hcl_type attribute
|
|
hcl_type: block
|
|
|
|
a_sub_block:
|
|
description: A label block insible block
|
|
hcl_type: block
|
|
|
|
a_first_label:
|
|
description: A label is also a family with hcl_type attribute
|
|
hcl_type: label
|
|
|
|
a_second_label:
|
|
description: A label is also a family with hcl_type attribute
|
|
hcl_type: label
|
|
|
|
a_string: a value # An attribute in a block
|
|
...
|
|
```
|
|
|
|
### Duplicate block name
|
|
|
|
In Rougail, it's not possible to have two families with the same name.
|
|
|
|
```hcl
|
|
a_block {
|
|
a_sub_block "a_label" {
|
|
an_attribut = [
|
|
"value 1",
|
|
"value2",
|
|
]
|
|
}
|
|
|
|
|
|
a_sub_block "a_label" {
|
|
an_attribut = [
|
|
"value 3",
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
```yaml
|
|
%YAML 1.2
|
|
---
|
|
version: 1.1
|
|
|
|
a_block:
|
|
description: A block is a family with hcl_type attribute
|
|
hcl_type: block
|
|
|
|
a_sub_block_1:
|
|
description: A label block insible block
|
|
hcl_type: block
|
|
hcl_name: a_sub_block
|
|
|
|
a_label:
|
|
description: Add a label
|
|
hcl_type: label
|
|
|
|
an_attribut: # An attribute
|
|
- value 1
|
|
- value2
|
|
|
|
a_sub_block_2:
|
|
description: Add a label
|
|
hcl_type: block
|
|
hcl_name: a_sub_block
|
|
|
|
a_label:
|
|
hcl_type: label
|
|
|
|
an_attribut: # An attribute
|
|
- value 3
|
|
...
|
|
```
|
|
|
|
### Variable block
|
|
|
|
The variable block define variables within your HCL configuration.
|
|
|
|
```hcl
|
|
variable "environment" {
|
|
description = "The deployment environment"
|
|
type = string
|
|
}
|
|
```
|
|
|
|
```yaml
|
|
%YAML 1.2
|
|
---
|
|
version: 1.1
|
|
|
|
variable:
|
|
description: Variable block
|
|
hcl_type: block
|
|
|
|
environment:
|
|
description: The deployment environment
|
|
hcl_type: label
|
|
|
|
description: The deployment environment # The environment description
|
|
|
|
type:
|
|
description: The type description
|
|
hcl_quoted_string: false
|
|
default: string
|
|
...
|
|
```
|