É possível acessar metadados de instância em uma instância em execução usando um dos seguintes métodos:
-
Serviço de metadados da instância versão 2 (IMDSv2): um método orientado a sessões
Para obter exemplos, consulte Exemplos para IMDSv2.
-
Serviço de metadados da instância versão 1 (IMDSv1) – um método de solicitação/resposta
Para obter exemplos, consulte Exemplos para IMDSv1.
Por padrão, é possível usar o IMDSv1 ou o IMDSv2 ou ambos.
É possível configurar o Serviço de metadados de instância (IMDS) em cada instância de modo que o código ou os usuários locais devam usar o IMDSv2. Quando você especifica que o IMDSv2 deve ser usado, o IMDSv1 não funciona mais. Para obter informações sobre como configurar sua instância para usar o IMDSv2, consulte Configurar as opções de serviço de metadados de instância.
Os cabeçalhos PUT ou GET são exclusivos do IMDSv2. Se esses cabeçalhos estiverem presentes na solicitação, a solicitação será destinada ao IMDSv2. Se nenhum cabeçalho estiver presente, presume-se que a solicitação seja destinada ao IMDSv1.
Para obter uma análise extensa do IMDSv2, consulte Adicionar defesa profunda contra firewalls abertos, proxies reversos e vulnerabilidades SSRF com melhorias no serviço de metadados da instância do EC2
Tópicos
Como Serviço de metadados da instância versão 2 funciona
O IMDSv2 usa solicitações orientadas a sessão. Com solicitações orientadas a sessão, você cria um token de sessão que define a duração da sessão, que pode ser, no mínimo, um segundo e, no máximo, seis horas. Durante o período especificado, é possível usar o mesmo token de sessão para solicitações subsequentes. Depois que a duração especificada expira, crie um novo token de sessão para uso em solicitações futuras.
nota
Os exemplos nesta seção usam o endereço IPv4 do Serviço de metadados da instância (IMDS): 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 IMDS é compatível com comandos IMDSv2. O endereço IPv6 só é acessível em instâncias baseadas em Nitro em uma sub-rede compatível com IPv6 (pilha dupla ou somente IPv6).
Os exemplos apresentados a seguir usam um script de shell e um IMDSv2 para recuperar os itens de metadados da instância de nível superior. Cada exemplo:
-
Cria um token de sessão que dura seis horas (21.600 segundos) usando a solicitação
PUT. -
Armazena o cabeçalho do token da sessão em uma variável chamada
TOKEN(para as instâncias do Linux) outoken(para as instâncias do Windows) -
Solicita os itens de metadados de nível superior usando o token
É possível executar dois comandos separados ou combiná-los.
Comandos separados
Primeiro, gere um token usando o comando a seguir.
[ec2-user ~]$TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"`
Em seguida, use o token para gerar itens de metadados de nível superior usando o comando a seguir.
[ec2-user ~]$curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/
Comandos combinados
É possível armazenar o token e combinar os comandos. O exemplo a seguir combina os dois comandos acima e armazena o cabeçalho do token de sessão em uma variável chamada TOKEN.
nota
Se houver um erro na criação do token, em vez de um token válido, uma mensagem de erro será armazenada na variável e o comando não funcionará.
[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/meta-data/
Depois de criar um token, é possível reutilizá-lo até que ele expire. No comando de exemplo a seguir, que obtém o ID da AMI usada para executar a instância, o token armazenado em $TOKEN no exemplo anterior é reutilizado.
[ec2-user ~]$curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/ami-id
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/meta-data/
Depois de criar um token, é possível reutilizá-lo até que ele expire. No comando de exemplo a seguir, que obtém o ID da AMI usada para executar a instância, o token armazenado em $token no exemplo anterior é reutilizado.
PS C:\>Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} ` -Method GET -uri http://169.254.169.254/latest/meta-data/ami-id
Quando você usa o IMDSv2 para solicitar os metadados da instância, a solicitação deve incluir o seguinte:
-
Use uma solicitação
PUTpara solicitar a inicialização de uma sessão para o serviço de metadados da instância. A solicitaçãoPUTretorna um token que deve ser incluído em solicitaçõesGETsubsequentes para o serviço de metadados da instância. O token é exigido para acessar metadados usando o IMDSv2. -
Inclua o token em todas as solicitações
GETpara o IMDS. Quando o uso do token está definido comorequired, as solicitações sem um token válido ou com um token expirado recebem um código de erro HTTP401 - Unauthorized.-
O token é uma chave específica da instância. O token não é válido em outras instâncias do EC2 e será rejeitado se você tentar usá-lo fora da instância na qual foi gerado.
-
A solicitação
PUTdeve incluir um cabeçalho que especifique a vida útil (TTL) do token, em segundos, até um máximo de seis horas (21.600 segundos). O token representa uma sessão lógica. O TTL especifica o período de validade do token e, portanto, a duração da sessão. -
Depois que o token expira, para continuar a acessar os metadados da instância, crie uma nova sessão usando outro
PUT. -
É possível optar por reutilizar um token ou criar um novo token para cada solicitação. Para um número pequeno de solicitações, pode ser mais fácil gerar e usar imediatamente um token a cada vez que você precisar acessar o IMDS. Mas, para obter eficiência, é possível especificar uma duração maior para o token e reutilizá-lo, em vez de precisar escrever uma solicitação
PUTtoda vez que precisar solicitar metadados da instância. Não há um limite prático para o número de tokens simultâneos, cada um representando sua própria sessão. No entanto, o IMDSv2 ainda é restringido pela conexão do IMDS e pelos limites de controle de utilização. Para ter mais informações, consulte Limitação de consulta.
-
Os métodos HTTP GET e HEAD são permitidos em solicitações de metadados de instâncias do IMDSv2. As solicitações PUT serão rejeitadas se contiverem um cabeçalho X-Forwarded-For.
Por padrão, a resposta a solicitações PUT tem um limite de saltos de resposta (vida útil) de 1 no nível de protocolo IP. Se você precisar de um limite maior de saltos, é possível ajustar o limite usando o comando modify-instance-metadata-options
Usar um AWS SDK compatível
Para usar o IMDSv2, as instâncias do EC2 devem usar uma versão do AWS SDK compatível com o uso do IMDSv2. As versões mais recentes de todos os AWS SDKs permitem usar o IMDSv2.
Importante
Recomendamos que você se mantenha atualizado com as versões do SDK para acompanhar os recursos, as atualizações de segurança e as dependências subjacentes mais recentes. O uso contínuo de uma versão não compatível do SDK não é recomendado e é feito a seu critério. Para obter mais informações, consulte a Política de manutenção de SDKs e ferramentas da AWS no Guia de referência de SDKs e ferramentas da AWS.
Veja a seguir as versões mínimas que são compatíveis com o uso do IMDSv2:
-
AWS CLI
: 1.16.289 -
AWS Tools for Windows PowerShell
: 4.0.1.0 -
AWS SDK for .NET
: 3.3.634.1 -
AWS SDK for C++
: 1.7.229 -
AWS SDK para Go
: 1.25.38 -
AWS SDK para Go v2
: 0.19.0 -
AWS SDK for Java
: 1.11.678 -
AWS SDK for Java 2.x
: 2.10.21 -
AWS SDK para JavaScript em Node.js
: 2.722.0 -
AWS SDK para Kotlin
– 1.1.4 -
AWS SDK for PHP
: 3.147.7 -
AWS SDK para Python (Botocore)
– 1.13.25 -
AWS SDK for Python (Boto3)
: 1.12.6 -
AWS SDK for Ruby
: 3.79.0
Exemplos para IMDSv2
Execute os exemplos a seguir na sua instância do Amazon EC2 para recuperar os metadados da instância para o IMDSv2.
Em instâncias do Windows, é possível usar o Windows PowerShell ou instalar cURL ou wget. Se você instalar uma ferramenta de terceiros em uma instância do Windows, leia a documentação que a acompanha, pois as chamadas e a saída podem ser diferentes do que é descrito aqui.
Exemplos
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.
[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/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 obter mais informações sobre os itens na resposta, consulte Categorias de metadados da instância.
Observe que as tags serão incluídas nessa saída somente se você tiver permitido o acesso. Para ter mais informações, consulte Permitir acesso a tags em metadados de instância.
[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/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/ tags/
Obtenção dos valores dos itens de metadados
Esses exemplos obtêm os valores de alguns dos itens de metadados de nível superior obtidos no exemplo anterior. Essas solicitações usam o token armazenado que foi criado usando o comando no exemplo anterior. O token não pode estar expirado.
[ec2-user ~]$curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/ami-idami-0abcdef1234567890
[ec2-user ~]$curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/reservation-idr-0efghijk987654321
[ec2-user ~]$curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/local-hostnameip-10-251-50-12.ec2.internal
[ec2-user ~]$curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/public-hostnameec2-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.
[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/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.
[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/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).
[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/meta-data/public-keys/0/openssh-keyssh-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.
[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/meta-data/network/interfaces/macs/02:29:96:8f:6a:2d/subnet-idsubnet-be9b61d7
Obter as tags de instância de uma instância de uma instância
Se o acesso às tags da instância nos metadados da instância estiver ativado, será possível obter as tags de uma instância nos metadados da instância. Para ter mais informações, consulte Recuperar tags dos metadados da instância.
Exemplos para IMDSv1
Execute os exemplos a seguir na sua instância do Amazon EC2 para recuperar os metadados da instância para o IMDSv1.
Em instâncias do Windows, é possível usar o Windows PowerShell ou instalar cURL ou wget. Se você instalar uma ferramenta de terceiros em uma instância do Windows, leia a documentação que a acompanha, pois as chamadas e a saída podem ser diferentes do que é descrito aqui.
Exemplos
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.
[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 obter mais informações sobre os itens na resposta, consulte Categorias de metadados da instância.
Observe que as tags serão incluídas nessa saída somente se você tiver permitido o acesso. Para ter mais informações, consulte Permitir acesso a tags em metadados de instância.
[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/ tags/
Obtenção dos valores dos itens de metadados
Esses exemplos obtêm os valores de alguns dos itens de metadados de nível superior obtidos no exemplo anterior.
[ec2-user ~]$curl http://169.254.169.254/latest/meta-data/ami-idami-0abcdef1234567890
[ec2-user ~]$curl http://169.254.169.254/latest/meta-data/reservation-idr-0efghijk987654321
[ec2-user ~]$curl http://169.254.169.254/latest/meta-data/local-hostnameip-10-251-50-12.ec2.internal
[ec2-user ~]$curl http://169.254.169.254/latest/meta-data/public-hostnameec2-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.
[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.
[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).
[ec2-user ~]$curl http://169.254.169.254/latest/meta-data/public-keys/0/openssh-keyssh-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.
[ec2-user ~]$curl http://169.254.169.254/latest/meta-data/network/interfaces/macs/02:29:96:8f:6a:2d/subnet-idsubnet-be9b61d7
Obter as tags de instância de uma instância de uma instância
Se o acesso às tags da instância nos metadados da instância estiver ativado, será possível obter as tags de uma instância nos metadados da instância. Para ter mais informações, consulte Recuperar tags dos metadados da instância.
