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 instance attributes include the instance ID, virtual private cloud (VPC) information, and network interface controller (NIC) information. The metadata service allows you to access information inside 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 in the Running state or applications that are hosted on ECS instances in a more convenient and secure manner. For example, the applications that run on ECS instances can access instance metadata to obtain the Security Token Service (STS) tokens of the Resource Access Management (RAM) roles that are attached to the instances. Then, the applications can use the tokens to access resources, such as Object Storage Service (OSS) resources, Key Management Service (KMS) resources, and other ECS resources, without the need to hard-code the tokens.
Limits
Only ECS instances that reside in VPCs support instance metadata.
To access 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 access credentials, we recommend that you cache the credentials and re-obtain the credentials before the credentials expire.
Obtain instance metadata
You can access the metadata service to obtain instance metadata. Instance metadata includes instance IDs, VPC information, and NIC information.
Procedure
If your ECS instance or instance metadata includes sensitive data, we recommend that you use appropriate methods, such as access control or data encryption, to protect the data.
You can access the metadata server in normal mode or security hardening mode to obtain instance metadata. For information about the modes, see the Instance metadata access modes section of this topic.
Security hardening mode
Make sure that cloud-init 23.2.2 is installed on the ECS instance whose metadata you want to obtain. If the version of cloud-init installed on the ECS instance is not 23.2.2, upgrade cloud-init to version 23.2.2. For information about how to check and upgrade the version of cloud-init on an ECS instance, see Install cloud-init.
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>"` # Access 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 # Access 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 access the metadata items of the ECS 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 access 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 access. For information about instance metadata items, see the Instance metadata items section of this topic.
Normal mode
In normal mode, requests are authenticated based on IP addresses. If issues exist on your ECS instance, such as incorrect reverse proxy configurations or unpatched server-side request forgery (SSRF) vulnerabilities, the STS temporary access credentials of the RAM role that is attached to the instance may be leaked.
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 access. For information about instance metadata items, see the Instance metadata items section of 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-idWindows 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-idWindows instance
Invoke-RestMethod http://100.100.100.200/latest/meta-data/vpc-id
Instance metadata access modes
By default, you can access instance metadata in normal mode and security hardening mode. To increase security, you can configure an ECS instance to support only the security hardening mode.
Differences between the normal mode and the security hardening mode
Item | Normal mode | Security hardening mode |
Interaction pattern | Request-response. | Session-oriented. |
Authentication method | Use source IP addresses in the same VPC for authentication. | Use source IP addresses in the same VPC and the metadata server access credentials for authentication. Metadata server access credentials have the following characteristics:
|
Access method | You can use commands to access an endpoint without the need to use access credentials. | To increase the security of instance metadata, obtain metadata server access credentials for authentication and then access the endpoint. |
Security level | Low Requests are authenticated based on IP addresses. Attackers can forge the source IP addresses in requests to bypass IP address-based authentication and launch SSRF attacks. As a result, instance metadata may be leaked. | High Before you can access instance metadata, you must obtain valid metadata server access credentials for authentication and authorization. Metadata server access credentials are generated in ECS instances and are tied to the ECS instances. Metadata server access credentials have a validity period. Metadata server access credentials are difficult for attackers to guess or forge and help you defend against most SSRF attacks. |
Requirement on cloud-init versions | None | Make sure that cloud-init 23.2.2 is installed on ECS instances. Important
|
Configure the instance metadata access mode
New instance
Use the ECS console
When you create ECS instances in the ECS console, the Metadata Access Mode parameter is automatically set to Normal Mode and Security Hardening Mode.
Call an API operation
When you call the RunInstances or CreateInstance operation to create ECS instances, use the
HttpTokensparameter to specify an instance metadata access mode. Valid values of the HttpTokens parameter:optional: does not forcefully use the security hardening mode. You can access instance metadata in normal mode and security hardening mode.required: forcefully uses the security hardening mode. After you set this parameter to required, you cannot access instance metadata in normal mode.
Existing instance
Use the ECS console
On the instance list page, find the ECS instance that you want to manage. In the Actions column, choose
> Instance Settings > Modify Instance Metadata Access Information. 
Turn on Enable Access Channel for Instance Metadata and configure the Instance Metadata Access Mode parameter. Valid values of the Instance Metadata Access Mode parameter:
Normal Mode: You can access instance metadata in normal mode or security hardening mode.
Security Hardening Mode (recommended): You can access instance metadata only in security hardening mode.
Call an API operation
When you call the ModifyInstanceMetadataOptions operation to modify the metadata of an existing ECS instance, use the
HttpTokensparameter to specify an instance metadata access mode. Valid values of the HttpTokens parameter:optional: does not forcefully use the security hardening mode. You can access instance metadata in normal mode and security hardening mode.required: forcefully uses the security hardening mode. After you set this parameter to required, you cannot access instance metadata in normal mode.
Limit the metadata server access mode to security hardening mode for RAM users
You can use a permissions policy to allow all RAM users under your Alibaba Cloud account to access instance metadata only in security hardening mode when the RAM users call the RunInstances or CreateInstance operation to create ECS instances or the ModifyInstanceMetadataOptions operation to modify the metadata of existing ECS instances. The following sample code provides an example of the content of the policy:
{
"Version": "1",
"Statement": [
{
"Effect": "Deny",
"Action": [
"ecs:RunInstances",
"ecs:CreateInstance",
"ecs:ModifyInstanceMetadataOptions"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"ecs:SecurityHardeningMode": [
"false"
]
}
}
}
]
}For information about how to create a permissions policy, see the Create a custom policy on the JSON tab section of the "Create custom policies" topic.
Before you access the metadata of an ECS instance that supports only the security hardening mode, make sure that cloud-init 23.2.2 is installed on the instance. If the version of cloud-init on the ECS instance is not 23.2.2, the instance may be unable to start. For information about how to check and upgrade the version of cloud-init on an ECS instance, see Install cloud-init.
Instance 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 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 that is associated with the security group of the NIC. | 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 |