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 supporting variablesFields supporting variables

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

• instance_template.fqdn: Host FQDN.
• instance_template.hostname: Host name.
• instance_template.metadata: VM metadata. Variables can only be used in the metadata field key values.
• instance_template.name: VM name.
• instance_template.labels: VM 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:

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

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 converts them according to the rules below.

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 allowed fields:
     • The {short_zone_var_{instance.zone_id}} user-defined variable and the {instance.index} system variable are specified in the instance_template.name field.
     • The system {instance.index} variable is specified in the instance_template.hostname field.

   ...
   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 will be converted to {short_zone_var_ru-central1-a}.
     • The {instance.index} system variable will be converted to 1.
   • In the instance_template.hostname field, the {instance.index} system variable will be converted to 1.

3. At Stage 2, Instance Groups will convert the resulting variables to the values listed 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 will be converted to rc1a.

See alsoSee also

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