Depuración de compilaciones con Administrador de sesiones - AWS CodeBuild
Requisitos previosPausar la compilaciónIniciar la compilaciónConectarse al contenedor de compilaciónReanudar la compilación

Depuración de compilaciones con Administrador de sesiones

En AWS CodeBuild, puede pausar una compilación en ejecución y, a continuación, usar AWS Systems Manager Session Manager para conectarse al contenedor de compilación y ver su estado.

nota

Esta característica no está disponible en entornos Windows.

Requisitos previos

Para permitir el uso de Session Manager con la sesión de compilación, es necesario habilitar la conexión de sesión para la compilación. Hay dos prerrequisitos:

  • Las imágenes seleccionadas estándar Linyx de CodeBuild ya tienen el agente SSM instalado y el ContainerMode del agente SSM activado.

    Si va a utilizar una imagen personalizada para la compilación, haga lo siguiente:

    1. Instalar el SSM Agent de . Para obtener más información, consulte Instalación manual de SSM Agent en instancias EC2 de Linux en la Guía del usuario de AWS Systems Manager. La versión de SSM Agent debe ser 3.0.1295.0 o posterior.

    2. Copie el archivo https://github.com/aws/aws-codebuild-docker-images/blob/master/ubuntu/standard/5.0/amazon-ssm-agent.json en el directorio /etc/amazon/ssm/ de la imagen. De este modo se habilita Modo de contenedor en SSM Agent.

    nota

    Las imágenes personalizadas requieren el agente SSM más actualizado para que esta función funcione según lo esperado.

  • El rol de servicio de CodeBuild debe tener la política SSM siguiente:

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

    Puede hacer que la consola CodeBuild asocie automáticamente esta política a su rol de servicio al iniciar la compilación. Como alternativa, puede adjuntar la política al rol de servicio manualmente.

  • Si tiene habilitada la actividad de auditoría y registro de la sesión en las preferencias de Systems Manager, el rol de servicio de CodeBuild también debe tener permisos adicionales. Los permisos varían según el lugar donde se almacenen los registros.

    Registros de CloudWatch

    Si utiliza Registros de CloudWatch para almacenar sus registros, añada el permiso siguiente al rol de servicio de 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

    Si utiliza Amazon S3 para almacenar sus registros, añada el permiso siguiente al rol de servicio de 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 obtener más información, consulte Actividad de auditoría y registro de sesión en la Guía del usuario de AWS Systems Manager.

Pausar la compilación

Para pausar la compilación, inserte el comando codebuild-breakpoint en cualquiera de las fases de compilación del archivo de especificación de compilación. La compilación se pausará en este punto, lo que permite conectar con el contenedor de compilación y ver el contenedor en su estado actual.

Por ejemplo, añada lo siguiente a las fases de compilación del archivo de especificación de compilación.

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

Este código crea el archivo /tmp/hello-world y, a continuación, detiene la compilación en este punto.

Iniciar la compilación

Para permitir el uso de Session Manager con la sesión de compilación, es necesario habilitar las conexiones de sesión para la compilación. Para hacerlo, al iniciar la compilación, siga estos pasos:

  1. Abra la consola de AWS CodeBuild en https://console.aws.amazon.com/codesuite/codebuild/home.

  2. En el panel de navegación, elija Proyectos de compilación. Elija el proyecto de compilación y, a continuación, elija Iniciar compilación con anulaciones.

  3. Seleccione Advanced build overrides (Sustitución avanzada de compilaciones).

  4. En la sección Entorno, elija la opción Habilitar la conexión de sesión. Si no se selecciona esta opción, se ignoran todos los comandos de codebuild-breakpoint y codebuild-resume.

  5. Realice los demás cambios que desee y elija Iniciar compilación.

  6. Monitoriza el estado de la compilación en la consola. Cuando la sesión esté disponible, el enlace al AWS Session Manager aparecerá en la sección Estado de compilación.

Conectarse al contenedor de compilación

Es posible conectarse al contenedor de compilación de una de las dos formas siguientes:

Consola de CodeBuild

En un navegador web, abra el enlace de AWS Session Manager para conectarse al contenedor de compilación. Se abre una sesión de terminal que le permite explorar y controlar el contenedor de compilación.

AWS CLI
nota

Su máquina local debe tener instalado el complemento de Session Manager para realizar este procedimiento. Para obtener más información, consulte Instalación del complemento Session Manager para la CLI de AWS en la Guía del usuario de AWS Systems Manager.

  1. Llame a la API de batch-get-builds con el ID de compilación para obtener información sobre la compilación, incluido el identificador de destino de la sesión. El nombre de la propiedad del identificador de destino de la sesión varía según el tipo de salida del comando aws. Por eso se añade --output json al comando.

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

  2. Copie el valor de la propiedad sessionTarget. El nombre de la propiedad sessionTarget puede variar en función del tipo de salida del comando aws. Por eso se añade --output json al comando en el paso anterior.

  3. Utilice el comando siguiente para conectarse al contenedor de compilación.

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

Para este ejemplo, comprueba que el archivo /tmp/hello-world exista y contiene el texto Hello World.

Reanudar la compilación

Después de examinar el contenedor de compilación, ejecute el comando codebuild-resume desde el intérprete de comandos del contenedor.

$ codebuild-resume