Recuperar metadados da instância - Amazon Elastic Compute Cloud

Recuperar metadados da instância

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.

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

Para visualizar todas as categorias de metadados da instância dentro de uma instância em execução, use o seguinte URI de IPv4 ou IPv6:

IPv4

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

IPv6

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

Os endereços IP são endereços locais de link e são válidos apenas a partir da instância. Para obter mais informações, consulte Endereço de link local na Wikipedia.

nota

Os exemplos nesta seção usam o endereço IPv4 do serviço de metadados da instância: 169.254.169.254. Se você estiver recuperando metadados de instância para instâncias do EC2 pelo endereço IPv6, certifique-se de habilitar e usar o endereço IPv6: fd00:ec2::254. O endereço IPv6 do serviço de metadados da instância é compatível com comandos IMDSv2. O endereço IPv6 só é acessível no Instâncias criadas no Sistema Nitro.

O formato do comando é diferente dependendo de se IMDSv1 ou IMDSv2 é usado. Por padrão, é possível usar os dois serviços de metadados de instância. Para exigir o uso do IMDSv2, consulte Usar IMDSv2.

É possível usar uma ferramenta, como o cURL, conforme mostrado no exemplo a seguir.

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" -v http://169.254.169.254/latest/meta-data/
IMDSv1
[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/

Para que o comando recupere metadados da instância de uma instância do Windows, consulte Recuperar metadados da instância no Guia do usuário do Amazon EC2 para instâncias do Windows.

Custos

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

Para evitar problemas com a recuperação de metadados de instância, considere o seguinte:

  • 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. 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 mais informações, consulte Configurar as opções de metadados da instância.

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

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 serviço de metadados de instância está desativado.

Exemplos de recuperação de metadados da instância

Os exemplos a seguir fornecem comandos que é possível usar em uma instância do Linux. Para obter os comandos para recuperar metadados da instância de uma instância do Windows, consulte Recuperar metadados da instância no Guia do usuário do Amazon EC2 para instâncias do Windows.

Obter as versões disponíveis dos metadados da instância

Este exemplo obtém as versões disponíveis dos metadados da instância. Cada versão indica uma compilação de metadados de instância quando novas categorias de metadados de instância foram lançadas. As versões de compilação de metadados de instância não têm correlação com as versões de API do Amazon EC2. As versões anteriores estarão disponíveis caso você tenha scripts que contam com a estrutura e as informações presentes em uma versão anterior.

nota

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. Por exemplo, use latest da seguinte maneira:

curl http://169.254.169.254/latest/meta-data/ami-id

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" -v http://169.254.169.254/ 1.0 2007-01-19 2007-03-01 2007-08-29 2007-10-10 2007-12-15 2008-02-01 2008-09-01 2009-04-04 2011-01-01 2011-05-01 2012-01-12 2014-02-25 2014-11-05 2015-10-20 2016-04-19 ... latest
IMDSv1
[ec2-user ~]$ curl http://169.254.169.254/ 1.0 2007-01-19 2007-03-01 2007-08-29 2007-10-10 2007-12-15 2008-02-01 2008-09-01 2009-04-04 2011-01-01 2011-05-01 2012-01-12 2014-02-25 2014-11-05 2015-10-20 2016-04-19 ... latest

Obter itens de metadados de nível superior.

Este exemplo obtém itens de metadados de nível superior. Para mais informações, consulte Categorias de metadados da instância.

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" -v http://169.254.169.254/latest/meta-data/ ami-id ami-launch-index ami-manifest-path block-device-mapping/ events/ hostname iam/ instance-action instance-id instance-life-cycle instance-type local-hostname local-ipv4 mac metrics/ network/ placement/ profile public-hostname public-ipv4 public-keys/ reservation-id security-groups services/
IMDSv1
[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/ ami-id ami-launch-index ami-manifest-path block-device-mapping/ events/ hostname iam/ instance-action instance-id instance-type local-hostname local-ipv4 mac metrics/ network/ placement/ profile public-hostname public-ipv4 public-keys/ reservation-id security-groups services/

Os exemplos a seguir obtêm os valores de alguns dos itens de metadados de nível superior que foram obtidos no exemplo anterior. As solicitações do IMDSv2 usam o token armazenado que foi criado no comando do exemplo anterior, supondo-se que ele não expirou.

IMDSv2
[ec2-user ~]$ curl -H "X-aws-ec2-metadata-token: $TOKEN" -v http://169.254.169.254/latest/meta-data/ami-id ami-0abcdef1234567890
IMDSv1
[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/ami-id ami-0abcdef1234567890

 

IMDSv2
[ec2-user ~]$ curl -H "X-aws-ec2-metadata-token: $TOKEN" -v http://169.254.169.254/latest/meta-data/reservation-id r-0efghijk987654321
IMDSv1
[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/reservation-id r-0efghijk987654321

 

IMDSv2
[ec2-user ~]$ curl -H "X-aws-ec2-metadata-token: $TOKEN" -v http://169.254.169.254/latest/meta-data/local-hostname ip-10-251-50-12.ec2.internal
IMDSv1
[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/local-hostname ip-10-251-50-12.ec2.internal

 

IMDSv2
[ec2-user ~]$ curl -H "X-aws-ec2-metadata-token: $TOKEN" -v http://169.254.169.254/latest/meta-data/public-hostname ec2-203-0-113-25.compute-1.amazonaws.com
IMDSv1
[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/public-hostname ec2-203-0-113-25.compute-1.amazonaws.com

Obter a lista de chaves públicas disponíveis

Este exemplo obtém uma lista de chaves públicas disponíveis.

IMDSv2
[ec2-user ~]$ `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" -v http://169.254.169.254/latest/meta-data/public-keys/ 0=my-public-key
IMDSv1
[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/public-keys/ 0=my-public-key

Mostrar os formatos nos quais a chave pública 0 está disponível

Este exemplo mostra os formatos nos quais a chave pública 0 está disponí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" -v http://169.254.169.254/latest/meta-data/public-keys/0/ openssh-key
IMDSv1
[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/public-keys/0/ openssh-key

Obter a chave pública 0 (no formato de chave OpenSSH)

Este exemplo obtém a chave pública 0 (no formato de chave OpenSSH).

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" -v http://169.254.169.254/latest/meta-data/public-keys/0/openssh-key ssh-rsa MIICiTCCAfICCQD6m7oRw0uXOjANBgkqhkiG9w0BAQUFADCBiDELMAkGA1UEBhMC VVMxCzAJBgNVBAgTAldBMRAwDgYDVQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBbWF6 b24xFDASBgNVBAsTC0lBTSBDb25zb2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMxHzAd BgkqhkiG9w0BCQEWEG5vb25lQGFtYXpvbi5jb20wHhcNMTEwNDI1MjA0NTIxWhcN MTIwNDI0MjA0NTIxWjCBiDELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAldBMRAwDgYD VQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBbWF6b24xFDASBgNVBAsTC0lBTSBDb25z b2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMxHzAdBgkqhkiG9w0BCQEWEG5vb25lQGFt YXpvbi5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMaK0dn+a4GmWIWJ 21uUSfwfEvySWtC2XADZ4nB+BLYgVIk60CpiwsZ3G93vUEIO3IyNoH/f0wYK8m9T rDHudUZg3qX4waLG5M43q7Wgc/MbQITxOUSQv7c7ugFFDzQGBzZswY6786m86gpE Ibb3OhjZnzcvQAaRHhdlQWIMm2nrAgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAtCu4 nUhVVxYUntneD9+h8Mg9q6q+auNKyExzyLwaxlAoo7TJHidbtS4J5iNmZgXL0Fkb FFBjvSfpJIlJ00zbhNYS5f6GuoEDmFJl0ZxBHjJnyp378OD8uTs7fLvjx79LjSTb NYiytVbZPQUQ5Yaxu2jXnimvw3rrszlaEXAMPLE my-public-key
IMDSv1
[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/public-keys/0/openssh-key ssh-rsa MIICiTCCAfICCQD6m7oRw0uXOjANBgkqhkiG9w0BAQUFADCBiDELMAkGA1UEBhMC VVMxCzAJBgNVBAgTAldBMRAwDgYDVQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBbWF6 b24xFDASBgNVBAsTC0lBTSBDb25zb2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMxHzAd BgkqhkiG9w0BCQEWEG5vb25lQGFtYXpvbi5jb20wHhcNMTEwNDI1MjA0NTIxWhcN MTIwNDI0MjA0NTIxWjCBiDELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAldBMRAwDgYD VQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBbWF6b24xFDASBgNVBAsTC0lBTSBDb25z b2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMxHzAdBgkqhkiG9w0BCQEWEG5vb25lQGFt YXpvbi5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMaK0dn+a4GmWIWJ 21uUSfwfEvySWtC2XADZ4nB+BLYgVIk60CpiwsZ3G93vUEIO3IyNoH/f0wYK8m9T rDHudUZg3qX4waLG5M43q7Wgc/MbQITxOUSQv7c7ugFFDzQGBzZswY6786m86gpE Ibb3OhjZnzcvQAaRHhdlQWIMm2nrAgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAtCu4 nUhVVxYUntneD9+h8Mg9q6q+auNKyExzyLwaxlAoo7TJHidbtS4J5iNmZgXL0Fkb FFBjvSfpJIlJ00zbhNYS5f6GuoEDmFJl0ZxBHjJnyp378OD8uTs7fLvjx79LjSTb NYiytVbZPQUQ5Yaxu2jXnimvw3rrszlaEXAMPLE my-public-key

Obter o ID de sub-rede de uma instância

Este exemplo obtém o ID de sub-rede para uma instância.

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" -v http://169.254.169.254/latest/meta-data/network/interfaces/macs/02:29:96:8f:6a:2d/subnet-id subnet-be9b61d7
IMDSv1
[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/network/interfaces/macs/02:29:96:8f:6a:2d/subnet-id subnet-be9b61d7

Obter as tags de instância de uma instância de uma instância

Nos exemplos a seguir, a instância de exemplo tem tags em metadados de instância habilitadas e as tags de instância Name=MyInstance e Environment=Dev.

Este exemplo obtém todas as chaves de tag de instância de uma instância.

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" -v http://169.254.169.254/latest/meta-data/tags/instance Name Environment
IMDSv1
[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/tags/instance Name Environment

O exemplo a seguir obtém o valor da chave Name que foi obtida no exemplo anterior. A solicitação de IMDSv2 usa o token armazenado que foi criado no comando do exemplo anterior, supondo que ele não tenha expirado.

IMDSv2
[ec2-user ~]$ curl -H "X-aws-ec2-metadata-token: $TOKEN" -v http://169.254.169.254/latest/meta-data/tags/instance/Name MyInstance
IMDSv1
[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/tags/instance/Name MyInstance

Limitação de consulta

Limitamos consultas ao serviço de metadados da instância em uma base por instância, e limitamos o número de conexões simultâneas de uma instância com o serviço de metadados da instância.

Se você estiver usando o serviço de metadados de instância 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.

Se você ficar limitado ao acessar o serviço de metadados de instância, tente a consulta novamente com uma estratégia de recuo exponencial.

Limitar o acesso a serviço de metadados da instância

É possível considerar o uso de regras do firewall local para desabilitar o acesso de alguns ou de todos os processos para o serviço de metadados de instância.

nota

Para Instâncias criadas no Sistema Nitro, o IMDS pode ser acessível a partir de sua própria rede quando um dispositivo de rede em sua VPC, como um roteador virtual, encaminha pacotes para o endereço IMDS e a verificação de origem/destino padrão na instância está desativada. Para evitar que uma fonte de fora da VPC alcance o IMDS, recomendamos que você modifique a configuração do dispositivo de rede para descartar pacotes com o endereço IPv4 de destino do IMDS 169.254.169.254 e, se você ativou o endpoint IPv6, o endereço IPv6 do IMDS fd00:ec2::254.

Usar iptables para limitar o acesso

O exemplo a seguir usa iptables do Linux e seu módulo owner para impedir que o servidor Web do Apache (com base no ID de usuário da instalação padrão do apache) acesse 169.254.169.254. Ele usa uma regra de negação para rejeitar todas as solicitações de metadados de instância (IMDSv1 ou IMDSv2) de qualquer processo que execute como esse usuário.

$ sudo iptables --append OUTPUT --proto tcp --destination 169.254.169.254 --match owner --uid-owner apache --jump REJECT

Ou é possível considerar permitir o acesso apenas a usuários ou grupos específicos usando regras de permissão. As regras de permissão podem ser mais fáceis de gerenciar de uma perspectiva de segurança, porque elas exigem que você decida qual software precisa acessar os metadados de instância. Se você usar regras de permissão, haverá menos probabilidade de você permitir acidentalmente que o software acesse o serviço de metadados (que você não queria que tivesse acesso) se você alterar o software ou a configuração posteriormente em uma instância. Também é possível combinar o uso de grupos com regras de permissão, para que você possa adicionar ou remover usuários de um grupo com permissão sem precisar alterar a regra do firewall.

O exemplo a seguir impede o acesso ao serviço de metadados da instância por todos os processos, exceto os processos em execução na conta do usuário trustworthy-user.

$ sudo iptables --append OUTPUT --proto tcp --destination 169.254.169.254 --match owner ! --uid-owner trustworthy-user --jump REJECT
nota
  • Para usar regras de firewall local, você precisa adaptar os comandos do exemplo anterior para se ajustarem a suas necessidades.

  • Por padrão, as regras de iptables não são persistentes em todas as reinicializações do sistema. Elas podem ser transformadas em persistentes usando recursos do SO não descritos aqui.

  • O módulo owner das iptables só corresponderá à associação do grupo se o grupo for o grupo primário de um determinado usuário local. Outros grupos não são correspondidos.

Usar PF ou IPFW para limitar o acesso

Se você estiver usando FreeBSD ou OpenBSD, poderá considerar também o uso de PF ou IPFW. Os exemplos a seguir limitam o acesso ao serviço de metadados de instância apenas ao usuário raiz.

PF

$ block out inet proto tcp from any to 169.254.169.254
$ pass out inet proto tcp from any to 169.254.169.254 user root

IPFW

$ allow tcp from any to 169.254.169.254 uid root
$ deny tcp from any to 169.254.169.254
nota

A ordem dos comandos PF e IPFW é importante. O padrão de PF e a regra correspondente mais recente, e o padrão de IPFW é a primeira regra correspondente.