View a markdown version of this page

Criar e atualizar as configurações de distribuição da AMI - EC2 Image Builder
Pré-requisitos de distribuição de AMICrie uma configuração de distribuição de AMIAtualizar uma configuração de distribuição de AMIExemplo: habilitar o EC2 Fast Launch com um modelo de lançamento para AMIs de saídaExemplo: Crie configurações de distribuição para discos de VM de saída a partir do AWS CLI

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

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.

Pré-requisitos de distribuição de AMI

Algumas configurações de distribuição têm pré-requisitos, como segue:

Pré-requisitos para parâmetros de saída SSM

Antes de criar uma nova configuração de distribuição de AMI que defina um AWS Systems Manager parâmetro de armazenamento de parâmetros (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 de fluxo de trabalho do Image Builder, adicionaria qualquer permissão de recurso adicional a essa função. Caso contrário, você criaria uma nova função personalizada que inclui as permissões necessárias.

Importante

Recomendamos que você não passe a função AWSServiceRoleForImageBuilder vinculada ao serviço como sua função de execução. Em vez disso, crie uma função personalizada do IAM e anexe a política EC2ImageBuilderExecutionPolicy AWS gerenciada. Essa política concede as mesmas permissões que o Image Builder precisa para chamar Serviços da AWS em seu nome. O uso de uma função personalizada oferece controle total sobre as permissões que o Image Builder usa. Ele também mantém suas políticas de controle de serviços (SCPs) e políticas de controle de recursos (RCPs) em vigor nas operações que o Image Builder executa em seu nome.

  • Para armazenar a ID da AMI de saída em um parâmetro SSM durante a distribuição, você deve especificar a ssm:PutParameter ação em sua 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.

Opt-in Região

Você deve ativar uma região opcional (região que está desativada por padrão) na conta de origem. Esse requisito se aplica quando sua configuração de distribuição tem como alvo essa regiãossmParameterConfigurations, independentemente de você usar a função vinculada ao serviço Image Builder ou uma função de execução personalizada.

nota

A cópia da AMI para uma região opcional pode ser bem-sucedida mesmo quando a conta de origem não habilitou a região. Somente a gravação do parâmetro de saída SSM falha.

Sem esse pré-requisito, a compilação falha com um erro semelhante ao seguinte:

In region 'af-south-1' - 'STS Client Error: The provided execution role does not exist or does not have sufficient permissions.'

Para resolver esse problema, execute um dos seguintes procedimentos:

Pré-requisitos para o EC2 Fast Launch

Antes de criar uma nova configuração de distribuição para EC2 Fast Launch para AMIs do Windows, 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 lançamento ao configurar o EC2 Fast Launch.

  • Se você não usar um modelo de lançamento personalizado para definir suas configurações, deverá anexar a EC2FastLaunchFullAccess 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 de fluxo de trabalho do Image Builder, adicionaria qualquer permissão de recurso adicional a essa função. Caso contrário, você criaria uma nova função personalizada que inclui as permissões necessárias.

    Esse recurso exige permissões adicionais além das da política de execução básica, portanto, você deve usar uma função personalizada. Recomendamos que você crie uma função personalizada com a política EC2ImageBuilderExecutionPolicy AWS gerenciada anexada e, em seguida, adicione a EC2FastLaunchFullAccess política a essa função.

    Então, quando o Image Builder copia sua imagem, o EC2 Fast Launch cria automaticamente uma CloudFormation pilha com os seguintes recursos em seu. Conta da AWS

    • Uma nuvem privada virtual (VPC).

    • Sub-redes privadas em várias zonas de disponibilidade

    • Um modelo de inicialização 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.

Crie uma configuração de distribuição de AMI

As configurações de distribuição incluem o nome da AMI de saída, configurações específicas da região 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 outros Contas da AWS a iniciarem 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 AMIs de saída do Windows. 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 do EC2.

Console

Siga estas etapas para criar uma nova configuração de distribuição de AMI no Console de gerenciamento da AWS:

  1. Abra o console do EC2 Image Builder em https://console.aws.amazon.com/imagebuilder/.

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

  3. Escolha Criar configurações de distribuição na parte superior do painel Configurações de distribuição.

  4. Na seção Tipo de imagem, escolha imagem de máquina da Amazon (AMI) como o tipo de saída.

  5. Na seção Geral, insira um Nome para sua configuração de distribuição e uma descrição opcional.

  6. 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 Ec2ImageBuilderCrossAccountDistributionAccess política 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 de AMI, você pode conceder acesso a AWS diretores específicos para iniciar 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 Privado se quiser manter sua AMI privada e permitir o acesso de AWS diretores específicos para iniciar uma instância a partir de 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 — Conceder 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 secundárias incluem OUs e AWS contas.

          • Organização — Conceda acesso à sua AWS Organizations e a todas as suas entidades filhas. As entidades secundárias incluem OUs e 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 de diferentes tipos.

      2. Você pode expandir a seção Configuração da licença para anexar as configurações de licença criadas com AWS License Manager as 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.

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

      4. Você pode expandir a seção de configurações de parâmetros SSM para configurar um parâmetro SSM que armazenará a ID da AMI de saída para a 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.

    2. Para adicionar configurações de distribuição para outra região, escolha Adicionar região.

  7. 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 AWS Organizations ou quais unidades organizacionais (OUs) têm permissão para iniciar a AMI que você distribui para as regiões especificadas. 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: Distribuir para organizações 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: Armazene o ID da AMI de saída em um parâmetro SSM

    Este exemplo armazena a ID da AMI de saída em um AWS Systems Manager parâmetro de armazenamento de parâmetros 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"
				}
			]
		}
	]
}
  2. 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 (\) 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 na Referência de comandos da AWS CLI .

Atualizar uma configuração de distribuição de AMI

Você pode alterar sua configuração de distribuição de 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 de AMI no Console de gerenciamento da AWS:

  1. Abra o console do EC2 Image Builder em https://console.aws.amazon.com/imagebuilder/.

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

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

  4. 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 Crie uma configuração de distribuição de AMI.

  5. Quando concluir, escolha Salvar alterações.

AWS CLI

O exemplo a seguir mostra como usar o comando update-distribution-configuration 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"
					]
				}
			}
		}
	]
}
  2. 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 (\) 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 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.

Exemplo: habilitar o EC2 Fast Launch com um modelo de lançamento para AMIs de saída

O exemplo a seguir mostra como usar o create-distribution-configuration 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 lançamento, verifique se você atendeu a todos os requisitos Pré-requisitos do EC2 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.

  2. 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 (\) 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 na Referência de comandos da AWS CLI .

Exemplo: Crie configurações de distribuição para discos de VM de saída a partir 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 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.

    • disco ImageFormat (string, obrigatório) — Exporte a imagem de disco atualizada para um dos seguintes formatos compatíveis:

      • Disco rígido virtual (VHD) — compatível com os produtos de virtualização Citrix Xen e Microsoft. Hyper-V

      • Stream-optimized ESX Virtual Machine Disk (VMDK) — Compatível com as versões 4, 5 e 6 do VMware ESX 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"
}
  2. 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 (\) 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 na Referência de comandos da AWS CLI .