Access information, such as instance attributes, inside an ECS instance by using metadata - Elastic Compute Service

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

Important

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

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: Metadata server access credentials are short-lived and remain valid for up to 6 hours. When the validity period ends, the credentials expire and must be re-obtained. 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 server access credentials do not support proxy access. If a request includes the X-Forwarded-For header, the metadata server does not issue access credentials.
Access method	Use commands to access the endpoint without access credentials.	To increase the security of instance metadata, obtain metadata server access credentials for authentication and then access the endpoint.
Requirement on cloud-init versions	None.	Make sure that cloud-init 23.2.2 is installed on ECS instances. Note Specific latest public images support cloud-init 23.2.2. When you call the RunInstances or CreateInstance operation to create ECS instances, you can set `ImageId` to the ID of such a public image. Instances created from public images that support cloud-init 23.2.2 support accessing instance metadata in security hardening mode. For information about public images that support cloud-init 23.2.2, see Release notes. If the cloud-init version on an existing ECS instance is not 23.2.2, you can upgrade the cloud-init version to 23.2.2 to support the security hardening mode. For information about how to check and upgrade the cloud-init version on an ECS instance, see Install cloud-init.

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.

Important

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: The system-assigned public IPv4 address of the instance The elastic IPv4 address that is associated with the primary NIC	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 `role-name` consists of the name of the RAM role and the STS token that is associated with the RAM role. If a RAM role is not attached to the instance, no value is returned for this metadata item.	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

What do I do if I cannot run a command to access the metadata of an ECS instance in security hardening mode?

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/