Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Tutoriel : Configuration d'un CodeBuild moteur Buildkite hébergé
Ce didacticiel vous montre comment configurer vos CodeBuild projets pour exécuter des tâches Buildkite. Pour plus d'informations sur l'utilisation de Buildkite avec CodeBuild , voir. [Buildkite Runner autogéré dans AWS CodeBuild](buildkite-runner.md)
Pour effectuer ce didacticiel, vous devez d'abord :
+ Ayez accès à une organisation Buildkite. Pour plus d'informations sur la configuration d'un compte et d'une organisation Buildkite, vous pouvez suivre ce didacticiel de [démarrage](https://buildkite.com/docs/pipelines/getting-started).
+ Créez un pipeline, un cluster et une file d'attente Buildkite configurés pour utiliser des coureurs auto-hébergés. Pour plus d'informations sur la configuration de ces ressources, vous pouvez consulter le didacticiel de [configuration du pipeline Buildkite](https://buildkite.com/docs/pipelines/create-your-own).
![\[Construire un projet dans Buildkite\]](http://docs.aws.amazon.com/fr_fr/codebuild/latest/userguide/images/buildkite-first.png)
## Étape 1 : générer un jeton d'agent Buildkite
Au cours de cette étape, vous allez générer un jeton d'agent dans Buildkite qui sera utilisé pour authentifier les coureurs auto-hébergés. CodeBuild Pour plus d'informations sur cette ressource, consultez [Buildkite Agent](https://buildkite.com/docs/agent/v3/tokens) Tokens.
**Pour générer un jeton d'agent Buildkite**
1. Dans votre cluster Buildkite, choisissez **Agent Tokens**, puis choisissez **New** Token.
1. Ajoutez une description au jeton et cliquez sur **Créer un jeton**.
1. Enregistrez la valeur du jeton de l'agent, car elle sera utilisée ultérieurement lors de la configuration CodeBuild du projet.
![\[Jetons d'agent dans Buildkite\]](http://docs.aws.amazon.com/fr_fr/codebuild/latest/userguide/images/buildkite-createtoken.png)
## Étape 2 : Création d'un CodeBuild projet avec un webhook
**Pour créer un CodeBuild projet avec un webhook**
1. Ouvrez la AWS CodeBuild console sur [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home).
1. Créez un projet de construction auto-hébergé. Pour plus d’informations, consultez [Création d'un projet de génération (console)](create-project.md#create-project-console) et [Exécution d'une génération (console)](run-build-console.md).
+ Dans **Configuration du projet**, sélectionnez le **projet Runner**. Dans **Runner** :
+ Pour le **fournisseur Runner**, choisissez **Buildkite**.
+ Pour le **jeton d'agent Buildkite**, choisissez **Créer un nouveau jeton d'agent en utilisant la page de création d'un secret**. Vous serez invité à créer un nouveau secret AWS Secrets Manager avec une valeur de secret égale au jeton d'agent Buildkite que vous avez généré ci-dessus.
+ (Facultatif) Si vous souhaitez utiliser des informations d'identification CodeBuild gérées pour votre tâche, sélectionnez le fournisseur du référentiel source de votre tâche dans les **options d'identification source de Buildkite** et vérifiez que les informations d'identification sont configurées pour votre compte. Vérifiez également que votre pipeline Buildkite utilise **Checkout via HTTPS**.
**Note**
Buildkite nécessite des informations d'identification de source dans l'environnement de construction afin d'extraire le code source de votre tâche. Consultez [Authentification de Buildkite auprès d'un dépôt privé](#sample-runner-buildkite-config) les options d'identification de source disponibles.
+ (Facultatif) Dans **l'environnement** :
+ Choisissez une **image d'environnement** compatible et **calculez**.
Notez que vous avez la possibilité de remplacer les paramètres d'image et d'instance en utilisant une étiquette dans les étapes YAML de Buildkite. Pour de plus amples informations, veuillez consulter [Étape 4 : Mettez à jour les étapes de votre pipeline Buildkite](#sample-runner-buildkite-update-pipeline).
+ (Facultatif) Dans **Buildspec** :
+ Votre spécification de construction sera ignorée par défaut à moins qu'elle ne `buildspec-override: "true"` soit ajoutée en tant qu'étiquette. Au lieu de cela, il le CodeBuild remplacera pour utiliser des commandes qui configureront le coureur auto-hébergé.
**Note**
CodeBuild ne prend pas en charge les fichiers buildspec pour les versions de Runner auto-hébergées par Buildkite. Pour les spécifications de construction en ligne, vous devrez les activer [ git-credential-helper](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec.env.git-credential-helper)dans votre spécification de construction si vous avez configuré les informations d'identification des sources gérées CodeBuild
1. Continuez avec les valeurs par défaut, puis choisissez **Create build project**.
1. Enregistrez l'**URL de charge utile** et les valeurs **secrètes** dans la fenêtre contextuelle **Create Webhook**. Suivez les instructions affichées dans la fenêtre contextuelle pour créer un nouveau webhook d'organisation Buildkite ou passez à la section suivante.
## Étape 3 : créer un CodeBuild webhook dans Buildkite
Au cours de cette étape, vous utiliserez l'**URL de charge utile** et les valeurs **secrètes** du CodeBuild webhook pour créer un nouveau webhook dans Buildkite. Ce webhook sera utilisé pour déclencher des builds au CodeBuild moment où une tâche Buildkite valide démarre.
**Pour créer un nouveau webhook dans Buildkite**
1. Accédez à la page des **paramètres** de votre organisation Buildkite.
1. Sous **Intégrations**, sélectionnez **Services de notification.**
1. Choisissez **Ajouter** à côté de la zone **Webhook**. Sur la page **Ajouter une notification Webhook**, utilisez la configuration suivante :
1. Sous **URL du webhook**, ajoutez la valeur de l'**URL de charge utile** enregistrée.
1. Sous **Jeton**, vérifiez que l'option **Envoyer le jeton sous X-Buildkite-Token** est sélectionnée. Ajoutez la valeur **secrète** de votre webhook dans le champ **Token**.
1. Sous, vérifiez que l'option **Envoyer le jeton sous X-Buildkite-Token** est sélectionnée. Ajoutez la valeur **secrète** de votre webhook dans le champ **Token**.
1. Sous **Events**, sélectionnez l'événement `job.scheduled` webhook.
1. (Facultatif) Sous **Pipelines**, vous pouvez éventuellement choisir de ne déclencher des builds que pour un pipeline spécifique.
1. Choisissez **Ajouter une notification Webhook**.
## Étape 4 : Mettez à jour les étapes de votre pipeline Buildkite
Au cours de cette étape, vous allez mettre à jour les étapes de votre pipeline Buildkite afin d'ajouter les étiquettes nécessaires et les remplacements facultatifs. Pour obtenir la liste complète des remplacements d'étiquettes pris en charge, consultez[Les remplacements d'étiquettes sont pris en charge avec le moteur CodeBuild Buildkite Runner hébergé](buildkite-runner-update-labels.md).
**Mettez à jour les étapes de votre pipeline**
1. **Accédez à la page des étapes de votre pipeline Buildkite en sélectionnant votre pipeline Buildkite, en choisissant **Paramètres**, puis en choisissant Étapes.**
Si ce n'est pas déjà fait, choisissez **Convertir en étapes YAML.**
![\[Étapes de mise à jour de YAML.\]](http://docs.aws.amazon.com/fr_fr/codebuild/latest/userguide/images/buildkite-steps.png)
1. Au minimum, vous devrez spécifier une [balise d'agent Buildkite](https://buildkite.com/docs/agent/v3/cli-start#agent-targeting) faisant référence au nom de votre pipeline. CodeBuild Le nom du projet est nécessaire pour lier les AWS paramètres associés à votre tâche Buildkite à un projet spécifique CodeBuild . En incluant le nom du projet dans le YAML, CodeBuild il est autorisé à invoquer des tâches avec les paramètres de projet corrects.
```
agents:
project: "codebuild-"
```
Voici un exemple d'étapes du pipeline Buildkite avec uniquement la balise d'étiquette du projet :
```
agents:
project: "codebuild-myProject"
steps:
- command: "echo \"Hello World\""
```
Vous pouvez également remplacer votre image et le type de calcul dans l'étiquette. Consultez [Calculez les images prises en charge avec le moteur CodeBuild Buildkite Runner hébergé](buildkite-runner-update-yaml.images.md) la liste des images disponibles. Le type de calcul et l'image figurant dans l'étiquette remplaceront les paramètres d'environnement de votre projet. Pour remplacer les paramètres de votre environnement pour une version de calcul CodeBuild EC2 ou Lambda, utilisez la syntaxe suivante :
```
agents:
project: "codebuild-"
image: "-"
instance-size: ""
```
Voici un exemple d'étapes du pipeline Buildkite avec des remplacements de taille d'image et d'instance :
```
agents:
project: "codebuild-myProject"
image: "arm-3.0"
instance-size: "small"
steps:
- command: "echo \"Hello World\""
```
Vous pouvez remplacer le parc utilisé pour votre construction dans l'étiquette. Cela remplacera les paramètres de flotte configurés dans votre projet pour utiliser le parc spécifié. Pour plus d'informations, voir [Exécuter des builds sur des flottes de capacité réservée](https://docs.aws.amazon.com/codebuild/latest/userguide/fleets.html).
Pour remplacer les paramètres de votre flotte pour une version de calcul Amazon EC2, utilisez la syntaxe suivante :
```
agents:
project: "codebuild-"
fleet: ""
```
Pour remplacer à la fois la flotte et l'image utilisées pour la génération, utilisez la syntaxe suivante :
```
agents:
project: "codebuild-"
fleet: ""
image: "-"
```
Voici un exemple d'étapes du pipeline Buildkite avec des remplacements de flotte et d'image :
```
agents:
project: "codebuild-myProject"
fleet: "myFleet"
image: "arm-3.0"
steps:
- command: "echo \"Hello World\""
```
1. Vous pouvez choisir d'exécuter des commandes buildspec en ligne lors de la version auto-hébergée de Buildkite Runner (voir pour plus de détails). [Exécutez les commandes buildspec pour les phases INSTALL, PRE\$1BUILD et POST\$1BUILD](sample-runner-buildkite-buildspec.md) Pour spécifier que le CodeBuild build doit exécuter les commandes buildspec lors de votre build d'exécution auto-hébergé par Buildkite, utilisez la syntaxe suivante :
```
agents:
project: "codebuild-"
buildspec-override: "true"
```
Voici un exemple de pipeline Buildkite avec une dérogation buildspec :
```
agents:
project: "codebuild-myProject"
buildspec-override: "true"
steps:
- command: "echo \"Hello World\""
```
1. Vous pouvez éventuellement fournir des étiquettes autres que celles prises CodeBuild en charge. Ces étiquettes seront ignorées dans le but de remplacer les attributs de la version, mais elles n'échoueront pas à la demande de webhook. Par exemple, l'ajout `myLabel: “testLabel"` d'une étiquette n'empêchera pas le build de s'exécuter.
## Étape 5 : Passez en revue vos résultats
Chaque fois qu'une tâche Buildkite est lancée dans votre pipeline, vous CodeBuild recevrez un événement webhook via le `job.scheduled` webhook Buildkite. Pour chaque tâche de votre build de Buildkite, une version CodeBuild sera lancée pour exécuter un Runner Buildkite éphémère. Le coureur est responsable de l'exécution d'une seule tâche Buildkite. Une fois le travail terminé, le lanceur et le processus de construction associé seront immédiatement interrompus.
Pour consulter les journaux des tâches de votre flux de travail, accédez à votre pipeline Buildkite et sélectionnez la version la plus récente (vous pouvez déclencher une nouvelle version en choisissant **Nouvelle version**). Une fois que le CodeBuild build associé à chacune de vos tâches démarre et reprend la tâche, vous devriez voir les journaux de la tâche dans la console Buildkite
![\[Passez en revue les résultats.\]](http://docs.aws.amazon.com/fr_fr/codebuild/latest/userguide/images/buildkite-log.png)
## Authentification de Buildkite auprès d'un dépôt privé
Si vous avez configuré un dépôt privé dans votre pipeline Buildkite, Buildkite a besoin d'[autorisations supplémentaires dans l'environnement de construction pour extraire le](https://buildkite.com/docs/agent/v3/github-ssh-keys) référentiel, car Buildkite ne vend pas d'informations d'identification à des exécuteurs auto-hébergés pour les extraire des référentiels privés. Pour authentifier l'agent Runner auto-hébergé par Buildkite auprès de votre référentiel source privé externe, vous pouvez utiliser l'une des options suivantes.
**Pour vous authentifier auprès de CodeBuild**
CodeBuild propose une gestion des informations d'identification gérées pour les types de sources pris en charge. Pour utiliser les informations d'identification CodeBuild source pour extraire le référentiel source de votre tâche, vous pouvez suivre les étapes suivantes :
1. Dans la CodeBuild console, accédez à **Modifier le projet** ou créez un nouveau CodeBuild projet en suivant les étapes décrites dans[Étape 2 : Création d'un CodeBuild projet avec un webhook](#sample-runner-buildkite-create-project).
1. Sous les **options d'identification source de Buildkite**, sélectionnez le fournisseur du référentiel source de votre tâche.
1. Si vous souhaitez utiliser les informations d' CodeBuild identification au niveau du compte, vérifiez qu'elles sont correctement configurées. De plus, si une spécification de construction en ligne est configurée dans votre projet, vérifiez qu'elle est activée. [ git-credential-helper](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec.env.git-credential-helper)
1. Si vous souhaitez utiliser les informations d' CodeBuild identification au niveau du projet, sélectionnez **Utiliser les informations d'identification de remplacement pour ce projet uniquement** et configurez les informations d'identification pour votre projet.
1. Dans les paramètres de votre pipeline Buildkite, accédez aux paramètres **du référentiel**. Définissez les paramètres de récupération de votre référentiel source sur **Checkout via HTTPS**
![\[Passez en revue les résultats.\]](http://docs.aws.amazon.com/fr_fr/codebuild/latest/userguide/images/buildkite-repo-https.png)
**Pour vous authentifier avec les secrets de Buildkite**
Buildkite gère un [plugin ssh-checkout](https://github.com/buildkite-plugins/git-ssh-checkout-buildkite-plugin) qui peut être utilisé pour authentifier le runner auto-hébergé auprès d'un référentiel source externe à l'aide d'une clé ssh. La valeur clé est stockée sous forme de [secret Buildkite](https://buildkite.com/docs/pipelines/security/secrets/buildkite-secrets) et récupérée automatiquement par l'agent Runner auto-hébergé par Buildkite lorsqu'il tente d'extraire un dépôt privé. Afin de configurer le plugin ssh-checkout pour votre pipeline Buildkite, vous pouvez suivre les étapes suivantes :
1. Générez une clé SSH privée et publique en utilisant votre adresse e-mail, par exemple `ssh-keygen -t rsa -b 4096 -C "myEmail@address.com"`
1. Ajoutez la clé publique à votre référentiel source privé. Par exemple, vous pouvez suivre [ce guide](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account) pour ajouter une clé à un GitHub compte.
1. Ajoutez une [nouvelle clé secrète SSH](https://buildkite.com/docs/pipelines/hosted-agents/code-access#private-repositories-with-other-providers-add-the-ssh-key-secret) à votre cluster Buildkite. Dans votre cluster Buildkite, sélectionnez **Secrets** → **Nouveau** secret. Donnez un nom à votre secret dans le champ **Clé** et ajoutez votre clé SSH privée dans le champ **Valeur** :
![\[Passez en revue les résultats.\]](http://docs.aws.amazon.com/fr_fr/codebuild/latest/userguide/images/buildkite-secret.png)
1. **Dans votre pipeline Buildkite, accédez aux paramètres de votre dépôt et configurez le checkout pour qu'il utilise SSH.**
![\[Passez en revue les résultats.\]](http://docs.aws.amazon.com/fr_fr/codebuild/latest/userguide/images/buildkite-repo.png)
1. Mettez à jour les étapes YAML de votre pipeline pour utiliser le `git-ssh-checkout` plugin. Par exemple, le fichier YAML de pipeline suivant utilise l'action de paiement avec la clé secrète Buildkite ci-dessus :
```
agents:
project: "codebuild-myProject"
steps:
- command: "npm run build"
plugins:
- git-ssh-checkout#v0.4.1:
ssh-secret-key-name: 'SOURCE_SSH_KEY'
```
1. Lorsque vous exécutez une tâche d'exécution auto-hébergée par Buildkite dans Buildkite CodeBuild, Buildkite utilise désormais automatiquement votre valeur secrète configurée lors de l'extraction de votre dépôt privé
## Options de configuration du coureur
Vous pouvez spécifier les variables d'environnement suivantes dans la configuration de votre projet pour modifier la configuration de vos coureurs auto-hébergés :
+ `CODEBUILD_CONFIG_BUILDKITE_AGENT_TOKEN`: CodeBuild récupérera la valeur secrète configurée comme valeur de cette variable d'environnement afin d'enregistrer l' AWS Secrets Manager agent d'exécution auto-hébergé par Buildkite. Cette variable d'environnement doit être de type `SECRETS_MANAGER` et sa valeur doit être le nom de votre secret dans Secrets Manager. Une variable d'environnement de jeton d'agent Buildkite est requise pour tous les projets Buildkite Runner.
+ `CODEBUILD_CONFIG_BUILDKITE_CREDENTIAL_DISABLE`: Par défaut, CodeBuild chargera les informations d'identification source au niveau du compte ou du projet dans l'environnement de construction, car ces informations d'identification sont utilisées par l'agent Buildkite pour extraire le référentiel source de la tâche. Pour désactiver ce comportement, vous pouvez ajouter cette variable d'environnement à votre projet avec la valeur définie sur`true`, ce qui empêchera le chargement des informations d'identification de la source dans l'environnement de génération.