Serviço de metadados de instância do Azure

  • Artigo

Aplica-se a: ✔️ VMs Linux ✔️ VMs Windows ✔️ Conjuntos de dimensionamento flexíveis

O Serviço de Metadados de Instância (IMDS) do Azure fornece informações sobre instâncias da máquina virtual em execução no momento. Você pode usá-lo para gerenciar e configurar suas máquinas virtuais. Estas informações incluem o SKU, o armazenamento, as configurações de rede e os eventos de manutenção futura. Para obter uma lista completa dos dados disponíveis, confira o Resumo das categorias de ponto de extremidade.

O IMDS está disponível para a execução de instâncias de VMs (máquinas virtuais) e instâncias de conjunto de dimensionamento. Todos os pontos de extremidade dão suporte a VMs criadas e gerenciadas usando o Azure Resource Manager. Somente a categoria atestada e a parte da rede da categoria da Instância dão suporte a VMs criadas usando o modelo de implantação clássico. O ponto de extremidade atestado faz isso em um âmbito limitado.

O IMDS é uma API REST que está disponível em um endereço IP conhecido e não roteável (169.254.169.254). Você somente pode acessá-lo da VM. A comunicação entre a VM e a IMDS nunca sai do host. Faça seus clientes HTTP ignorarem os proxies Web na VM ao consultar o IMDS e tratarem 169.254.169.254 da mesma forma que 168.63.129.16.

Uso

Acessar o Serviço de Metadados de Instância do Azure

Para acessar o IMDS, crie uma VM no Azure Resource Manager ou no portal do Azure e siga as amostras abaixo. Para obter mais exemplo, confira Amostras de Metadados de Instância do Azure.

Aqui está o exemplo de código para recuperar todos os metadados de uma instância. Para acessar uma fonte de dados específica, consulte Categorias de ponto de extremidade para obter uma visão geral de todos os recursos disponíveis.

Solicitação

Importante

Este exemplo ignora proxies. Você deve ignorar os proxies ao consultar o IMDS. Confira Proxies para obter informações adicionais.

Observação

As solicitações IMDS devem ser enviadas usando a NIC e o IP primários da VM, e o DHCP deve estar habilitado.

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 requer o PowerShell V6 ou superior. Consulte o nosso repositório de amostras para obter exemplos de versões mais antigas do PowerShell.

Resposta

Observação

A resposta é uma cadeia de caracteres JSON. Todas as respostas de exemplo a seguir são estilos de formatação para facilitar a leitura.

{
    "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"
        }]
    }
}

Segurança e autenticação

O Serviço de Metadados de Instância está acessível somente dentro da instância de máquina virtual em execução em um endereço IP não roteável. As VMs só podem interagir com os próprios metadados e funcionalidades. A API é somente HTTP e nunca sai do host.

Para garantir que as solicitações sejam diretamente destinadas ao IMDS e impedir o redirecionamento não intencional ou indesejado de solicitações, as solicitações:

  • Devem conter o cabeçalho Metadata: true
  • Não devem conter o cabeçalho X-Forwarded-For

Solicitações que não atenderem a esses dois requisitos serão rejeitadas pelo serviço.

Importante

O IMDS não é um canal para dados sensíveis. A API não é autenticada e está aberta a todos os processos na VM. As informações expostas por esse serviço devem ser consideradas informações compartilhadas para todos os aplicativos em execução dentro da VM.

Se não for necessário que cada processo na VM acesse o ponto de extremidade do IMDS, você poderá definir regras de firewall locais para limitar o acesso. Por exemplo, se apenas um serviço de sistema conhecido precisar acessar o serviço de metadados da instância, você poderá definir uma regra de firewall no ponto de extremidade do IMDS, permitindo apenas que os processos específicos acessem ou negando acesso para o restante dos processos.

Proxies

O IMDS não deve ser usado atrás de um proxy e não há suporte a isso. A maioria dos clientes HTTP fornece uma opção para você desabilitar os proxies em suas solicitações, e essa funcionalidade deve ser utilizada ao se comunicar com o IMDS. Confira a documentação do seu cliente para obter detalhes.

Importante

Mesmo que você não conheça nenhuma configuração de proxy em seu ambiente, você ainda deve substituir as configurações padrão de proxy do cliente. As configurações de proxy podem ser descobertas automaticamente e deixar de ignorar essas configurações expõe você a riscos de interrupção, caso a configuração do computador seja alterada no futuro.

Limitação de taxa

Em geral, as solicitações ao IMDS são limitadas a cinco por segundo (por VM). As solicitações que excederem esse limite serão rejeitadas com respostas 429. As solicitações para a categoria Identidade gerenciada são limitadas a 20 solicitações por segundo e cinco solicitações simultâneas (em um regime por VM).

Verbos HTTP

Há suporte aos seguintes verbos HTTP:

Verbo Descrição
GET Recuperar o recurso solicitado

Parâmetros

Os pontos de extremidade podem ser compatíveis com parâmetros obrigatórios e/ou opcionais. Confira o Esquema e a documentação do ponto de extremidade específico em questão para obter detalhes.

Parâmetros de consulta

Os pontos de extremidade do IMDS dão suporte a parâmetros de cadeia de caracteres de consulta HTTP. Por exemplo:

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

Especifica os parâmetros:

Nome Valor
api-version 2021-01-01
format json

Solicitações com nomes de parâmetros de consulta duplicados serão rejeitadas.

Parâmetros de rota

Para alguns pontos de extremidade que retornam Blobs JSON maiores, damos suporte à anexação de parâmetros de rota ao ponto de extremidade da solicitação para filtrar um subconjunto da resposta:

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

Os parâmetros correspondem aos índices/chaves que seriam usados para percorrer o objeto JSON com o qual você está interagindo com uma representação analisada.

Por exemplo, /metadata/instance retorna o objeto json:

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

Se quisermos filtrar a resposta para apenas a propriedade de Computação, enviaremos a solicitação:

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

Da mesma forma, se quisermos filtrar uma propriedade aninhada ou elemento de matriz específico, manteremos a anexação de chaves:

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

filtraria o primeiro elemento da propriedade Network.interface e retornaria:

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

Observação

Ao filtrar para um nó folha, format=json não funciona. Para essas consultas, format=text precisa ser especificado explicitamente se o formato padrão for JSON.

Esquema

Formato de dados

Por padrão, o IMDS retorna os dados no formato JSON (Content-Type: application/json). No entanto, os pontos de extremidade que dão suporte à filtragem de resposta (confira Parâmetros de rota) também dão suporte ao formato text.

Para acessar um formato de resposta não padrão, especifique o formato solicitado como um parâmetro de cadeia de caracteres de consulta na solicitação. Por exemplo:

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

Em respostas JSON, todos os primitivos serão do tipo string, e os valores ausentes ou inaplicáveis sempre serão incluídos e definidos como uma cadeia de caracteres vazia.

Controle de versão

O IMDS tem controle de versão e a especificação da versão de API na solicitação HTTP é obrigatória. A única exceção a esse requisito é o ponto de extremidade de versões, que pode ser usado para recuperar dinamicamente as versões de API disponíveis.

Conforme versões mais recentes são adicionadas, as versões mais antigas ainda podem ser acessadas para fins de compatibilidade se os scripts tiverem dependências de formatos de dados específicos.

Quando você não especificar uma versão, obterá um erro com uma lista das versões mais recentes compatíveis:

{
    "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"
    ]
}

Versões de API com suporte

Observação

A versão 2023-11-15 ainda está sendo implementada e pode não estar disponível em algumas regiões.

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

Swagger

Uma definição completa do Swagger para o IMDS está disponível em: https://github.com/Azure/azure-rest-api-specs/blob/main/specification/imds/data-plane/readme.md

Disponibilidade regional

O serviço está em disponibilidade geral em todas nuvens do Azure.

Ponto de extremidade raiz

O ponto de extremidade raiz é http://169.254.169.254/metadata.

Categorias de ponto de extremidade

A API do IMDS contém várias categorias de ponto de extremidade que representam diferentes fontes de dados, cada uma contendo um ou mais pontos de extremidades. Confira cada categoria para obter detalhes.

Raiz da categoria DESCRIÇÃO Versão introduzida
/metadata/attested Confira Dados Atestados 01-10-2018
/metadata/identity Confira Identidade Gerenciada por meio do IMDS 01-02-2018
/metadata/instance Confira os Metadados da Instância 2017-04-02
/metadata/loadbalancer Confira Recuperar metadados do Load Balancer por meio do IMDS 2020-10-01
/metadata/scheduledevents Confira Eventos Agendados por meio do IMDS 2017-08-01
/metadata/versions Confira Versões N/D

Versões

Listar versões de API

Retorna o conjunto de versões de API compatíveis.

GET /metadata/versions

Parâmetros

Nenhum (este ponto de extremidade não tem controle de versão).

Resposta

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

Metadados da instância

Obter metadados da VM

Expõe os metadados importantes para a instância de VM, incluindo computação, rede e armazenamento.

GET /metadata/instance

Parâmetros

Nome Obrigatório/Opcional Descrição
api-version Obrigatório A versão usada para atender à solicitação.
format Opcional* O formato (json ou text) da resposta. *Observação: pode ser necessário ao usar parâmetros de solicitação

Esse ponto de extremidade dá suporte à filtragem de resposta por meio de parâmetros de rota.

Resposta

{
    "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"
        }]
    }
}

Divisão de esquema:

Computação

Dados Descrição Versão introduzida
azEnvironment Ambiente do Azure em que a VM está em execução 01-10-2018
additionalCapabilities.hibernationEnabled Identifica se a hibernação está habilitada na VM 01/11/2021
customData Esse recurso foi preterido e desabilitado no IMDS. Ele foi substituído por userData 2019-02-01
evictionPolicy Define como uma VM do Spot será removida. 2020-12-01
extendedLocation.type Tipo do local estendido da VM. 2021-03-01
extendedLocation.name Nome do local estendido da VM 2021-03-01
host.id Nome do host da VM. Observe que uma VM terá um host ou um hostGroup, mas não ambos. 15/11/2021
hostGroup.id Nome do hostGroup da VM. Observe que uma VM terá um host ou um hostGroup, mas não ambos. 15/11/2021
isHostCompatibilityLayerVm Identifica se a VM é executada na Camada de Compatibilidade do Host. 2020-06-01
licenseType Tipo de licença para o Benefício Híbrido do Azure. Está presente apenas para VMs habilitadas para AHB. 2020-09-01
location Região do Azure na qual a máquina virtual está sendo executada 2017-04-02
name Nome da VM 2017-04-02
offer Oferece informações para a imagem da VM e está presente apenas para imagens implantadas na galeria de imagens do Azure 2017-04-02
osProfile.adminUsername Especifica o nome da conta de administrador. 2020-07-15
osProfile.computerName Especifica o nome do computador. 2020-07-15
osProfile.disablePasswordAuthentication Especifica se a autenticação de senha está desabilitada. Está presente apenas para VMs do Linux. 2020-10-01
osType Linux ou Windows 2017-04-02
physicalZone Zona física da VM 2023-11-15
placementGroupId Grupo de posicionamento do conjunto de dimensionamento 2017-08-01
plan O Plano que contém o nome, o produto e o editor de uma VM, em caso de imagem do Azure Marketplace 2018-04-02
platformUpdateDomain Domínio de atualização no qual a máquina virtual está sendo executada 2017-04-02
platformFaultDomain Domínio de falha no qual a máquina virtual está sendo executada 2017-04-02
platformSubFaultDomain Subdomínio de falha no qual a VM está sendo executada, se aplicável. 01-10-2021
priority Prioridade da VM. Confira VMs do Spot para obter mais informações 2020-12-01
provider Provedor da VM 01-10-2018
publicKeys Coleção de Chaves Públicas atribuídas à VM e aos caminhos 2018-04-02
publisher Publicador da imagem da máquina virtual 2017-04-02
resourceGroupName Grupo de recursos para a sua Máquina Virtual 2017-08-01
resourceId A ID totalmente qualificada do recurso 2019-03-11
sku SKU específica para a imagem da máquina virtual 2017-04-02
securityProfile.secureBootEnabled Identifica se a inicialização segura do UEFI está habilitada na VM 2020-06-01
securityProfile.virtualTpmEnabled Identifica se o Trusted Platform Module (TPM) virtual está habilitado na VM 2020-06-01
securityProfile.encryptionAtHost Identifica se a Criptografia no host está habilitada na VM 01/11/2021
securityProfile.securityType Identifica se a VM é uma VM confiável ou uma VM confidencial 2021-12-13
storageProfile Confira Perfil de armazenamento abaixo 2019-06-01
subscriptionId Assinatura do Azure para a Máquina Virtual 2017-08-01
tags Marcas para a sua Máquina Virtual 2017-08-01
tagsList Marcas formatadas como uma matriz JSON para facilitar a análise programática 2019-06-04
userData O conjunto de dados especificado quando a VM foi criada para uso durante ou após o provisionamento (codificado em Base64) 01/01/2021
version Versão da imagem da máquina virtual 2017-04-02
virtualMachineScaleSet.id A ID do Conjunto de Dimensionamento de Máquinas Virtuais criado com orquestração flexível do qual a Máquina Virtual faz parte. Esse campo não está disponível para Conjuntos de Dimensionamento de Máquinas Virtuais criados com orquestração uniforme. 2021-03-01
vmId Identificador exclusivo da VM. O blog mencionado deve ser seguido apenas para VMs que têm SMBIOS < 2.6. Para VMs que têm SMBIOS >= 2.6, o UUID do DMI é exibido no formato little endian. Portanto, não há necessidade de mudar os bytes. 2017-04-02
vmScaleSetName Nome do conjunto de dimensionamento de máquinas virtuais do conjunto de dimensionamento 2017-12-01
vmSize Tamanho da VM 2017-04-02
zone Zona de Disponibilidade da máquina virtual 2017-12-01

† Esta versão ainda não está totalmente disponível e talvez não tenha suporte em todas as regiões.

Perfil de armazenamento

O perfil de armazenamento de uma VM é dividido em três categorias: referência de imagem, disco do sistema operacional e discos de dados, além de um objeto adicional para o disco temporário local.

O objeto de referência de imagem contém as seguintes informações sobre a imagem do SO. Observe que uma imagem pode vir da plataforma, do marketplace, da galeria da comunidade ou da galeria compartilhada direta, mas não de ambos:

Dados Descrição Versão introduzida
id ID de Recurso 2019-06-01
offer Oferta da imagem da plataforma ou do marketplace 2019-06-01
publisher Editor de imagem da plataforma ou do marketplace 2019-06-01
sku SKU da plataforma ou imagem do marketplace 2019-06-01
version Versão da imagem 2019-06-01
communityGalleryImageId ID do recurso da imagem da comunidade; caso contrário, vazio 2023-07-01
sharedGalleryImageId ID do recurso da imagem compartilhada direta, caso contrário, vazio 2023-07-01
exactVersion Versão da comunidade ou imagem compartilhada direta 2023-07-01

O objeto de disco do sistema operacional contém as seguintes informações sobre o disco do sistema operacional pela VM:

Dados Descrição
caching Requisitos de cache
createOption Informações sobre como a VM foi criada
diffDiskSettings Configurações do disco efêmero
diskSizeGB Tamanho do disco em GB
image Disco rígido virtual de imagem do usuário de origem
managedDisk Parâmetros do disco gerenciado
name Nome do disco
vhd Disco rígido virtual
writeAcceleratorEnabled Se writeAccelerator está habilitado ou não no disco

A matriz de discos de dados contém uma lista dos discos de dados anexada à VM. Cada objeto de disco de dados contém as seguintes informações:

Dados Descrição Versão introduzida
bytesPerSecondThrottle* Cota de leitura/gravação de disco em bytes 2021-05-01
caching Requisitos de cache 2019-06-01
createOption Informações sobre como a VM foi criada 2019-06-01
diffDiskSettings Configurações do disco efêmero 2019-06-01
diskCapacityBytes* Tamanho do disco em bytes 2021-05-01
diskSizeGB Tamanho do disco em GB 2019-06-01
encryptionSettings Configurações de criptografia do disco 2019-06-01
image Disco rígido virtual de imagem do usuário de origem 2019-06-01
isSharedDisk* Identifica se o disco é compartilhado entre os recursos 2021-05-01
isUltraDisk Identifica se o disco de dados é um Disco Ultra 2021-05-01
lun Número de unidade lógica do disco 2019-06-01
managedDisk Parâmetros do disco gerenciado 2019-06-01
name Nome do disco 2019-06-01
opsPerSecondThrottle* Cota de leitura/gravação de disco em IOPS 2021-05-01
osType Tipo de sistema operacional incluído no disco 2019-06-01
vhd Disco rígido virtual 2019-06-01
writeAcceleratorEnabled Se writeAccelerator está habilitado ou não no disco 2019-06-01

* Estes campos são preenchidos apenas para Discos Ultra. Eles serão cadeias de caracteres vazias para discos que não forem Ultra.

O blob de configurações de criptografia contém dados que indicam como o disco é criptografado (quando ele é criptografado):

Dados Descrição Versão introduzida
diskEncryptionKey.sourceVault.id O local da chave de criptografia de disco 01/11/2021
diskEncryptionKey.secretUrl O local do segredo 01/11/2021
keyEncryptionKey.sourceVault.id O local da chave de criptografia de chave 01/11/2021
keyEncryptionKey.keyUrl O local da chave 01/11/2021

O objeto de disco de recurso contém o tamanho do Disco Temporário Local anexado à VM, se tiver uma, em quilobytes. Se não houver nenhum disco temporário local para a VM, esse valor será 0.

Dados Descrição Versão introduzida
resourceDisk.size Tamanho do disco temporário local para a VM (em kB) 01/02/2021

Rede

Dados Descrição Versão introduzida
ipv4.privateIpAddress Endereço IPv4 local da máquina virtual 2017-04-02
ipv4.publicIpAddress Endereço IPv4 local da máquina virtual 2017-04-02
subnet.address Endereço sub-rede da máquina virtual 2017-04-02
subnet.prefix Prefixo de sub-rede, exemplo 24 2017-04-02
ipv6.ipAddress Endereço IPv6 local da máquina virtual 2017-04-02
macAddress Endereço mac da máquina virtual 2017-04-02

Observação

Não há garantia de que as NICs retornadas pela chamada de rede estarão em ordem.

Obter dados do usuário

Ao criar uma nova VM, você pode especificar um conjunto de dados a serem usados durante ou após o provisionamento da VM, e recuperá-lo através do IMDS. Verifique a experiência de dados de ponta a ponta do usuário aqui.

Para configurar dados do usuário, utilize o modelo de início rápido aqui. O exemplo a seguir mostra como recuperar esses dados através do IMDS. Este recurso é liberado com a versão 2021-01-01 e superior.

Observação

Aviso de segurança: o IMDS está aberto para todos os aplicativos na VM, e dados confidenciais não devem ser inseridos nos dados do usuário.

$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))

Exemplo 1: VM de controle em execução no Azure

Como provedor de serviço, você talvez precise controlar o número de máquinas virtuais que executam o seu software ou ter agentes que precisam controlar a exclusividade da máquina virtual. Para obter uma ID exclusiva de uma máquina virtual, use o vmId campo do serviço de metadados de instância.

Solicitação

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"

Resposta

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

Exemplo 2: posicionamento de réplicas de dados diferentes

Para determinados cenários nos quais o posicionamento de réplicas diferentes é de vital importância. Por exemplo, o posicionamento de réplica de HDFS ou o posicionamento do contêiner por meio de um orquestrador pode exigir que você conheça platformFaultDomain e platformUpdateDomain em que a máquina virtual está sendo executada. Também é possível usar as Zonas de Disponibilidade das instâncias para tomar essas decisões. Você pode consultar esses dados diretamente no IMDS.

Solicitação

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"

Resposta

0

Amostra 3: obter as marcas da VM

As marcas de VM são incluídas na API de instância no ponto de extremidade de instância/computação/marcações. As marcas podem ter sido aplicadas à VM do Azure para organizá-las logicamente em uma taxonomia. As marcas atribuídas a uma VM podem ser recuperadas usando a solicitação abaixo.

Solicitação

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"

Resposta

Department:IT;ReferenceNumber:123456;TestStatus:Pending

O campo tags é uma cadeia de caracteres com as marcas delimitadas por ponto e vírgula. Essa saída pode ser um problema se o ponto e vírgula for usado nas próprias marcas. Se um analisador for escrito para extrair as marcas de maneira programática, você deverá contar com o campo tagsList. O campo tagsList é uma matriz JSON sem delimitadores e, consequentemente, mais fácil de analisar. A tagsList atribuída a uma VM pode ser recuperada usando a solicitação abaixo.

Solicitação

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

Resposta

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

Exemplo 4: obter mais informações sobre a VM durante a ocorrência de suporte

Como provedor de serviços, você poderá receber uma chamada de suporte na qual gostaria de ter mais informações sobre a máquina virtual. Pedir ao cliente para informar os metadados de computação pode fornecer informações básicas para o profissional de suporte saber o tipo de VM no Azure.

Solicitação

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

Resposta

Observação

A resposta é uma cadeia de caracteres JSON. Todas as respostas de exemplo a seguir são estilos de formatação para facilitar a leitura.

{
    "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"
}

Exemplo 5: obter o Ambiente do Azure em que a VM está em execução

O Azure tem várias nuvens soberanas, como o Azure Governamental. Às vezes, é necessário que o Ambiente do Azure tome algumas decisões de runtime. O exemplo a seguir mostra como você pode gerar tal comportamento.

Solicitação

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"

Resposta

AzurePublicCloud

A nuvem e os valores do Ambiente do Azure estão listados abaixo.

Nuvem Ambiente do Azure
Todas as regiões globais do Azure disponíveis AzurePublicCloud
Azure Governamental AzureUSGovernmentCloud
Microsoft Azure operado pela 21Vianet AzureChinaCloud
Azure Alemanha AzureGermanCloud

Exemplo 6: recuperar informações de rede

Solicitação

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

Resposta

{
  "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"
    }
  ]
}

Exemplo 7: recuperar endereço IP público

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"

Observação

  • Se você quiser recuperar informações do IMDS de um endereço IP público do SKU Standard, confira a API de metadados do Load Balancer para obter mais informações.

Dados atestados

Obter dados atestados

O IMDS ajuda a fornecer garantias de que os dados fornecidos são provenientes do Azure. A Microsoft assina parte dessas informações para que você possa validar se uma imagem no Azure Marketplace é aquela que você está executando no Azure.

GET /metadata/attested/document

Parâmetros

Nome Obrigatório/Opcional Descrição
api-version Obrigatório A versão usada para atender à solicitação.
nonce Opcional Uma cadeia de caracteres de 10 dígitos que serve como um nonce criptográfico. Se nenhum valor for fornecido, o IMDS usará o carimbo de data/hora UTC atual.

Resposta

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

O blob de assinatura é uma versão assinada por pkcs7 do documento. Ele contém o certificado usado para assinar, juntamente com determinados detalhes específicos da VM.

Para VMs criadas usando o Azure Resource Manager, o documento inclui vmId, sku, nonce, subscriptionId, timeStamp para a criação e expiração do documento, além de informações do plano sobre a imagem. As informações do plano são preenchidas apenas para as imagens do Azure Marketplace.

Para as VMs criadas por meio do modelo de implantação clássico, somente a vmId e a subscriptionId terão a garantia de serem preenchidos. Você pode extrair o certificado da resposta e usá-lo para confirmar que a resposta é válida e proveniente do Azure.

O documento decodificado contém os seguintes campos:

Dados Descrição Versão introduzida
licenseType Tipo de licença para o Benefício Híbrido do Azure. Está presente apenas para VMs habilitadas para AHB. 2020-09-01
nonce Uma cadeia de caracteres que pode ser fornecida opcionalmente com a solicitação. Se nenhum nonce for fornecido, será usado o carimbo de data/hora atual no Tempo Universal Coordenado. 01-10-2018
plan O plano de Imagem do Azure Marketplace. Contém a ID do plano (nome), a imagem do produto ou da oferta (produto) e a ID do editor (publicador). 01-10-2018
timestamp.createdOn O carimbo de data/hora UTC em que o primeiro documento assinado foi criado. 2018-20-01
timestamp.expiresOn O carimbo de data/hora UTC em que o documento assinado expira. 01-10-2018
vmId Identificador exclusivo para a máquina virtual 01-10-2018
subscriptionId Assinatura do Azure para a Máquina Virtual 2019-04-30
sku SKU específico para a imagem de VM (correlacionado à propriedade compute/sku do ponto de extremidade de metadados da instância [/metadata/instance]) 2019-11-01

Observação

Para VMs clássicas (não Azure Resource Manager), somente o vmId será preenchido garantidamente.

Documento de exemplo:

{
   "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"
}

Diretrizes de validação de assinatura

Ao validar a assinatura, confirme se a assinatura foi criada com um certificado do Azure. Isso é feito ao validar o SAN (nome alternativo da entidade do certificado).

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

Observação

O domínio para a nuvem pública e a nuvem soberana serão diferentes.

Nuvem Domínio em SAN
Todas as regiões globais do Azure disponíveis *.metadata.azure.com
Azure Governamental *.metadata.azure.us
Azure operado pela 21Vianet *.metadata.azure.cn
Azure Alemanha *.metadata.microsoftazure.de

Observação

Os certificados podem não ter uma correspondência exata para o domínio. Por esse motivo, a validação da certificação deve aceitar qualquer subdomínio (por exemplo, em regiões de disponibilidade geral da nuvem pública aceitam *.metadata.azure.com).

Não é recomendável a fixação de certificados para certificados intermediários. Para obter mais diretrizes, consulte a Fixação de certificado – fixação de certificado e os serviços do Azure. Observe que o Serviço de Metadados da Instância do Azure NÃO oferecerá notificações para futuras alterações da Autoridade de Certificação. Em vez disso, siga o artigo centralizado de detalhes da Autoridade de Certificação do Azure para todas as atualizações futuras.

Exemplo 1: verificar se a VM está em execução no Azure

Os fornecedores do Azure Marketplace desejam atestar que seu software está licenciado para ser executado somente no Azure. Se alguém copiar o VHD para um ambiente local, o fornecedor deverá poder detectar isso. Por meio do IMDS, esses fornecedores podem obter dados assinados que garantem a resposta somente do Azure.

Observação

Este exemplo exige que o utilitário jq seja instalado.

Validação

# 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)

Verifique se a assinatura é do Microsoft Azure e se há erros na cadeia de certificados.

# 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

O nonce no documento assinado pode ser comparado se você forneceu um parâmetro nonce na solicitação inicial.

Identidade gerenciada

Uma identidade gerenciada, atribuída pelo sistema, pode ser habilitada na VM. Você também pode atribuir uma ou mais identidades gerenciadas atribuídas pelo usuário à VM. Você pode solicitar tokens para identidades gerenciadas do IMDS. Use esses tokens para autenticar usando outros serviços do Azure, como o Azure Key Vault.

Para obter as etapas detalhadas para habilitar esse recurso, confira Adquirir um token de acesso.

Metadados do Load Balancer

Ao posicionar as instâncias de máquina virtual ou de conjunto de máquinas virtuais atrás de um Azure Standard Load Balancer, você pode usar o IMDS para recuperar metadados relacionados ao balanceador de carga e às instâncias. Para obter mais informações, confira Recuperar informações do balanceador de carga.

Eventos agendados

Você pode obter o status dos eventos agendados usando o IMDS. Em seguida, o usuário pode especificar um conjunto de ações a serem executadas quanto a esses eventos. Para obter mais informações, consulte Eventos agendados para Linux ou Eventos agendados para Windows.

Exemplo de código em diferentes linguagens

Esta tabela lista exemplos de como chamar o IMDS usando diferentes linguagens dentro da VM:

Linguagem Exemplo
Bash https://github.com/Microsoft/azureimds/blob/master/IMDSSample.sh
C# https://github.com/Microsoft/azureimds/blob/master/IMDSSample.cs
Ir 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

Erros e depuração

Se houver um elemento de dados não encontrado ou solicitações malformadas, o Serviço de Metadados de Instância retornará o erro HTTP padrão. Por exemplo:

Código de status HTTP Motivo
200 OK A solicitação foi bem-sucedida.
400 Bad Request Cabeçalho Metadata: true ou parâmetro format=json ausente ao consultar um nó folha
404 Not Found O elemento solicitado não existe
405 Method Not Allowed Não há suporte ao método HTTP (verbo) no ponto de extremidade.
410 Gone Tente novamente após algum tempo por no máximo 70 segundos
429 Too Many Requests Os Limites de Taxa da API foram excedidos
500 Service Error Aguarde um pouco e tente novamente

Perguntas frequentes

  • Estou recebendo o erro 400 Bad Request, Required metadata header not specified. O que isso significa?

    • O IMDS exige que o cabeçalho Metadata: true seja passado na solicitação. Passar o cabeçalho na chamada de REST permite acessar o IMDS.

  • Por que não estou obtendo informações de computação para minha máquina virtual?

    • Atualmente o IMDS dá suporte apenas às instâncias criadas com o Azure Resource Manager.

  • Eu criei minha VM por meio do Azure Resource Manager algum tempo atrás. Por que não consigo ver as informações de metadados de computação?

    • Se você criou sua VM após setembro de 2016, adicione uma marca para começar a ver os metadados de computação. Se você criou sua VM antes de setembro de 2016, adicione ou remova extensões ou discos de dados da instância de VM para atualizar os metadados.

  • Os dados do usuário são os mesmos que os dados personalizados?

    • Os dados do usuário oferecem a funcionalidade semelhante aos dados personalizados, permitindo que você passe seus próprios metadados para a instância da VM. A diferença é que os dados do usuário são recuperados pelo IMDS e são persistentes durante todo o tempo de vida da instância da VM. O recurso de dados personalizados existente continuará funcionando conforme descrito neste artigo. No entanto, você só pode obter dados personalizados através da pasta do sistema local, não através do IMDS.

  • Por que não estou vendo todos os dados preenchidos para a nova versão?

    • Se você criou sua VM após setembro de 2016, adicione uma marca para começar a ver os metadados de computação. Se você criou sua VM antes de setembro de 2016, adicione ou remova extensões ou discos de dados da instância de VM para atualizar os metadados.

  • Por que estou recebendo o erro 500 Internal Server Error ou 410 Resource Gone?

    • Repita a solicitação. Para obter mais informações, confira Manipulação de falhas transitórias. Se o problema persistir, crie um problema de suporte no portal do Azure para a VM.

  • Isso funciona para instância de conjunto de dimensionamento?

    • Sim, o IMDS está disponível para instâncias de conjunto de dimensionamento.

  • Atualizei minhas marcas nos conjuntos de dimensionamento, mas elas não são exibidas nas instâncias (ao contrário das VM de instância única). Estou fazendo algo errado?

    • No momento, as marcas de conjuntos de dimensionamento são exibidas para a VM apenas durante uma reinicialização, uma ação de refazer imagem ou uma alteração de disco da instância.

  • Por que não estou vendo as informações de SKU da minha VM nos instance/compute detalhes?

    • Para imagens personalizadas criadas no Azure Marketplace, a plataforma Azure não retém as informações de SKU da imagem personalizada e os detalhes de todas as VMs criadas a partir da imagem personalizada. Isso ocorre intencionalmente e, portanto, não é exibido nos detalhes instance/compute da VM.

  • Por que minha solicitação atinge o tempo limite (ou não se conecta) para minha chamada ao serviço?

    • As chamadas de metadados devem ser feitas do endereço IP primário atribuído à placa de rede primária da VM. Além disso, se você alterou suas rotas, deve haver uma rota para o endereço 169.254.169.254/32 na tabela de roteamento local da VM.

      1. Despeje sua tabela de roteamento local e procure a entrada IMDS. Por exemplo:

        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. Verifique se existe uma rota para 169.254.169.254 e anote a interface de rede correspondente (por exemplo, 172.16.69.7).

      3. Despeje a configuração da interface e localize a interface que corresponde à interface referenciada na tabela de roteamento, anotando o endereço MAC (físico).

        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. Confirme se a interface corresponde ao NIC e ao IP primários da VM. Você pode encontrar o NIC e o IP primário verificando a configuração de rede no portal do Azure ou na CLI do Azure. Anote os IPs privados (e o endereço MAC se você estiver usando a CLI). Exemplo da CLI do PowerShell:

        $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. Se eles não corresponderem, atualize a tabela de roteamento para que o NIC e o IP primários sejam direcionados.

  • Fazer failover do clustering no Windows Server

    • Quando você consulta o IMDS com clustering de failover, às vezes é necessário adicionar uma rota à tabela de roteamento. Aqui está como:

      1. Abra uma prompt de comando com privilégios de administrador.

      2. Execute o seguinte comando e anote o endereço da Interface de rede de destino (0.0.0.0) na tabela de rotas do IPv4.

      route print

      Observação

      A saída de exemplo a seguir é de uma VM do Windows Server com cluster de failover habilitado. Para simplificar, a saída contém apenas a tabela de roteamento 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

      Execute o seguinte comando e anote o endereço da Interface de rede de destino (0.0.0.0) que é o (10.0.1.10) neste exemplo.

      route add 169.254.169.254/32 10.0.1.10 metric 1 -p

Suporte

Se você não conseguir obter uma resposta dos metadados após várias tentativas, crie um problema de suporte no portal do Azure.

Comentários sobre o produto

Você pode fornecer comentários sobre o produto e ideias para nosso canal de comentários do usuário em Máquinas Virtuais > Serviço de Metadados de Instância aqui

Próximas etapas