Configurar o serviço de metadados da instância - Amazon Elastic Compute Cloud

Configurar o serviço de metadados da instância

É 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 1 (IMDSv1) – um método de solicitação/resposta

  • Serviço de metadados da instância versão 2 (IMDSv2) – um método orientado a sessões

Por padrão, você pode usar o IMDSv1 ou o IMDSv2 ou ambos. O serviço de metadados da instância faz distinção entre as solicitações do IMDSv1 e do IMDSv2 com base na presença dos cabeçalhos de PUT ou de GET, que são exclusivos do IMDSv2, em cada solicitação.

Você pode configurar o serviço de metadados da instância em cada instância de forma que o código ou os usuários locais usem o IMDSv2. Quando você especifica que o IMDSv2 deve ser usado, o IMDSv1 não funciona mais. Para obter mais informações, consulte Configurar as opções de metadados da instância.

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, você pode usar o mesmo token de sessão para solicitações subsequentes. Depois que a duração especificada expira, você deve criar um novo token de sessão para uso em solicitações futuras.

O exemplo a seguir usa um script shell do Linux e o IMDSv2 para recuperar os itens de metadados de nível superior de instância. O comando de 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

  • Solicita os itens de metadados de nível superior usando o token

[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/

Depois de criar um token, você pode 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" -v 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:

  1. Use uma solicitação PUT para solicitar a inicialização de uma sessão para o serviço de metadados da instância. A solicitação PUT retorna um token que deve ser incluído em solicitações GET subsequentes para o serviço de metadados da instância. O token é exigido para acessar metadados usando o IMDSv2.

  2. Inclua o token em todas as solicitações GET para o serviço de metadados da instância. Quando o uso do token está definido como required, as solicitações sem um token válido ou com um token expirado recebem um código de erro HTTP 401 - Unauthorized. Para obter informações sobre como alterar o uso do token, consulte modify-instance-metadata-options no AWS CLI Command Reference.

    • 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 PUT deve 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, você deve criar 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 serviço de metadados da instância. Mas, para obter eficiência, você pode especificar uma duração maior para o token e reutilizá-lo, em vez de precisar escrever uma solicitação PUT toda 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 serviço de metadados da instância e pelos limites de controle de utilização. Para obter mais informações, consulte Limitação.

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. É possível ajustar o limite de saltos usando o comando modify-instance-metadata-options se você precisar de um limite maior. Por exemplo, um limite de saltos maior pode ser necessário para compatibilidade com versões anteriores de serviços de contêiner em execução na instância. Para obter mais informações, consulte modify-instance-metadata-options no AWS CLI Command Reference.

Transição para usar o Serviço de metadados da instância versão 2

O uso do Serviço de metadados da instância versão 2 (IMDSv2) é opcional. O suporte ao Serviço de metadados da instância versão 1 (IMDSv1) será oferecido indefinidamente. Se você optar por migrar usando o IMDSv2, recomendamos usar as ferramentas e o caminho de transição a seguir.

Ferramentas para ajudar com a transição para o IMDSv2

Se seu software usar o IMDSv1, use as ferramentas a seguir para ajudar a configurar o software para usar o IMDSv2.

  • Software da AWS: as versões mais recentes dos AWS SDKs e CLIs oferecem suporte ao IMDSv2. Para usar o IMDSv2, verifique se as instâncias do EC2 têm as versões mais recentes dos AWS SDKs e CLIs. Para obter informações sobre como atualizar a CLI, consulte Atualizar para a versão mais recente da CLI da AWS no Guia do usuário do AWS Command Line Interface.

  • CloudWatch: o IMDSv2 usa sessões com token, enquanto o IMDSv1 não. A métrica MetadataNoToken do CloudWatch rastreia o número de chamadas para o serviço de metadados da instância que estão usando o IMDSv1. Rastreando essa métrica até zero, você pode determinar se e quando todo o software foi atualizado para usar o IMDSv2. Para obter mais informações, consulte Métricas de instância.

  • Atualizações das CLIs e APIs do EC2: para instâncias existentes, é possível usar o comando modify-instance-metadata-options da CLI (ou a API ModifyInstanceMetadataOptions) para exigir o uso do IMDSv2. Para novas instâncias, é possível usar o comando run-instances da CLI (ou a API RunInstances) e o parâmetro metadata-options para executar novas instâncias que exigem o uso do IMDSv2.

    Para exigir o uso do IMDSv2 em todas as novas instâncias executadas por grupos do Auto Scaling, os grupos do Auto Scaling devem usar modelos de execução. Ao criar um modelo de execução, configure os parâmetros MetadataOptions para exigir o uso do IMDSv2. Para grupos do Auto Scaling que usam configurações de execução, substitua as configurações de execução por modelos de execução. Depois de substituir uma configuração de execução por um modelo de execução, o grupo do Auto Scaling executa novas instâncias usando o novo modelo de execução, mas as instâncias existentes não são afetadas. Use o comando modify-instance-metadata-options da CLI (ou a API ModifyInstanceMetadataOptions) para exigir o uso do IMDSv2 em instâncias existentes, ou encerre as instâncias, e o grupo do Auto Scaling executará novas instâncias de substituição com as configurações das opções de metadados de instância definidas no modelo de execução.

  • Políticas do IAM e SCPs: é possível usar uma condição do IAM para exigir que os usuários do IAM não executem uma instância a menos que ela use IMDSv2. Também é possível usar condições do IAM para exigir que os usuários do IAM não podem executar instâncias para habilitar novamente o IMDSv1 e exigir que o serviço de metadados da instância esteja disponível na instância.

    As chaves de condição ec2:MetadataHttpTokens, ec2:MetadataHttpPutResponseHopLimit e ec2:MetadataHttpEndpoint do IAM podem ser usadas para controlar o uso de RunInstances, da API ModifyInstanceMetadataOptions e da CLI correspondente. Se uma política for criada, e um parâmetro na chamada à API não corresponder ao estado especificado na política usando a chave de condição, a chamada à API ou à CLI falhará com uma resposta UnauthorizedOperation. Essas chaves de condição podem ser usadas em políticas do IAM ou políticas de controle de serviço (SCPs) das AWS Organizations.

    Além disso, é possível escolher uma camada adicional de proteção para exigir a alteração do IMDSv1 para o IMDSv2. Na camada de gerenciamento de acesso com relação a API chamadas por meio de credenciais de função do EC2, você pode usar uma nova chave de condição nas políticas do IAM ou nas políticas de controle de serviço (SCPs) do AWS Organizations. Especificamente, ao usar a chave da condição da política ec2:RoleDelivery com um valor de 2.0 nas políticas do IAM, as chamadas à API feitas com credencias de função do EC2 obtidas do IMDSv1 receberão uma resposta UnauthorizedOperation. A mesma coisa pode ser obtida de forma mais ampla com essa condição exigida por uma SCP. Isso garante que as credenciadas entregues por meio do IMDSv1 não podem ser realmente usadas para chamar APIs porque todas as chamadas à API que não corresponderem à condição especificada receberão um erro UnauthorizedOperation. Para obter exemplos de políticas do IAM, consulte Trabalhar com metadados de instância. Para obter mais informações, consulte Políticas de controle de serviço no Guia do usuário do AWS Organizations.

Caminho recomendado para exigir acesso ao IMDSv2

Usando as ferramentas acima, recomendamos que você siga este caminho para fazer a transição para o IMDSv2:

Etapa 1: No início

Atualize os SDKs, as CLIs e o software que usam credenciais de função em suas instâncias do EC2 para versões compatíveis com o IMDSv2. Para obter informações sobre como atualizar a CLI, consulte Atualizar para a versão mais recente da CLI da AWS no Guia do usuário do AWS Command Line Interface.

Depois, altere o software que acessa os metadados da instância diretamente (ou seja, que não usa um SDK) usando as solicitações do IMDSv2.

Etapa 2: Durante a transição

Acompanhe o andamento da transição usando a métrica do CloudWatch MetadataNoToken. Essa métrica mostra o número de chamadas para o serviço de metadados da instância que estão usando o IMDSv1 em suas instâncias. Para obter mais informações, consulte Métricas de instância.

Etapa 3: Quando tudo estiver pronto em todas as instâncias

Tudo estará pronto em todas as instâncias quando a métrica do CloudWatch MetadataNoToken registrar uso zero do IMDSv1. Nessa fase, é possível fazer o seguinte:

  • Nessa fase, você pode exigir o uso do IMDSv2 por meio do comando modify-instance-metadata-options. É possível fazer essas alterações em instâncias em execução. Não é necessário reiniciar as instâncias.

  • Para novas instâncias: ao executar uma nova instância, é possível usar o comando run-instances para especificar que somente o IMDSv2 deve ser usado.

A especificação das opções de metadados da instância está disponível apenas por meio da API ou da CLI da AWS, ela não está disponível por meio do Console de gerenciamento da AWS. Para obter mais informações, consulte Configurar as opções de metadados da instância.

Etapa 4: Quando todas as suas instâncias tiverem feito a transição para o IMDSv2

As chaves de condição ec2:MetadataHttpTokens, ec2:MetadataHttpPutResponseHopLimit e ec2:MetadataHttpEndpoint do IAM podem ser usadas para controlar o uso de RunInstances, da API ModifyInstanceMetadataOptions e da CLI correspondente. Se uma política for criada, e um parâmetro na chamada à API não corresponder ao estado especificado na política usando a chave de condição, a chamada à API ou à CLI falhará com uma resposta UnauthorizedOperation. Para obter exemplos de políticas do IAM, consulte Trabalhar com metadados de instância.

Configurar as opções de metadados da instância

As opções de metadados de instância permitem configurar instâncias novas ou existentes para fazer o seguinte:

  • Exigir o uso do IMDSv2 ao solicitar metadados de instância

  • Especificar o limite de salto de resposta PUT

  • Desativar o acesso aos metadados da instância

Também é possível usar chaves de condição do IAM em uma política do IAM ou SCP para fazer o seguinte:

  • Permitir que uma instância seja executada somente se ela estiver configurada para exigir o uso do IMDSv2

  • Restringir o número de saltos permitidos

  • Desativar o acesso aos metadados da instância

Para configurar as opções de metadados de instância em instâncias novas ou existentes, você usa o AWS SDK ou a CLI. Para obter mais informações, consulte run-instances e modify-instance-metadata-options na AWS CLI Command Reference.

nota

Proceda com cautela e conduza testes cuidadosos antes de fazer qualquer alteração. Anote o seguinte:

  • Se você exigir o uso do IMDSv2, os aplicativos ou agentes que usam o IMDSv1 para acesso aos metadados da instância falharão.

  • Se você desativar todo o acesso aos metadados da instância, os aplicativos ou agentes que contam com o acesso aos metadados da instância para funcionarem falharão.

Configurar opções de metadados da instância para novas instâncias

É possível exigir o uso do IMDSv2 em uma instância ao executá-la. Você também pode criar uma política do IAM que impeça que os usuários executem novas instâncias, a menos que exijam o IMDSv2 na nova instância.

Como exigir o uso do IMDSv2 em uma nova instância

O exemplo de run-instances a seguir executa uma instância c3.large com --metadata-options definido como HttpTokens=required. Quando você especifica um valor para HttpTokens, você também deve definir HttpEndpoint como enabled. Como o cabeçalho de token seguro é definido como required para solicitações de recuperação de metadados, ele opta por exigir o uso do IMDSv2 na instância ao solicitar metadados de instância.

aws ec2 run-instances --image-id ami-0abcdef1234567890 --instance-type c3.large ... --metadata-options "HttpEndpoint=enabled,HttpTokens=required"

Como exigir o uso do IMDSv2 em todas as novas instâncias

Para garantir que os usuários do IAM podem executar apenas instâncias que usam o IMDSv2 ao solicitar metadados da instância, você pode especificar que a condição para exigir o IMDSv2 deve ser atendida para que uma instância possa ser executada. Para ver um exemplo de política do IAM, consulte Trabalhar com metadados de instância.

Como desabilitar o acesso aos metadados da instância

Para garantir que o acesso aos metadados da instância esteja desativado, independentemente da versão do serviço de metadados da instância que você esteja usando, inicie a instância com --metadata-options definido como HttpEndpoint=disabled. Você pode habilitar o acesso posteriormente usando o comando modify-instance-metadata-options.

aws ec2 run-instances --image-id ami-0abcdef1234567890 --instance-type c3.large ... --metadata-options "HttpEndpoint=disabled"

Configurar opções de metadados de instâncias existentes

É possível exigir o uso do IMDSv2 em uma instância existente Você também pode alterar o limite de saltos de resposta PUT e desativar o acesso aos metadados em uma instância existente. Também é possível criar uma política do IAM que impeça que os usuários modifiquem as opções de metadados em uma instância existente.

Como exigir o uso do IMDSv2 em uma instância existente

Para instâncias existentes, é possível optar por exigir que o IMDSv2 seja usado ao solicitar metadados de instância. Use o comando modify-instance-metadata-options da CLI e defina o parâmetro http-tokens como required.

nota

Ao especificar um valor para http-tokens, também é necessário definir http-endpoint como enabled.

aws ec2 modify-instance-metadata-options \ --instance-id i-1234567898abcdef0 \ --http-tokens required \ --http-endpoint enabled

Como alterar o limite de saltos da resposta de PUT em uma instância existente

Para instâncias existentes, é possível alterar as configurações do limite de saltos de resposta de PUT. Use o comando modify-instance-metadata-options da CLI e defina o parâmetro http-put-response-hop-limit como o número de saltos necessário. No exemplo a seguir, o limite de saltos está definido como 3. Observe que ao especificar um valor para http-put-response-hop-limit, também é necessário definir http-endpoint como enabled.

aws ec2 modify-instance-metadata-options \ --instance-id i-1234567898abcdef0 \ --http-put-response-hop-limit 3 \ --http-endpoint enabled

Como desativar o acesso a metadados de instância em uma instância existente

Para instâncias existentes, é possível desativar o acesso aos metadados da instância desabilitando o HTTP endpoint do serviço de metadados de instância, independentemente de qual versão do serviço de metadados de instância você está usando. É possível reverte essa alteração a qualquer momento habilitando o HTTP endpoint. Use o comando modify-instance-metadata-options da CLI e defina o parâmetro http-endpoint como disabled.

aws ec2 modify-instance-metadata-options \ --instance-id i-1234567898abcdef0 \ --http-endpoint disabled

Como controlar o uso de modify-instance-metadata-options

Para controlar quais usuários do IAM podem modificar as opções de metadados em uma instância existente, é possível especificar uma política que impeça que todos os usuários que não tenham uma função especificada usem a API ModifyInstanceMetadataOptions. Para ver um exemplo de política do IAM, consulte Trabalhar com metadados de instância.