Contact UsGet started
© 2024 Direct Cursus Technology L.L.C.

Variables in an instance template

Written by
Updated at July 9, 2024

With Instance Groups, you can create a group of VM instances of the same type from a template. To use different specifications for such instances, use the substitution feature for the system and user-defined variables in the template. For example, you can use variables and tags to create an instance group with fixed IP addresses.

A system variable is a value calculated by Instance Groups when a VM is created; it is then inserted into the template for further use.

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

Fields that support variables

A VM 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

In Instance Groups, system and user-defined variables get replaced with values in two stages:

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

Value conversion may also occur in multiple stages. In this case, the value obtained in the first stage is a variable for the second stage.

You can see an example of substitution stages below.

Value substitution: Stage 1

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

System variable Description
{instance_group.id} Instance group ID
{instance_group.labels.label_key} Value of the instance group label with label_key as its key.
{instance.index} Unique instance number in the group.
{instance.index_in_zone} Instance number in the zone. It is unique for a specific group
of instances within a zone.
{instance.labels.another_label_key} Value of the instance label with another_label_key as its key.
{instance.short_id} Instance ID that is unique within the group. It consists of four alphabetic characters.
{instance.tag} Tag of an instance in the group within the availability zone. For more information, see the Allocation policy.
{instance.zone_id} Zone ID

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

Value substitution: Stage 2

To enable Instance Groups to substitute values at this stage, provide a list of user-defined variables in key:value format in advance.

At this stage, Instance Groups will do the following:

  1. Compare variables with the keys from the user-provided list.
  2. Replace the variables with 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 will convert 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 feature, Instance Groups will not replace it.
{{specified_key}} {specified_key} At stage 1, the internal level of brackets is removed.
{{unknown_key}} {{unknown_key}} Keys that are not supported by the substitution feature will not change.

Example of running substitution stages

  1. Let's assume the instance template specifies the following:

    • List of user-defined variables in key:value format in the variables section.
    • System and user-defined variables in the supported fields:
      • The instance_template.name field specifies the {short_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: short_zone_var_ru-central1-a
    value: rc1a
  - key: short_zone_var_ru-central1-b
    value: rc1b
  - key: short_zone_var_ru-central1-d
    value: rc1d
instance_template:
  name: production-{short_zone_var_{instance.zone_id}}-{instance.index}
  hostname: production-{instance.index}
  platform_id: standard-v3
...

  2. At stage 1, Instance Groups will replace the system variables with the calculated values:

    ...
variables:
  - key: short_zone_var_ru-central1-a
    value: rc1a
  - key: short_zone_var_ru-central1-b
    value: rc1b
  - key: short_zone_var_ru-central1-d
    value: rc1d
instance_template:
  name: production-{short_zone_var_ru-central1-a}-1
  hostname: production-1
  platform_id: standard-v3
...

    Where:

    • In the instance_template.name field:
      • The {short_zone_var_{instance.zone_id}} variable is converted to the {short_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.

  3. At stage 2, Instance Groups will convert the resulting variables to the values from the list in the variables section:

    ...
variables:
  - key: short_zone_var_ru-central1-a
    value: rc1a
  - key: short_zone_var_ru-central1-b
    value: rc1b
  - key: short_zone_var_ru-central1-d
    value: rc1d
instance_template:
  name: production-rc1a-1
  hostname: production-1
  platform_id: standard-v3
...

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

See also

Previous
Instance template
Next
Overview