Usar o comando register-on-premises-instance (ARN de sessão do IAM) para registrar uma instância on-premises - AWS CodeDeploy
Pré-requisitos de registro do ARN de sessão do IAMEtapa 1: criar o perfil do IAM que as instâncias on-premises assumirãoEtapa 2: gerar credenciais temporárias para uma instância individual usando o AWS STSEtapa 3: adicionar um arquivo de configuração à instância on-premisesEtapa 4: preparar uma instância on-premises para implantações do CodeDeploy Etapa 5: registrar a instância on-premises no CodeDeployEtapa 6: marcar a instância on-premisesEtapa 7: implantar revisões de aplicações na instância on-premisesEtapa 8: acompanhar implantações na instância on-premises

Usar o comando register-on-premises-instance (ARN de sessão do IAM) para registrar uma instância on-premises

Para obter o controle máximo sobre a autenticação e o registro das suas instâncias on-premises, use o comando register-on-premises-instance e credenciais temporárias periodicamente atualizadas geradas com o AWS Security Token Service (AWS STS). Um perfil do IAM estático para a instância assume a função dessas credenciais atualizadas do AWS STS para executar operações de implantação do CodeDeploy.

Esse método é mais útil quando você precisa registrar um grande número de instâncias. Ele permite que você automatize o processo de registro no CodeDeploy. Você pode usar seu próprio sistema de identidade e autenticação para autenticar instâncias on-premises e distribuir credenciais de sessão do IAM do serviço para as instâncias, para uso com o CodeDeploy.

nota

Como alternativa, você pode usar um usuário do IAM compartilhado, distribuído em todas as instâncias locais, para chamar a API AWS STSAssumeRole do de modo a recuperar credenciais de sessão para instâncias locais. Esse método é menos seguro e não é recomendado para ambientes de produção ou críticos.

Use as informações nos tópicos a seguir para configurar uma instância local usando credenciais de segurança temporárias geradas com o AWS STS.

Pré-requisitos de registro do ARN de sessão do IAM

Além dos pré-requisitos listados em Pré-requisitos para configurar uma instância on-premises, os seguintes requisitos adicionais devem ser atendidos:

permissões do IAM

A identidade do IAM que você usa para registrar uma instância on-premises deve receber permissões para realizar operações do CodeDeploy. Verifique se a política gerenciada AWSCodeDeployFullAccess está anexada à identidade do IAM. Para obter mais informações, consulte Políticas gerenciadas pela AWS no Manual do usuário do IAM.

Sistema para atualizar credenciais temporárias

Se você usar um ARN de sessão do IAM para registrar instâncias locais, deverá ter um sistema em vigor para atualizar periodicamente as credenciais temporárias. As credenciais temporárias expiram depois de uma hora ou antes quando um período mais curto é especificado no momento em que as credenciais são geradas. Existem dois métodos para atualizar as credenciais:

  • Método 1: use o sistema de identidade e autenticação instalado na sua rede corporativa com um script CRON que faça uma sondagem periódica do sistema de identidade e autenticação e que copie as credenciais da última sessão para a instância. Isso permite que você integre sua estrutura de identidade e autenticação à AWS sem precisar fazer alterações no agente do CodeDeploy ou no serviço para dar suporte aos tipos de autenticação utilizados na sua organização.

  • Método 2: execute periodicamente um trabalho CRON na instância para chamar o ação AssumeRole do AWS STS e grave as credenciais da sessão em um arquivo que o agente do CodeDeploy possa acessar. Esse método ainda requer um usuário do IAM e a cópia de credenciais na instância local, mas você pode reutilizar o mesmo usuário do IAM e as mesmas credenciais por toda a sua frota de instâncias locais.

nota

Independentemente de você estar usando o método 1 ou 2, você deve configurar um processo para reiniciar o agente do CodeDeploy depois que as credenciais da sessão temporária forem atualizadas para que as novas credenciais entrem em vigor.

Para obter informações sobre como criar e trabalhar com credenciais do AWS STS, consulte Referência da API do AWS Security Token Service e Uso de credenciais de segurança temporárias para solicitar acesso a recursos da AWS.

Etapa 1: criar o perfil do IAM que as instâncias on-premises assumirão

É possível usar a AWS CLI ou o console do IAM para criar um perfil do IAM que será usado pelas suas instâncias on-premises para autenticação e interação no CodeDeploy.

Você só precisa criar uma função do IAM. Cada uma das suas instâncias locais pode assumir essa função para recuperar as credenciais de segurança temporárias que fornecem as permissões concedidas a essa função.

A função que você criar exigirá as seguintes permissões para acessar os arquivos necessários para instalar o agente do CodeDeploy:

JSON
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Action": [
                "s3:Get*",
                "s3:List*"
            ],
            "Effect": "Allow",
            "Resource": "*"
        }
    ]
}

Recomendamos que você restrinja essa política somente para os buckets do Amazon S3 que a sua instância on-premises precisa acessar. Se você restringir essa política, lembre-se de fornecer acesso aos buckets do Amazon S3 que contêm o agente do CodeDeploy. Caso contrário, um erro poderá ocorrer sempre que o agente do CodeDeploy for instalado ou atualizado na instância on-premises. Para obter mais informações sobre como controlar o acesso aos buckets do Amazon S3, consulte Gerenciar permissões de acesso aos recursos do Amazon S3.

Para criar perfil do IAM

  1. Chame o comando create-role usando a opção --role-name para especificar um nome para a função do IAM (por exemplo, CodeDeployInstanceRole) e a opção --assume-role-policy-document para fornecer as permissões.

    Ao criar a função do IAM para essa instância, você pode dar a ela o nome CodeDeployInstanceRole e incluir as permissões necessárias em um arquivo chamado CodeDeployRolePolicy.json:

    aws iam create-role --role-name CodeDeployInstanceRole --assume-role-policy-document file://CodeDeployRolePolicy.json

  2. Na saída da chamada para o comando create-role, anote o valor do campo ARN. Por exemplo:

    arn:aws:iam::123456789012:role/CodeDeployInstanceRole

    Você precisará do ARN da função quando usar a API AWS STSAssumeRole do para gerar credenciais de curto prazo para cada instância.

    Para obter mais informações sobre como criar um perfil do IAM, consulte Criação de uma função para delegar permissões a um serviço da AWS no Guia do usuário do IAM.

    Para obter informações sobre como atribuir permissões a uma função existente, consulte put-role-policy na Referência de comandos da AWS CLI.

Etapa 2: gerar credenciais temporárias para uma instância individual usando o AWS STS

Antes de gerar as credenciais temporárias que serão usadas para registrar uma instância local, você deve criar ou escolher a identidade do IAM (usuário ou função) para a qual você gerará essas credenciais temporárias. A permissão sts:AssumeRole deve ser incluída nas configurações de política para essa identidade do IAM.

Para obter informações sobre como conceder permissões sts:AssumeRole a uma identidade do IAM, consulte Criar uma função para delegar permissões a um serviço do AWS e AssumeRole.

Existem duas maneiras de gerar as credenciais temporárias:

  • Use o comando assume-role com o AWS CLI. Por exemplo:

    aws sts assume-role --role-arn arn:aws:iam::12345ACCOUNT:role/role-arn --role-session-name session-name

    Em que:

    nota

    Se você usar um script CRON que faz sondagens periódicas no sistema de identidade e autenticação e copia as credenciais da sessão mais recente para a instância (método 1 de atualização de credenciais temporárias, descrito em Pré-requisitos de registro do ARN de sessão do IAM), existe a opção de usar qualquer SDK da AWS com suporte para chamar AssumeRole.

  • Use uma ferramenta fornecida pela AWS.

    A ferramenta aws-codedeploy-session-helper gera credenciais do AWS STS e as grava em um arquivo que você coloca na instância. Essa ferramenta é mais adequada para o método 2 de atualização de credenciais temporárias, descrito em Pré-requisitos de registro do ARN de sessão do IAM. Nesse método, a ferramenta aws-codedeploy-session-helper é colocada em cada instância e executa o comando usando as permissões de um usuário do IAM. Cada instância usa as mesmas credenciais do usuário do IAM em conjunto com essa ferramenta.

    Para obter mais informações, consulte o repositório GitHub de aws-codedeploy-session-helper.

    nota

    Depois de ter criado as credenciais de sessão do IAM, coloque-as em qualquer parte da instância local. Na próxima etapa, você configurará o agente do CodeDeploy para acessar as credenciais nesse local.

Antes de continuar, verifique se o sistema que você usará para atualizar periodicamente as credenciais temporárias está em vigor. Se as credenciais temporárias não forem atualizadas, as implantações na instância local falharão. Para obter mais informações, consulte "Sistema para atualizar credenciais temporárias", em Pré-requisitos de registro do ARN de sessão do IAM.

Etapa 3: adicionar um arquivo de configuração à instância on-premises

Adicione um arquivo de configuração à instância on-premises usando permissões raiz ou de administrador. Esse arquivo de configuração é usado para declarar as credenciais do IAM e a região da AWS de destino a ser usada para o CodeDeploy. O arquivo deve ser adicionado a um local específico na instância on-premises. Ele deve incluir o ARN da sessão temporária do IAM, seu ID de chave secreta e a chave de acesso secreta, bem como a região da AWS de destino.

Para adicionar um arquivo de configuração

  1. Crie um arquivo chamado codedeploy.onpremises.yml (para uma instância on-premises do Ubuntu Server ou do RHEL) ou conf.onpremises.yml (para uma instância on-premises do Windows Server) na seguinte localização da instância on-premises:

    • Para Ubuntu Server: /etc/codedeploy-agent/conf

    • Para Windows Server: C:\ProgramData\Amazon\CodeDeploy

  2. Use um editor de texto para adicionar as seguintes informações ao arquivo codedeploy.onpremises.yml (Linux) ou conf.onpremises.yml (Windows) recém-criado: 

    ---
iam_session_arn: iam-session-arn
aws_credentials_file: credentials-file
region: supported-region

    Em que:

Etapa 4: preparar uma instância on-premises para implantações do CodeDeploy

Instalar e configurar a AWS CLI

Instale e configure a AWS CLI na instância on-premises. (A AWS CLI será usada para baixar e instalar o agente do CodeDeploy na instância on-premises.)

  1. Para instalar a AWS CLI na instância on-premises, siga as instruções em Configuração com a AWS CLI no Guia do usuário do AWS Command Line Interface.

    nota

    Os comandos do CodeDeploy para trabalhar com instâncias on-premises tornaram-se disponíveis na versão 1.7.19 da AWS CLI. Se tiver uma versão da AWS CLI já instalada, verifique a versão chamando aws --version.

  2. Para configurar a AWS CLI na instância on-premises, siga as instruções em Configurando o AWS CLI no Guia do usuário do AWS Command Line Interface.

    Importante

    À medida que você configura a AWS CLI (por exemplo, chamando o comando aws configure), lembre-se de especificar o ID de chave secreta e a chave de acesso secreta de um usuário do IAM que tenha pelo menos acesso às permissões descritas em Pré-requisitos de registro do ARN de sessão do IAM.

Definir a variável de ambiente AWS_REGION (somente para o Ubuntu Server e o RHEL)

Se não estiver executando o Ubuntu Server ou o RHEL na sua instância on-premises, ignore esta etapa e vá diretamente para "Instalar o agente do CodeDeploy".

Instale o agente do CodeDeploy em uma instância on-premises do Ubuntu Server ou RHEL e permita que a instância atualize o agente do CodeDeploy sempre que uma nova versão estiver disponível. Isso é feito configurando a variável de ambiente AWS_REGION na instância como o identificador de uma das regiões com suporte pelo CodeDeploy. Recomendamos definir o valor como a região na qual seus aplicativos, grupos de implantação e revisões de aplicativo do CodeDeploy estão localizados (por exemplo, us-west-2). Para obter uma lista de regiões, consulte Região e endpoints, na Referência geral da AWS.

Para definir a variável de ambiente, chame o seguinte usando o terminal:

export AWS_REGION=supported-region

Em que supported-region é o identificador da região (por exemplo, us-west-2).

Instalar o agente do CodeDeploy

Etapa 5: registrar a instância on-premises no CodeDeploy

As instruções nesta etapa supõem que você esteja registrando a instância on-premises a partir dela mesma. Você pode registrar uma instância local a partir de um dispositivo ou instância à parte que tenha a AWS CLI instalada e configurada.

Use a AWS CLI para registrar a instância on-premises no CodeDeploy, para que ela possa ser usada nas implantações.

Antes de poder usar a AWS CLI, será necessário o ARN das credenciais de sessão temporária criadas em Etapa 3: adicionar um arquivo de configuração à instância on-premises. Por exemplo, para uma instância identificada como AssetTag12010298EX:

arn:sts:iam::123456789012:assumed-role/CodeDeployInstanceRole/AssetTag12010298EX

Chame o comando register-on-premises-instance, especificando o seguinte:

  • Um nome que identifique de forma exclusiva a instância on premises (com a opção --instance-name).

    Importante

    Para ajudar a identificar a instância local, especialmente para fins de depuração, recomendamos que você especifique um nome que seja mapeado para alguma característica exclusiva da instância local (por exemplo, o nome da sessão das credenciais do STS e o número de série ou um identificador interno de ativo, se aplicável). Se você especificar um endereço MAC como um nome, lembre-se de que endereços MAC contêm caracteres não permitidos pelo CodeDeploy, como o caractere de dois pontos (:). Para obter uma lista de caracteres permitidos, consulte Cotas do CodeDeploy.

  • O ARN da sessão do IAM que você configurou para autenticar várias instâncias locais em Etapa 1: criar o perfil do IAM que as instâncias on-premises assumirão.

Por exemplo:

aws deploy register-on-premises-instance --instance-name name-of-instance --iam-session-arn arn:aws:sts::account-id:assumed-role/role-to-assume/session-name

Em que:

  • name-of-instance é o nome usado para identificar a instância local, como AssetTag12010298EX.

  • account-id é o ID da conta de 12 dígitos da sua organização, como 111222333444.

  • role-to-assume é o nome da função do IAM que você criou para a instância, como CodeDeployInstanceRole.

  • session-name é o nome da função de sessão que você especificou em Etapa 2: gerar credenciais temporárias para uma instância individual usando o AWS STS.

Etapa 6: marcar a instância on-premises

Você pode usar a AWS CLI ou o console do CodeDeploy para marcar a instância on-premises. (O CodeDeploy usa tags de instância on-premises para identificar os destinos de implantação durante uma implantação.)

Para marcar a instância on-premises (CLI)

  • Chame o comando add-tags-to-on-premises-instances, especificando o seguinte:

    • O nome que identifica de forma exclusiva a instância on-premises (com a opção --instance-names).

    • O nome da chave da tag de instância on-premises e o valor da tag que você deseja usar (com a opção --tags). Você deve especificar um nome e um valor. O CodeDeploy não permite tags de instâncias on-premises que possuam apenas valores.

      Por exemplo:

      aws deploy add-tags-to-on-premises-instances --instance-names AssetTag12010298EX --tags Key=Name,Value=CodeDeployDemo-OnPrem
Para marcar a instância on-premises (console)

  1. Faça login no Console de gerenciamento da AWS e abra o console do CodeDeploy em https://console.aws.amazon.com/codedeploy.

    nota

    Faça login com o mesmo usuário que você configurou em Conceitos básicos do CodeDeploy.

  2. No painel de navegação, expanda Implantar e escolha Instâncias on-premises.

  3. Na lista de instâncias locais, selecione nome da instância local que deseja marcar.

  4. Na lista de tags, selecione ou insira a chave e o valor da tag desejados. Após inserir a chave e o valor da tag, outra linha será exibida. Isso pode ser repetido para até 10 tags. Para remover uma tag, selecione Remover.

  5. Depois de adicionar as tags, escolha Atualizar tags.

Etapa 7: implantar revisões de aplicações na instância on-premises

Agora, você está pronto para implantar revisões de aplicativo na instância on-premises registrada e marcada.

Você implementa revisões de aplicativos em instâncias on-premises de uma maneira semelhante à implantação de revisões de aplicativos em instâncias do Amazon EC2. Para instruções, consulte Crie uma implantação com o CodeDeploy. Essas instruções incluem um link para pré-requisitos, que incluem: criar um aplicativo, criar um grupo de implantação e preparar uma revisão de aplicativo. Se você precisa de uma simples revisão de aplicativo de amostra para implantar, poderá criar aquela descrito em Etapa 2: criar uma revisão de aplicativo de amostra, no Tutorial: implantar um aplicativo em uma instância on-premises com o CodeDeploy (Windows Server, Ubuntu Server ou Red Hat Enterprise Linux).

Importante

Se você reutilizar um perfil de serviço do CodeDeploy como parte da criação de um grupo de implantação direcionado a instâncias on-premises, deverá incluir Tag:get* na parte Action da declaração de política do perfil de serviço. Para obter mais informações, consulte Etapa 2: Criar um perfil de serviço para CodeDeploy.

Etapa 8: acompanhar implantações na instância on-premises

Depois de implantar uma revisão de aplicativo em instâncias on-premises registradas e marcadas, você poderá controlar o progresso da implantação.

Você controla as implantações em instâncias on-premises de uma maneira semelhante ao controle de implantações em instâncias do Amazon EC2. Para instruções, consulte Veja os detalhes da implantação do CodeDeploy .