Acceso a los metadatos de instancia de una instancia de EC2 - Amazon Elastic Compute Cloud
Consideraciones sobre el acceso a los metadatos de instanciaAcceso a los metadatos de la instancia desde una instancia de EC2Opciones de metadatos de instancia de consultaRespuestas y mensajes de errorLimitación de consultas

Acceso a los metadatos de instancia de una instancia de EC2

Puede acceder a los metadatos de la instancia de EC2 desde la propia instancia o desde la consola de EC2, la API, los SDK o la AWS CLI. Para obtener la configuración de metadatos de la instancia actual de una instancia desde la consola o la línea de comandos, consulte Opciones de metadatos de instancia de consulta para instancias existentes.

También puede modificar los datos de usuario de las instancias con un volumen raíz de EBS. La instancia debe estar detenida. Para obtener instrucciones sobre la consola, consulte Actualización de los datos de usuario de la instancia. Para ver un ejemplo de Linux en el que se usa la AWS CLI, consulte modify-instance-attribute. Para ver un ejemplo de Windows en el que se utiliza Tools for Windows PowerShell, consulte Datos de usuario y las Tools for Windows PowerShell.

nota

No se le cobrará por las solicitudes HTTP utilizadas para recuperar metadatos de instancia y datos de usuario.

Consideraciones sobre el acceso a los metadatos de instancia

Para evitar problemas con la recuperación de metadatos de instancia, tenga en cuenta la siguiente información.

Formato de comando

El formato de comando es diferente en función de si se usa la versión 1 del servicio de metadatos de instancias (IMDSv1) o la versión 2 del servicio de metadatos de instancias (IMDSv2). De forma predeterminada, puede usar ambos ambas versiones del servicio de metadatos de instancias. Para exigir el uso de IMDSv2, consulte Uso del servicio de metadatos de instancias para acceder a metadatos de instancia.

(IMDSv2) Si se requiere IMDSv2, IMDSv1 no funciona.

Para comprobar si IMDSv2 es obligatorio, seleccione la instancia para ver los detalles. El valor de IMDSv2 es obligatorio (se debe usar IMDSv2) u Opcional (se puede usar IMDSv2 o IMDSv1).

(IMDSv2) Se usa para recuperar el token /latest/api/token

La emisión de solicitudes PUT a cualquier ruta específica de la versión, como, por ejemplo, /2021-03-23/api/token, da lugar a que el servicio de metadatos devuelva errores 403 Forbidden (403 Prohibido). Este es el comportamiento deseado.

Compatibilidad con IPv6

Para recuperar metadatos de instancia que utilizan la dirección IPv6, asegúrese de habilitar y utilizar [fd00:ec2::254] en lugar de la dirección IPv4. La instancia debe ser una instancia basada en Nitro en una subred que admita IPv6.

(Windows) Creación de las AMI personalizadas con Sysprep.

Para asegurarse de que el IMDS funcione cuando inicie una instancia desde una AMI de Windows personalizada, la AMI debe ser una imagen estandarizada creada con Windows Sysprep. De lo contrario, IMDS no funcionará. Para obtener más información, consulte Creación de una AMI de Amazon EC2 con Windows Sysprep.

En un entorno de contenedores, se debe establecer el límite de saltos en 2.

Los AWS SDK utilizan llamadas a IMDSv2 de forma predeterminada. Si la IMDSv2 llamada no recibe respuesta, el SDK reintenta la llamada y, si aún no tiene éxito, utiliza IMDSv1. Esto puede generar un retraso, especialmente en un entorno de contenedor. En un entorno de contenedor, si el límite de saltos es 1, no devuelve la IMDSv2 respuesta porque ir al contenedor se considera un salto de red adicional. Para evitar el proceso de retroceso IMDSv1 y el retraso resultante, en un entorno de contenedor recomendamos que establezca el límite de saltos en 2. Para obtener más información, consulte Configuración de las opciones del servicio de metadatos de instancias.

Versión de metadatos

Para no tener que actualizar el código cada vez que Amazon EC2 publique una nueva compilación de metadatos de instancia, se recomienda utilizar latest en la ruta, no el número de versión.

Límite de paquetes por segundo (PPS)

Hay un límite de 1024 paquetes por segundo (PPS) para los servicios que utilizan direcciones locales de enlace. Este límite incluye la suma de las consultas de DNS de Route 53 Resolver, las solicitudes del servicio de metadatos de instancias (IMDS), las solicitudes del protocolo de tiempo de red (NTP) del servicio temporal de Amazon y las solicitudes del Servicio de licencias de Windows (para instancias basadas en Microsoft Windows).

Consideraciones adicionales para el acceso a datos de usuario

  • Los datos de usuario se tratan como datos opacos: lo que especifica es lo que obtiene en la recuperación. La instancia debe interpretar los datos de usuario y actuar sobre ellos.

  • Los datos de usuario deben estar codificados con base64. Según la herramienta o el SDK que utilice, es posible que se realice automáticamente la codificación en base64. Por ejemplo:

    • La consola de Amazon EC2 puede realizar la codificación con base64 por usted, o bien puede aceptar la entrada codificada con base64.

    • La AWS CLI versión 2 realiza la codificación en base64 de los parámetros binarios de forma predeterminada. La AWS CLI versión 1 realiza la codificación en base64 del parámetro --user-data por usted.

    • AWS SDK for Python (Boto3) realiza la codificación en base64 del parámetro UserData por usted.

  • Los datos de usuario están limitados a 16 KB, sin formato, antes de cifrarlo en base64. El tamaño de una cadena de longitud n tras el cifrado en base64 es ceil(n/3)*4.

  • Los datos de usuario deben descodificarse en base64 al recuperarlos. Los datos se descodifican automáticamente si los recupera con los metadatos de instancia o la consola.

  • Si detiene una instancia, modifica sus datos de usuario y la inicia de nuevo, los datos de usuario actualizados no se ejecutan automáticamente al iniciar la instancia. Con instancias de Windows, puede configurar los ajustes para que los scripts de datos de usuario actualizados se ejecuten una vez al iniciar la instancia, o bien cada vez que esta se inicie o se reinicie.

  • Los datos de usuario son un atributo de la instancia. Si crea una AMI a partir de una instancia, los datos de usuario de la instancia no se incluyen en la AMI.

Acceso a los metadatos de la instancia desde una instancia de EC2

Puesto que los metadatos de la instancia se encuentran disponibles en la instancia en ejecución, no se necesita utilizar la consola de Amazon EC2 ni la AWS CLI. Esto puede resultar de utilidad al escribir scripts para ejecutarlos desde la instancia. Por ejemplo, puede obtener acceso a la dirección IP local de la instancia desde los metadatos de la instancia para administrar una conexión a una aplicación externa.

Todos los datos siguientes se consideran metadatos de instancia, pero se accede a ellos de diferentes maneras. Seleccione la pestaña que representa el tipo de metadatos de la instancia a los que desea acceder para ver más información.

Metadata

Las propiedades de los metadatos de instancia se dividen en categorías. Para obtener una descripción de cada categoría de metadatos de instancia, consulte Categorías de metadatos de instancia.

Para acceder a las propiedades de metadatos de instancia desde una instancia en ejecución, obtenga los datos de las siguientes URI IPv4 o IPv6. Estas direcciones IP son direcciones de enlace local y solo son válidas desde la instancia. Para obtener más información, consulte Direcciones de enlace local.

IPv4

http://169.254.169.254/latest/meta-data/

IPv6

http://[fd00:ec2::254]/latest/meta-data/
Dynamic data

Para recuperar datos dinámicos de una instancia en ejecución, utilice los siguientes URI.

IPv4

http://169.254.169.254/latest/dynamic/

IPv6

http://[fd00:ec2::254]/latest/dynamic/
Ejemplos: acceso con cURL

Los ejemplos siguientes usan cURL para recuperar categorías de identidad de instancia de alto nivel.

IMDSv2

[ec2-user ~]$ TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \
&& curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/dynamic/instance-identity/
rsa2048
pkcs7
document
signature
dsa2048

IMDSv1

[ec2-user ~]$ curl http://169.254.169.254/latest/dynamic/instance-identity/
rsa2048
pkcs7
document
signature
dsa2048
Ejemplos: acceso con PowerShell

En los ejemplos siguientes se usa PowerShell para recuperar categorías de identidad de instancia de alto nivel.

IMDSv2

PS C:\> [string]$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri http://169.254.169.254/latest/api/token
PS C:\> Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/dynamic/instance-identity/
document
rsa2048
pkcs7
signature

IMDSv1

PS C:\> Invoke-RestMethod -uri http://169.254.169.254/latest/dynamic/instance-identity/
document
rsa2048
pkcs7
signature

Para obtener más información sobre datos dinámicos y ejemplos de cómo recuperarlos, consulte Documentos de identidad de la instancia para las instancias de Amazon EC2.

User data

Para recuperar datos de usuario de una instancia, utilice los siguientes URI. Para recuperar los datos de usuario mediante la dirección IPv6, debe habilitarla y la instancia debe ser una instancia basada en Nitro en una subred que admita IPv6.

IPv4

http://169.254.169.254/latest/user-data

IPv6

http://[fd00:ec2::254]/latest/user-data

Las solicitudes de datos de usuario devuelven los datos tal cual (tipo de contenido application/octet-stream). Si la instancia no tiene ningún dato de usuario, la solicitud devuelve 404 - Not Found.

Ejemplos: acceso con cURL para recuperar texto separado por comas

Los ejemplos siguientes usan cURL para recuperar datos de usuario especificados como texto separado por comas.

IMDSv2

TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \
&& curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/user-data
1234,john,reboot,true | 4512,richard, | 173,,,

IMDSv1

curl http://169.254.169.254/latest/user-data
1234,john,reboot,true | 4512,richard, | 173,,,
Ejemplos: acceso con PowerShell para recuperar texto separado por comas

En los ejemplos siguientes se usa PowerShell para recuperar datos de usuario que se especificaron como texto separado por comas.

IMDSv2

[string]$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri http://169.254.169.254/latest/api/token
Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/user-data
1234,john,reboot,true | 4512,richard, | 173,,,

IMDSv1

Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} `
-Method PUT -Uri http://169.254.169.254/latest/api/token} -Method GET -uri http://169.254.169.254/latest/user-data
1234,john,reboot,true | 4512,richard, | 173,,,
Ejemplos: acceso con cURL para recuperar un script

Los ejemplos siguientes usan cURL para recuperar datos de usuario que se especificaron como script.

IMDSv2

TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \
&& curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/user-data
#!/bin/bash
yum update -y
service httpd start
chkconfig httpd on

IMDSv1

curl http://169.254.169.254/latest/user-data
#!/bin/bash
yum update -y
service httpd start
chkconfig httpd on
Ejemplos: acceso con PowerShell para recuperar un script

En los ejemplos siguientes se usa PowerShell para recuperar datos de usuario que se especificaron como script.

IMDSv2

[string]$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri http://169.254.169.254/latest/api/token
Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/user-data
<powershell>
$file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
New-Item $file -ItemType file
</powershell>
<persist>true</persist>

IMDSv1

Invoke-RestMethod -uri http://169.254.169.254/latest/user-data
<powershell>
$file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
New-Item $file -ItemType file
</powershell>
<persist>true</persist>

Opciones de metadatos de instancia de consulta para instancias existentes

Puede consultar las opciones de metadatos de las instancias existentes mediante uno de los siguientes métodos.

Console
Consulta de las opciones de metadatos de una instancia existente mediante la consola

  1. Abra la consola de Amazon EC2 en https://console.aws.amazon.com/ec2/.

  2. En el panel de navegación, seleccione Instances (Instancia[s]).

  3. Seleccione la instancia.

  4. Elija Acciones, Configuración de la instancia y Modificar opciones de metadatos de instancia.

  5. Revise las opciones de metadatos de la instancia actuales en el cuadro de diálogo Modificar las opciones de metadatos de la instancia.

AWS CLI
Para consultar las opciones de metadatos de una instancia existente mediante el AWS CLI

Utilice el comando de la CLI describe-instances.

aws ec2 describe-instances \
    --instance-id i-1234567898abcdef0 \
    --query 'Reservations[].Instances[].MetadataOptions'
PowerShell
Para consultar las opciones de metadatos de una instancia existente mediante las herramientas para PowerShell

Utilice el cmdlet Get-EC2Instance.

(Get-EC2Instance `
    -InstanceId i-1234567898abcdef0).Instances.MetadataOptions

Respuestas y mensajes de error

Todos los metadatos de instancia se devuelven como texto (tipo de contenido HTTP text/plain).

La solicitud de un recurso de metadato concreto devuelve el valor correspondiente, o bien un código de error HTTP 404 - Not Found si no se encuentra disponible el recurso.

La solicitud de un recurso de metadato general (el URI acaba en /) devuelve una lista de recursos disponibles, o bien un código de error HTTP 404 - Not Found si no existe dicho recurso. Los elementos de la lista aparecen en líneas separadas que acaban con saltos de línea (ASCII 10).

Para las solicitudes realizadas con Servicio de metadatos de instancia versión 2, pueden aparecer los siguientes códigos de error HTTP:

  • 400 - Missing or Invalid Parameters – la solicitud PUT no es válida.

  • 401 - Unauthorized – la solicitud GET usa un token no válido. La acción recomendada es generar un token nuevo.

  • 403 - Forbidden: la solicitud no está permitida o IMDS está desactivado.

  • 503: la solicitud no se ha podido completar. Intente realizar de nuevo la solicitud .

Limitación de consultas

Limitamos las consultas a IMDS por cada instancia y aplicamos límites en el número de conexiones simultáneas desde una instancia a IMDS.

Si utiliza IMDS para recuperar credenciales de seguridad de AWS, evite consultar credenciales en cada transacción o mientras se ejecuta una gran cantidad de procesos o subprocesos, ya que puede producirse una limitación controlada en las operaciones. En lugar de ello, se recomienda guardar en caché las credenciales hasta que comience a aproximarse su caducidad. Para obtener más información sobre el rol de IAM y las credenciales de seguridad asociadas al rol, consulte Recuperar credenciales de seguridad de los metadatos de la instancia.

Si experimenta limitaciones controladas al acceder a IMDS, vuelva a realizar la consulta con una estrategia de retroceso exponencial.