All Products
Search
Document Center

Elastic Compute Service:Obtain information about an ECS instance, such as instance attributes, by using instance metadata

Last Updated:Jan 25, 2024

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

    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.

Differences between the modes in which you can obtain instance metadata

By default, you can obtain instance metadata in normal mode or security hardening mode. The following table describes the differences between the normal mode and the security hardening mode.

Item

Normal mode

Security hardening mode

Interaction pattern

Request-response.

Session.

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.

Obtain metadata server access credentials for authentication, and then run commands to access the endpoint.

(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:

  • The auto-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 Security Token Service (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

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/