Tutorial: Configuración de un ejecutor de Buildkite alojado en CodeBuild

Generación de un token de agente de Buildkite

1. En el clúster de Buildkite, elija Tokens de agente y, a continuación, Nuevo token.

2. Agregue una descripción al token y haga clic en Crear token.

3. Guarde el valor del token del agente, ya que se utilizará más adelante durante la configuración del proyecto de CodeBuild.

   

Para crear un proyecto de CodeBuild con un webhook

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

2. Cree un proyecto de compilación autoalojado. Para obtener más información, consulte Creación de un proyecto de compilación (consola) y Ejecutar una compilación (consola).

   • En Project Configurator, seleccione Proyecto de ejecutor. En Ejecutor:

     • En Proveedor de ejecutor, elija Buildkite.

     • En Token de agente de Buildkite, seleccione Crear un nuevo token de agente mediante la página de creación de secreto. Se le pedirá que cree un nuevo secreto en AWS Secrets Manager con un valor de secreto igual al token de agente de Buildkite que generó anteriormente.

     • (Opcional) Si desea utilizar las credenciales administradas por CodeBuild para el trabajo, seleccione el proveedor de repositorios de código fuente del trabajo en Opciones de credenciales de código fuente de Buildkite y compruebe que las credenciales estén configuradas para su cuenta. Además, verifique que la canalización de Buildkite utilice Extracción mediante HTTPS.

     nota

     Buildkite requiere credenciales de código fuente en el entorno de compilación para poder extraer el código fuente del trabajo. Consulte en Autenticación de Buildkite en un repositorio privado las opciones de credenciales de código fuente disponibles.

   • (Opcional) En Entorno:

     • Elija una Imagen del entorno y una Computación compatibles.

       Tenga en cuenta que tiene la opción de anular la configuración de imagen e instancia mediante una etiqueta en los pasos de YAML de Buildkite. Para obtener más información, consulte Paso 4: actualización de los pasos de la canalización de Buildkite.

   • (Opcional) En Buildspec:

     • La buildspec se ignorará de forma predeterminada a menos que se agregue buildspec-override: "true" como etiqueta. En su lugar, CodeBuild la anulará para usar comandos que configurarán el ejecutor autoalojado.

       nota

       CodeBuild no admite archivos buildspec para las compilaciones de ejecutores autoalojados de Buildkite. Para buildspecs integradas, deberá habilitar git-credential-helper en la buildspec si ha configurado credenciales de código fuente administrado por CodeBuild.

3. Continúe con los valores predeterminados y, a continuación, elija Crear el proyecto de compilación.

4. Guarde los valores de URL de carga útil y Secreto de la ventana emergente Crear webhook. Siga las instrucciones de la ventana emergente para crear un nuevo webhook de organización de Buildkite o continúe con la siguiente sección.

Cómo crear un nuevo webhook en Buildkite

1. Vaya a la página Configuración de la organización de Buildkite.

2. En Integraciones, seleccione Servicios de notificación.

3. Seleccione Agregar junto a la casilla Webhook. En la página Agregar notificación de webhook, use la siguiente configuración:

   1. En URL de webhook, agregue el valor de URL de carga útil guardado.

   2. En Token, compruebe que esté seleccionada Enviar el token como X-Buildkite-Token. Agregue el valor de Secreto de webhook al campo Token.

   3. En Token, compruebe que esté seleccionada Enviar el token como X-Buildkite-Token. Agregue el valor de Secreto de webhook al campo Token.

   4. En Eventos, seleccione el evento del webhook job.scheduled.

   5. (Opcional) En Canalizaciones, puede elegir opcionalmente desencadenar solo las compilaciones de una canalización específica.

4. Seleccione Agregar notificación de webhook.

Actualización de los pasos de la canalización

1. Vaya a la página de pasos de la canalización de Buildkite seleccionando la canalización de Buildkite, luego Configuración y, por último, Pasos.

   Si aún no lo ha hecho, elija Convertir a pasos de YAML.

   

2. Como mínimo, tendrá que especificar una Etiqueta de agente de Buildkite que haga referencia al nombre de la canalización de CodeBuild. El nombre del proyecto es necesario para vincular la configuración relacionada con AWS de su trabajo de Buildkite a un proyecto de CodeBuild específico. Al incluir el nombre del proyecto en el YAML, CodeBuild puede invocar trabajos con la configuración de proyecto correcta.

   agents:
     project: "codebuild-<project name>"

   A continuación, se muestra un ejemplo de pasos de canalización de Buildkite solo con la etiqueta del proyecto:

   agents:
     project: "codebuild-myProject"
   steps:
     - command: "echo \"Hello World\""

   También puede anular el tipo de computación e imagen en la etiqueta. Consulte Imágenes de computación compatibles con el ejecutor de Buildkite alojado en CodeBuild para obtener una lista de las imágenes disponibles. El tipo de computación y la imagen de la etiqueta anularán la configuración del entorno en el proyecto. Para anular la configuración del entorno para una compilación de computación de EC2 de CodeBuild o Lambda, utilice la siguiente sintaxis:

   agents:
     project: "codebuild-<project name>"
     image: "<environment-type>-<image-identifier>"
     instance-size: "<instance-size>"

   A continuación, se muestra un ejemplo de pasos de canalización de Buildkite con anulaciones de tamaño de imagen e instancia:

   agents:
     project: "codebuild-myProject"
     image: "arm-3.0"
     instance-size: "small"
   steps:
     - command: "echo \"Hello World\""

   Puede anular la flota utilizada para su compilación en la etiqueta. Al hacerlo, se anularán los valores de flota configurados en el proyecto para usar la flota especificada. Para obtener más información, consulte Ejecución de compilaciones en flotas de capacidad reservada.

   Si quiere anular la configuración de la flota para una compilación de computación de Amazon EC2, utilice la siguiente sintaxis:

   agents:
     project: "codebuild-<project name>"
     fleet: "<fleet-name>"
   

   Para anular tanto la flota como la imagen utilizadas para la compilación, utilice la sintaxis siguiente:

   agents:
     project: "codebuild-<project name>"
     fleet: "<fleet-name>"
     image: "<environment-type>-<image-identifier>"

   A continuación, se muestra un ejemplo de pasos de canalización de Buildkite con anulaciones de flota e imagen:

   agents:
     project: "codebuild-myProject"
     fleet: "myFleet"
     image: "arm-3.0"
   steps:
     - command: "echo \"Hello World\""

3. Puede optar por ejecutar comandos buildspec integrados durante la compilación del ejecutor autoalojado en Buildkite (consulte Ejecución de comandos buildspec durante las fases INSTALL, PRE_BUILD y POST_BUILD para obtener más información). Para especificar que la compilación de CodeBuild debe ejecutar comandos buildspec durante la compilación del ejecutor autoalojado de Buildkite, use la siguiente sintaxis:

   agents:
     project: "codebuild-<project name>"
     buildspec-override: "true"

   A continuación, se muestra un ejemplo de canalización de Buildkite con anulaciones de buildspec:

   agents:
     project: "codebuild-myProject"
     buildspec-override: "true"
   steps:
     - command: "echo \"Hello World\""

4. Como opción, puede proporcionar etiquetas distintas a las admitidas por CodeBuild. Estas etiquetas se ignorarán para el fin de anular los atributos de la compilación, pero no provocarán un error de la solicitud de webhook. Por ejemplo, agregar myLabel: “testLabel" como etiqueta no impedirá que la compilación se ejecute.

Cómo autenticarse con CodeBuild

CodeBuild ofrece control de credenciales administrada para los tipos de código fuente compatibles. Si desea usar las credenciales de código fuente de CodeBuild para extraer el repositorio de código fuente del trabajo, puede seguir estos pasos:

1. En la consola de CodeBuild, vaya a Editar proyecto o cree un nuevo proyecto de CodeBuild siguiendo los pasos que se indican en Paso 2: creación de un proyecto de CodeBuild con un webhook.

2. En Opciones de credenciales de código fuente de Buildkite, seleccione el proveedor de repositorio de código fuente del trabajo.

   1. Si desea utilizar credenciales de CodeBuild de nivel de cuenta, compruebe que estén configuradas correctamente. Además, si el proyecto tiene una buildspec integrada configurada, compruebe que git-credential-helper esté habilitado.

   2. Si desea usar credenciales de CodeBuild de nivel de proyecto, seleccione Usar credenciales de anulación solo para este proyecto y configure las credenciales para el proyecto.

3. En la configuración de la canalización de Buildkite, vaya a Configuración del repositorio. Establezca la configuración de extracción del repositorio de código fuente en Extracción mediante HTTPS

   

Cómo autenticarse con secretos de Buildkite

Buildkite mantiene un complemento ssh-checkout que se puede utilizar para autenticar el ejecutor autoalojado en un repositorio de código fuente externo mediante una clave ssh. El valor de clave se guarda como Secreto de Buildkite y el agente de ejecutor autoalojado en Buildkite lo recupera automáticamente al intentar acceder a un repositorio privado. Para configurar el complemento ssh-checkout para la canalización de Buildkite, puede seguir estos pasos:

1. Genere una clave ssh privada y pública con su dirección de correo electrónico, p. ej. ssh-keygen -t rsa -b 4096 -C "myEmail@address.com"

2. Agregue la clave pública al repositorio de código fuente privado. Por ejemplo, puede seguir esta guía para agregar una clave a una cuenta de GitHub.

3. Agregue una nueva clave SSH secreta al clúster de Buildkite. En el clúster de Buildkite, seleccione Secretos → Nuevo secreto. Agregue un nombre para el secreto en el campo Clave y agregue la clave SSH privada al campo Valor:

   

4. En la canalización de Buildkite, navegue hasta la configuración del repositorio y configure el proceso de extracción para que use SSH.

   

5. Actualice los pasos de YAML de la canalización para usar el complemento git-ssh-checkout. Por ejemplo, el siguiente archivo YAML de canalización utiliza la acción de extracción con la clave del secreto de Buildkite anterior:

   agents:
     project: "codebuild-myProject"
   steps:
     - command: "npm run build"
       plugins:
         - git-ssh-checkout#v0.4.1:
             ssh-secret-key-name: 'SOURCE_SSH_KEY'

6. Al ejecutar en CodeBuild un trabajo de ejecutor autoalojado en Buildkite, ahora Buildkite usará automáticamente el valor secreto configurado al extraer el repositorio privado