As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Configurar imagens personalizadas com o Image Builder
Os recursos de configuração são os componentes básicos dos pipelines de imagens, bem como as imagens que esses pipelines produzem. Este capítulo aborda a criação, manutenção e compartilhamento de recursos do Image Builder, incluindo componentes, fórmulas e imagens, além de configurações de infraestrutura e configurações de distribuição.
**nota**
Para ajudar você a gerenciar os recursos do Image Builder, é possível atribuir seus próprios metadados a cada recurso na forma de tags. Você pode usar etiquetas para categorizar seus recursos da AWS de diferentes formas, como por finalidade, proprietário ou ambiente. Isso é útil quando você tem muitos recursos do mesmo tipo. Identifique rapidamente um recurso específico com base nas tags atribuídas a ele.
Para obter mais informações sobre como marcar seus recursos usando os comandos do Image Builder no AWS CLI, consulte a [Marcar recursos](tag-resources.md) seção deste guia.
**Topics**
+ [
# Gerenciar fórmulas no Image Builder
](manage-recipes.md)
+ [
# Gerenciar a configuração da infraestrutura do Image Builder
](manage-infra-config.md)
+ [
# Gerenciar as configurações de distribuição do Image Builder
](manage-distribution-settings.md)
# Gerenciar fórmulas no Image Builder
Uma receita do EC2 Image Builder define a imagem base a ser usada como ponto de partida para criar uma nova imagem, junto com o conjunto de componentes que você adiciona para personalizar sua imagem e verificar se tudo funciona conforme o esperado. O Image Builder fornece opções automáticas de versão para cada componente. Por padrão, você pode aplicar até vinte componentes a uma fórmula. Isso inclui componentes de compilação e teste.
Depois de criar uma fórmula, não é possível modificá-la ou substituí-la. Para atualizar os componentes depois de criar uma fórmula, você deve criar uma nova fórmula ou versão da fórmula. Você sempre pode aplicar tags às fórmulas existentes. Para obter mais informações sobre como marcar seus recursos usando os comandos do Image Builder no AWS CLI, consulte a [Marcar recursos](tag-resources.md) seção deste guia.
**dica**
Você pode usar componentes gerenciados pela Amazon em suas receitas ou desenvolver seus próprios componentes personalizados. Para obter mais informações, consulte [Desenvolver componentes personalizados para imagens do Image Builder](create-custom-components.md). Para receitas de imagens que criam saída AMIs, você também pode usar produtos e componentes de AWS Marketplace imagem. Para obter mais informações sobre integração com AWS Marketplace produtos, consulte[AWS Marketplace integração no Image Builder](integ-marketplace.md).
Esta seção aborda como listar, visualizar e criar fórmulas.
**Topics**
+ [
# Liste e visualize detalhes da fórmula da imagem
](image-recipe-details.md)
+ [
# Liste e visualize detalhes da fórmula de contêiner
](container-recipe-details.md)
+ [
# Criar uma nova versão de uma fórmula de imagem
](create-image-recipes.md)
+ [
# Criar uma nova versão de fórmula de contêiner
](create-container-recipes.md)
+ [
## Limpar recursos
](#recipes-cleanup)
# Liste e visualize detalhes da fórmula da imagem
Esta seção descreve as várias maneiras pelas quais você pode encontrar informações e visualizar detalhes de suas fórmulas de imagem do EC2 Image Builder.
**Topics**
+ [
## Listar fórmulas de imagem com o console
](#list-image-recipes-console)
+ [
## Listar receitas de imagens do AWS CLI
](#cli-list-image-recipes)
+ [
## Visualizar detalhes da fórmula de imagem com o console
](#view-image-recipe-details-console)
+ [
## Obtenha detalhes da receita da imagem no AWS CLI
](#cli-get-image-recipe)
+ [
## Obtenha detalhes da política de receitas de imagens no AWS CLI
](#cli-get-image-recipe-policy)
## Listar fórmulas de imagem com o console
Para ver uma lista das fórmulas de imagem que foram criadas em sua conta no console do Image Builder, siga estas etapas:
1. Abra o console [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/)do EC2 Image Builder em.
1. Escolha **Fórmulas de imagem** do painel de navegação. Isso mostra uma lista das fórmulas de imagem criadas em sua conta.
1. Para ver detalhes ou criar uma nova versão da fórmula, escolha o link **Nome da fórmula**. Isso abre a visualização de detalhes da fórmula.
**nota**
Você também pode selecionar a caixa ao lado de **Nome da fórmula**, depois escolher **Visualizar detalhes**.
## Listar receitas de imagens do AWS CLI
O exemplo a seguir mostra como listar todas as fórmulas de imagem usando a AWS CLI.
```
aws imagebuilder list-image-recipes
```
## Visualizar detalhes da fórmula de imagem com o console
Para ver detalhes de uma fórmula de imagem específica usando o console do Image Builder, selecione a fórmula de imagem a ser revisada e use as etapas descritas em [Listar fórmulas de imagem com o console](#list-image-recipes-console).
Na página de detalhes da fórmula, você pode:
+ Excluir a fórmula. Para obter mais informações sobre exclusão de recursos no Image Builder, consulte [Excluir recursos desatualizados ou não utilizados do Image Builder](delete-resources.md).
+ Criar uma nova versão.
+ Criar um pipeline a partir da fórmula. Depois de escolher **Criar pipeline a partir desta fórmula**, você será direcionado para o assistente de pipeline. Para obter mais informações sobre como criar um pipeline do Image Builder usando o assistente de pipeline, consulte [Tutorial: criar um pipeline de imagens com a AMI de saída por meio do assistente do console do Image Builder](start-build-image-pipeline.md)
**nota**
Quando você cria um pipeline a partir de uma fórmula existente, a opção de criar uma nova fórmula não está disponível.
## Obtenha detalhes da receita da imagem no AWS CLI
O exemplo a seguir mostra como usar um comando CLI **imagebuilder** para obter os detalhes de uma fórmula de imagem especificando seu nome do recurso da Amazon (ARN).
```
aws imagebuilder get-image-recipe --image-recipe-arn arn:aws:imagebuilder:us-west-2:123456789012:image-recipe/my-example-recipe/2020.12.03
```
## Obtenha detalhes da política de receitas de imagens no AWS CLI
O exemplo a seguir mostra como usar um comando CLI **imagebuilder** para obter os detalhes de uma política de fórmula especificando seu ARN.
```
aws imagebuilder get-image-recipe-policy --image-recipe-arn arn:aws:imagebuilder:us-west-2:123456789012:image-recipe/my-example-recipe/2020.12.03
```
# Liste e visualize detalhes da fórmula de contêiner
Esta seção descreve as maneiras pelas quais você pode encontrar informações e visualizar detalhes de suas fórmulas de contêiner do EC2 Image Builder.
**Topics**
+ [
## Liste as fórmulas de contêiner no console
](#list-container-recipes-console)
+ [
## Liste as receitas de contêineres com o AWS CLI
](#cli-list-container-recipes)
+ [
## Visualizar detalhes da fórmula de contêiner no console
](#view-container-recipe-details-console)
+ [
## Obtenha detalhes da receita do recipiente com o AWS CLI
](#cli-get-container-recipe)
+ [
## Obtenha detalhes da política de receitas de contêineres com o AWS CLI
](#cli-get-container-recipe-policy)
## Liste as fórmulas de contêiner no console
Para ver uma lista das fórmulas de contêiner que foram criadas em sua conta no console do Image Builder, siga estas etapas:
1. Abra o console [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/)do EC2 Image Builder em.
1. Escolha **Fórmulas de contêiner** do painel de navegação. Isso mostra uma lista das fórmulas de contêiner criadas em sua conta.
1. Para ver detalhes ou criar uma nova versão da fórmula, escolha o link **Nome da fórmula**. Isso abre a visualização de detalhes da fórmula.
**nota**
(Você também pode selecionar a caixa ao lado de **Nome da fórmula**, e depois escolher **Exibir detalhes**.
## Liste as receitas de contêineres com o AWS CLI
O exemplo a seguir mostra como listar todas as fórmulas de contêiner, usando a AWS CLI.
```
aws imagebuilder list-container-recipes
```
## Visualizar detalhes da fórmula de contêiner no console
Para visualizar detalhes de uma fórmula de contêiner específica com o console do Image Builder, selecione a fórmula de contêiner a ser visualizada e use as etapas descritas em [Liste as fórmulas de contêiner no console](#list-container-recipes-console).
Na página de detalhes da fórmula, você pode fazer o seguinte:
+ Excluir a fórmula. Para obter mais informações sobre como excluir recursos no Image Builder, consulte [Excluir recursos desatualizados ou não utilizados do Image Builder](delete-resources.md).
+ Criar uma nova versão.
+ Criar um pipeline a partir da fórmula. Depois de escolher **Criar pipeline a partir desta fórmula**, você será direcionado para o assistente de pipeline. Para obter mais informações sobre como criar um pipeline do Image Builder usando o assistente de pipeline, consulte [Tutorial: criar um pipeline de imagens com a AMI de saída por meio do assistente do console do Image Builder](start-build-image-pipeline.md)
**nota**
Quando você cria um pipeline a partir de uma fórmula existente, a opção de criar uma nova fórmula não está disponível.
## Obtenha detalhes da receita do recipiente com o AWS CLI
O exemplo a seguir mostra como usar um comando CLI **imagebuilder** para obter os detalhes de uma fórmula de contêiner especificando seu ARN.
```
aws imagebuilder get-container-recipe --container-recipe-arn arn:aws:imagebuilder:us-west-2:123456789012:container-recipe/my-example-recipe/2020.12.03
```
## Obtenha detalhes da política de receitas de contêineres com o AWS CLI
O exemplo a seguir mostra como usar um comando CLI **imagebuilder** para obter os detalhes de uma política da fórmula de contêiner especificando seu ARN.
```
aws imagebuilder get-container-recipe-policy --container-recipe-arn arn:aws:imagebuilder:us-west-2:123456789012:container-recipe/my-example-recipe/2020.12.03
```
# Criar uma nova versão de uma fórmula de imagem
Esta seção descreve como criar uma nova versão de uma fórmula de imagem.
**Topics**
+ [
## Criar uma versão de uma fórmula de imagem com o console
](#create-image-recipe-version-console)
+ [
## Crie uma receita de imagem com o AWS CLI
](#create-image-recipe-cli)
+ [
## Importar uma VM como sua imagem de base no console
](#import-vm-recipes)
## Criar uma versão de uma fórmula de imagem com o console
Quando você cria uma nova versão de fórmula, é praticamente o mesmo que criar uma nova fórmula. A diferença é que certos detalhes são pré-selecionados para corresponder à fórmula de base, na maioria dos casos. A lista a seguir descreve as diferenças entre criar uma nova fórmula e criar uma nova versão de uma fórmula existente.
**Detalhes da fórmula de base na nova versão**
+ **Nome**: *não editável*.
+ **Versão**: obrigatória. Insira o número da versão que você deseja criar no formato *..*. O Image Builder oferece suporte ao incremento automático de versões para receitas, permitindo que você use padrões curinga em suas versões de receitas. Quando você cria uma receita com uma versão curinga`1.0.x`, como, por exemplo, Image Builder incrementa automaticamente a versão (por exemplo,, `1.0.1` `1.0.2``1.0.3`, e assim por diante). Isso elimina a necessidade de rastrear e incrementar manualmente as versões da receita.
+ A opção **Selecionar imagem**: pré-selecionada, mas você pode editá-la. Se você alterar sua escolha para a fonte da imagem de base, você poderá perder outros detalhes que dependem da opção original escolhida por você.
Para ver detalhes associados à seleção imagem base, escolha a guia que corresponde à sua seleção.
------
#### [ Managed image ]
+ **Sistema operacional (OS) de imagem**: *não editável*.
+ **Nome da imagem**: pré-selecionado, com base na combinação de opções de imagem de base que você fez para a fórmula existente. No entanto, se você alterar a opção **Selecionar imagem**, você perderá o **Nome da imagem** pré-selecionado.
+ **Opções de autoversionamento**: *não* corresponde à sua fórmula de base. Essa opção de imagem usa como padrão a opção **Usar versão do OS selecionada**.
**Importante**
Se você estiver usando o auto-versionamento semântico para iniciar as compilações do pipeline, certifique-se de alterar esse valor para **Usar a versão do OS mais recente disponível**. Para saber mais sobre o versionamento semântico dos recursos do Image Builder, consulte [Versionamento semântico no Image Builder](ibhow-semantic-versioning.md).
------
#### [ AWS Marketplace image ]
+ **Assinaturas** — Essa guia deve estar aberta e a imagem assinada AWS Marketplace deve ser pré-selecionada para corresponder à sua receita base. Se você alterar a imagem que sua fórmula usa como imagem de base, você pode perder outros detalhes que dependem da imagem original que você escolheu.
Para obter mais informações sobre AWS Marketplace produtos, consulte [Comprar produtos](https://docs.aws.amazon.com/marketplace/latest/buyerguide/buyer-subscribing-to-products.html) no *Guia do AWS Marketplace comprador*.
------
#### [ Custom AMI ]
**Fonte da AMI** (obrigatória) - insira a ID da AMI ou um parâmetro AWS Systems Manager (SSM) do Parameter Store que contém uma ID da AMI para usar como imagem base. O agente SSM deve estar pré-instalado na AMI selecionada.
+ **ID AMI** — Essa configuração não está pré-preenchida com sua entrada original. Insira o ID da AMI para sua imagem base. Exemplo: `ami-1234567890abcdef1`.
+ **Parâmetro SSM** — Insira o nome ou ARN do parâmetro SSM Parameter Store que contém o ID da AMI para sua imagem base. Exemplo: `/ib/test/param` ou `arn:aws:ssm:us-east-1:111122223333:parameter/ib/test/param`.
------
+ **Configuração da instância**: as configurações são pré-selecionadas, mas você pode editá-las.
+ **Atendente do Systems Manager**: você pode marcar ou desmarcar essa caixa de seleção para controlar a instalação do atendente do Systems Manager na nova imagem. A caixa de seleção é desmarcada por padrão para incluir o atendente do Systems Manager em sua nova imagem. Para remover o atendente do Systems Manager da imagem final, marque a caixa de seleção para que o atendente não seja incluído na sua AMI.
+ **Dados do usuário**: você pode usar essa área para fornecer comandos, ou um script de comando a executar, quando você inicializa sua instância de compilação. No entanto, esse valor substitui qualquer comando que o Image Builder possa ter adicionado para garantir que o Systems Manager seja instalado. Esses comandos incluem o script de limpeza que o Image Builder normalmente executa para imagens do Linux antes de criar a nova imagem.
Quando o Image Builder inicia uma instância, os scripts de dados do usuário são executados durante a fase de inicialização da nuvem, antes do início da execução do componente. Essa etapa é registrada no seguinte arquivo na instância:`var/log/cloud-init.log`.
**nota**
Se você inserir dados do usuário, certifique-se de que o atendente do Systems Manager esteja pré-instalado na imagem de base ou que você inclua a instalação nos dados do usuário.
Para imagens do Linux, certifique-se de que as etapas de limpeza sejam executadas incluindo um comando para criar um arquivo vazio nomeado `perform_cleanup` no script de dados do usuário. O Image Builder detecta esse arquivo e executa o script de limpeza antes de criar a nova imagem. Para obter mais informações e um exemplo de script, consulte [Práticas recomendadas de segurança para o Image Builder](security-best-practices.md).
+ **Diretório de trabalho**: pré-selecionado, mas você pode editá-lo.
+ **Componentes**: os componentes que já estão incluídos na fórmula são exibidos na seção **Componentes selecionados** no final de cada uma das listas de componentes (compilação e teste). Você pode remover ou reordenar os componentes selecionados para atender às suas necessidades.
Os componentes de endurecimento do CIS não seguem as regras padrão de ordenação de componentes nas fórmulas do Image Builder. Os componentes de endurecimento do CIS sempre são executados por último para garantir que os testes de benchmark sejam executados em relação à sua imagem de saída.
**nota**
As listas de componentes de compilação e teste exibem os componentes disponíveis com base no tipo de proprietário do componente. Para adicionar um componente, escolha **Adicionar componentes de construção** e selecione o filtro de propriedade aplicável. Por exemplo, para adicionar um componente de compilação associado a um AWS Marketplace produto, selecione`AWS Marketplace`. Isso abre um painel de seleção no lado direito da interface do console que lista AWS Marketplace os componentes.
Para o componente CIS, selecione`Third party managed`.
Você pode definir as seguintes configurações para seu componente selecionado:
+ **Opções de versionamento**: pré-selecionadas, mas você pode alterá-las. Recomendamos que você escolha a opção **Usar a versão mais recente disponível do componente** para garantir que suas compilações de imagem sempre usem a versão mais recente do componente. Se precisar usar uma versão específica do componente em sua fórmula, você pode escolher **Especificar versão do componente** e inserir a versão na caixa **Versão do componente** que aparece.
+ **Parâmetros de entrada**: exibe os parâmetros de entrada que o componente aceita. O **Valor** é pré-preenchido com o valor da versão anterior da fórmula. Se você estiver usando esse componente pela primeira vez nessa fórmula e um valor padrão tiver sido definido para o parâmetro de entrada, o valor padrão aparecerá na caixa **Valor** com texto acinzentado. Se nenhum outro valor for inserido, o Image Builder usará o valor padrão.
Se um parâmetro de entrada for necessário, mas não tiver um valor padrão definido no componente, você deverá fornecer um valor. O Image Builder não criará a versão da fórmula se algum parâmetro obrigatório estiver faltando e não houver um valor padrão definido.
**Importante**
Os parâmetros do componente são valores de texto simples e estão logados em AWS CloudTrail. Recomendamos que você use AWS Secrets Manager ou o AWS Systems Manager Parameter Store para armazenar seus segredos. Para obter mais informações sobre o Secrets Manager, consulte [O que é o Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) no *AWS Secrets Manager Guia do usuário*. Para obter mais informações sobre o AWS Systems Manager Parameter Store, consulte [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) no *AWS Systems Manager Guia do usuário*.
Para expandir as configurações das **opções de versionamento** ou **dos parâmetros de entrada**, você pode escolher a seta ao lado do nome da configuração. Para expandir todas as configurações de todos os componentes selecionados, você pode ativar e desativar a opção **Expandir tudo**.
+ **Armazenamento (volumes)**: são pré-preenchidos. As seleções **Nome do dispositivo**, **Snapshot** e **IOPS** do volume raiz não são editáveis. No entanto, você pode alterar todas as demais configurações, como o **Tamanho**. Você também pode adicionar novos volumes e criptografar volumes novos ou existentes.
Para criptografar volumes para as imagens que o Image Builder cria em sua conta na região de origem (onde a compilação é executada), você deve usar a criptografia do volume de armazenamento na fórmula de imagem. A criptografia executada durante a fase de distribuição da compilação é somente para imagens que são distribuídas para outras contas ou regiões.
**nota**
Se você usar criptografia para seus volumes, deverá selecionar a chave de cada volume separadamente, mesmo que a chave seja a mesma usada para o volume-raiz.
**Para criar uma nova versão de fórmula de imagem:**
1. Na parte superior da página de detalhes da fórmula, escolha **Criar nova versão**. Isso leva você à página **Criar fórmula de imagem**.
1. Para criar a nova versão, faça suas alterações e depois escolha **Criar fórmula**.
Sua imagem final pode conter até quatro códigos de produto de produtos e componentes de AWS Marketplace imagem. Se a imagem base e os componentes selecionados contiverem mais de quatro códigos de produto, o Image Builder retornará um erro quando você tentar criar a receita.
Para obter mais informações sobre como criar uma fórmula de imagem ao criar um pipeline de imagens, consulte [Etapa 2: Escolher fórmula](start-build-image-pipeline.md#start-build-image-step2) na seção **Conceitos básicos** deste guia.
## Crie uma receita de imagem com o AWS CLI
Para criar uma receita de imagem com o `create-image-recipe` comando Image Builder no AWS CLI, siga estas etapas:
**Pré-requisitos**
Antes de executar os comandos do Image Builder nesta seção para criar uma receita de imagem a partir do AWS CLI, você pode, opcionalmente, criar componentes que a receita usa. O exemplo de fórmula de imagem na etapa a seguir se refere a exemplos de componentes que são criados na seção [Crie um componente personalizado a partir do AWS CLI](create-component.md#create-component-ib-cli) deste guia.
Se você quiser incluir componentes em sua receita, anote o ARNs que você deseja incluir. Você também pode criar receitas sem nenhum componente para testar fluxos de trabalho existentes AMIs ou somente de distribuição.
1.
**Criar um arquivo JSON de entrada da CLI**
Você pode fornecer toda a entrada para o comando **create-image-recipe** com parâmetros de comando embutidos. No entanto, o comando resultante pode ser bastante longo. Para simplificar o comando, você pode fornecer um arquivo JSON que contenha todas as configurações da fórmula.
**nota**
A convenção de nomenclatura para os valores de dados no arquivo JSON segue o padrão especificado para os parâmetros de solicitação de operação da API Image Builder. Para revisar os parâmetros da solicitação de operação da API, consulte o [CreateImageRecipe](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_CreateImageRecipe.html)comando na Referência da *API do EC2 Image Builder*.
Para fornecer os valores dos dados como parâmetros da linha de comando, consulte os nomes dos parâmetros especificados na *AWS CLI Referência de comando*.
Aqui está um resumo dos parâmetros que esses exemplos especificam:
+ **name** (string, obrigatório): o nome da fórmula de imagem.
+ **description** (string): a descrição da fórmula de imagem.
+ **parentImage** (string, obrigatório): a imagem que a fórmula de imagem usa como base para sua imagem personalizada. Você pode especificar a imagem principal usando uma das seguintes opções:
+ ID DA AMI
+ ARN do recurso de imagem do Image Builder
+ AWS Systems Manager (SSM) Parâmetro do Parameter Store, prefixado por`ssm:`, seguido pelo nome do parâmetro ou ARN.
+ AWS Marketplace ID do produto
**nota**
Os exemplos de Linux e macOS usam uma AMI do Image Builder, e o exemplo do Windows usa um ARN.
+ **SemanticVersion** *(string, obrigatório) — Insira o número da versão que você deseja criar no formato. . *. O Image Builder oferece suporte ao incremento automático de versões para receitas, permitindo que você use padrões curinga em suas versões de receitas. Quando você cria uma receita com uma versão curinga`1.0.x`, como, por exemplo, Image Builder incrementa automaticamente a versão (por exemplo,, `1.0.1` `1.0.2``1.0.3`, e assim por diante). Isso elimina a necessidade de rastrear e incrementar manualmente as versões da receita. Para saber mais sobre o versionamento semântico dos recursos do Image Builder, consulte [Versionamento semântico no Image Builder](ibhow-semantic-versioning.md).
+ **components** (matriz, opcional) — Contém uma matriz de `ComponentConfiguration` objetos. Os componentes são opcionais - você pode criar receitas sem nenhum componente para fluxos de trabalho de teste ou distribuição:
**nota**
O Image Builder instala os componentes na ordem em que você os especificou na fórmula. No entanto, os componentes de fortalecimento do CIS sempre são executados por último para garantir que os testes de benchmark sejam executados em relação à sua imagem de saída.
+ **componentARN** (string, obrigatório): o ARN do componente.
**dica**
Para usar um dos exemplos para criar sua própria receita de imagem, você deve substituir o exemplo ARNs ARNs pelo dos componentes que você está usando para sua receita.
+ **parameters** (matriz de objetos): contém uma variedade de objetos `ComponentParameter`. Se um parâmetro de entrada for necessário, mas não tiver um valor padrão definido no componente, você deverá fornecer um valor. O Image Builder não criará a versão da fórmula se algum parâmetro obrigatório estiver faltando e não houver um valor padrão definido.
**Importante**
Os parâmetros do componente são valores de texto simples e estão logados em AWS CloudTrail. Recomendamos que você use AWS Secrets Manager ou o AWS Systems Manager Parameter Store para armazenar seus segredos. Para obter mais informações sobre o Secrets Manager, consulte [O que é o Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) no *AWS Secrets Manager Guia do usuário*. Para obter mais informações sobre o AWS Systems Manager Parameter Store, consulte [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) no *AWS Systems Manager Guia do usuário*.
+ **nome** (string, obrigatório): o nome do parâmetro do componente a ser definido.
+ **value** (matriz de strings, obrigatório): contém uma matriz de strings para definir o valor do parâmetro do componente nomeado. Se houver um valor padrão definido para o componente e nenhum outro valor for fornecido, AWSTOE use o valor padrão.
+ **additionalInstanceConfiguration**(objeto) — Especifique configurações adicionais e scripts de lançamento para suas instâncias de compilação.
+ **systemsManagerAgent**(object) — Contém configurações para o agente Systems Manager em sua instância de compilação.
+ **uninstallAfterBuild**(Boolean) — Controla se o agente do Systems Manager é removido da imagem de compilação final antes de criar a nova AMI. Se essa opção for definida para `true`, o atendente será removido da imagem final. Se a opção for definida para `false`, o atendente será mantido para que seja incluído na nova AMI. O valor padrão é `false`.
**nota**
Se o atributo `uninstallAfterBuild` não estiver incluído no arquivo JSON e as condições a seguir forem verdadeiras, o Image Builder removerá o atendente do Systems Manager da imagem final para que ele não fique disponível na AMI:
O `userDataOverride` está vazio ou foi omitido do arquivo JSON.
O Image Builder instalou automaticamente o atendente do Systems Manager na instância de compilação de um sistema operacional que não tinha o atendente pré-instalado na imagem de base.
+ **userDataOverride**(string) — Forneça comandos ou um script de comando para executar ao iniciar sua instância de compilação.
**nota**
Os dados do usuário são sempre codificados em base 64. Por exemplo, os seguintes comandos são codificados como `IyEvYmluL2Jhc2gKbWtkaXIgLXAgL3Zhci9iYi8KdG91Y2ggL3Zhcg==`:
```
#!/bin/bash
mkdir -p /var/bb/
touch /var
```
O exemplo do Linux usa esse valor codificado.
------
#### [ Linux ]
A imagem base (propriedade de `parentImage`) no exemplo a seguir é uma AMI. Ao usar uma AMI, você deve ter acesso à AMI, e a AMI deve estar na região de origem (a mesma região em que o Image Builder executa o comando). Salve o arquivo como `create-image-recipe.json` e use-o no comando **create-image-recipe**.
```
{
"name": "BB Ubuntu Image recipe",
"description": "Hello World image recipe for Linux.",
"parentImage": "ami-1234567890abcdef1",
"semanticVersion": "1.0.0",
"components": [
{
"componentArn": "arn:aws:imagebuilder:us-west-2:111122223333:component/bb$"
}
],
"additionalInstanceConfiguration": {
"systemsManagerAgent": {
"uninstallAfterBuild": true
},
"userDataOverride": "IyEvYmluL2Jhc2gKbWtkaXIgLXAgL3Zhci9iYi8KdG91Y2ggL3Zhcg=="
}
}
```
------
#### [ Windows ]
O exemplo a seguir se refere à versão mais recente da imagem de base completa em inglês do Windows Server 2016. O ARN neste exemplo faz referência à imagem mais recente com base nos filtros de versão semântica que você especificou:. `arn:aws:imagebuilder:us-west-2:aws:image/windows-server-2016-english-full-base-x86/x.x.x`
```
{
"name": "MyBasicRecipe",
"description": "This example image recipe creates a Windows 2016 image.",
"parentImage": "arn:aws:imagebuilder:us-west-2:aws:image/windows-server-2016-english-full-base-x86/x.x.x",
"semanticVersion": "1.0.0",
"components": [
{
"componentArn": "arn:aws:imagebuilder:us-west-2:111122223333:component/my-example-component/2019.12.02/1"
},
{
"componentArn": "arn:aws:imagebuilder:us-west-2:111122223333:component/my-imported-component/1.0.0/1"
}
]
}
```
**nota**
Para saber mais sobre o versionamento semântico dos recursos do Image Builder, consulte [Versionamento semântico no Image Builder](ibhow-semantic-versioning.md).
------
#### [ macOS ]
A imagem base (propriedade de `parentImage`) no exemplo a seguir é uma AMI. Ao usar uma AMI, você deve ter acesso à AMI, e a AMI deve estar na região de origem (a mesma região em que o Image Builder executa o comando). Salve o arquivo como `create-image-recipe.json` e use-o no comando **create-image-recipe**.
```
{
"name": "macOS Catalina Image recipe",
"description": "Hello World image recipe for macOS.",
"parentImage": "ami-1234567890abcdef1",
"semanticVersion": "1.0.0",
"components": [
{
"componentArn": "arn:aws:imagebuilder:us-west-2:111122223333:component/catalina$"
}
],
"additionalInstanceConfiguration": {
"systemsManagerAgent": {
"uninstallAfterBuild": true
},
"userDataOverride": "IyEvYmluL2Jhc2gKbWtkaXIgLXAgL3Zhci9iYi8KdG91Y2ggL3Zhcg=="
}
}
```
------
**Exemplo: Receita sem componentes**
Você pode criar receitas sem nenhum componente para testar fluxos de trabalho existentes AMIs ou somente de distribuição. O exemplo a seguir mostra uma receita que usa uma AMI existente sem aplicar nenhum componente adicional:
```
{
"name": "Test Distribution Recipe",
"description": "Recipe for testing and distributing existing AMI without modifications.",
"parentImage": "ami-1234567890abcdef1",
"semanticVersion": "1.0.0",
"additionalInstanceConfiguration": {
"systemsManagerAgent": {
"uninstallAfterBuild": true
}
}
}
```
1.
**Criar a fórmula**
Use o comando a seguir para criar a fórmula. Forneça o nome do arquivo JSON que você criou na etapa anterior no parâmetro `--cli-input-json`:
```
aws imagebuilder create-image-recipe --cli-input-json file://create-image-recipe.json
```
**nota**
É necessário incluir a notação `file://` no início do caminho do arquivo JSON.
O caminho para o arquivo JSON deve seguir a convenção apropriada para o sistema operacional de base no qual você está executando o comando. Por exemplo, o Windows usa a barra invertida (\$1) para se referir ao caminho do diretório, enquanto o Linux e o macOS usam a barra (/).
Sua imagem final pode conter até quatro códigos de produto de produtos e componentes de AWS Marketplace imagem. Se a imagem base e os componentes selecionados contiverem mais de quatro códigos de produto, o Image Builder retornará um erro ao executar o `create-image-recipe` comando.
## Importar uma VM como sua imagem de base no console
Nesta seção, vamos nos concentrar em como importar uma máquina virtual (VM) como imagem de base para sua fórmula de imagem. Aqui, não abordamos outras etapas envolvidas na criação de uma fórmula ou versão da fórmula. Para ver as etapas adicionais para criar uma nova fórmula de imagem com o assistente de criação de pipeline no console do Image Builder, consulte [Assistente de pipeline: criar AMI](start-build-image-pipeline.md). Para ver as etapas adicionais para criar uma nova fórmula de imagem ou versão de fórmula, consulte [Criar uma nova versão de uma fórmula de imagem](#create-image-recipes).
Para importar uma VM como imagem de base para sua fórmula de imagem no console do Image Builder, siga estas etapas, junto com todas as outras etapas necessárias, para criar sua fórmula ou versão da fórmula.
1. Na seção **Selecionar imagem** para a imagem de base, selecione a opção **Importar imagem de base**.
1. Escolha o **Sistema operacional (OS) de imagem** e a **Versão do OS** como você faria normalmente.
### Configuração de importação de VM
Quando você exporta sua VM do ambiente de virtualização, esse processo cria um conjunto de um ou mais arquivos de contêiner de disco que atuam como snapshots do ambiente, das configurações e dos dados da sua VM. Você pode usar esses arquivos para importar sua VM como imagem de base para sua fórmula de imagem. Para obter mais informações sobre importação VMs no Image Builder, consulte [Importar e exportar imagens de VM](vm-import-export.md)
Para especificar a localização da sua fonte de importação, siga estas etapas:
**Importar fonte**
Especifique a fonte do primeiro contêiner de disco ou snapshot de imagem da VM a ser importado na seção **Contêiner de disco 1**.
1. **Fonte**: essa pode ser um bucket do S3 ou um snapshot do EBS.
1. **Selecione a localização do disco do S3**: insira a localização no Amazon S3 onde suas imagens de disco estão armazenadas. Para procurar o local, escolha **Browse S3**.
1. Para adicionar um contêiner de disco, escolha **Adicionar contêiner de disco**.
**Perfil do IAM**
Para associar um Perfil do IAM à sua configuração de importação de VM, selecione o perfil na lista suspensa de **Perfil do IAM** ou escolha **Criar novo perfil** para criar um novo. Se você criar um novo perfil, a página do console de Perfis do IAM será aberta em uma guia separada.
#### Configurações avançadas: *opcionais*
As seguintes configurações são opcionais. Com essas configurações, você pode configurar criptografia, licenciamento, tags e muito mais para a imagem de base criada pela importação.
**Geral**
1. Especifique um **Nome** exclusivo para a imagem de base. Se você não inserir um valor, a imagem de base herdará o nome da fórmula.
1. Especifique uma **Versão** para a imagem de base. Use o formato a seguir: `..`. Se você não inserir um valor, a imagem de base herdará a versão da fórmula.
1. Você também pode inserir uma **Descrição** para a imagem de base.
**Arquitetura da imagem de base**
Para especificar a arquitetura da sua fonte de importação de VM, selecione um valor na lista **Arquitetura**.
**Criptografia**
Se as imagens de disco da VM estiverem criptografadas, você deverá fornecer uma chave para usar no processo de importação. Para especificar um AWS KMS key para a importação, selecione um valor na lista **Criptografia (chave KMS)**. A lista contém chaves KMS às quais sua conta tem acesso na região atual.
**Gerenciamento de licença**
Quando você importa uma VM, o processo de importação detecta automaticamente o OS da VM e aplica a licença apropriada à imagem de base. Dependendo da plataforma do seu OS, os tipos de licença são os seguintes:
+ **Licença incluída**: Uma licença AWS apropriada para sua plataforma é aplicada à sua imagem de base.
+ **Traga a sua própria licença (BYOL)**: Retém a licença da sua VM, se aplicável.
Para anexar as configurações de licença criadas com AWS License Manager à sua imagem base, selecione na lista **Nome da configuração da licença**. Para obter mais informações sobre o License Manager, consulte [Trabalhando com AWS License Manager]()
**nota**
As configurações de licença contêm regras de licenciamento com base nos termos de seus contratos empresariais.
O Linux só oferece suporte a licenças BYOL.
**Tags (imagem de base)**
As tags usam pares de chave–valor para atribuir texto pesquisável ao seu recurso do Image Builder. Para especificar tags para a imagem de base importada, insira pares de chave–valor com as caixas **Chave** e **Valor**.
Para adicionar uma tag, escolha **Adicionar tag**. Para remover uma tag, selecione **Remover tag**.
# Criar uma nova versão de fórmula de contêiner
Esta seção mostra como criar uma nova versão de fórmula de contêiner.
**Topics**
+ [
## Crie uma nova versão de fórmula de contêiner com o console
](#create-container-recipe-version)
+ [
## Crie uma receita de recipiente com o AWS CLI
](#create-container-recipe-cli)
## Crie uma nova versão de fórmula de contêiner com o console
Criar uma nova versão de uma fórmula do contêiner é praticamente o mesmo que criar uma nova fórmula. A diferença é que certos detalhes são pré-selecionados para corresponder à fórmula de base, na maioria dos casos. A lista a seguir descreve as diferenças entre criar uma nova fórmula e criar uma nova versão de uma fórmula existente.
**Detalhes da fórmula**
+ **Nome**: *não editável*.
+ **Versão**: obrigatória. Esse detalhe não é pré-preenchido com a versão atual nem com qualquer tipo de sequência. Insira o número da versão que você deseja criar no formato *major.minor.patch.* Se a versão já existir, você encontrará um erro.
**Imagem de base**
+ Opção **Selecionar imagem**: pré-selecionada, mas você pode editá-la. Se você alterar sua escolha para a fonte da imagem de base, você poderá perder outros detalhes que dependem da opção original escolhida por você.
Para imagens de contêiner do Docker, você pode escolher entre imagens públicas hospedadas em DockerHub, imagens de contêiner existentes no Amazon ECR ou imagens de contêiner gerenciadas pela Amazon. Para ver detalhes associados à seleção imagem base, escolha a guia que corresponde à sua seleção.
------
#### [ Managed images ]
+ **Sistema operacional (OS) de imagem**: *não editável*.
+ **Nome da imagem**: pré-selecionado, com base na combinação de opções de imagem de base que você fez para a fórmula existente. No entanto, se você alterar a opção **Selecionar imagem**, você perderá o **Nome da imagem** pré-selecionado.
+ **Opções de autoversionamento**: *não* corresponde à sua fórmula de base. As opções de autoversionamento usam como padrão a opção **Usar a versão do sistema operacional selecionada**.
**Importante**
Se você estiver usando o versionamento semântico para iniciar as compilações do pipeline, altere esse valor para **Usar a versão mais recente do sistema operacional disponível**. Para saber mais sobre o versionamento semântico dos recursos do Image Builder, consulte [Versionamento semântico no Image Builder](ibhow-semantic-versioning.md).
------
#### [ ECR image ]
+ **Sistema operacional de imagem (OS)**: pré-selecionado, mas editável.
+ **Versão do OS**: pré-selecionada, mas editável.
+ **ID de imagem ECR**: pré-preenchido, mas editável.
------
#### [ Docker Hub image ]
+ **Sistema operacional (OS) de imagem**: *não editável*.
+ **Versão do OS**: pré-selecionada, mas editável.
+ **ID de imagem do Docker**: pré-preenchido, mas editável.
------
**Configuração da instância**
+ **Fonte da AMI** (obrigatória) — identifique uma AMI personalizada para usar como imagem base para a criação e a instância de teste do contêiner. Isso pode ser uma ID de AMI ou um parâmetro AWS Systems Manager (SSM) do Parameter Store que contém uma ID de AMI.
+ **ID AMI** — Essa configuração não está pré-preenchida com sua entrada original. Insira o ID da AMI para sua imagem base. Exemplo: `ami-1234567890abcdef1`.
+ **Parâmetro SSM** — Insira o nome ou ARN do parâmetro SSM Parameter Store que contém o ID da AMI para sua imagem base. Exemplo: `/ib/test/param` ou `arn:aws:ssm:us-east-1:111122223333:parameter/ib/test/param`.
+
**Armazenamento (volumes)**
**Volume 1 do EBS (raiz da AMI)**: pré-preenchido. As seleções **Nome do dispositivo**, **Snapshot** e **IOPS** do volume raiz não podem ser editados. No entanto, você pode alterar todas as demais configurações, como o **Tamanho**. Você também pode adicionar novos volumes.
**nota**
Se você especificar uma AMI base compartilhada de outra conta com você, os snapshots de qualquer volume secundário especificado também devem ser compartilhados com sua conta.
**Diretório de trabalho**
+ **Caminho do diretório de trabalho**: pré-preenchido, mas editável.
**Componentes**
+ **Componentes**: os componentes que já estão incluídos na fórmula são exibidos na seção **Componentes selecionados** no final de cada uma das listas de componentes (compilação e teste). Você pode remover ou reordenar os componentes selecionados para atender às suas necessidades.
Os componentes de endurecimento do CIS não seguem as regras padrão de ordenação de componentes nas fórmulas do Image Builder. Os componentes de endurecimento do CIS sempre são executados por último para garantir que os testes de benchmark sejam executados em relação à sua imagem de saída.
**nota**
As listas de componentes de compilação e teste exibem os componentes disponíveis com base no tipo de proprietário do componente. Para adicionar um componente, escolha **Adicionar componentes de construção** e selecione o filtro de propriedade aplicável. Por exemplo, para adicionar um componente de compilação associado a um AWS Marketplace produto, selecione`AWS Marketplace`. Isso abre um painel de seleção no lado direito da interface do console que lista AWS Marketplace os componentes.
Para o componente CIS, selecione`Third party managed`.
Você pode definir as seguintes configurações para seu componente selecionado:
+ **Opções de versionamento**: pré-selecionadas, mas você pode alterá-las. Recomendamos que você escolha a opção **Usar a versão mais recente disponível do componente** para garantir que suas compilações de imagem sempre usem a versão mais recente do componente. Se precisar usar uma versão específica do componente em sua fórmula, você pode escolher **Especificar versão do componente** e inserir a versão na caixa **Versão do componente** que aparece.
+ **Parâmetros de entrada**: exibe os parâmetros de entrada que o componente aceita. O **Valor** é pré-preenchido com o valor da versão anterior da fórmula. Se você estiver usando esse componente pela primeira vez nessa fórmula e um valor padrão tiver sido definido para o parâmetro de entrada, o valor padrão aparecerá na caixa **Valor** com texto acinzentado. Se nenhum outro valor for inserido, o Image Builder usará o valor padrão.
Se um parâmetro de entrada for necessário, mas não tiver um valor padrão definido no componente, você deverá fornecer um valor. O Image Builder não criará a versão da fórmula se algum parâmetro obrigatório estiver faltando e não houver um valor padrão definido.
**Importante**
Os parâmetros do componente são valores de texto simples e estão logados em AWS CloudTrail. Recomendamos que você use AWS Secrets Manager ou o AWS Systems Manager Parameter Store para armazenar seus segredos. Para obter mais informações sobre o Secrets Manager, consulte [O que é o Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) no *AWS Secrets Manager Guia do usuário*. Para obter mais informações sobre o AWS Systems Manager Parameter Store, consulte [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) no *AWS Systems Manager Guia do usuário*.
Para expandir as configurações das **opções de versionamento** ou **dos parâmetros de entrada**, você pode escolher a seta ao lado do nome da configuração. Para expandir todas as configurações de todos os componentes selecionados, você pode ativar e desativar a opção **Expandir tudo**.
**Modelo do Dockerfile**
+ **Modelo do Dockerfile**: pré-preenchido, mas editável. Você pode especificar qualquer uma das variáveis contextuais a seguir que o Image Builder substitui por informações de compilação no runtime.
**parentImage (obrigatória)**
No momento da compilação, esta variável é resolvida na imagem de base da sua fórmula.
Exemplo:
```
FROM
{{{ imagebuilder:parentImage }}}
```
**environments (necessários se os componentes forem especificados)**
Esta variável será resolvida em um script que executa componentes.
Exemplo:
```
{{{ imagebuilder:environments }}}
```
**components (opcional)**
O Image Builder resolve scripts de componentes de compilação e teste para os componentes que a fórmula de contêiner inclui. Esta variável pode ser colocada em qualquer lugar no Dockerfile, depois da variável environments.
Exemplo:
```
{{{ imagebuilder:components }}}
```
**Repositório de destino**
+ **Nome do repositório de destino**: o repositório Amazon ECR onde sua imagem de saída está armazenada se não houver outro repositório especificado na configuração de distribuição do seu pipeline para a região onde o pipeline é executado (Região 1).
**Para criar uma nova fórmula de contêiner:**
1. Na parte superior da página de detalhes da fórmula do contêiner, escolha **Criar nova versão**. Você será direcionado para a página **Criar fórmula** para fórmulas de contêiner.
1. Para criar a nova versão, faça suas alterações e depois escolha **Criar fórmula**.
Para obter mais informações sobre como criar uma fórmula de contêiner ao criar um pipeline de imagens, consulte [Etapa 2: Escolher fórmula](start-build-container-pipeline.md#start-build-container-step2) a seção **Introdução** deste guia.
## Crie uma receita de recipiente com o AWS CLI
Para criar uma receita de contêiner do Image Builder com o `imagebuilder create-container-recipe` comando no AWS CLI, siga estas etapas:
**Pré-requisitos**
Antes de executar os comandos do Image Builder nesta seção para criar uma receita de contêiner com o AWS CLI, você deve criar os componentes que a receita usará. O exemplo de fórmula de contêiner na etapa a seguir se refere a exemplos de componentes que são criados na seção [Crie um componente personalizado a partir do AWS CLI](create-component.md#create-component-ib-cli) deste guia.
Depois de criar seus componentes, ou se você estiver usando componentes existentes, anote o ARNs que você deseja incluir na receita.
1.
**Criar um arquivo JSON de entrada da CLI**
Você pode fornecer toda a entrada para o comando **create-container-recipe** com parâmetros de comando embutidos. No entanto, o comando resultante pode ser bastante longo. Para simplificar o comando, você pode fornecer um arquivo JSON que contenha todas as configurações da fórmula do contêiner
**nota**
A convenção de nomenclatura para os valores de dados no arquivo JSON segue o padrão especificado para os parâmetros de solicitação de operação da API Image Builder. Para revisar os parâmetros da solicitação de operação da API, consulte o [CreateContainerRecipe](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_CreateContainerRecipe.html)comando na Referência da *API do EC2 Image Builder*.
Para fornecer os valores dos dados como parâmetros da linha de comando, consulte os nomes dos parâmetros especificados na *AWS CLI Referência de comando*.
Aqui está um resumo dos parâmetros neste exemplo:
+ **componentes** (matriz de objetos, obrigatório): contém uma matriz de `ComponentConfiguration` objetos. Pelo menos um componente da compilação deve ser especificado:
**nota**
O Image Builder instala os componentes na ordem em que você os especificou na fórmula. No entanto, os componentes de fortalecimento do CIS sempre são executados por último para garantir que os testes de benchmark sejam executados em relação à sua imagem de saída.
+ **componentARN** (string, obrigatório): o ARN do componente.
**dica**
Para usar o exemplo para criar sua própria receita de contêiner, substitua o ARNs exemplo ARNs pelo dos componentes que você está usando para sua receita,. Isso inclui o Região da AWS, nome, e o número da versão de cada um.
+ **parameters** (matriz de objetos): contém uma variedade de objetos `ComponentParameter`. Se um parâmetro de entrada for necessário, mas não tiver um valor padrão definido no componente, você deverá fornecer um valor. O Image Builder não criará a versão da fórmula se algum parâmetro obrigatório estiver faltando e não houver um valor padrão definido.
**Importante**
Os parâmetros do componente são valores de texto simples e estão logados em AWS CloudTrail. Recomendamos que você use AWS Secrets Manager ou o AWS Systems Manager Parameter Store para armazenar seus segredos. Para obter mais informações sobre o Secrets Manager, consulte [O que é o Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) no *AWS Secrets Manager Guia do usuário*. Para obter mais informações sobre o AWS Systems Manager Parameter Store, consulte [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) no *AWS Systems Manager Guia do usuário*.
+ **nome** (string, obrigatório): o nome do parâmetro do componente a ser definido.
+ **value** (matriz de strings, obrigatório): contém uma matriz de strings para definir o valor do parâmetro do componente nomeado. Se houver um valor padrão definido para o componente e nenhum outro valor for fornecido, AWSTOE use o valor padrão.
+ **ContainerType** (string, obrigatório): o tipo de contêiner a ser criado. Os valores válidos são: `DOCKER`.
+ **dockerfileTemplateData**(string) — O modelo Dockerfile usado para criar sua imagem, expresso como um blob de dados embutido.
+ **name** (string, obrigatório): o nome da fórmula do contêiner.
+ **description** (string): a descrição da fórmula do contêiner.
+ **parentImage** (string, required) — A imagem do contêiner Docker a ser usada na receita do contêiner como base para sua imagem personalizada.
+ Imagens públicas hospedadas em DockerHub
+ Imagens de contêiner existentes no Amazon ECR
+ Imagens de contêiner gerenciadas pela Amazon
+ **platformOverride** (string) - Especifica a plataforma do sistema operacional quando você usa uma imagem base personalizada.
+ **SemanticVersion** (string, obrigatório): a versão semântica da fórmula do contêiner especificada no formato a seguir, com valores numéricos em cada posição para indicar uma versão específica: *,, *. Um exemplo seria `1.0.0`. Para saber mais sobre o versionamento semântico dos recursos do Image Builder, consulte [Versionamento semântico no Image Builder](ibhow-semantic-versioning.md).
+ **tags** (string map) - Tags que estão anexadas à fórmula do contêiner.
+ **instanceConfiguration** (objeto) - Um grupo de opções que pode ser utilizado para configurar uma instância para compilar e testar imagens de contêiner.
+ **image** (string) — A imagem base para uma instância de criação e teste de contêiner. Isso pode conter uma ID de AMI ou especificar um parâmetro AWS Systems Manager (SSM) do Parameter Store, prefixado por`ssm:`, seguido pelo nome do parâmetro ou ARN. Se você usar um parâmetro SSM, o valor do parâmetro deverá conter uma ID de AMI. Se você não especificar uma imagem base, o Image Builder usa a AMI otimizada apropriada do Amazon ECS como imagem base.
+ **blockDeviceMappings**(matriz de objetos) — Define os dispositivos de bloco a serem conectados para criar uma instância a partir da AMI do Image Builder especificada no **image** parâmetro.
+ **deviceName** (string): o dispositivo ao qual esses mapeamentos se aplicam.
+ **ebs** (objeto) - Use para gerenciar a configuração específica do Amazon EBS para esse mapeamento.
+ **deleteOnTermination**(Boolean) — Usado para configurar a exclusão no encerramento do dispositivo associado.
+ **encrypted** (booleano): usado para configurar a criptografia do dispositivo.
+ **volumeSize** (inteiro): usado para substituir o tamanho do volume do dispositivo.
+ **volumeSize** (string): usado para substituir o tipo do volume do dispositivo.
+ **targetRepository** (objeto, obrigatório): o repositório de destino da imagem do contêiner, se não houver outro repositório especificado na configuração de distribuição do pipeline para a região onde o pipeline é executado (Região 1).
+ **repositoryName** (string, obrigatório) - O nome do repositório de contêiner onde a imagem do contêiner de saída é armazenada. Este nome é prefixado pelo local do repositório.
+ **serviço** (string, obrigatório) - Especifica o serviço no qual esta imagem foi registrada.
+ **workingDirectory** (string) - O diretório de trabalho a ser usado durante os fluxos de trabalho de compilação e teste.
```
{
"components": [
{
"componentArn": "arn:aws:imagebuilder:us-west-2:111122223333:component/helloworldal2/x.x.x"
}
],
"containerType": "DOCKER",
"description": "My Linux Docker container image",
"dockerfileTemplateData": "FROM {{{ imagebuilder:parentImage }}}\n{{{ imagebuilder:environments }}}\n{{{ imagebuilder:components }}}",
"name": "amazonlinux-container-recipe",
"parentImage": "amazonlinux:latest",
"platformOverride": "Linux",
"semanticVersion": "1.0.2",
"tags": {
"sometag" : "Tag detail"
},
"instanceConfiguration": {
"image": "ami-1234567890abcdef1",
"blockDeviceMappings": [
{
"deviceName": "/dev/xvda",
"ebs": {
"deleteOnTermination": true,
"encrypted": false,
"volumeSize": 8,
"volumeType": "gp2"
}
}
]
},
"targetRepository": {
"repositoryName": "myrepo",
"service": "ECR"
},
"workingDirectory": "/tmp"
}
```
1.
**Criar a fórmula**
Use o comando a seguir para criar a fórmula. Forneça o nome do arquivo JSON que você criou na etapa anterior no parâmetro `--cli-input-json`:
```
aws imagebuilder create-container-recipe --cli-input-json file://create-container-recipe.json
```
**nota**
É necessário incluir a notação `file://` no início do caminho do arquivo JSON.
O caminho para o arquivo JSON deve seguir a convenção apropriada para o sistema operacional de base no qual você está executando o comando. Por exemplo, o Windows usa a barra invertida (\$1) para se referir ao caminho do diretório, enquanto o Linux e o macOS usam a barra (/).
## Limpar recursos
Para evitar cobranças inesperadas, certifique-se de limpar os recursos e pipelines que você criou com base nos exemplos deste guia. Para obter mais informações sobre exclusão de recursos no Image Builder, consulte [Excluir recursos desatualizados ou não utilizados do Image Builder](delete-resources.md).
# Gerenciar a configuração da infraestrutura do Image Builder
Você pode usar configurações de infraestrutura para especificar a infraestrutura do Amazon EC2 que o Image Builder usa para criar e testar sua imagem do EC2 Image Builder. As configurações de infraestrutura incluem:
+ Tipos de instância para sua infraestrutura de compilação e teste. Recomendamos que você especifique mais de um tipo de instância, pois isso permite que o Image Builder execute uma instância a partir de um grupo com capacidade suficiente. Isto pode reduzir suas falhas transitórias de compilação.
Para imagens do Mac, é possível escolher tipos de instância que ofereçam suporte nativo ao sistema operacional macOS. Para obter mais informações, consulte [Amazon EC2 Mac instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-mac-instances.html) no *Amazon EC2 User Guide*.
+ Configurações de posicionamento de instância nas quais você pode especificar o host, o grupo de posicionamento do host ou a zona de disponibilidade para onde devem ir as instâncias executadas em sua imagem.
+ Um perfil de instância que fornece às suas instâncias de compilação e teste as permissões necessárias para realizar atividades de personalização. Por exemplo, se você tem um componente que recupera recursos do Amazon S3, o perfil de instância exige permissões para acessar esses arquivos. O perfil de instância também exige um conjunto mínimo de permissões para que o EC2 Image Builder se comunique com sucesso com a instância. Para obter mais informações, consulte [Configurar compilação de imagens personalizadas com o Image Builder](set-up-ib-env.md).
+ A VPC, a sub-rede e grupos de segurança para as instâncias de compilação e teste do seu pipeline.
+ O local do Amazon S3 onde o Image Builder armazena os logs do aplicativo de sua compilação e teste. Se você configurar o registro em log, o perfil de instância especificado na configuração da sua infraestrutura deverá ter `s3:PutObject` permissões para o bucket de destino (`arn:aws:s3:::BucketName/*`).
+ Um par de chaves do Amazon EC2 que permite que você faça login em sua instância para solucionar problemas caso a criação falhe e você defina `terminateInstanceOnFailure` como `false`.
+ Um tópico do SNS em que o Image Builder envia notificações de eventos. Para obter mais informações sobre como o Image Builder se integra ao Amazon SNS, consulte [Integração do Amazon SNS no Image Builder](integ-sns.md).
**nota**
Se o tópico do SNS estiver criptografado, a chave que criptografa esse tópico deverá residir na conta em que o serviço Image Builder é executado. O Image Builder não pode enviar notificações para tópicos do SNS criptografados com chaves de outras contas.
Você pode criar e gerenciar as configurações da infraestrutura usando o console do Image Builder através do Image Builder API ou com os comandos **imagebuilder** no AWS CLI.
**Topics**
+ [
# Listar e visualizar detalhes de uma configuração de infraestrutura
](infra-config-details.md)
+ [
# Criar uma configuração de infraestrutura
](create-infra-config.md)
+ [
# Atualizar uma configuração de infraestrutura
](update-infra-config.md)
+ [
# Image Builder e AWS PrivateLink interface de VPC endpoints
](vpc-interface-endpoints.md)
**dica**
Quando você tem vários recursos do mesmo tipo, a marcação com tags ajuda a identificar um recurso específico com base nas tags que você atribuiu a ele. Para obter mais informações sobre como marcar seus recursos usando os comandos do Image Builder no AWS CLI, consulte a [Marcar recursos](tag-resources.md) seção deste guia.
# Listar e visualizar detalhes de uma configuração de infraestrutura
Esta seção descreve as várias maneiras pelas quais você pode encontrar informações e visualizar detalhes das configurações de infraestrutura do EC2 Image Builder.
**Topics**
+ [
## Listar as configurações de infraestrutura do AWS CLI
](#cli-list-infrastructure-configurations)
+ [
## Obtenha detalhes da configuração da infraestrutura no AWS CLI
](#cli-get-infrastructure-configuration-details)
## Listar as configurações de infraestrutura do AWS CLI
O exemplo a seguir mostra como listar todas as suas configurações de infraestrutura por meio do comando **[list-infrastructure-configurations](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/list-infrastructure-configurations.html)** na AWS CLI.
```
aws imagebuilder list-infrastructure-configurations
```
## Obtenha detalhes da configuração da infraestrutura no AWS CLI
O exemplo a seguir mostra como usar o **[get-infrastructure-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/get-infrastructure-configuration.html)** comando no AWS CLI para obter os detalhes de uma configuração de infraestrutura especificando seu Amazon Resource Name (ARN).
```
aws imagebuilder get-infrastructure-configuration --infrastructure-configuration-arn arn:aws:imagebuilder:us-west-2:123456789012:infrastructure-configuration/my-example-infrastructure-configuration
```
# Criar uma configuração de infraestrutura
Esta seção descreve como você pode usar o console do Image Builder ou **imagebuilder** os comandos no AWS CLI para criar uma configuração de infraestrutura,
------
#### [ Console ]
Para criar um recurso de configuração de infraestrutura a partir do console Image Builder, siga estas etapas:
1. Abra o console [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/)do EC2 Image Builder em.
1. No painel de navegação, escolha **Configuração de infraestrutura**.
1. Escolha **Criar configuração de infraestrutura**.
1. Na seção **Geral**, insira as seguintes informações obrigatórias:
+ Insira o **nome** do seu recurso de configuração de infraestrutura.
+ Selecione um **perfil do IAM** que você deseja associar ao perfil de instância para permissões de componente em suas instâncias de compilação e teste. O Image Builder usa essas permissões para baixar e executar seus componentes, fazer upload de registros e realizar quaisquer ações adicionais especificadas pelos componentes em sua receita. CloudWatch
1. No painel **Infraestrutura da AWS **, você pode definir as configurações de infraestrutura restantes que estão disponíveis. Insira as seguintes informações obrigatórias:
+ **Tipo de instância** – Você pode especificar um ou mais tipos de instância para usar nessa compilação. O serviço escolherá um desses tipos de instância com base na disponibilidade.
**nota**
Instâncias do Mac são executadas em instâncias do tipo `.metal` em um host dedicado. Seu tipo de instância deve corresponder a um dos tipos definidos para o host em que ela é executada. Para obter mais informações sobre instâncias Mac e uma lista de tipos de instância que oferecem suporte nativo ao sistema operacional macOS, consulte [Instâncias Mac do Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-mac-instances.html) no *Manual do usuário do Amazon EC2*.
+ **Tópico do SNS (opcional)**: selecione um tópico do SNS para receber notificações e alertas do EC2 Image Builder.
Se você não fornecer valores para as configurações a seguir, elas usarão padrões específicos do serviço, quando aplicável.
+ **VPC, sub-rede e grupos de segurança**: o Image Builder usa sua VPC e a sub-rede padrão. Para obter mais informações sobre como configurar os endpoint da interface da VPC, consulte [Image Builder e AWS PrivateLink interface de VPC endpoints](vpc-interface-endpoints.md).
+ Na seção **Configurações para solução de problemas**, você pode definir os seguintes valores:
+ Por padrão, a caixa de seleção **Encerrar instância em caso de falha** está marcada. No entanto, quando uma compilação falha, você pode fazer login na instância do EC2 para solucionar o problema. Se você quiser que sua instância continue em execução após uma falha de compilação, desmarque a caixa de seleção.
+ **Par de chaves**: se sua instância do EC2 continuar em execução após uma falha de compilação, você poderá criar um par de chaves ou usar um par de chaves existente para fazer login na instância e solucionar os problemas.
+ **Logs**: você pode especificar um bucket do S3 em que o Image Builder pode gravar registros de aplicativos para ajudar a solucionar problemas de compilação e testes. Se você não especificar um bucket do S3, o Image Builder grava os logs do aplicativo na instância.
+ Na seção **Configurações de metadados da instância**, você pode configurar os seguintes valores para serem aplicados às instâncias do EC2 que o Image Builder usa para criar e testar sua imagem:
+ Selecione a **versão de metadados** para determinar se o EC2 exige um cabeçalho de token assinado para solicitações de recuperação de metadados de instância.
+ **V1 e V2 (token opcional)**: valor padrão se você não selecionar nada.
+ **V2 (token obrigatório)**
**nota**
Recomendamos que você configure todas as instâncias do EC2 que o Image Builder executa a partir de um pipeline criado para uso, de IMDSv2 forma que as solicitações de recuperação de metadados da instância exijam um cabeçalho de token assinado.
+ **Metadata token response hop limit** (Limite de salto de resposta do token de metadados) - número permitido de saltos de rede para o token de metadados. Saltos mínimos: 1, saltos máximos: 64, com o padrão de um salto.
+ Na seção **Configurações de posicionamento da instância**, você pode configurar os seguintes valores para serem aplicados às instâncias do EC2 que o Image Builder usa para criar e testar sua imagem:
+ Você pode selecionar a **Zona de disponibilidade** em que o Image Builder inicia instâncias durante a criação da imagem.
+ Como opção, selecione **Locação** para os servidores que executam as instâncias que você inicia. Por padrão, as instâncias EC2 são executadas em hardware de locação compartilhada. Isso significa que várias Contas da AWS podem compartilhar o mesmo hardware físico. Uma instância com locação `dedicated` é executada em um hardware de locatário único. Uma instância com locação `host` é executada em um host dedicado.
As instâncias do Mac exigem um host dedicado criado como pré-requisito antes de você compilar uma imagem personalizada. Selecione `host` para sua imagem do macOS. Em seguida, você pode selecionar um host de destino ou um grupo de recursos do host para iniciar instâncias, mas isso não é necessário se seu host dedicado tiver o posicionamento automático habilitado. Para obter mais informações, consulte [Posicionamento automático](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/dedicated-hosts-understanding.html#dedicated-hosts-auto-placement) no *Manual do usuário do Amazon EC2*.
+ **ID do host de locação**: o ID do host dedicado no qual as instâncias são executadas.
+ **Grupo de recursos do host de locação**: o nome do recurso da Amazon (ARN) do grupo de recursos do host no qual as instâncias serão executadas.
1. Na seção **Tags de infraestrutura** (opcional), você pode atribuir tags de metadados à instância do Amazon EC2 que o Image Builder executa durante o processo de compilação. As tags são inseridas como pares de chave-valor.
1. Na seção **Tags** (opcional), você pode atribuir tags de metadados ao recurso de configuração de infraestrutura que o Image Builder cria como saída. As tags são inseridas como pares de chave-valor.
------
#### [ AWS CLI ]
O procedimento a seguir mostra como configurar a infraestrutura da sua imagem com o comando **[create-infrastructure-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-infrastructure-configuration.html)** do Image Builder na AWS CLI. O comando na Etapa 2 incorpora o arquivo que você criou na Etapa 1. Para esses exemplos, o arquivo da Etapa 1 é chamado `create-infrastructure-configuration.json`.
1.
**Criar um arquivo JSON de entrada da CLI**
Os exemplos a seguir mostram variações do arquivo JSON que você pode criar para a configuração da infraestrutura. Use uma ferramenta de edição de arquivos para criar seu próprio arquivo JSON.
**Exemplo 1: configuração para reter uma instância de uma compilação com falha**
Este exemplo especifica dois tipos de instância: `m5.large` e `m5.xlarge`. Recomendamos que você especifique mais de um tipo de instância, pois isso permite que o Image Builder execute uma instância a partir de um grupo com capacidade suficiente. Isto pode reduzir suas falhas transitórias de compilação.
O `instanceProfileName` especifica o perfil de instância que fornece à instância as permissões que o perfil exige para realizar atividades de personalização. Por exemplo, se você tem um componente que recupera recursos do Amazon S3, o perfil de instância exige permissões para acessar esses arquivos. O perfil de instância também exige um conjunto mínimo de permissões para que o EC2 Image Builder se comunique com sucesso com a instância. Para obter mais informações, consulte [Configurar compilação de imagens personalizadas com o Image Builder](set-up-ib-env.md).
```
{
"name": "ExampleInfraConfigDontTerminate",
"description": "An example that will retain instances of failed builds",
"instanceTypes": [
"m5.large", "m5.xlarge"
],
"instanceProfileName": "myIAMInstanceProfileName",
"securityGroupIds": [
"sg-12345678"
],
"subnetId": "sub-12345678",
"logging": {
"s3Logs": {
"s3BucketName": "my-logging-bucket",
"s3KeyPrefix": "my-path"
}
},
"keyPair": "myKeyPairName",
"terminateInstanceOnFailure": false,
"snsTopicArn": "arn:aws:sns:us-west-2:123456789012:MyTopic"
}
```
**Exemplo 2: configuração do macOS com posicionamento automático**
Este exemplo especifica os tipos de instância e o posicionamento de uma instância do Mac em que o host dedicado tem o posicionamento automático habilitado.
```
{
"name": "macOSInfraConfigAutoPlacement",
"description": "An example infrastructure configuration for macOS.",
"instanceProfileName": "EC2InstanceProfileForImageBuilder",
"instanceTypes": ["mac1.metal, mac2.metal"],
"terminateInstanceOnFailure": false,
"placement": {
"tenancy": "host"
}
}
```
**Exemplo 3: configuração do macOS com o ID do host especificado**
Este exemplo especifica o tipo de instância e o posicionamento de uma instância do Mac que tem como destino um host dedicado específico.
```
{
"name": "macOSInfraConfigHostPlacement",
"description": "An example infrastructure configuration for macOS.",
"instanceProfileName": "EC2InstanceProfileForImageBuilder",
"instanceTypes": ["mac2-m1ultra.metal"],
"terminateInstanceOnFailure": false,
"placement": {
"tenancy": "host",
"hostId" : "h-1234567890abcdef0"
}
}
```
1.
**Use o arquivo que você criou como entrada quando executar o seguinte comando.**
```
aws imagebuilder create-infrastructure-configuration --cli-input-json file://create-infrastructure-configuration.json
```
------
# Atualizar uma configuração de infraestrutura
Esta seção aborda como você pode usar o console do Image Builder ou **imagebuilder** os comandos no AWS CLI para atualizar um recurso de configuração de infraestrutura. Para monitorar seus recursos, é possível aplicar tags da maneira a seguir. As tags são inseridas como pares de chave-valor.
+ As *tags de recursos* atribuem tags de metadados à instância do Amazon EC2 que o Image Builder executa durante o processo de compilação.
+ Em *Tags*, atribua tags de metadados ao recurso de configuração de infraestrutura que o Image Builder cria como saída.
------
#### [ Console ]
Você pode editar os seguintes detalhes de configuração da infraestrutura no console do Image Builder:
+ A **descrição** da configuração da infraestrutura.
+ Associe o **perfil do IAM** para associar ao perfil de instância.
+ **AWS infraestrutura**, incluindo o **tipo de instância** e um **tópico de SNS** para notificações.
+ **VPC, sub-rede e grupos de segurança**.
+ **Configurações de solução de problemas**, incluindo **Encerrar instância em caso de falha**, o **par de chaves** para conexão e um local opcional do bucket S3 para os logs da instância.
Para atualizar um recurso de configuração de infraestrutura do console do Image Builder, siga estas etapas:
**Escolha uma configuração de infraestrutura existente do Image Builder**
1. Abra o console [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/)do EC2 Image Builder em.
1. Para ver uma lista dos recursos de configuração de infraestrutura em sua conta, escolha **Configuração de infraestrutura** no painel de navegação.
1. Para ver detalhes ou editar uma configuração de infraestrutura, escolha o link **Nome da configuração**. Isto abre a visualização detalhada da configuração da infraestrutura.
**nota**
Você também pode selecionar a caixa ao lado do **nome da configuração** e, em seguida, escolher **Exibir detalhes**.
1. No canto superior direito do painel **Detalhes da infraestrutura**, escolha **Editar**.
1. Quando estiver pronto para salvar as atualizações feitas na configuração da sua infraestrutura, escolha **Salvar alterações **.
------
#### [ AWS CLI ]
O exemplo a seguir mostra como atualizar a configuração da infraestrutura da sua imagem com o comando **[update-infrastructure-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/update-infrastructure-configuration.html)** do Image Builder na AWS CLI.
1.
**Criar um arquivo JSON de entrada da CLI**
Este exemplo de configuração de infraestrutura usa as mesmas configurações do exemplo de criação, exceto que atualizamos a configuração `terminateInstanceOnFailure` para`false`. Depois de executarmos o comando **update-infrastructure-configuration**, os pipelines que usam esta configuração de infraestrutura encerram as instâncias de compilação e teste quando a compilação falha.
Use uma ferramenta de edição de arquivos para criar um arquivo JSON com as chaves mostradas no exemplo a seguir, além de valores válidos para seu ambiente. Este exemplo usa um arquivo denominado `update-infrastructure-configuration.json`:
```
{
"infrastructureConfigurationArn": "arn:aws:imagebuilder:us-west-2:123456789012:infrastructure-configuration/my-example-infrastructure-configuration",
"description": "An example that will terminate instances of failed builds",
"instanceTypes": [
"m5.large", "m5.2xlarge"
],
"instanceProfileName": "myIAMInstanceProfileName",
"securityGroupIds": [
"sg-12345678"
],
"subnetId": "sub-12345678",
"logging": {
"s3Logs": {
"s3BucketName": "my-logging-bucket",
"s3KeyPrefix": "my-path"
}
},
"terminateInstanceOnFailure": true,
"snsTopicArn": "arn:aws:sns:us-west-2:123456789012:MyTopic"
}
```
1.
**Use o arquivo que você criou como entrada quando executar o seguinte comando.**
```
aws imagebuilder update-infrastructure-configuration --cli-input-json file://update-infrastructure-configuration.json
```
------
# Image Builder e AWS PrivateLink interface de VPC endpoints
É possível estabelecer uma conexão privada entre sua VPC e o EC2 Image Builder criando um *endpoint da VPC de interface*. Os endpoints de interface são alimentados por [AWS PrivateLink](https://aws.amazon.com/privatelink/)uma tecnologia que permite acessar de forma privada o Image Builder APIs sem um gateway de internet, dispositivo NAT, conexão VPN ou conexão. Direct Connect As instâncias em sua VPC não precisam de endereços IP públicos para se comunicar com o Image Builder. APIs O tráfego entre sua VPC e o Image Builder não deixa a rede da Amazon.
Cada endpoint de interface é representado por uma ou mais [Interfaces de Rede Elástica](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html) nas sub-redes. Ao criar uma nova imagem, você pode especificar o ID de sub-rede da VPC na configuração da sua infraestrutura.
**nota**
Cada serviço que você acessa de dentro de uma VPC tem seu próprio endpoint de interface, com sua própria política de endpoint. O Image Builder baixa o aplicativo gerenciador de AWSTOE componentes e acessa os recursos gerenciados dos buckets do S3 para criar imagens personalizadas. Para conceder acesso a esses buckets, você deve atualizar a política de endpoint do S3 para permitir isso. Para obter mais informações, consulte [Políticas personalizadas para acesso ao bucket do S3](#vpc-endpoint-policy-s3).
Para obter mais informações sobre endpoints da VPC, consulte [endpoints da VPC de interface (AWS PrivateLink)](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html) no *Guia do usuário da Amazon VPC*.
## Considerações sobre endpoints VPC do Image Builder
Antes de configurar um endpoint da VPC de interface para o Image Builder, certifique-se de revisar as [Propriedades e limitações do endpoint de interface](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#vpce-interface-limitations) no *Guia do usuário da Amazon VPC*.
O Image Builder oferece suporte a chamadas para todas as ações de API da sua VPC.
## Criar um endpoint da VPC de interface para o Image Builder
Para criar um VPC endpoint para o serviço Image Builder, você pode usar o console Amazon VPC ou o (). AWS Command Line Interface AWS CLI Para obter mais informações, consulte [Criar um endpoint de interface](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#create-interface-endpoint) no *Guia do usuário da Amazon VPC*.
Crie um endpoint da VPC para o Image Builder usando o seguinte nome de serviço:
+ com.amazonaws. *region*.construtor de imagens
Se você habilitar o DNS privado para o endpoint, poderá fazer solicitações de API para o Image Builder usando seu nome DNS padrão para a região, por exemplo, `imagebuilder.us-east-1.amazonaws.com`. Para pesquisar o endpoint que se aplica à sua região de destino, consulte [endpoints e cotas do EC2 Image Builder](https://docs.aws.amazon.com/general/latest/gr/imagebuilder.html#imagebuilder_region) no. *Referência geral da Amazon Web Services*
Para mais informações, consulte [Acessar um serviço por um endpoint de interface](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#access-service-though-endpoint) no *Guia do usuário da Amazon VPC*.
## Criar uma política de endpoint da VPC o Image Builder
É possível anexar uma política de endpoint ao endpoint da VPC que controla o acesso ao Image. Essa política especifica as seguintes informações:
+ A entidade principal que pode realizar ações.
+ As ações que podem ser realizadas.
+ Os recursos aos quais as ações podem ser aplicadas.
Se você estiver usando componentes gerenciados pela Amazon em sua fórmula, o endpoint da VPC para Image Builder deve permitir acesso à seguinte biblioteca de componentes de propriedade do serviço:
`arn:aws:imagebuilder:region:aws:component/*`
**Importante**
Quando uma política não padrão é aplicada a um endpoint VPC de interface para o EC2 Image Builder, certas solicitações de API com falha, como aquelas que `RequestLimitExceeded` falham, podem não ser registradas na Amazon. AWS CloudTrail CloudWatch
Para mais informações, consulte [Controlar o acesso a serviços com VPC endpoints](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-access.html) no *Guia do usuário da Amazon VPC*.
### Políticas personalizadas para acesso ao bucket do S3
O Image Builder usa um bucket do S3 disponível publicamente para armazenar e acessar recursos gerenciados, como componentes. Ele também baixa o aplicativo de gerenciamento de AWSTOE componentes de um bucket S3 separado. Se estiver usando um endpoint da VPC para o Amazon S3 em seu ambiente, será necessário garantir que sua política de endpoint da VPC do S3 permita que o construtor de imagens acesse os seguintes buckets do S3. Os nomes dos buckets são exclusivos por AWS região (*region*) e pelo ambiente do aplicativo (*environment*). Image Builder e dê AWSTOE suporte aos seguintes ambientes de aplicativos: `prod``preprod`, `beta` e.
+ O bucket AWSTOE do gerenciador de componentes:
```
s3://ec2imagebuilder-toe-region-environment
```
**Exemplo:** s3://ec2 imagebuilder-toe-us-west -2-prod/\$1
+ O bucket de recursos gerenciados do Image Builder:
```
s3://ec2imagebuilder-managed-resources-region-environment/components
```
**Exemplo:** s3://ec2 imagebuilder-managed-resources-us -west-2-prod/components/\$1
### Exemplos de política de endpoint da VPC
Esta seção inclui exemplos de políticas personalizadas de endpoint da VPC.
**Política geral de endpoint da VPC para ações do Image Builder**
O exemplo de política de endpoint a seguir para o Image Builder nega permissão para excluir imagens e componentes do Image Builder. O exemplo de política também concede permissão para executar todas as outras ações do EC2 Image Builder.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": "imagebuilder:*",
"Effect": "Allow",
"Resource": "*"
},
{
"Action": "imagebuilder:DeleteImage",
"Effect": "Deny",
"Resource": "*"
},
{
"Action": "imagebuilder:DeleteComponent",
"Effect": "Deny",
"Resource": "*"
}
]
}
```
------
**Restrinja o acesso por organização, permita o acesso gerenciado aos componentes**
O exemplo de política de endpoint a seguir mostra como restringir o acesso a identidades e recursos que pertencem à sua organização e conceder acesso aos componentes do Image Builder gerenciados pela Amazon. Substitua *region**principal-org-id*, e *resource-org-id* pelos valores da sua organização.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowRequestsByOrgsIdentitiesToOrgsResources",
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Action": "*",
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:PrincipalOrgID": "principal-org-id",
"aws:ResourceOrgID": "resource-org-id"
}
}
},
{
"Sid": "AllowAccessToEC2ImageBuilderComponents",
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Action": [
"imagebuilder:GetComponent"
],
"Resource": [
"arn:aws:imagebuilder:us-east-1:aws:component/*"
]
}
]
}
```
------
**Política de endpoint da VPC para acesso ao bucket do Amazon S3**
O exemplo de política de endpoint do S3 a seguir mostra como fornecer acesso aos buckets do S3 que o Image Builder usa para criar imagens personalizadas. *environment*Substitua *region* e pelos valores da sua organização. Adicione outras permissões necessárias à política com base nos requisitos do seu aplicativo.
**nota**
Com relação a imagens do Linux, se você não especificar dados do usuário em sua fórmula de imagem, o Image Builder adicionará um script para baixar e instalar o Systems Manager Agent nas instâncias de compilação e teste da sua imagem. Para baixar o agente, o Image Builder acessa o bucket do S3 referente à sua região de compilação.
Para garantir que o Image Builder possa inicializar as instâncias de compilação e teste, adicione o seguinte recurso complementar à sua política de endpoint do S3:
"`arn:aws:s3:::amazon-ssm-region/*`"
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowImageBuilderAccessToAppAndComponentBuckets",
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::ec2imagebuilder-toe-region-environment/*",
"arn:aws:s3:::ec2imagebuilder-managed-resources-region-environment/components/*"
]
}
]
}
```
------
# Gerenciar as configurações de distribuição do Image Builder
Antes de definir as configurações de distribuição de imagens de saída, recomendamos que você verifique a disponibilidade de qualquer infraestrutura subjacente ou outros requisitos para instâncias que são executadas na imagem de saída nas regiões de destino da distribuição. Por exemplo, nem todas as regiões permitem hosts dedicados do EC2 para Mac, necessários para iniciar instâncias em uma imagem do macOS. Para obter mais informações sobre os tipos de instância e a definição de preço de hosts dedicados, consulte [Preços de hosts dedicados do Amazon EC2](https://aws.amazon.com/ec2/dedicated-hosts/pricing/).
Depois de criar as configurações de distribuição com o Image Builder, você pode gerenciá-las usando o console do Image Builder, a API do Image Builder ou comandos **imagebuilder** na AWS CLI. Com as configurações de distribuição, você pode executar as seguintes ações:
**Distribuição da AMI**
+ Especifique o nome e a descrição da sua AMI de saída.
+ Autorize outras Contas da AWS organizações e a iniciar OUs a AMI a partir da conta do proprietário. A conta do proprietário é cobrada pelas cobranças que são associadas à AMI.
**nota**
Para tornar uma AMI pública, defina as contas autorizadas com permissão de execução como `all`. Para obter mais informações e ver exemplos, consulte **[ModifyImageAttribute](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyImageAttribute.html)** na *Referência de API do Amazon EC2*.
+ Crie uma cópia da AMI de saída para cada uma das contas, organizações e organizações de destino especificadas OUs na região de destino. As contas, organizações e organizações de destino OUs possuem suas cópias da AMI e são cobradas por quaisquer cobranças associadas. Para obter mais informações sobre como distribuir sua AMI para AWS Organizations e OUs, consulte [Compartilhar uma AMI com organizações ou OUs](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/share-amis-with-organizations-and-OUs.html).
+ Copie a AMI para a conta do proprietário em outra Regiões da AWS.
+ Exporte discos de imagem de VM para o Amazon Simple Storage Service (Amazon S3). Para obter mais informações, consulte [Exemplo: Crie configurações de distribuição para discos VM de saída do AWS CLI](cr-upd-ami-distribution-settings.md#cli-create-vm-dist-config).
**Distribuição de imagens de contêiner**
+ Especifique o repositório ECR em que o Image Builder armazena a imagem de saída na região de distribuição.
Você pode usar suas configurações de distribuição das seguintes formas para entregar imagens às regiões, contas AWS Organizations e unidades organizacionais (OUs) de destino uma vez ou com cada criação de funil:
+ Para entregar automaticamente imagens atualizadas para regiões, contas, Organizations especificadas e OUs use as configurações de distribuição com um pipeline do Image Builder que é executado de acordo com um cronograma.
+ Para criar uma nova imagem e entregá-la às regiões, contas e organizações especificadas OUs, use as configurações de distribuição com um pipeline do Image Builder que você executa uma vez no console do Image Builder, usando **Run pipeline** no menu **Actions**.
+ Para criar uma nova imagem e entregá-la às regiões, contas, organizações e organizações especificadas OUs, use as configurações de distribuição com a seguinte ação de API ou comando Image Builder no AWS CLI:
+ A ação **[CreateImage](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_CreateImage.html)** na API do Image Builder.
+ O comando **[create-image](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-image.html)** na AWS CLI.
+ Para exportar discos de imagem de máquina virtual (VM) para buckets do S3 nas regiões de destino como parte do seu processo normal de compilação de imagens.
**dica**
Quando você tem vários recursos do mesmo tipo, a marcação com tags ajuda a identificar um recurso específico com base nas tags que você atribuiu a ele. Para obter mais informações sobre como marcar seus recursos usando os comandos do Image Builder no AWS CLI, consulte a [Marcar recursos](tag-resources.md) seção deste guia.
**Topics**
+ [
# Listar e visualizar detalhes de uma configuração de distribuição
](distribution-settings-detail.md)
+ [
# Criar e atualizar as configurações de distribuição da AMI
](cr-upd-ami-distribution-settings.md)
+ [
# Criar e atualizar configurações de distribuição para imagens de contêiner
](cr-upd-container-distribution-settings.md)
+ [
# Configurar a distribuição da AMI entre contas com o Image Builder
](cross-account-dist.md)
+ [
# Configurar a distribuição da AMI com um modelo de execução do EC2
](dist-using-launch-template.md)
+ [
# Use recursos aprimorados de distribuição de AMI
](distribution-enhanced_functionality.md)
# Listar e visualizar detalhes de uma configuração de distribuição
Esta seção descreve as várias maneiras pelas quais você pode encontrar informações e visualizar detalhes de suas configurações de distribuição do EC2 Image Builder.
**Topics**
+ [
## Listar configurações de distribuição com o console
](#list-distribution-config-console)
+ [
## Visualizar detalhes da configuração de distribuição com o console
](#view-distribution-config-details-console)
+ [
## Listar distribuições do AWS CLI
](#cli-list-distributions)
+ [
## Obtenha detalhes da configuração de distribuição no AWS CLI
](#cli-get-distribution-configuration)
## Listar configurações de distribuição com o console
Para ver uma lista das configurações de distribuição que foram criadas em sua conta no console do Image Builder, siga estas etapas:
1. Abra o console [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/)do EC2 Image Builder em.
1. Escolha **Configurações de distribuição** no painel de navegação. Isso mostra uma lista das configurações de distribuição criadas em sua conta.
1. Para ver detalhes ou criar uma nova configuração de distribuição, escolha o link **Nome da configuração**. Isso abre a visualização detalhada das configurações de distribuição.
**nota**
Você também pode selecionar a caixa ao lado do **nome da configuração** e, em seguida, escolher **Exibir detalhes**.
## Visualizar detalhes da configuração de distribuição com o console
Para ver detalhes de uma configuração de distribuição específica usando o console do Image Builder, selecione a configuração a ser revisada e use as etapas descritas em [Listar configurações de distribuição com o console](#list-distribution-config-console).
Na página de detalhes da distribuição, você pode:
+ **Excluir** a configuração de distribuição. Para obter mais informações sobre exclusão de recursos no Image Builder, consulte [Excluir recursos desatualizados ou não utilizados do Image Builder](delete-resources.md).
+ **Editar** detalhes de distribuição.
## Listar distribuições do AWS CLI
O exemplo a seguir mostra como usar o **[list-distribution-configurations](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/list-distribution-configurations.html)** comando no AWS CLI para listar todas as suas distribuições.
```
aws imagebuilder list-distribution-configurations
```
## Obtenha detalhes da configuração de distribuição no AWS CLI
O exemplo a seguir mostra como usar o **[get-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/get-distribution-configuration.html)** comando no AWS CLI para obter os detalhes de uma configuração de distribuição especificando seu Amazon Resource Name (ARN).
```
aws imagebuilder get-distribution-configuration --distribution-configuration-arn arn:aws:imagebuilder:us-west-2:123456789012:distribution-configuration/my-example-distribution-configuration
```
# Criar e atualizar as configurações de distribuição da AMI
Esta seção aborda a criação e a atualização de configurações de distribuição para uma AMI do Image Builder.
**Topics**
+ [
## Pré-requisitos de distribuição da AMI
](#ami-distribution-config-prereqs)
+ [
## Criar uma configuração de distribuição da AMI
](#create-ami-distribution-config)
+ [
## Atualizar uma configuração de distribuição da AMI
](#update-ami-distribution-config)
+ [
## Exemplo: habilite o EC2 Fast Launch com um modelo de execução para saída AMIs
](#create-ami-dist-win-fast-launch)
+ [
## Exemplo: Crie configurações de distribuição para discos VM de saída do AWS CLI
](#cli-create-vm-dist-config)
## Pré-requisitos de distribuição da AMI
Algumas configurações de distribuição têm pré-requisitos, como segue:
**Topics**
+ [Pré-requisitos do parâmetro de saída SSM](#ami-distribution-prereqs-ssm-param)
+ [Pré-requisitos do EC2 Fast Launch](#ami-distribution-prereqs-fast-launch)
### Pré-requisitos para parâmetros de saída SSM
Antes de criar uma nova configuração de distribuição da AMI que defina um AWS Systems Manager parâmetro do Parameter Store (parâmetro SSM), verifique se você atendeu aos seguintes pré-requisitos.
**Perfil de execução**
Ao criar um pipeline ou usar o comando create-image no AWS CLI, você só pode especificar uma função de execução do Image Builder. Se você tiver definido uma função de execução do fluxo de trabalho do Image Builder, você adicionaria quaisquer permissões de recursos adicionais a essa função. Caso contrário, você criaria um novo papel personalizado que inclua as permissões necessárias.
+ Para armazenar o ID da AMI de saída em um parâmetro SSM durante a distribuição, você deve especificar a `ssm:PutParameter` ação na função de execução do Image Builder, com o parâmetro listado como um recurso.
+ Ao definir o tipo de dados do parâmetro para sinalizar `AWS EC2 Image` ao Systems Manager que valide o valor do parâmetro como uma ID de AMI, você também deve adicionar a `ec2:DescribeImages` ação.
### Pré-requisitos para o EC2 Fast Launch
Antes de criar uma nova configuração de distribuição para o EC2 Fast Launch for Windows AMIs, verifique se você atendeu aos seguintes pré-requisitos.
+ Se você fornecer um modelo de inicialização personalizado ao configurar o EC2 Fast Launch, o serviço usará a VPC e outras configurações que você definiu no modelo de inicialização. Para obter mais informações, consulte [Usar um modelo de execução ao configurar o EC2 Fast Launch](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/win-fast-launch-configure.html#win-fast-launch-with-template).
+ Se você não usar um modelo de lançamento personalizado para definir suas configurações, deverá anexar a [https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/security-iam-awsmanpol-EC2FastLaunchFullAccess.html](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/security-iam-awsmanpol-EC2FastLaunchFullAccess.html)política à função do IAM que o Image Builder usa para criar sua imagem. Ao criar um pipeline ou usar o comando create-image no AWS CLI, você só pode especificar uma função de execução do Image Builder. Se você tiver definido uma função de execução do fluxo de trabalho do Image Builder, você adicionaria quaisquer permissões de recursos adicionais a essa função. Caso contrário, você criaria um novo papel personalizado que inclua as permissões necessárias.
Então, quando o Image Builder copia sua imagem, o EC2 Fast Launch cria automaticamente uma CloudFormation pilha com os seguintes recursos em sua. Conta da AWS
+ Uma nuvem privada virtual (VPC).
+ Sub-redes privadas em várias zonas de disponibilidade
+ Um modelo de lançamento configurado com o Instance Metadata Service versão 2 () IMDSv2
+ Um grupo de segurança sem regras de entrada e saída
**nota**
O Image Builder não permite a distribuição entre contas para AMIs com o EC2 Fast Launch pré-habilitado. O EC2 Fast Launch deve ser habilitado na conta de destino.
## Criar uma configuração de distribuição da AMI
As configurações de distribuição incluem o nome da AMI de saída, configurações de região específicas para criptografia, permissões de lançamento e Contas da AWS organizações e unidades organizacionais (OUs) que podem iniciar a AMI de saída e configurações de licença.
Uma configuração de distribuição permite que você especifique o nome e a descrição da sua AMI de saída, autorize outras pessoas Contas da AWS a iniciar a AMI, copie a AMI para outras contas e replique a AMI para outras AWS regiões. Também permite exportar a AMI para o Amazon Simple Storage Service (Amazon S3) ou configurar o EC2 Fast Launch para Windows de saída. AMIs Para tornar uma AMI pública, defina as contas autorizadas com permissão de execução como `all`. Consulte os exemplos para tornar uma AMI pública em **[ModifyImageAttribute](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyImageAttribute.html)** do EC2.
------
#### [ Console ]
Siga estas etapas para criar uma nova configuração de distribuição da AMI no Console de gerenciamento da AWS:
1. Abra o console [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/)do EC2 Image Builder em.
1. Escolha **Configurações de distribuição** no painel de navegação. Isso mostra uma lista das configurações de distribuição criadas em sua conta.
1. Escolha **Criar configurações de distribuição** na parte superior do painel **Configurações de distribuição**.
1. Na seção **Tipo de imagem**, escolha **imagem de máquina da Amazon (AMI)** como o tipo de saída.
1. Na seção **Geral**, insira um **Nome** para sua configuração de distribuição e uma descrição opcional.
1. Na seção **Configurações da região**, insira os seguintes detalhes para cada região em que você está distribuindo sua AMI:
1. A AMI é distribuída para a região atual (**Região 1**), por padrão. A **Região 1** é a fonte da distribuição. Algumas configurações da **Região 1** não estão abertas para edição. Para qualquer região que você adicionar, você pode escolher uma região na lista suspensa **Região**.
A **chave Kms** identifica o AWS KMS key que é usado para criptografar os volumes do EBS para sua imagem na região de destino. É importante observar que isso não se aplica à AMI original que a compilação cria em sua conta na região de origem (**Região 1**). A criptografia executada durante a fase de distribuição da compilação é somente para imagens que são distribuídas para outras contas ou regiões.
Para criptografar os volumes do EBS para a AMI criada na região de origem da sua conta, você deve definir a chave KMS no mapeamento de dispositivos de blocos de fórmula de imagem (**Armazenamento (volumes)** no console).
O Image Builder copia a AMI para as **contas de destino** que você especifica para a região.
**Pré-requisito**
Para copiar uma imagem entre contas, você deve criar o perfil `EC2ImageBuilderDistributionCrossAccountRole` em todas as contas de distribuição de destino e anexar a política gerenciada [Política Ec2ImageBuilderCrossAccountDistributionAccess](security-iam-awsmanpol.md#sec-iam-manpol-Ec2ImageBuilderCrossAccountDistributionAccess) ao perfil.
O **nome da AMI de saída** é opcional. Se você fornecer um nome, o nome final da AMI de saída incluirá um timestamp anexado de quando a AMI foi criada. Se você não especificar um nome, o Image Builder acrescentará o timestamp de compilação ao nome da fórmula. Isso garante nomes exclusivos de AMI para cada compilação.
1. Com o compartilhamento da AMI, você pode conceder acesso a AWS diretores específicos para executar instâncias da sua AMI. Se você expandir a seção de **compartilhamento da AMI**, poderá inserir os seguintes detalhes:
+ **Permissões de execução** — selecione **Privada** se quiser manter sua AMI privada e permitir o acesso de AWS diretores específicos para iniciar uma instância a partir da sua AMI privada. Selecione **Público** se quiser tornar sua AMI pública. Qualquer AWS diretor pode iniciar uma instância a partir da sua AMI pública.
+ **Diretores** — Você pode conceder acesso aos seguintes tipos de AWS Diretores para iniciar instâncias:
+ **AWS conta** — Conceda acesso a uma AWS conta específica
+ **Unidade organizacional (OU)**: conceda acesso a uma OU e a todas as suas entidades secundárias. As entidades OUs secundárias incluem AWS contas.
+ **Organização** — conceda acesso à sua AWS Organizations entidade e a todas as suas entidades secundárias. As entidades OUs secundárias incluem AWS contas.
Primeiro, selecione o tipo de entidade principal. Em seguida, insira o ID da entidade principal da AWS a qual deseja conceder acesso na caixa à direita da lista suspensa. Você pode inserir vários IDs tipos diferentes.
1. Você pode expandir a seção **Configuração de licença** para anexar as configurações de licença criadas com AWS License Manager às suas imagens do Image Builder. As configurações de licença contêm regras de licenciamento com base nos termos de seus contratos empresariais. O Image Builder inclui automaticamente as configurações de licença associadas à sua AMI básica.
1. Você pode expandir a seção de **configuração do modelo de inicialização** para especificar um modelo de inicialização do EC2 a ser usado para iniciar instâncias da AMI que você criou.
Se você estiver usando um modelo de execução do EC2, poderá instruir o Image Builder para criar uma nova versão do seu modelo de inicialização que inclua a ID de AMI mais recente após a conclusão da compilação. Para atualizar o modelo de lançamento, defina as configurações da seguinte forma:
+ **Nome do modelo de inicialização**: selecione o nome do modelo de inicialização que você deseja que o Image Builder atualize.
+ **Definir a versão padrão**: marque essa caixa de seleção para atualizar a versão padrão do modelo de execução para a nova versão.
Para adicionar outra configuração de modelo de inicialização, escolha **Adicionar configuração de modelo de inicialização**. Você pode ter até cinco configurações de modelo de inicialização por região.
1. Você pode expandir a seção de **configurações de parâmetros do SSM** para configurar um parâmetro do SSM que armazenará o ID da AMI de saída da imagem que é distribuída para a região de destino. Opcionalmente, você pode especificar uma conta de distribuição na Região.
**Nome do parâmetro** — Insira o nome do seu parâmetro. Por exemplo, `/output/image/param`.
**Tipo de dados** — Mantenha o valor padrão (`AWS EC2 Image`). Isso faz com que o Systems Manager valide o valor do parâmetro para garantir que seja um ID de AMI válido.
1. Para adicionar configurações de distribuição para outra região, escolha **Adicionar região**.
1. Quando concluir, escolha **Criar configurações**.
------
#### [ AWS CLI ]
O exemplo a seguir mostra como usar o comando **create-distribution-configuration** para criar uma nova configuração de distribuição para AMI, usando a AWS CLI.
1.
**Criar um arquivo JSON de entrada da CLI**
Use uma ferramenta de edição de arquivos para criar um arquivo JSON com as chaves mostradas em um dos exemplos a seguir e valores válidos para seu ambiente. Esses exemplos definem quais Contas da AWS unidades organizacionais (OUs) têm permissão para iniciar a AMI que você distribui para as regiões especificadas. AWS Organizations Nomeie o arquivo `create-ami-distribution-configuration.json` para uso na próxima etapa:
**Exemplo 1: Distribuir para Contas da AWS**
Este exemplo distribui uma AMI para duas regiões e especifica Contas da AWS que têm permissões de execução em cada região.
```
{
"name": "MyExampleAccountDistribution",
"description": "Copies AMI to eu-west-1, and specifies accounts that can launch instances in each Region.",
"distributions": [
{
"region": "us-west-2",
"amiDistributionConfiguration": {
"name": "Name {{imagebuilder:buildDate}}",
"description": "An example image name with parameter references",
"amiTags": {
"KeyName": "Some Value"
},
"launchPermission": {
"userIds": [
"987654321012"
]
}
}
},
{
"region": "eu-west-1",
"amiDistributionConfiguration": {
"name": "My {{imagebuilder:buildVersion}} image {{imagebuilder:buildDate}}",
"amiTags": {
"KeyName": "Some value"
},
"launchPermission": {
"userIds": [
"100000000001"
]
}
}
}
]
}
```
**Exemplo 2: Distribute to Organizations e OUs**
Este exemplo distribui uma AMI para a região de origem e especifica as permissões de lançamento da organização e da OU.
```
{
"name": "MyExampleAWSOrganizationDistribution",
"description": "Shares AMI with the Organization and OU",
"distributions": [
{
"region": "us-west-2",
"amiDistributionConfiguration": {
"name": "Name {{ imagebuilder:buildDate }}",
"launchPermission": {
"organizationArns": [
"arn:aws:organizations::123456789012:organization/o-myorganization123"
],
"organizationalUnitArns": [
"arn:aws:organizations::123456789012:ou/o-123example/ou-1234-myorganizationalunit"
]
}
}
}
]
}
```
**Exemplo 3: armazenar o ID da AMI de saída em um parâmetro SSM**
Este exemplo armazena o ID da AMI de saída em um AWS Systems Manager parâmetro do Parameter Store na região de distribuição.
```
{
"name": "SSMParameterOutputAMI",
"description": "Updates an SSM parameter with the output AMI ID for the distribution.",
"distributions": [
{
"region": "us-west-2",
"amiDistributionConfiguration": {
"name": "Name {{ imagebuilder:buildDate }}"
},
"ssmParameterConfigurations": [
{
"amiAccountId": "111122223333",
"parameterName": "/output/image/param",
"dataType": "aws:ec2:image"
}
]
}
]
}
```
1.
**Execute o seguinte comando, usando o arquivo que você criou como entrada.**
```
aws imagebuilder create-distribution-configuration --cli-input-json file://create-ami-distribution-configuration.json
```
**nota**
É necessário incluir a notação `file://` no início do caminho do arquivo JSON.
O caminho para o arquivo JSON deve seguir a convenção apropriada para o sistema operacional de base no qual você está executando o comando. Por exemplo, o Windows usa a barra invertida (\$1) para se referir ao caminho do diretório, enquanto o Linux e o macOS usam a barra (/).
Para obter mais informações detalhadas, consulte **[create-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-distribution-configuration.html)** na *Referência de comandos da AWS CLI *.
------
## Atualizar uma configuração de distribuição da AMI
Você pode alterar a configuração de distribuição da AMI. No entanto, as alterações feitas não se aplicam a nenhum recurso que o Image Builder já tenha distribuído. Por exemplo, se você distribuiu uma AMI para uma região que posteriormente removeu da sua distribuição, a AMI que já foi distribuída permanece nessa região até que você a remova manualmente.
------
#### [ Console de gerenciamento da AWS ]
Siga estas etapas para obter uma configuração de distribuição da AMI no Console de gerenciamento da AWS:
1. Abra o console [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/)do EC2 Image Builder em.
1. Escolha **Configurações de distribuição** no painel de navegação. Isso mostra uma lista das configurações de distribuição criadas em sua conta.
1. Para ver detalhes ou atualizar uma configuração de distribuição, escolha o link **Nome da configuração**. Isso abre a visualização detalhada das configurações de distribuição.
**nota**
Você também pode selecionar a caixa ao lado do **nome da configuração** e, em seguida, escolher **Exibir detalhes**.
1. Para editar a configuração da distribuição, escolha **Editar** no canto superior direito da seção **Detalhes da distribuição**. Alguns campos estão bloqueados, como o **Nome** da configuração de distribuição e a **Região** padrão que é exibida como **Região 1**. Para obter mais informações sobre as configurações de distribuição, consulte [Criar uma configuração de distribuição da AMI](#create-ami-distribution-config).
1. Quando concluir, escolha **Salvar alterações**.
------
#### [ AWS CLI ]
O exemplo a seguir mostra como usar o comando **[update-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/update-distribution-configuration.html)** para atualizar as configurações de distribuição da AMI, usando a AWS CLI.
1.
**Criar um arquivo JSON de entrada da CLI**
Use uma ferramenta de edição de arquivos para criar um arquivo JSON com as chaves mostradas no exemplo a seguir e valores válidos para seu ambiente. Este exemplo usa um arquivo denominado `update-ami-distribution-configuration.json`.
```
{
"distributionConfigurationArn": "arn:aws:imagebuilder:us-west-2:123456789012:distribution-configuration/update-ami-distribution-configuration.json",
"description": "Copies AMI to eu-west-2, and specifies accounts that can launch instances in each Region.",
"distributions": [
{
"region": "us-west-2",
"amiDistributionConfiguration": {
"name": "Name {{imagebuilder:buildDate}}",
"description": "An example image name with parameter references",
"launchPermissions": {
"userIds": [
"987654321012"
]
}
}
},
{
"region": "eu-west-2",
"amiDistributionConfiguration": {
"name": "My {{imagebuilder:buildVersion}} image {{imagebuilder:buildDate}}",
"tags": {
"KeyName": "Some value"
},
"launchPermissions": {
"userIds": [
"100000000001"
]
}
}
}
]
}
```
1.
**Execute o seguinte comando, usando o arquivo que você criou como entrada.**
```
aws imagebuilder update-distribution-configuration --cli-input-json file://update-ami-distribution-configuration.json
```
**nota**
É necessário incluir a notação `file://` no início do caminho do arquivo JSON.
O caminho para o arquivo JSON deve seguir a convenção apropriada para o sistema operacional de base no qual você está executando o comando. Por exemplo, o Windows usa a barra invertida (\$1) para se referir ao caminho do diretório, enquanto o Linux e o macOS usam a barra (/).
Para obter mais informações detalhadas, consulte **[update-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/update-distribution-configuration.html)** na *Referência de comandos da AWS CLI *. Para atualizar as tags do seu recurso de configuração de distribuição, consulte a seção [Marcar recursos](tag-resources.md).
------
## Exemplo: habilite o EC2 Fast Launch com um modelo de execução para saída AMIs
O exemplo a seguir mostra como usar o **[create-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-distribution-configuration.html)** comando com um modelo de execução para criar configurações de distribuição que tenham o EC2 Fast Launch configurado para sua AMI, a AWS CLI partir do.
Para definir as configurações do EC2 Fast Launch sem um modelo de execução, certifique-se de ter cumprido todos os requisitos [Pré-requisitos do EC2 Fast Launch](#ami-distribution-prereqs-fast-launch) antes de criar sua configuração de distribuição.
1.
**Criar um arquivo JSON de entrada da CLI**
Use uma ferramenta de edição de arquivos para criar um arquivo JSON com as chaves como mostrado no exemplo a seguir, além de valores válidos para seu ambiente.
Este exemplo executa instâncias para todos os seus recursos de destino simultaneamente, porque o número máximo de inicializações paralelas é maior que a contagem de recursos de destino. Esse arquivo é nomeado `ami-dist-config-win-fast-launch.json` no exemplo de comando mostrado na próxima etapa.
```
{
"name": "WinFastLaunchDistribution",
"description": "An example of Windows AMI EC2 Fast Launch settings in the distribution configuration.",
"distributions": [
{
"region": "us-west-2",
"amiDistributionConfiguration": {
"name": "Name {{imagebuilder:buildDate}}",
"description": "Includes Windows AMI EC2 Fast Launch settings.",
"amiTags": {
"KeyName": "Some Value"
}
},
"fastLaunchConfigurations": [{
"enabled": true,
"snapshotConfiguration": {
"targetResourceCount": 5
},
"maxParallelLaunches": 6,
"launchTemplate": {
"launchTemplateId": "lt-0ab1234c56d789012",
"launchTemplateVersion": "1"
}
}],
"launchTemplateConfigurations": [{
"launchTemplateId": "lt-0ab1234c56d789012",
"setDefaultVersion": true
}]
}]
}
```
**nota**
Você pode especificar o `launchTemplateName` em vez do `launchTemplateId` na seção `launchTemplate`, mas não pode especificar o nome e o ID.
1.
**Execute o seguinte comando, usando o arquivo que você criou como entrada.**
```
aws imagebuilder create-distribution-configuration --cli-input-json file://ami-dist-config-win-fast-launch.json
```
**nota**
É necessário incluir a notação `file://` no início do caminho do arquivo JSON.
O caminho para o arquivo JSON deve seguir a convenção apropriada para o sistema operacional de base no qual você está executando o comando. Por exemplo, o Windows usa a barra invertida (\$1) para se referir ao caminho do diretório, enquanto o Linux e o macOS usam a barra (/).
Para obter mais informações detalhadas, consulte **[create-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-distribution-configuration.html)** na *Referência de comandos da AWS CLI *.
## Exemplo: Crie configurações de distribuição para discos VM de saída do AWS CLI
O exemplo a seguir mostra como usar o comando **create-distribution-configuration** para criar configurações de distribuição que exportarão discos de imagem da VM para o Amazon S3 a cada compilação de imagem.
1.
**Criar um arquivo JSON de entrada da CLI**
Você pode simplificar o comando **create-distribution-configuration** que você usa na AWS CLI. Para fazer isso, crie um arquivo JSON que contenha toda a configuração de exportação que você deseja passar para o comando.
**nota**
A convenção de nomenclatura para os valores de dados no arquivo JSON segue o padrão especificado para os parâmetros de solicitação de operação da API Image Builder. Para revisar os parâmetros da solicitação de operação da API, consulte o **[CreateDistributionConfiguration](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_CreateDistributionConfiguration.html)** comando na Referência da *API do EC2 Image Builder*.
Para fornecer os valores dos dados como parâmetros da linha de comando, consulte os nomes dos parâmetros especificados na *Referência de comando do AWS CLI * para o comando **create-distribution-configuration** como opções.
Aqui está um resumo dos parâmetros que especificamos no objeto JSON `s3ExportConfiguration` deste exemplo:
+ **roleName** (string, required) — O nome da função que concede Import/Export permissão à VM para exportar imagens para seu bucket do S3.
+ **diskImageFormat**(string, obrigatório) — Exporte a imagem de disco atualizada para um dos seguintes formatos compatíveis:
+ **Virtual Hard Disk (VHD)**: compatível com os produtos de virtualização Citrix Xen e Microsoft Hyper-V.
+ **Disco de máquina virtual ESX (VMDK) otimizado para streaming** — compatível com as versões 4, 5 e 6 do ESX VMware e VMware vSphere.
+ **Raw**: formato bruto.
+ **S3bucket** (string, obrigatório): o bucket S3 no qual armazenar as imagens de disco de saída para sua VM.
Salve o arquivo como `export-vm-disks.json`. Use o nome do arquivo no comando **create-distribution-configuration**.
```
{
"name": "example-distribution-configuration-with-vm-export",
"description": "example",
"distributions": [
{
"region": "us-west-2",
"amiDistributionConfiguration": {
"description": "example-with-vm-export"
},
"s3ExportConfiguration": {
"roleName": "vmimport",
"diskImageFormat": "RAW",
"s3Bucket": "vm-bucket-export"
}
}],
"clientToken": "abc123def4567ab"
}
```
1.
**Execute o seguinte comando, usando o arquivo que você criou como entrada.**
```
aws imagebuilder create-distribution-configuration --cli-input-json file://export-vm-disks.json
```
**nota**
É necessário incluir a notação `file://` no início do caminho do arquivo JSON.
O caminho para o arquivo JSON deve seguir a convenção apropriada para o sistema operacional de base no qual você está executando o comando. Por exemplo, o Windows usa a barra invertida (\$1) para se referir ao caminho do diretório, enquanto o Linux e o macOS usam a barra (/).
Para obter mais informações detalhadas, consulte **[create-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-distribution-configuration.html)** na *Referência de comandos da AWS CLI *.
# Criar e atualizar configurações de distribuição para imagens de contêiner
Esta seção aborda a criação e a atualização de configurações de distribuição de imagens de contêiner do Image Builder.
**Topics**
+ [
## Crie configurações de distribuição para imagens de contêiner do Image Builder a partir do AWS CLI
](#cli-create-container-distribution-configuration)
+ [
## Atualize as configurações de distribuição da imagem do seu contêiner a partir do AWS CLI
](#cli-update-container-distribution-configuration)
## Crie configurações de distribuição para imagens de contêiner do Image Builder a partir do AWS CLI
Uma configuração de distribuição permite que você especifique o nome e a descrição da imagem do contêiner de saída e replique a imagem do contêiner para outras AWS regiões. Você também pode aplicar tags separadas ao recurso de configuração de distribuição e às imagens do contêiner em cada região.
1.
**Criar um arquivo JSON de entrada da CLI**
Use a sua ferramenta de edição de arquivos favorita para criar um arquivo JSON com as chaves mostradas no exemplo a seguir, além de valores válidos para seu ambiente. Este exemplo usa um arquivo denominado `create-container-distribution-configuration.json`:
```
{
"name": "distribution-configuration-name",
"description": "Distributes container image to Amazon ECR repository in two regions.",
"distributions": [
{
"region": "us-west-2",
"containerDistributionConfiguration": {
"description": "My test image.",
"targetRepository": {
"service": "ECR",
"repositoryName": "testrepo"
},
"containerTags": ["west2", "image1"]
}
},
{
"region": "us-east-1",
"containerDistributionConfiguration": {
"description": "My test image.",
"targetRepository": {
"service": "ECR",
"repositoryName": "testrepo"
},
"containerTags": ["east1", "imagedist"]
}
}
],
"tags": {
"DistributionConfigurationTestTagKey1": "DistributionConfigurationTestTagValue1",
"DistributionConfigurationTestTagKey2": "DistributionConfigurationTestTagValue2"
}
}
```
1.
**Execute o seguinte comando, usando o arquivo que você criou como entrada.**
```
aws imagebuilder create-distribution-configuration --cli-input-json file://create-container-distribution-configuration.json
```
**nota**
É necessário incluir a notação `file://` no início do caminho do arquivo JSON.
O caminho para o arquivo JSON deve seguir a convenção apropriada para o sistema operacional de base no qual você está executando o comando. Por exemplo, o Windows usa a barra invertida (\$1) para se referir ao caminho do diretório, enquanto o Linux e o macOS usam a barra (/).
Para obter mais informações detalhadas, consulte **[create-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-distribution-configuration.html)** na *Referência de comandos da AWS CLI *.
## Atualize as configurações de distribuição da imagem do seu contêiner a partir do AWS CLI
O exemplo a seguir mostra como usar o comando **[update-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/update-distribution-configuration.html)** para atualizar as configurações de distribuição da imagem de contêiner usando a AWS CLI. Você também pode atualizar as tags das imagens de contêiner em cada região.
1.
**Criar um arquivo JSON de entrada da CLI**
Use a sua ferramenta de edição de arquivos favorita para criar um arquivo JSON com as chaves mostradas no exemplo a seguir, além de valores válidos para seu ambiente. Este exemplo usa um arquivo denominado `update-container-distribution-configuration.json`:
```
{
"distributionConfigurationArn": "arn:aws:imagebuilder:us-west-2:123456789012:distribution-configuration/update-container-distribution-configuration.json",
"description": "Distributes container image to Amazon ECR repository in two regions.",
"distributions": [
{
"region": "us-west-2",
"containerDistributionConfiguration": {
"description": "My test image.",
"targetRepository": {
"service": "ECR",
"repositoryName": "testrepo"
},
"containerTags": ["west2", "image1"]
}
},
{
"region": "us-east-2",
"containerDistributionConfiguration": {
"description": "My test image.",
"targetRepository": {
"service": "ECR",
"repositoryName": "testrepo"
},
"containerTags": ["east2", "imagedist"]
}
}
]
}
```
1.
**Execute o seguinte comando, usando o arquivo que você criou como entrada:**
```
aws imagebuilder update-distribution-configuration --cli-input-json file://update-container-distribution-configuration.json
```
**nota**
É necessário incluir a notação `file://` no início do caminho do arquivo JSON.
O caminho para o arquivo JSON deve seguir a convenção apropriada para o sistema operacional de base no qual você está executando o comando. Por exemplo, o Windows usa a barra invertida (\$1) para se referir ao caminho do diretório, enquanto o Linux e o macOS usam a barra (/).
Para obter mais informações detalhadas, consulte **[update-distribution-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/update-distribution-configuration.html)** na *Referência de comandos da AWS CLI *. Para atualizar as tags do seu recurso de configuração de distribuição, consulte a seção [Marcar recursos](tag-resources.md).
# Configurar a distribuição da AMI entre contas com o Image Builder
Esta seção descreve como você pode definir as configurações de distribuição para entregar uma AMI do Image Builder para outras contas que você especificar.
A conta de destino pode então inicializar ou modificar a AMI, conforme necessário.
**nota**
AWS CLI os exemplos de comando nesta seção pressupõem que você tenha criado anteriormente arquivos JSON de receita de imagem e configuração de infraestrutura. Para criar o arquivo JSON para uma fórmula de imagem, consulte [Crie uma receita de imagem com o AWS CLI](create-image-recipes.md#create-image-recipe-cli). Para criar o arquivo JSON para uma configuração de infraestrutura, consulte [Criar uma configuração de infraestrutura](create-infra-config.md).
## Pré-requisitos para a distribuição da AMI entre contas
Para garantir que as contas de destino possam inicializar as instâncias com sucesso a partir da sua imagem do Image Builder, você deve configurar as permissões apropriadas para todas as contas de destino em todas as regiões.
Se você criptografar sua AMI usando AWS Key Management Service (AWS KMS), deverá configurar uma AWS KMS key para sua conta que seja usada para criptografar a nova imagem.
Quando o Image Builder realiza a distribuição entre contas para criptografia AMIs, a imagem na conta de origem é descriptografada e enviada para a região de destino, onde é recriptografada usando a chave designada para essa região. Como o Image Builder age em nome da conta de destino e usa um perfil do IAM que você cria na região de destino, essa conta deve ter acesso às chaves nas regiões de origem e de destino.
### Chaves de criptografia
Os pré-requisitos a seguir são necessários se sua imagem for criptografada usando AWS KMS. Os pré-requisitos do IAM são abordados na próxima seção.
**Requisitos da conta de origem**
+ Crie uma chave do KMS em sua conta em todas as regiões em que você compila e distribui sua AMI. Você também pode usar uma chave existente.
+ Atualize a política de chave para todas essas chaves, para permitir que as contas de destino usem sua chave.
**Requisitos da conta de destino**
+ Adicione uma política em linha para `EC2ImageBuilderDistributionCrossAccountRole` que permita que o perfil execute as ações necessárias para distribuir uma AMI criptografada. Para ver as etapas de configuração do IAM, consulte a seção de pré-requisitos [Políticas do IAM](#cross-account-prereqs-iam).
Para obter mais informações sobre o uso do acesso entre contas AWS KMS, consulte [Permitir que usuários em outras contas usem uma chave KMS](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-modifying-external-accounts.html) no Guia do *AWS Key Management Service desenvolvedor*.
Especifique sua chave de criptografia na fórmula da imagem, da seguinte forma:
+ Se você estiver usando o console do Image Builder, escolha sua chave de criptografia na lista suspensa **Criptografia (alias KMS)** na seção **Armazenamento (volumes)** da sua fórmula.
+ Se você estiver usando a ação da **CreateImageRecipe** API ou o **create-image-recipe** comando no AWS CLI, configure sua chave na `ebs` seção abaixo `blockDeviceMappings` em sua entrada JSON.
O snippet de JSON a seguir mostra as configurações de criptografia de uma fórmula de imagem. Além de fornecer sua chave de criptografia, você também deve definir o sinalizador `encrypted` como `true`.
```
{
...
"blockDeviceMappings": [
{
"deviceName": "Example root volume",
"ebs": {
"deleteOnTermination": true,
"encrypted": true,
"iops": 100,
"kmsKeyId": "image-owner-key-id",
...
},
...
}],
...
}
```
### Políticas do IAM
Para configurar as permissões de distribuição entre contas no AWS Identity and Access Management (IAM), siga estas etapas:
1. Para usar o Image Builder AMIs distribuído entre contas, o proprietário da conta de destino deve criar uma nova função do IAM em sua conta chamada`EC2ImageBuilderDistributionCrossAccountRole`.
1. Ele deve anexar o [Política Ec2ImageBuilderCrossAccountDistributionAccess](security-iam-awsmanpol.md#sec-iam-manpol-Ec2ImageBuilderCrossAccountDistributionAccess) ao perfil para permitir a distribuição entre contas. Para obter mais informações sobre políticas gerenciadas, consulte [Políticas gerenciadas e políticas em linha](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies) no *Guia do usuário do AWS Identity and Access Management *.
1. Verifique se o ID da conta de origem foi adicionado à política de confiança anexada ao perfil do IAM da conta de destino. O exemplo a seguir mostra uma política de confiança na conta de destino que especifica o ID da conta de origem.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::444455556666:root"
},
"Action": "sts:AssumeRole"
}]
}
```
------
Para obter mais informações sobre políticas de confiança, consulte [Políticas Baseadas em Recursos](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_resource-based) no *Guia do Usuário do AWS Identity and Access Management *.
1. Se a AMI que você distribui for criptografada, o proprietário da conta de destino deverá adicionar a seguinte política em linha ao `EC2ImageBuilderDistributionCrossAccountRole` na conta dele para que ele possa usar suas chaves KMS. A seção `Principal` contém o número da conta dele. Isso permite que o Image Builder aja em seu nome quando usado AWS KMS para criptografar e descriptografar a AMI com as chaves apropriadas para cada região.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowRoleToPerformKMSOperationsOnBehalfOfTheDestinationAccount",
"Effect": "Allow",
"Action": [
"kms:Encrypt",
"kms:Decrypt",
"kms:ReEncrypt*",
"kms:GenerateDataKey*",
"kms:DescribeKey",
"kms:CreateGrant",
"kms:ListGrants",
"kms:RevokeGrant"
],
"Resource": "*"
}
]
}
```
------
Para obter mais informações sobre políticas em linha, consulte [Políticas em linha](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#inline-policies) no *Guia do usuário do AWS Identity and Access Management *.
1. Se você estiver usando `launchTemplateConfigurations` para especificar um modelo de inicialização do Amazon EC2, você também deve adicionar a seguinte política ao seu `EC2ImageBuilderDistributionCrossAccountRole` em cada conta de destino.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:CreateLaunchTemplateVersion",
"ec2:ModifyLaunchTemplate"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/CreatedBy": "EC2 Image Builder"
}
}
},
{
"Effect": "Allow",
"Action": [
"ec2:DescribeLaunchTemplates"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"ec2:CreateTags"
],
"Resource": "arn:aws:ec2:*:*:launch-template/*",
"Condition": {
"StringEquals": {
"aws:RequestTag/CreatedBy": "EC2 Image Builder"
}
}
}
]
}
```
------
1. Se você usar um AWS Systems Manager parâmetro do Parameter Store para armazenar o ID da AMI de saída para a conta de distribuição e a região, deverá adicionar a seguinte política à sua `EC2ImageBuilderDistributionCrossAccountRole` em cada conta de destino.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssm:PutParameter"
],
"Resource": "arn:aws:ssm:*:111122223333:parameter/ImageBuilder-*"
},
{
"Effect": "Allow",
"Action": [
"ec2:DescribeImages"
],
"Resource": "*"
}
]
}
```
------
## Limites para a distribuição entre contas
Há algumas limitações ao distribuir imagens do Image Builder entre contas:
+ A conta de destino está limitada a 50 cópias simultâneas da AMI para cada região de destino.
+ Se você quiser copiar uma AMI de virtualização paravirtual (PV) para outra região, a região de destino deve oferecer suporte à virtualização fotovoltaica. AMIs Para obter mais informações, consulte [Linux AMI virtualization types](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/virtualization_types.html).
+ Você não pode criar uma cópia não criptografada de um snapshot criptografado. Se você não especificar uma chave gerenciada pelo cliente AWS Key Management Service (AWS KMS) para o parâmetro `KmsKeyId`, o Image Builder usa a chave padrão para o Amazon Elastic Block Store (Amazon EBS). Para obter mais informações, consulte [Criptografia do Amazon EBS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html) no *Guia do usuário do Amazon Elastic Compute Cloud*.
Para obter mais informações, consulte a [CreateDistributionConfiguration](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_CreateDistributionConfiguration.html)Referência da *API EC2 Image Builder*.
## Configurar a distribuição entre contas para uma AMI do Image Builder com o console
Esta seção descreve como criar e definir configurações de distribuição para distribuição entre contas do Image Builder AMIs usando o. Console de gerenciamento da AWS A configuração da distribuição entre contas requer permissões específicas do IAM. Você deve preencher o [Pré-requisitos para a distribuição da AMI entre contas](#cross-account-dist-prereqs) para esta seção antes de continuar.
Para criar configurações de distribuição no console do Image Builder, siga estas etapas:
1. Abra o console [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/)do EC2 Image Builder em.
1. Escolha **Configurações de distribuição** no painel de navegação. Isso mostra uma lista das configurações de distribuição criadas em sua conta.
1. Na parte superior da página **Configurações de distribuição**, escolha **Criar configurações de distribuição**. Isso o leva para a página **Criar configurações de distribuição**.
1. Na seção **Tipo de imagem**, escolha **imagem de máquina da Amazon (AMI)** como o **Tipo de saída**. Essa é a configuração padrão.
1. Na seção **Geral**, insira o **Nome** do recurso de configurações de distribuição que você deseja criar (*obrigatório*).
1. Na seção **Configurações de região**, insira um ID de conta de 12 dígitos para o qual você deseja distribuir sua AMI em **Contas de destino** da região selecionada e pressione **Enter**. Isso verifica se a formatação está correta e, em seguida, exibe o ID da conta que você inseriu abaixo da caixa. Repita o processo para adicionar mais contas.
Para remover uma conta que você inseriu, escolha o **X** exibido à direita do ID da conta.
Insira o **Nome da AMI de saída** para cada região.
1. Continue especificando quaisquer configurações adicionais necessárias e escolha **Criar configurações** para criar seu novo recurso de configurações de distribuição.
## Configure a distribuição entre contas para uma AMI do Image Builder a partir do AWS CLI
Esta seção descreve como definir um arquivo de configurações de distribuição e usar o **create-image** comando AWS CLI para criar e distribuir uma AMI do Image Builder entre contas.
A configuração da distribuição entre contas requer permissões específicas do IAM. Você deve preencher o [Pré-requisitos para a distribuição da AMI entre contas](#cross-account-dist-prereqs) para esta seção antes de executar o comando **create-image**.
1.
**Configurar um arquivo de configurações de distribuição**
Antes de usar o **create-image** comando no AWS CLI para criar uma AMI do Image Builder que seja distribuída para outra conta, você deve criar uma estrutura `DistributionConfiguration` JSON que especifique a conta de destino IDs nas `AmiDistributionConfiguration` configurações. Você deve especificar pelo menos um `AmiDistributionConfiguration` na região de origem.
O arquivo de amostra a seguir, denominado `create-distribution-configuration.json`, mostra a configuração para distribuição de imagem entre contas na região de origem.
```
{
"name": "cross-account-distribution-example",
"description": "Cross Account Distribution Configuration Example",
"distributions": [
{
"amiDistributionConfiguration": {
"targetAccountIds": ["123456789012", "987654321098"],
"name": "Name {{ imagebuilder:buildDate }}",
"description": "ImageCopy Ami Copy Configuration"
},
"region": "us-west-2"
}
]
}
```
1.
**Criar as configurações de distribuição**
Para criar um recurso de configurações de distribuição do Image Builder usando o [create-distribution-configuration](https://docs.aws.amazon.com/cli/latest/reference/imagebuilder/create-distribution-configuration.html)comando no AWS CLI, forneça os seguintes parâmetros no comando:
+ Insira o nome da distribuição no parâmetro `--name`.
+ Anexe o arquivo JSON de configuração de distribuição que você criou no parâmetro `--cli-input-json`.
```
aws imagebuilder create-distribution-configuration --name my distribution name --cli-input-json file://create-distribution-configuration.json
```
**nota**
É necessário incluir a notação `file://` no início do caminho do arquivo JSON.
O caminho para o arquivo JSON deve seguir a convenção apropriada para o sistema operacional de base no qual você está executando o comando. Por exemplo, o Windows usa a barra invertida (\$1) para se referir ao caminho do diretório, enquanto o Linux e o macOS usam a barra (/).
*Você também pode fornecer o JSON diretamente no comando, usando o parâmetro `--distributions`.*
# Configurar a distribuição da AMI com um modelo de execução do EC2
A fim de ajudar a garantir uma experiência de execução consistente para sua AMI do Image Builder nas contas e regiões de destino, você pode usar `launchTemplateConfigurations` para especificar um modelo de execução do Amazon EC2 em suas configurações de distribuição. Quando `launchTemplateConfigurations` estão presentes durante o processo de distribuição, o Image Builder cria uma nova versão do modelo de lançamento que inclui todas as configurações originais do modelo e a nova AMI ID da compilação. Para obter mais informações sobre a execução de uma instância do EC2 usando um modelo de execução, consulte um dos links a seguir dependendo do sistema operacional de destino.
+ [Executar uma instância Linux a partir de um modelo de execução](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-launch-templates.html)
+ [Executar uma instância Windows a partir de um modelo de execução](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-launch-templates.html)
**nota**
Quando você inclui um modelo de execução para habilitar a inicialização rápida do Windows em sua imagem, o modelo de execução deve incluir a tag a seguir para que o Image Builder possa habilitá-la em seu nome.
`CreatedBy: EC2 Image Builder`
## Adicionar um modelo de execução do EC2 às configurações de distribuição da AMI com o console
Para fornecer um modelo de execução com sua AMI de saída, siga estas etapas no console:
1. Abra o console [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/)do EC2 Image Builder em.
1. Escolha **Configurações de distribuição** no painel de navegação. Isso mostra uma lista das configurações de distribuição criadas em sua conta.
1. Na parte superior da página **Configurações de distribuição**, escolha **Criar configurações de distribuição**. Isso abre a página **Criar configurações de distribuição**.
1. Na seção **Tipo de imagem**, escolha **imagem de máquina da Amazon (AMI)** como o **tipo de saída**. Essa é a configuração padrão.
1. Na seção **Geral**, insira o **Nome** do recurso de configurações de distribuição que você deseja criar (*obrigatório*).
1. Na seção **Configurações de região**, selecione o nome de um modelo de execução do EC2 na lista. Se não houver modelos de lançamento em sua conta, escolha **Criar novo modelo de lançamento**, que abre os **modelos de lançamento** no **painel do EC2**.
Selecione a caixa de seleção **Definir a versão padrão** para atualizar a versão padrão do modelo de execução para a nova versão que o Image Builder cria com sua AMI de saída.
Para adicionar outro modelo de lançamento à região selecionada, escolha **Adicionar configuração de modelo de lançamento**.
Para remover um modelo de lançamento, escolha **Remover**.
1. Continue especificando quaisquer configurações adicionais necessárias e escolha **Criar configurações** para criar seu novo recurso de configurações de distribuição.
## Adicione um modelo de execução do EC2 às configurações de distribuição da AMI a partir do AWS CLI
Esta seção descreve como definir um arquivo de configurações de distribuição com um modelo de execução e usar o **create-image** comando em AWS CLI para criar e distribuir uma AMI do Image Builder e uma nova versão do modelo de execução que a usa.
1.
**Configurar um arquivo de configurações de distribuição**
Antes de criar uma AMI do Image Builder com um modelo de execução, usando o AWS CLI, você deve criar uma estrutura JSON de configuração de distribuição que especifique as `launchTemplateConfigurations` configurações. Você deve especificar pelo menos uma entrada `launchTemplateConfigurations` na região de origem.
O arquivo de exemplo a seguir, denominado`create-distribution-config-launch-template.json`, mostra alguns cenários possíveis para a configuração do modelo de execução na região de origem.
```
{
"name": "NewDistributionConfiguration",
"description": "This is just a test",
"distributions": [
{
"region": "us-west-2",
"amiDistributionConfiguration": {
"name": "test-{{imagebuilder:buildDate}}-{{imagebuilder:buildVersion}}",
"description": "description"
},
"launchTemplateConfigurations": [
{
"launchTemplateId": "lt-0a1bcde2fgh34567",
"accountId": "935302948087",
"setDefaultVersion": true
},
{
"launchTemplateId": "lt-0aaa1bcde2ff3456"
},
{
"launchTemplateId": "lt-12345678901234567",
"accountId": "123456789012"
}
]
}
],
"clientToken": "clientToken1"
}
```
1.
**Criar as configurações de distribuição**
Para criar um recurso de configurações de distribuição do Image Builder usando o [create-distribution-configuration](https://docs.aws.amazon.com/cli/latest/reference/imagebuilder/create-distribution-configuration.html)comando no AWS CLI, forneça os seguintes parâmetros no comando:
+ Insira o nome da distribuição no parâmetro `--name`.
+ Anexe o arquivo JSON de configuração de distribuição que você criou no parâmetro `--cli-input-json`.
```
aws imagebuilder create-distribution-configuration --name my distribution name--cli-input-json file://create-distribution-config-launch-template.json
```
**nota**
É necessário incluir a notação `file://` no início do caminho do arquivo JSON.
O caminho para o arquivo JSON deve seguir a convenção apropriada para o sistema operacional de base no qual você está executando o comando. Por exemplo, o Windows usa a barra invertida (\$1) para se referir ao caminho do diretório, enquanto o Linux e o macOS usam a barra (/).
*Você também pode fornecer o JSON diretamente no comando, usando o parâmetro `--distributions`.*
# Use recursos aprimorados de distribuição de AMI
O Image Builder oferece recursos avançados de distribuição que oferecem flexibilidade e controle sobre como AMIs você é distribuído entre regiões e contas. Esses recursos separam a distribuição do processo de criação, permitindo que você distribua imagens existentes sob demanda, recupere-se de falhas de distribuição com eficiência e implemente estratégias de distribuição controladas em vários estágios por meio de fluxos de trabalho personalizáveis.
Você pode usar recursos aprimorados de distribuição de AMI no Image Builder para realizar atividades de distribuição diretamente sem a necessidade de executar novamente uma criação de imagem completa.
## Distribuição desacoplada
A DistributeImage API aceita três tipos de referências de imagem de origem:
+ **ID da AMI** — Um identificador padrão da AMI (por exemplo,`ami-0abcdef1234567890`)
+ Parâmetro **SSM — Um parâmetro** SSM que armazena uma ID de AMI (por exemplo,) `ssm:/my/ami/parameter`
+ **Versão ARN do Image Builder — Uma versão ARN** da imagem do Image Builder
## Tentativa de distribuição
Se uma distribuição de imagem falhar, use a `RetryImage` API para tentar novamente a distribuição. Isso reduz o tempo para solucionar a causa da falha, evitando a reconstrução completa da imagem. Use `RetryImage` depois de resolver a causa subjacente da falha de distribuição.
A RetryImage API aceita uma versão ARN de criação de imagem (por exemplo,`arn:aws:imagebuilder:us-west-2:123456789012:image/my-image/1.0.0/1`). Quando você invoca a API, o Image Builder retoma automaticamente o processo de distribuição a partir do ponto de falha usando a configuração e as configurações originais da distribuição. A `RetryImage` API pode tentar novamente distribuições que falharam durante a fase de distribuição, a fase de teste ou a fase de integração. Ele funciona AMIs nos seguintes estados: pendente, com falha, excluído ou disponível.
**Pré-requisitos**
Antes de tentar novamente uma distribuição, verifique o seguinte:
+ Você identificou e resolveu a causa raiz da falha. Revise os registros de distribuição no CloudWatch Logs para obter detalhes do erro.
+ Você tem as permissões do IAM necessárias para tentar criar novamente a imagem.
+ Para falhas de distribuição entre contas, verifique se a conta `EC2ImageBuilderDistributionCrossAccountRole` de destino tem a `Ec2ImageBuilderCrossAccountDistributionAccess` política anexada.
**Importante:** tentar novamente sem corrigir o problema subjacente resultará em falhas repetidas.
## Fluxos de trabalho de distribuição
Os fluxos de trabalho de distribuição são um novo tipo de fluxo de trabalho que complementa os fluxos de trabalho de criação e teste, permitindo que você defina e controle o processo de distribuição com etapas sequenciais. Com fluxos de trabalho de distribuição, você pode criar processos de distribuição personalizados que incluem operações de cópia da AMI, wait-for-action pontos de verificação, modificações de atributos de imagem e outras etapas relacionadas à distribuição. Isso fornece controle estruturado sobre como AMIs você é distribuído, com visibilidade em nível de etapas, recursos de distribuição paralela e relatórios granulares de erros.
Para saber mais sobre como criar e personalizar fluxos de trabalho, consulte [Gerenciar fluxos de trabalho de imagem](manage-image-workflows.html).