Service de métadonnées d’instance Azure

  • Article

S’applique à : ✔️ Machines virtuelles Linux ✔️ Machines virtuelles Windows ✔️ Groupes identiques flexibles

Azure Instance Metadata Service fournit des informations sur les instances de machine virtuelle en cours d’exécution. Vous pouvez l’utiliser pour gérer et configurer vos machines virtuelles. Ces information comprennent la référence SKU, le stockage, les configurations réseau et les événements de maintenance à venir. Pour connaître la liste complète des données disponibles, consultez le Résumé des catégories de points de terminaison.

IMDS est disponible pour les instances de machine virtuelle et les instances de groupe identique en cours d’exécution. Tous les points de terminaison prennent en charge les machines virtuelles créées et gérées avec Azure Resource Manager. Seules la catégorie Attesté et la partie Réseau de la catégorie Instance prennent en charge les machines virtuelles créées avec le modèle de déploiement Classic. Le point de terminaison Attesté le fait seulement dans une certaine mesure.

IMDS est une API REST disponible à une adresse IP connue et non routable (169.254.169.254). On ne peut y accéder qu’à partir de la machine virtuelle. La communication entre la machine virtuelle et IMDS ne quitte jamais l’hôte. Faites en sorte que vos clients HTTP contournent les proxys web au sein de la machine virtuelle lors de l’interrogation d’IMDS et traitent 169.254.169.254 de la même façon que 168.63.129.16.

Usage

Accéder à Azure Instance Metadata Service

Pour accéder à IMDS, créez une machine virtuelle à partir d’Azure Resource Manager ou du portail Azure, puis utilisez les exemples suivants. Pour obtenir plus d’exemples, consultez Exemples Azure Instance Metadata.

Voici un exemple de code permettant de récupérer toutes les métadonnées d’une instance. Pour obtenir une vue d’ensemble de toutes les fonctionnalités disponibles dans le but d’accéder à une source de données spécifique, consultez Catégories de points de terminaison.

Requête

Important

Dans cet exemple, les proxys sont contournés. Vous devez contourner les proxys lorsque vous interrogez IMDS. Pour plus d’informations, consultez Proxys.

Remarque

Les requêtes IMDS doivent être envoyées en utilisant la carte réseau primaire de la machine virtuelle et l’adresse IP primaire. Le protocole DHCP doit être activé.

Invoke-RestMethod -Headers @{"Metadata"="true"} -Method GET -NoProxy -Uri "http://169.254.169.254/metadata/instance?api-version=2021-02-01" | ConvertTo-Json -Depth 64

-NoProxy nécessite PowerShell V6 ou version ultérieure. Consultez notre référentiel d’échantillons pour obtenir des exemples de versions PowerShell plus anciennes.

Réponse

Notes

La réponse est une chaîne JSON. L’exemple de réponse suivant est imprimé avec soin par souci de lisibilité.

{
    "compute": {
        "azEnvironment": "AZUREPUBLICCLOUD",
        "additionalCapabilities": {
            "hibernationEnabled": "true"
        },
        "hostGroup": {
          "id": "testHostGroupId"
        }, 
        "extendedLocation": {
            "type": "edgeZone",
            "name": "microsoftlosangeles"
        },
        "evictionPolicy": "",
        "isHostCompatibilityLayerVm": "true",
        "licenseType":  "Windows_Client",
        "location": "westus",
        "name": "examplevmname",
        "offer": "WindowsServer",
        "osProfile": {
            "adminUsername": "admin",
            "computerName": "examplevmname",
            "disablePasswordAuthentication": "true"
        },
        "osType": "Windows",
        "placementGroupId": "f67c14ab-e92c-408c-ae2d-da15866ec79a",
        "plan": {
            "name": "planName",
            "product": "planProduct",
            "publisher": "planPublisher"
        },
        "platformFaultDomain": "36",
        "platformSubFaultDomain": "",        
        "platformUpdateDomain": "42",
        "priority": "Regular",
        "publicKeys": [{
                "keyData": "ssh-rsa 0",
                "path": "/home/user/.ssh/authorized_keys0"
            },
            {
                "keyData": "ssh-rsa 1",
                "path": "/home/user/.ssh/authorized_keys1"
            }
        ],
        "publisher": "RDFE-Test-Microsoft-Windows-Server-Group",
        "resourceGroupName": "macikgo-test-may-23",
        "resourceId": "/subscriptions/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/resourceGroups/macikgo-test-may-23/providers/Microsoft.Compute/virtualMachines/examplevmname",
        "securityProfile": {
            "secureBootEnabled": "true",
            "virtualTpmEnabled": "false",
            "encryptionAtHost": "true",
            "securityType": "TrustedLaunch"
        },
        "sku": "2019-Datacenter",
        "storageProfile": {
            "dataDisks": [{
                "bytesPerSecondThrottle": "979202048",
                "caching": "None",
                "createOption": "Empty",
                "diskCapacityBytes": "274877906944",
                "diskSizeGB": "1024",
                "image": {
                  "uri": ""
                },
                "isSharedDisk": "false",
                "isUltraDisk": "true",
                "lun": "0",
                "managedDisk": {
                  "id": "/subscriptions/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/resourceGroups/macikgo-test-may-23/providers/Microsoft.Compute/disks/exampledatadiskname",
                  "storageAccountType": "StandardSSD_LRS"
                },
                "name": "exampledatadiskname",
                "opsPerSecondThrottle": "65280",
                "vhd": {
                  "uri": ""
                },
                "writeAcceleratorEnabled": "false"
            }],
            "imageReference": {
                "id": "",
                "offer": "WindowsServer",
                "publisher": "MicrosoftWindowsServer",
                "sku": "2019-Datacenter",
                "version": "latest",
                "communityGalleryImageId": "/CommunityGalleries/testgallery/Images/1804Gen2/Versions/latest",
                "sharedGalleryImageId": "/SharedGalleries/1P/Images/gen2/Versions/latest",
                "exactVersion": "1.1686127202.30113"
            },
            "osDisk": {
                "caching": "ReadWrite",
                "createOption": "FromImage",
                "diskSizeGB": "30",
                "diffDiskSettings": {
                    "option": "Local"
                },
                "encryptionSettings": {
                  "enabled": "false",
                  "diskEncryptionKey": {
                    "sourceVault": {
                      "id": "/subscriptions/test-source-guid/resourceGroups/testrg/providers/Microsoft.KeyVault/vaults/test-kv"
                    },
                    "secretUrl": "https://test-disk.vault.azure.net/secrets/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
                  },
                  "keyEncryptionKey": {
                    "sourceVault": {
                      "id": "/subscriptions/test-key-guid/resourceGroups/testrg/providers/Microsoft.KeyVault/vaults/test-kv"
                    },
                    "keyUrl": "https://test-key.vault.azure.net/secrets/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
                  }
                },
                "image": {
                    "uri": ""
                },
                "managedDisk": {
                    "id": "/subscriptions/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/resourceGroups/macikgo-test-may-23/providers/Microsoft.Compute/disks/exampleosdiskname",
                    "storageAccountType": "StandardSSD_LRS"
                },
                "name": "exampleosdiskname",
                "osType": "Windows",
                "vhd": {
                    "uri": ""
                },
                "writeAcceleratorEnabled": "false"
            },
            "resourceDisk": {
                "size": "4096"
            }
        },
        "subscriptionId": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
        "tags": "baz:bash;foo:bar",
        "userData": "Zm9vYmFy",
        "version": "15.05.22",
        "virtualMachineScaleSet": {
            "id": "/subscriptions/xxxxxxxx-xxxxx-xxx-xxx-xxxx/resourceGroups/resource-group-name/providers/Microsoft.Compute/virtualMachineScaleSets/virtual-machine-scale-set-name"
        },
        "vmId": "02aab8a4-74ef-476e-8182-f6d2ba4166a6",
        "vmScaleSetName": "crpteste9vflji9",
        "vmSize": "Standard_A3",
        "zone": ""
    },
    "network": {
        "interface": [{
            "ipv4": {
               "ipAddress": [{
                    "privateIpAddress": "10.144.133.132",
                    "publicIpAddress": ""
                }],
                "subnet": [{
                    "address": "10.144.133.128",
                    "prefix": "26"
                }]
            },
            "ipv6": {
                "ipAddress": [
                 ]
            },
            "macAddress": "0011AAFFBB22"
        }]
    }
}

Sécurité et authentification

Instance Metadata Service n’est accessible qu’à partir d’une instance de machine virtuelle en cours d’exécution sur une adresse IP non routable. Les machines virtuelles peuvent interagir seulement avec leurs propres métadonnées/fonctionnalités. L’API est HTTP uniquement. Elle ne quitte jamais l’hôte.

Les demandes doivent respecter les conditions suivantes pour être directement destinées à IMDS et éviter toute redirection involontaire ou indésirable :

  • Elles doivent contenir l’en-tête Metadata: true.
  • Elles ne doivent pas contenir l’en-tête X-Forwarded-For.

Toutes les requêtes qui ne respectent pas ces deux exigences sont rejetées par le service.

Important

IMDS n’est pas un canal pour les données sensibles. L’API n’est pas authentifiée. Elle est ouverte à tous les processus de la machine virtuelle. Les informations exposées par le biais de ce service doivent être considérées comme des informations partagées pour toutes les applications exécutées dans la machine virtuelle.

S’il n’est pas nécessaire pour chaque processus sur la machine virtuelle d’accéder au point de terminaison IMDS, vous pouvez définir des règles de pare-feu local pour limiter l’accès. Par exemple, si seul un service système connu a besoin d’accéder au service de métadonnées d’instance, vous pouvez définir une règle de pare-feu sur le point de terminaison IMDS, en autorisant uniquement le ou les processus spécifiques auxquels accéder ou en refusant l’accès pour le reste des processus.

Proxies

IMDS n’est pas destiné à être utilisé derrière un proxy, ce qui n’est pas pris en charge. La plupart des clients HTTP proposent une option vous permettant de désactiver les proxys sur vos demandes. Cette fonctionnalité doit être utilisée lors de la communication avec IMDS. Pour plus d’informations, consultez la documentation de votre client.

Important

Même si vous n’avez connaissance d’aucune configuration de proxy dans votre environnement, vous devez toujours remplacer les paramètres de proxy client par défaut. Les configurations de proxy peuvent être découvertes automatiquement. Si vous ne les contournez pas, vous vous exposez à des risques de panne en cas de modification ultérieure de la configuration de la machine.

Limitation du débit

En général, les demandes adressées à IMDS sont limitées à 5 par seconde (par machine virtuelle). Celles qui dépassent ce seuil sont rejetées avec une réponse 429. Les demandes adressées à la catégorie Identité managée sont limitées à 20 par seconde et à 5 demandes simultanément (par machine virtuelle).

Verbes HTTP

Sont actuellement pris en charge les verbes HTTP suivants :

Verbe Description
GET Récupère la ressource demandée

Paramètres

Les points de terminaison peuvent prendre en charge les paramètres obligatoires et facultatifs. Pour plus d’informations, consultez Schéma et la documentation du point de terminaison en question.

Paramètres de requête

Les points de terminaison IMDS prennent en charge les paramètres de chaîne de requête HTTP. Exemple :

http://169.254.169.254/metadata/instance/compute?api-version=2021-01-01&format=json

Spécifie les paramètres :

Nom Valeur
api-version 2021-01-01
format json

Les demandes comportant des noms de paramètres de requête en double sont rejetées.

Paramètres d’itinéraire

Dans le cas de certains points de terminaison qui retournent des objets blob JSON volumineux, l’ajout de paramètres d’itinéraire au point de terminaison de la demande est pris en charge pour filtrer la réponse sur un sous-ensemble :

http://169.254.169.254/metadata/<endpoint>/[<filter parameter>/...]?<query parameters>

Les paramètres correspondent aux index/clés qui seraient utilisés pour parcourir l’objet JSON si l’on interagissait avec une représentation analysée.

Par exemple, /metadata/instance retourne l’objet JSON suivant :

{
    "compute": { ... },
    "network": {
        "interface": [
            {
                "ipv4": {
                   "ipAddress": [{
                        "privateIpAddress": "10.144.133.132",
                        "publicIpAddress": ""
                    }],
                    "subnet": [{
                        "address": "10.144.133.128",
                        "prefix": "26"
                    }]
                },
                "ipv6": {
                    "ipAddress": [
                     ]
                },
                "macAddress": "0011AAFFBB22"
            },
            ...
        ]
    }
}

Pour filtrer la réponse sur la propriété compute, la demande envoyée serait la suivante :

http://169.254.169.254/metadata/instance/compute?api-version=<version>

De même, pour appliquer un filtre sur une propriété imbriquée ou un élément de tableau spécifique, des clés seraient encore ajoutées :

http://169.254.169.254/metadata/instance/network/interface/0?api-version=<version>

Cette demande appliquerait un filtre sur le premier élément de la propriété Network.interface et retournerait la réponse suivante :

{
    "ipv4": {
       "ipAddress": [{
            "privateIpAddress": "10.144.133.132",
            "publicIpAddress": ""
        }],
        "subnet": [{
            "address": "10.144.133.128",
            "prefix": "26"
        }]
    },
    "ipv6": {
        "ipAddress": [
         ]
    },
    "macAddress": "0011AAFFBB22"
}

Notes

En cas de filtrage sur un nœud terminal, format=json ne fonctionne pas. Pour ces requêtes, format=text doit être spécifié explicitement si le format par défaut est json.

schéma

Format de données

Par défaut, IMDS retourne les données au format JSON (Content-Type: application/json). Toutefois, les points de terminaison qui prennent en charge le filtrage de réponse (cf. Paramètres d’itinéraire) prennent également en charge le format text.

Pour accéder à un format de réponse autre que le format par défaut, spécifiez le format demandé en tant que paramètre de chaîne de requête dans la demande. Par exemple :

Invoke-RestMethod -Headers @{"Metadata"="true"} -Method GET -NoProxy -Uri "http://169.254.169.254/metadata/instance?api-version=2017-08-01&format=text"

Dans les réponses JSON, toutes les primitives sont de type string. Les valeurs manquantes et les valeurs non applicables sont toujours incluses, mais définies sur une chaîne vide.

Contrôle de version

IMDS est versionné. Il est obligatoire de spécifier la version de l’API dans la requête HTTP. La seule exception à cette exigence est le point de terminaison versions, qui peut être utilisé pour récupérer dynamiquement les versions d’API disponibles.

Au fur et à mesure que des versions plus récentes sont ajoutées, les versions antérieures sont toujours accessibles pour des questions de compatibilité si vos scripts ont des dépendances sur des formats de données spécifiques.

Si vous ne spécifiez pas de version, vous recevez une erreur accompagnée de la liste des dernières versions prises en charge :

{
    "error": "Bad request. api-version was not specified in the request. For more information refer to aka.ms/azureimds",
    "newest-versions": [
        "2020-10-01",
        "2020-09-01",
        "2020-07-15"
    ]
}

Versions d'API prises en charge

Remarque

La version 2023-11-15 est toujours déployée, mais elle n’est peut-être pas disponible dans certaines régions.

  • 2023-11-15
  • 2023-07-01
  • 13-12-2021
  • 15-11-2021
  • 2021-11-01
  • 2021-10-01
  • 2021-08-01
  • 2021-05-01
  • 2021-03-01
  • 2021-02-01
  • 2021-01-01
  • 2020-12-01
  • 2020-10-01
  • 2020-09-01
  • 2020-07-15
  • 2020-06-01
  • 2019-11-01
  • 2019-08-15
  • 2019-08-01
  • 2019-06-04
  • 2019-06-01
  • 2019-04-30
  • 2019-03-11
  • 2019-02-01
  • 2018-10-01
  • 2018-04-02
  • 2018-02-01
  • 2017-12-01
  • 2017-10-01
  • 2017-08-01
  • 2017-04-02
  • 2017-03-01

Fichier Swagger

Une définition Swagger complète pour IMDS est disponible à l’adresse https://github.com/Azure/azure-rest-api-specs/blob/main/specification/imds/data-plane/readme.md.

Disponibilité régionale

Le service est en disponibilité générale dans tous les clouds Azure.

Point de terminaison racine

Le point de terminaison racine est http://169.254.169.254/metadata.

Catégories de points de terminaison

L’API IMDS contient plusieurs catégories de points de terminaison qui représentent des sources de données différentes, chacune contenant un ou plusieurs points de terminaison. Examinez chaque catégorie pour plus de détails.

Racine de la catégorie Description Version introduite
/metadata/attested Voir Données attestées 2018-10-01
/metadata/identity Voir Identité managée via IMDS 2018-02-01
/metadata/instance Voir Métadonnées d’instance 2017-04-02
/metadata/loadbalancer Voir Récupérer les métadonnées de l’équilibreur de charge à l’aide d’IMDS 2020-10-01
/metadata/scheduledevents Voir Scheduled Events via IMDS 2017-08-01
/metadata/versions Voir Versions N/A

Versions

Liste des versions d’API

Retourne l’ensemble des versions d’API prises en charge.

GET /metadata/versions

Paramètres

Aucun (ce point de terminaison n’est pas versionné).

response

{
  "apiVersions": [
    "2017-03-01",
    "2017-04-02",
    ...
  ]
}

Métadonnées d’instance

Récupération des métadonnées de machine virtuelle

Expose les métadonnées importantes pour l’instance de machine virtuelle, notamment le calcul, le réseau et le stockage.

GET /metadata/instance

Paramètres

Nom Obligatoires/facultatif Description
api-version Obligatoire Version utilisée pour traiter la demande.
format Facultatif* Format (json ou text) de la réponse. *Remarque : Peut être obligatoire si les paramètres de demande sont utilisés.

Ce point de terminaison prend en charge le filtrage de la réponse avec les paramètres de routage.

response

{
    "compute": {
        "azEnvironment": "AZUREPUBLICCLOUD",
        "additionalCapabilities": {
            "hibernationEnabled": "true"
        },
        "hostGroup": {
          "id": "testHostGroupId"
        }, 
        "extendedLocation": {
            "type": "edgeZone",
            "name": "microsoftlosangeles"
        },
        "evictionPolicy": "",
        "isHostCompatibilityLayerVm": "true",
        "licenseType":  "Windows_Client",
        "location": "westus",
        "name": "examplevmname",
        "offer": "WindowsServer",
        "osProfile": {
            "adminUsername": "admin",
            "computerName": "examplevmname",
            "disablePasswordAuthentication": "true"
        },
        "osType": "Windows",
        "placementGroupId": "f67c14ab-e92c-408c-ae2d-da15866ec79a",
        "plan": {
            "name": "planName",
            "product": "planProduct",
            "publisher": "planPublisher"
        },
        "platformFaultDomain": "36",
        "platformSubFaultDomain": "",        
        "platformUpdateDomain": "42",
        "priority": "Regular",
        "publicKeys": [{
                "keyData": "ssh-rsa 0",
                "path": "/home/user/.ssh/authorized_keys0"
            },
            {
                "keyData": "ssh-rsa 1",
                "path": "/home/user/.ssh/authorized_keys1"
            }
        ],
        "publisher": "RDFE-Test-Microsoft-Windows-Server-Group",
        "resourceGroupName": "macikgo-test-may-23",
        "resourceId": "/subscriptions/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/resourceGroups/macikgo-test-may-23/providers/Microsoft.Compute/virtualMachines/examplevmname",
        "securityProfile": {
            "secureBootEnabled": "true",
            "virtualTpmEnabled": "false",
            "encryptionAtHost": "true",
            "securityType": "TrustedLaunch"
        },
        "sku": "2019-Datacenter",
        "storageProfile": {
            "dataDisks": [{
                "bytesPerSecondThrottle": "979202048",
                "caching": "None",
                "createOption": "Empty",
                "diskCapacityBytes": "274877906944",
                "diskSizeGB": "1024",
                "image": {
                  "uri": ""
                },
                "isSharedDisk": "false",
                "isUltraDisk": "true",
                "lun": "0",
                "managedDisk": {
                  "id": "/subscriptions/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/resourceGroups/macikgo-test-may-23/providers/Microsoft.Compute/disks/exampledatadiskname",
                  "storageAccountType": "StandardSSD_LRS"
                },
                "name": "exampledatadiskname",
                "opsPerSecondThrottle": "65280",
                "vhd": {
                  "uri": ""
                },
                "writeAcceleratorEnabled": "false"
            }],
            "imageReference": {
                "id": "",
                "offer": "WindowsServer",
                "publisher": "MicrosoftWindowsServer",
                "sku": "2019-Datacenter",
                "version": "latest",
                "communityGalleryImageId": "/CommunityGalleries/testgallery/Images/1804Gen2/Versions/latest",
                "sharedGalleryImageId": "/SharedGalleries/1P/Images/gen2/Versions/latest",
                "exactVersion": "1.1686127202.30113"
            },
            "osDisk": {
                "caching": "ReadWrite",
                "createOption": "FromImage",
                "diskSizeGB": "30",
                "diffDiskSettings": {
                    "option": "Local"
                },
                "encryptionSettings": {
                  "enabled": "false",
                  "diskEncryptionKey": {
                    "sourceVault": {
                      "id": "/subscriptions/test-source-guid/resourceGroups/testrg/providers/Microsoft.KeyVault/vaults/test-kv"
                    },
                    "secretUrl": "https://test-disk.vault.azure.net/secrets/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
                  },
                  "keyEncryptionKey": {
                    "sourceVault": {
                      "id": "/subscriptions/test-key-guid/resourceGroups/testrg/providers/Microsoft.KeyVault/vaults/test-kv"
                    },
                    "keyUrl": "https://test-key.vault.azure.net/secrets/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
                  }
                },
                "image": {
                    "uri": ""
                },
                "managedDisk": {
                    "id": "/subscriptions/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/resourceGroups/macikgo-test-may-23/providers/Microsoft.Compute/disks/exampleosdiskname",
                    "storageAccountType": "StandardSSD_LRS"
                },
                "name": "exampleosdiskname",
                "osType": "Windows",
                "vhd": {
                    "uri": ""
                },
                "writeAcceleratorEnabled": "false"
            },
            "resourceDisk": {
                "size": "4096"
            }
        },
        "subscriptionId": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
        "tags": "baz:bash;foo:bar",
        "userData": "Zm9vYmFy",
        "version": "15.05.22",
        "virtualMachineScaleSet": {
            "id": "/subscriptions/xxxxxxxx-xxxxx-xxx-xxx-xxxx/resourceGroups/resource-group-name/providers/Microsoft.Compute/virtualMachineScaleSets/virtual-machine-scale-set-name"
        },
        "vmId": "02aab8a4-74ef-476e-8182-f6d2ba4166a6",
        "vmScaleSetName": "crpteste9vflji9",
        "vmSize": "Standard_A3",
        "zone": ""
    },
    "network": {
        "interface": [{
            "ipv4": {
               "ipAddress": [{
                    "privateIpAddress": "10.144.133.132",
                    "publicIpAddress": ""
                }],
                "subnet": [{
                    "address": "10.144.133.128",
                    "prefix": "26"
                }]
            },
            "ipv6": {
                "ipAddress": [
                 ]
            },
            "macAddress": "0011AAFFBB22"
        }]
    }
}

Décomposition du schéma :

Calcul

Données Description Version introduite
azEnvironment Environnement Azure dans lequel s’exécute la machine virtuelle 2018-10-01
additionalCapabilities.hibernationEnabled Identifie si la mise en veille prolongée est activée sur la machine virtuelle 2021-11-01
customData Cette fonctionnalité est déconseillée et désactivée dans IMDS. Elle a été remplacée par userData. 2019-02-01
evictionPolicy Définit le mode de suppression d’une machine virtuelle spot. 2020-12-01
extendedLocation.type Type de l’emplacement étendu de la machine virtuelle. 2021-03-01
extendedLocation.name Nom de l’emplacement étendu de la machine virtuelle 2021-03-01
host.id Nom de l’hôte de la machine virtuelle. Notez qu’une machine virtuelle aura un hôte ou un groupe hôte, mais pas les deux. 15-11-2021
hostGroup.id Nom du groupe hôte de la machine virtuelle. Notez qu’une machine virtuelle aura un hôte ou un groupe hôte, mais pas les deux. 15-11-2021
isHostCompatibilityLayerVm Indique si la machine virtuelle s’exécute sur la couche de compatibilité de l’ordinateur hôte 2020-06-01
licenseType Type de licence pour Azure Hybrid Benefit. Présent seulement pour les machines virtuelles dotées d’AHB 2020-09-01
location Région Azure dans laquelle la machine virtuelle est en cours d’exécution 2017-04-02
name Nom de la machine virtuelle 2017-04-02
offer Fournit des informations pour l’image de machine virtuelle et ne sont présentes que pour les images déployées à partir de la galerie d’images Azure 2017-04-02
osProfile.adminUsername Spécifie le nom du compte administrateur 2020-07-15
osProfile.computerName Spécifie le nom de l’ordinateur 2020-07-15
osProfile.disablePasswordAuthentication Spécifie si l'authentification par mot de passe est désactivée. Présent seulement pour les machines virtuelles Linux 2020-10-01
osType Linux ou Windows 2017-04-02
physicalZone Zone physique de la machine virtuelle 2023-11-15
placementGroupId Groupe de placement de votre groupe identique 2017-08-01
plan Plan contenant le nom, le produit et l’éditeur pour une machine virtuelle s’il s’agit d’une image de la Place de marché Azure 2018-04-02
platformUpdateDomain Domaine de mise à jour dans lequel la machine virtuelle est en cours d’exécution 2017-04-02
platformFaultDomain Domaine par défaut dans lequel la machine virtuelle est en cours d’exécution 2017-04-02
platformSubFaultDomain Sous-domaine d’erreur où la machine virtuelle s’exécute, le cas échéant. 2021-10-01
priority Priorité de la machine virtuelle. Pour en savoir plus, consultez la section Machines virtuelles spot 2020-12-01
provider Fournisseur de la machine virtuelle 2018-10-01
publicKeys Collection de clés publiques affectée à la machine virtuelle et aux chemins 2018-04-02
publisher Éditeur de l’image de machine virtuelle 2017-04-02
resourceGroupName Groupe de ressources de votre machine virtuelle 2017-08-01
resourceId L’ID complet de la ressource 2019-03-11
sku Référence (SKU) spécifique pour l’image de machine virtuelle 2017-04-02
securityProfile.secureBootEnabled Indique si le démarrage sécurisé UEFI est activé sur la machine virtuelle 2020-06-01
securityProfile.virtualTpmEnabled Indique si le Module de plateforme sécurisée (TPM) virtuel est activé sur la machine virtuelle 2020-06-01
securityProfile.encryptionAtHost Identifie si le chiffrement sur l’hôte est activé sur la machine virtuelle 2021-11-01
securityProfile.securityType Identifie si la machine virtuelle est une machine virtuelle approuvée ou une machine virtuelle confidentielle 13-12-2021
storageProfile Voir Profil de stockage ci-dessous 2019-06-01
subscriptionId Abonnement Azure pour la machine virtuelle 2017-08-01
tags Étiquettes de votre machine virtuelle 2017-08-01
tagsList Balises mises en forme en tant que tableau JSON pour faciliter l’analyse programmatique 2019-06-04
userData Jeu de données spécifié lors de la création de la machine virtuelle à utiliser pendant ou après l’approvisionnement (encodé en base64) 2021-01-01
version Version de l’image de machine virtuelle 2017-04-02
virtualMachineScaleSet.id ID du groupe de machines virtuelles identiques créé avec une orchestration flexible dont la machine virtuelle fait partie. Ce champ n’est pas disponible pour les groupe de machines virtuelles identiques créés avec l’orchestration uniforme. 2021-03-01
vmId Identificateur unique de la machine virtuelle. Le blog référencé ne convient qu’aux machines virtuelles dotées de SMBIOS < 2.6. Pour les machines virtuelles avec un SMBIOS >= 2.6, l’UUID issu de DMI s’affiche au format Little Endian et il n’est donc pas nécessaire d’intervertir les octets. 2017-04-02
vmScaleSetName Nom du groupe de machines virtuelles identiques de votre groupe identique 2017-12-01
vmSize Taille de la machine virtuelle 2017-04-02
zone Zone de disponibilité de votre machine virtuelle 2017-12-01

† Cette version n’est pas encore entièrement disponible et peut ne pas être prise en charge dans toutes les régions.

Profil de stockage

Le profil de stockage d’une machine virtuelle est divisé en trois catégories : la référence de l’image, le disque de système d’exploitation et les disques de données, plus un objet supplémentaire pour le disque temporaire local.

L’objet de référence d’image contient les informations suivantes sur l’image du système d’exploitation, notez qu’une image peut provenir de la plateforme, de la place de marché, de la galerie de la communauté ou de la galerie partagée directe, mais pas les deux :

Données Description Version introduite
id ID de ressource 2019-06-01
offer Offre de la plateforme ou de l’image de la Place de marché 2019-06-01
publisher Éditeur de l’image de la plateforme ou de la place de marché 2019-06-01
sku SKU de l’image de la plateforme ou de la place de marché 2019-06-01
version Version de l’image 2019-06-01
communityGalleryImageId ID de ressource de l’image de la communauté (vide sinon) 2023-07-01
sharedGalleryImageId ID de ressource de l’image partagée directe (vide sinon) 2023-07-01
exactVersion Version de l’image de la communauté ou partagée directe 2023-07-01

L’objet de disque du système d’exploitation contient les informations suivantes sur le disque du système d’exploitation utilisé par la machine virtuelle :

Données Description
caching Exigences de la mise en cache
createOption Informations sur la façon dont la machine virtuelle a été créée
diffDiskSettings Paramètres du disque éphémère
diskSizeGB Taille du disque en Go
image Disque dur virtuel de l’image utilisateur source
managedDisk Paramètres des disques managés
name Nom du disque
vhd Disque dur virtuel
writeAcceleratorEnabled Indique si writeAccelerator est activé ou non sur le disque

Le tableau des disques de données contient la liste des disques de données attachés à la machine virtuelle. Chaque objet de disque de données contient les informations suivantes :

Données Description Version introduite
bytesPerSecondThrottle* Quota de lecture/écriture sur le disque en octets 2021-05-01
caching Exigences de la mise en cache 2019-06-01
createOption Informations sur la façon dont la machine virtuelle a été créée 2019-06-01
diffDiskSettings Paramètres du disque éphémère 2019-06-01
diskCapacityBytes* Taille du disque en octets 2021-05-01
diskSizeGB Taille du disque en Go 2019-06-01
encryptionSettings Paramètres de chiffrement du disque 2019-06-01
image Disque dur virtuel de l’image utilisateur source 2019-06-01
isSharedDisk* Indique si le disque est partagé entre les ressources 2021-05-01
isUltraDisk Indique si le disque de données est un disque Ultra 2021-05-01
lun Numéro d’unité logique du disque 2019-06-01
managedDisk Paramètres des disques managés 2019-06-01
name Nom du disque 2019-06-01
opsPerSecondThrottle* Quota de lecture/écriture sur le disque en E/S par seconde 2021-05-01
osType Type de système d’exploitation inclus dans le disque 2019-06-01
vhd Disque dur virtuel 2019-06-01
writeAcceleratorEnabled Indique si writeAccelerator est activé ou non sur le disque 2019-06-01

*Ces champs sont remplis seulement pour disques Ultra. Ce sont des chaînes vides pour les disques non-Ultra.

L’objet blob des paramètres de chiffrement contient des données sur le mode de chiffrement du disque (si celui-ci est chiffré) :

Données Description Version introduite
diskEncryptionKey.sourceVault.id Emplacement de la clé de chiffrement du disque 2021-11-01
diskEncryptionKey.secretUrl Emplacement du secret 2021-11-01
keyEncryptionKey.sourceVault.id Emplacement de la clé de chiffrement de la clé 2021-11-01
keyEncryptionKey.keyUrl Emplacement de la clé 2021-11-01

L’objet de disque de ressources contient la taille du disque temporaire local attaché à la machine virtuelle, le cas échéant, en kilo-octets. S’il n’existe aucun disque temporaire local pour la machine virtuelle, cette valeur est 0.

Données Description Version introduite
resourceDisk.size Taille du disque temporaire local de la machine virtuelle (en ko) 2021-02-01

Réseau

Données Description Version introduite
ipv4.privateIpAddress Adresse IPv4 locale de la machine virtuelle 2017-04-02
ipv4.publicIpAddress Adresse IPv4 publique de la machine virtuelle 2017-04-02
subnet.address Adresse de sous-réseau de la machine virtuelle 2017-04-02
subnet.prefix Préfixe de sous-réseau, par exemple 24 2017-04-02
ipv6.ipAddress Adresse IPv6 locale de la machine virtuelle 2017-04-02
macAddress Adresse MAC de la machine virtuelle 2017-04-02

Notes

L’ordre des cartes réseau retournées par l’appel réseau n’est pas garanti.

Obtenir les données utilisateur

Lorsque vous créez une machine virtuelle, vous pouvez spécifier un jeu de données à utiliser pendant ou après l’approvisionnement de la machine virtuelle, puis le récupérer via IMDS. Vérifiez ici l’expérience de données d’utilisateur de bout en bout.

Pour configurer les données utilisateur, utilisez le modèle de démarrage rapide fourni ici. L’exemple ci-dessous montre comment récupérer ces données par le biais d’IMDS. Cette fonctionnalité est proposée avec la version 2021-01-01 et versions supérieures.

Notes

Avis de sécurité : IMDS est ouvert à toutes les applications sur la machine virtuelle ; les données sensibles ne doivent pas être placées dans les données utilisateur.

$userData = Invoke-RestMethod -Headers @{"Metadata"="true"} -Method GET -NoProxy -Uri "http://169.254.169.254/metadata/instance/compute/userData?api-version=2021-01-01&format=text"
[System.Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($userData))

Exemple 1 : Suivi de la machine virtuelle s’exécutant sur Azure

En tant que fournisseur de service, vous aurez peut-être besoin de suivre le nombre de machines virtuelles s’exécutant sur votre logiciel ou de disposer d’agents effectuant le suivi de l’unicité de la machine virtuelle. Pour pouvoir obtenir un ID unique pour une machine virtuelle, utilisez le champ vmId du service de métadonnées d’instance.

Requête

Invoke-RestMethod -Headers @{"Metadata"="true"} -Method GET -NoProxy -Uri "http://169.254.169.254/metadata/instance/compute/vmId?api-version=2017-08-01&format=text"

Réponse

5c08b38e-4d57-4c23-ac45-aca61037f084

Exemple 2 : Positionnement de différents réplicas de données

Pour certains scénarios, le positionnement des différents réplicas de données est de première importance. Par exemple, pour le positionnement du réplica HDFS ou le positionnement des conteneurs via un orchestrateur, vous devez connaître les domaines platformFaultDomain et platformUpdateDomain sur lesquels la machine virtuelle s’exécute. Vous pouvez également utiliser les Zones de disponibilité pour les instances pour prendre ces décisions. Vous pouvez interroger ces données directement via IMDS.

Requête

Invoke-RestMethod -Headers @{"Metadata"="true"} -Method GET -NoProxy -Uri "http://169.254.169.254/metadata/instance/compute/platformFaultDomain?api-version=2017-08-01&format=text"

Réponse

0

Exemple 3 : Obtenir les balises de machines virtuelles

Les balises de machine virtuelle sont incluses dans l’API d’instance sous le point de terminaison instance/compute/tags. Des balises peuvent être appliqués à votre machine virtuelle Azure pour les organiser de manière logique dans une taxonomie. Les balises affectées à une machine virtuelle peuvent être récupérées à l’aide de la requête ci-dessous.

Requête

Invoke-RestMethod -Headers @{"Metadata"="true"} -Method GET -NoProxy -Uri "http://169.254.169.254/metadata/instance/compute/tags?api-version=2017-08-01&format=text"

Réponse

Department:IT;ReferenceNumber:123456;TestStatus:Pending

Le champ tags est une chaîne dont les étiquettes sont délimitées par des points-virgules. Cette sortie peut constituer un problème si des points-virgules sont utilisés dans les étiquettes proprement dites. Si un analyseur est écrit pour extraire les balises par programmation, vous devez vous appuyer sur le champ tagsList. Le champ tagsList est un tableau JSON sans délimiteur et, par conséquent plus facile à analyser. Le tagsList attribué à une machine virtuelle peut être récupéré à l’aide de la requête ci-dessous.

Requête

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

Réponse

{
    "value":  [
                  {
                      "name":  "Department",
                      "value":  "IT"
                  },
                  {
                      "name":  "ReferenceNumber",
                      "value":  "123456"
                  },
                  {
                      "name":  "TestStatus",
                      "value":  "Pending"
                  }
              ],
    "Count":  3
}

Exemple 4 : Obtenir plus d’informations sur la machine virtuelle dans le cadre du support technique

En tant que fournisseur de services, vous recevrez peut-être un appel du support pour lequel vous devrez connaître les informations de la machine virtuelle. Demandez au client de partager les métadonnées de calcul afin que l’équipe du support dispose des informations de base concernant le type de machine virtuelle sur Azure.

Requête

Invoke-RestMethod -Headers @{"Metadata"="true"} -Method GET -NoProxy -Uri "http://169.254.169.254/metadata/instance/compute?api-version=2020-09-01" | ConvertTo-Json -Depth 64

Réponse

Notes

La réponse est une chaîne JSON. L’exemple de réponse suivant est imprimé avec soin par souci de lisibilité.

{
    "azEnvironment": "AZUREPUBLICCLOUD",
    "extendedLocation": {
      "type": "edgeZone",
      "name": "microsoftlosangeles"
    },
    "evictionPolicy": "",
    "additionalCapabilities": {
        "hibernationEnabled": "false"
    },
    "hostGroup": {
      "id": "testHostGroupId"
    },
    "isHostCompatibilityLayerVm": "true",
    "licenseType":  "Windows_Client",
    "location": "westus",
    "name": "examplevmname",
    "offer": "WindowsServer",
    "osProfile": {
        "adminUsername": "admin",
        "computerName": "examplevmname",
        "disablePasswordAuthentication": "true"
    },
    "osType": "Windows",
    "placementGroupId": "f67c14ab-e92c-408c-ae2d-da15866ec79a",
    "plan": {
        "name": "planName",
        "product": "planProduct",
        "publisher": "planPublisher"
    },
    "platformFaultDomain": "36",
    "platformUpdateDomain": "42",
    "priority": "Regular",
    "publicKeys": [{
            "keyData": "ssh-rsa 0",
            "path": "/home/user/.ssh/authorized_keys0"
        },
        {
            "keyData": "ssh-rsa 1",
            "path": "/home/user/.ssh/authorized_keys1"
        }
    ],
    "publisher": "RDFE-Test-Microsoft-Windows-Server-Group",
    "physicalZone": "useast-AZ01",
    "resourceGroupName": "macikgo-test-may-23",
    "resourceId": "/subscriptions/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/resourceGroups/macikgo-test-may-23/providers/Microsoft.Compute/virtualMachines/examplevmname",
    "securityProfile": {
        "secureBootEnabled": "true",
        "virtualTpmEnabled": "false",
        "encryptionAtHost": "true",
        "securityType": "TrustedLaunch"
    },
    "sku": "2019-Datacenter",
    "storageProfile": {
        "dataDisks": [{
            "bytesPerSecondThrottle": "979202048",
            "caching": "None",
            "createOption": "Empty",
            "diskCapacityBytes": "274877906944",
            "diskSizeGB": "1024",
            "image": {
              "uri": ""
            },
            "isSharedDisk": "false",
            "isUltraDisk": "true",
            "lun": "0",
            "managedDisk": {
              "id": "/subscriptions/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/resourceGroups/macikgo-test-may-23/providers/MicrosoftCompute/disks/exampledatadiskname",
              "storageAccountType": "StandardSSD_LRS"
            },
            "name": "exampledatadiskname",
            "opsPerSecondThrottle": "65280",
            "vhd": {
              "uri": ""
            },
            "writeAcceleratorEnabled": "false"
        }],
        "imageReference": {
            "id": "",
            "offer": "WindowsServer",
            "publisher": "MicrosoftWindowsServer",
            "sku": "2019-Datacenter",
            "version": "latest",
            "communityGalleryImageId": "/CommunityGalleries/testgallery/Images/1804Gen2/Versions/latest",
            "sharedGalleryImageId": "/SharedGalleries/1P/Images/gen2/Versions/latest",
            "exactVersion": "1.1686127202.30113"
        },
        "osDisk": {
            "caching": "ReadWrite",
            "createOption": "FromImage",
            "diskSizeGB": "30",
            "diffDiskSettings": {
                "option": "Local"
            },
            "encryptionSettings": {
              "enabled": "false",
              "diskEncryptionKey": {
                "sourceVault": {
                  "id": "/subscriptions/test-source-guid/resourceGroups/testrg/providers/Microsoft.KeyVault/vaults/test-kv"
                },
                "secretUrl": "https://test-disk.vault.azure.net/secrets/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
              },
              "keyEncryptionKey": {
                "sourceVault": {
                  "id": "/subscriptions/test-key-guid/resourceGroups/testrg/providers/Microsoft.KeyVault/vaults/test-kv"
                },
                "keyUrl": "https://test-key.vault.azure.net/secrets/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
              }
            },
            "image": {
                "uri": ""
            },
            "managedDisk": {
                "id": "/subscriptions/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/resourceGroups/macikgo-test-may-23/providers/Microsoft.Compute/disks/exampleosdiskname",
                "storageAccountType": "StandardSSD_LRS"
            },
            "name": "exampleosdiskname",
            "osType": "Windows",
            "vhd": {
                "uri": ""
            },
            "writeAcceleratorEnabled": "false"
        },
        "resourceDisk": {
            "size": "4096"
        }
    },
    "subscriptionId": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
    "tags": "baz:bash;foo:bar",
    "version": "15.05.22",
    "virtualMachineScaleSet": {
      "id": "/subscriptions/xxxxxxxx-xxxxx-xxx-xxx-xxxx/resourceGroups/resource-group-name/providers/Microsoft.Compute/virtualMachineScaleSets/virtual-machine-scale-set-name"
    },
    "vmId": "02aab8a4-74ef-476e-8182-f6d2ba4166a6",
    "vmScaleSetName": "crpteste9vflji9",
    "vmSize": "Standard_A3",
    "zone": "3"
}

Exemple 5 : Obtenir l’environnement Azure dans lequel s’exécute la machine virtuelle

Azure dispose de plusieurs clouds souverains comme Azure Government. Vous avez parfois besoin de l’environnement Azure pour prendre certaines décisions liées au runtime. L’exemple suivant vous montre comment obtenir ce comportement.

Requête

Invoke-RestMethod -Headers @{"Metadata"="true"} -Method GET -NoProxy -Uri "http://169.254.169.254/metadata/instance/compute/azEnvironment?api-version=2018-10-01&format=text"

Réponse

AzurePublicCloud

Le cloud et les valeurs de l’environnement Azure sont listés ici.

Cloud Environnement Azure
Toutes les régions Azure mondiales en disponibilité générale AzurePublicCloud
Azure Government AzureUSGovernmentCloud
Microsoft Azure géré par 21Vianet AzureChinaCloud
Azure Allemagne AzureGermanCloud

Exemple 6 : Récupérer des informations sur le réseau

Requête

Invoke-RestMethod -Headers @{"Metadata"="true"} -Method GET -NoProxy -Uri "http://169.254.169.254/metadata/instance/network?api-version=2017-08-01" | ConvertTo-Json  -Depth 64

Réponse

{
  "interface": [
    {
      "ipv4": {
        "ipAddress": [
          {
            "privateIpAddress": "10.1.0.4",
            "publicIpAddress": "X.X.X.X"
          }
        ],
        "subnet": [
          {
            "address": "10.1.0.0",
            "prefix": "24"
          }
        ]
      },
      "ipv6": {
        "ipAddress": []
      },
      "macAddress": "000D3AF806EC"
    }
  ]
}

Exemple 7 : Récupérer l’IP publique

Invoke-RestMethod -Headers @{"Metadata"="true"} -Method GET -NoProxy -Uri "http://169.254.169.254/metadata/instance/network/interface/0/ipv4/ipAddress/0/publicIpAddress?api-version=2017-08-01&format=text"

Notes

Données attestées

Récupération de données attestées

IMDS permet de garantir que les données fournies proviennent d’Azure. Microsoft signe une partie de ces informations : vous pouvez donc vérifier qu’une image de la Place de marché Azure est bien celle que vous exécutez sur Azure.

GET /metadata/attested/document

Paramètres

Nom Obligatoires/facultatif Description
api-version Obligatoire Version utilisée pour traiter la demande.
nonce Facultatif Chaîne à 10 chiffres servant de nonce de chiffrement. Si aucune valeur n’est fournie, IMDS utilise l’horodatage UTC actuel.

response

{
    "encoding":"pkcs7",
    "signature":"MIIEEgYJKoZIhvcNAQcCoIIEAzCCA/8CAQExDzANBgkqhkiG9w0BAQsFADCBugYJKoZIhvcNAQcBoIGsBIGpeyJub25jZSI6IjEyMzQ1NjY3NjYiLCJwbGFuIjp7Im5hbWUiOiIiLCJwcm9kdWN0IjoiIiwicHVibGlzaGVyIjoiIn0sInRpbWVTdGFtcCI6eyJjcmVhdGVkT24iOiIxMS8yMC8xOCAyMjowNzozOSAtMDAwMCIsImV4cGlyZXNPbiI6IjExLzIwLzE4IDIyOjA4OjI0IC0wMDAwIn0sInZtSWQiOiIifaCCAj8wggI7MIIBpKADAgECAhBnxW5Kh8dslEBA0E2mIBJ0MA0GCSqGSIb3DQEBBAUAMCsxKTAnBgNVBAMTIHRlc3RzdWJkb21haW4ubWV0YWRhdGEuYXp1cmUuY29tMB4XDTE4MTEyMDIxNTc1N1oXDTE4MTIyMDIxNTc1NlowKzEpMCcGA1UEAxMgdGVzdHN1YmRvbWFpbi5tZXRhZGF0YS5henVyZS5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAML/tBo86ENWPzmXZ0kPkX5dY5QZ150mA8lommszE71x2sCLonzv4/UWk4H+jMMWRRwIea2CuQ5RhdWAHvKq6if4okKNt66fxm+YTVz9z0CTfCLmLT+nsdfOAsG1xZppEapC0Cd9vD6NCKyE8aYI1pliaeOnFjG0WvMY04uWz2MdAgMBAAGjYDBeMFwGA1UdAQRVMFOAENnYkHLa04Ut4Mpt7TkJFfyhLTArMSkwJwYDVQQDEyB0ZXN0c3ViZG9tYWluLm1ldGFkYXRhLmF6dXJlLmNvbYIQZ8VuSofHbJRAQNBNpiASdDANBgkqhkiG9w0BAQQFAAOBgQCLSM6aX5Bs1KHCJp4VQtxZPzXF71rVKCocHy3N9PTJQ9Fpnd+bYw2vSpQHg/AiG82WuDFpPReJvr7Pa938mZqW9HUOGjQKK2FYDTg6fXD8pkPdyghlX5boGWAMMrf7bFkup+lsT+n2tRw2wbNknO1tQ0wICtqy2VqzWwLi45RBwTGB6DCB5QIBATA/MCsxKTAnBgNVBAMTIHRlc3RzdWJkb21haW4ubWV0YWRhdGEuYXp1cmUuY29tAhBnxW5Kh8dslEBA0E2mIBJ0MA0GCSqGSIb3DQEBCwUAMA0GCSqGSIb3DQEBAQUABIGAld1BM/yYIqqv8SDE4kjQo3Ul/IKAVR8ETKcve5BAdGSNkTUooUGVniTXeuvDj5NkmazOaKZp9fEtByqqPOyw/nlXaZgOO44HDGiPUJ90xVYmfeK6p9RpJBu6kiKhnnYTelUk5u75phe5ZbMZfBhuPhXmYAdjc7Nmw97nx8NnprQ="
}

L’objet blob de signature est une version signée pkcs7 du document. Il contient le certificat utilisé pour la signature, ainsi que certains détails spécifiques de la machine virtuelle.

Pour les machines virtuelles créées avec Azure Resource Manager, le document comprend vmId, sku, nonce, subscriptionId et timeStamp pour la création et l’expiration du document, et les informations de plan de l’image. Les informations du plan ne sont fournies que pour les images de la Place de marché Azure.

Pour les machines virtuelles créées avec le modèle de déploiement classique, seul le remplissage de vmId et subscriptionId est garanti. Vous pouvez extraire le certificat de la réponse et l’utiliser pour vérifier que la réponse est valide et qu’elle provient d’Azure.

Le document décodé contient les champs suivants :

Données Description Version introduite
licenseType Type de licence pour Azure Hybrid Benefit. Présent seulement pour les machines virtuelles dotées d’AHB 2020-09-01
nonce Chaîne qui peut être éventuellement fournie avec la requête. Si la valeur de nonce n’a pas été fournie, l’horodatage UTC actuel est utilisé. 2018-10-01
plan Plan d’image de la Place de marché Azure. Contient l’ID de plan (name), l’image de produit ou l’offre (product) et l’ID d’éditeur (publisher). 2018-10-01
timestamp.createdOn Horodatage UTC de création du document signé. 2018-20-01
timestamp.expiresOn Horodatage UTC d’expiration du document signé. 2018-10-01
vmId Identificateur unique de la machine virtuelle 2018-10-01
subscriptionId Abonnement Azure pour la machine virtuelle 2019-04-30
sku Référence SKU spécifique pour l’image de machine virtuelle (correspond à la propriété compute/sku du point de terminaison Instance Metadata [/metadata/instance]) 2019-11-01

Notes

Pour les machines virtuelles Classic (hors Azure Resource Manager), seul le remplissage de vmId est garanti.

Exemple de document :

{
   "nonce":"20201130-211924",
   "plan":{
      "name":"planName",
      "product":"planProduct",
      "publisher":"planPublisher"
   },
   "sku":"Windows-Server-2012-R2-Datacenter",
   "subscriptionId":"8d10da13-8125-4ba9-a717-bf7490507b3d",
   "timeStamp":{
      "createdOn":"11/30/20 21:19:19 -0000",
      "expiresOn":"11/30/20 21:19:24 -0000"
   },
   "vmId":"02aab8a4-74ef-476e-8182-f6d2ba4166a6"
}

Conseils sur la validation de la signature

Lors de la validation de la signature, vous devez confirmer que la signature a été créée avec un certificat à partir d’Azure. Pour ce faire, validez le certificat Autre nom de l’objet (SAN).

Exemple de DNS Name=eastus.metadata.azure.com, DNS Name=metadata.azure.com SAN

Remarque

Le domaine est différent pour le cloud public et pour chaque cloud souverain.

Cloud Domaine dans SAN
Toutes les régions Azure mondiales en disponibilité générale *.metadata.azure.com
Azure Government *.metadata.azure.us
Azure géré par 21Vianet *.metadata.azure.cn
Azure Allemagne *.metadata.microsoftazure.de

Remarque

Les certificats peuvent ne pas avoir de correspondance exacte pour le domaine. Pour cette raison, la validation de la certification doit accepter n’importe quel sous-domaine (par exemple, dans les régions de disponibilité générale du cloud public, elle doit accepter *.metadata.azure.com).

Nous déconseillons l’épinglage de certificat pour les certificats intermédiaires. Pour obtenir des conseils supplémentaires, consultez Épinglage de certificat : épinglage de certificats et services Azure. Notez qu’Azure Instance Metadata Service n’offre PAS de notifications pour les futures modifications de l’autorité de certification. Au lieu de cela, vous devez suivre l’article Détails sur l’autorité de certification Azure centralisé pour les mises à jour futures.

Exemple 1 : Vérifier que la machine virtuelle s’exécute dans Azure

Les fournisseurs de la Place de marché Azure veulent être sûrs que la licence de leur logiciel autorise l’exécution seulement dans Azure. Si quelqu’un copie le disque dur virtuel dans un environnement local, le fournisseur doit pouvoir le détecter. Via IMDS, ces fournisseurs peuvent recevoir des données signées qui garantissent une réponse seulement depuis Azure.

Notes

Cet exemple nécessite l’installation de l’utilitaire jq.

Validation

# Get the signature
$attestedDoc = Invoke-RestMethod -Headers @{"Metadata"="true"} -Method GET -NoProxy -Uri http://169.254.169.254/metadata/attested/document?api-version=2020-09-01
# Decode the signature
$signature = [System.Convert]::FromBase64String($attestedDoc.signature)

Vérifiez que la signature provient de Microsoft Azure et recherchez les erreurs dans la chaîne de certificats.

# Get certificate chain
$cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]($signature)
$chain = New-Object -TypeName System.Security.Cryptography.X509Certificates.X509Chain
$chain.Build($cert)
# Print the Subject of each certificate in the chain
foreach($element in $chain.ChainElements)
{
    Write-Host $element.Certificate.Subject
}

# Get the content of the signed document
Add-Type -AssemblyName System.Security
$signedCms = New-Object -TypeName System.Security.Cryptography.Pkcs.SignedCms
$signedCms.Decode($signature);
$content = [System.Text.Encoding]::UTF8.GetString($signedCms.ContentInfo.Content)
Write-Host "Attested data: " $content
$json = $content | ConvertFrom-Json
# Do additional validation here

La valeur de nonce dans le document signé peut être comparée si vous avez fourni un paramètre nonce dans la requête initiale.

Identité gérée

Une identité managée, affectée par le système, peut être activée sur la machine virtuelle. Vous pouvez aussi affecter une ou plusieurs identités managées affectées par l’utilisateur à la machine virtuelle. Vous pouvez ensuite demander des jetons pour les identités gérées auprès d’IMDS. Utilisez ces jetons pour l’authentification auprès d’autres services Azure, comme Azure Key Vault.

Pour plus d’informations sur la procédure d’activation de cette fonctionnalité, consultez Obtenir un jeton d’accès.

Métadonnées de l’équilibreur de charge

Lorsque vous placez des instances de machine virtuelle ou de groupe de machines virtuelles derrière Azure Standard Load Balancer, utilisez IMDS pour récupérer les métadonnées relatives à l’équilibreur de charge et aux instances. Pour en savoir plus, consultez la section Récupérer les informations de l’équilibreur de charge.

Événements planifiés

Vous pouvez obtenir l’état des événements planifiés en utilisant IMDS. L’utilisateur peut ensuite spécifier un ensemble d’actions à exécuter pour ces événements. Pour plus d’informations, consultez Événements planifiés pour Linux ou Événements planifiés pour Windows.

Exemple de code dans différents langages

Le tableau suivant liste des exemples d’appel d’IMDS avec différents langages dans la machine virtuelle :

Langage Exemple
Bash https://github.com/Microsoft/azureimds/blob/master/IMDSSample.sh
C# https://github.com/Microsoft/azureimds/blob/master/IMDSSample.cs
Go https://github.com/Microsoft/azureimds/blob/master/imdssample.go
Java https://github.com/Microsoft/azureimds/blob/master/imdssample.java
NodeJS https://github.com/Microsoft/azureimds/blob/master/IMDSSample.js
Perl https://github.com/Microsoft/azureimds/blob/master/IMDSSample.pl
PowerShell https://github.com/Microsoft/azureimds/blob/master/IMDSSample.ps1
Puppet https://github.com/keirans/azuremetadata
Python https://github.com/Microsoft/azureimds/blob/master/IMDSSample.py
Ruby https://github.com/Microsoft/azureimds/blob/master/IMDSSample.rb

Erreurs et débogage

Si un élément de données est introuvable ou qu’une requête est mal formée, Instance Metadata Service retourne des erreurs HTTP standard. Par exemple :

Code d'état HTTP Motif
200 OK La demande a abouti.
400 Bad Request En-tête Metadata: true manquant ou paramètre format=json manquant lors de l’interrogation d’un nœud terminal
404 Not Found L’élément demandé n’existe pas
405 Method Not Allowed La méthode (verbe) HTTP n’est pas prise en charge sur le point de terminaison.
410 Gone Recommencez l’opération dans un délai maximum de 70 secondes
429 Too Many Requests Les limites de débit de l’API ont été dépassées
500 Service Error Recommencez l’opération plus tard

Forum aux questions

  • J’obtiens l’erreur 400 Bad Request, Required metadata header not specified. Qu’est-ce que cela signifie ?

    • IMDS requiert que l’en-tête Metadata: true soit passé dans la requête. Passer cet en-tête dans l’appel REST permet d’accéder à IMDS.

  • Pourquoi je n’obtiens pas les informations de calcul pour ma machine virtuelle ?

    • Actuellement, IMDS prend en charge seulement les instances créées avec Azure Resource Manager.

  • J’ai créé ma machine virtuelle par l’intermédiaire d’Azure Resource Manager il y a quelque temps. Pourquoi ne puis-je pas voir les informations de métadonnées de calcul ?

    • Si vous avez créé votre machine virtuelle après septembre 2016, ajoutez une étiquette pour commencer à voir les métadonnées de calcul. Si vous avez créé votre machine virtuelle avant septembre 2016, ajoutez ou supprimez des extensions ou des disques de données aux instances de machine virtuelle pour actualiser les métadonnées.

  • Les données utilisateur sont-elles identiques aux données personnalisées ?

    • Les données utilisateur offrent une fonctionnalité similaire aux données personnalisées, vous permettant de transmettre vos propres métadonnées à l’instance de machine virtuelle. La différence est que les données utilisateur sont récupérées via IMDS et sont persistantes pendant toute la durée de vie de l’instance de machine virtuelle. La fonctionnalité existante de données personnalisées continuera à fonctionner comme décrit dans cet article. Toutefois, vous pouvez uniquement récupérer des données personnalisées par le biais du dossier système local, et non par le biais d’IMDS.

  • Pourquoi je ne vois pas toutes les données renseignées pour une nouvelle version ?

    • Si vous avez créé votre machine virtuelle après septembre 2016, ajoutez une étiquette pour commencer à voir les métadonnées de calcul. Si vous avez créé votre machine virtuelle avant septembre 2016, ajoutez ou supprimez des extensions ou des disques de données aux instances de machine virtuelle pour actualiser les métadonnées.

  • Pourquoi est-ce que je reçois l’erreur 500 Internal Server Error ou 410 Resource Gone ?

    • Réessayez votre requête. Pour plus d’informations, consultez Gestion des erreurs transitoires. Si le problème persiste, créez un ticket de support dans le portail Azure pour la machine virtuelle.

  • Ceci fonctionne-t-il pour des instances de groupe identique ?

    • Oui, IMDS est disponible pour les instances de groupe identique.

  • J’ai mis à jour mes étiquettes dans mes groupes identiques, mais elles n’apparaissent pas dans les instances (contrairement aux machines virtuelles mono-instances). Ai-je fait une erreur quelque part ?

    • Actuellement, les étiquettes pour les groupes identiques s’affichent seulement sur la machine virtuelle lors d’un redémarrage, d’un réimageage ou d’un changement de disque de l’instance.

  • Pourquoi les informations de référence SKU n’apparaissent-elles pas pour ma machine virtuelle dans les détails de instance/compute?

    • Pour les images personnalisées créées à partir de la Place de marché Azure, la plateforme Azure ne conserve ni les informations de référence SKU de l’image personnalisée ni les détails des machines virtuelles créées à partir de cette image. Elle est conçue ainsi, d’où l’absence d’exposition dans les détails instance/compute de la machine virtuelle.

  • Pourquoi ma requête dépasse le délai d’attente (ou subit un échec de connexion) pour mon appel au service ?

    • Les appels de métadonnées doivent être effectués à partir de l’adresse IP principale affectée à la carte réseau principale de la machine virtuelle. De plus, si vous avez changé vos routes, il doit y avoir une route pour l’adresse 169.254.169.254/32 dans la table de routage locale de votre machine virtuelle.

      1. Produisez une image mémoire de votre table de routage locale et recherchez l’entrée IMDS. Par exemple :

        route print

        IPv4 Route Table
===========================================================================
Active Routes:
Network Destination        Netmask          Gateway       Interface  Metric
        0.0.0.0          0.0.0.0      172.16.69.1      172.16.69.7     10
        127.0.0.0        255.0.0.0         On-link         127.0.0.1    331
        127.0.0.1  255.255.255.255         On-link         127.0.0.1    331
127.255.255.255  255.255.255.255         On-link         127.0.0.1    331
    168.63.129.16  255.255.255.255      172.16.69.1      172.16.69.7     11
169.254.169.254  255.255.255.255      172.16.69.1      172.16.69.7     11
... (continues) ...

      2. Vérifiez qu’il existe une route pour 169.254.169.254 et notez l’interface réseau correspondante (par exemple 172.16.69.7).

      3. Produisez une image mémoire de la configuration de l’interface et recherchez l’interface qui correspond à celle référencée dans la table de routage, en notant l’adresse MAC (physique).

        ipconfig /all

        ... (continues) ...
Ethernet adapter Ethernet:

Connection-specific DNS Suffix  . : xic3mnxjiefupcwr1mcs1rjiqa.cx.internal.cloudapp.net
Description . . . . . . . . . . . : Microsoft Hyper-V Network Adapter
Physical Address. . . . . . . . . : 00-0D-3A-E5-1C-C0
DHCP Enabled. . . . . . . . . . . : Yes
Autoconfiguration Enabled . . . . : Yes
Link-local IPv6 Address . . . . . : fe80::3166:ce5a:2bd5:a6d1%3(Preferred)
IPv4 Address. . . . . . . . . . . : 172.16.69.7(Preferred)
Subnet Mask . . . . . . . . . . . : 255.255.255.0
... (continues) ...

      4. Vérifiez que l’interface correspond à la carte réseau principale et à l’adresse IP principale de la machine virtuelle. Vous pouvez trouver la carte réseau et l’adresse IP principales en examinant la configuration réseau dans le portail Azure ou en la recherchant avec Azure CLI. Notez les adresses IP privées (et l’adresse MAC si vous utilisez l’interface CLI). Voici un exemple PowerShell CLI :

        $ResourceGroup = '<Resource_Group>'
$VmName = '<VM_Name>'
$NicNames = az vm nic list --resource-group $ResourceGroup --vm-name $VmName | ConvertFrom-Json | Foreach-Object { $_.id.Split('/')[-1] }
foreach($NicName in $NicNames)
{
    $Nic = az vm nic show --resource-group $ResourceGroup --vm-name $VmName --nic $NicName | ConvertFrom-Json
    Write-Host $NicName, $Nic.primary, $Nic.macAddress
}

        wintest767 True 00-0D-3A-E5-1C-C0

      5. Si elles ne correspondent pas, mettez à jour la table de routage afin de cibler la carte réseau et l’adresse IP principales.

  • Clustering de basculement dans Windows Server

    • Quand vous interrogez IMDS avec le clustering de basculement, il est parfois nécessaire d’ajouter une route à la table de routage. Voici comment faire :

      1. Ouvrez une invite de commandes avec les privilèges Administrateur.

      2. Exécutez la commande suivante et notez l’adresse de l’interface pour la destination réseau (0.0.0.0) dans la table de routage IPv4.

      route print

      Notes

      L’exemple de sortie suivant provient d’une machine virtuelle Windows Server avec le cluster de basculement activé. Pour simplifier, la sortie contient seulement la table de routage IPv4.

      IPv4 Route Table
===========================================================================
Active Routes:
Network Destination        Netmask          Gateway       Interface  Metric
        0.0.0.0          0.0.0.0         10.0.1.1        10.0.1.10    266
        10.0.1.0  255.255.255.192         On-link         10.0.1.10    266
        10.0.1.10  255.255.255.255         On-link         10.0.1.10    266
        10.0.1.15  255.255.255.255         On-link         10.0.1.10    266
        10.0.1.63  255.255.255.255         On-link         10.0.1.10    266
        127.0.0.0        255.0.0.0         On-link         127.0.0.1    331
        127.0.0.1  255.255.255.255         On-link         127.0.0.1    331
127.255.255.255  255.255.255.255         On-link         127.0.0.1    331
    169.254.0.0      255.255.0.0         On-link     169.254.1.156    271
    169.254.1.156  255.255.255.255         On-link     169.254.1.156    271
169.254.255.255  255.255.255.255         On-link     169.254.1.156    271
        224.0.0.0        240.0.0.0         On-link         127.0.0.1    331
        224.0.0.0        240.0.0.0         On-link     169.254.1.156    271
255.255.255.255  255.255.255.255         On-link         127.0.0.1    331
255.255.255.255  255.255.255.255         On-link     169.254.1.156    271
255.255.255.255  255.255.255.255         On-link         10.0.1.10    266

      Exécutez la commande suivante et notez l’adresse de l’interface pour la destination réseau (0.0.0.0) qui est (10.0.1.10) dans cet exemple.

      route add 169.254.169.254/32 10.0.1.10 metric 1 -p

Support

Si vous ne pouvez pas obtenir une réponse de métadonnées après plusieurs tentatives, vous pouvez créer un ticket de support dans le portail Azure.

Commentaires sur le produit

Vous pouvez formuler des commentaires sur le produit et des idées sur notre canal de commentaires des utilisateurs, sous Machines virtuelles > Instance Metadata Service ici

Étapes suivantes