VM instance metadata

The VM instance details are available in the metadata service. You can use the metadata to pass any keys and values, and then request metadata from inside or outside an instance.

Metadata is also used by programs launched on VM start.

How to send metadata

You can pass metadata when you create or change your virtual machine. VM connection data can't change, so it must be passed during creation:

In the CLI, you can specify metadata in three parameters:

  • --metadata-from-file as a file (for example, --metadata-from-file key=path/to/file). This is convenient when passing values consisting of multiple strings.

  • --metadata with a the list of key-value pairs separated by commas (for example, --metadata foo1=bar, foo2=baz).

    If the value is multiline, use \n to split lines: --metadata user-data="#ps1\nnet user Administrator Passw0rd"

  • --ssh-key with an SSH key. Only for Linux-based virtual machines.

    Compute Cloud Create the user yc-user and add the specified SSH key to the list of authorized keys. After the VM is created, you can use this key to connect to it over SSH.

You can combine these parameters, for example:

$ yc compute instance create \
--name my-instance \
--metadata-from-file user-data=metadata.yaml \
--metadata serial-port-enable=1
...

In the API, you specify the metadata in the metadata property as a JSON object, for example:

"metadata": {
  "ssh-keys": "ssh-rsa AAAAB3Nza... user@example.com",
  "serial-port-enable": "1"
}

To enter a line break in values, use the character combination \n.

Important

The metadata, including the user-defined metadata, is available in unencrypted format. If you place confidential information in the metadata, take measures to protect it (for example, by encrypting it).

Keys processed in public images

The list of keys that are processed in Yandex.Cloud's public images depends on the operating system.

  • serial-port-enable: A flag that enables access to the serial console. 1 — enable, 0 (default) — disable.

  • user-data: A string with the user metadata to be processed by the cloud-init agent running on a virtual machine.

    Cloud-init supports different formats for passing metadata, such as cloud-config. In this format, you can pass SSH keys and indicate which user each key is associated with. To do this, specify them in the users/ssh_authorized_keys element.

    #cloud-config
    users:
      - name: user
        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
    

    To pass this data in the request, replace line breaks with \n:

    "metadata": {
      "user-data": "#cloud-config\nusers:\n  - name: user\n    groups: sudo\n    shell: /bin/bash\n    sudo: ['ALL=(ALL) NOPASSWD:ALL']\n    ssh-authorized-keys:\n      - ssh-rsa AAAAB3Nza......OjbSMRX user@example.com\n      - ssh-rsa AAAAB3Nza......Pu00jRN user@desktop"
    }
    
  • ssh-keys: A key for delivering an SSH key to Linux VMs. The key is specified in the format any name>:<SSH key content>, for example, user:ssh-rsa AAAAB3Nza... user@example.com. If you specify multiple keys, only the first one is used.

    Important

    Regardless of the username specified, the key is assigned to the user given in the cloud-init configuration by default. In different images, these users differ.

    If you don't know the default user, find the string containing Authorized keys from in the serial port output. It contains the name of the user assigned the authorized keys.

    If no such string is found, but you see the string no authorized ssh keys fingerprints found for user, it means that you incorrectly passed your SSH key. Check the format again or try passing the SSH keys in the user-data field.

user-data: A string with user metadata to be processed by the Cloudbase-Init agent. This agent supports various data formats, such as PowerShell scripts that set the administrator password:

"metadata": {
  "user-data": "#ps1\nnet user Administrator Passw0rd"
}