Acessar metadados de instância para uma instância do EC2 - Amazon Elastic Compute Cloud
Considerações sobre o acesso aos metadados da instânciaAcessar os metadados de instância em uma instância do EC2Consultar as opções de metadados da instânciaRespostas e mensagens de erroLimitação de consulta

Acessar metadados de instância para uma instância do EC2

Você pode acessar os metadados das instâncias do EC2 na própria instância ou no console do EC2, na API, nos SDKs ou na AWS CLI. Para obter as configurações atuais de metadados de instância para uma instância no console ou na linha de comandos, consulte Consultar as opções de metadados da instância para as instâncias existentes.

Você pode modificar os dados do usuário das instâncias com um volume raiz do EBS. A instância deve estar no estado interrompido. Para obter instruções para o console, consulte Atualizar os dados do usuário da instância. Para obter um exemplo do Linux que usa a AWS CLI, consulte modify-instance-attribute. Para obter um exemplo do Windows que usa o Tools for Windows PowerShell, consulte Dados do usuário e Tools for Windows PowerShell.

nota

Você não será cobrado pelas solicitações HTTP usadas para recuperar os metadados da instância e os dados do usuário.

Considerações sobre o acesso aos metadados da instância

Para evitar problemas com a recuperação de metadados de instância, considere os aspectos a seguir.

Formato do comando

O formato do comando é diferente, dependendo se você usa o serviço de metadados de instância versão 1 (IMDSv1) ou o serviço de metadados de instância versão 2 IMDSv2. Por padrão, você pode usar as duas versões do serviço de metadados de instância. Para exigir o uso do IMDSv2, consulte Use o serviço de metadados de instância para acessar metadados de instância.

(IMDSv2) Se o IMDSv2 for necessário, o IMDSv1 não funcionará

Para verificar se o IMDSv2 é necessário, selecione a instância para visualizar seus detalhes. O valor para IMDSv2 é Obrigatório (você deve usar IMDSv2) ou Opcional (é possível usar IMDSv2 ou IMDSv1).

(IMDSv2) Use /latest/api/token para recuperar o token

Emitir solicitações PUT para qualquer caminho específico da versão, por exemplo /2021-03-23/api/token, faz com que o serviço de metadados retorne erros 403 Forbidden. Este é o comportamento pretendido.

Suporte a IPv6

Para recuperar metadados da instância usando um endereço IPv6, certifique-se de habilitar e usar [fd00:ec2::254] em vez do endereço IPv4. A instância deve ser uma instância baseada em Nitro executada em uma sub-rede compatível com IPv6.

(Windows) Criar AMIs personalizadas usando o Sysprep do Windows.

Para garantir que o IMDS funcione quando você iniciar uma instância usando uma AMI personalizada do Windows, a AMI deverá ser uma imagem padronizada criada com a ferramenta Sysprep do Windows. Caso contrário, o IMDS não funcionará. Para obter mais informações, consulte Criar uma AMI do Amazon EC2 usando o Sysprep do Windows.

Em um ambiente de contêiner, defina o limite de saltos como 2.

Os SDKs da AWS usam chamadas IMDSv2 por padrão. Se a chamada IMDSv2 não receber resposta, o SDK tenta novamente o atendimento e, se houver falha, usa IMDSv1. Isso pode resultar em um atraso, especialmente em um ambiente de contêiner. Em um ambiente de contêiner, se o limite de salto for 1, a resposta de IMDSv2 não retorna porque ir ao contêiner é considerado um salto de rede adicional. Para evitar o processo de recuar para IMDSv1 e o atraso resultante, em um ambiente de contêiner recomendamos que você defina o limite de salto como 2. Para ter mais informações, consulte Configurar as opções de serviço de metadados de instância.

Versão de metadados

Para evitar ter que atualizar seu código sempre que o Amazon EC2 lançar uma nova compilação de metadados de instância, recomendamos que você use latest no caminho em vez do número da versão.

Limite de pacotes por segundo (PPS)

Há um limite de 1.024 pacotes por segundo (PPS) para serviços que usam endereços locais do link. Esse limite inclui o agregado de consultas ao DNS do Route 53 Resolver, solicitações do Serviço de metadados de instância (IMDS), solicitações do Amazon Time Service Network Time Protocol (NTP) e solicitações do Windows Licensing Service (para instâncias baseadas no Microsoft Windows).

Considerações adicionais sobre acesso aos dados do usuário

  • Os dados do usuário são tratados como dados opacos: o que você especifica é o que receberá de volta na recuperação. Cabe à instância interpretar e agir com base nos dados do usuário.

  • Os dados do usuário devem ser codificados por base64. Dependendo da ferramenta ou do SDK que você está usando, a codificação base64 pode ser executada para você. Por exemplo:

    • O console do Amazon EC2 pode executar a codificação base64 para você ou aceitar a entrada codificada por base64.

    • A AWS CLI versão 2 executa a codificação base64 de parâmetros binários para você por padrão. A AWS CLI versão 1 executa a codificação base64 do --user-data parâmetro para você.

    • O AWS SDK for Python (Boto3) executa a codificação base64 do parâmetro UserData para você.

  • Os dados do usuário são limitados a 16 KB, na forma bruta, antes de serem codificados em base64. O tamanho de uma string de comprimento n depois que a codificação em base64 for ceil (n/3)*4.

  • Os dados do usuário devem ser decodificados em base64 quando você os recupera. Se você recuperar os dados usando o console ou os metadados da instância, eles serão decodificados automaticamente para você.

  • Se você interromper uma instância, modificar os dados do usuário e iniciar a instância, os dados do usuário atualizados não serão executados automaticamente quando você iniciar a instância. Com as instâncias do Windows, é possível definir configurações para que os scripts de dados do usuário atualizados sejam executados uma vez quando você inicia a instância ou sempre que você reinicia ou inicia a instância.

  • Os dados do usuário são um atributo da instância. Se você criar uma AMI a partir de uma instância, os dados do usuário da instância não serão incluídos na AMI.

Acessar os metadados de instância em uma instância do EC2

Como os metadados da instância estão disponíveis na sua instância em execução, você não precisa usar o console do Amazon EC2 nem a AWS CLI. Isso pode ser útil quando você for elaborar scripts a serem executados a partir de sua instância. Por exemplo, é possível acessar o endereço IP local de sua instância a partir dos metadados da instância para gerenciar uma conexão com uma aplicação externa.

Todos os itens a seguir são considerados metadados de instância, mas são acessados de maneiras diferentes. Selecione a guia que representa o tipo de metadados de instância que você quer acessar para ver mais informações.

Metadata

As propriedades de metadados de instância são divididas em categorias. Para obter uma descrição de cada categoria de metadados de instância, consulte Categorias de metadados da instância

Para acessar as propriedades de metadados da instância em uma instância em execução, obtenha os dados dos URIs IPv4 ou IPv6 a seguir. Esses endereços IP são endereços locais de link e são válidos apenas a partir da instância. Para ter mais informações, consulte Endereços locais de link.

IPv4

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

IPv6

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

Para recuperar dados dinâmicos de uma instância em execução, use um dos seguintes URIs.

IPv4

http://169.254.169.254/latest/dynamic/

IPv6

http://[fd00:ec2::254]/latest/dynamic/
Exemplos: acessar com cURL

Os exemplos a seguir usam cURL para recuperar as categorias de identidade de instância de alto nível.

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
Exemplos: acessar com o PowerShell

Os exemplos a seguir usam o PowerShell para recuperar as categorias de identidade de instância de alto nível.

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 obter mais informações sobre dados dinâmicos e os exemplos de como recuperá-los, consulte Documentos de identidade da instância para instâncias do Amazon EC2.

User data

Para recuperar os dados do usuário de uma instância, use um dos URIs a seguir. Para recuperar dados do usuário usando o endereço IPv6, você deve habilitá-lo, e a instância deve ser uma instância baseada em Nitro em uma sub-rede compatível com IPv6.

IPv4

http://169.254.169.254/latest/user-data

IPv6

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

Uma solicitação de dados do usuário retorna os dados no estado em que se encontram (tipo de conteúdo application/octet-stream). Se a instância não tiver dados do usuário, a solicitação retornará 404 - Not Found.

Exemplos: acessar com cURL para recuperar texto separado por vírgula

Os exemplos a seguir usam cURL para recuperar dados do usuário que foram especificados como texto separado por vírgula.

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,,,
Exemplos: acessar com o PowerShell para recuperar texto separado por vírgula

Os exemplos a seguir usam o PowerShell para recuperar dados do usuário que foram especificados como texto separado por vírgula.

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,,,
Exemplos: acessar com cURL para recuperar um script

Os exemplos a seguir usam cURL para recuperar dados do usuário que foram especificados como um 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
Exemplos: acessar com o PowerShell para recuperar um script

Os exemplos a seguir usam o PowerShell para recuperar dados do usuário que foram especificados como um 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>

Consultar as opções de metadados da instância para as instâncias existentes

Você pode consultar as opções de metadados da instância para suas instâncias existentes usando um dos métodos a seguir.

Console
Para consultar as opções de metadados da instância para uma instância existente, usando o console

  1. Abra o console do Amazon EC2 em https://console.aws.amazon.com/ec2/.

  2. No painel de navegação, escolha Instances (Instâncias).

  3. Selecione sua instância.

  4. Escolha Ações, Configurações da instância e Modificar opções de metadados da instância.

  5. Analise as opções de metadados da instância atual na caixa de diálogo Modificar opções de metadados da instância.

AWS CLI
Para consultar as opções de metadados da instância para uma instância existente, usando o AWS CLI

Use o comando da CLI describe-instances.

aws ec2 describe-instances \
    --instance-id i-1234567898abcdef0 \
    --query 'Reservations[].Instances[].MetadataOptions'
PowerShell
Para consultar as opções de metadados da instância para uma instância existente, usando o Tools for PowerShell

Use o cmdlet Get-EC2Instance.

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

Respostas e mensagens de erro

Todos os metadados de instância são retornados como texto (tipo de conteúdo HTTP text/plain).

Uma solicitação para um recurso de metadados específico retorna o valor apropriado, ou um código de erro de HTTP 404 - Not Found se o recurso não estiver disponível.

Uma solicitação de um recurso de metadados geral (o URI termina com /) retorna uma lista de recursos disponíveis, ou um código de erro de HTTP 404 - Not Found se não houver esse recurso. Os itens da lista estão em linhas separadas que são delimitadas por caracteres de alimentação de linha (ASCII 10).

Para solicitações feitas usando o Serviço de metadados da instância versão 2, os seguintes códigos de erro HTTP podem ser retornados:

  • 400 - Missing or Invalid Parameters – a solicitação PUT não é válida.

  • 401 - Unauthorized – a solicitação GET usa um token inválido. A ação recomendada é gerar um novo token.

  • 403 - Forbidden: a solicitação não é permitida ou o IMDS está desativado.

  • 503: a solicitação não pôde ser concluída. Repetir a solicitação .

Limitação de consulta

Controlamos a utilização de consultas ao IMDS em uma base por instância, e limitamos o número de conexões simultâneas de uma instância com o IMDS.

Se você estiver usando o IMDS para recuperar as credenciais de segurança da AWS, evite consultar as credenciais durante cada transação ou simultaneamente em um número elevado de threads ou processos, pois isso pode levar a uma limitação. Em vez disso, recomendamos que você armazene em cache as credenciais até elas começarem a se aproximar da data de expiração. Para obter mais informações sobre o perfil do IAM e as credenciais de segurança associadas ao perfil, consulte Recuperar credenciais de segurança dos metadados da instância.

Se você ficar limitado ao acessar o IMDS, tente a consulta novamente com uma estratégia de recuo exponencial.