Skip to content

Commit 53c6eda

Browse files
NingKuangNingKuang
committed
update based on feedback, add back version 2019-11-01 description, update regional/version section, add scheduled task to next step
1 parent 5575b9d commit 53c6eda

File tree

1 file changed

+81
-100
lines changed

1 file changed

+81
-100
lines changed

‎articles/virtual-machines/linux/instance-metadata-service.md

Lines changed: 81 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -18,27 +18,11 @@ ms.reviewer: azmetadata
1818
## Summary
1919

2020
The Azure Instance Metadata Service (IMDS) provides information about currently running virtual machine instances and can be used to manage and configure your virtual machines.
21-
This includes the SKU, storage, network configurations, and upcoming maintenance events. For a complete list of the data that is available, see [metadata APIs](#-Metadata-APIs).
21+
This includes the SKU, storage, network configurations, and upcoming maintenance events. For a complete list of the data that is available, see [metadata APIs](#metadata-apis).
2222
Instance Metadata Service is available for both the VM and virtual machine scale set Instances. It is only available for running VMs created/managed using [Azure Resource Manager](https://docs.microsoft.com/rest/api/resources/).
2323

2424
Azure's Instance Metadata Service is a REST Endpoint that is available at a well-known non-routable IP address (`169.254.169.254`), it can be accessed only from within the VM.
2525

26-
> [!IMPORTANT]
27-
> This service is **generally available** in all Azure Regions. It regularly receives updates to expose new information and features. This page reflects the up-to-date [metadata APIs](#-Metadata-APIs) available.
28-
29-
## Regional Availability
30-
31-
The service is available in generally available Azure regions. Not all API version may be available in all Azure Regions.
32-
33-
Regions | Availability? | Supported Versions
34-
-----------------------------------------------|-----------------------------------------------|-----------------
35-
[All Generally Available Global Azure Regions](https://azure.microsoft.com/regions/) | Generally Available | 2017-04-02, 2017-08-01, 2017-12-01, 2018-02-01, 2018-04-02, 2018-10-01, 2019-02-01, 2019-03-11, 2019-04-30, 2019-06-01, 2019-06-04, 2019-08-01, 2019-08-15
36-
[Azure Government](https://azure.microsoft.com/overview/clouds/government/) | Generally Available | 2017-04-02, 2017-08-01, 2017-12-01, 2018-02-01, 2018-04-02, 2018-10-01, 2019-02-01, 2019-03-11, 2019-04-30, 2019-06-01, 2019-06-04, 2019-08-01, 2019-08-15
37-
[Azure China 21Vianet](https://www.azure.cn/) | Generally Available | 2017-04-02, 2017-08-01, 2017-12-01, 2018-02-01, 2018-04-02, 2018-10-01, 2019-02-01, 2019-03-11, 2019-04-30, 2019-06-01, 2019-06-04, 2019-08-01, 2019-08-15
38-
[Azure Germany](https://azure.microsoft.com/overview/clouds/germany/) | Generally Available | 2017-04-02, 2017-08-01, 2017-12-01, 2018-02-01, 2018-04-02, 2018-10-01, 2019-02-01, 2019-03-11, 2019-04-30, 2019-06-01, 2019-06-04, 2019-08-01, 2019-08-15
39-
40-
This table is updated when there are service updates and or new supported versions are available.
41-
4226
## Security
4327

4428
The Instance Metadata Service endpoint is accessible only from within the running virtual machine instance on a non-routable IP address. In addition, any request with a `X-Forwarded-For` header is rejected by the service.
@@ -54,8 +38,7 @@ Requests must also contain a `Metadata: true` header to ensure that the actual r
5438
To access Instance Metadata Service, create a VM from [Azure Resource Manager](https://docs.microsoft.com/rest/api/resources/) or the [Azure portal](https://portal.azure.com), and follow the samples below.
5539
More examples of how to query IMDS can be found at [Azure Instance Metadata Samples](https://github.com/microsoft/azureimds).
5640

57-
58-
Below is the sample code to retrieve all metadata for an instance, to access specific data source, see [Metadata API](#-metadata-apis) section.
41+
Below is the sample code to retrieve all metadata for an instance, to access specific data source, see [Metadata API](#metadata-apis) section.
5942

6043
**Request**
6144

@@ -203,7 +186,9 @@ curl -H Metadata:true "http://169.254.169.254/metadata/instance?api-version=2017
203186

204187
The Instance Metadata Service is versioned and specifying the API version in the HTTP request is mandatory.
205188

206-
You can see the newest versions listed in this [availability table](#-Regional-Availability).
189+
Follow are the supported service versions: 2017-04-02, 2017-08-01, 2017-12-01, 2018-02-01, 2018-04-02, 2018-10-01, 2019-02-01, 2019-03-11, 2019-04-30, 2019-06-01, 2019-06-04, 2019-08-01, 2019-08-15.
190+
191+
Note when new version is released, it will take a while to roll out to all regions. Currently version 2019-11-01 is still getting deployed and may not be available in all regions.
207192

208193
As newer versions are added, older versions can still be accessed for compatibility if your scripts have dependencies on specific data formats.
209194

@@ -236,8 +221,8 @@ IMDS contains multiple API interfaces representing different data sources.
236221

237222
Data | Description | Version Introduced
238223
-----|-------------|-----------------------
239-
instance | See [Instance API](#-Instance-API) | 2017-04-02
240-
attested | See [Attested Data](#-Attested-Data) | 2018-10-01
224+
instance | See [Instance API](#instance-api) | 2017-04-02
225+
attested | See [Attested Data](#attested-data) | 2018-10-01
241226
identity | See [Acquire an access token](../../active-directory/managed-identities-azure-resources/how-to-use-vm-token.md) | 2018-02-01
242227
scheduledevents | See [Scheduled Events](scheduled-events.md) | 2017-08-01
243228

@@ -274,7 +259,6 @@ vmScaleSetName | [Virtual machine scale set Name](../../virtual-machine-scale-se
274259
vmSize | [VM size](sizes.md) | 2017-04-02
275260
zone | [Availability Zone](../../availability-zones/az-overview.md) of your virtual machine | 2017-12-01
276261

277-
278262
### Sample 1: Tracking VM running on Azure
279263

280264
As a service provider, you may require to track the number of VMs running your software or have agents that need to track uniqueness of the VM. To be able to get a unique ID for a VM, use the `vmId` field from Instance Metadata Service.
@@ -434,6 +418,69 @@ The cloud and the values of the Azure Environment are listed below.
434418
[Azure China 21Vianet](https://azure.microsoft.com/global-infrastructure/china/) | AzureChinaCloud
435419
[Azure Germany](https://azure.microsoft.com/overview/clouds/germany/) | AzureGermanCloud
436420

421+
## Network Metadata
422+
423+
Network metadata is part of the instance API. The following Network categories are available through the instance/network endpoint.
424+
425+
Data | Description | Version Introduced
426+
-----|-------------|-----------------------
427+
ipv4/privateIpAddress | Local IPv4 address of the VM | 2017-04-02
428+
ipv4/publicIpAddress | Public IPv4 address of the VM | 2017-04-02
429+
subnet/address | Subnet address of the VM | 2017-04-02
430+
subnet/prefix | Subnet prefix, example 24 | 2017-04-02
431+
ipv6/ipAddress | Local IPv6 address of the VM | 2017-04-02
432+
macAddress | VM mac address | 2017-04-02
433+
434+
> [!NOTE]
435+
> All API responses are JSON strings. All following example responses are pretty-printed for readability.
436+
437+
#### Sample 1: Retrieving network information
438+
439+
***Request***
440+
441+
```bash
442+
curl -H Metadata:true "http://169.254.169.254/metadata/instance/network?api-version=2017-08-01"
443+
```
444+
445+
***Response***
446+
447+
> [!NOTE]
448+
> The response is a JSON string. The following example response is pretty-printed for readability.
449+
450+
```json
451+
{
452+
"interface": [
453+
{
454+
"ipv4": {
455+
"ipAddress": [
456+
{
457+
"privateIpAddress": "10.1.0.4",
458+
"publicIpAddress": "X.X.X.X"
459+
}
460+
],
461+
"subnet": [
462+
{
463+
"address": "10.1.0.0",
464+
"prefix": "24"
465+
}
466+
]
467+
},
468+
"ipv6": {
469+
"ipAddress": []
470+
},
471+
"macAddress": "000D3AF806EC"
472+
}
473+
]
474+
}
475+
476+
```
477+
478+
#### Sample 2: Retrieving public IP address
479+
480+
```bash
481+
curl -H Metadata:true "http://169.254.169.254/metadata/instance/network/interface/0/ipv4/ipAddress/0/publicIpAddress?api-version=2017-08-01&format=text"
482+
483+
```
437484

438485
## Storage Metadata
439486

@@ -596,71 +643,6 @@ curl -H Metadata:true "http://169.254.169.254/metadata/instance/compute/tagsList
596643
]
597644
```
598645

599-
## Network Metadata
600-
601-
Network metadata is part of the instance API. The following Network categories are available through the instance/network endpoint.
602-
603-
Data | Description | Version Introduced
604-
-----|-------------|-----------------------
605-
ipv4/privateIpAddress | Local IPv4 address of the VM | 2017-04-02
606-
ipv4/publicIpAddress | Public IPv4 address of the VM | 2017-04-02
607-
subnet/address | Subnet address of the VM | 2017-04-02
608-
subnet/prefix | Subnet prefix, example 24 | 2017-04-02
609-
ipv6/ipAddress | Local IPv6 address of the VM | 2017-04-02
610-
macAddress | VM mac address | 2017-04-02
611-
612-
> [!NOTE]
613-
> All API responses are JSON strings. All following example responses are pretty-printed for readability.
614-
615-
#### Sample 1: Retrieving network information
616-
617-
***Request***
618-
619-
```bash
620-
curl -H Metadata:true "http://169.254.169.254/metadata/instance/network?api-version=2017-08-01"
621-
```
622-
623-
***Response***
624-
625-
> [!NOTE]
626-
> The response is a JSON string. The following example response is pretty-printed for readability.
627-
628-
```json
629-
{
630-
"interface": [
631-
{
632-
"ipv4": {
633-
"ipAddress": [
634-
{
635-
"privateIpAddress": "10.1.0.4",
636-
"publicIpAddress": "X.X.X.X"
637-
}
638-
],
639-
"subnet": [
640-
{
641-
"address": "10.1.0.0",
642-
"prefix": "24"
643-
}
644-
]
645-
},
646-
"ipv6": {
647-
"ipAddress": []
648-
},
649-
"macAddress": "000D3AF806EC"
650-
}
651-
]
652-
}
653-
654-
```
655-
656-
#### Sample 2: Retrieving public IP address
657-
658-
```bash
659-
curl -H Metadata:true "http://169.254.169.254/metadata/instance/network/interface/0/ipv4/ipAddress/0/publicIpAddress?api-version=2017-08-01&format=text"
660-
661-
```
662-
663-
664646
## Attested Data
665647

666648
Part of the scenario served by Instance Metadata Service is to provide guarantees that the data provided is coming from Azure. We sign part of this information so that marketplace images can be sure that it's their image running on Azure.
@@ -677,7 +659,7 @@ curl -H Metadata:true "http://169.254.169.254/metadata/attested/document?api-ver
677659

678660
```
679661

680-
Api-version is a mandatory field. Refer to the [service availability section](#service-availability) for supported API versions.
662+
Api-version is a mandatory field. Refer to the [usage section](#Usage) for supported API versions.
681663
Nonce is an optional 10-digit string. If not provided, IMDS returns the current UTC timestamp in its place. Due to IMDS's caching mechanism, a previously cached nonce value may be returned.
682664

683665
***Response***
@@ -693,7 +675,6 @@ Nonce is an optional 10-digit string. If not provided, IMDS returns the current
693675

694676
The signature blob is a [pkcs7](https://aka.ms/pkcs7) signed version of document. It contains the certificate used for signing along with the VM details like vmId, sku, nonce, subscriptionId, timeStamp for creation and expiry of the document and the plan information about the image. The plan information is only populated for Azure Market place images. The certificate can be extracted from the response and used to validate that the response is valid and is coming from Azure.
695677

696-
697678
### Sample 2: Validating that the VM is running in Azure
698679

699680
Marketplace vendors want to ensure that their software is licensed to run only in Azure. If someone copies the VHD out to on-premise, then they should have the ability to detect that. By calling into Instance Metadata Service, Marketplace vendors can get signed data that guarantees response only from Azure.
@@ -751,7 +732,6 @@ vmId | [Unique identifier](https://azure.microsoft.com/blog/accessing-and-using
751732
subscriptionId | Azure subscription for the Virtual Machine, introduced in `2019-04-30`
752733
sku | Specific SKU for the VM image, introduced in `2019-11-01`
753734

754-
755735
#### Sample 3: Verifying the signature
756736

757737
Once you get the signature above, you can verify that the signature is from Microsoft. Also you can verify the intermediate certificate and the certificate chain. Lastly, you can verify the subscription ID is correct.
@@ -788,15 +768,20 @@ In cases where the intermediate certificate cannot be downloaded due to network
788768
>The intermediate certificate for Azure China 21Vianet will be from DigiCert Global Root CA instead of Baltimore.
789769
Also if you had pinned the intermediate certificates for Azure China as part of root chain authority change, the intermediate certificates will have to be updated.
790770

791-
792771
## Managed Identity via Metadata Service
793772
User can enable the managed identity on a VM, and then leverage Instance Metadata Service to pass the token for accessing Azure services. Applications running on a VM now can request a token from the Azure Instance Metadata service endpoint, and then use the token to authenticate to cloud services, including key vault.
794773
For detailed steps to enable this feature, see [Acquire an access token](../../active-directory/managed-identities-azure-resources/how-to-use-vm-token.md).
795774

796-
797775
## Scheduled Events via Metadata Service
798776
You can obtain the status of the scheduled events via metadata service, then user can specify a set of action to execute upon these events. See [Scheduled Events](scheduled-events.md) for details.
799777

778+
## Regional Availability
779+
780+
The service is **generally available** in all Azure regions. This includes:
781+
1. [All Generally Available Global Azure Regions](https://azure.microsoft.com/regions/)
782+
2. [Azure Government](https://azure.microsoft.com/overview/clouds/government/)
783+
3. [Azure China 21Vianet](https://www.azure.cn/)
784+
4. [Azure Germany](https://azure.microsoft.com/overview/clouds/germany/)
800785

801786
## Sample Code in Different Languages
802787

@@ -810,14 +795,11 @@ Python | https://github.com/Microsoft/azureimds/blob/master/IMDSSample.py
810795
C++ | https://github.com/Microsoft/azureimds/blob/master/IMDSSample-windows.cpp
811796
C# | https://github.com/Microsoft/azureimds/blob/master/IMDSSample.cs
812797
JavaScript | https://github.com/Microsoft/azureimds/blob/master/IMDSSample.js
813-
PowerShell | https://github.com/Microsoft/azureimds/blob/master/IMDSSample.ps1
814798
Bash | https://github.com/Microsoft/azureimds/blob/master/IMDSSample.sh
815799
Perl | https://github.com/Microsoft/azureimds/blob/master/IMDSSample.pl
816800
Java | https://github.com/Microsoft/azureimds/blob/master/imdssample.java
817-
Visual Basic | https://github.com/Microsoft/azureimds/blob/master/IMDSSample.vb
818801
Puppet | https://github.com/keirans/azuremetadata
819802

820-
821803
## Error and Debugging
822804

823805
If there is a data element not found or a malformed request, the Instance Metadata Service returns standard HTTP errors. For example:
@@ -832,7 +814,6 @@ HTTP Status Code | Reason
832814
429 Too Many Requests | The API currently supports a maximum of 5 queries per second
833815
500 Service Error | Retry after some time
834816

835-
836817
### Known issues and FAQ
837818

838819
1. I am getting the error `400 Bad Request, Required metadata header not specified`. What does this mean?
@@ -856,15 +837,15 @@ HTTP Status Code | Reason
856837
10. I updated my tags in virtual machine scale set but they don't appear in the instances unlike VMs?
857838
* Currently for ScaleSets tags only show to the VM on a reboot/reimage/or a disk change to the instance.
858839

859-
860840
## Support and Feedback
861841

862842
Send your feedback and comments on https://feedback.azure.com.
863843
To get support for the service, create a support issue in Azure portal for the VM where you are not able to get metadata response after long retries.
864844

865845
![Instance Metadata Support](./media/instance-metadata-service/InstanceMetadata-support.png)
866846

867-
868847
## Next Steps
869848

870-
Learn more about [Acquire an access token for the VM](../../active-directory/managed-identities-azure-resources/how-to-use-vm-token.md).
849+
Learn more about:
850+
1. [Acquire an access token for the VM](../../active-directory/managed-identities-azure-resources/how-to-use-vm-token.md).
851+
2. [Scheduled Events](scheduled-events.md)

0 commit comments

Comments
 (0)