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 security credentials, we recommend that you cache the credentials and re-obtain the credentials when the credentials are about to expire.
Access instance metadata
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.
Instance metadata access modes
You can access instance metadata in normal mode or security hardening mode.
Differences between the normal mode and the security hardening mode
Access instance metadata
(Recommended) Access 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>"` # 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 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 query. For information about instance metadata items, see the Instance metadata items section of this topic.
Access 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 query. 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 accessed.
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
Configure the instance metadata access mode
By default, you can access instance metadata in normal and security hardening modes. To increase security, you can configure an ECS instance to support only security hardening mode.
New instance
When you call the RunInstances or CreateInstance operation to create an ECS instance, set the HttpTokens
parameter to specify an instance metadata access mode. Valid values of the parameter:
optional
: does not forcefully use the security hardening mode. You can access the instance metadata in both normal and security hardening modes.required
: forcefully uses the security hardening mode. After you set this parameter to required, you cannot access instance metadata in normal mode.
Existing instance
When you call the ModifyInstanceMetadataOptions operation to modify the metadata of an existing ECS instance, set the HttpTokens
parameter to specify an instance metadata access mode. Valid values of the parameter:
optional
: does not forcefully use the security hardening mode. You can access the instance metadata in both normal and security hardening modes.required
: forcefully uses the security hardening mode. After you set this parameter to required, you cannot access instance metadata in normal mode.
Configure a permissions policy to limit the instance metadata access mode to security hardening
You can use a permissions policy to limit all RAM users under your Alibaba Cloud account to accessing instance metadata only in security hardening mode when the users call the RunInstances or CreateInstance operation to create ECS instances or the ModifyInstanceMetadataOptions operation to modify the metadata of ECS instances. The following sample code shows 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 cloud-init version 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 cloud-init version 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 |