Depurar compilações com o Session Manager - AWS CodeBuild
Pré-requisitosPausar a compilaçãoIniciar a compilaçãoConectar-se ao contêiner de compilaçãoRetomar a compilação

Depurar compilações com o Session Manager

No AWS CodeBuild, é possível pausar uma compilação em execução e, depois, usar o Gerenciador de Sessões do AWS Systems Manager para se conectar ao contêiner de compilação e visualizar o estado do contêiner.

nota

Esse atributo não está disponível em ambientes Windows.

Pré-requisitos

Para permitir que o Gerenciador de Sessões seja usado com a sessão de compilação, é necessário habilitar a conexão de sessão para a compilação. Há dois pré-requisitos:

  • As imagens selecionadas padrão do CodeBuild Linux já têm o agente do SSM instalado e o SSM Agent ContainerMode habilitado.

    Se você estiver usando uma imagem personalizada para a compilação, faça o seguinte:

    1. Instalar o SSM Agent do . Para obter mais informações, consulte Manually install SSM Agent on EC2 instances for Linux no Guia do usuário do AWS Systems Manager. A versão do SSM Agent deve ser 3.0.1295.0 ou posterior.

    2. Copie o arquivo https://github.com/aws/aws-codebuild-docker-images/blob/master/ubuntu/standard/5.0/amazon-ssm-agent.json para o diretório /etc/amazon/ssm/ na imagem. Isso habilita o Modo de contêiner no SSM Agent.

    nota

    Imagens personalizadas exigiriam o SSM Agent mais atualizado para que esse atributo funcionasse conforme o esperado.

  • O perfil de serviço do CodeBuild deve ter a seguinte política do SSM:

    JSON
    {
   "Version":"2012-10-17",		 	 	  
   "Statement": [
     {
       "Effect": "Allow",
       "Action": [
          "ssmmessages:CreateControlChannel",
          "ssmmessages:CreateDataChannel",
          "ssmmessages:OpenControlChannel",
          "ssmmessages:OpenDataChannel"
       ],
       "Resource": "*"
     }
   ]
}

    É possível fazer com que o console do CodeBuild anexe automaticamente essa política ao perfil de serviço ao iniciar a compilação. Se preferir, você poderá anexar essa política ao perfil de serviço manualmente.

  • Se você tiver a Auditing and logging session activity habilitada nas preferências do Systems Manager, o perfil de serviço do CodeBuild também deverá ter permissões adicionais. As permissões são diferentes, dependendo do local onde os logs são armazenados.

    CloudWatch Logs

    Se estiver usando o CloudWatch Logs para armazenar os logs, adicione a seguinte permissão ao perfil de serviço do CodeBuild:

    JSON
    {
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "logs:DescribeLogGroups",
            "Resource": "arn:aws:logs:us-east-1:111122223333:log-group:*:*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogStream",
                "logs:PutLogEvents"
            ],
            "Resource": "arn:aws:logs:us-east-1:111122223333:log-group:MyLogGroup:*"
        }
    ]
}
    Amazon S3

    Se estiver usando o Amazon S3 para armazenar os logs, adicione a seguinte permissão ao perfil de serviço do CodeBuild:

    JSON
    {
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetEncryptionConfiguration",
        "s3:PutObject"
      ],
      "Resource": [
        "arn:aws:s3:::<bucket-name>",
        "arn:aws:s3:::<bucket-name>/*"
      ]
    }
  ]
}

    Para obter mais informações, consulte Auditing and logging session activity no Guia do usuário do AWS Systems Manager.

Pausar a compilação

Para pausar a compilação, insira o comando codebuild-breakpoint em qualquer uma das fases de compilação no arquivo buildspec. A compilação será pausada nesse momento, o que permite a você se conectar ao contêiner de compilação e visualizar o contêiner no estado atual.

Por exemplo, adicione o seguinte às fases de compilação do arquivo buildspec.

phases:
  pre_build:
    commands:
      - echo Entered the pre_build phase...
      - echo "Hello World" > /tmp/hello-world
      - codebuild-breakpoint

Esse código cria o arquivo /tmp/hello-world e, depois, pausa a compilação nesse momento.

Iniciar a compilação

Para permitir que o Gerenciador de Sessões seja usado com a sessão de compilação, é necessário habilitar as conexões de sessão para a compilação. Para fazer isso, ao iniciar a compilação, siga as estas etapas:

  1. Abra o console do AWS CodeBuild em https://console.aws.amazon.com/codesuite/codebuild/home.

  2. No painel de navegação, selecione Projetos de compilação. Selecione o projeto de compilação e, depois, escolha Iniciar compilação com substituições.

  3. Escolha Advanced build overrides (Substituições de compilação avançadas).

  4. Na seção Ambiente, escolha a opção Habilitar conexão de sessão. Se essa opção não for selecionada, todos os comandos codebuild-breakpoint e codebuild-resume serão ignorados.

  5. Faça todas as outras alterações desejadas e escolha Iniciar compilação.

  6. Monitore o status da compilação no console. Quando a sessão está disponível, o link do Gerenciador de Sessões da AWS é exibido na seção Status da compilação.

Conectar-se ao contêiner de compilação

É possível se conectar ao contêiner de compilação de uma duas formas:

Console do CodeBuild

Em um navegador web, abra o link do Gerenciador de Sessões do AWS para se conectar ao contêiner de compilação. É aberta uma sessão de terminal que permite a você navegar e controlar o contêiner de compilação.

AWS CLI
nota

A máquina local deve ter o plug-in do Gerenciador de Sessões instalado para esse procedimento. Para obter mais informações, consulte Install the Session Manager Plugin for the AWS CLI no Guia do usuário do AWS Systems Manager.

  1. Chame a API batch-get-builds com o ID da compilação para obter informações sobre a compilação, incluindo o identificador de destino da sessão. O nome da propriedade do identificador de destino da sessão varia de acordo com o tipo de saída do comando aws. É por isso que --output json é adicionado ao comando.

    aws codebuild batch-get-builds --ids <buildID> --region <region> --output json

  2. Copie o valor da propriedade sessionTarget. O nome da propriedade sessionTarget pode variar dependendo do tipo de saída do comando aws. É por isso que --output json foi adicionado ao comando na etapa anterior.

  3. Use o comando a seguir para se conectar ao contêiner de compilação.

    aws ssm start-session --target <sessionTarget> --region <region>

Neste exemplo, verifique se o arquivo /tmp/hello-world existe e contém o texto Hello World.

Retomar a compilação

Depois de terminar de examinar o contêiner de compilação, emita o comando codebuild-resume do shell de contêiner.

$ codebuild-resume