Variables in an instance template

Fields that support variables
Stages of variable substitution
- First stage of value substitution
- Second stage of value substitution
Conversion of variables
Example of running the substitution stages

Instance Groups lets you create a group of instances of the same type from a template. To use different characteristics for such instances, use the substitution mechanism for the system and user-defined variables in the template.

A system variable is a value that Instance Groups calculates during instance creation and inserts it into the template for further use.

A user-defined variable is a value that Instance Groups takes from a list. The list is made by the user in advance and its variables are described in key:value format.

Fields that support variables

The instance template is described in a YAML file using the instance_template key. You can specify the system and user-defined variables instead of the values of the following template fields:

instance_template.fqdn: Host FQDN.
instance_template.hostname: Hostname.
instance_template.metadata: Instance metadata. Variables can only be used in the metadata field key values.
instance_template.name: Instance name.
instance_template.labels: Instance labels. Variables can only be used in the labels field key values.
instance_template.boot_disk_spec.disk_id: Boot disk ID.
instance_template.boot_disk_spec.disk_spec.description: Boot disk description.
instance_template.boot_disk_spec.disk_spec.image_id: Boot disk image ID.
instance_template.boot_disk_spec.disk_spec.snapshot_id: Boot disk snapshot ID.
instance_template.boot_disk_spec.disk_spec.type_id: Boot disk type.
instance_template.network_interface_specs.primary_v4_address_spec.one_to_one_nat_spec.address: Configuration of the external IPv4 address.
instance_template.network_interface_specs.primary_v6_address_spec.one_to_one_nat_spec.address: Configuration of the external IPv6 address.
instance_template.placement_policy.placement_group_id: Placement group ID.
instance_template.secondary_disk_specs.disk_id: Secondary disk ID.
instance_template.secondary_disk_specs.disk_spec.description: Secondary disk description.
instance_template.secondary_disk_specs.disk_spec.image_id: Secondary disk image ID.
instance_template.secondary_disk_specs.disk_spec.snapshot_id: Secondary disk snapshot ID.
instance_template.secondary_disk_specs.disk_spec.type_id: Secondary disk type.

Stages of variable substitution

Instance Groups replaces system and user-defined variables with values in two stages:

Replacing system variables with calculated values.
Replacing user-defined variables with values from the list.

Conversion can occur in multiple stages. In this case, the value obtained in the first stage is a variable for the second stage.

An example of substitution stages is given below.

First stage of value substitution

Instance Groups only replaces the fixed list of system variables with calculated values:

System variable	Description
`{instance_group.id}`	Instance group ID.
`{instance_group.labels.label_key}`	Value of the label with the `label_key` key.
`{instance.index}`	The unique instance number in the group. Possible values: 1 to N, where N is the number of instances in the group.
`{instance.index_in_zone}`	Instance number in the zone. It's unique for a specific group of instances within a zone.
`{instance.short_id}`	Instance ID that is unique within the group. Consists of four letters.
`{instance.zone_id}`	Zone ID.

For example, when creating an instance group, Instance Groups assigns an ID to the group and substitutes the {instance_group.id} of each instance with it.

Second stage of value substitution

To make sure that Instance Groups substitutes values at this stage, make a list of user-defined variables in key:value format in advance.

At this stage, Instance Groups:

Compares variables with the keys from the custom list.
Sets them to the values specified in the keys.

Conversion of variables

System and user-defined variables are specified as values for template fields in curly brackets {}. Instance Groups converts them according to the rules below.

Template field value	Field value after conversion	Conversion description
`{specified_key}`	`value`	The value is inserted from the list created in advance.
`{unknown_key}`	`{unknown_key}`	If the specified key is not supported by the substitution mechanism, Instance Groups won't replace it.
`{{specified_key}}`	`{specified_key}`	At the first stage, the internal level of brackets is removed.
`{{unknown_key}}`	`{{unknown_key}}`	A key that is not supported by the substitution mechanism won't change.

Example of running the substitution stages

The instance template specifies:
- The list of user-defined variables in key:value format in the variables section.
- The system and user-defined variables in the supported fields:
  - The instance_template.name field specifies the {shot_zone_var_{instance.zone_id}} user-defined variable and the {instance.index} system variable.
  - The instance_template.hostname field specifies the {instance.index} system variable.
```
...
variables:
  - key: shot_zone_var_ru-central1-a
    value: rc1a
  - key: shot_zone_var_ru-central1-b
    value: rc1b
  - key: shot_zone_var_ru-central1-c
    value: rc1c
instance_template:
  name: production-{shot_zone_var_{instance.zone_id}}-{instance.index}
  hostname: production-{instance.index}
  platform_id: standard-v2
...
```
During the first stage, Instance Groups replaces the system variables with the calculated values.
- In the instance_template.name field:
  - The {shot_zone_var_{instance.zone_id}} variable is converted to the {shot_zone_var_ru-central1-a} variable.
  - The {instance.index} system variable is converted to index 1.
- In the instance_template.hostname field, the {instance.index} system variable is converted to index 1.
```
...
variables:
  - key: shot_zone_var_ru-central1-a
    value: rc1a
  - key: shot_zone_var_ru-central1-b
    value: rc1b
  - key: shot_zone_var_ru-central1-c
    value: rc1c
instance_template:
  name: production-{shot_zone_var_ru-central1-a}-1
  hostname: production-1
  platform_id: standard-v2
...
```

At the second stage, Instance Groups converts the resulting variables to the values from the list in the variables section:

In the instance_template.name field: the {shot_zone_var_ru-central1-a} variable is converted to the value rc1a.

...
variables:
  - key: shot_zone_var_ru-central1-a
    value: rc1a
  - key: shot_zone_var_ru-central1-b
    value: rc1b
  - key: shot_zone_var_ru-central1-c
    value: rc1c
instance_template:
  name: production-rc1a-1
  hostname: production-1
  platform_id: standard-v2
...