The metadata of an Elastic Compute Service (ECS) instance is the information that is obtained from the instance, such as the instance attributes, by using the metadata service. The metadata service allows you to obtain information from ECS instances without the need to log on to the ECS console or call API operations. The metadata service also allows you to configure or manage ECS instances that are in the Running state or applications that are hosted on ECS instances in a more convenient and secure manner. For example, you can obtain the temporary access credentials of instance Resource Access Management (RAM) roles by using instance metadata in the applications that are hosted on ECS instances, and then use the credentials to securely access relevant resources, such as files that are downloaded from Object Storage Service (OSS).
Limits
ECS instances that are deployed only in virtual private clouds (VPCs) support instance metadata.
To obtain the metadata of an ECS instance, you must access the metadata server from the instance and make sure that the instance is in the Running state.
If you frequently access the metadata server from a single ECS instance, your access requests may be throttled. If you want to frequently access the metadata of a single ECS instance, we recommend that you cache the instance metadata that you obtained to prevent the preceding issue. For example, after you obtain temporary RAM security credentials, we recommend that you cache the credentials and re-obtain the credentials when the credentials are about to expire.
Obtain the metadata of an ECS instance
If your ECS instance or instance metadata includes sensitive data, we recommend that you use appropriate methods to protect the data, such as access control or data encryption.
Differences between the modes in which you can obtain instance metadata
(Recommended) Obtain instance metadata in security hardening mode
Linux instance
# Obtain metadata server access credentials and specify a validity period for the credentials. Do not include the X-Forwarded-For header in the access request. TOKEN=`curl -X PUT "http://100.100.100.200/latest/api/token" -H "X-aliyun-ecs-metadata-token-ttl-seconds:<Validity period of the metadata server access credentials>"` # Obtain the instance metadata. curl -H "X-aliyun-ecs-metadata-token: $TOKEN" http://100.100.100.200/latest/meta-data/<metadata>
Windows instance
# Obtain metadata server access credentials and specify a validity period for the credentials. Do not include the X-Forwarded-For header in the access request. $token=Invoke-RestMethod -Headers @{"X-aliyun-ecs-metadata-token-ttl-seconds" = "<Validity period of the metadata server access credentials>"} -Method PUT -Uri http://100.100.100.200/latest/api/token # Obtain the instance metadata. Invoke-RestMethod -Headers @{"X-aliyun-ecs-metadata-token" = $token} -Method GET -Uri http://100.100.100.200/latest/meta-data/<metadata>
<Validity period of the metadata server access credentials>
: Specify a validity period for the metadata server access credentials to increase data security. Valid values: 1 to 21600. Unit: seconds.You can repeatedly run the preceding command to obtain the metadata items of the instance within the validity period of the metadata server access credentials. After the validity period ends, re-obtain the metadata server access credentials. If you do not re-obtain the metadata server access credentials, you cannot obtain the metadata of the instance.
Metadata server access credentials are tied to ECS instances. If you copy the metadata server access credentials of an ECS instance to access another ECS instance, your access is denied.
<metadata>
: Replace this parameter with the metadata item that you want to obtain. For information about instance metadata items, see the Instance metadata items section in this topic.
Obtain instance metadata in normal mode
Linux instance
curl http://100.100.100.200/latest/meta-data/<metadata>
Windows instance (PowerShell)
Invoke-RestMethod http://100.100.100.200/latest/meta-data/<metadata>
<metadata>
: Replace this parameter with the metadata item that you want to obtain. For information about instance metadata items, see the Instance metadata items section in this topic.
Examples
In the following examples, the VPC ID of an ECS instance is obtained.
Security hardening mode
In the following examples, <Validity period of the metadata server access credentials>
is set to 180 seconds.
Linux instance
TOKEN=`curl -X PUT "http://100.100.100.200/latest/api/token" -H "X-aliyun-ecs-metadata-token-ttl-seconds:180"` curl -H "X-aliyun-ecs-metadata-token: $TOKEN" http://100.100.100.200/latest/meta-data/vpc-id
Windows instance
$token = Invoke-RestMethod -Headers @{"X-aliyun-ecs-metadata-token-ttl-seconds" = "180"} -Method PUT –Uri http://100.100.100.200/latest/api/token Invoke-RestMethod -Headers @{"X-aliyun-ecs-metadata-token" = $token} -Method GET -Uri http://100.100.100.200/latest/meta-data/vpc-id
Normal mode
Linux instance
curl http://100.100.100.200/latest/meta-data/vpc-id
Windows instance
Invoke-RestMethod http://100.100.100.200/latest/meta-data/vpc-id
Metadata items
Metadata item | Description | Example |
dns-conf/nameservers | The Domain Name System (DNS) configurations of the instance. | 100.100.XX.XX |
hostname | The hostname of the instance. | iZbp13znx0m0me8cquu**** |
instance/instance-type | The instance type. | ecs.g6e.large |
instance/instance-name | The name of the instance. | iZbp1bfqfsvqzxhmnd5**** |
image-id | The ID of the image that is used to create the instance. | aliyun_3_x64_20G_alibase_20210425.vhd |
image/market-place/product-code | The product code of the Alibaba Cloud Marketplace image. | cmjj01**** |
image/market-place/charge-type | The billing method of the Alibaba Cloud Marketplace image. | PrePaid |
instance-id | The ID of the instance. | i-bp13znx0m0me8cquu**** |
mac | The media access control (MAC) address of the instance. If the instance has multiple network interfaces (NICs), only the MAC address of the eth0 NIC is displayed. | 00:16:3e:0f:XX:XX |
network-type | The network type of the instance. Only instances that are deployed in VPCs support this metadata item. | vpc |
network/interfaces/macs/[mac]/network-interface-id | The identifier of the NIC. Replace [mac] with the MAC address of the instance. | eni-bp1b2c0jvnj0g17b**** |
network/interfaces/macs/[mac]/netmask | The subnet mask of the NIC. | 255.255.XX.XX |
network/interfaces/macs/[mac]/vswitch-cidr-block | The IPv4 CIDR block of the vSwitch to which the NIC is connected. | 192.168.XX.XX/24 |
network/interfaces/macs/[mac]/vpc-cidr-block | The IPv4 CIDR block of the VPC to which the NIC belongs. | 192.168.XX.XX/16 |
network/interfaces/macs/[mac]/private-ipv4s | The private IPv4 addresses that are assigned to the NIC. | ["192.168.XX.XX"] |
network/interfaces/macs/[mac]/vswitch-id | The ID of the vSwitch in the VPC to which the security group of the NIC belongs. | vsw-bp1ygryo03m39xhsy**** |
network/interfaces/macs/[mac]/vpc-id | The ID of the VPC to which the security group of the NIC belongs. | vpc-bp1e0g399hkd7c8q3**** |
network/interfaces/macs/[mac]/primary-ip-address | The primary private IP address of the NIC. | 192.168.XX.XX |
network/interfaces/macs/[mac]/gateway | The IPv4 gateway address of the NIC. | 192.168.XX.XX |
instance/max-netbw-egress | The maximum outbound internal bandwidth of the instance. Unit: Kbit/s. | 1228800 |
network/interfaces/macs/[mac]/ipv4-prefixes | The private IPv4 prefix lists that are assigned to the NIC. | 192.168.XX.XX/28 |
network/interfaces/macs/[mac]/ipv6-prefixes | The private IPv6 prefix lists that are assigned to the NIC. | 2001:db8:1234:1a00:XXXX::/80 |
disks/[disk-id]/id | The ID of the disk. | d-bp131n0q38u3a4zi**** |
disks/[disk-id]/name | The name of the disk. | testDiskName |
private-ipv4 | The private IPv4 address of the primary NIC. | 192.168.XX.XX |
public-ipv4 | The public IPv4 address of the primary NIC. | 120.55.XX.XX |
eipv4 | This metadata item is used to obtain the following information:
| 120.55.XX.XX |
ntp-conf/ntp-servers | The address of the Network Time Protocol (NTP) server. | ntp1.aliyun.com |
owner-account-id | The ID of the Alibaba Cloud account to which the instance belongs. | 1609**** |
region-id | The region ID of the instance. | cn-hangzhou |
zone-id | The zone ID of the instance. | cn-hangzhou-i |
public-keys/[keypair-id]/openssh-key | The public key of the instance. This metadata item is available only if a public key was bound to the instance during instance creation. | ssh-rsa ****3NzaC1yc2EAAAADAQABAAABAQDLNbE7pS****@****.com |
serial-number | The serial number of the instance. | 4acd2b47-b328-4762-852f-998**** |
source-address | The address of the YUM or APT image repository. The package management software of a Linux instance can obtain updates from the image repository. | http://mirrors.cloud.aliyuncs.com |
kms-server | The Key Management Service (KMS) server that is used by the Windows instance to activate Windows. | kms.cloud.aliyuncs.com |
wsus-server/wu-server | The update server of the Windows instance. | http://update.cloud.aliyuncs.com |
wsus-server/wu-status-server | The server that monitors the update status of the Windows instance. | http://update.cloud.aliyuncs.com |
vpc-id | The ID of the VPC to which the instance belongs. | vpc-bp1e0g399hkd7c8q**** |
vpc-cidr-block | The CIDR block of the VPC to which the instance belongs. | 192.168.XX.XX/16 |
vswitch-cidr-block | The CIDR block of the vSwitch to which the instance is connected. | 192.168.XX.XX/24 |
vswitch-id | The ID of the vSwitch to which the instance is connected. | vsw-bp1ygryo03m39xhsy**** |
/ram/security-credentials/[role-name] | The RAM role of the instance. If a RAM role is attached to the instance, the value of | AliyunECSImageExportDefaultRole |
instance/spot/termination-time | The stop time and release time that are configured in the operating system of the preemptible instance. The time is in the yyyy-MM-ddThh:mm:ssZ format. The time is displayed in UTC. | 2020-04-07T17:03:00Z |
instance/virtualization-solution | The ECS virtualization solution. Virt 1.0 and Virt 2.0 are supported. | ECS Virt |
instance/virtualization-solution-version | The version of the ECS virtualization solution. | 2.0 |
FAQ
Q: What do I do if I cannot run a command to obtain the metadata of an ECS instance in security hardening mode?
A: Check whether the command that you use is correct. The following errors may exit in the command:
The validity period of the metadata server access credentials is not within the range of 1 second to 21,600 seconds.
curl -X PUT "http://100.100.100.200/latest/api/token" -H "X-aliyun-ecs-metadata-token-ttl-seconds: 21700"
The request includes the X-Forwarded-For header.
curl -X PUT "http://100.100.100.200/latest/api/token" -H "X-Forwarded-For: www.ba****.com"
The specified metadata server access credentials are invalid.
curl -H "X-aliyun-ecs-metadata-token: aaa" -v http://100.100.100.200/latest/meta-data/