Contact UsGet started
© 2024 Direct Cursus Technology L.L.C.

VM metadata

Written by
Improved by
Updated at December 16, 2024

VM instance details are available in the metadata service. You can use metadata to provide any keys and values, and then request the metadata from inside or outside a VM instance. For more information about setting up a metadata service, see Setting up metadata service parameters for a VM instance.

Metadata is also used by apps that launch at VM startup.

Metadata formats supported inside VM

From inside a VM instance, metadata is available in the following formats:

Compute Cloud VMs support the following VM metadata service settings:

  • aws-v1-http-endpoint: Provides access to metadata using AWS format (IMDSv1). Possible values: enabled, disabled. If set to disabled, the metadata request will fail with error 400 (BadRequest). The default value is enabled.

  • aws-v1-http-token: Enables using the AWSv1 (IMDSv1) metadata to get a token of the service account connected to the VM. Possible values: enabled, disabled. If set to disabled, the token request will fail with error 400 (BadRequest). The default value is disabled.

    Note

    The IMDSv1 format has a number of security flaws; therefore, the aws-v1-http-token parameter is disabled by default. The most severe drawback of IMDSv1 is its high risk of certain attacks, e.g., SSRF. You can read more about it in the AWS official blog. To change the default behavior of this parameter, contact support.

    The most secure way to get a token in Yandex Cloud is to use Google Compute Engine format, which provides an extra header for protection against SSRF.

  • gce-http-endpoint: Provides access to metadata using Google Compute Engine format. Possible values: enabled, disabled. If set to disabled, the metadata request will fail with error 400 (BadRequest). The default value is enabled.

  • aws-v1-http-token: Enables using the Google Compute Engine metadata to get a token of the service account connected to the VM. Possible values: enabled, disabled. If the disabled value is set for the option, then the request to get a token will end with error 400 (BadRequest). The default value is enabled.

You can get the values of the metadata service parameters together with the VM information using the CLI and API.

How to send metadata

You can provide metadata when creating or updating VMs. Data for connection to a VM can only be provided when creating the VM; moreover, in a VM running Linux, a public SSH key must be provided for each user.

Note

When creating VM users via metadata using the user-data key, all users, including the default one specified under Access, will be overwritten. To avoid this, specify the data of all users in the user-data key, including the user specified under Access.

Metadata is provided under Metadata in Key:Value format.

For example, to create multiple users in the virtual machine OS, add the user-data key and specify the following configuration in it:

#cloud-config
datasource:
  Ec2:
    strict_id: false
ssh_pwauth: no
users:
- name: <username_1>
  sudo: 'ALL=(ALL) NOPASSWD:ALL'
  shell: /bin/bash
  ssh_authorized_keys:
  - <public_SSH_key_1>
- name: <username_2>
  sudo: 'ALL=(ALL) NOPASSWD:ALL'
  shell: /bin/bash
  ssh_authorized_keys:
  - <public_SSH_key_2>
...
- name: <username_n>
  sudo: 'ALL=(ALL) NOPASSWD:ALL'
  shell: /bin/bash
  ssh_authorized_keys:
  - <public_SSH_key_n>
runcmd: []

Note

When creating VM users via metadata using the user-data key, all users, including the default one specified under --ssh-key, will be overwritten. To avoid this, specify the data of all users in the user-data key, including the user specified under --ssh-key.

In the CLI, you can provide metadata in any of the three parameters:

  • --metadata-from-file: As a configuration file in this format: --metadata-from-file key=<file_path>. Use this method to conveniently deliver a value consisting of several lines.

    For example, to add several users to a VM at the same time, describe the configuration in a YAML file:

    #cloud-config
datasource:
  Ec2:
    strict_id: false
ssh_pwauth: no
users:
- name: <username_1>
  sudo: 'ALL=(ALL) NOPASSWD:ALL'
  shell: /bin/bash
  ssh_authorized_keys:
  - <public_SSH_key_1>
- name: <username_2>
  sudo: 'ALL=(ALL) NOPASSWD:ALL'
  shell: /bin/bash
  ssh_authorized_keys:
  - <public_SSH_key_2>
...
- name: <username_n>
  sudo: 'ALL=(ALL) NOPASSWD:ALL'
  shell: /bin/bash
  ssh_authorized_keys:
  - <public_SSH_key_n>
runcmd: []

  • --metadata: As a comma-separated list of key=value pairs, e.g., --metadata foo1=bar,foo2=baz.

    For a multiline value, use \n as a separator: --metadata user-data="#ps1\nnet user Administrator Passw0rd".

  • --ssh-key: SSH key. Only for Linux VMs.

    Compute Cloud creates the yc-user user and adds 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
...

Note

When creating VM users via metadata using the user-data key, all users, including the default one specified under ssh-keys, will be overwritten. To avoid this, specify the data of all users in the user-data key, including the user specified under ssh-keys.

In Terraform, you can specify metadata in three ways:

  • As a separate file with user metadata to process by the cloud-init agent. To do this, undermetadata, specify the path to the file with user metadata, such as cloud-init.yaml:

    ...
metadata = {
  user-data = "${file("cloud-init.yaml")}"
}
...
    Sample contents of the cloud-init.yaml file
    #cloud-config
datasource:
  Ec2:
    strict_id: false
ssh_pwauth: no
users:
- name: <username_1>
  sudo: 'ALL=(ALL) NOPASSWD:ALL'
  shell: /bin/bash
  ssh_authorized_keys:
  - <public_SSH_key_1>
- name: <username_2>
  sudo: 'ALL=(ALL) NOPASSWD:ALL'
  shell: /bin/bash
  ssh_authorized_keys:
  - <public_SSH_key_2>
...
- name: <username_n>
  sudo: 'ALL=(ALL) NOPASSWD:ALL'
  shell: /bin/bash
  ssh_authorized_keys:
  - <public_SSH_key_n>
runcmd: []

  • Under metadata, as a line with user metadata. For a multiline value, use \n as a separator. For example:

    ...
metadata = {
  user-data = "#cloud-config\nusers:\n  - name: <username>\n    groups: sudo\n    shell: /bin/bash\n    sudo: 'ALL=(ALL) NOPASSWD:ALL'\n    ssh_authorized_keys:\n      - <SSH_key_contents>"
}
...

  • Only for Linux VMs. Under ssh-keys, specify the username and the SSH key to access Linux VMs. Enter your username and the contents of your SSH key as follows:

    ...
metadata = {
  ssh-keys = "<username>:<SSH_key_contents>"
}
...

    If you are using an out-of-the-box public image from Yandex Cloud Marketplace, the specified username does not matter. The key will be assigned to the user specified in the cloud-init configuration by default. Such users vary depending on an image.

    If you do not know the default user, find the string containing Authorized keys from in the serial port output. It will contain the name of the user the authorized keys are assigned to.

    If you cannot find this string but you see the no authorized ssh keys fingerprints found for user string, it means you have provided your SSH key incorrectly. Check the format once again or try providing the SSH keys in the user-data field.

In the API, specify the metadata in the metadata property as a JSON object, e.g.:

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

For a line break, use \n.

Warning

The metadata, including the user-defined one, is available in unencrypted format. If the metadata contains sensitive information, make sure to protect it, e.g., through encryption.

Keys processed in public images

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

  • serial-port-enable: Flag enabling access to the serial console. Use 1 to enable or 0 (default) to disable access.

  • enable-oslogin: Flag enabling access via OS Login. Use true to enable or false (default) to disable access.

  • install-unified-agent: Flag that installs the agent for collecting Unified Agent metrics and logs. Use 1 to install or 0 (default) not to install the agent.

  • user-data: String with the user metadata to be processed by the cloud-init agent running on a VM instance.

    Cloud-init supports different metadata transmission formats, e.g., cloud-config. In this format, you can provide SSH keys and indicate which user each key is associated with. To do this, specify them in the users/ssh_authorized_keys section:

    #cloud-config
users:
  - name: <username>
    groups: sudo
    shell: /bin/bash
    sudo: 'ALL=(ALL) NOPASSWD:ALL'
    ssh_authorized_keys:
      - <public_SSH_key_1>
      - <public_SSH_key_2>
      - ...

    Where:

    • name: VM user name.

    • ssh_authorized_keys: List of public SSH keys for VM access.

      Key example: ssh-ed25519 AAAAB3Nza...Pu00jRN user@desktop.

    To provide 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-ed25519 AAAAB3Nza......OjbSMRX user@example.com\n      - ssh-ed25519 AAAAB3Nza...Pu00jRN user@desktop"
}

    In the user-data key, you may also describe the software installation scripts to be executed when creating a new VM.

  • ssh-keys: Key for delivering the SSH key to Linux VMs through Terraform. Use this format: <username>:<SSH_key_contents>, e.g., user:ssh-ed25519 AAC4NzaC1... user@example.com. If you specify multiple keys, only the first one will be used.

user-data: 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"
}

Identity document

When creating a VM, an identity document that stores information about the VM is generated. It contains IDs of the VM, Marketplace product, disk image, etc. VMs can request information about themselves from the metadata service.

To request an identity document:

  1. Connect to the VM:

    ssh <VM_IP_address>

  2. You can get an identity document in Google Compute Engine and Amazon EC2 formats. Run this command:

    curl \
  --header Metadata-Flavor:Google 169.254.169.254/computeMetadata/v1/instance/vendor/identity/document

    curl http://169.254.169.254/latest/vendor/instance-identity/document

    Response example:

    {"instanceId":"fhmm5252k8vl********","productCodes":null,"imageId":"fd8evlqsgg4e********","productIds":["f2e3ia802lab********"],"createdAt":"2023-05-29T09:46:59Z","version":"2023-03-01"}

Note

If you created your VM before June 9, 2023, and you cannot get its identity document, stop and restart the VM.

Signed identity documents

If you are going to use the contents of an identity document for critical tasks, check the contents and validate the document before using it.

Apart from identity documents, the VM metadata service provides their cryptographic signatures. You can use these signatures to verify a document's origin, validity, and integrity.

  1. Connect to the VM:

    ssh <VM_IP_address>

  2. Get an RSA signature from the VM metadata and save it to a file named rsa2048:

    • GCE:

      curl \
  --header Metadata-Flavor:Google 169.254.169.254/computeMetadata/v1/instance/vendor/identity/rsa > rsa2048

    • EC2:

      curl http://169.254.169.254/latest/vendor/instance-identity/rsa > rsa2048

  3. Create a file named certificate and add a public certificate to it:

  4. Verify the signature and save the contents of the document to a file named document:

    openssl smime -verify -in rsa2048 -inform PEM -certfile certificate -noverify | tee document

    If the signature is valid, you will see a message saying Verification successful.

  1. Connect to the VM:

    ssh <VM_IP_address>

  2. Get a signature from the VM metadata and save it to a file named dsa2048:

    • GCE:

      curl \
  --header Metadata-Flavor:Google 169.254.169.254/computeMetadata/v1/instance/vendor/identity/dsa > dsa2048

    • EC2:

      curl http://169.254.169.254/latest/vendor/instance-identity/dsa > dsa2048

  3. Create a certificate file and save a public certificate to it:

    -----BEGIN CERTIFICATE-----
MIIERjCCA+ugAwIBAgIULIUmuptqf9Pz7nMGMHeW+BPNneYwCwYJYIZIAWUDBAMC
MAAwHhcNMjMwNjA3MDY1NjI0WhcNMzMwNjA0MDY1NjI0WjAAMIIDRjCCAjkGByqG
SM44BAEwggIsAoIBAQDFyteKPnUOauqiHzsLCw2Z//c1IjSqVVPpIbETQ1NUCsUI
o6+at1VkxJ76K/HqvFlhC87nSGWuQMgflQXcVIEQ8c0wnQGRj4lwkkjm8WClo4xv
t/FsNyv4uEcPgcz45A2YxE4+5odjicKMCz4pPW+kc9t4BiKw4I9uGySBhA1p21e+
fmR4AzDSHdHGRlvlYOfYANZlVeWm+qLsb+VfyeETTOD+ooMA9Y4ue3dw2l8Clib8
WummF2PNRnnOeEFGbwZErtdObla2TjdNzFWc6QWo1EcqqkBXG1TutY/FgNcTj+Ps
nFoUu4ZIy7o8p8YgzyffSCQbP5ppRGpfh4DuIS+vAiEA8tkwKyKmcCxTWnpRNWlY
O6kUanHgEQczpLtP3mDvcdUCggEAMhbW4syX5p7X1qs0OnFCLcd4tYA2DnR1dLu3
ZPusUh6c9+cH3ICEnK22KB1nplMAHDyXjtV2rCvIGlNUcT6OkSulnkvNE185cfM0
UKofG4t6VJNpa8bngF7Ccyf6QBPcUzigHv+QDQDZuA4k3IcQp0hC9ppOaN6J9rKp
5cSPyLzJ2vyY6mG650omxgnwG4OGZSRX8c1JN/MvIj79m3LqM7civ8l6ljnC+LNm
1T7mcgZcf9iYc5+OWICoeDtFUdr+qsNIXonIMku6FpJu0pBgVgE6GI+nD4oaXSQS
bckxB24DEYvTlVALuXqPS8MZyQZz5ltoI8xnbEOMqtU3IPox1AOCAQUAAoIBADcS
Pt2SC+cGUCKNhrPquESB2/dZKUDuyEtYIYMidfoyoBGhz2QuqOqf5tEcLY9gCeMP
NxmaXW1AQtcAX/+tyCZrVxEc31btW3alLmu/NtKxmb6PRshsASI/LIE1wH82TV8C
4ymFDyKUGCb5AWN+Ziv5AP5/6Q08awQ7YAuz/sw0xOMqDuUfYkLerPEuQg5Sozs0
DWucS/ex7l+VqNAZUBZykta961bhplIDTRG05YD3Lz0w/WIBMdZzzolA7F3jgFJg
rCfZwQeDbf1iorfxRS5DqR0Vt7XE6/yqRUzDjOMctKY68jLZGFfOfTQ9iX2R9K/f
7kJPxaHnA+WWo13ExwGjUzBRMB0GA1UdDgQWBBTj+x+t2VJhAWI57o9xRwMOeTFj
mzAfBgNVHSMEGDAWgBTj+x+t2VJhAWI57o9xRwMOeTFjmzAPBgNVHRMBAf8EBTAD
AQH/MAsGCWCGSAFlAwQDAgNIADBFAiAX2ABj/9ea1Q4ssAgIGkA4vJywoUoT4Sbg
LFFIJGlNWgIhAO0b749SY5+6UMEOLsxgvNzKKcv58BKADfBdJAXE6fRk
-----END CERTIFICATE-----

  4. Verify the signature and save the contents of the document to a file named document:

    openssl smime -verify -in dsa2048 -inform PEM -certfile certificate -noverify | tee document

    If the signature is valid, you will see a message saying Verification successful.

  1. Connect to the VM:

    ssh <VM_IP_address>

  2. Get a base64 signature from the VM metadata and save it to a file named signature:

    • GCE:

      curl \
  --header Metadata-Flavor:Google 169.254.169.254/computeMetadata/v1/instance/vendor/identity/base64 | \
  base64 -d >> signature

    • EC2:

      curl http://169.254.169.254/latest/vendor/instance-identity/base64 | base64 -d >> signature

  3. Get an identity document and save it to a file named document:

    • GCE:

      curl \
  --header Metadata-Flavor:Google 169.254.169.254/computeMetadata/v1/instance/vendor/identity/document > document

    • EC2:

      curl http://169.254.169.254/latest/vendor/instance-identity/document > document

  4. Create a certificate file and save a public certificate to it:

    -----BEGIN CERTIFICATE-----
MIIC4TCCAcmgAwIBAgIUP0zcGO1MeRwze8VdSMEt/OdBXoIwDQYJKoZIhvcNAQEL
BQAwADAeFw0yMzA2MDcwNjU4MTBaFw0zMzA2MDQwNjU4MTBaMAAwggEiMA0GCSqG
SIb3DQEBAQUAA4IBDwAwggEKAoIBAQDw6TvAvrbJvY4tzIIuDnLEVfRUW4BZJD3y
K8fyyxXrYDvC69RKCKk9+TQhnUOLhZNlDST4HFfSPlakOjXUduyJE5M1EmoLAstN
81aP3TejseDavxmaNijXRsa9E731T5H+zo44PgAHfQJmiD7rtcr+QOIosKUB2dwp
F2acp9hLKd389BfNctziG0Oxq7hlISTDBnhzBg7eKuqWtShjVW5RqQvp3bARfUPa
RWdYjmZvR+AnmozV1SGnpAnatzhnF6tNAb5XSEw49tumsX1D4A11J6mtrafO6bsP
wdIPwy9W15iCszUNlFcdBaZhESc34VbyCyLMvA5T0Uj1FJHz1RFlAgMBAAGjUzBR
MB0GA1UdDgQWBBQq0z6Vcmjcn8wnRTwKGSm5YGas9TAfBgNVHSMEGDAWgBQq0z6V
cmjcn8wnRTwKGSm5YGas9TAPBgNVHRMBAf8EBTADAQH/MA0GCSqGSIb3DQEBCwUA
A4IBAQBplippQ/Pxn7AkuwOTSwSTeJ7S+rMSb6iSL9chNHetanft0Ikr5BDsSrd6
TeHV0sEMilDIjX0EjSNHwYtYrDPk6cGjkzDTYb6/U10c5Xhwi0g7/lMH/RPihPz5
co80VEqXWlgfgHuE7/cAiTJ61PiFD9oI494bQcIISQNDfbUUiYfn32+8nK20rn8C
w7PbGoIv6zz6A0c6DJT7yXJF5sAHgX4M03Oi9edzQ077ZOboXSuUKe4VfHIpjTjZ
0sM/NbG5BFstyetVc3FZOGWGukTRb0C0GSASOm6hCyh5ctmpwlS4menc/OAx9BYO
r9ZBjEa0oLFVV0pP5Tj4Gf1DDpuJ
-----END CERTIFICATE-----

  5. Extract a public key from the certificate and save it to a file named key:

    openssl x509 -pubkey -noout -in certificate >> key

  6. Verify the signature and save the contents of the document to a file named document:

    openssl dgst -sha256 -verify key -signature signature document

    If the signature is valid, you will see a message saying Verified OK.

Map the identity document from the VM metadata to the document saved to the file:

curl http://169.254.169.254/latest/vendor/instance-identity/document | \
openssl dgst -sha256

openssl dgst -sha256 < document

If they have the same hash, the identity document saved to the file matches the document from the VM metadata.

See also

Previous
Statuses
Next
VM maintenance policies