# Usar metadados da instância para gerenciar a instância do EC2
<a name="ec2-instance-metadata"></a>

Os *metadados da instância* são dados sobre sua instância que é possível usar para configurar ou gerenciar a instância em execução. Os metadados de instância incluem o seguinte:

**Propriedades de metadados de instância**  
As propriedades dos metadados de instância são divididas em [categorias](#instancedata-data-categories), por exemplo, nome do host, eventos e grupos de segurança.

**Dados dinâmicos**  
Os dados dinâmicos são metadados que são gerados quando a instância é executada, como um documento de identidade de instância. Para obter mais informações, consulte [Categorias de dados dinâmicos](#dynamic-data-categories).

**Dados do usuário**  
Você também pode usar os metadados de instância para acessar os *dados do usuário* que você especificou ao executar a instância. Por exemplo, é possível especificar parâmetros para configurar a instância ou incluir um script simples. Além disso, é possível criar AMIs genéricas e usar dados do usuário para modificar os arquivos de configuração fornecidos no momento da inicialização. Por exemplo, se você executar servidores Web para diversas pequenas empresas, todos eles poderão usar a mesma AMI genérica e recuperar o conteúdo de um bucket do Amazon S3 que você especificar nos dados do usuário na execução. Para adicionar um novo cliente a qualquer momento, crie um bucket para o cliente, adicione seu conteúdo e inicie a AMI com o nome exclusivo do bucket fornecido ao código nos dados do usuário. Se você executar várias instâncias usando a mesma chamada `RunInstances`, os dados do usuário estarão disponíveis para todas as instâncias nessa reserva. Cada instância que integra a mesma reserva tem um número de `ami-launch-index` exclusivo, permitindo que você escreva código que controle o que as instâncias farão. Por exemplo, o primeiro host pode se eleger como o nó original em um cluster. Para obter um exemplo detalhado de inicialização da AMI, consulte [Identificar cada instância executada em uma única solicitação](AMI-launch-index-examples.md).

**Importante**  
Embora você só possa acessar os metadados de instância e os dados do usuário de dentro da própria instância, os dados não são protegidos por autenticação ou métodos de criptografia. Qualquer usuário que tenha acesso direto à instância e, potencialmente, qualquer software em execução na instância, pode visualizar seus metadados. Portanto, você não deve armazenar dados confidenciais, como senhas ou chaves de criptografia de longa duração, como dados de usuário.

**Topics**
+ [

## Categorias de metadados da instância
](#instancedata-data-categories)
+ [

## Categorias de dados dinâmicos
](#dynamic-data-categories)
+ [

# Acessar metadados de instância para uma instância do EC2
](instancedata-data-retrieval.md)
+ [

# Configurar as opções de serviço de metadados de instância
](configuring-instance-metadata-options.md)
+ [

# Executar comandos ao iniciar uma instância do EC2 com entrada de dados do usuário
](user-data.md)
+ [

# Identificar cada instância executada em uma única solicitação
](AMI-launch-index-examples.md)

## Categorias de metadados da instância
<a name="instancedata-data-categories"></a>

As propriedades de metadados de instância são divididas em categorias. Para recuperar as propriedades dos metadados de instância, especifique a categoria na solicitação. Os metadados serão retornados na resposta.

Quando novas categorias forem lançadas, uma nova compilação de metadados de instância será criada com um novo número de versão. Na tabela a seguir, a coluna **Version when category was released** (Versão quando a categoria foi lançada) especifica a versão da compilação quando uma categoria de metadados de instância foi lançada. Para evitar ter que atualizar seu código sempre que o Amazon EC2 lançar uma nova compilação de metadados de instância, use `latest` em vez do número da versão em suas solicitações de metadados. Para obter mais informações, consulte [Obter as versões disponíveis dos metadados da instância](configuring-instance-metadata-service.md#instance-metadata-ex-1).

Quando o Amazon EC2 libera uma nova categoria de metadados de instância, os metadados de instância da nova categoria podem não estar disponíveis para instâncias existentes. Com instâncias [basedas em Nitro](instance-types.md#instance-hypervisor-type), será possível recuperar metadados de instâncias somente para as categorias que estavam disponíveis na execução. Para instâncias com o hipervisor Xen, é possível [interromper e iniciar](Stop_Start.md) a instância para atualizar as categorias que estão disponíveis para a instância.

A tabela a seguir lista as categorias de metadados da instância. Alguns dos nomes de categoria incluem espaços reservados para dados exclusivos da instância. Por exemplo, *mac* representa o endereço MAC para a interface de rede. É necessário substituir os espaços reservados pelos valores reais ao recuperar os metadados da instância.


| Categoria | Descrição | Versão quando a categoria foi lançada | 
| --- | --- | --- | 
| ami-id  | O ID da AMI usada para executar a instância. | 1,0 | 
| ami-launch-index  | Se você executar várias instâncias usando a mesma chamada RunInstances, esse valor indicará a ordem de execução de cada instância. O valor da primeira instância executada é 0. Se você executar instâncias usando uma frota do Auto Scaling ou do EC2, esse valor será sempre 0. | 1,0 | 
| ami-manifest-path  | O caminho para o arquivo de manifesto da AMI no Amazon S3. Se você usou uma AMI baseada no Amazon EBS para executar a instância, o resultado retornado será unknown. | 1,0 | 
| ancestor-ami-ids  | Os IDs das AMIs de todas as instâncias que foram reagrupadas para criar essa AMI. Este valor existirá somente se o arquivo de manifesto de AMIs continham uma chave ancestor-amis. | 10/10/2007 | 
| autoscaling/target-lifecycle-state |  Valor mostrando o estado de destino do ciclo de vida do Auto Scaling para o qual uma instância do Auto Scaling está fazendo a transição. Presente quando a instância faz a transição para um dos estados de destino do ciclo de vida após 10 de março de 2022. Valores possíveis: `Detached` \$1 `InService` \$1 `Standby` \$1 `Terminated` \$1 `Warmed:Hibernated` \$1 `Warmed:Running` \$1 `Warmed:Stopped` \$1 `Warmed:Terminated`. Consulte [Retrieve the target lifecycle state through instance metadata](https://docs.aws.amazon.com/autoscaling/ec2/userguide/retrieving-target-lifecycle-state-through-imds.html) (Recuperar o estado de destino do ciclo de vida por meio de metadados da instância) no *Guia do usuário do Amazon EC2 Auto Scaling*.   | 2021-07-15 | 
| block-device-mapping/ami | O dispositivo virtual que contém o sistema de arquivos de inicialização/raiz. | 15/12/2007 | 
| block-device-mapping/ebsN  | Os dispositivos virtuais associados a quaisquer volumes do Amazon EBS. Os volumes do Amazon EBS estarão disponíveis somente em metadados se estiverem presentes no momento da execução ou quando a instância foi iniciada pela última vez. O N indica o índice do volume do Amazon EBS (como ebs1 ou ebs2). | 15/12/2007 | 
| block-device-mapping/ephemeralN  | Os dispositivos virtuais para qualquer volume de armazenamento de instâncias não NVMe. O N indica o índice de cada volume. O número dos volumes de armazenamento de instâncias no mapeamento de dispositivos de blocos pode não corresponder ao número real de volumes de armazenamento de instâncias da instância. O tipo de instância determina o número de volumes de armazenamento de instâncias que estão disponíveis para uma instância. Se o número de volumes de armazenamento de instâncias em um mapeamento de dispositivos de blocos exceder o número disponível para uma instância, os volumes de armazenamento de instâncias adicionais serão ignorados. | 15/12/2007 | 
| block-device-mapping/root  | Os dispositivos virtuais ou as partições associadas aos dispositivos raiz, ou as partições no dispositivo virtual, onde o sistema de arquivos raiz (/ ou C:) está associado à instância específica. | 15/12/2007 | 
| block-device-mapping/swap  | Os dispositivos virtuais associados a swap. Nem sempre presente. | 15/12/2007 | 
| events/maintenance/history | Se houver eventos de manutenção da instância concluídos ou cancelados, contém uma string JSON com informações sobre os eventos. | 17/08/2018 | 
| events/maintenance/scheduled | Se houver eventos de manutenção da instância ativos, contém uma string JSON com informações sobre os eventos. Para obter mais informações, consulte [Visualizar eventos programados que afetam as instâncias do Amazon EC2](viewing_scheduled_events.md). | 17/08/2018 | 
| events/recommendations/rebalance | O tempo aproximado, em UTC, quando a notificação de recomendação de rebalanceamento da instância do EC2 é emitida para a instância. Veja a seguir um exemplo dos metadados para esta categoria: \$1"noticeTime": "2020-11-05T08:22:00Z"\$1. Esta categoria só está disponível após a emissão da notificação. Para obter mais informações, consulte [Recomendações de rebalanceamento de instâncias do EC2](rebalance-recommendations.md). | 2020-10-27 | 
| hostname | Se a instância do EC2 estiver usando a nomenclatura baseada em IP (IPBN), esse é o hostname DNS de IPv4 privado da instância. Se a instância do EC2 estiver usando nomenclatura baseada em recursos (RBN), esse é o RBN. Em casos em que várias interfaces de rede estão presentes, isso se refere ao dispositivo eth0 (o dispositivo para o qual o número de dispositivo é 0). Para obter mais informações sobre IPBN e RBN, consulte [Nomes de host e domínios de instâncias do EC2](ec2-instance-naming.md). | 1,0 | 
|  iam/info  | Se houver uma função do IAM associada à instância, conterá informações sobre a última vez que o perfil de instância foi atualizado, incluindo a data LastUpdated, InstanceProfileArn e InstanceProfileId. Caso contrário, não estará presente. | 12/01/2012 | 
|  iam/security-credentials/role-name  | Se houver uma função do IAM associada à instância, role-name será o nome da função, e role-name conterá as credenciais de segurança temporárias associadas à função (para obter mais informações, consulte [Recuperar credenciais de segurança dos metadados da instância](instance-metadata-security-credentials.md)). Caso contrário, não estará presente. | 12/01/2012 | 
| identity-credentials/ec2/info | Informações sobre as credenciais no identity-credentials/ec2/security-credentials/ec2-instance. | 23/05/2018 | 
| identity-credentials/ec2/security-credentials/ec2-instance | As credenciais do perfil de identidade da instância que permitem que o software na instância se identifique para a AWS para oferecer suporte a recursos como o EC2 Instance Connect e à Configuração padrão de gerenciamento de host do AWS Systems Manager. Essas credenciais não têm políticas anexadas, portanto, não têm permissões adicionais de APIs da AWS além de identificar a instância para o recurso da AWS. Para obter mais informações, consulte [Perfis de identidade da instância para instâncias do Amazon EC2](iam-roles-for-amazon-ec2.md#ec2-instance-identity-roles). | 23/05/2018 | 
| instance-action | Notifica a instância que ela deve ser reinicializada em preparação para o empacotamento. Valores válidos: none \$1 shutdown \$1 bundle-pending. | 01/09/2008 | 
| instance-id | O ID dessa instância. | 1,0 | 
| instance-life-cycle | A opção de compra desta instância. Para obter mais informações, consulte [Opções de faturamento e compra do Amazon EC2](instance-purchasing-options.md). | 01/10/2019 | 
| instance-type  | O tipo da instância. Para obter mais informações, consulte [Tipos de instância do Amazon EC2](instance-types.md). | 29/08/2007 | 
| ipv6  | O endereço IPv6 da instância. Em casos em que várias interfaces de rede estão presentes, isso se refere ao dispositivo eth0 (o dispositivo cujo número de dispositivo é 0) na interface de rede e o primeiro endereço iPv6 atribuído. Se nenhum endereço IPv6 existir na interface de rede[0], esse item não será definido e gerará uma resposta HTTP 404. | 2021-01-03 | 
|  kernel-id  | O ID do kernel executado com essa instância, se aplicável. | 01/02/2008 | 
|  local-hostname  | Em casos em que várias interfaces de rede estão presentes, isso se refere ao dispositivo eth0 (o dispositivo para o qual o número de dispositivo é 0). Se a instância do EC2 estiver usando a nomenclatura baseada em IP (IPBN), esse é o hostname DNS de IPv4 privado da instância. Se a instância do EC2 estiver usando nomenclatura baseada em recursos (RBN), esse é o RBN. Para obter mais informações sobre IPBN, RBN e nomenclatura de instâncias do EC2, consulte [Nomes de host e domínios de instâncias do EC2](ec2-instance-naming.md). | 19/01/2007 | 
|  local-ipv4  | O endereço IPv4 privado da instância. Em casos em que várias interfaces de rede estão presentes, isso se refere ao dispositivo eth0 (o dispositivo para o qual o número de dispositivo é 0). Se esta for uma instância somente IPv6, esse item não será definido e gerará uma resposta HTTP 404. | 1,0 | 
|  mac  | O endereço Media Access Control (MAC) da instância. Em casos em que várias interfaces de rede estão presentes, isso se refere ao dispositivo eth0 (o dispositivo para o qual o número de dispositivo é 0). | 01/01/2011 | 
| metrics/vhostmd | Não está mais disponível. | 01/05/2011 | 
|  network/interfaces/macs/mac/device-number  | O número de dispositivo exclusivo associado a essa interface. O número do dispositivo corresponde ao nome do dispositivo; por exemplo, um device-number de 2 é para o dispositivo eth2. Essa categoria corresponde aos campos DeviceIndex e device-index que são usados pelos comandos da API do Amazon EC2 e do EC2 para a AWS CLI. | 01/01/2011 | 
|  network/interfaces/macs/mac/interface-id  | O ID da interface de rede. | 01/01/2011 | 
|  network/interfaces/macs/mac/ipv4-associations/public-ip  | Os endereços IPv4 privados que estão associados a cada endereço IP público e estão atribuídos a essa interface. | 01/01/2011 | 
| network/interfaces/macs/mac/ipv6s | Os endereços IPv6 atribuídos à interface. | 30/06/2016 | 
| network/interfaces/macs/mac/ipv6-prefix | O prefixo IPv6 atribuído à interface de rede. |  | 
|  network/interfaces/macs/mac/local-hostname  |  O nome de host DNS IPv4 privado da instância. Em casos em que várias interfaces de rede estão presentes, isso se refere ao dispositivo eth0 (o dispositivo para o qual o número de dispositivo é 0). Se esta for uma instância somente IPv6, esse será o nome baseado em recursos. Para obter mais informações sobre IPBN e RBN, consulte [Nomes de host e domínios de instâncias do EC2](ec2-instance-naming.md).  | 19/01/2007 | 
|  network/interfaces/macs/mac/local-ipv4s  | Os endereços IPv4 privados associados à interface. Se esta for uma interface de rede somente IPv6, esse item não será definido e gerará uma resposta HTTP 404. | 01/01/2011 | 
|  network/interfaces/macs/mac/mac  | O endereço MAC da instância. | 01/01/2011 | 
|  network/interfaces/macs/mac/network-card  | O índice da placa de rede. Alguns tipos de instância suportam várias placas de rede. | 01-11-2020 | 
| network/interfaces/macs/mac/owner-id  | O ID do proprietário da interface de rede. Em ambientes de várias interfaces, um terceiro pode anexar uma interface, como o Elastic Load Balancing. O tráfego em uma interface é sempre cobrado do proprietário da interface. | 01/01/2011 | 
|  network/interfaces/macs/mac/public-hostname  | O DNS público da interface (IPv4). Essa categoria só será retornada se o atributo enableDnsHostnames for definido como true. Para acessar mais informações, consulte [Atributos de DNS para sua VPC](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html) no Guia do usuário da Amazon VPC. Se a instância tiver apenas um endereço IPv6 público e nenhum endereço IPv4 público, esse item não será definido e gerará uma resposta HTTP 404. |  01/01/2011 | 
|  network/interfaces/macs/mac/public-ipv4s  | Os endereços IP públicos ou os endereços IP elásticos associados à interface. Pode haver vários endereços IPv4 em uma instância.  | 01/01/2011 | 
| network/interfaces/macs/mac/security-groups  | Grupos de segurança aos quais a interface de rede pertence. | 01/01/2011 | 
|  network/interfaces/macs/mac/security-group-ids  | Os IDs dos grupos de segurança aos quais a interface de rede pertence. | 01/01/2011 | 
|  network/interfaces/macs/mac/subnet-id  | O ID da sub-rede na qual a interface reside. | 01/01/2011 | 
|  network/interfaces/macs/mac/subnet-ipv4-cidr-block  | O bloco CIDR IPv4 da sub-rede na qual a interface reside. | 01/01/2011 | 
| network/interfaces/macs/mac/subnet-ipv6-cidr-blocks  | O bloco CIDR IPv6 da sub-rede na qual a interface reside. | 30/06/2016  | 
|  network/interfaces/macs/mac/vpc-id  | O ID da VPC na qual a interface reside. | 01/01/2011 | 
| network/interfaces/macs/mac/vpc-ipv4-cidr-block | O bloco CIDR IPv4 principal da VPC. | 01/01/2011 | 
| network/interfaces/macs/mac/vpc-ipv4-cidr-blocks | Os blocos CIDR IPv4 da VPC. | 30/06/2016  | 
| network/interfaces/macs/mac/vpc-ipv6-cidr-blocks | O bloco CIDR IPv6 da VPC na qual a interface reside. | 30/06/2016  | 
|  placement/availability-zone | A zona de disponibilidade na qual a instância foi executada. | 01/02/2008 | 
|  placement/availability-zone-id | O ID estático da zona de disponibilidade em que a instância é executada. O ID da zona de disponibilidade é consistente entre as contas. No entanto, pode ser diferente da zona de disponibilidade, que pode variar de acordo com a conta. | 01/10/2019 | 
|  placement/group-name  | O nome do grupo de posicionamento no qual a instância é executada. | 24/08/2020 | 
|  placement/host-id  | O ID do host no qual a instância é executada. Aplicável apenas a Hosts dedicados. | 24/08/2020 | 
|  placement/partition-number  | O número da partição na qual a instância é executada. | 24/08/2020 | 
|  placement/region  | A região da AWS na qual a instância é executada. | 24/08/2020 | 
|  product-codes  | AWS Marketplace Os códigos de produtos associados com a instância, se houver.  | 01/03/2007 | 
|  public-hostname  | O DNS público da instância (IPv4). Essa categoria só será retornada se o atributo enableDnsHostnames for definido como true. Para acessar mais informações, consulte [Atributos de DNS para sua VPC](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html) no Guia do usuário da Amazon VPC. Se a instância tiver apenas um endereço IPv6 público e nenhum endereço IPv4 público, esse item não será definido e gerará uma resposta HTTP 404. | 19/01/2007 | 
|  public-ipv4  | O endereço IPv4 público. Se um endereço IP elástico estiver associado à instância, o valor retornado será o endereço IP elástico. | 19/01/2007 | 
|  public-keys/0/openssh-key  | Chave pública. Disponível somente se fornecido no momento da execução da instância. | 1,0 | 
|  ramdisk-id  | O ID do disco de RAM no momento da execução, se aplicável. | 10/10/2007 | 
|  reservation-id  | O ID da reserva. | 1,0 | 
|  security-groups  |  Os nomes dos grupos de segurança aplicados à instância. Após a execução, você só pode alterar os grupos de segurança das instâncias. Essas alterações estão refletidas aqui e em network/interfaces/macs/**mac**/security-groups.  | 1,0 | 
|  services/domain  |  O domínio dos recursos da AWS para a região.  | 25/02/2014 | 
|  services/partition  |  A partição na qual o recurso está. Para regiões padrão da AWS a partição é `aws`. Se você tem recursos em outras partições, a partição é `aws-partitionname`. Por exemplo, a partição de recursos na região China (Pequim) é `aws-cn`.  | 20/10/2015 | 
|  spot/instance-action  |  A ação (hibernar, interromper ou encerrar) e o tempo aproximado, em UTC, em que a ação ocorrerá. Esse item estará presente somente se a instância spot tiver sido marcada para hibernar, interromper ou encerrar. Para obter mais informações, consulte [instance-action](spot-instance-termination-notices.md#instance-action-metadata).  | 15/11/2016 | 
|  spot/termination-time  |  O tempo aproximado, em UTC, no qual o sistema operacional para sua instância spot receberá o sinal de desligamento. Esse item está presente e contém um valor de tempo (por exemplo, 2015-01-05T18:02:00Z) somente se a instância spot tiver sido marcada para término pelo Amazon EC2. O item hora de encerramento não está definido como uma hora se você mesmo encerrou a instância spot. Para obter mais informações, consulte [termination-time](spot-instance-termination-notices.md#termination-time-metadata).  | 05/11/2014 | 
| system | O tipo de virtualização subjacente (hipervisor) da instância. | 2022-09-24 | 
| tags/instance | As tags de instância associadas à instância. Somente disponível se você permitir explicitamente acesso a etiquetas em metadados de instância. Para obter mais informações, consulte [Habilitar o acesso a tags em metadados da instância](work-with-tags-in-IMDS.md#allow-access-to-tags-in-IMDS). | 2021-03-23 | 

## Categorias de dados dinâmicos
<a name="dynamic-data-categories"></a>

A tabela a seguir lista as categorias de dados dinâmicos.


| Categoria | Descrição | Versão quando a categoria foi lançada | 
| --- | --- | --- | 
| fws/instance-monitoring  | O valor que mostra se o cliente habilitou o monitoramento de um minuto detalhado no CloudWatch. Valores válidos: enabled \$1 disabled | 04/04/2009 | 
| instance-identity/document  | O JSON que contém os atributos da instância, como o ID da instância, o endereço IP privado, etc. Consulte [Documentos de identidade da instância para instâncias do Amazon EC2](instance-identity-documents.md).  | 04/04/2009 | 
| instance-identity/pkcs7  | Usado para verificar a autenticidade e o conteúdo do documentos em relação à assinatura. Consulte [Documentos de identidade da instância para instâncias do Amazon EC2](instance-identity-documents.md).  | 04/04/2009 | 
| instance-identity/signature  | Os dados que podem ser usados por outras partes para verificar sua origem e autenticidade. Consulte [Documentos de identidade da instância para instâncias do Amazon EC2](instance-identity-documents.md).  | 04/04/2009 | 

# Acessar metadados de instância para uma instância do EC2
<a name="instancedata-data-retrieval"></a>

É possível 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](#query-IMDS-existing-instances).

É possível 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](user-data.md#user-data-modify). Para obter um exemplo do Linux que usa a AWS CLI, consulte [modify-instance-attribute](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-attribute.html). Para obter um exemplo do Windows que usa o Tools for Windows PowerShell, consulte [Dados do usuário e Tools for Windows PowerShell](user-data.md#user-data-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
<a name="imds-considerations"></a>

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

**Falhas na inicialização da instância devido à imposição do IMDSv2 (`HttpTokensEnforced=enabled`)**  
Antes de habilitar a imposição do IMDSv2, você precisa que todo o software na instância ofereça suporte ao IMDSv2. Depois disso, você pode alterar o padrão para desabilitar o IMDSv1 (`httpTokens=required`) e depois habilitar a imposição. Para obter mais informações, [Transição para usar o Serviço de metadados da instância versão 2](instance-metadata-transition-to-version-2.md).

**Formato do comando**  
O formato do comando é diferente, dependendo de você usar a versão 1 do serviço de metadados de instância (IMDSv1) ou a versão 2 do serviço de metadados de instância (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](configuring-instance-metadata-service.md).

**Se o IMDSv2 for necessário, o IMDSv1 não funcionará**  
Se você usa o IMDSv1 e não recebe nenhuma resposta, é provável que o IMDSv2 seja necessário. Para verificar se o IMDSv2 é necessário, selecione a instância para visualizar seus detalhes. O valor de **IMDSv2** indica **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.

**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.

**Suporte a IPv6**  
Para recuperar metadados da instância usando um endereço IPv6, certifique-se de habilitar e usar o endereço IPv6 do IMDS `[fd00:ec2::254]`, em vez do endereço IPv4 `169.254.169.254`. A instância deve ser uma [instância baseada em Nitro](instance-types.md#instance-hypervisor-type) executada em uma [sub-rede com suporte para IPv6](https://docs.aws.amazon.com/vpc/latest/userguide/configure-subnets.html#subnet-ip-address-range).

**(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](ami-create-win-sysprep.md).

**Em um ambiente de contêiner, considere reconfigurar ou aumentar o limite de saltos para 2.**  
Os SDKs da AWS usam chamadas IMDSv2 por padrão. Caso a chamada do IMDSv2 não receba resposta, alguns AWS SDKs tentam realizar a chamada novamente e, se ainda não tiver sucesso, usam o IMDSv1. Isso pode resultar em um atraso, especialmente em um ambiente de contêiner. Para os AWS SDKs que *precisam* do IMDSv2, se o limite de saltos for 1 em um ambiente de contêiner, a chamada pode não receber nenhuma resposta, pois acessar o contêiner é considerado um salto de rede adicional.  
Para mitigar esses problemas em um ambiente de contêiner, considere alterar a configuração para transferir as configurações (como a Região da AWS) diretamente para o contêiner, ou considere aumentar o limite de saltos para 2. Para obter informações sobre o impacto do limite de saltos, consulte [Add defense in depth against open firewalls, reverse proxies, and SSRF vulnerabilities with enhancements to the EC2 Instance Metadata Service](https://aws.amazon.com/blogs/security/defense-in-depth-open-firewalls-reverse-proxies-ssrf-vulnerabilities-ec2-instance-metadata-service/). Para obter informações sobre como alterar o limite de saltos, consulte [Alterar o limite de salto de resposta PUT](configuring-IMDS-existing-instances.md#modify-PUT-response-hop-limit).

**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](using-instance-addressing.md#link-local-addresses). Esse limite inclui o agregado de [consultas ao DNS do Route 53 Resolver](https://docs.aws.amazon.com/vpc/latest/userguide/AmazonDNS-concepts.html#vpc-dns-limits), solicitações do Serviço de metadados de instância (IMDS), solicitações do [Amazon Time Service Network Time Protocol (NTP)](set-time.md) e solicitações do [Windows Licensing Service (para instâncias baseadas no Microsoft Windows)](https://aws.amazon.com/windows/resources/licensing/). 

**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](https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration-changes.html#cliv2-migration-binaryparam) 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 para 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)\$14.
+ 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
<a name="instancedata-inside-access"></a>

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, consult [Categorias de metadados da instância](ec2-instance-metadata.md#instancedata-data-categories).

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 obter mais informações, consulte [Endereços locais de link](using-instance-addressing.md#link-local-addresses).

**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](instance-identity-documents.md).

------
#### [ 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](instance-types.md#instance-hypervisor-type) 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
<a name="query-IMDS-existing-instances"></a>

É possível consultar as opções de metadados da instância para instâncias existentes.

------
#### [ Console ]

**Para consultar as opções de metadados da instância para uma instância existente**

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

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

1. Selecione a instância e confira os seguintes campos:
   + **IMDSv2**: o valor é **Obrigatório** ou **Opcional**.
   + **Permitir etiquetas em metadados de instâncias**: o valor é **Habilitado** ou **Desabilitado**.

1. Com sua instância selecionada, escolha **Ações**, **Configurações da instância**, **Modificar opções de metadados da instância**.

   A caixa de diálogo mostra se o serviço de metadados da instância está habilitado ou desabilitado para a instância selecionada.

------
#### [ AWS CLI ]

**Para consultar as opções de metadados da instância para uma instância existente**  
Use o comando [describe-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html).

```
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](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2Instance.html).

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

------

## Respostas e mensagens de erro
<a name="instance-metadata-returns"></a>

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).

Se uma solicitação para o IMDSv1 não receber resposta, é provável que o IMDSv2 seja necessário.

Para solicitações realizadas usando o IMDSv2, 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.
+ `404 - Not Found`: o recurso não está disponível ou não existe esse recurso.
+ `503`: a solicitação não pôde ser concluída. Repetir a solicitação.

Se o IMDS retornar um erro, o **curl** imprimirá a mensagem de erro na saída e retornará um código de status de êxito. A mensagem de erro é armazenada na variável `TOKEN`, o que faz com que os comandos de **curl** que usam o token falhem. Se você chamar o **curl** com a opção **-f**, ele retornará um código de status de erro no caso de um erro no servidor de HTTP. Se você habilitar o tratamento de erros, o shell poderá capturar o erro e interromper o script.

## Limitação de consulta
<a name="instancedata-throttling"></a>

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](instance-metadata-security-credentials.md).

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

# Use o serviço de metadados de instância para acessar metadados de instância
<a name="configuring-instance-metadata-service"></a>

É 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](#instance-metadata-retrieval-examples).
+ 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](#instance-metadata-retrieval-examples-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 a aceitar somente chamadas IMDSv2, o que fará com que as chamadas IMDSv1 falhem. 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](configuring-instance-metadata-options.md).

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](https://aws.amazon.com/blogs/security/defense-in-depth-open-firewalls-reverse-proxies-ssrf-vulnerabilities-ec2-instance-metadata-service/).

**Topics**
+ [

## Como Serviço de metadados da instância versão 2 funciona
](#instance-metadata-v2-how-it-works)
+ [

## Usar um AWS SDK compatível
](#use-a-supported-sdk-version-for-imdsv2)
+ [

## Exemplos para IMDSv2
](#instance-metadata-retrieval-examples)
+ [

## Exemplos para IMDSv1
](#instance-metadata-retrieval-examples-imdsv1)

## Como Serviço de metadados da instância versão 2 funciona
<a name="instance-metadata-v2-how-it-works"></a>

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](instance-types.md#instance-hypervisor-type) em uma [sub-rede compatível com IPv6](https://docs.aws.amazon.com/vpc/latest/userguide/configure-subnets.html#subnet-ip-address-range) (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) ou `token` (para as instâncias do Windows)
+ Solicita os itens de metadados de nível superior usando o token

### Exemplo do Linux
<a name="how-imdsv2-works-example-linux"></a>

É 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
```

### Exemplo do Windows
<a name="how-imdsv2-works-example-windows"></a>

```
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:

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.

1. Inclua o token em todas as solicitações `GET` para o IMDS. 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`.
   + 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, 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 `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 IMDS e pelos limites de controle de utilização. Para obter mais informações, consulte [Limitação de consulta](instancedata-data-retrieval.md#instancedata-throttling).

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](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-options.html) da AWS CLI. 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 [Modificar as opções de metadados de instância para as instâncias existentes](configuring-IMDS-existing-instances.md).

## Usar um AWS SDK compatível
<a name="use-a-supported-sdk-version-for-imdsv2"></a>

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](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html) 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](https://github.com/aws/aws-cli): 1.16.289
+ [AWS Tools for Windows PowerShell](https://github.com/aws/aws-tools-for-powershell): 4.0.1.0
+ [AWS SDK para .NET](https://github.com/aws/aws-sdk-net): 3.3.634.1
+ [AWS SDK para C\$1\$1](https://github.com/aws/aws-sdk-cpp): 1.7.229
+ [AWS SDK para Go](https://github.com/aws/aws-sdk-go): 1.25.38
+ [AWS SDK para Go v2](https://github.com/aws/aws-sdk-go-v2) – 0.19.0
+ [AWS SDK para Java](https://github.com/aws/aws-sdk-java): 1.11.678
+ [AWS SDK for Java 2.x](https://github.com/aws/aws-sdk-java-v2): 2.10.21
+ [AWS SDK para JavaScript em Node.js](https://github.com/aws/aws-sdk-js) – 2.722.0
+ [AWS SDK para Kotlin](https://github.com/awslabs/aws-sdk-kotlin) – 1.1.4
+ [AWS SDK para PHP](https://github.com/aws/aws-sdk-php): 3.147.7
+ [AWS SDK para Python (Botocore)](https://github.com/boto/botocore) – 1.13.25
+ [AWS SDK para Python (Boto3)](https://github.com/boto/boto3): 1.12.6
+ [AWS SDK para Ruby](https://github.com/aws/aws-sdk-ruby): 3.79.0

## Exemplos para IMDSv2
<a name="instance-metadata-retrieval-examples"></a>

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.

**Topics**
+ [

### Obter as versões disponíveis dos metadados da instância
](#instance-metadata-ex-1)
+ [

### Obter itens de metadados de nível superior.
](#instance-metadata-ex-2)
+ [

### Obtenção dos valores dos itens de metadados
](#instance-metadata-ex-2a)
+ [

### Obter a lista de chaves públicas disponíveis
](#instance-metadata-ex-3)
+ [

### Mostrar os formatos nos quais a chave pública 0 está disponível
](#instance-metadata-ex-4)
+ [

### Obter a chave pública 0 (no formato de chave OpenSSH)
](#instance-metadata-ex-5)
+ [

### Obter o ID de sub-rede de uma instância
](#instance-metadata-ex-6)
+ [

### Obter as tags de instância de uma instância de uma instância
](#instance-metadata-ex-7)

### Obter as versões disponíveis dos metadados da instância
<a name="instance-metadata-ex-1"></a>

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.

------
#### [ cURL ]

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

------
#### [ PowerShell ]

```
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/
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.
<a name="instance-metadata-ex-2"></a>

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](ec2-instance-metadata.md#instancedata-data-categories).

Observe que as tags serão incluídas nessa saída somente se você tiver permitido o acesso. Para obter mais informações, consulte [Habilitar o acesso a tags em metadados da instância](work-with-tags-in-IMDS.md#allow-access-to-tags-in-IMDS).

------
#### [ cURL ]

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

------
#### [ PowerShell ]

```
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/
ami-id
ami-launch-index
ami-manifest-path
block-device-mapping/
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
<a name="instance-metadata-ex-2a"></a>

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.

------
#### [ cURL ]

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

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

```
[ec2-user ~]$ curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/local-hostname
ip-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-hostname
ec2-203-0-113-25.compute-1.amazonaws.com
```

------
#### [ PowerShell ]

```
PS C:\> Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/meta-data/ami-id
ami-0abcdef1234567890
```

```
PS C:\> Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/meta-data/reservation-id
r-0efghijk987654321
```

```
PS C:\> Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/meta-data/local-hostname
ip-10-251-50-12.ec2.internal
```

```
PS C:\> Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri 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
<a name="instance-metadata-ex-3"></a>

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

------
#### [ cURL ]

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

------
#### [ PowerShell ]

```
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/public-keys/
0=my-public-key
```

------

### Mostrar os formatos nos quais a chave pública 0 está disponível
<a name="instance-metadata-ex-4"></a>

Este exemplo mostra os formatos nos quais a chave pública 0 está disponível.

------
#### [ cURL ]

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

------
#### [ PowerShell ]

```
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/public-keys/0/openssh-key
openssh-key
```

------

### Obter a chave pública 0 (no formato de chave OpenSSH)
<a name="instance-metadata-ex-5"></a>

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

------
#### [ cURL ]

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

------
#### [ PowerShell ]

```
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/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
<a name="instance-metadata-ex-6"></a>

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

------
#### [ cURL ]

```
[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-id
subnet-be9b61d7
```

------
#### [ PowerShell ]

```
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/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
<a name="instance-metadata-ex-7"></a>

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 obter mais informações, consulte [Recuperar tags dos metadados da instância](work-with-tags-in-IMDS.md#retrieve-tags-from-IMDS).

## Exemplos para IMDSv1
<a name="instance-metadata-retrieval-examples-imdsv1"></a>

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.

**Topics**
+ [

### Obter as versões disponíveis dos metadados da instância
](#instance-metadata-ex-1-imdsv1)
+ [

### Obter itens de metadados de nível superior.
](#instance-metadata-ex-2-imdsv1)
+ [

### Obtenção dos valores dos itens de metadados
](#instance-metadata-ex-2a-imdsv1)
+ [

### Obter a lista de chaves públicas disponíveis
](#instance-metadata-ex-3-imdsv1)
+ [

### Mostrar os formatos nos quais a chave pública 0 está disponível
](#instance-metadata-ex-4-imdsv1)
+ [

### Obter a chave pública 0 (no formato de chave OpenSSH)
](#instance-metadata-ex-5-imdsv1)
+ [

### Obter o ID de sub-rede de uma instância
](#instance-metadata-ex-6-imdsv1)
+ [

### Obter as tags de instância de uma instância de uma instância
](#instance-metadata-ex-7-imdsv1)

### Obter as versões disponíveis dos metadados da instância
<a name="instance-metadata-ex-1-imdsv1"></a>

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.

------
#### [ cURL ]

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

------
#### [ PowerShell ]

```
PS C:\> Invoke-RestMethod -uri 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.
<a name="instance-metadata-ex-2-imdsv1"></a>

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](ec2-instance-metadata.md#instancedata-data-categories).

Observe que as tags serão incluídas nessa saída somente se você tiver permitido o acesso. Para obter mais informações, consulte [Habilitar o acesso a tags em metadados da instância](work-with-tags-in-IMDS.md#allow-access-to-tags-in-IMDS).

------
#### [ cURL ]

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

------
#### [ PowerShell ]

```
PS C:\> Invoke-RestMethod -uri http://169.254.169.254/latest/meta-data/    
ami-id
ami-launch-index
ami-manifest-path
block-device-mapping/
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
<a name="instance-metadata-ex-2a-imdsv1"></a>

Esses exemplos obtêm os valores de alguns dos itens de metadados de nível superior obtidos no exemplo anterior.

------
#### [ cURL ]

```
[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/ami-id
ami-0abcdef1234567890
```

```
[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/reservation-id
r-0efghijk987654321
```

```
[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/local-hostname
ip-10-251-50-12.ec2.internal
```

```
[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/public-hostname
ec2-203-0-113-25.compute-1.amazonaws.com
```

------
#### [ PowerShell ]

```
PS C:\> Invoke-RestMethod -uri http://169.254.169.254/latest/meta-data/ami-id
ami-0abcdef1234567890
```

```
PS C:\> Invoke-RestMethod -uri http://169.254.169.254/latest/meta-data/reservation-id
r-0efghijk987654321
```

```
PS C:\> Invoke-RestMethod -uri http://169.254.169.254/latest/meta-data/local-hostname
ip-10-251-50-12.ec2.internal
```

```
PS C:\> Invoke-RestMethod -uri 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
<a name="instance-metadata-ex-3-imdsv1"></a>

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

------
#### [ cURL ]

```
[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/public-keys/
0=my-public-key
```

------
#### [ PowerShell ]

```
PS C:\> Invoke-RestMethod -uri 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
<a name="instance-metadata-ex-4-imdsv1"></a>

Este exemplo mostra os formatos nos quais a chave pública 0 está disponível.

------
#### [ cURL ]

```
[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/public-keys/0/
openssh-key
```

------
#### [ PowerShell ]

```
PS C:\> Invoke-RestMethod -uri http://169.254.169.254/latest/meta-data/public-keys/0/openssh-key
openssh-key
```

------

### Obter a chave pública 0 (no formato de chave OpenSSH)
<a name="instance-metadata-ex-5-imdsv1"></a>

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

------
#### [ cURL ]

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

------
#### [ PowerShell ]

```
PS C:\> Invoke-RestMethod -uri 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
<a name="instance-metadata-ex-6-imdsv1"></a>

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

------
#### [ cURL ]

```
[ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/network/interfaces/macs/02:29:96:8f:6a:2d/subnet-id
subnet-be9b61d7
```

------
#### [ PowerShell ]

```
PS C:\> Invoke-RestMethod -uri 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
<a name="instance-metadata-ex-7-imdsv1"></a>

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 obter mais informações, consulte [Recuperar tags dos metadados da instância](work-with-tags-in-IMDS.md#retrieve-tags-from-IMDS).

# Transição para usar o Serviço de metadados da instância versão 2
<a name="instance-metadata-transition-to-version-2"></a>

Se você deseja configurar suas instâncias para aceitar somente chamadas da versão 2 do serviço de metadados de instância (IMDSv2), recomendamos que use as ferramentas e o caminho de transição apresentados a seguir.

**Topics**
+ [

## Ferramentas para fazer a transição para o IMDSv2
](#tools-for-transitioning-to-imdsv2)
+ [

## Caminho recomendado para exigir IMDSv2
](#recommended-path-for-requiring-imdsv2)

## Ferramentas para fazer a transição para o IMDSv2
<a name="tools-for-transitioning-to-imdsv2"></a>

As ferramentas a seguir podem ajudar a identificar, monitorar e gerenciar a transição do seu software do IMDSv1 para o IMDSv2. Para obter instruções sobre como usar as ferramentas, consulte [Caminho recomendado para exigir IMDSv2](#recommended-path-for-requiring-imdsv2).

**AWS Software da**  
As versões mais recentes da AWS CLI e dos AWS SDKs são compatíveis com o IMDSv2. Para usar o IMDSv2, atualize as instâncias do EC2 para usar as versões mais recentes. Para obter as versões mínimas do AWS SDK compatíveis com IMDSv2, consulte [Usar um AWS SDK compatível](configuring-instance-metadata-service.md#use-a-supported-sdk-version-for-imdsv2).  
Todos os pacotes de software Amazon Linux 2 e Amazon Linux 2023 são compatíveis com o IMDSv2. O Amazon Linux 2023 desabilita o IMDSv1 por padrão.

**IMDS Packet Analyzer**  
O IMDS Packet Analyzer é uma ferramenta de código aberto que identifica e registra as chamadas IMDSv1 durante a fase de inicialização e as operações de runtime da sua instância. Ao analisar esses registros, você pode identificar com precisão o software que faz chamadas do IMDSv1 em suas instâncias e determinar o que precisa ser atualizado para oferecer suporte ao IMDSv2 somente em suas instâncias. É possível executar o IMDS Packet Analyzer em uma linha de comando ou instalá-lo como um serviço. Para obter mais informações, consulte [AWS ImdsPacketAnalyzer](https://github.com/aws/aws-imds-packet-analyzer) no *GitHub*.

**CloudWatch**  
O CloudWatch fornece as duas métricas a seguir para monitorar suas instâncias:  
`MetadataNoToken` – O IMDSv2 usa sessões baseadas em token, enquanto o IMDSv1 não o faz. A métrica `MetadataNoToken` rastreia o número de chamadas para o Serviço de metadados de instância (IMDS) que estão usando o IMDSv1. Rastreando essa métrica até zero, é possível determinar se e quando todo o software foi atualizado para usar o IMDSv2.  
`MetadataNoTokenRejected` – Após desabilitar o IMDSv1, é possível usar a métrica do `MetadataNoTokenRejected` para rastrear o número de vezes que uma chamada do IMDSv1 foi tentada e rejeitada. Ao rastrear essa métrica, você pode verificar se o software precisa ser atualizado para usar o IMDSv2.  
Para cada instância do EC2, essas métricas são mutuamente exclusivas. Quando o IMDSv1 está habilitado (`httpTokens = optional`), só emite `MetadataNoToken`. Quando o IMDSv1 está desabilitado (`httpTokens = required`), só emite `MetadataNoTokenRejected`. Para saber quando usar essas métricas, consulte [Caminho recomendado para exigir IMDSv2](#recommended-path-for-requiring-imdsv2).  
Para obter mais informações, consulte [Métricas de instância](viewing_metrics_with_cloudwatch.md#ec2-cloudwatch-metrics).

**Inicie APIs**  
**Novas instâncias:** use a API [RunInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RunInstances.html) para iniciar novas instâncias que exijam o uso do IMDSv2. Para obter mais informações, consulte [Configurar opções de metadados da instância para novas instâncias](configuring-IMDS-new-instances.md).  
**Instâncias existentes:** use a API [ModifyInstanceMetadataOptions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyInstanceMetadataOptions.html) para exigir o uso do IMDSv2 nas instâncias existentes. Para obter mais informações, consulte [Modificar as opções de metadados de instância para as instâncias existentes](configuring-IMDS-existing-instances.md).  
**Novas instâncias iniciadas pelos grupos do Auto Scaling:** para exigir o uso do IMDSv2 em todas as novas instâncias executadas por grupos do Auto Scaling, seus grupos do Auto Scaling podem usar um modelo de execução ou uma configuração de execução. Quando você [cria um modelo de execução](https://docs.aws.amazon.com/cli/latest/reference/ec2/create-launch-template.html) ou [cria uma configuração de execução](https://docs.aws.amazon.com/cli/latest/reference/autoscaling/create-launch-configuration.html), é necessário configurar os parâmetros de `MetadataOptions` para exigir o uso do IMDSv2. O grupo do Auto Scaling inicia novas instâncias usando o novo modelo de execução ou configuração de execução, mas as instâncias existentes não serão afetadas.   
**Instâncias existentes em um grupo do Auto Scaling:** use a API [ModifyInstanceMetadataOptions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyInstanceMetadataOptions.html) para exigir o uso do IMDSv2 em instâncias existentes, ou encerrar 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 ou na configuração de execução.

**AMIs**  
As AMIs configuradas com o parâmetro `ImdsSupport` definido como `v2.0` iniciarão instâncias que exigem o IMDSv2 por padrão. O Amazon Linux 2023 está configurado com `ImdsSupport = v2.0`.  
**Novas AMIs:** use o comando da CLI [register-image](https://docs.aws.amazon.com/cli/latest/reference/ec2/register-image.html) para definir o parâmetro `ImdsSupport` como `v2.0` ao criar uma nova AMI.  
**AMIs existentes:** use o comando da CLI [modify-image-attribute](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-image-attribute.html) para definir o parâmetro `ImdsSupport` como `v2.0` ao modificar uma AMI existente.  
Para obter mais informações, consulte [Configurar a AMI](configuring-IMDS-new-instances.md#configure-IMDS-new-instances-ami-configuration).

**Controles no nível de conta**  
Você pode configurar valores padrão para todas as opções de metadados da instância no nível da conta. Os valores padrão são aplicados automaticamente quando você executa uma instância. Para obter mais informações, consulte [Definir o IMDSv2 como o padrão para a conta](configuring-IMDS-new-instances.md#set-imdsv2-account-defaults).  
Você também pode impor a exigência de usar o IMDSv2 no nível da conta. Quando a imposição do IMDSv2 está habilitada:  
+ **Novas instâncias:** as instâncias configuradas para serem executadas com o IMDSv1 habilitado falharão na inicialização
+ **Instâncias existentes com o IMDSv1 desativado:** as tentativas de habilitar o IMDSv1 em instâncias existentes serão evitadas.
+ **Instâncias existentes com o IMDSv1 habilitado:** as instâncias existentes com o IMDSv1 já habilitado não serão afetadas.
Para obter mais informações, consulte [Aplique o IMDSv2 no nível da conta](configuring-IMDS-new-instances.md#enforce-imdsv2-at-the-account-level).

**Políticas do IAM e SCPs**  
É possível usar uma política do IAM ou uma política de controle de serviços (SCP) do AWS Organizations para controlar os usuários como se segue:  
+ Não é possível iniciar uma instância usando a API [RunInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RunInstances.html), a menos que a instância esteja configurada para usar o IMDSv2.
+ Não é possível modificar uma instância em execução usando a API [ModifyInstanceMetadataOptions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyInstanceMetadataOptions.html) para reabilitar o IMDSv1.
A política do IAM ou a SCP devem conter as seguintes chaves de condição do IAM:  
+ `ec2:MetadataHttpEndpoint`
+ `ec2:MetadataHttpPutResponseHopLimit`
+ `ec2:MetadataHttpTokens`
Se um parâmetro da chamada de API ou CLI não corresponder ao estado especificado na política que contém a chave de condição, a chamada de API ou CLI falhará com uma resposta `UnauthorizedOperation`.  
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 às APIs chamadas por meio de credenciais de função do EC2, é possível usar uma chave de condição nas políticas do IAM ou nas políticas de controle de serviço (SCPs) do AWS Organizations. Especificamente, usando a chave de condição da política `ec2:RoleDelivery` com um valor `2.0` nas políticas do IAM, as chamadas de API feitas com as credenciais do perfil 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](ExamplePolicies_EC2.md#iam-example-instance-metadata). Para obter mais informações sobre SCPs, consulte [Políticas de controle de serviço](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps.html) no *Guia do usuário do AWS Organizations*.

**Políticas declarativas**  
Use políticas declarativas (um atributo do AWS Organizations) para definir centralmente as configurações padrão da conta IMDS, incluindo a aplicação do IMDSv2, em toda a sua organização. Para ver um exemplo de política, consulte a guia **Metadados da instância** na seção [Políticas declarativas compatíveis](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_declarative_syntax.html#declarative-policy-examples) no *Guia do usuário do AWS Organizations*.

## Caminho recomendado para exigir IMDSv2
<a name="recommended-path-for-requiring-imdsv2"></a>

**Topics**
+ [

### Etapa 1: identificar instâncias com IMDSv2=opcional e auditar o uso do IMDSv1
](#path-step-1)
+ [

### Etapa 2: atualizar o software para o IMDSv2
](#path-step-2)
+ [

### Etapa 3: exigir o IMDSv2 nas instâncias
](#path-step-3)
+ [

### Etapa 4: definir IMDSv2=obrigatório como padrão
](#path-step-4)
+ [

### Etapa 5: impor instâncias que exijam o IMDSv2
](#path-step-5)

### Etapa 1: identificar instâncias com IMDSv2=opcional e auditar o uso do IMDSv1
<a name="path-step-1"></a>

Para avaliar seu escopo de migração do IMDSv2, identifique as instâncias configuradas para permitir o IMDSv1 ou o IMDSv2 e audite as chamadas do IMDSv1.

1. **Identifique instâncias configuradas para permitir o IMDSv1 ou o IMDSv2:**

------
#### [ Amazon EC2 console ]

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

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

   1. Para ver somente as instâncias que estão configuradas para permitir IMDSv1 ou IMDSv2, adicione o filtro **IMDSv2 = opcional**.

   1. Como alternativa, para ver se o IMDSv2 é **opcional** ou **obrigatório** para todas as instâncias, abra a janela **Preferências** (ícone de engrenagem), ative o **IMDSv2** e escolha **Confirmar**. Isso adiciona a coluna **IMDSv2** à tabela **Instâncias**.

------
#### [ AWS CLI ]

   Use o comando [describe-instances](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ec2/modify-instance-metadata-options.html) e filtre por `metadata-options.http-tokens = optional`, da seguinte forma:

   ```
   aws ec2 describe-instances --filters "Name=metadata-options.http-tokens,Values=optional" --query "Reservations[*].Instances[*].[InstanceId]" --output text
   ```

------

1. **Audite as chamadas do IMDSv1 em cada instância:**

   Use a métrica `MetadataNoToken` do CloudWatch. Esta métrica mostra o número de chamadas IMDSv1 para o IMDS em suas instâncias. Para obter mais informações, consulte [Métricas de instância](https://docs.aws.amazon.com/en_us/AWSEC2/latest/UserGuide/viewing_metrics_with_cloudwatch.html#ec2-cloudwatch-metrics).

1. **Identifique o software em suas instâncias que fazem chamadas do IMDSv1:**

   Use o [IMDS Packet Analyzer](https://github.com/aws/aws-imds-packet-analyzer) de código aberto para identificar e registrar chamadas do IMDSv1 durante a fase de inicialização e as operações de runtime da sua instância. Use essas informações para identificar o software a atualizar e preparar suas instâncias para usar somente o IMDSv2. É possível executar o IMDS Packet Analyzer em uma linha de comando ou instalá-lo como um serviço.

### Etapa 2: atualizar o software para o IMDSv2
<a name="path-step-2"></a>

Atualize todos os SDKs, as CLIs e o software que usam credenciais de função em suas instâncias para versões compatíveis com o IMDSv2. Para obter mais informações sobre como atualizar a CLI, consulte [Instalação ou atualização para a versão mais recente da AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) no *Guia do usuário da AWS Command Line Interface*.

### Etapa 3: exigir o IMDSv2 nas instâncias
<a name="path-step-3"></a>

Depois de confirmar que não há chamadas do IMDSv1 por meio da métrica `MetadataNoToken`, configure suas instâncias existentes para exigir o IMDSv2. Além disso, configure todas as novas instâncias para exigir o IMDSv2. Em outras palavras, desative o IMDSv1 em todas as instâncias novas e existentes.

1. **Configure as instâncias existentes para exigir o IMDSv2:**

------
#### [ Amazon EC2 console ]

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

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

   1. Selecione sua instância.

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

   1. Em **IMDSv2**, escolha **Obrigatório**.

   1. Escolha **Salvar**.

------
#### [ AWS CLI ]

   Use o comando [modify-instance-metadata-options](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ec2/modify-instance-metadata-options.html) da CLI para especificar que apenas o IMDSv2 deverá ser usado. 

------
**nota**  
É possível modificar essa configuração em instâncias em execução. A alteração entra em vigor imediatamente sem a necessidade de reiniciar a instância.

   Para obter mais informações, consulte [Exigir o uso de IMDSv2](configuring-IMDS-existing-instances.md#modify-require-IMDSv2).

1. **Monitore os problemas após a desativação do IMDSv1:**

   1. Rastreie o número de vezes que uma chamada do IMDSv1 foi tentada e rejeitada com a métrica `MetadataNoTokenRejected` do CloudWatch.

   1. Se a métrica `MetadataNoTokenRejected` registrar chamadas do IMDSv1 em uma instância com problemas de software, isso indica que o software precisa ser atualizado para usar o IMDSv2.

1. **Configure novas instâncias para exigir o IMDSv2:**

------
#### [ Amazon EC2 console ]

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

   1. Siga estas etapas para [executar uma instância](ec2-launch-instance-wizard.md).

   1. Expanda **Detalhes avançados** e, para a **versão de metadados**, escolha **somente V2 (token obrigatório)**.

   1. No painel **Resumo**, analise a configuração da instância e selecione **Iniciar instância**.

      Para obter mais informações, consulte [Configurar a instância na inicialização](configuring-IMDS-new-instances.md#configure-IMDS-new-instances-instance-settings).

------
#### [ AWS CLI ]

   AWS CLI: use o comando [run-instances](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ec2/run-instances.html) e especifique que o IMDSv2 é obrigatório.

------

### Etapa 4: definir IMDSv2=obrigatório como padrão
<a name="path-step-4"></a>

Você pode definir IMDSv2=obrigatório como a configuração padrão no nível da conta ou da organização. Isso garante que todas as instâncias recém-lançadas sejam automaticamente configuradas para exigir o IMDSv2.

1. **Definir padrão por conta:**

------
#### [ Amazon EC2 console ]

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

   1. No painel de navegação, escolha **Painel**.

   1. No cartão **Atributos da conta**, em **Configurações**, escolha **Proteção e segurança de dados**.

   1. Em **Padrões do IMDS**, escolha **Gerenciar**.

   1. Em **Serviço de metadados de instância**, escolha **Habilitado**.

   1. Em **Versão de metadados**, selecione **Apenas V2 (token obrigatório)**.

   1. Selecione **Atualizar**.

------
#### [ AWS CLI ]

   Use o comando [modify-instance-metadata-defaults](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ec2/modify-instance-metadata-defaults.html) da CLI e especifique `--http-tokens required` e `--http-put-response-hop-limit 2`.

------

   Para obter mais informações, consulte [Definir o IMDSv2 como o padrão para a conta](configuring-IMDS-new-instances.md#set-imdsv2-account-defaults).

1. **Como alternativa, defina o padrão no nível da organização usando uma Política Declarativa:**

   Use uma política declarativa para definir o padrão da organização para o IMDSv2 como obrigatório. Para ver um exemplo de política, consulte a guia **Metadados da instância** na seção [Políticas declarativas compatíveis](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_declarative_syntax.html#declarative-policy-examples) no *Guia do usuário do AWS Organizations*.

### Etapa 5: impor instâncias que exijam o IMDSv2
<a name="path-step-5"></a>

Depois de confirmar que não há dependência do IMDSv1 em nenhuma de suas instâncias, recomendamos que você aplique o IMDSv2 em todas as novas instâncias.

Use uma das seguintes opções a seguir para impor o IMDSv2:

1. **Impor o IMDSv2 com uma propriedade de conta**

   Você pode impor o uso do IMDSv2 por conta para cada Região da AWS. Quando impostas, as instâncias só podem ser iniciadas se estiverem configuradas para exigir o IMDSv2. Essa imposição se aplica independentemente de como a instância ou a AMI estejam configuradas. Para obter mais informações, consulte [Aplique o IMDSv2 no nível da conta](configuring-IMDS-new-instances.md#enforce-imdsv2-at-the-account-level). Para aplicar essa configuração no nível da organização, defina uma política declarativa. Para ver um exemplo de política, consulte a guia **Metadados da instância** na seção [Políticas declarativas compatíveis](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_declarative_syntax.html#declarative-policy-examples) no *Guia do usuário do AWS Organizations*.

   Para evitar a reversão da imposição, você deve usar uma política do IAM para impedir o acesso à API [ModifyInstanceMetadataDefaults](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyInstanceMetadataDefaults.html). Para obter mais informações, consulte [Usar uma política do IAM](configuring-IMDS-new-instances.md#configure-IMDS-new-instances-iam-policy).
**nota**  
Essa configuração não altera a versão do IMDS das instâncias existentes, mas bloqueia a ativação do IMDSv1 em instâncias existentes que atualmente têm o IMDSv1 desabilitado.
**Atenção**  
Se a imposição do IMDSv2 estiver habilitada e o `httpTokens` não tiver sido definido para `required` na configuração da instância na inicialização, nas configurações da conta ou na configuração da AMI, sua execução falhará. Para obter informações sobre a solução de problemas, consulte [Falha na inicialização de uma instância habilitada para IMDSv1](troubleshooting-launch.md#launching-an-imdsv1-enabled-instance-fails).

1. **Como alternativa, impor o IMDSv2 usando as seguintes chaves de condição do IAM ou do SCP:**
   + `ec2:MetadataHttpTokens`
   + `ec2:MetadataHttpPutResponseHopLimit`
   + `ec2:MetadataHttpEndpoint`

   Essas chaves de condição controlam o uso de [RunInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RunInstances.html), da API [ModifyInstanceMetadataOptions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyInstanceMetadataOptions.html) 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](ExamplePolicies_EC2.md#iam-example-instance-metadata).

# Limitar o acesso ao serviço de metadados de instância
<a name="instance-metadata-limiting-access"></a>

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

Em [instâncias baseadas em Nitro](instance-types.md#instance-hypervisor-type), o IMDS pode ser acessado de sua própria rede quando um dispositivo de rede na VPC, como um roteador virtual, encaminha pacotes para o endereço do IMDS e a [verificação de origem e de destino](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_NAT_Instance.html#EIP_Disable_SrcDestCheck) padrão na instância está desabilitada. Para evitar que uma fonte externa à VPC acesse 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ê tiver habilitado o endpoint IPv6, o endereço IPv6 do IMDS `[fd00:ec2::254]`.

## Limitar acesso ao IMDS para instâncias do Linux
<a name="instance-metadata-limiting-access-linux"></a>

**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 IMDS 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 IMDS 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.

## Limitar acesso ao IMDS para instâncias do Windows
<a name="instance-metadata-limiting-access-windows"></a>

**Usar o firewall do Windows para limitar o acesso**

O seguinte PowerShell de exemplo usa o firewall interno do Windows para impedir que o servidor Web do Servidor de informações da Internet (com base no ID de usuário de sua instalação padrão de `NT AUTHORITY\IUSR`) 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.

```
PS C:\> $blockPrincipal = New-Object -TypeName System.Security.Principal.NTAccount ("NT AUTHORITY\IUSR")
PS C:\> $BlockPrincipalSID = $blockPrincipal.Translate([System.Security.Principal.SecurityIdentifier]).Value
PS C:\> $BlockPrincipalSDDL = "D:(A;;CC;;;$BlockPrincipalSID)"
PS C:\> New-NetFirewallRule -DisplayName "Block metadata service from IIS" -Action block -Direction out `
-Protocol TCP -RemoteAddress 169.254.169.254 -LocalUser $BlockPrincipalSDDL
```

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 aos metadados da instância por todos os processos em execução como um grupo do SO especificado na variável `blockPrincipal` (neste exemplo, o grupo `Everyone` do Windows), exceto os processos especificados em `exceptionPrincipal` (neste exemplo, um grupo chamado `trustworthy-users`). Especifique as entidades de negação e de permissão porque o Firewall do Windows, ao contrário da regra `! --uid-owner trustworthy-user` nas iptables do Linux, não fornece um mecanismo de atalho para permitir somente uma entidade específica (usuário ou grupo) negando todas as outras.

```
PS C:\> $blockPrincipal = New-Object -TypeName System.Security.Principal.NTAccount ("Everyone")
PS C:\> $BlockPrincipalSID = $blockPrincipal.Translate([System.Security.Principal.SecurityIdentifier]).Value
PS C:\> $exceptionPrincipal = New-Object -TypeName System.Security.Principal.NTAccount ("trustworthy-users")
PS C:\> $ExceptionPrincipalSID = $exceptionPrincipal.Translate([System.Security.Principal.SecurityIdentifier]).Value
PS C:\> $PrincipalSDDL = "O:LSD:(D;;CC;;;$ExceptionPrincipalSID)(A;;CC;;;$BlockPrincipalSID)"
PS C:\> New-NetFirewallRule -DisplayName "Block metadata service for $($blockPrincipal.Value), exception: $($exceptionPrincipal.Value)" -Action block -Direction out `
-Protocol TCP -RemoteAddress 169.254.169.254 -LocalUser $PrincipalSDDL
```

**nota**  
Para usar regras de firewall local, você precisa adaptar os comandos do exemplo anterior para se ajustarem a suas necessidades. 

**Usar regras de netsh para limitar o acesso**

É possível considerar o bloqueio de todos os softwares usando regras de `netsh`, mas essas regras são muito menos flexíveis.

```
C:\> netsh advfirewall firewall add rule name="Block metadata service altogether" dir=out protocol=TCP remoteip=169.254.169.254 action=block
```

**nota**  
Para usar regras de firewall local, você precisa adaptar os comandos do exemplo anterior para se ajustarem a suas necessidades. 
`netsh`As regras de devem ser definidas em um prompt de comando elevado e não podem ser definidas para negar ou permitir principais específicos.

# Configurar as opções de serviço de metadados de instância
<a name="configuring-instance-metadata-options"></a>

O serviço de metadados de instância (IMDS) é executado localmente em cada instância do EC2. As *opções de metadados de instância* se referem a um conjunto de configurações que controlam a acessibilidade e o comportamento do IMDS em uma instância do EC2.

É possível configurar as seguintes opções de metadados da instância em cada instância:

**Serviço de metadados de instância (IMDS)**: `enabled` \$1 `disabled`  
É possível habilitar ou desabilitar o IMDS em uma instância. Quando desabilitado, os metadados da instância não poderão ser acessados por você ou por nenhum outro código.  
O IMDS tem dois endpoints em uma instância: IPv4 (`169.254.169.254`) e IPv6 (`[fd00:ec2::254]`). Quando você habilita o IMDS, o endpoint IPv4 é habilitado automaticamente. Se quiser habilitar o endpoint IPv6, você precisará fazer isso explicitamente.

**Endpoint IPv6 do IMDS**: `enabled` \$1 `disabled`  
É possível habilitar explicitamente o endpoint IPv6 do IMDS em uma instância. Quando o endpoint IPv6 estiver habilitado, o endpoint IPv4 permanecerá habilitado. O endpoint IPv6 só é compatível com [instâncias baseadas em Nitro](instance-types.md#instance-hypervisor-type) em [sub-redes compatíveis com IPv6](https://docs.aws.amazon.com/vpc/latest/userguide/configure-subnets.html#subnet-ip-address-range) (pilha dupla ou IPv6 apenas).

**Versão de metadados**: `IMDSv1 or IMDSv2 (token optional)` \$1 `IMDSv2 only (token required)`  
Ao solicitar metadados de instância, as chamadas do IMDSv2 exigem um token. As chamadas do IMDSv1 não exigem um token. É possível configurar uma instância para permitir chamadas do IMDSv1 ou do IMDSv2 (quando um token for opcional) ou para permitir somente chamadas do IMDSv2 (quando um token for obrigatório).

**Limite de salto de resposta de metadados**: `1`–`64`  
O limite de saltos é o número de saltos de rede que a resposta PUT pode fazer. É possível definir o limite de saltos para um mínimo de `1` e um máximo de `64`. Em um ambiente de contêiner, um limite de salto igual a `1` pode gerar problemas. Para obter informações sobre como mitigar esses problemas, consulte as informações sobre ambientes de contêiner em [Considerações sobre o acesso aos metadados da instância](instancedata-data-retrieval.md#imds-considerations).

**Acesso a tags nos metadados da instância**: `enabled` \$1 `disabled`  
É possível habilitar ou desabilitar o acesso às tags de uma instância nos metadados de uma instância. Para obter mais informações, consulte [Visualizar tags para as instâncias do EC2 usando os metadados de instância](work-with-tags-in-IMDS.md).

Para ver a configuração atual de uma instância, consulte [Consultar as opções de metadados da instância para as instâncias existentes](instancedata-data-retrieval.md#query-IMDS-existing-instances).

## Onde configurar as opções de metadados da instância
<a name="where-to-configure-instance-metadata-options"></a>

É possível configurar as opções de metadados da instância em diferentes níveis, da seguinte forma:
+ **Conta**: você pode definir valores padrão para as opções de metadados da instância por conta para cada Região da AWS. Quando uma instância for executada, as opções de metadados da instância serão definidas automaticamente para os valores na conta. É possível alterar esses valores na execução. Os valores padrão por conta não afetam as instâncias existentes.
+ **AMI**: ao registrar ou modificar uma AMI, é possível definir o parâmetro `imds-support` como `v2.0`. Quando uma instância for executada com essa AMI, a versão dos metadados da instância será definida automaticamente como IMDSv2 e o limite de saltos será definido como 2.
+ **Instância**: você pode alterar todas as opções de metadados de uma instância na execução, substituindo as configurações padrão. Também é possível alterar as opções de metadados da instância após a execução em uma instância em execução ou parada. Observe que as alterações poderão sofrer restrições de uma política do IAM ou SCP.

Para obter mais informações, consulte [Configurar opções de metadados da instância para novas instâncias](configuring-IMDS-new-instances.md) e [Modificar as opções de metadados de instância para as instâncias existentes](configuring-IMDS-existing-instances.md).

## Ordem de precedência das opções de metadados da instância
<a name="instance-metadata-options-order-of-precedence"></a>

O valor de cada opção de metadados da instância é determinado na inicialização da instância, seguindo uma ordem hierárquica de precedência. A hierarquia, com a maior precedência no topo, é a seguinte:
+ **Precedência 1: configuração da instância na execução**: é possível especificar os valores no modelo de execução ou na configuração da instância. Todos os valores especificados aqui substituirão os valores especificados por conta ou na AMI.
+ **Precedência 2: configurações da conta**: se não houver um valor especificado na inicialização da instância, ele será determinado pelas configurações por conta (que são definidas para cada Região da AWS). As configurações por conta incluem um valor para cada opção de metadados ou não indicam nenhuma preferência.
+ **Precedência 3: configuração da AMI**: se não houver um valor especificado na execução da instância ou por conta, ele será determinado pela configuração da AMI. Isso se aplica somente a `HttpTokens` e `HttpPutResponseHopLimit`.

Cada opção de metadados é avaliada separadamente. É possível configurar a instância com uma combinação de configuração direta da instância, padrões por conta e a configuração da AMI.

A menos que as alterações sejam restringidas por uma política do IAM ou SCP, será possível alterar o valor de qualquer opção de metadados após a execução em uma instância em execução ou parada.

**nota**  
A configuração de imposição do IMDSv2 no nível da conta é avaliada depois que a ordem de precedência determina as configurações do IMDS da instância. Quando a imposição do IMDSv2 estiver habilitada, as instâncias habilitadas com o IMDSv1 falharão. Para ter mais informações sobre imposições, consulte [Aplique o IMDSv2 no nível da conta](configuring-IMDS-new-instances.md#enforce-imdsv2-at-the-account-level).

**Atenção**  
Se a imposição do IMDSv2 estiver habilitada e o `httpTokens` não tiver sido definido como `required` na configuração da instância na inicialização, nas configurações da conta ou na configuração da AMI, sua execução falhará.

**Exemplo 1: determinar os valores para opções de metadados**

Neste exemplo, uma instância do EC2 é iniciada em uma região na qual `HttpPutResponseHopLimit` está definido como `1` para a conta. A AMI especificada tem `ImdsSupport` definido como `v2.0`. Nenhuma opção de metadados é especificada diretamente na instância na execução. A instância é executada com as seguintes opções de metadados:

```
"MetadataOptions": {
    ...
    "HttpTokens": "required",
    "HttpPutResponseHopLimit": 1,
    ...
```

Esses valores foram determinados da seguinte manneira:
+ **Nenhuma opção de metadados especificada na execução:** durante a execução da instância, não se forneceu valores específicos para as opções de metadados nos parâmetros de execução da instância nem no modelo de execução.
+ **As configurações da conta têm a próxima precedência:** na ausência da definição de valores específicos na execução, as configurações por conta na região terão precedência. Isso significa que os valores padrão configurados por conta serão aplicados. Nesse caso, o `HttpPutResponseHopLimit` foi definido como `1`.
+ **As configurações da AMI têm a última precedência:** na ausência de um valor específico definido na inicialização ou no nível da conta para `HttpTokens` (a versão de metadados da instância), a configuração da AMI é aplicada. Nesse caso, a configuração da AMI `ImdsSupport: v2.0` determinou que `HttpTokens` estava definido como `required`. Observe que, embora a configuração da AMI `ImdsSupport: v2.0` tenha sido projetada para definir `HttpPutResponseHopLimit: 2`, ela foi substituída pela configuração no nível da conta `HttpPutResponseHopLimit: 1`, que tem maior precedência.

**Exemplo 2: determinar os valores para opções de metadados**

Neste exemplo, a instância do EC2 é executada com as mesmas configurações do Exemplo 1 anterior, mas com a configuração `HttpTokens` definida como `optional` diretamente na instância na execução. A instância é executada com as seguintes opções de metadados:

```
"MetadataOptions": {
    ...
    "HttpTokens": "optional",
    "HttpPutResponseHopLimit": 1,
    ...
```

O valor de `HttpPutResponseHopLimit` é determinado da mesma forma que no Exemplo 1. No entanto, o valor de `HttpTokens` é determinado da seguinte forma: as opções de metadados configuradas na instância na execução terão precedência. Embora a AMI tenha sido configurada com `ImdsSupport: v2.0` (em outras palavras, `HttpTokens` esteja definido como `required`), o valor especificado na instância na execução (`HttpTokens` definido como `optional`) teve precedência.

**Exemplo 3: determinar os valores para opções de metadados com o HttpTokensEnforced habilitado**

Neste exemplo, a conta na região têm `HttpTokens = required` e `HttpTokensEnforced = enabled`.

Considere as seguintes tentativas de inicialização das instâncias do EC2:
+ Tentativa de inicialização com `HttpTokens` definido como `optional`: a inicialização falha porque a imposição no nível da conta está habilitada (`HttpTokensEnforced = enabled`) e o parâmetro de inicialização tem precedência sobre o padrão da conta.
+ Tentativa de inicialização com `HttpTokens` definido como `required`: a inicialização é bem-sucedida porque está em conformidade com a imposição em nível de conta. 
+ Tentativa de inicialização sem valor de `HttpTokens` especificado: a inicialização é bem-sucedida porque o valor padrão é `required` baseado nas configurações da conta. 

### Definir a versão de metadados da instância
<a name="metadata-version-order-of-precedence"></a>

**Quando uma instância é iniciada, o valor da *versão de metadados* da instância é **IMDSv1 ou IMDSv2 (token opcional)** (`httpTokens=optional`) ou somente IMDSv2 (token obrigatório) (`httpTokens=required`)**.

Na execução da instância, é possível especificar manualmente o valor da versão de metadados ou usar o valor padrão. Se você especificar o valor manualmente, ele substituirá todos os padrões. Se você optar por não especificar o valor manualmente, ele será determinado por uma combinação de configurações padrão.

O fluxograma apresentado a seguir mostra como a versão dos metadados de uma instância na execução é determinada pelas configurações nos diferentes níveis da configuração e por onde a fiscalização é avaliada. A tabela a seguir fornece as configurações específicas em cada nível.

![\[Um fluxograma que mostra os pontos de avaliação da versão de metadados da instância e da aplicação do IMDSv2.\]](http://docs.aws.amazon.com/pt_br/AWSEC2/latest/UserGuide/images/imds-defaults-launch-flow.png)


A tabela mostra como a versão dos metadados de uma instância na execução (indicada pela **Configuração resultante da instância** na coluna 4) é determinada pelas configurações nos diferentes níveis de configuração. A ordem de precedência é da esquerda para a direita, com a primeira coluna tendo a maior precedência, da seguinte maneira:
+ Coluna 1: **Parâmetro de inicialização**: representa a configuração na instância que você especifica manualmente na execução.
+ Coluna 2: **Padrão por conta**: representa a configuração da conta.
+ Coluna 3: **Padrão da AMI**: representa a configuração na AMI.


| Parâmetro de execução | Padrão por conta | Padrão da AMI | Configuração resultante da instância | 
| --- | --- | --- | --- | 
| Somente V2 (requer token) | Sem preferência | Somente V2 | Somente V2 | 
| Somente V2 (requer token) | Somente V2 | Somente V2 | Somente V2 | 
| Somente V2 (requer token) | V1 ou V2 | Somente V2 | Somente V2 | 
| V1 ou V2 (token opcional) | Sem preferência | Somente V2 | V1 ou V2 | 
| V1 ou V2 (token opcional) | Somente V2 | Somente V2 | V1 ou V2 | 
| V1 ou V2 (token opcional) | V1 ou V2 | Somente V2 | V1 ou V2 | 
| Não definido | Sem preferência | Somente V2 | Somente V2 | 
| Não definido | Somente V2 | Somente V2 | Somente V2 | 
| Não definido | V1 ou V2 | Somente V2 | V1 ou V2 | 
| Somente V2 (requer token) | Sem preferência | nulo | Somente V2 | 
| Somente V2 (requer token) | Somente V2 | nulo | Somente V2 | 
| Somente V2 (requer token) | V1 ou V2 | nulo | Somente V2 | 
| V1 ou V2 (token opcional) | Sem preferência | nulo | V1 ou V2 | 
| V1 ou V2 (token opcional) | Somente V2 | nulo | V1 ou V2 | 
| V1 ou V2 (token opcional) | V1 ou V2 | nulo | V1 ou V2 | 
| Não definido | Sem preferência | nulo | V1 ou V2 | 
| Não definido | Somente V2 | nulo | Somente V2 | 
| Não definido | V1 ou V2 | nulo | V1 ou V2 | 

## Usar chaves de condição do IAM para restringir as opções de metadados da instância
<a name="iam-condition-keys-and-imds"></a>

É possível usar chaves de condição do IAM em uma política do IAM ou SCP da seguinte maneira:
+ 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

**Topics**
+ [

## Onde configurar as opções de metadados da instância
](#where-to-configure-instance-metadata-options)
+ [

## Ordem de precedência das opções de metadados da instância
](#instance-metadata-options-order-of-precedence)
+ [

## Usar chaves de condição do IAM para restringir as opções de metadados da instância
](#iam-condition-keys-and-imds)
+ [

# Configurar opções de metadados da instância para novas instâncias
](configuring-IMDS-new-instances.md)
+ [

# Modificar as opções de metadados de instância para as instâncias existentes
](configuring-IMDS-existing-instances.md)

**nota**  
Proceda com cautela e conduza testes cuidadosos antes de fazer qualquer alteração. Anote o seguinte:  
Se você exigir o uso do IMDSv2, as aplicações 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, as aplicações ou agentes que contam com o acesso aos metadados da instância para funcionarem falharão.
Para IMDSv2, use `/latest/api/token` ao recuperar o token.
(Somente para o Windows) Se a versão do PowerShell for uma versão anterior à 4.0, você deverá [atualizar para o Windows Management Framework 4.0](https://devblogs.microsoft.com/powershell/windows-management-framework-wmf-4-0-update-now-available-for-windows-server-2012-windows-server-2008-r2-sp1-and-windows-7-sp1/) para exigir o uso do IMDSv2.

# Configurar opções de metadados da instância para novas instâncias
<a name="configuring-IMDS-new-instances"></a>

É possível configurar as opções de metadados de instância a seguir em cada instância.

**Topics**
+ [

## Exigir o uso de IMDSv2
](#configure-IMDS-new-instances)
+ [

## Habilitar os endpoints IPv4 e IPv6 do IMDS
](#configure-IMDS-new-instances-ipv4-ipv6-endpoints)
+ [

## Desativar o acesso aos metadados da instância
](#configure-IMDS-new-instances--turn-off-instance-metadata)
+ [

## Permitir acesso a tags em metadados de instância
](#configure-IMDS-new-instances-tags-in-instance-metadata)

**nota**  
A configuração dessa opções é definida no nível da conta, diretamente na conta ou usando uma política declarativa. Elas devem ser configuradas em cada Região da AWS onde você quiser configurar as opções de metadados da instância. O uso de uma política declarativa permite que você aplique as configurações em várias regiões simultaneamente, bem como em várias contas simultaneamente. Quando uma política declarativa está em uso, você não pode modificar as configurações diretamente em uma conta. Este tópico descreve como ajustar as configurações diretamente em uma conta. Para obter informações sobre o uso de políticas declarativas, consulte [Políticas declarativas](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_declarative.html) no *Guia do usuário do AWS Organizations*.

## Exigir o uso de IMDSv2
<a name="configure-IMDS-new-instances"></a>

É possível utilizar um dos métodos a seguir para exigir o uso do IMDSv2 nas novas instâncias.

**Topics**
+ [

### Definir o IMDSv2 como o padrão para a conta
](#set-imdsv2-account-defaults)
+ [

### Aplique o IMDSv2 no nível da conta
](#enforce-imdsv2-at-the-account-level)
+ [

### Configurar a instância na inicialização
](#configure-IMDS-new-instances-instance-settings)
+ [

### Configurar a AMI
](#configure-IMDS-new-instances-ami-configuration)
+ [

### Usar uma política do IAM
](#configure-IMDS-new-instances-iam-policy)

### Definir o IMDSv2 como o padrão para a conta
<a name="set-imdsv2-account-defaults"></a>

É possível definir a versão padrão do serviço de metadados de instância (IMDS) em nível de conta para cada Região da AWS. Isso significa que, quando uma *nova* instância é executada, a versão dos metadados da instância é definida automaticamente para padrão do nível de conta. No entanto, você pode substituir manualmente o valor na execução ou após a execução. Para obter mais informações sobre como as configurações em nível de conta e as substituições manuais afetam uma instância, consulte [Ordem de precedência das opções de metadados da instância](configuring-instance-metadata-options.md#instance-metadata-options-order-of-precedence).

**nota**  
Definir o padrão no nível de conta não redefine as instâncias *existentes*. Por exemplo, se você definir o padrão no nível de conta como IMDSv2, as instâncias existentes definidas como IMDSv1 não serão afetadas. Se desejar alterar o valor nas instâncias existentes, altere manualmente o valor nas próprias instâncias.

É possível definir o padrão da conta para a versão dos metadados de instância como IMDSv2 para que todas as *novas* instâncias na conta sejam iniciadas com o IMDSv2 obrigatório. Nesse caso, o IMDSv1 será desabilitado. Com esse padrão da conta, quando você executar uma instância, os valores padrão da instância serão os seguintes:
+ Console: a **Versão de metadados** estará definida como **Somente V2 (requer token)** e o **Limite de salto de resposta de metadados** como **2**.
+ AWS CLI: `HttpTokens` estará definido como `required` e `HttpPutResponseHopLimit` como `2`. 

**nota**  
Antes de definir a conta padrão para IMDSv2, certifique-se de que suas instâncias não dependam do IMDSv1. Para obter mais informações, consulte [Caminho recomendado para exigir IMDSv2](instance-metadata-transition-to-version-2.md#recommended-path-for-requiring-imdsv2).

------
#### [ Console ]

**Para definir o IMDSv2 como padrão para a conta da região especificada**

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

1. Para alterar a Região da AWS, use o seletor de regiões no canto superior direito da página.

1. No painel de navegação, escolha **Painel**.

1. No cartão **Atributos da conta**, em **Configurações**, escolha **Proteção e segurança de dados**.

1. Ao lado de **Padrões do IMDS**, escolha **Gerenciar**.

1. Na página **Gerenciar padrões do IMDS**, faça o seguinte:

   1. Em **Serviço de metadados de instância**, escolha **Habilitado**.

   1. Em **Metadata version** (Versão de metadados), selecione **V2 only (token required)** (Apenas V2 [token obrigatório]).

   1. Em **Limite de salto de resposta de metadados**, especifique **2** se suas instâncias forem hospedar contêineres. Caso contrário, selecione **Sem preferência**. Quando nenhuma preferência é especificada, na inicialização, o valor padrão é **2** se a AMI tiver a configuração `ImdsSupport: v2.0`; caso contrário, o padrão é **1**.

   1. Selecione **Atualizar**.

------
#### [ AWS CLI ]

**Para definir o IMDSv2 como padrão para a conta da região especificada**  
Use o comando [modify-instance-metadata-defaults](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-defaults.html) e especifique a região na qual deseja modificar as configurações do IMDS por conta. Inclua `--http-tokens` definido como `required` e `--http-put-response-hop-limit` como `2` se suas instâncias forem hospedar contêineres. Caso contrário, especifique `-1` para não indicar nenhuma preferência. Quando `-1` (nenhuma preferência) é especificada, na inicialização, o valor padrão é `2` se a AMI tiver a configuração `ImdsSupport: v2.0`; caso contrário, o padrão é `1`.

```
aws ec2 modify-instance-metadata-defaults \
    --region us-east-1 \
    --http-tokens required \
    --http-put-response-hop-limit 2
```

O seguinte é um exemplo de saída.

```
{
    "Return": true
}
```

**Para visualizar as configurações padrão de conta para as opções de metadados de instância para a região especificada**  
Use o comando [get-instance-metadata-defaults](https://docs.aws.amazon.com/cli/latest/reference/ec2/get-instance-metadata-defaults.html) e especifique a região.

```
aws ec2 get-instance-metadata-defaults --region us-east-1
```

O seguinte é um exemplo de saída.

```
{
    "AccountLevel": {
        "HttpTokens": "required",
        "HttpPutResponseHopLimit": 2
    },
    "ManagedBy": "account"
}
```

O campo `ManagedBy` indica a entidade que definiu as configurações. Neste exemplo, `account` indica que as configurações foram definidas diretamente na conta. Um valor de `declarative-policy` significaria que as configurações foram definidas por uma política declarativa. Para obter mais informações, consulte [Políticas declarativas](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_declarative.html) no *Guia do Usuário do AWS Organizations*.

**Para definir o IMDSv2 como o padrão para a conta de todas as regiões**  
Use o comando [modify-instance-metadata-defaults](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-defaults.html) para modificar as configurações em nível de conta do IMDS para todas as regiões. Inclua `--http-tokens` definido como `required` e `--http-put-response-hop-limit` como `2` se suas instâncias forem hospedar contêineres. Caso contrário, especifique `-1` para não indicar nenhuma preferência. Quando `-1` (nenhuma preferência) é especificada, na inicialização, o valor padrão é `2` se a AMI tiver a configuração `ImdsSupport: v2.0`; caso contrário, o padrão é `1`.

```
echo -e "Region          \t Modified" ; \
echo -e "--------------  \t ---------" ; \
for region in $(
    aws ec2 describe-regions \
        --region us-east-1 \
        --query "Regions[*].[RegionName]" \
        --output text
    ); 
    do (output=$(
        aws ec2 modify-instance-metadata-defaults \
            --region $region \
            --http-tokens required \
            --http-put-response-hop-limit 2 \
            --output text)
        echo -e "$region        \t $output"
    );
done
```

O seguinte é um exemplo de saída.

```
Region                   Modified
--------------           ---------
ap-south-1               True
eu-north-1               True
eu-west-3                True
...
```

**Para visualizar as configurações padrão de conta para as opções de metadados de instância para todas as regiões**  
Use o comando [get-instance-metadata-defaults](https://docs.aws.amazon.com/cli/latest/reference/ec2/get-instance-metadata-defaults.html).

```
echo -e "Region   \t Level          Hops    HttpTokens" ; \
echo -e "-------------- \t ------------   ----    ----------" ; \
for region in $(
    aws ec2 describe-regions \
        --region us-east-1 \
        --query "Regions[*].[RegionName]" \
        --output text
    ); 
    do (output=$(
        aws ec2 get-instance-metadata-defaults \
            --region $region \
            --output text)
        echo -e "$region \t $output" 
    );
done
```

O seguinte é um exemplo de saída.

```
Region           Level          Hops    HttpTokens
--------------   ------------   ----    ----------
ap-south-1       ACCOUNTLEVEL   2       required
eu-north-1       ACCOUNTLEVEL   2       required
eu-west-3        ACCOUNTLEVEL   2       required
...
```

------
#### [ PowerShell ]

**Para definir o IMDSv2 como padrão para a conta da região especificada**  
Use o cmdlet [Edit-EC2InstanceMetadataDefault](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMetadataDefault.html) e especifique a região na qual deseja modificar as configurações de nível de conta do IMDS. Inclua `-HttpToken` definido como `required` e `-HttpPutResponseHopLimit` como `2` se suas instâncias forem hospedar contêineres. Caso contrário, especifique `-1` para não indicar nenhuma preferência. Quando `-1` (nenhuma preferência) é especificada, na inicialização, o valor padrão é `2` se a AMI tiver a configuração `ImdsSupport: v2.0`; caso contrário, o padrão é `1`.

```
Edit-EC2InstanceMetadataDefault `
    -Region us-east-1 `
    -HttpToken required `
    -HttpPutResponseHopLimit 2
```

O seguinte é um exemplo de saída.

```
True
```

**Para visualizar as configurações padrão de conta para as opções de metadados de instância para a região especificada**  
Use o cmdlet [Get-EC2InstanceMetadataDefault](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2InstanceMetadataDefault.html) e especifique a região.

```
Get-EC2InstanceMetadataDefault -Region us-east-1 | Format-List
```

O seguinte é um exemplo de saída.

```
HttpEndpoint            : 
HttpPutResponseHopLimit : 2
HttpTokens              : required
InstanceMetadataTags    :
```

**Para definir o IMDSv2 como o padrão para a conta de todas as regiões**  
Use o cmdlet [Edit-EC2InstanceMetadataDefault](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMetadataDefault.html) para modificar as configurações em nível de conta do IMDS para todas as regiões. Inclua `-HttpToken` definido como `required` e `-HttpPutResponseHopLimit` como `2` se suas instâncias forem hospedar contêineres. Caso contrário, especifique `-1` para não indicar nenhuma preferência. Quando `-1` (nenhuma preferência) é especificada, na inicialização, o valor padrão é `2` se a AMI tiver a configuração `ImdsSupport: v2.0`; caso contrário, o padrão é `1`.

```
(Get-EC2Region).RegionName | `
    ForEach-Object {
    [PSCustomObject]@{
        Region   = $_
        Modified = (Edit-EC2InstanceMetadataDefault `
                -Region $_ `
                -HttpToken required `
                -HttpPutResponseHopLimit 2)
    } 
} | `
Format-Table Region, Modified -AutoSize
```

Saída esperada

```
Region         Modified
------         --------
ap-south-1         True
eu-north-1         True
eu-west-3          True
...
```

**Para visualizar as configurações padrão de conta para as opções de metadados de instância para todas as regiões**  
Use o cmdlet [Get-EC2InstanceMetadataDefault](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2InstanceMetadataDefault.html).

```
(Get-EC2Region).RegionName | `
    ForEach-Object {
    [PSCustomObject]@{
        Region = $_
        HttpPutResponseHopLimit = (Get-EC2InstanceMetadataDefault -Region $_).HttpPutResponseHopLimit
        HttpTokens              = (Get-EC2InstanceMetadataDefault -Region $_).HttpTokens
    }
} | `
Format-Table -AutoSize
```

Exemplo de saída

```
Region         HttpPutResponseHopLimit HttpTokens
------         ----------------------- ----------
ap-south-1                           2 required
eu-north-1                           2 required
eu-west-3                            2 required                    
...
```

------

### Aplique o IMDSv2 no nível da conta
<a name="enforce-imdsv2-at-the-account-level"></a>

Você pode impor o uso do IMDSv2 por conta para cada Região da AWS. Quando impostas, as instâncias só podem ser iniciadas se estiverem configuradas para exigir o IMDSv2. Essa imposição se aplica independentemente de como a instância ou a AMI estejam configuradas.

**nota**  
Antes de ativar a aplicação do IMDSv2 no nível da conta, certifique-se de que suas aplicações e AMIs sejam compatíveis com o IMDSv2. Para obter mais informações, consulte [Caminho recomendado para exigir IMDSv2](instance-metadata-transition-to-version-2.md#recommended-path-for-requiring-imdsv2). Se a imposição do IMDSv2 estiver habilitada e o `httpTokens` não tiver sido definido para `required` na configuração da instância na inicialização, nas configurações da conta ou na configuração da AMI, sua execução falhará. Para obter informações sobre a solução de problemas, consulte [Falha na inicialização de uma instância habilitada para IMDSv1](troubleshooting-launch.md#launching-an-imdsv1-enabled-instance-fails).

**nota**  
Essa configuração não altera a versão do IMDS das instâncias existentes, mas bloqueia a ativação do IMDSv1 em instâncias existentes que atualmente têm o IMDSv1 desabilitado.

------
#### [ Console ]

**Para impor o IMDSv2 para a conta na região especificada**

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

1. Para alterar a Região da AWS, use o seletor de regiões no canto superior direito da página.

1. No painel de navegação, escolha **Painel**.

1. No cartão **Atributos da conta**, em **Configurações**, escolha **Proteção e segurança de dados**.

1. Ao lado de **Padrões do IMDS**, escolha **Gerenciar**.

1. Na página **Gerenciar padrões do IMDS**, faça o seguinte:

   1. Em **Metadata version** (Versão de metadados), selecione **V2 only (token required)** (Apenas V2 [token obrigatório]).

   1. Para **Impor IMDSv2**, escolha **Habilitado**.

   1. Selecione **Atualizar**.

------
#### [ AWS CLI ]

**Para impor o IMDSv2 para a conta na região especificada**  
 Use o comando [modify-instance-metadata-defaults](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-defaults.html) e especifique a região na qual deseja impor o IMDSv2. 

```
aws ec2 modify-instance-metadata-defaults \
    --region us-east-1 \
    --http-tokens required \
    --http-tokens-enforced enabled
```

O seguinte é um exemplo de saída.

```
{
"Return": true
}
```

**Para visualizar a configuração de imposição do IMDSv2 para a conta em uma região específica**  
Use o comando [get-instance-metadata-defaults](https://docs.aws.amazon.com/cli/latest/reference/ec2/get-instance-metadata-defaults.html) e especifique a região.

```
aws ec2 get-instance-metadata-defaults --region us-east-1
```

O seguinte é um exemplo de saída.

```
{
    "AccountLevel": {
        "HttpTokens": "required",
        "HttpTokensEnforced": "enabled"
    },
    "ManagedBy": "account"
}
```

O campo `ManagedBy` indica a entidade que definiu as configurações. Neste exemplo, `account` indica que as configurações foram definidas diretamente na conta. Um valor de `declarative-policy` significaria que as configurações foram definidas por uma política declarativa. Para obter mais informações, consulte [Políticas declarativas](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_declarative.html) no *Guia do Usuário do AWS Organizations*.

**Para impor o IMDSv2 para a conta de todas as regiões**  
Use o comando [modify-instance-metadata-defaults](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-defaults.html) para impor o IMDSv2 em todas as regiões.

```
echo -e "Region          \t Modified" ; \
echo -e "--------------  \t ---------" ; \
for region in $(
    aws ec2 describe-regions \
        --region us-east-1 \
        --query "Regions[*].[RegionName]" \
        --output text
    ); 
    do (output=$(
        aws ec2 modify-instance-metadata-defaults \
            --region $region \
            --http-tokens-enforced enabled \
            --output text)
        echo -e "$region        \t $output"
    );
done
```

O seguinte é um exemplo de saída.

```
Region                   Modified
--------------           ---------
ap-south-1               True
eu-north-1               True
eu-west-3                True
...
```

**Para visualizar a configuração de imposição do IMDSv2 para a conta em todas as regiões**  
Use o comando [get-instance-metadata-defaults](https://docs.aws.amazon.com/cli/latest/reference/ec2/get-instance-metadata-defaults.html).

```
echo -e "Region   \t Level           HttpTokensEnforced" ; \
echo -e "-------------- \t ------------   ----------------" ; \
for region in $(
    aws ec2 describe-regions \
        --region us-east-1 \
        --query "Regions[*].[RegionName]" \
        --output text
    ); 
    do (output=$(
        aws ec2 get-instance-metadata-defaults \
            --region $region \
            --query 'AccountLevel.HttpTokensEnforced' \           
            --output text)
        echo -e "$region \t ACCOUNTLEVEL $output" 
    );
done
```

O seguinte é um exemplo de saída.

```
Region           Level          HttpTokensEnforced
--------------   ------------   ------------------
ap-south-1       ACCOUNTLEVEL   enabled
eu-north-1       ACCOUNTLEVEL   enabled
eu-west-3        ACCOUNTLEVEL   enabled
...
```

------
#### [ PowerShell ]

**Para impor o IMDSv2 para a conta na região especificada**  
Use o cmdlet [Edit-EC2InstanceMetadataDefault](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMetadataDefault.html) e especifique a região na qual deseja impor o IMDSv2. 

```
Edit-EC2InstanceMetadataDefault `
    -Region us-east-1 `
    -HttpToken required `
    -HttpPutResponseHopLimit 2
```

O seguinte é um exemplo de saída.

```
@{
    Return = $true
}
```

**Para visualizar a configuração de imposição do IMDSv2 para a conta em uma região específica**  
Use o comando Get-EC2InstanceMetadataDefault e especifique a região.

```
Get-EC2InstanceMetadataDefault -Region us-east-1
```

O seguinte é um exemplo de saída.

```
@{
    AccountLevel = @{
        HttpTokens = "required"
        HttpTokensEnforced = "enabled"
    }
    ManagedBy = "account"
}
```

O campo `ManagedBy` indica a entidade que definiu as configurações. Neste exemplo, `account` indica que as configurações foram definidas diretamente na conta. Um valor de `declarative-policy` significaria que as configurações foram definidas por uma política declarativa. Para obter mais informações, consulte [Políticas declarativas](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_declarative.html) no *Guia do Usuário do AWS Organizations*.

**Para impor o IMDSv2 para a conta de todas as regiões**  
Use o comando [modify-instance-metadata-defaults](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-defaults.html) para impor o IMDSv2 em todas as regiões.

```
echo -e "Region          \t Modified" ; \
echo -e "--------------  \t ---------" ; \
for region in $(
    aws ec2 describe-regions \
        --region us-east-1 \
        --query "Regions[*].[RegionName]" \
        --output text
    ); 
    do (output=$(
        aws ec2 modify-instance-metadata-defaults \
            --region $region \
            --http-tokens-enforced enabled \
            --output text)
        echo -e "$region        \t $output"
    );
done
```

O seguinte é um exemplo de saída.

```
Region                   Modified
--------------           ---------
ap-south-1               True
eu-north-1               True
eu-west-3                True
...
```

**Para definir o IMDSv2 como o padrão para a conta de todas as regiões**  
Use o cmdlet [Edit-EC2InstanceMetadataDefault](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMetadataDefault.html) para modificar as configurações em nível de conta do IMDS para todas as regiões. Inclua `-HttpToken` definido como `required` e `-HttpPutResponseHopLimit` como `2` se suas instâncias forem hospedar contêineres. Caso contrário, especifique `-1` para não indicar nenhuma preferência. Quando `-1` (nenhuma preferência) é especificada, na inicialização, o valor padrão é `2` se a AMI tiver a configuração `ImdsSupport: v2.0`; caso contrário, o padrão é `1`.

```
(Get-EC2Region).RegionName | `
    ForEach-Object {
    [PSCustomObject]@{
        Region   = $_
        Modified = (Edit-EC2InstanceMetadataDefault `
                -Region $_ `
                -HttpToken required `
                -HttpPutResponseHopLimit 2)
    } 
} | `
Format-Table Region, Modified -AutoSize
```

Saída esperada

```
Region         Modified
------         --------
ap-south-1         True
eu-north-1         True
eu-west-3          True
...
```

**Para visualizar as configurações padrão de conta para as opções de metadados de instância para todas as regiões**  
Use o cmdlet [Get-EC2InstanceMetadataDefault](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2InstanceMetadataDefault.html).

```
(Get-EC2Region).RegionName | `
    ForEach-Object {
    [PSCustomObject]@{
        Region = $_
        HttpPutResponseHopLimit = (Get-EC2InstanceMetadataDefault -Region $_).HttpPutResponseHopLimit
        HttpTokens              = (Get-EC2InstanceMetadataDefault -Region $_).HttpTokens
    }
} | `
Format-Table -AutoSize
```

Exemplo de saída

```
Region         HttpPutResponseHopLimit HttpTokens
------         ----------------------- ----------
ap-south-1                           2 required
eu-north-1                           2 required
eu-west-3                            2 required                    
...
```

------

### Configurar a instância na inicialização
<a name="configure-IMDS-new-instances-instance-settings"></a>

Quando você [inicia uma instância](ec2-launch-instance-wizard.md), pode configurá-la para exigir o uso do IMDSv2, configurando os seguintes campos:
+ Console do Amazon EC2: defina **Metadata version** (Versão de metadados) como **V2 only (token required)** (Apenas V2 [token obrigatório]).
+ AWS CLI: defina `HttpTokens` como `required`.

Quando você especificar que o IMDSv2 é obrigatório, também deverá habilitar o endpoint do Serviço de metadados da instância (IMDS) definindo **Metadados acessíveis** como **Habilitado** (console) ou `HttpEndpoint` como `enabled` (AWS CLI).

Em um ambiente de contêiner, quando o IMDSv2 for necessário, recomendamos definir o limite de saltos como `2`. Para obter mais informações, consulte [Considerações sobre o acesso aos metadados da instância](instancedata-data-retrieval.md#imds-considerations).

------
#### [ Console ]

**Como exigir o uso do IMDSv2 em uma nova instância**
+ Ao executar uma nova instância no console do Amazon EC2, expanda **Advanced details** (Detalhes avançados) e faça o seguinte:
  + Para **Metadata acessible** (Metadados acessíveis), escolha **Enabled** (Habilitado).
  + Em **Metadata version** (Versão de metadados), selecione **V2 only (token required)** (Apenas V2 [token obrigatório]).
  + (Ambiente de contêiner) Em **Limite de salto de resposta dos metadados**, escolha **2**.

  Para obter mais informações, consulte [Detalhes avançados](ec2-instance-launch-parameters.md#liw-advanced-details).

------
#### [ AWS CLI ]

**Como exigir o uso do IMDSv2 em uma nova instância**  
O exemplo de [run-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/run-instances.html) a seguir executa uma instância `c6i.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, é necessário que a instância use o IMDSv2 ao solicitar metadados da instância.

Em um ambiente de contêiner, quando o IMDSv2 for necessário, recomendamos definir o limite de saltos como `2` com `HttpPutResponseHopLimit=2`.

```
aws ec2 run-instances \
    --image-id ami-0abcdef1234567890 \
    --instance-type c6i.large \
	...
    --metadata-options "HttpEndpoint=enabled,HttpTokens=required,HttpPutResponseHopLimit=2"
```

------
#### [ PowerShell ]

**Como exigir o uso do IMDSv2 em uma nova instância**  
O exemplo de cmdlet [New-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/New-EC2Instance.html) a seguir inicia uma instância `c6i.large` com `MetadataOptions_HttpEndpoint` definido como `enabled` e o parâmetro `MetadataOptions_HttpTokens` como `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, é necessário que a instância use o IMDSv2 ao solicitar metadados da instância.

```
New-EC2Instance `
    -ImageId ami-0abcdef1234567890 `
    -InstanceType c6i.large `
    -MetadataOptions_HttpEndpoint enabled `
    -MetadataOptions_HttpTokens required
```

------
#### [ CloudFormation ]

Para especificar as opções de metadados de uma instância usando CloudFormation, consulte a propriedade [AWS::EC2::LaunchTemplate MetadataOptions](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ec2-launchtemplate-metadataoptions.html) no *Guia do usuário do AWS CloudFormation*.

------

### Configurar a AMI
<a name="configure-IMDS-new-instances-ami-configuration"></a>

Ao registrar uma nova AMI ou modificar uma AMI existente, é possível definir o parâmetro `imds-support` como `v2.0`. As instâncias iniciadas a partir dessa AMI terão **Metadata version** (Versão de metadados) definido como **V2 only (token required)** (Apenas V2 [token obrigatório]) (console) ou `HttpTokens` definido como `required` (AWS CLI). Com essas configurações, a instância exige que o IMDSv2 seja usado ao solicitar metadados da instância.

Observe que quando você configura `imds-support` como `v2.0`, as instâncias iniciadas a partir dessa AMI também têm **Metadata response hop limit** (Limite de saltos na resposta de metadados) (console) ou `http-put-response-hop-limit` (AWS CLI) definido como **2**.

**Importante**  
Não use esse parâmetro, a menos que seu software AMI ofereça suporte ao IMDSv2. Após definir o valor como `v2.0`, você não poderá desfazer essa ação. A única maneira de “redefinir” sua AMI é criando uma nova AMI a partir do snapshot subjacente.

**Para configurar uma nova AMI para o IMDSv2**  
Use um dos métodos a seguir para configurar uma nova AMI para o IMDSv2.

------
#### [ AWS CLI ]

O exemplo de [register-image](https://docs.aws.amazon.com/cli/latest/reference/ec2/register-image.html) a seguir registra uma AMI usando o snapshot especificado de um volume raiz do EBS como `/dev/xvda` de dispositivo. Especifique `v2.0` para o parâmetro `imds-support`, de forma que instâncias iniciadas a partir dessa AMI exijam que o IMDSv2 seja usado ao solicitar metadados da instância.

```
aws ec2 register-image \
    --name my-image \
    --root-device-name /dev/xvda \
    --block-device-mappings DeviceName=/dev/xvda,Ebs={SnapshotId=snap-0123456789example} \
    --architecture x86_64 \
    --imds-support v2.0
```

------
#### [ PowerShell ]

O exemplo de cmdlet [Register-EC2Image](https://docs.aws.amazon.com/powershell/latest/reference/items/Register-EC2Image.html) a seguir registra uma AMI usando o snapshot especificado de um volume raiz do EBS como dispositivo `/dev/xvda`. Especifique `v2.0` para o parâmetro `ImdsSupport`, de forma que instâncias iniciadas a partir dessa AMI exijam que o IMDSv2 seja usado ao solicitar metadados da instância.

```
Register-EC2Image `
    -Name 'my-image' `
    -RootDeviceName /dev/xvda `
    -BlockDeviceMapping  ( 
    New-Object `
        -TypeName Amazon.EC2.Model.BlockDeviceMapping `
        -Property @{ 
        DeviceName = '/dev/xvda'; 
        EBS        = (New-Object -TypeName Amazon.EC2.Model.EbsBlockDevice -Property @{ 
                SnapshotId = 'snap-0123456789example'
                VolumeType = 'gp3' 
                } )      
        }  ) `
    -Architecture X86_64 `
    -ImdsSupport v2.0
```

------

**Para configurar uma AMI existente para o IMDSv2**  
Use um dos métodos a seguir para configurar uma AMI para IMDSv2 existente.

------
#### [ AWS CLI ]

O exemplo de [modify-image-attribute](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-image-attribute.html) a seguir modifica uma AMI existente para IMDSv2 somente. Especifique `v2.0` para o parâmetro `imds-support`, de forma que instâncias iniciadas a partir dessa AMI exijam que o IMDSv2 seja usado ao solicitar metadados da instância.

```
aws ec2 modify-image-attribute \
    --image-id ami-0abcdef1234567890 \
    --imds-support v2.0
```

------
#### [ PowerShell ]

O exemplo de cmdlet [Edit-EC2ImageAttribute](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2ImageAttribute.html) a seguir só modifica uma AMI existente para IMDSv2. Especifique `v2.0` para o parâmetro `imds-support`, de forma que instâncias iniciadas a partir dessa AMI exijam que o IMDSv2 seja usado ao solicitar metadados da instância.

```
Edit-EC2ImageAttribute `
    -ImageId ami-0abcdef1234567890 `
    -ImdsSupport 'v2.0'
```

------

### Usar uma política do IAM
<a name="configure-IMDS-new-instances-iam-policy"></a>

Você pode criar uma política do IAM que faça o seguinte:
+ Impeça que os usuários iniciem novas instâncias, a menos que exijam o IMDSv2 na nova instância.
+ Impeça que os usuários chamem a API ModifyInstanceMetadataOptions para alterar as opções de metadados de uma instância em execução. Restrinja o acesso à propriedade ModifyInstanceMetadataOptions httpTokens para evitar atualizações não intencionais das instâncias em execução.
+ Impeça que os usuários chamem a API ModifyInstanceMetadataDefaults para alterar as configurações padrão da conta de httpTokens e httpTokensEnforced. Restringir o acesso a essas duas propriedades garantirá que somente perfis autorizados possam modificar os padrões da conta.

**Para impor o uso do IMDSv2 em todas as novas instâncias usando uma política do IAM**  
Para garantir que os usuários possam executar apenas instâncias que requeiram o uso do IMDSv2 ao solicitar metadados da instância, faça o seguinte:
+ Restrinja o acesso à API `ModifyInstanceMetadataOptions` e `ModifyInstanceMetadataDefaults` e mais especificamente às propriedades `httpTokens` e `httpTokensEnforced`.
+ Em seguida, defina o padrão da conta como `httpTokens = required` e `httpTokensEnforced = enabled`.

  Para ver um exemplo de política do IAM, consulte [Trabalhar com metadados de instância](ExamplePolicies_EC2.md#iam-example-instance-metadata).

## Habilitar os endpoints IPv4 e IPv6 do IMDS
<a name="configure-IMDS-new-instances-ipv4-ipv6-endpoints"></a>

O IMDS tem dois endpoints em uma instância: IPv4 (`169.254.169.254`) e IPv6 (`[fd00:ec2::254]`). Quando você habilita o IMDS, o endpoint IPv4 é habilitado automaticamente. O endpoint IPv6 permanece desabilitado mesmo que você inicie uma instância em uma sub-rede IPv6 apenas. Para habilitar o endpoint IPv6, você precisa fazer isso explicitamente. Quando você habilita o endpoint IPv6, o endpoint IPv4 permanece habilitado.

É possível habilitar o endpoint iPv6 ao iniciar a instância ou posteriormente.

**Requisitos para habilitação do endpoint iPv6**
+ O tipo de instância selecionado é uma [instância baseada em Nitro](instance-types.md#instance-hypervisor-type).
+ A sub-rede selecionada é compatível com IPv6, no qual a sub-rede é de [pilha dupla ou IPv6 apenas](https://docs.aws.amazon.com/vpc/latest/userguide/configure-subnets.html#subnet-ip-address-range).

Use um dos métodos a seguir para iniciar uma instância com o endpoint IPv6 do IMDS habilitado.

------
#### [ Console ]

**Para habilitar o endpoint IPv6 do IMDS na inicialização de instância**
+ [Inicie a instância](ec2-launch-instance-wizard.md) no console do Amazon EC2 com o valor a seguir especificado em **Advanced details** (Detalhes avançados):
  + Para o **endpoint IPv6 de metadados**, escolha **Habilitado**.

Para obter mais informações, consulte [Detalhes avançados](ec2-instance-launch-parameters.md#liw-advanced-details).

------
#### [ AWS CLI ]

**Para habilitar o endpoint IPv6 do IMDS na inicialização de instância**  
O exemplo de [run-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/run-instances.html) a seguir inicia uma instância `c6i.large` com o endpoint IPv6 habilitado para o IMDS. Para habilitar o endpoint IPv6, no parâmetro `--metadata-options`, especifique `HttpProtocolIpv6=enabled`. Quando você especifica um valor para `HttpProtocolIpv6`, você também deve definir `HttpEndpoint` como `enabled`.

```
aws ec2 run-instances \
    --image-id ami-0abcdef1234567890 \
    --instance-type c6i.large \
    ...
    --metadata-options "HttpEndpoint=enabled,HttpProtocolIpv6=enabled"
```

------
#### [ PowerShell ]

**Para habilitar o endpoint IPv6 do IMDS na inicialização de instância**  
O exemplo de cmdlet [New-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/New-EC2Instance.html) a seguir inicia uma instância `c6i.large` com o endpoint IPv6 habilitado para IMDS. Para habilitar o endpoint IPv6, especifique `MetadataOptions_HttpProtocolIpv6` como `enabled`. Quando você especifica um valor para `MetadataOptions_HttpProtocolIpv6`, você também deve definir `MetadataOptions_HttpEndpoint` como `enabled`.

```
New-EC2Instance `
    -ImageId ami-0abcdef1234567890 `
    -InstanceType c6i.large `
    -MetadataOptions_HttpEndpoint enabled `
    -MetadataOptions_HttpProtocolIpv6 enabled
```

------

## Desativar o acesso aos metadados da instância
<a name="configure-IMDS-new-instances--turn-off-instance-metadata"></a>

É possível desativar o acesso aos metadados da instância desativando o IMDS ao executar uma instância. É possível ativar o acesso mais tarde reativando o IMDS. Para obter mais informações, consulte [Ativar o acesso aos metadados da instância](configuring-IMDS-existing-instances.md#enable-instance-metadata-on-existing-instances).

**Importante**  
É possível desativar o IMDS na execução ou após a execução. Se você desativar o IMDS *na execução*, os seguintes problemas poderão ocorrer:  
Talvez você não tenha acesso SSH à sua instância. A `public-keys/0/openssh-key`, que é a chave SSH pública da sua instância, não estará acessível porque a chave normalmente é fornecida e acessada nos metadados da instância do EC2.
Os dados do usuário do EC2 não estarão disponíveis e não serão executados no início da instância. Os dados do usuário do EC2 são hospedados no IMDS. Caso desative o IMDS, você desativará efetivamente o acesso aos dados do usuário.
Para acessar essa funcionalidade, você pode reativar o IMDS após a execução.

------
#### [ Console ]

**Desativar o acesso aos metadados da instância na execução**
+ [Inicie a instância](ec2-launch-instance-wizard.md) no console do Amazon EC2 com o valor a seguir especificado em **Advanced details** (Detalhes avançados):
  + Para **Metadata acessible** (Metadados acessíveis), escolha **Disabled** (Desabilitado).

Para obter mais informações, consulte [Detalhes avançados](ec2-instance-launch-parameters.md#liw-advanced-details).

------
#### [ AWS CLI ]

**Desativar o acesso aos metadados da instância na execução**  
Inicie a instância com `--metadata-options` definido como `HttpEndpoint=disabled`.

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

------
#### [ PowerShell ]

**Desativar o acesso aos metadados da instância na execução**  
O exemplo de cmdlet [New-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/New-EC2Instance.html) a seguir inicia uma instância `MetadataOptions_HttpEndpoint` definida como `disabled`.

```
New-EC2Instance `
    -ImageId ami-0abcdef1234567890 `
    -InstanceType c6i.large `
    -MetadataOptions_HttpEndpoint disabled
```

------
#### [ CloudFormation ]

Para especificar as opções de metadados de uma instância usando CloudFormation, consulte a propriedade [AWS::EC2::LaunchTemplate MetadataOptions](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ec2-launchtemplate-metadataoptions.html) no *Guia do usuário do CloudFormation*. 

------

## Permitir acesso a tags em metadados de instância
<a name="configure-IMDS-new-instances-tags-in-instance-metadata"></a>

Por padrão, as tags de instância não podem ser acessadas nos metadados da instância. Para cada instância, permita o acesso explicitamente. Se o acesso for permitido, as *chaves* de tag da instância devem estar em conformidade com restrições de caracteres específicas, caso contrário, a execução da instância falhará. Para obter mais informações, consulte [Habilitar o acesso a tags em metadados da instância](work-with-tags-in-IMDS.md#allow-access-to-tags-in-IMDS).

# Modificar as opções de metadados de instância para as instâncias existentes
<a name="configuring-IMDS-existing-instances"></a>

É possível modificar as opções de metadados da instância para instâncias existentes.

Também é possível criar uma política do IAM que impeça que os usuários modifiquem as opções de metadados em instâncias existentes. Para controlar quais usuários podem modificar as opções de metadados em uma instância, especifique uma política que impeça que todos os usuários que não tenham um perfil especificado usem a API [ModifyInstanceMetadataOptions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyInstanceMetadataOptions.html). Para ver um exemplo de política do IAM, consulte [Trabalhar com metadados de instância](ExamplePolicies_EC2.md#iam-example-instance-metadata).

**nota**  
Se uma política declarativa foi usada para configurar as opções de metadados da instância, você não poderá modificá-las diretamente na conta. Para obter mais informações, consulte [Políticas declarativas](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_declarative.html) no *Guia do usuário do AWS Organizations*.

## Exigir o uso de IMDSv2
<a name="modify-require-IMDSv2"></a>

Use um dos seguintes métodos para modificar as opções de metadados da instância para exigir que o IMDSv2 seja usado ao solicitar metadados da instância. Quando o IMDSv2 for necessário, o IMDSv1 não poderá ser usado.

**nota**  
Antes de exigir que o IMDSv2 seja usado, certifique-se de que a instância não esteja fazendo chamadas do IMDSv1. A métrica `MetadataNoToken` do CloudWatch rastreia as chamadas do IMDSv1. Quando `MetadataNoToken` registra zero uso do IMDSv1 para uma instância, a instância está pronta para exigir o IMDSv2.

------
#### [ Console ]

**Para exigir o uso do IMDSv2 em uma instância existente**

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

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

1. Selecione sua instância.

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

1. Na caixa de diálogo **Modificar opções de metadados da instância**, faça o seguinte:

   1. Em **Serviço de metadados de instância**, selecione **Habilitar**.

   1. Em **IMDSv2**, escolha **Obrigatório**.

   1. Escolha **Salvar**.

------
#### [ AWS CLI ]

**Para exigir o uso do IMDSv2 em uma instância existente**  
Use o comando [modify-instance-metadata-options](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-options.html) da CLI e defina o parâmetro `http-tokens` como `required`. Quando você especifica um valor para `http-tokens`, você também deve definir `http-endpoint` como `enabled`.

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

------
#### [ PowerShell ]

**Para exigir o uso do IMDSv2 em uma instância existente**  
Use o cmdlet [Edit-EC2InstanceMetadataOption](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMetadataOption.html) e defina o parâmetro `HttpTokens` como `required`. Quando você especifica um valor para `HttpTokens`, você também deve definir `HttpEndpoint` como `enabled`.

```
(Edit-EC2InstanceMetadataOption `
    -InstanceId i-1234567890abcdef0 `
    -HttpTokens required `
    -HttpEndpoint enabled).InstanceMetadataOptions
```

------

## Restaurar o uso do IMDSv1
<a name="modify-restore-IMDSv1"></a>

Quando o IMDSv2 é necessário em uma instância, o uso de uma solicitação do IMDSv1 falhará. Quando o IMDSv2 for opcional, tanto o IMDSv2 quanto o IMDSv1 funcionarão. Portanto, para restaurar o IMDSv1, defina o IMDSv2 opcional (`httpTokens = optional`) usando um dos métodos a seguir.

A propriedade `httpTokensEnforced` do IMDS também impede tentativas de habilitar o IMDSv1 em uma instância existente. Quando habilitada para uma conta em uma região, uma tentativa de definir `httpTokens` como `optional` resultará em uma exceção `UnsupportedOperation`. Para obter mais informações, consulte [Solução de problemas](#troubleshoot-modifying-an-imdsv1-enabled-instance-fails).

**Importante**  
Se as execuções de sua instância falharem devido à imposição do IMDSv2, você tem duas opções para permitir que as execuções sejam bem-sucedidas:  
**Inicie instâncias somente como IMDSv2**: se o software executado nas instâncias usar somente o IMDSv2 (sem depender do IMDSv1), você poderá iniciar as instâncias somente como IMDSv2. Para fazer isso, configure o IMDSv2 apenas quando definido como `httpTokens = required` nos parâmetros de inicialização ou nos metadados padrão da conta na região. 
**Desabilitar a imposição**: se seu software ainda depender do IMDSv1, defina `httpTokensEnforced` como `disabled` para a conta na região. Para obter mais informações, consulte [Aplique o IMDSv2 no nível da conta](configuring-IMDS-new-instances.md#enforce-imdsv2-at-the-account-level).

------
#### [ Console ]

**Para restaurar o uso do IMDSv1 em uma instância**

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

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

1. Selecione sua instância.

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

1. Na caixa de diálogo **Modificar opções de metadados da instância**, faça o seguinte:

   1. Em **Serviço de metadados de instância**, certifique-se de que a opção **Habilitar** esteja selecionada.

   1. Em **IMDSv2**, escolha **Opcional**.

   1. Escolha **Salvar**.

------
#### [ AWS CLI ]

**Para restaurar o uso do IMDSv1 em uma instância**  
É possível usar o comando da CLI [modify-instance-metadata-options](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-options.html) com `http-tokens` definido como `optional` para restaurar o uso de IMDSv1 ao solicitar metadados de instância.

```
aws ec2 modify-instance-metadata-options \
    --instance-id i-1234567890abcdef0 \
    --http-tokens optional \
    --http-endpoint enabled
```

------
#### [ PowerShell ]

**Para restaurar o uso do IMDSv1 em uma instância**  
É possível usar o cmdlet [Edit-EC2InstanceMetadataOption](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMetadataOption.html) com o `HttpTokens` configurado como `optional` para restaurar o uso do IMDSv1 ao solicitar metadados da instância.

```
(Edit-EC2InstanceMetadataOption `
    -InstanceId i-1234567890abcdef0 `
    -HttpTokens optional `
    -HttpEndpoint enabled).InstanceMetadataOptions
```

------

## Alterar o limite de salto de resposta PUT
<a name="modify-PUT-response-hop-limit"></a>

Para instâncias existentes, é possível alterar as configurações do limite de saltos de resposta de `PUT`.

Atualmente, somente os SDKs AWS CLI e AWS oferecem suporte à alteração do limite de salto de resposta PUT.

------
#### [ AWS CLI ]

**Como alterar o limite de salto de resposta PUT**  
Use o comando [modify-instance-metadata-options](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-options.html) 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-1234567890abcdef0 \
    --http-put-response-hop-limit 3 \
    --http-endpoint enabled
```

------
#### [ PowerShell ]

**Como alterar o limite de salto de resposta PUT**  
Use o cmdlet [Edit-EC2InstanceMetadataOption](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMetadataOption.html) e defina o parâmetro `HttpPutResponseHopLimit`para o número necessário de saltos. No exemplo a seguir, o limite de saltos está definido como `3`. Observe que ao especificar um valor para `HttpPutResponseHopLimit`, também é necessário definir `HttpEndpoint` como `enabled`.

```
(Edit-EC2InstanceMetadataOption `
    -InstanceId i-1234567890abcdef0 `
    -HttpPutResponseHopLimit 3 `
    -HttpEndpoint enabled).InstanceMetadataOptions
```

------

## Habilitar os endpoints IPv4 e IPv6 do IMDS
<a name="enable-ipv6-endpoint-for-existing-instances"></a>

O IMDS tem dois endpoints em uma instância: IPv4 (`169.254.169.254`) e IPv6 (`[fd00:ec2::254]`). Quando você habilita o IMDS, o endpoint IPv4 é habilitado automaticamente. O endpoint IPv6 permanece desabilitado mesmo que você inicie uma instância em uma sub-rede IPv6 apenas. Para habilitar o endpoint IPv6, você precisa fazer isso explicitamente. Quando você habilita o endpoint IPv6, o endpoint IPv4 permanece habilitado.

É possível habilitar o endpoint iPv6 ao iniciar a instância ou posteriormente.

**Requisitos para habilitação do endpoint iPv6**
+ O tipo de instância selecionado é uma [instância baseada em Nitro](instance-types.md#instance-hypervisor-type).
+ A sub-rede selecionada é compatível com IPv6, no qual a sub-rede é de [pilha dupla ou IPv6 apenas](https://docs.aws.amazon.com/vpc/latest/userguide/configure-subnets.html#subnet-ip-address-range).

Atualmente, apenas a AWS CLI e os SDKs da AWS são compatíveis com a habilitação do endpoint IPv6 do IMDS após a inicialização da instância.

------
#### [ AWS CLI ]

**Para habilitar o endpoint de IPv6 do IMDS para a instância**  
Use o comando [modify-instance-metadata-options](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-options.html) da CLI e defina o parâmetro `http-protocol-ipv6` como `enabled`. Observe que ao especificar um valor para `http-protocol-ipv6`, também é necessário definir `http-endpoint` como `enabled`.

```
aws ec2 modify-instance-metadata-options \
	--instance-id i-1234567890abcdef0 \
	--http-protocol-ipv6 enabled \
	--http-endpoint enabled
```

------
#### [ PowerShell ]

**Para habilitar o endpoint de IPv6 do IMDS para a instância**  
Use o cmdlet [Edit-EC2InstanceMetadataOption](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMetadataOption.html) e defina o parâmetro `HttpProtocolIpv6` como `enabled`. Observe que ao especificar um valor para `HttpProtocolIpv6`, também é necessário definir `HttpEndpoint` como `enabled`.

```
(Edit-EC2InstanceMetadataOption `
    -InstanceId i-1234567890abcdef0 `
    -HttpProtocolIpv6 enabled `
    -HttpEndpoint enabled).InstanceMetadataOptions
```

------

## Ativar o acesso aos metadados da instância
<a name="enable-instance-metadata-on-existing-instances"></a>

É possível ativar o acesso aos metadados da instância habilitando o endpoint de HTTP do IMDS na sua instância, independentemente da versão do IMDS que esteja sendo usada. É possível reverter essa alteração a qualquer momento desabilitando o endpoint de HTTP.

Use um dos métodos a seguir para ativar o acesso aos metadados da instância em uma instância.

------
#### [ Console ]

**Para ativar o acesso aos metadados da instância**

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

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

1. Selecione sua instância.

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

1. Na caixa de diálogo **Modificar opções de metadados da instância**, faça o seguinte:

   1. Em **Serviço de metadados de instância**, selecione **Habilitar**.

   1. Escolha **Salvar**.

------
#### [ AWS CLI ]

**Para ativar o acesso aos metadados da instância**  
Use o comando [modify-instance-metadata-options](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-options.html) da CLI e defina o parâmetro `http-endpoint` como `enabled`.

```
aws ec2 modify-instance-metadata-options \
    --instance-id i-1234567890abcdef0 \
    --http-endpoint enabled
```

------
#### [ PowerShell ]

**Para ativar o acesso aos metadados da instância**  
Use o cmdlet [Edit-EC2InstanceMetadataOption](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMetadataOption.html) e defina o parâmetro `HttpEndpoint` como `enabled`.

```
(Edit-EC2InstanceMetadataOption `
    -InstanceId i-1234567890abcdef0 `
    -HttpEndpoint enabled).InstanceMetadataOptions
```

------

## Desativar o acesso aos metadados da instância
<a name="disable-instance-metadata-on-existing-instances"></a>

É possível desativar o acesso aos metadados da instância desabilitando o endpoint de HTTP do IMDS na sua instância, independentemente da versão do IMDS que esteja sendo usada. É possível reverte essa alteração a qualquer momento habilitando o HTTP endpoint.

Use um dos métodos a seguir para desativar o acesso aos metadados da instância em uma instância.

------
#### [ Console ]

**Como desabilitar o acesso aos metadados da instância**

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

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

1. Selecione sua instância.

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

1. Na caixa de diálogo **Modificar opções de metadados da instância**, faça o seguinte:

   1. Em **Serviço de metadados de instância**, desmarque **Habilitar**.

   1. Escolha **Salvar**.

------
#### [ AWS CLI ]

**Como desabilitar o acesso aos metadados da instância**  
Use o comando [modify-instance-metadata-options](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-options.html) da CLI e defina o parâmetro `http-endpoint` como `disabled`.

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

------
#### [ PowerShell ]

**Como desabilitar o acesso aos metadados da instância**  
Use o cmdlet [Edit-EC2InstanceMetadataOption](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMetadataOption.html) e defina o parâmetro `HttpEndpoint` como `disabled`.

```
(Edit-EC2InstanceMetadataOption `
    -InstanceId i-1234567890abcdef0 `
    -HttpEndpoint disabled).InstanceMetadataOptions
```

------

## Permitir acesso a tags em metadados de instância
<a name="modify-access-to-tags-in-instance-metadata-on-existing-instances"></a>

É possível permitir o acesso a tags em metadados de instância em uma instância em execução ou parada. Para cada instância, permita o acesso explicitamente. Se o acesso for permitido, as *chaves* de tag da instância devem estar em conformidade com restrições de caracteres específicas, caso contrário, você receberá um erro. Para obter mais informações, consulte [Habilitar o acesso a tags em metadados da instância](work-with-tags-in-IMDS.md#allow-access-to-tags-in-IMDS).

## Solução de problemas
<a name="troubleshoot-modifying-an-imdsv1-enabled-instance-fails"></a>

### Falha na modificação de uma instância habilitada para IMDSv1
<a name="modifying-an-imdsv1-enabled-instance-fails"></a>

#### Descrição
<a name="modifying-an-imdsv1-enabled-instance-fails-description"></a>

Você recebeu a seguinte mensagem de erro:

`You can't launch instances with IMDSv1 because httpTokensEnforced is enabled for this account. Either launch the instance with httpTokens=required or contact your account owner to disable httpTokensEnforced using the ModifyInstanceMetadataDefaults API or the account settings in the EC2 console.`

#### Causa
<a name="modifying-an-imdsv1-enabled-instance-fails-cause"></a>

Esse erro é gerado quando você tenta modificar uma instância existente para habilitar o IMDSv1 (`httpTokens = optional`) em uma conta onde as configurações da conta do EC2 ou uma política declarativa da organização da AWS impõem o uso de IMDSv2 (`httpTokensEnforced = enabled`). 

#### Solução
<a name="modifying-an-imdsv1-enabled-instance-fails-solution"></a>

Se você precisar do suporte do IMDSv1 em instâncias existentes, precisará desabilitar a aplicação do IMDSv2 para a conta na região. Para desabilitar a aplicação do IMDSv2, defina `HttpTokensEnforced` como `disabled`. Para obter mais informações, consulte [ModifyInstanceMetadataDefaults](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyInstanceMetadataDefaults.html) na Referência a APIs do Amazon EC2. Se você preferir definir essa configuração usando o console, consulte [Aplique o IMDSv2 no nível da conta](configuring-IMDS-new-instances.md#enforce-imdsv2-at-the-account-level).

Recomendamos usar somente o IMDSv2 (`httpTokens=required`). Para obter mais informações, consulte [Transição para usar o Serviço de metadados da instância versão 2](instance-metadata-transition-to-version-2.md).

 

# Executar comandos ao iniciar uma instância do EC2 com entrada de dados do usuário
<a name="user-data"></a>

Ao iniciar uma instância do Amazon EC2, é possível transferir dados do usuário para a instância que é usada para executar tarefas de configuração automatizadas ou para executar scripts após o início da instância.

Caso tenha interesse em cenários de automação mais complexos, considere usar o CloudFormation. Para obter mais informações, consulte [Implantar aplicações no Amazon EC2 com o CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/deploying.applications.html) no *Guia do usuário do AWS CloudFormation*.

Em instâncias do Linux, é possível transferir dois tipos de dados do usuário para o Amazon EC2, nomeadamente, os scripts de shell e diretivas do cloud-init. Além disso, é possível transferir esses dados para o assistente de inicialização de instâncias como texto simples, como um arquivo (isso é útil para iniciar instâncias com as ferramentas de linha de comando) ou como texto codificado em base64 (para chamadas de API).

Nas instâncias do Windows, os agentes de inicialização gerenciam os scripts de dados do usuário.

**Considerações**
+ Os dados do usuário são tratados como dados opacos: o que você fornece é o que receberá de volta. Cabe à instância interpretá-los.
+ Os dados do usuário devem ser codificados por base64. O console do Amazon EC2 pode executar a codificação base64 para você ou aceitar uma entrada codificada em base64. Se você recuperar os dados usando o console ou os metadados da instância, eles serão decodificados automaticamente de base64para 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)\$14.
+ 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.

## Dados do usuário no Console de gerenciamento da AWS
<a name="user-data-console"></a>

É possível especificar os dados do usuário da instância ao executar uma instância. Se o volume raiz da instância for um volume do EBS, também é possível parar a instância e atualizar os dados de usuário.

### Especificar os dados do usuário da instância na execução com o Launch Wizard
<a name="user-data-launch-instance-wizard"></a>

É possível especificar dados do usuário quando executar uma instância com o Launch Wizard no console do EC2. Para especificar os dados do usuário na execução, siga o procedimento para [executar uma instância](ec2-launch-instance-wizard.md). O campo **User data** (Dados do usuário) está localizado na seção [Detalhes avançados](ec2-instance-launch-parameters.md#liw-advanced-details) do assistente de inicialização de instância. Insira seu script do PowerShell no campo **Dados do usuário** e conclua o procedimento de execução de instância.

Na seguinte captura de tela do campo **Dados do usuário**, o script de exemplo cria um arquivo na pasta temporária do Windows usando a data e a hora atuais no nome de arquivo. Ao incluir `<persist>true</persist>`, o script é executado sempre que você reiniciar ou iniciar a instância. Se deixar a caixa de seleção **Os dados do usuário já foram codificados em base64** vazia, o console do Amazon EC2 executará a codificação em base64 para você.

![\[Campo de texto de dados do usuário Advance Details (Detalhes avançados).\]](http://docs.aws.amazon.com/pt_br/AWSEC2/latest/UserGuide/images/configure_ec2config_userdata.png)


Para obter mais informações, consulte [Especificar os dados do usuário da instância na execução com o Launch Wizard](#user-data-launch-instance-wizard). Para obter um exemplo do Linux que usa a AWS CLI, consulte [Dados do usuário e AWS CLI](#user-data-api-cli). Para obter um exemplo do Windows que usa o Tools for Windows PowerShell, consulte [Dados do usuário e Tools for Windows PowerShell](#user-data-powershell).

### Visualizar e atualizar os dados do usuário da instância
<a name="user-data-view-change"></a>

É possível visualizar dados do usuário da instância para qualquer instância e atualizar dados do usuário da instância para uma instância interrompida.

**Para atualizar os dados do usuário para uma instância usando o console**

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

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

1. Selecione a instância e escolha **Actions (Ações)**, **Instance state (Estado da instância)** e **Stop instance (Interromper instância)**.
**Atenção**  
Quando você interrompe uma instância, os dados nos volumes de armazenamento de instância são perdidos. Para preservar esses dados, faça backup no armazenamento persistente.

1. Quando a confirmação for solicitada, escolha **Parar**. Pode demorar alguns minutos para que a instância pare.

1. Com a instância ainda selecionada, escolha **Actions (Ações)**, **Instance settings (Configurações de instância)**, **Edit user data (Editar dados de usuário)**. Não é possível alterar os dados do usuário se a instância estiver em execução, mas é possível visualizá-la.

1. Na caixa de diálogo **Edit user data** (Editar dados do usuário), atualize os dados do usuário e escolha **Save** (Salvar). Para executar os scripts de dados do usuário sempre que você reiniciar ou iniciar a instância, adicione `<persist>true</persist>`, como mostrado no exemplo a seguir:  
![\[Caixa de diálogo Edit User Data (Editar dados do usuário).\]](http://docs.aws.amazon.com/pt_br/AWSEC2/latest/UserGuide/images/view-change-user-data.png)

1. Inicie a instância. Se você habilitou a execução de dados do usuário para reinicializações ou inicializações subsequentes, os scripts de dados do usuário atualizados serão executados como parte do processo de inicialização da instância.

## Como o Amazon EC2 lida com os dados dos usuários para instâncias do Linux
<a name="userdata-linux"></a>

Os exemplos a seguir usam dados do usuário para executar comandos que configuram um servidor LAMP quando a instância é inicializada. Em cada exemplo, as seguintes tarefas são executadas:
+ Os pacotes de distribuição de software são atualizados.
+ O servidor Web, o `php` e os pacotes `mariadb` são instalados.
+ O serviço `httpd` é iniciado e ativado.
+ O usuário `ec2-user` é adicionado ao grupo apache.
+ As permissões de propriedade e de arquivos apropriadas são definidas para o diretório Web e os arquivos contidos nele.
+ Uma página Web simples é criada para testar o servidor Web e o mecanismo de PHP.

**Topics**
+ [

### Pré-requisitos
](#user-data-requirements)
+ [

### Dados de usuário e scripts de shell
](#user-data-shell-scripts)
+ [

### Atualizar os dados do usuário da instância
](#user-data-modify)
+ [

### Diretivas de cloud-init e dados de usuário
](#user-data-cloud-init)
+ [

### Dados do usuário e AWS CLI
](#user-data-api-cli)
+ [

### Combinar scripts de shell e diretivas de cloud-init
](#user-data-mime-multi)

### Pré-requisitos
<a name="user-data-requirements"></a>

Para os exemplos deste tópico, suponha o seguinte:
+ Sua instância tem um nome DNS público que é acessível pela Internet.
+ O grupo de segurança associado à sua instância é configurado para permitir tráfego SSH (porta 22), de modo que você possa se conectar à instância para visualizar os arquivos de log de saída.
+ Sua instância é inicializada usando uma AMI do Amazon Linux. Os comandos e diretivas podem não funcionar para outras distribuições Linux. Para obter mais informações sobre outras distribuições, como suporte para cloud-init, consulte a documentação específica da distribuição.

### Dados de usuário e scripts de shell
<a name="user-data-shell-scripts"></a>

Se você estiver familiarizado com scripts de shell, esta é a maneira mais fácil e completa de enviar instruções para uma instância na execução. Se você adicionar essas tarefas no momento da inicialização, será necessário mais tempo para iniciar a instância. É necessário reservar alguns minutos extras para que as tarefas sejam concluídas antes de testar se o script de usuário foi concluído com êxito.

**Importante**  
Por padrão, os scripts de dados do usuário e as diretrizes cloud-init são executados somente durante o ciclo de inicialização quando você inicia uma instância pela primeira vez. É possível atualizar sua configuração para garantir que seus scripts de dados de usuário e diretrizes cloud-init sejam executados sempre que você reiniciar sua instância. Para obter mais informações, consulte [How can I utilize user data to automatically run a script with every restart of my Amazon EC2 Linux instance? (Como posso utilizar os dados do usuário para executar automaticamente um script a cada reinicialização da minha instância do Linux do Amazon EC2?)](https://repost.aws/knowledge-center/execute-user-data-ec2) na Central de Conhecimento da AWS.

Os scripts de shell de dados de usuário devem ser iniciados pelos caracteres `#!` e pelo caminho para o intérprete que você deseja que leia o script (geralmente **/bin/bash)**. Para uma introdução sobre scripts de shell, consulte o [Manual de referência do Bash](https://www.gnu.org/software/bash/manual/bash.html) no site do *Sistema operacional GNU*.

Os scripts inseridos como dados de usuário são executados como usuário raiz,, portanto, não use o comando **sudo** no script. Lembre-se de que todos os arquivos que você criar serão de propriedade do usuário raiz. Caso precise que um usuário não raiz tenha acesso aos arquivos, modifique as permissões em conformidade com o script. Além disso, como o script não é executado interativamente, você não pode incluir os comandos que exigem feedback do usuário (como **yum update** sem o sinalizador `-y`).

Se você usar uma API da AWS, incluindo a CLI da AWS em um script de dados de usuário, deverá usar um perfil de instância ao inicializar a instância. Um perfil de instância fornece as credenciais apropriadas da AWS exigidas pelo script de dados do usuário para emitir a chamada de API. Para obter mais informações, consulte [Usar perfis de instâncias](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html) no Guia do usuário do IAM. As permissões que atribui à função do IAM dependem de quais serviços você chama com a API. Para obter mais informações, consulte [Funções do IAM para Amazon EC2](iam-roles-for-amazon-ec2.md).

O arquivo de log de saída de cloud-init captura a saída do console para facilitar a depuração de seus scripts após uma execução se a instância não se comportar da maneira desejada. Para exibir o arquivo de log, [conecte-se à instância](connect-to-linux-instance.md) e abra `/var/log/cloud-init-output.log`.

Quando um script de dados do usuário é processado, ele é copiado para e executado a partir deste diretório `/var/lib/cloud/instances/instance-id/`. O script não é excluído depois de ser executado. Certifique-se de excluir os scripts de dados do usuário de `/var/lib/cloud/instances/instance-id/` antes de criar uma AMI a partir da instância. Caso contrário, o script existirá nesse diretório em qualquer instância iniciada na AMI.

### Atualizar os dados do usuário da instância
<a name="user-data-modify"></a>

Para atualizar os dados do usuário da instância, primeiro é necessário interromper a instância. Se a instância estiver em execução, será possível visualizar os dados do usuário, mas não modificá-los.

**Atenção**  
Quando você interrompe uma instância, os dados nos volumes de armazenamento de instância são perdidos. Para preservar esses dados, faça backup no armazenamento persistente.

**Para modificar os dados do usuário da instância**

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

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

1. Selecione a instância e escolha **Estado da instância** e **Parar instância**. Se a opção estiver desabilitada, significa que a instância já está interrompida ou que o volume raiz é um armazenamento de instância.

1. Quando a confirmação for solicitada, escolha **Parar**. Pode demorar alguns minutos para que a instância pare.

1. Com a instância ainda selecionada, escolha **Actions (Ações)**, **Instance settings (Configurações de instância)**, **Edit user data (Editar dados de usuário)**.

1. Modifique os dados do usuário conforme necessário e escolha **Save (Salvar)**.

1. Inicie a instância. Os novos dados do usuário ficam visíveis na instância depois que você a inicia. Contudo, os scripts dos dados do usuário não são executados.

### Diretivas de cloud-init e dados de usuário
<a name="user-data-cloud-init"></a>

O pacote de cloud-init configura aspectos específicos de uma nova instância do Amazon Linux quando ela é executada. Em particular, ele configura o arquivo `.ssh/authorized_keys` para o usuário ec2 para que você possa se conectar com sua própria chave privada. Para obter mais informações sobre as tarefas de configuração que o pacote cloud-init executa para instâncias do Amazon Linux, consulte a seguinte documentação:
+ **Amazon Linux 2023** – [Customized cloud-init](https://docs.aws.amazon.com/linux/al2023/ug/cloud-init.html)
+ **Amazon Linux 2** – [Using cloud-init on Amazon Linux 2](https://docs.aws.amazon.com/linux/al2/ug/amazon-linux-cloud-init.html)

As diretivas de cloud-init podem ser passadas a uma instância em execução da mesma forma que um script é passado, embora a sintaxe seja diferente. Para obter mais informações sobre o cloud-init, consulte [https://cloudinit.readthedocs.org/en/latest/index.html](https://cloudinit.readthedocs.org/en/latest/index.html).

**Importante**  
Por padrão, os scripts de dados do usuário e as diretrizes cloud-init são executados somente durante o ciclo de inicialização quando você inicia uma instância pela primeira vez. É possível atualizar sua configuração para garantir que seus scripts de dados de usuário e diretrizes cloud-init sejam executados sempre que você reiniciar sua instância. Para obter mais informações, consulte [How can I utilize user data to automatically run a script with every restart of my Amazon EC2 Linux instance? (Como posso utilizar os dados do usuário para executar automaticamente um script a cada reinicialização da minha instância Linux do Amazon EC2?)](https://repost.aws/knowledge-center/execute-user-data-ec2) na Central de Conhecimento da AWS.

Se você adicionar essas tarefas no momento da inicialização, será necessário mais tempo para iniciar uma instância. É necessário reservar alguns minutos extras para que as tarefas sejam concluídas antes de testar se as diretivas de dados de usuário foram concluídas.

**Para passar diretivas do cloud-init para uma instância do Amazon Linux**

1. Siga o procedimento para [iniciar uma instância](ec2-launch-instance-wizard.md). O campo **User data** (Dados do usuário) está localizado na seção [Detalhes avançados](ec2-instance-launch-parameters.md#liw-advanced-details) do assistente de inicialização de instância. Insira o texto da diretiva cloud-init no campo **User data** (Dados do usuário) e conclua o procedimento de inicialização de instância.

   No exemplo a seguir, as diretivas criam e configuram um servidor Web no Amazon Linux. A linha `#cloud-config` na parte superior é necessária para identificar os comandos como diretrizes cloud-init.

------
#### [ AL2023 ]

   ```
   #cloud-config
   package_update: true
   package_upgrade: all
   	
   packages:
   - httpd
   - mariadb105-server
   - php8.1
   - php8.1-mysqlnd
   
   runcmd:
   - systemctl start httpd
   - systemctl enable httpd
   - [ sh, -c, "usermod -a -G apache ec2-user" ]
   - [ sh, -c, "chown -R ec2-user:apache /var/www" ]
   - chmod 2775 /var/www
   - [ find, /var/www, -type, d, -exec, chmod, 2775, {}, \; ]
   - [ find, /var/www, -type, f, -exec, chmod, 0664, {}, \; ]
   - [ sh, -c, 'echo "<?php phpinfo(); ?>" > /var/www/html/phpinfo.php' ]
   ```

------
#### [ AL2 ]

   ```
   #cloud-config
   package_update: true
   package_upgrade: all
   	
   packages:
   - httpd
   - mariadb-server
   	
   runcmd:
   - [ sh, -c, "amazon-linux-extras install -y lamp-mariadb10.2-php7.2 php7.2" ]
   - systemctl start httpd
   - systemctl enable httpd
   - [ sh, -c, "usermod -a -G apache ec2-user" ]
   - [ sh, -c, "chown -R ec2-user:apache /var/www" ]
   - chmod 2775 /var/www
   - [ find, /var/www, -type, d, -exec, chmod, 2775, {}, \; ]
   - [ find, /var/www, -type, f, -exec, chmod, 0664, {}, \; ]
   - [ sh, -c, 'echo "<?php phpinfo(); ?>" > /var/www/html/phpinfo.php' ]
   ```

------

1. Reserve tempo suficiente para que a instância seja executada e execute as diretivas nos dados de usuário. Depois, verifique se as diretivas concluíram as tarefas previstas.

   Para este exemplo, em um navegador da Web, insira a URL do arquivo de teste PHP criado pelas diretivas. Essa URL é o endereço DNS público da instância seguido por uma barra e o nome do arquivo.

   ```
   http://my.public.dns.amazonaws.com/phpinfo.php
   ```

   É necessário consultar a página de informações do PHP. Caso não seja possível visualizar a página de informações do PHP, verifique se o security group que você está usando contém uma regra para permitir tráfego HTTP (porta 80). Para obter mais informações, consulte [Configurar regras de grupos de segurança](changing-security-group.md#add-remove-security-group-rules).

1. (Opcional) Se as diretivas não tiverem realizado as tarefas que você esperava ou se você quiser simplesmente verificar se as diretivas foram concluídas sem erros, [conecte-se à instância](connect-to-linux-instance.md), examine o arquivo de log de saída (`/var/log/cloud-init-output.log`) e procure mensagens de erro na saída. Para informações adicionais de depuração, é possível adicionar a seguinte linha às diretivas:

   ```
   output : { all : '| tee -a /var/log/cloud-init-output.log' }
   ```

   Essa diretiva orientadora envia a saída **runcmd** para `/var/log/cloud-init-output.log`.

### Dados do usuário e AWS CLI
<a name="user-data-api-cli"></a>

É possível usar AWS CLI para especificar, modificar e ver os dados do usuário para sua instância. Para obter informações sobre como visualizar os dados do usuário da sua instância usando metadados de instância, consulte [Acessar metadados de instância para uma instância do EC2](instancedata-data-retrieval.md).

No Windows, é possível usar o AWS Tools for Windows PowerShell em vez de usar a AWS CLI. Para ter mais informações, consulte [Dados do usuário e Tools for Windows PowerShell](#user-data-powershell) .

**Exemplo: especificar dados do usuário na execução**  
Para especificar dados de usuário ao executar a instância, use o comando [run-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/run-instances.html) com o parâmetro `--user-data`. Com **run-instances**, a AWS CLI executa codificação de base64 dos dados de usuário para você.

O exemplo a seguir mostra como especificar um script como uma string na linha de comando:

```
aws ec2 run-instances --image-id ami-abcd1234 --count 1 --instance-type m3.medium \
    --key-name my-key-pair --subnet-id subnet-abcd1234 --security-group-ids sg-abcd1234 \
    --user-data echo user data
```

O exemplo a seguir mostra como especificar um script usando um arquivo de texto. Certifique-se de usar o prefixo `file://` para especificar o arquivo.

```
aws ec2 run-instances --image-id ami-abcd1234 --count 1 --instance-type m3.medium \
    --key-name my-key-pair --subnet-id subnet-abcd1234 --security-group-ids sg-abcd1234 \
    --user-data file://my_script.txt
```

A seguir, temos um exemplo de arquivo de texto com um script de shell.

```
#!/bin/bash
yum update -y
service httpd start
chkconfig httpd on
```

**Exemplo: modificar os dados do usuário de uma instância interrompida**  
É possível modificar os dados de usuário de uma instância interrompida usando o comando [modify-instance-attribute](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-attribute.html). Com **modify-instance-attribute**, a AWS CLI não executa a codificação de base64 dos dados de usuário para você.
+ Em um computador **Linux**, use o comando base64 para codificar os dados de usuário.

  ```
  base64 my_script.txt >my_script_base64.txt
  ```
+ Em um computador **Windows**, use o comando certutil para codificar os dados de usuário. Para poder usar esse arquivo com a AWS CLI, é necessário remover as primeiras (INICIAR CERTIFICADO) e últimas (ENCERRAR CERTIFICADO) linhas.

  ```
  certutil -encode my_script.txt my_script_base64.txt
  notepad my_script_base64.txt
  ```

Use os parâmetros `--attribute` e `--value` para usar o arquivo de texto codificado para especificar os dados de usuário. Certifique-se de usar o prefixo `file://` para especificar o arquivo.

```
aws ec2 modify-instance-attribute --instance-id i-1234567890abcdef0 --attribute userData --value file://my_script_base64.txt
```

**Exemplo: limpar os dados do usuário de uma instância interrompida**  
Para excluir os dados do usuário existentes, use o comando [modify-instance-attribute](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-attribute.html) da seguinte maneira:

```
aws ec2 modify-instance-attribute --instance-id i-1234567890abcdef0 --user-data Value=
```

**Exemplo: visualizar dados do usuário**  
Para recuperar os dados de usuário de uma instância, use o comando [describe-instance-attribute](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instance-attribute.html). Com **describe-instance-attribute**, a AWS CLI não executa a decodificação de base64 dos dados de usuário para você.

```
aws ec2 describe-instance-attribute --instance-id i-1234567890abcdef0 --attribute userData
```

Esta é uma saída de exemplo com dados de usuário com codificação base64.

```
{
    "UserData": {
        "Value": "IyEvYmluL2Jhc2gKeXVtIHVwZGF0ZSAteQpzZXJ2aWNlIGh0dHBkIHN0YXJ0CmNoa2NvbmZpZyBodHRwZCBvbg=="
    },
    "InstanceId": "i-1234567890abcdef0"
}
```
+ Em um computador **Linux**, use a opção `--query` para obter os dados de usuário codificados e o comando base64 para descodificá-los.

  ```
  aws ec2 describe-instance-attribute --instance-id i-1234567890abcdef0 --attribute userData --output text --query "UserData.Value" | base64 --decode
  ```
+ Em um computador **Windows**, use a opção `--query` para obter os dados de usuário codificados e o comando certutil para descodificá-los. Observe que a saída codificada está armazenada em um arquivo e a saída descodificada está armazenada em outro arquivo.

  ```
  aws ec2 describe-instance-attribute --instance-id i-1234567890abcdef0 --attribute userData --output text --query "UserData.Value" >my_output.txt
  certutil -decode my_output.txt my_output_decoded.txt
  type my_output_decoded.txt
  ```

O seguinte é um exemplo de saída.

```
#!/bin/bash
yum update -y
service httpd start
chkconfig httpd on
```

### Combinar scripts de shell e diretivas de cloud-init
<a name="user-data-mime-multi"></a>

Por padrão, você só pode incluir um tipo de conteúdo em dados de usuário de cada vez. Porém, você pode usar os tipos de conteúdo `text/cloud-config` e `text/x-shellscript` em um arquivo mime-multi part para incluir um script de shell e diretivas de cloud-init nos dados de usuário.

O exemplo a seguir mostra o formato mime-multi part.

```
Content-Type: multipart/mixed; boundary="//"
MIME-Version: 1.0
	
--//
Content-Type: text/cloud-config; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="cloud-config.txt"
	
#cloud-config
cloud-init directives
	
--//
Content-Type: text/x-shellscript; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="userdata.txt"
	
#!/bin/bash
shell script commands
--//--
```

Por exemplo, os seguintes dados de usuário incluem diretivas cloud-init e um script de shell bash. As diretivas cloud-init criam um arquivo (`/test-cloudinit/cloud-init.txt`) e gravam `Created by cloud-init` nesse arquivo. O script de shell bash cria um arquivo (`/test-userscript/userscript.txt`) e grava `Created by bash shell script` nesse arquivo.

```
Content-Type: multipart/mixed; boundary="//"
MIME-Version: 1.0
	
--//
Content-Type: text/cloud-config; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="cloud-config.txt"
	
#cloud-config
runcmd:
- [ mkdir, /test-cloudinit ]
write_files:
- path: /test-cloudinit/cloud-init.txt
content: Created by cloud-init
	
--//
Content-Type: text/x-shellscript; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="userdata.txt"
	
#!/bin/bash
mkdir test-userscript
touch /test-userscript/userscript.txt
echo "Created by bash shell script" >> /test-userscript/userscript.txt
--//--
```

## Como o Amazon EC2 lida com os dados dos usuários para instâncias do Windows
<a name="ec2-windows-user-data"></a>

Nas instâncias do Windows, o agente de inicialização executa as tarefas relacionadas aos dados do usuário. Para saber mais, consulte:
+ [EC2Launch v2](ec2launch-v2.md) 
+ [EC2Launch](ec2launch.md) 
+ [Serviço EC2Config](ec2config-service.md)

Para obter exemplos de assembly de uma propriedade `UserData` em um modelo do CloudFormation, consulte [Propriedade UserData codificada em Base64](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/quickref-general.html#scenario-userdata-base64) e [Propriedade UserData codificada em Base64 com AccessKey e SecretKey](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/quickref-general.html#scenario-userdata-base64-with-keys).

Para obter um exemplo de comandos de execução em uma instância dentro de um grupo do Auto Scaling que funciona com ganchos do ciclo de vida, consulte [Tutorial: Configure user data to retrieve the target lifecycle state through instance metadata](https://docs.aws.amazon.com/autoscaling/ec2/userguide/tutorial-lifecycle-hook-instance-metadata.html) no *Guia do usuário do Amazon EC2 Auto Scaling*.

**Topics**
+ [

### Scripts de dados do usuário
](#user-data-scripts)
+ [

### Dados de usuários compactados
](#user-data-compressed)
+ [

### Execução de dados do usuário
](#user-data-execution)
+ [

### Dados do usuário e Tools for Windows PowerShell
](#user-data-powershell)

### Scripts de dados do usuário
<a name="user-data-scripts"></a>

Para que o `EC2Config` ou o `EC2Launch` execute scripts, é necessário colocar o script em uma etiqueta especial ao adicioná-lo aos dados do usuário. A tag usada depende de os comandos serem executados em uma janela de prompt de comando (comandos de lote) ou usando o Windows PowerShell.

Se você especificar um script em lote e um script do Windows PowerShell, o script em lote é executado primeiro e o script do Windows PowerShell é executado em seguida, independentemente da ordem em que eles aparecem nos dados do usuário da instância.

Se você usar uma API da AWS, incluindo a AWS CLI, em um script de dados de usuário, deverá usar um perfil de instância ao inicializar a instância. Um perfil de instância fornece as credenciais apropriadas da AWS exigidas pelo script de dados do usuário para executar a chamada de API. Para obter mais informações, consulte [Perfis de instância](iam-roles-for-amazon-ec2.md#ec2-instance-profile). As permissões que atribui à função do IAM dependem de quais serviços você chama com a API. Para obter mais informações, consulte [Funções do IAM para Amazon EC2](iam-roles-for-amazon-ec2.md).

**Topics**
+ [

#### Sintaxe para scripts em lote
](#user-data-batch-scripts)
+ [

#### Sintaxe para scripts do Windows PowerShell
](#user-data-powershell-scripts)
+ [

#### Sintaxe para scripts de configuração YAML
](#user-data-yaml-scripts)
+ [

#### Codificação base64
](#user-data-base64-encoding)

#### Sintaxe para scripts em lote
<a name="user-data-batch-scripts"></a>

Especifique um script em lote usando a tag `script`. Separe os comandos usando quebras de linha, conforme mostrado no exemplo a seguir.

```
<script>
    echo Current date and time >> %SystemRoot%\Temp\test.log
    echo %DATE% %TIME% >> %SystemRoot%\Temp\test.log
</script>
```

Por padrão, os scripts de dados do usuário são executados uma vez ao inicializar a instância. Para executar os scripts de dados do usuário sempre que você reiniciar ou iniciar a instância, adicione `<persist>true</persist>` aos dados do usuário.

```
<script>
    echo Current date and time >> %SystemRoot%\Temp\test.log
    echo %DATE% %TIME% >> %SystemRoot%\Temp\test.log
</script>
<persist>true</persist>
```

**Agente do EC2Launch v2**  
Para executar um script de dados do usuário XML como um processo separado com a tarefa **executeScript** do EC2Launch v2 no estágio `UserData`, adicione `<detach>true</detach>` aos dados do usuário.

**nota**  
A tag detach não é compatível com agentes de inicialização anteriores.

```
<script>
    echo Current date and time >> %SystemRoot%\Temp\test.log
    echo %DATE% %TIME% >> %SystemRoot%\Temp\test.log
</script>
<detach>true</detach>
```

#### Sintaxe para scripts do Windows PowerShell
<a name="user-data-powershell-scripts"></a>

As AMIs do Windows da AWS incluem o [AWS Tools for Windows PowerShell](https://aws.amazon.com/powershell/) para que você possa especificar esses cmdlets nos dados do usuário. Se você associar uma função do IAM à sua instância, não será necessário especificar as credenciais para os cmdlets, pois os aplicações em execução na instância usam as credenciais da função para acessar os recursos da AWS (por exemplo, buckets do Amazon S3).

Especifique um script do Windows PowerShell usando a tag `<powershell>`. Separe os comandos usando quebras de linha. A tag `<powershell>` não diferencia maiúsculas de minúsculas.

Por exemplo:

```
<powershell>
    $file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
    New-Item $file -ItemType file
</powershell>
```

Por padrão, os scripts de dados do usuário são executados uma vez ao inicializar a instância. Para executar os scripts de dados do usuário sempre que você reiniciar ou iniciar a instância, adicione `<persist>true</persist>` aos dados do usuário.

```
<powershell>
    $file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
    New-Item $file -ItemType file
</powershell>
<persist>true</persist>
```

É possível especificar um ou mais argumentos do PowerShell com tag `<powershellArguments>`. Se nenhum argumento for passado, o EC2Launch e o EC2Launch v2 adicionarão o seguinte argumento por padrão: `-ExecutionPolicy Unrestricted`.

**Exemplo:**

```
<powershell>
    $file = $env:SystemRoot + "\Temp" + (Get-Date).ToString("MM-dd-yy-hh-mm")
    New-Item $file -ItemType file
</powershell>
<powershellArguments>-ExecutionPolicy Unrestricted -NoProfile -NonInteractive</powershellArguments>
```

**Agente do EC2Launch v2**  
Para executar um script de dados do usuário XML como um processo separado com a tarefa **executeScript** do EC2Launch v2 no estágio `UserData`, adicione `<detach>true</detach>` aos dados do usuário.

**nota**  
A tag detach não é compatível com agentes de inicialização anteriores.

```
<powershell>
    $file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
    New-Item $file -ItemType file
</powershell>
<detach>true</detach>
```

#### Sintaxe para scripts de configuração YAML
<a name="user-data-yaml-scripts"></a>

Se você estiver usando o EC2Launch v2 para executar scripts, poderá usar o formato YAML. Para visualizar tarefas de configuração, detalhes e exemplos do EC2Launch v2, consulte [Configuração de tarefas do EC2Launch v2](ec2launch-v2-settings.md#ec2launch-v2-task-configuration).

Especifique um script YAML com a tarefa `executeScript`.

**Exemplo de sintaxe do YAML para executar um script do PowerShell** 

```
version: 1.0
tasks:
- task: executeScript
  inputs:
  - frequency: always
    type: powershell
    runAs: localSystem
    content: |-
      $file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
      New-Item $file -ItemType file
```

**Exemplo de sintaxe do YAML para executar um script em lote**

```
version: 1.1
tasks:
- task: executeScript
  inputs:
  - frequency: always
    type: batch
    runAs: localSystem
    content: |-
      echo Current date and time >> %SystemRoot%\Temp\test.log
      echo %DATE% %TIME% >> %SystemRoot%\Temp\test.log
```

#### Codificação base64
<a name="user-data-base64-encoding"></a>

Se você estiver usando a API do Amazon EC2 ou uma ferramenta que não execute codificação base64 dos dados do usuário, codifique você mesmo os dados do usuário. Caso contrário, será registrado um erro sobre não ser possível encontrar as tags `script` ou `powershell` para executar. A seguir está um exemplo que codifica usando o Windows PowerShell.

```
$UserData = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($Script))
```

A seguir está um exemplo que decodifica usando o PowerShell.

```
$Script = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($UserData))
```

Para obter mais informações sobre a codificação base64, consulte [https://www.ietf.org/rfc/rfc4648.txt](https://www.ietf.org/rfc/rfc4648.txt).

### Dados de usuários compactados
<a name="user-data-compressed"></a>

O EC2Launch v2 é compatível com dados de usuário compactados como um método para enviar dados de usuários acima do limite de 16 KB imposto pelo IMDS. Para usar esse atributo, compacte o script de dados de usuário em um arquivo `.zip` e passe-o para a instância do EC2. Quando o EC2Launch v2 detecta dados de usuário compactados, ele automaticamente descompacta e executa o script compactado de dados de usuário.

Como acontece com os dados de usuário padrão, se estiver usando a API do Amazon EC2 ou uma ferramenta que não faça codificação base64 de dados do usuário, você mesmo deverá codificar os dados de usuário compactados. Para obter mais informações sobre o limite de tamanho dos dados de usuário e a codificação base64, consulte [Acessar metadados de instância para uma instância do EC2](instancedata-data-retrieval.md).

### Execução de dados do usuário
<a name="user-data-execution"></a>

Por padrão, todas as AMIs do Windows da AWS têm a execução de dados de usuário habilitada para a execução inicial. É possível especificar que os scripts de dados do usuário sejam executados na próxima vez que a instância for reiniciada. Também é possível especificar que os scripts de dados do usuário sejam executados toda vez que a instância for reiniciada.

**nota**  
Os dados do usuário não são habilitados para execução por padrão após a inicialização inicial. Para permitir que os dados do usuário sejam executados ao reinicializar ou iniciar a instância, consulte [Executar scripts durante inícios ou reinicializações subsequentes](#user-data-scripts-subsequent).

Os scripts de dados do usuário são executados na conta do administrador local quando uma senha aleatória é gerada. Caso contrário, os scripts de dados do usuário são executados na conta do sistema.

#### Scripts de execução de instância
<a name="user-data-scripts-launch"></a>

Os scripts nos dados do usuário da instância são executados durante a execução inicial da instância. Se a tag `persist` for localizada, a execução de dados do usuário será habilitada para reinicializações ou inicializações subsequentes. Os arquivos de log do EC2Launch v2, EC2Launch e EC2Config contêm a saída da saída padrão e dos fluxos de erro padrão.

**EC2Launch v2**  
O arquivo de log para EC2Launch v2 é `C:\ProgramData\Amazon\EC2Launch\log\agent.log`.

**nota**  
A pasta `C:\ProgramData` pode estar oculta. Para visualizar a pasta, é necessário mostrar arquivos e pastas ocultos.

As informações a seguir são registradas quando os dados do usuário são executados.
+ `Info: Converting user-data to yaml format` – Se os dados do usuário tiverem sido fornecidos no formato XML
+ `Info: Initialize user-data state`: o início da execução de dados do usuário
+ `Info: Frequency is: always` – Se a tarefa de dados do usuário estiver sendo executada em cada inicialização
+ `Info: Frequency is: once` – Se a tarefa de dados do usuário estiver sendo executada apenas uma vez
+ `Stage: postReadyUserData execution completed` – O final da execução de dados do usuário

**EC2Launch**  
O arquivo de log do EC2Launch é `C:\ProgramData\Amazon\EC2-Windows\Launch\Log\UserdataExecution.log`.

A pasta `C:\ProgramData` pode estar oculta. Para visualizar a pasta, é necessário mostrar arquivos e pastas ocultos.

As informações a seguir são registradas quando os dados do usuário são executados.
+ `Userdata execution begins`: o início da execução de dados do usuário
+ `<persist> tag was provided: true` –se a etiqueta persist for encontrada
+ `Running userdata on every boot` –se a etiqueta persist for encontrada
+ `<powershell> tag was provided.. running powershell content`: se a tag powershell for encontrada
+ `<script> tag was provided.. running script content` – se a etiqueta script for encontrada
+ `Message: The output from user scripts` – Se os scripts de dados do usuário forem executados, a saída será registrada

**EC2Config**  
O arquivo de log do EC2Config é `C:\Program Files\Amazon\Ec2ConfigService\Logs\Ec2Config.log`. As informações a seguir são registradas quando os dados do usuário são executados.
+ `Ec2HandleUserData: Message: Start running user scripts`: o início da execução de dados do usuário
+ `Ec2HandleUserData: Message: Re-enabled userdata execution` –se a etiqueta persist for encontrada
+ `Ec2HandleUserData: Message: Could not find <persist> and </persist>`: se a tag persist não for encontrada
+ `Ec2HandleUserData: Message: The output from user scripts` – Se os scripts de dados do usuário forem executados, a saída será registrada

#### Executar scripts durante inícios ou reinicializações subsequentes
<a name="user-data-scripts-subsequent"></a>

Quando você atualiza os dados de usuários da instância, o conteúdo atualizado desses dados é refletido automaticamente nos metadados da instância na próxima vez que você reinicializar ou iniciar a instância. Porém, dependendo do agente de inicialização instalado, pode ser necessária uma configuração adicional para configurar scripts de dados de usuários a serem executados em reinicializações ou inicializações subsequentes.

Se você escolher a opção **Desativar com Sysprep**, os scripts de dados do usuário serão executados na próxima vez que a instância for reiniciada ou iniciada, mesmo que você não tenha habilitado a execução de dados do usuário para reinicializações ou inicializações subsequentes.

Para obter instruções sobre como habilitar a execução de dados de usuários, selecione a guia que corresponde ao seu agente de lançamento.

------
#### [ EC2Launch v2 ]

Ao contrário de EC2Launch v1, EC2Launch v2 avalia a tarefa de dados de usuários em cada inicialização. Não é necessário programar manualmente a tarefa de dados de usuários. Os dados de usuários são executados com base na frequência incluída ou em opções de persistência.

Para scripts de dados de usuários de XML  
Para executar scripts de dados de usuários em cada inicialização, adicione o sinalizador `<persist>true</persist>` a esses dados. Se o sinalizador de persistência não estiver incluído, o script de dados de usuários será executado somente na inicialização inicial.

Para dados de usuários YAML  
+ Para executar uma tarefa em dados de usuários na inicialização inicial, defina a tarefa `frequency` como `once`.
+ Para executar uma tarefa em dados de usuários em cada inicialização, defina `frequency` como `always`.

------
#### [ EC2Launch ]

1. Conecte-se à sua instância do Windows.

1. Abra uma janela de comando do PowerShell e execute um dos seguintes comandos:

**Executar uma vez**  
Para executar dados de usuários uma vez na próxima inicialização, use o sinalizador `-Schedule`.

   ```
   C:\ProgramData\Amazon\EC2-Windows\Launch\Scripts\InitializeInstance.ps1 -Schedule
   ```

**Executar em todas as inicializações subsequentes**  
Para executar dados de usuários em todas as inicializações subsequentes, use o sinalizador `-SchedulePerBoot`.

   ```
   C:\ProgramData\Amazon\EC2-Windows\Launch\Scripts\InitializeInstance.ps1 -SchedulePerBoot
   ```

1. Desconecte-se da instância do Windows. Para executar scripts atualizados na próxima vez que a instância for iniciada, interrompa a instância e atualize os dados do usuário.

------
#### [ EC2Config ]

1. Conecte-se à sua instância do Windows.

1. Aberto `C:\Program Files\Amazon\Ec2ConfigService\Ec2ConfigServiceSetting.exe`.

1. Em **User Data (Dados do usuário)**, selecione **Enable UserData execution for next service start (Habilitar execução de dados do usuário para o próximo início de serviço)**.

1. Desconecte-se da instância do Windows. Para executar scripts atualizados na próxima vez que a instância for iniciada, interrompa a instância e atualize os dados do usuário.

------

### Dados do usuário e Tools for Windows PowerShell
<a name="user-data-powershell"></a>

É possível usar Tools for Windows PowerShell para especificar, modificar e ver os dados do usuário para sua instância. Para obter informações sobre como visualizar os dados do usuário da sua instância usando metadados de instância, consulte [Acessar metadados de instância para uma instância do EC2](instancedata-data-retrieval.md). Para obter informações sobre os dados do usuário e a AWS CLI, consulte [Dados do usuário e AWS CLI](#user-data-api-cli).

**Exemplo: especifique os dados do usuário da instância no lançamento**  
Crie um arquivo de texto com dados do usuário da instância. Para executar os scripts de dados do usuário sempre que você reiniciar ou iniciar a instância, adicione `<persist>true</persist>`, como mostrado no exemplo a seguir:

```
<powershell>
    $file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
    New-Item $file -ItemType file
</powershell>
<persist>true</persist>
```

Para especificar dados do usuário da instância ao executar a instância, use o comando [New-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/New-EC2Instance.html). Esse comando não executa a codificação base64 dos dados do usuário para você. Use os comandos a seguir para codificar os dados do usuário em um arquivo de texto denominado `script.txt`.

```
PS C:\> $Script = Get-Content -Raw script.txt
PS C:\> $UserData = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($Script))
```

Use o parâmetro `-UserData` para passar os dados do usuário para o comando **New-EC2Instance**.

```
PS C:\> New-EC2Instance -ImageId ami-abcd1234 -MinCount 1 -MaxCount 1 -InstanceType m3.medium \
    -KeyName my-key-pair -SubnetId subnet-12345678 -SecurityGroupIds sg-1a2b3c4d \
    -UserData $UserData
```

**Exemplo: atualizar dados do usuário da instância para uma instância interrompida**  
É possível modificar os dados do usuário de uma instância interrompida usando o comando [Edit-EC2InstanceAttribute](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceAttribute.html).

Crie um arquivo de texto com o novo script. Use os comandos a seguir para codificar os dados do usuário no arquivo de texto denominado `new-script.txt`.

```
PS C:\> $NewScript = Get-Content -Raw new-script.txt
PS C:\> $NewUserData = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($NewScript))
```

Use os parâmetros `-UserData` e `-Value` para especificar os dados do usuário.

```
PS C:\> Edit-EC2InstanceAttribute -InstanceId i-1234567890abcdef0 -Attribute userData -Value $NewUserData
```

**Exemplo: visualizar dados do usuário da instância**  
Para recuperar os dados do usuário para uma instância, use o comando [Get-EC2InstanceAttribute](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2InstanceAttribute.html).

```
PS C:\> (Get-EC2InstanceAttribute -InstanceId i-1234567890abcdef0 -Attribute userData).UserData
```

A seguir está um exemplo de saída. Observe que os dados do usuário são codificados.

```
PHBvd2Vyc2hlbGw+DQpSZW5hbWUtQ29tcHV0ZXIgLU5ld05hbWUgdXNlci1kYXRhLXRlc3QNCjwvcG93ZXJzaGVsbD4=
```

Use os comandos a seguir para armazenar os dados de usuário codificados em uma variável e decodifique-os.

```
PS C:\> $UserData_encoded = (Get-EC2InstanceAttribute -InstanceId i-1234567890abcdef0 -Attribute userData).UserData
PS C:\> [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($UserData_encoded))
```

A seguir está um exemplo de saída.

```
<powershell>
    $file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
    New-Item $file -ItemType file
</powershell>
<persist>true</persist>
```

**Exemplo: renomear a instância para corresponder ao valor da tag**  
É possível usar o comando [Get-EC2Tag](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2Tag.html) para ler o valor da tag. Renomeie a instância na primeira inicialização para corresponder ao valor da tag e reinicialize. Para executar esse comando com êxito, é necessário ter uma função com permissões `ec2:DescribeTags` vinculadas à instância, pois as informações de tag são recuperadas pela chamada de API. Para obter mais informações sobre as permissões de configuração ao usar perfis do IAM, consulte [Anexar uma função do IAM a uma instância](attach-iam-role.md).

------
#### [ IMDSv2 ]

```
<powershell>
    [string]$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri 'http://169.254.169.254/latest/api/token' -UseBasicParsing
    $instanceId = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri 'http://169.254.169.254/latest/meta-data/instance-id' -UseBasicParsing
	$nameValue = (Get-EC2Tag -Filter @{Name="resource-id";Value=$instanceid},@{Name="key";Value="Name"}).Value
	$pattern = "^(?![0-9]{1,15}$)[a-zA-Z0-9-]{1,15}$"
	#Verify Name Value satisfies best practices for Windows hostnames
	If ($nameValue -match $pattern) 
	    {Try
	        {Rename-Computer -NewName $nameValue -Restart -ErrorAction Stop} 
	    Catch
	        {$ErrorMessage = $_.Exception.Message
	        Write-Output "Rename failed: $ErrorMessage"}}
	Else
	    {Throw "Provided name not a valid hostname. Please ensure Name value is between 1 and 15 characters in length and contains only alphanumeric or hyphen characters"}
</powershell>
```

------
#### [ IMDSv1 ]

```
<powershell>
	$instanceId = (Invoke-WebRequest http://169.254.169.254/latest/meta-data/instance-id -UseBasicParsing).content
	$nameValue = (Get-EC2Tag -Filter @{Name="resource-id";Value=$instanceid},@{Name="key";Value="Name"}).Value
	$pattern = "^(?![0-9]{1,15}$)[a-zA-Z0-9-]{1,15}$"
	#Verify Name Value satisfies best practices for Windows hostnames
	If ($nameValue -match $pattern) 
	    {Try
	        {Rename-Computer -NewName $nameValue -Restart -ErrorAction Stop} 
	    Catch
	        {$ErrorMessage = $_.Exception.Message
	        Write-Output "Rename failed: $ErrorMessage"}}
	Else
	    {Throw "Provided name not a valid hostname. Please ensure Name value is between 1 and 15 characters in length and contains only alphanumeric or hyphen characters"}
</powershell>
```

------

Também é possível renomear a instância usando tags em metadados de instância, se sua instância estiver configurada para acessar tags a partir dos metadados da instância. Para obter mais informações, consulte [Visualizar tags para as instâncias do EC2 usando os metadados de instância](work-with-tags-in-IMDS.md).

------
#### [ IMDSv2 ]

```
<powershell>
    [string]$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri 'http://169.254.169.254/latest/api/token' -UseBasicParsing
	$nameValue = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri 'http://169.254.169.254/latest/meta-data/tags/instance/Name' -UseBasicParsing
	$pattern = "^(?![0-9]{1,15}$)[a-zA-Z0-9-]{1,15}$"
	#Verify Name Value satisfies best practices for Windows hostnames
	If ($nameValue -match $pattern) 
	    {Try
	        {Rename-Computer -NewName $nameValue -Restart -ErrorAction Stop} 
	    Catch
	        {$ErrorMessage = $_.Exception.Message
	        Write-Output "Rename failed: $ErrorMessage"}}
	Else
	    {Throw "Provided name not a valid hostname. Please ensure Name value is between 1 and 15 characters in length and contains only alphanumeric or hyphen characters"}
</powershell>
```

------
#### [ IMDSv1 ]

```
<powershell>
	$nameValue = Get-EC2InstanceMetadata -Path /tags/instance/Name
	$pattern = "^(?![0-9]{1,15}$)[a-zA-Z0-9-]{1,15}$"
	#Verify Name Value satisfies best practices for Windows hostnames
	If ($nameValue -match $pattern) 
	    {Try
	        {Rename-Computer -NewName $nameValue -Restart -ErrorAction Stop} 
	    Catch
	        {$ErrorMessage = $_.Exception.Message
	        Write-Output "Rename failed: $ErrorMessage"}}
	Else
	    {Throw "Provided name not a valid hostname. Please ensure Name value is between 1 and 15 characters in length and contains only alphanumeric or hyphen characters"}
</powershell>
```

------

# Identificar cada instância executada em uma única solicitação
<a name="AMI-launch-index-examples"></a>

Este exemplo demonstra como usar dados do usuário e metadados de instância para configurar as instâncias do Amazon EC2.

**nota**  
Os exemplos nesta seção usam o endereço IPv4 do 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](instance-types.md#instance-hypervisor-type) em [sub-redes compatíveis com IPv6](https://docs.aws.amazon.com/vpc/latest/userguide/configure-subnets.html#subnet-ip-address-range) (pilha dupla ou IPv6 apenas).

Alice deseja executar quatro instâncias de sua AMI de banco de dados favorita, em que a primeira atua como a instância original e as três restantes como réplicas. Ao executá-las, ela deseja adicionar dados do usuário sobre a estratégia de replicação para cada réplica. Ela sabe que esses dados estarão disponíveis para todas as quatro instâncias, então, ela precisa estruturar os dados do usuário de forma que permita a cada instância reconhecer quais partes são aplicáveis a ela. Ela pode fazer isso usando o valor de metadados da instância `ami-launch-index`, que será exclusivo para cada instância. Se você iniciar mais de uma instância ao mesmo tempo, o `ami-launch-index`indicará a ordem em que as instâncias foram executadas. O valor da primeira instância iniciada é `0`.

Veja a seguir os dados de usuário construídos por Alice.

```
replicate-every=1min | replicate-every=5min | replicate-every=10min
```

Os dados `replicate-every=1min` definem a configuração da primeira réplica, `replicate-every=5min` definem a configuração da segunda réplica e assim por diante. Alice decide fornecer esses dados como uma string ASCII com um símbolo de pipe (`|`) que limita os dados para as instâncias separadas.

Alice executa quatro instâncias usando o comando [run-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/run-instances.html) e especificando os dados do usuário.

```
aws ec2 run-instances \
    --image-id ami-0abcdef1234567890 \
    --count 4 \
    --instance-type t2.micro \
    --user-data "replicate-every=1min | replicate-every=5min | replicate-every=10min"
```

Depois de executadas, todas as instâncias têm uma cópia dos dados do usuário e os metadados comuns mostrados aqui:
+ ID da AMI: ami-0abcdef1234567890
+ ID da reserva: r-1234567890abcabc0
+ Chaves públicas: nenhuma 
+ Nome do security group: padrão
+ Tipo de instância: t2.micro

No entanto, cada instância tem metadados exclusivos, conforme mostrado nas tabelas a seguir.


| Metadados | Valor | 
| --- | --- | 
| instance-id | i-1234567890abcdef0 | 
| ami-launch-index | 0 | 
| public-hostname | ec2-203-0-113-25.compute-1.amazonaws.com | 
| public-ipv4 | 67.202.51.223 | 
| local-hostname | ip-10-251-50-12.ec2.internal | 
| local-ipv4 | 10.251.50.35 | 


| Metadados | Valor | 
| --- | --- | 
| instance-id | i-0598c7d356eba48d7 | 
| ami-launch-index | 1 | 
| public-hostname | ec2-67-202-51-224.compute-1.amazonaws.com | 
| public-ipv4 | 67.202.51.224 | 
| local-hostname | ip-10-251-50-36.ec2.internal | 
| local-ipv4 | 10.251.50.36 | 


| Metadados | Valor | 
| --- | --- | 
| instance-id | i-0ee992212549ce0e7 | 
| ami-launch-index | 2 | 
| public-hostname | ec2-67-202-51-225.compute-1.amazonaws.com | 
| public-ipv4 | 67.202.51.225 | 
| local-hostname | ip-10-251-50-37.ec2.internal | 
| local-ipv4 | 10.251.50.37 | 


| Metadados | Valor | 
| --- | --- | 
| instance-id | i-1234567890abcdef0 | 
| ami-launch-index | 3 | 
| public-hostname | ec2-67-202-51-226.compute-1.amazonaws.com | 
| public-ipv4 | 67.202.51.226 | 
| local-hostname | ip-10-251-50-38.ec2.internal | 
| local-ipv4 | 10.251.50.38 | 

Alice pode usar o valor `ami-launch-index` para determinar qual parte dos dados do usuário é aplicável a uma instância específica.

1. Ela se conecta a uma das instâncias e recupera o `ami-launch-index` dessa instância para garantir que ela seja uma das réplicas:

------
#### [ IMDSv2 ]

   ```
   [ec2-user ~]$ TOKEN=`curl -X PUT "http://169.254.169.254/latest/meta-data/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-launch-index
   2
   ```

   Para as etapas a seguir, as solicitações do IMDSv2 usam o token armazenado do comando anterior do IMDSv2, supondo-se que o token não tenha expirado.

------
#### [ IMDSv1 ]

   ```
   [ec2-user ~]$ curl http://169.254.169.254/latest/meta-data/ami-launch-index
   2
   ```

------

1. Ela salva o `ami-launch-index` como uma variável.

------
#### [ IMDSv2 ]

   ```
   [ec2-user ~]$ ami_launch_index=`curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/ami-launch-index`
   ```

------
#### [ IMDSv1 ]

   ```
   [ec2-user ~]$ ami_launch_index=`curl http://169.254.169.254/latest/meta-data/ami-launch-index`
   ```

------

1. Ela salva os dados do usuário como uma variável.

------
#### [ IMDSv2 ]

   ```
   [ec2-user ~]$ user_data=`curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/user-data`
   ```

------
#### [ IMDSv1 ]

   ```
   [ec2-user ~]$ user_data=`curl http://169.254.169.254/latest/user-data`
   ```

------

1. Finalmente, Alice usa o comando **cut** para extrair a parte dos dados do usuário aplicável à instância.

------
#### [ IMDSv2 ]

   ```
   [ec2-user ~]$ echo $user_data | cut -d"|" -f"$ami_launch_index"
   replicate-every=5min
   ```

------
#### [ IMDSv1 ]

   ```
   [ec2-user ~]$ echo $user_data | cut -d"|" -f"$ami_launch_index"
   replicate-every=5min
   ```

------