Elastic Compute Service (ECS) instance metadata includes attribute information, such as the instance ID, virtual private cloud (VPC), and network interface controller (NIC), which can be accessed from inside the instance by using the metadata service. You can access ECS instance metadata without logging on to the ECS console or call API operations, and use the metadata easily and securely to configure or manage running instances or applications hosted on the instances.
Instance metadata items
You can use the metadata service to obtain the metadata of an ECS instance, including the hostname, instance type, instance name, and image ID. Expand the following table to view instance metadata items.
Instance metadata access modes
You can access instance metadata in normal or security hardening mode. For more information, see Access instance metadata in different modes. The following table compares the two modes.
We recommend that you use the security hardening mode. To access metadata in this mode, make sure that the cloud-init version on the instance is 23.2.2 or later. For information about how to check and upgrade the cloud-init version, see Install cloud-init.
Comparison of access modes
Item | Normal mode | Security hardening mode |
Interaction method | Request-response | Session-oriented |
Authentication method | Authenticates requests based on source IP addresses in the same VPC. | Performs authentication based on source IP addresses in the same VPC and instance metadata access credentials. Instance metadata access credentials have the following characteristics:
|
Access method | Runs commands to access an endpoint without access credentials. | Obtains instance metadata access credentials for authentication to access an endpoint. |
Security level | Low In normal mode, requests are authenticated based on IP addresses. Attackers can forge the source IP addresses in requests to bypass the IP address-based authentication and launch Server-Side Request Forgery (SSRF) attacks. As a result, instance metadata may be leaked. | High To access instance metadata, valid metadata access credentials are required for authentication and authorization. These credentials are generated on and tied to ECS instances, and are valid for a limited period, making them difficult for attackers to guess or forge. This helps defend against most SSRF attacks. |
Access instance metadata in different modes
Security hardening mode
Linux instance
# Obtain metadata access credentials and specify their validity period. Do not include the X-Forwarded-For header in the request. TOKEN=`curl -X PUT "http://100.100.100.200/latest/api/token" -H "X-aliyun-ecs-metadata-token-ttl-seconds:<Validity period of metadata server access credentials>"` # Access instance metadata. curl -H "X-aliyun-ecs-metadata-token: $TOKEN" http://100.100.100.200/latest/meta-data/<metadata>Windows instance
# Obtain metadata access credentials and specify their validity period. Do not include the X-Forwarded-For header in the request. $token = Invoke-RestMethod -Headers @{"X-aliyun-ecs-metadata-token-ttl-seconds" = "<Validity period of metadata server access credentials>"} -Method PUT -Uri http://100.100.100.200/latest/api/token # Access instance metadata. Invoke-RestMethod -Headers @{"X-aliyun-ecs-metadata-token" = $token} -Method GET -Uri http://100.100.100.200/latest/meta-data/<metadata>Replace the following fields in the preceding code with actual values:
<Validity period of metadata server access credentials>: the validity period of the metadata access credentials. Valid values: 1 to 21600. Unit: seconds.Within the validity period, you can repeatedly run commands to access the instance metadata by using the metadata access credentials. After the credentials expire, you must obtain new credentials to access the metadata.
Metadata access credentials are tied to ECS instances. You cannot use the credential of one ECS instance to access the metadata of another ECS instance.
<metadata>: the metadata item you want to query. For more information, see Instance metadata items.
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>: the metadata item you want to query. For more information, see Instance metadata items.
If an ECS instance frequently accesses the metadata server to obtain metadata, access requests may be throttled. We recommend that you cache and refresh data, such as RAM credentials, before it expires.
Configure the security hardening mode as the exclusive metadata access mode for an instance
To enhance security, Alibaba Cloud allows you to configure the security hardening mode as the exclusive metadata access mode for an instance. Once this setting is configured, requests that use the normal mode are rejected. This helps defend against most SSRF-related risks. The following sections describe how to configure this setting in different scenarios.
If you use the credentials tool to obtain the temporary identity credentials of the RAM role attached to an ECS instance, switching to the security hardening mode may affect your business. To prevent this issue, upgrade the credentials tool. For information about the versions that support the security hardening mode, see Obtain temporary access credentials by using the credentials tool.
Configure the security hardening mode as the exclusive metadata access mode during instance creation
Use the ECS console
On the instance buy page, expand the Advanced Options section and set the Metadata Access Mode parameter to Security Hardening Mode.
You can select Security Hardening Mode only if the image that you use supports it.
If you cannot select Security Hardening Mode, create the instance, upgrade the cloud-init version to 23.2.2 or later, and then configure the security hardening mode as the exclusive metadata access mode for the instance.
Some latest Alibaba Cloud public images support the security hardening mode because they are pre-installed with cloud-init 23.2.2 or later. To check whether an image supports the mode, call the DescribeImages operation and view the ImdsSupport value for the image in the response. If the ImdsSupport value is v2, the image supports the security hardening mode.
Call an API operation
When you call the RunInstances or CreateInstance operation to create an ECS instance, set the HttpTokens parameter to required to enable Security Hardening Mode.
The instance can be started only if the image that you use supports the security hardening mode.
If the start fails, set the HttpTokens parameter to optional, upgrade the cloud-init version to 23.2.2 or later, and then configure the security hardening mode as the exclusive metadata access mode for the instance.
Some latest Alibaba Cloud public images support the security hardening mode because they are pre-installed with cloud-init version 23.2.2 or later. To check whether an image supports the mode, call the DescribeImages operation and view the ImdsSupport value for the image in the response. If the value of ImdsSupport is v2, the image supports the security hardening mode.
Configure the security hardening mode as the exclusive metadata access mode for an existing instance
If you no longer use the normal mode to access the metadata of an existing ECS instance, modify the application code of the instance and configure the security hardening mode as the exclusive metadata access mode. After this setting is configured, requests that use the normal mode are rejected.
Step 1: Modify application code to use the security hardening mode
Identify the instances whose application code you want to modify.
Method 1: Log on to the CloudMonitor console. On the page, search for ECS Metadata. Identify the ECS instances whose Monitoring Charts show that the number of successful accesses in normal mode(count) is greater than 0, which means that the applications on the instances use the normal mode. You must configure the security hardening mode for these instances. To ensure data accuracy, we recommend a time range of 14 days or longer.
Method 2: Use the
ACS-ECS-ImdsPacketAnalyzerplug-in provided by Cloud Assistant to identify the processes on an ECS instance that use the normal mode.The plug-in is available only for Linux operating systems because Cloud Assistant Agent is pre-installed on Linux instances during instance creation. However, operating system restrictions apply.
Deploying the ACS-ECS-ImdsPacketAnalyzer plug-in on an instance may affect the instance performance.
Supported following operating systems:
Alibaba Cloud Linux 3
Anolis OS 8
CentOS Stream 8 and 9
CentOS 8
Ubuntu 20 and 24
Debian 10, 11, and 12
Fedora 35 and later
AlmaLinux 8 and 9
Rocky Linux 8 and 9
Red Hat Enterprise Linux 8 and 9
For Red Hat, you must download and install the RPM package of Cloud Assistant Agent. For more information, see Install Cloud Assistant Agent.
SUSE 15.1, 15.2, 15.3, 15.4, 15.5, and 15.6
openSUSE 15.2, 15.3, 15.4, 15.5, and 15.6
Procedure:
Connect to an ECS instance. For more information, see Methods for connecting to an ECS instance.
Run the following command to check whether Cloud Assistant Agent is installed on the instance and provides the
ACS-ECS-ImdsPacketAnalyzerplug-in:sudo acs-plugin-manager --list
Run the following command to deploy the
imds_tracer_toolservice:sudo acs-plugin-manager --exec --plugin ACS-ECS-ImdsPacketAnalyzerThe following output shows that the service is deployed.
Run the following command to check the deployment status of the
imds_tracer_toolservice:sudo systemctl status imds_tracer_tool
Run the following command to display all applications that support the normal and security hardening modes:
cat /var/log/imds/imds-trace.* | grep WARNING
Make sure that the cloud-init version on the identified instances is 23.2.2 or later. If the cloud-init version is earlier than 23.2.2, upgrade to version 23.2.2 or later. For information about how to check and upgrade the version, see Install cloud-init.
Modify your application code to obtain metadata access credentials and then include the credentials in the request header to access instance metadata. For more information, see Access instance metadata in security hardening mode.
Make sure that your application code no longer uses the normal mode to access instance metadata.
On ECS Metadata page in the CloudMonitor console , check whether the Monitoring Charts of the identified instances show the number of successful accesses in normal mode(count) as No data. If yes, you can proceed to Step 2. If not, requests to access instance metadata in normal mode may be rejected after you configure the security hardening mode as the exclusive metadata access mode for the instances. To ensure data accuracy, we recommend a time range of 14 days or longer.
Step 2: Configure the security hardening mode as the exclusive metadata access mode for the instance
Use the ECS console
Go to ECS console - Instance.
In the top navigation bar, select the region and resource group of the resource that you want to manage.
Find the instance that you want to manage, click the ID of the instance to go to the instance details page, and then click All Actions in the upper-right corner. In the pane that appears, search for and click Modify Instance Metadata Access Information.
Turn on Enable Access Channel for Instance Metadata and set Instance Metadata Access Mode to Security Hardening Mode.
Call an API operation
You can call the DescribeInstances operation and view the HttpTokens value in the response to check whether the security hardening mode is forcefully used to access instance metadata. Applications on ECS instances whose HttpTokens value is optional still use the normal mode. Identify these ECS instances in the DescribeInstances response.
Call the ModifyInstanceMetadataOptions operation with HttpTokens set to required for each instance to change the metadata access mode to the security hardening mode.
After you configure the security hardening mode as the only metadata access mode for ECS instances, requests to access metadata in normal mode are rejected. To avoid business interruptions due to request failure, configure alerts in the CloudMonitor console to be notified when requests that use the normal mode are rejected. If requests that use the normal mode are rejected after you configure the security hardening mode as the exclusive metadata access mode, configure the instance to support the normal and security hardening modes, make sure that the instance metadata is no longer accessed in normal mode, and then reconfigure the security hardening mode as the exclusive metadata access mode for the instance.