VM instance metadata

Information about VM instances is stored on the metadata server. You can request metadata from inside or outside an instance using the API or CLI.

Metadata is used by programs that are run when the VM starts (for example, to make a list of users or specify a public SSH key to connect to the VM).

From inside the VM, the metadata server is accessible at the IP address 169.254.169.254.

Currently, the Yandex.Cloud metadata server returns metadata in the Google Compute Engine and Amazon EC2 formats.

Metadata format when creating a VM

Metadata is set in the metadata field as key:value pairs. Only a string can be used as a value. If you need to pass multiple strings, separate them with the line break character \n.

You can pass metadata values to the CLI as the following file: --metadata-from-file key=path/to/file. This is convenient when passing values consisting of multiple strings.

You can specify any keys. The keys you need to specify depend on the program that will handle them on your VM. For example, in Linux images provided by Yandex.Cloud, the cloud-init program is used.

Important

Metadata, including user-defined metadata, is stored unencrypted. Anyone who can connect to a VM can get this metadata. If you place confidential information in the metadata, take measures to protect it (for example, by encrypting it).

Programs that process metadata in Yandex.Cloud images

In Linux public images, the program used to configure VMs by default is cloud-init.

In Windows public images, it is Cloudbase-Init.

Using cloud-init

The cloud-init program handles metadata that was passed in the user-data and ssh-keys keys.

user-data

All user-defined metadata for cloud-init should be passed in the user-data key. There are several formats of metadata supported by cloud-init, such as cloud-config.

You can use user-data to pass SSH keys to a VM and specify which user each key belongs to. To do this, pass them in the users/ssh_authorized_keys element. For more information, see the section Users and Groups in the cloud-init documentation.

Example of metadata in the cloud-config format:

#cloud-config
users:
  - name: demo
    groups: sudo
    shell: /bin/bash
    sudo: ['ALL=(ALL) NOPASSWD:ALL']
    ssh-authorized-keys:
      - ssh-rsa AAAAB3Nza......OjbSMRX user@example.com
      - ssh-rsa AAAAB3Nza......Pu00jRN user@desktop

ssh-keys

To pass SSH keys to a VM, use the ssh-keys field. cloud-init will handle only the first key in the list. The key will be assigned to the user specified in the cloud-init configuration by default. In different images, these users differ.

If you aren't sure which user is set by default, we recommend passing the SSH keys in the user-data field.