Creating a VM with metadata from environment variables

With the Yandex Cloud CLI, you can create a VM whose metadata will contain values set in environment variables. The cloud-init agent running on the VM will process the metadata configuration you set in the user-data key.

This use case demonstrates creating a VM on Ubuntu 22.04 LTS with a preinstalled Nginx web server. When executing the CLI command, the local user name and SSH key values will be provided to the VM metadata through substitution from the USER_NAME and SSH_KEY variables of the environment the command is executed in.

Also, these two variables from the data configuration section will be provided to the VM metadata: var1 set to value1 and var2 set to value2. These variables and their values will be available in the user-data folder of the metadata service from inside the VM after you create it.

To create a VM with metadata from environment variables:

1. Specify the environment variables containing the VM local user's name and SSH key; these will be substituted into the VM metadata when the Yandex Cloud CLI command is executed later on:

   export USER_NAME="<username>"
   export SSH_KEY="<SSH_key>"
   

2. Create a file named metadata.yaml and paste into it the following metadata configuration for the new VM:

   metadata.yaml

   #cloud-config
   datasource:
     Ec2:
       strict_id: false
     data:
       var1: value1
       var2: value2
   ssh_pwauth: no
   users:
   - name: $USER_NAME
     sudo: 'ALL=(ALL) NOPASSWD:ALL'
     shell: /bin/bash
     ssh_authorized_keys:
     - $SSH_KEY
   write_files:
     - path: "/usr/local/etc/startup.sh"
       permissions: "755"
       content: |
         #!/bin/bash
   
         apt-get update
         apt-get install -y nginx
         service nginx start
         sed -i -- "s/ nginx/ Yandex Cloud - $$HOSTNAME/" /var/www/html/index.nginx-debian.html
       defer: true
   runcmd:
     - ["/usr/local/etc/startup.sh"]
   packages:
     - yq
   

3. Create a virtual machine:

   CLI

   If you do not have the Yandex Cloud CLI yet, install and initialize it.

   The folder specified in the CLI profile is used by default. You can specify a different folder through the --folder-name or --folder-id parameter.

   yc compute instance create \
     --name my-vm \
     --hostname <host_name> \
     --zone <availability_zone> \
     --network-interface subnet-name=<subnet_name>,nat-ip-version=ipv4,security-group-ids=<security_group_ID> \
     --create-boot-disk image-folder-id=standard-images,image-family=ubuntu-2204-lts \
     --metadata-from-file user-data="<path_to_configuration_file>"
   

   Where:

   • --name: Name of the new VM, e.g., my-vm.

   • --hostname: Host name for the new VM. This is an optional parameter. If omitted, the VM ID will be used as the host name.

   • --zone: Availability zone the new VM will reside in.

   • --network-interface: Network interface settings for the new VM:

     • subnet-name: Name of the subnet in the availability zone specified in the --zone parameter.
     • security-group-ids: Security group ID.

   • --metadata-from-file: The user-data key with the path to the cloud-config YAML configuration file for value. e.g., --metadata-from-file user-data="/home/user/metadata.yaml".

     Note

     Note that the CLI command for the HOSTNAME variable will not substitute its value into the metadata. Instead, the $HOSTNAME variable name will be provided to the cloud-init configuration when executing the CLI command; the hostname value of the new VM will be substituted in place of that variable later what creating the VM.

     This is why the HOSTNAME variable is specified using the two-dollar syntax in the user-data key: $$HOSTNAME. For more information, see Specifics of providing environment variables in metadata via the CLI.

   Result

   done (36s)
   id: epd8m0fqvkuu********
   folder_id: b1gt6g8ht345********
   created_at: "2025-01-01T14:24:37Z"
   name: my-vm
   zone_id: ru-central1-b
   platform_id: standard-v2
   resources:
     memory: "2147483648"
     cores: "2"
     core_fraction: "100"
   status: RUNNING
   metadata_options:
     gce_http_endpoint: ENABLED
     aws_v1_http_endpoint: ENABLED
     gce_http_token: ENABLED
     aws_v1_http_token: DISABLED
   boot_disk:
     mode: READ_WRITE
     device_name: epd60hoo48qj********
     auto_delete: true
     disk_id: epd60hoo48qj********
   network_interfaces:
     - index: "0"
       mac_address: d0:0d:8b:01:fa:fd
       subnet_id: e2lqsms4cdl3********
       primary_v4_address:
         address: 192.168.15.14
         one_to_one_nat:
           address: 51.250.**.**
           ip_version: IPV4
       security_group_ids:
         - enpbtvidu0g0********
   serial_port_settings:
     ssh_authorization: OS_LOGIN
   gpu_settings: {}
   fqdn: my-web-server.ru-central1.internal
   scheduling_policy: {}
   network_settings:
     type: STANDARD
   placement_policy: {}
   hardware_generation:
     legacy_features:
       pci_topology: PCI_TOPOLOGY_V1
   

   For more information about the yc compute instance create command, see the CLI reference.

4. Save the public IP address of the VM you created into the EXT_IP variable.

   EXT_IP=$(yc compute instance get my-vm --jq '.network_interfaces[0].primary_v4_address.one_to_one_nat.address')
   

5. Connect to the VM over SSH:

   ssh $USER_NAME@$EXT_IP
   

6. Get the values of the variables you previously provided to the metadata from inside the VM. To do this, run the following requests in the VM terminal:

   export var1=$(curl -sf -H Metadata-Flavor:Google 169.254.169.254/latest/user-data | yq .datasource.data.var1)
   export var2=$(curl -sf -H Metadata-Flavor:Google 169.254.169.254/latest/user-data | yq .datasource.data.var2)
   echo $var1 $var2
   

   Result:

   value1 value2
   

For other configuration examples for user-data, see Examples.

See alsoSee also

• VM metadata
• Creating a VM instance with access to a Yandex Lockbox secret
• Creating a VM with a custom configuration script