When you run workloads in Azure, your virtual machines often need to know details about themselves, like which region they’re running in, their network configuration, or even how to request access tokens for managed identities.

That’s where the Azure Instance Metadata Service (IMDS) comes in. IMDS is a RESTful endpoint available to every Azure VM that provides information about the instance and its environment, without exposing this data outside the VM.

IMDS is a REST API that’s available at a well-known, non-routable IP address (169.254.169.254). You can only access it from within the VM. Communication between the VM and IMDS never leaves the host. Have your HTTP clients bypass web proxies within the VM when querying IMDS.

Source: https://learn.microsoft.com/en-us/azure/virtual-machines/instance-metadata-service


It’s lightweight, secure, and essential for automation, configuration management, and identity-based access in the cloud.

Besides instance metadata and identity tokens, IMDS also exposes Scheduled Events. These are notifications Azure sends to your VM before planned actions like reboots, redeployments, or host maintenance.

Through the IMDS endpoint, your VM can query upcoming events and get advance warning, often 30 seconds or more before the action occurs.


Table Of Contents
  1. Accessing the Instance Metadata Service (IMDS)
  2. Scheduled events
  3. Links


Accessing the Instance Metadata Service (IMDS)

To access the IMDS and retrieving all metadata for an instance, we can use PowerShell. To support all options and flags, we should first install PowerShell V6 or greater.

Installing PowerShell on Windows
https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows


The following PowerShell cmdlet will retrieve all metadata for an instance. In order to ensure that requests are directly intended for IMDS and prevent unintended or unwanted redirection of requests, requests:

  • Must contain the header Metadata: true
  • Must not contain an X-Forwarded-For header


IMDS requests must be sent using VM’s primary NIC and primary IP, and DHCP must be enabled.

The response is a JSON string as shown below.

The Instance Metadata Service is only accessible from within a running virtual machine instance on a non-routable IP address.

VMs can only interact with their own metadata/functionality. The API is HTTP only and never leaves the host.

PS> Invoke-RestMethod -Headers @{"Metadata"="true"} -Method GET -NoProxy -Uri "http://169.254.169.254/metadata/instance?api-version=2025-04-07" | ConvertTo-Json -Depth 64


As mentioned, in order to ensure that requests are directly intended for IMDS and prevent unintended or unwanted redirection of requests, requests must contain the header Metadata: true.

Therefore when just browsing to the IMDS URL like shown below, you will run into the following error.

{ “error”: “Bad request: . Required metadata header not specified” }



We can also just query specific data for the instance like associated VM tags by running the following command.

PS> Invoke-RestMethod -Headers @{"Metadata"="true"} -Method GET -NoProxy -Uri "http://169.254.169.254/metadata/instance/compute/tagsList?api-version=2025-04-07" | ConvertTo-Json -Depth 64



Further also when using managed identities for the virtual machine instance, we can request tokens for them from IMDS. We can use these tokens to authenticate with other Azure services, such as Azure Key Vault.

More about Azure Managed Identities you will also find in my following post.

Mastering Azure Managed Identities



More in general about the IMDS you will find here https://learn.microsoft.com/en-us/azure/virtual-machines/instance-metadata-service.

Scheduled events

We can also obtain the status of the scheduled events by using IMDS. Then the user can specify a set of actions to run upon these events.

Scheduled Events is available as part of the Azure Instance Metadata Service, which is available on every Azure virtual machine. Customers can write automation to query the endpoint of their virtual machines to find scheduled maintenance notifications and perform mitigations, like saving the state and taking the virtual machine out of rotation. We recommend building automation to record the Scheduled Events so you can have an auditing log of Azure maintenance events.

Source: https://learn.microsoft.com/en-us/azure/virtual-machines/windows/scheduled-event-service


About how to monitor scheduled events you will see in detail in my following post.

Step-by-Step Guide: Monitor Scheduled Events for Azure Windows Virtual Machines

Links

Azure Instance Metadata Service
https://learn.microsoft.com/en-us/azure/virtual-machines/instance-metadata-service?tabs=windows

Azure Instance MetaData Service – Find out Azure information from within guest OS! (John Savill)
https://www.youtube.com/watch?v=M5BO91VOfXo