Variables in an instance template

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 variablesFields 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 substitutionStages 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 1Value 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 2Value 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 variablesConversion 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 stagesExample 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 alsoSee also

• Specification of an instance group in YAML format
• Instance template
• Creating a group of instances with fixed IP addresses