How to access instance metadata from within a VM

The instance metadata service (IMDS) provides information about a running virtual machine (VM) instance, including instance metadata, labels, resources, user and network data.

The legacy /mnt/cloud-metadata mount on older Nebius VM images is deprecated and will be removed on September 30, 2026. After that date, use only the HTTP-based IMDS described in this article. To migrate, replace any reads from /mnt/cloud-metadata with the equivalent HTTP requests to IMDS.

How to access IMDS

IMDS is available only from within a VM instance itself. Once you connect to a VM, use the following base URL to request metadata:

http://metadata.nebius.internal

All IMDS requests must use the GET method and include the Metadata: true header. Requests without this header return 400 Bad Request. Requests that use any method other than GET return 405 Method Not Allowed.

Metadata updates

IMDS provides metadata captured at VM start time. The following endpoints are not refreshed in real time:

instance-data
parent-data
network-data
user-data

To get updated values from these endpoints after a change, stop and restart the VM.

Unlike the other endpoints, instance-events provides live updates and does not require a VM restart. A maintenance event may take up to five minutes to appear in the response.

Example requests

The following examples show how to retrieve different types of metadata from IMDS.

Getting all instance metadata

To get all available instance metadata in JSON format, run:

curl http://metadata.nebius.internal/v1/instance-data \
  -H "Metadata: true"

Example output:

{
  "id": "computeinstance-***",
  "parent_id": "project-***",
  "name": "example-vm",
  "hostname": "example-hostname",
  "platform": "cpu-d3",
  "preset": "8vcpu-32gb",
  "labels": {
    "env": "example-env",
    "runners_count": "24"
  },
  "resource_version": 12345,
  "created_at": "2025-11-11T08:03:31.754114Z",
  "service_account_id": "serviceaccount-***",
  "gpu_cluster_id": "computegpucluster-***",
  "infiniband_fabric": "fabric-1",
  "infiniband_topology_path": ["hash-1", "hash-2", "hash-3"],
  "region": "eu-north0",
  "nvl_instance_group_id": "computenvlinstancegroup-***"
}

labels is always returned as a JSON object. If no labels were set, IMDS returns an empty object. The following fields are optional and are returned only when available for the VM:

hostname
service_account_id
gpu_cluster_id
infiniband_fabric
infiniband_topology_path
nvl_instance_group_id

Getting a specific metadata field

To get a specific metadata field as plain text, run:

curl http://metadata.nebius.internal/v1/instance-data/<field> \
  -H "Metadata: true"

Example:

curl http://metadata.nebius.internal/v1/instance-data/id \
  -H "Metadata: true"

Example output:

computeinstance-***

Getting instance labels

To get all labels for the VM, run:

curl http://metadata.nebius.internal/v1/instance-data/labels \
  -H "Metadata: true"

Example output:

{
  "env": "example-env",
  "runners_count": "24"
}

To get a specific label, run:

curl http://metadata.nebius.internal/v1/instance-data/labels/<label_name> \
  -H "Metadata: true"

Example:

curl http://metadata.nebius.internal/v1/instance-data/labels/env \
  -H "Metadata: true"

Example output:

example-env

Getting parent resource metadata

To get parent resource metadata in JSON format, run:

curl http://metadata.nebius.internal/v1/parent-data \
  -H "Metadata: true"

Example output:

{
  "id": "project-***",
  "parent_id": "tenant-***",
  "name": "example-project",
  "created_at": "2025-11-11T08:03:30.754114Z",
  "labels": {
    "teamcity_build_id": "13672974"
  }
}

To access parent-data, the VM must have an attached service account with permissions to read the parent resource metadata. Otherwise, the request returns 403 Forbidden.

Getting user data

To get the user data that was provided when the VM was created, run:

curl http://metadata.nebius.internal/v1/user-data \
  -H "Metadata: true"

Example output:

#cloud-config
package_update: true
packages:
  - nginx
runcmd:
  - systemctl enable --now nginx

Getting network data

To get the VM network data, run:

curl http://metadata.nebius.internal/v1/network-data \
  -H "Metadata: true"

This request returns the network data that cloud-init used to initialize the VM during its first boot. Example output:

version: 2
ethernets:
  interface0:
    match:
      macaddress: "XX:XX:XX:XX:XX:XX"
    set-name: "eth0"
    dhcp4: true
    mtu: 1450

Getting service account information

To get information about the service account attached to the VM and its IAM token, run:

curl http://metadata.nebius.internal/v1/iam/sa \
  -H "Metadata: true"

Example output:

{
  "service_account_id": "serviceaccount-***",
  "token": {
    "access_token": "<access_token>",
    "expires_at": "2027-01-01T00:00:00Z"
  }
}

To get only the IAM token, run:

curl http://metadata.nebius.internal/v1/iam/sa/token/access_token \
  -H "Metadata: true"

Example output:

<access_token>

Getting maintenance events

To check if a maintenance event is scheduled for the VM, run:

curl http://metadata.nebius.internal/v1/instance-events \
  -H "Metadata: true"

Example output:

{
  "data": [
    {
      "id": "computemaintenance-***",
      "type": "maintenance",
      "status": "scheduled",
      "created_at": "2026-02-28T15:10:00Z",
      "not_before": "2026-03-01T10:00:00Z",
      "extra": {
        "support_center_ticket_id": "123456",
        "is_planned": "false"
      }
    }
  ]
}

If there are no active maintenance events, IMDS returns an empty array:

{
  "data": []
}

Request throttling

Nebius AI Cloud applies throttling to IMDS requests on a per-instance basis to reduce accidental overload and abuse:

10 requests per second for regular requests
20 requests per second for burst requests

If you exceed the limit, IMDS returns 429 Too Many Requests.

Status codes

HTTP status code	Description
`200 OK`	The request succeeded.
`400 Bad Request`	The `Metadata: true` header is missing or invalid.
`403 Forbidden`	The VM does not have permission to access the requested resource.
`404 Not Found`	The requested resource or field does not exist.
`405 Method Not Allowed`	The request used a method other than `GET`.
`429 Too Many Requests`	The request rate limit was exceeded. Retry the request.
`500 Internal Server Error`	The server encountered an error. Retry the request.
`501 Not Implemented`	The requested feature is not implemented.
`503 Service Unavailable`	The service is temporarily unavailable, or the request could not be attributed to this VM. Retry the request.

Virtual machines

Slurm and Soperator in Nebius AI Cloud

Managed Service for Kubernetes®

How to access instance metadata from within a VM

How to access IMDS

Metadata updates

Example requests

Getting all instance metadata

Getting a specific metadata field

Getting instance labels

Getting parent resource metadata

Getting user data

Getting network data

Getting service account information

Getting maintenance events

Request throttling

Status codes

Virtual machines

Slurm and Soperator in Nebius AI Cloud

Managed Service for Kubernetes®

Documentation Index

​How to access IMDS

​Metadata updates

​Example requests

​Getting all instance metadata

​Getting a specific metadata field

​Getting instance labels

​Getting parent resource metadata

​Getting user data

​Getting network data

​Getting service account information

​Getting maintenance events

​Request throttling

​Status codes

How to access IMDS

Metadata updates

Example requests

Getting all instance metadata

Getting a specific metadata field

Getting instance labels

Getting parent resource metadata

Getting user data

Getting network data

Getting service account information

Getting maintenance events

Request throttling

Status codes