Configure um pipeline de CI/CD para workloads híbridas no Amazon ECS Anywhere usando o AWS CDK e o GitLab - Recomendações da AWS
ResumoPré-requisitos e limitaçõesArquiteturaFerramentasPráticas recomendadasÉpicosSolução de problemasRecursos relacionados

Configure um pipeline de CI/CD para workloads híbridas no Amazon ECS Anywhere usando o AWS CDK e o GitLab

Dr. Rahul Sharad Gaikwad, Amazon Web Services

Resumo

Aviso: O AWS CodeCommit não está mais disponível para novos clientes. Os clientes atuais do AWS CodeCommit podem continuar usando o serviço normalmente. Saiba mais.

O Amazon ECS Anywhere é uma extensão do Amazon Elastic Container Service (Amazon ECS). Ele fornece suporte para registrar uma instância externa, como um servidor on-premises ou uma máquina virtual (VM), no cluster do Amazon ECS. Esse atributo ajuda a reduzir custos e mitigar operações e orquestrações de contêineres on-premises. Você pode usar o ECS Anywhere para implantar e executar aplicativos de contêiner em ambientes on-premises e na nuvem. Isso elimina a necessidade de sua equipe aprender vários domínios e conjuntos de habilidades ou gerenciar softwares complexos por conta própria.

Esse padrão descreve uma abordagem passo a passo para provisionar um cluster do Amazon ECS com instâncias do Amazon ECS Anywhere usando pilhas do AWS Cloud Development Kit (AWS CDK) da Amazon Web Services. Em seguida, você usa o AWS CodePipeline para configurar um pipeline de integração e implantação contínuas (CI/CD). Em seguida, você replica seu repositório de código do GitLab para o AWS CodeCommit e implanta seu aplicativo em contêineres no cluster Amazon ECS.

Esse padrão foi projetado para ajudar aqueles que usam a infraestrutura on-premises para executar aplicativos de contêiner e usam o GitLab para gerenciar a base de código do aplicativo. Você pode gerenciar essas workloads usando os serviços de Nuvem AWS, sem perturbar sua infraestrutura on-premises existente.

Pré-requisitos e limitações

Pré-requisitos

  • Uma conta AWS ativa

  • Um aplicativo de contêiner executado na infraestrutura on-premises.

  • Um repositório do GitLab onde você gerencia a base de código do seu aplicativo. Para obter mais informações, consulte Repositório (GitLab).

  • AWS Command Line Interface (AWS CLI), instalada e configurada. Para obter mais informações, consulte Instalar ou atualizar a versão mais recente da AWS CLI (Documentação da AWS CLI).

  • AWS CDK Toolkit, instalado e configurado globalmente. Para obter mais informações, consulte Instalar o AWS CDK na documentação do AWS CDK Workshop.

  • npm, instalado e configurado para o AWS CDK em TypeScript. Para obter mais informações, consulte Como baixar e instalar o Node.js e o npm (documentação do npm).

Limitações

Versões do produto

  • AWS CDK Toolkit versão 2.27.0 ou superior

  • npm versão 7.20.3 ou superior

  • Node.js versão 16.6.1 ou superior

Arquitetura

Pilha de tecnologias de destino

  • AWS CDK

  • AWS CloudFormation

  • AWS CodeBuild

  • AWS CodeCommit

  • AWS CodePipeline

  • Amazon ECS Anywhere

  • Amazon Elastic Container Registry (Amazon ECR)

  • AWS Identity and Access Management (IAM)

  • AWS Systems Manager

  • Repositório GitLab

Arquitetura de destino

Diagrama de arquitetura da configuração do cluster Amazon ECS e do pipeline de CI/CD.

Esse diagrama representa dois fluxos de trabalho principais descritos nesse padrão, provisionando o cluster do Amazon ECS e configurando o pipeline de CI/CD que configura e implanta o pipeline de CI/CD, da seguinte forma:

  1. Provisionar o cluster do Amazon ECS

    1. Quando você implanta a primeira pilha de CDK da AWS, ela cria uma pilha do CloudFormation na AWS.

    2. Essa pilha do CloudFormation provisiona um cluster do Amazon ECS e recursos relacionados da AWS.

    3. Para registrar uma instância externa com um cluster do Amazon ECS, você deve instalar o AWS Systems Manager Agent (SSM Agent) na sua VM e registrar a VM como uma instância gerenciada do AWS Systems Manager. 

    4. Você deve instalar o agente de contêiner do Amazon ECS e o Docker na sua VM para registrá-la como instância externa com o cluster do Amazon ECS.

    5. Quando a instância externa é registrada e configurada com o cluster Amazon ECS, ela pode executar vários contêineres na sua VM, que é registrada como uma instância externa.

    6. O cluster do Amazon ECS está ativo e pode executar as cargas de trabalho do aplicativo por meio de contêineres. A instância de contêiner Amazon ECS Anywhere é executada em um ambiente on-premises, mas está associada ao cluster do Amazon ECS na nuvem.

  2. Configurando e implantando o pipeline de CI/CD

    1. Quando você implanta a segunda pilha de CDK da AWS, ela cria outra pilha do CloudFormation na AWS.

    2. Essa pilha do CloudFormation provisiona um pipeline no CodePipeline e nos recursos relacionados da AWS.

    3. Você envia e mescla as alterações do código do aplicativo em um repositório GitLab on-premises. 

    4. O repositório do GitLab é automaticamente replicado para o repositório do CodeCommit.

    5. As atualizações no repositório do CodeCommit iniciam automaticamente o CodePipeline. 

    6. O CodePipeline copia o código do CodeCommit e cria o aplicativo implantável construído no CodeBuild.

    7. O CodePipeline cria uma imagem do Docker do ambiente de compilação do CodeBuild e a envia para o repositório Amazon ECR.

    8. O CodePipeline inicia ações do CodeDeploy que extraem a imagem do contêiner do repositório Amazon ECR.

    9. O CodePipeline implanta a imagem do contêiner no cluster Amazon ECS.

Automação e escala

Esse padrão usa o AWS CDK como uma ferramenta de infraestrutura como código (IaC) para configurar e implantar essa arquitetura. O AWS CDK ajuda você a orquestrar os recursos da AWS e configurar o Amazon ECS Anywhere e o pipeline de CI/CD.

Ferramentas

Serviços da AWS

  • O AWS Cloud Development Kit (AWS CDK) é uma estrutura de desenvolvimento de software que ajuda você a definir e provisionar a infraestrutura da Nuvem AWS em código.

  • O AWS CodeCommit é um serviço de versionamento que ajuda você a armazenar e gerenciar repositórios Git de forma privada, sem precisar gerenciar seu próprio sistema de controle de origem.

  • O AWS CodePipeline ajuda você a modelar e configurar rapidamente os diferentes estágios de um lançamento de software e automatiza as etapas necessárias para lançar as alterações feitas continuamente no software.

  • A ‭AWS Command Line Interface (AWS CLI)‭ é uma ferramenta de código aberto que permite que você interaja com serviços da AWS usando comandos no shell da linha de comando.

  • O Amazon Elastic Container Registry (Amazon ECR) é um serviço gerenciado de registro de imagens de contêineres seguro, escalável e confiável.

  • O Amazon Elastic Container Service (Amazon ECS) é um serviço de gerenciamento de contêineres escalável e rápido que facilita a execução, a interrupção e o gerenciamento de contêineres em um cluster. Esse padrão também usa o Amazon ECS Anywhere, que fornece suporte para registrar um servidor on-premises ou uma VM no cluster do Amazon ECS.

Outras ferramentas

  • O Node.js é um ambiente de runtime de JavaScript orientado por eventos projetado para criar aplicativos de rede escaláveis.

  • O npm é um registro de software executado em um ambiente Node.js e usado para compartilhar ou emprestar pacotes e gerenciar a implantação de pacotes privados.

  • O Vagrant é um utilitário de código aberto para criar e manter ambientes portáteis de desenvolvimento de software virtual. Para fins de demonstração, esse padrão usa o Vagrant para criar uma VM on-premises.

Repositório de código

O código desse padrão está disponível no pipeline de CI/CD do GitHub para o Amazon ECS Anywhere usando o repositório AWS CDK.

Práticas recomendadas

Considere as seguintes práticas recomendadas ao implantar esse padrão:

Épicos

TarefaDescriçãoHabilidades necessárias

Verifique a versão do AWS CDK.

Verifique a versão do AWS CDK Toolkit inserindo o comando a seguir.

cdk --version

Este padrão requer a versão 2.27.0 ou superior. Se você tiver uma versão anterior, siga as instruções na documentação do AWS CDK para atualizá-la.

Engenheiro de DevOps

Verificar a versão do npm.

Verifique a versão do npm inserindo o comando a seguir.

npm --version

Este padrão requer a versão 7.20.3 ou superior. Se você tiver uma versão anterior, siga as instruções na documentação do npm para atualizá-la.

Engenheiro de DevOps

Configurar credenciais da AWS.

Configure as credenciais da AWS inserindo o comando aws configure e seguindo as instruções.

$aws configure
AWS Access Key ID [None]: <your-access-key-ID>
AWS Secret Access Key [None]: <your-secret-access-key>
Default region name [None]: <your-Region-name>
Default output format [None]:
Engenheiro de DevOps
TarefaDescriçãoHabilidades necessárias

Clone o repositório de códigos do AWS CDK.

  1. Clone o pipeline de CI/CD para o Amazon ECS Anywhere usando o repositório AWS CDK para esse padrão digitando o seguinte comando.

    git clone https://github.com/aws-samples/amazon-ecs-anywhere-cicd-pipeline-cdk-sample.git

  2. Navegue até o diretório clonado inserindo o comando a seguir.

    cd amazon-ecs-anywhere-cicd-pipeline-cdk-sample
Engenheiro de DevOps

Faça o bootstrap do ambiente.

Implemente o modelo do CloudFormation na conta e na região da AWS que você deseja usar inserindo o seguinte comando.

cdk bootstrap <account-number>/<Region>

Para obter mais informações, consulte Inicialização na documentação do AWS CDK.

Engenheiro de DevOps
TarefaDescriçãoHabilidades necessárias

Instale as dependências do pacote e compile os arquivos TypeScript.

Instale as dependências do pacote e compile os arquivos TypeScript digitando os seguintes comandos.

$cd EcsAnywhereCdk
$npm install
$npm fund

Esses comandos instalam todos os pacotes do repositório de exemplo. Para obter mais informações, consulte npm ci e npm install na documentação do npm. Se você receber algum erro sobre pacotes ausentes ao inserir esses comandos, consulte a seção Solução de problemas desse padrão.

Engenheiro de DevOps

Crie o projeto.

Para compilar o código do projeto, digite o comando a seguir.

npm run build

Para obter mais informações sobre como criar e implantar o projeto, consulte Seu primeiro aplicativo da AWS CDK na documentação da AWS CDK.

Engenheiro de DevOps

Implante a pilha de infraestrutura do Amazon ECS Anywhere.

  1. Liste as pilhas inserindo os comandos abaixo.

    $cdk list

  2. Confirme se a saída retorna as pilhas EcsAnywhereInfraStack e ECSAnywherePipelineStack.

  3. Implemente a pilha do EcsAnywhereInfraStack inserindo os comandos abaixo.

    $cdk  deploy EcsAnywhereInfraStack
Engenheiro de DevOps

Verifique a criação e a saída da pilha.

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

  2. Na página Stacks, selecione a pilha EcsAnywhereInfraStack.

  3. Confirme se o status da pilha é CREATE_IN_PROGRESS ou CREATE_COMPLETE.

    A configuração do cluster do Amazon ECS pode levar algum tempo. Não prossiga até que a criação da pilha esteja concluída.

Engenheiro de DevOps
TarefaDescriçãoHabilidades necessárias

Configurar a VM.

Crie uma VM Vagrant inserindo o comando vagrant up do diretório raiz onde o Vagrantfile está localizado. Para obter mais informações, consulte a documentação do Vagrant.

Engenheiro de DevOps

Registre sua VM como uma instância externa.

  1. Faça login na VM Vagrant usando o comando vagrant ssh. Para obter mais informações, consulte a documentação do Vagrant.

  2. Instale a AWS CLI na VM seguindo as instruções de instalação da AWS CLI e inserindo os seguintes comandos. 

    $ curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" \
> -o "awscliv2.zip"
$sudo apt install unzip
$unzip awscliv2.zip
$sudo ./aws/install
$aws configure
AWS Access Key ID [None]: <your-access-key-ID>
AWS Secret Access Key [None]: <your-secret-access-key>
Default region name [None]: <your-Region-name>
Default output format [None]:

  1. Crie um código de ativação e um ID que você possa usar para registrar sua VM no AWS Systems Manager e ativar sua instância externa. A saída desse comando inclui os valores do ID de ativação e do código de ativação.

    aws ssm create-activation \
> --iam-role EcsAnywhereInstanceRole \
> | tee ssm-activation.json

    Se você receber um erro ao executar esse comando, consulte a seção Solução de problemas.

  2. Exporte o ID de ativação e os valores do código.

    export ACTIVATION_ID=<activation-ID>
export ACTIVATION_CODE=<activation-code>

  3. Baixe o script de instalação na VM.

    curl --proto "https" -o "ecs-anywhere-install.sh" \
> "https://amazon-ecs-agent.s3.amazonaws.com/ecs-anywhere-install-latest.sh"

  4. Execute o script de instalação na sua VM.

    sudo bash ecs-anywhere-install.sh \
--cluster EcsAnywhereCluster \
--activation-id $ACTIVATION_ID \
--activation-code $ACTIVATION_CODE \
--region <region-name>

Isso configura sua VM como uma instância externa do Amazon ECS Anywhere e registra a instância no cluster do Amazon ECS. Para obter mais informações, consulte Registro de uma instância externa em um cluster na documentação do Amazon ECS. Se você tiver algum problema, consulte a seção Solução de problemas.

Engenheiro de DevOps

Verifique o status do Amazon ECS Anywhere e da VM externa.

Para verificar se sua VM está conectada ao ambiente de gerenciamento do Amazon ECS e em execução, use os seguintes comandos.

$aws ssm describe-instance-information
$aws ecs list-container-instances --cluster $CLUSTER_NAME
Engenheiro de DevOps
TarefaDescriçãoHabilidades necessárias

Criar uma ramificação em um repositório do CodeCommit.

Crie uma ramificação nomeada main no repositório CodeCommit criando o primeiro commit para o repositório. Você pode seguir a documentação da AWS para criar um commit no CodeCommit. O comando a seguir é um exemplo.

aws codecommit put-file \
  --repository-name EcsAnywhereRepo \
  --branch-name main \
  --file-path README.md \
  --file-content "Test" \
  --name "Dev Ops" \
  --email "devops@example.com" \
  --commit-message "Adding README."
Engenheiro de DevOps

Configure o espelhamento do repositório.

Você pode espelhar um repositório do GitLab de e para fontes externas. Você pode selecionar qual repositório serve como fonte. Ramificações, tags e commits são sincronizados automaticamente. Configure um espelho de push entre o repositório GitLab que hospeda seu aplicativo e o repositório do CodeCommit. Para obter instruções, consulte Configurar um espelho de push do GitLab para o CodeCommit (documentação do GitLab).

nota

Por padrão, o espelhamento sincroniza automaticamente o repositório. Se você quiser atualizar manualmente os repositórios, consulte Atualizar um espelho (documentação do GitLab).

Engenheiro de DevOps

Implante a pilha de pipeline de CI/CD.

Implemente a pilha do EcsAnywherePipelineStack inserindo os comandos abaixo.

$cdk  deploy EcsAnywherePipelineStack
Engenheiro de DevOps

Testar o pipeline de CI/CD.

  1. Faça alterações no código do aplicativo e envie-o para o repositório GitLab on-premises de origem. Para obter mais informações, consulte Opções push (documentação do GitLab). Por exemplo, edite o arquivo ../application/index.html para atualizar o valor da versão do aplicativo.

  2. Quando o código é replicado para o repositório CodeCommit, isso inicia o pipeline de CI/CD. Execute um destes procedimentos:

    • Se você estiver usando o espelhamento automático para sincronizar o repositório GitLab com o repositório CodeCommit, continue na próxima etapa.

    • Se você estiver usando o espelhamento manual, envie as alterações do código do aplicativo para o repositório do CodeCommit seguindo as instruções em Atualizar um espelho (documentação do GitLab).

  3. Em sua máquina local, em um navegador da Web, digite http://localhost:80. Isso abre a página da web do NGINX porque a porta 80 é encaminhada para o localhost no Vagrantfile. Confirme se você pode visualizar o valor da versão atualizada do aplicativo. Isso valida a implantação do pipeline e da imagem.

  4. (Opcional) Se você deseja verificar a implantação no Console de Gerenciamento da AWS, faça o seguinte:

    1. Abra o console do Amazon ECS em https://console.aws.amazon.com/ecs/.

    2. Na barra de navegação, selecione a Região a ser usada.

    3. No painel de navegação, escolha Clusters.

    4. Na página Clusters, selecione o cluster EcsAnywhereCluster.

    5. Escolha Definições de tarefas.

    6. Confirme se o contêiner está funcionando.

Engenheiro de DevOps
TarefaDescriçãoHabilidades necessárias

Limpe e exclua os recursos.

Depois de analisar esse padrão, você deve remover os recursos de prova de conceito que você criou. Para limpar, insira os comandos a seguir.

$cdk destroy EcsAnywherePipelineStack
$cdk destroy EcsAnywhereInfraStack
Engenheiro de DevOps

Solução de problemas

ProblemaSolução

Erros sobre pacotes ausentes ao instalar dependências de pacotes.

Insira um dos comandos a seguir para resolver pacotes ausentes.

$npm ci

ou

$npm install -g @aws-cdk/<package_name>

Ao executar o comando aws ssm create-activation na VM, você receberá o seguinte erro.

An error occurred (ValidationException) when calling the CreateActivation operation: Nonexistent role or missing ssm service principal in trust policy: arn:aws:iam::000000000000:role/EcsAnywhereInstanceRole

A pilha do EcsAnywhereInfraStack não está totalmente implantada e o perfil do IAM necessário para executar esse comando ainda não foi criado. Verifique o status da pilha no console do CloudFormation. Use o comando novamente depois que o status muar para CREATE_COMPLETE.

Uma verificação de integridade do Amazon ECS retorna UNHEALTHY e você vê o seguinte erro na seção Serviços do cluster no console do Amazon ECS.

service EcsAnywhereService was unable to place a task because no container instance met all of its requirements. Reason: No Container Instances were found in your cluster.

Reinicie o agente do Amazon ECS na VM do Vagrant inserindo os comandos a seguir.

$vagrant ssh
$sudo systemctl restart ecs
$sudo systemctl status ecs

Recursos relacionados