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.
# Utiliser le cadre de documentation des AWSTOE composants pour les composants personnalisés
Pour créer un composant à l'aide de la structure de composants AWS Task Orchestrator and Executor (AWSTOE), vous devez fournir un document basé sur YAML qui représente les phases et les étapes applicables au composant que vous créez. Services AWS utilisent votre composant lorsqu'ils créent une nouvelle image de machine Amazon (AMI) ou une nouvelle image de conteneur.
**Topics**
+ [Flux de travail documentaire des composants](#component-doc-workflow)
+ [Journalisation des composants](#component-logging)
+ [Chainage des entrées et des sorties](#document-chaining)
+ [Schéma du document et définitions](#document-schema)
+ [Exemples de documents](#document-example)
+ [Utiliser des variables dans votre document de composant personnalisé](toe-user-defined-variables.md)
+ [Utiliser des constructions conditionnelles dans AWSTOE](toe-conditional-constructs.md)
+ [Utiliser des opérateurs de comparaison dans les documents relatifs aux AWSTOE composants](toe-comparison-operators.md)
+ [Utiliser des opérateurs logiques dans les documents relatifs aux AWSTOE composants](toe-logical-operators.md)
+ [Utiliser des constructions en boucle dans AWSTOE](toe-looping-constructs.md)
## Flux de travail documentaire des composants
Le document du AWSTOE composant utilise des phases et des étapes pour regrouper les tâches associées et organiser ces tâches dans un flux de travail logique pour le composant.
**Astuce**
Le service qui utilise votre composant pour créer une image peut implémenter des règles concernant les phases à utiliser pour son processus de génération et le moment où ces phases sont autorisées à s'exécuter. Il est important d'en tenir compte lors de la conception de votre composant.
**Phases**
Les phases représentent la progression de votre flux de travail tout au long du processus de création de l'image. Par exemple, le service Image Builder utilise `build` et met en `validate` phase les images qu'il produit au cours de sa *phase de création*. Il utilise les `container-host-test` phases `test` et au cours de sa *phase de test* pour s'assurer que l'instantané d'image ou l'image du conteneur produit les résultats attendus avant de créer l'AMI finale ou de distribuer l'image du conteneur.
Lorsque le composant s'exécute, les commandes associées à chaque phase sont appliquées dans l'ordre dans lequel elles apparaissent dans le document du composant.
**Règles pour les phases**
+ Chaque nom de phase doit être unique dans un document.
+ Vous pouvez définir de nombreuses phases dans votre document.
+ Vous devez inclure au moins l'une des phases suivantes dans votre document :
+ **build** — pour Image Builder, cette phase est généralement utilisée pendant la *phase de construction*.
+ **valider** — pour Image Builder, cette phase est généralement utilisée pendant la *phase de construction*.
+ **test** — pour Image Builder, cette phase est généralement utilisée pendant la *phase de test*.
+ Les phases s'exécutent toujours dans l'ordre dans lequel elles sont définies dans le document. L'ordre dans lequel elles sont spécifiées pour AWSTOE les commandes du n' AWS CLI a aucun effet.
**Étapes**
Les étapes sont des unités de travail individuelles qui définissent le flux de travail au sein de chaque phase. Les étapes sont exécutées par ordre séquentiel. Cependant, l'entrée ou la sortie d'une étape peuvent également alimenter une étape suivante en tant qu'entrée. C'est ce qu'on appelle le « chaînage ».
**Règles relatives aux étapes**
+ Le nom de l'étape doit être unique pour la phase.
+ L'étape doit utiliser une action prise en charge (module d'action) qui renvoie un code de sortie.
Pour obtenir la liste complète des modules d'action pris en charge, leur fonctionnement, leurs input/output valeurs et des exemples, voir[Modules d'action pris en charge par le gestionnaire de AWSTOE composants](toe-action-modules.md).
## Journalisation des composants
AWSTOE crée un nouveau dossier journal sur les instances EC2 utilisées pour créer et tester une nouvelle image, chaque fois que votre composant s'exécute. Pour les images de conteneur, le dossier journal est stocké dans le conteneur.
Pour faciliter le dépannage en cas de problème lors du processus de création de l'image, le document d'entrée et tous les fichiers de sortie AWSTOE créés lors de l'exécution du composant sont stockés dans le dossier journal.
Le nom du dossier journal comprend les éléments suivants :
1. **Répertoire des journaux** : lorsqu'un service exécute un AWSTOE composant, il est transmis dans le répertoire des journaux, ainsi que les autres paramètres de la commande. Dans les exemples suivants, nous montrons le format de fichier journal utilisé par Image Builder.
+ **Linux et macOS** : `/var/lib/amazon/toe/`
+ **Windows** : `$env:ProgramFiles\Amazon\TaskOrchestratorAndExecutor\`
1. **Préfixe de fichier** — Il s'agit d'un préfixe standard utilisé pour tous les composants : « »`TOE_`.
1. Durée d'**exécution : il s'**agit d'un horodatage au format YYYY-MM-DD \_HH-MM-SS\_UTC-0.
1. **ID d'exécution** : il s'agit du GUID attribué lors de l' AWSTOE exécution d'un ou de plusieurs composants.
Exemple : `{{/var/lib/amazon/toe/}}TOE_{{2021-07-01_12-34-56_UTC-0}}_{{a1bcd2e3-45f6-789a-bcde-0fa1b2c3def4}}`
AWSTOE stocke les fichiers principaux suivants dans le dossier journal :
**Fichiers d'entrée**
+ **document.yaml** — Document utilisé comme entrée pour la commande. Une fois le composant exécuté, ce fichier est stocké sous forme d'artefact.
**Fichiers de sortie**
+ **application.log** — Le journal de l'application contient des informations horodatées AWSTOE sur le niveau de débogage indiquant ce qui se passe pendant l'exécution du composant.
+ **detailedoutput.json** — Ce fichier JSON contient des informations détaillées sur l'état d'exécution, les entrées, les sorties et les échecs pour tous les documents, phases et étapes applicables au composant lors de son exécution.
+ **console.log** — Le journal de la console contient toutes les informations de sortie standard (stdout) et d'erreur standard (stderr) écrites sur la console pendant l'exécution du composant. AWSTOE
+ **chaining.json** — Ce fichier JSON représente les optimisations AWSTOE appliquées pour résoudre les expressions de chaînage.
**Note**
Le dossier journal peut également contenir d'autres fichiers temporaires qui ne sont pas abordés ici.
## Chainage des entrées et des sorties
L'application AWSTOE de gestion de configuration fournit une fonctionnalité permettant de chaîner les entrées et les sorties en écrivant des références dans les formats suivants :
`{{ phase_name.step_name.inputs/outputs.variable }}`
or
`{{ phase_name.step_name.inputs/outputs[index].variable }}`
La fonction de chaînage vous permet de recycler le code et d'améliorer la maintenabilité du document.
**Règles de chaînage**
+ Les expressions de chaînage ne peuvent être utilisées que dans la section des entrées de chaque étape.
+ Les instructions contenant des expressions de chaînage doivent être placées entre guillemets. Par exemple :
+ **Expression non valide** : `echo {{ phase.step.inputs.variable }}`
+ **Expression valide** : `"echo {{ phase.step.inputs.variable }}"`
+ **Expression valide** : `'echo {{ phase.step.inputs.variable }}'`
+ Les expressions de chaînage peuvent faire référence à des variables issues d'autres étapes et phases du même document. Cependant, le service d'appel peut avoir des règles qui exigent que le chaînage des expressions ne fonctionne que dans le contexte d'une seule étape. Par exemple, Image Builder ne prend pas en charge le chaînage entre la *phase de création* et la *phase de test*, car il exécute chaque étape indépendamment.
+ Les index des expressions de chaînage suivent une indexation basée sur zéro. L'indice commence par zéro (0) pour référencer le premier élément.
**Exemples**
Pour faire référence à la variable source dans la deuxième entrée de l'étape d'exemple suivante, le modèle de chaînage est`{{ build.{{SampleS3Download}}.inputs[1].source }}`.
```
phases:
- name: 'build'
steps:
- name: {{SampleS3Download}}
action: S3Download
timeoutSeconds: 60
onFailure: Abort
maxAttempts: 3
inputs:
- source: 's3://{{sample-bucket}}/{{sample1}}.ps1'
destination: 'C:\{{sample1}}.ps1'
- source: 's3://{{sample-bucket}}/{{sample2}}.ps1'
destination: 'C:\{{sample2}}.ps1'
```
Pour faire référence à la variable de sortie (égale à « Hello ») de l'étape d'exemple suivante, le modèle de chaînage est`{{ build.{{SamplePowerShellStep}}.outputs.stdout }}`.
```
phases:
- name: 'build'
steps:
- name: {{SamplePowerShellStep}}
action: ExecutePowerShell
timeoutSeconds: 120
onFailure: Abort
maxAttempts: 3
inputs:
commands:
- 'Write-Host "Hello"'
```
## Schéma du document et définitions
Le schéma YAML d'un document est le suivant.
```
name: (optional)
description: (optional)
schemaVersion: "string"
phases:
- name: "string"
steps:
- name: "string"
action: "string"
timeoutSeconds: integer
onFailure: "Abort|Continue|Ignore"
maxAttempts: integer
inputs:
```
Les définitions de schéma d'un document sont les suivantes.
| Champ | Description | Type | Obligatoire |
| --- | --- | --- | --- |
| name | Nom du document. | String | Non |
| description | Description du document. | String | Non |
| schemaVersion | Version du schéma du document, actuellement 1.0. | String | Oui |
| phases | Une liste des phases avec leurs étapes. | List | Oui |
Les définitions du schéma d'une phase sont les suivantes.
| Champ | Description | Type | Obligatoire |
| --- | --- | --- | --- |
| name | Nom de la phase. | String | Oui |
| steps | Liste des étapes de la phase. | List | Oui |
Les définitions du schéma d'une étape sont les suivantes.
| Champ | Description | Type | Obligatoire | Valeur par défaut |
| --- | --- | --- | --- | --- |
| name | Nom défini par l'utilisateur pour l'étape. | String | | |
| action | Mot-clé relatif au module qui exécute l'étape. | String | | |
| timeoutSeconds | Nombre de secondes pendant lesquelles l'étape s'exécute avant d'échouer ou de réessayer.
Supporte également la valeur -1, ce qui indique un délai d'expiration infini. 0 et les autres valeurs négatives ne sont pas autorisées. | Entier | Non | 7 200 secondes (120 minutes) |
| onFailure | Spécifie ce que l'étape doit faire en cas d'échec. Les valeurs valides sont les suivantes : [See the AWS documentation website for more details](http://docs.aws.amazon.com/fr_fr/imagebuilder/latest/userguide/toe-use-documents.html) | String | Non | Interruption |
| maxAttempts | Nombre maximum de tentatives autorisées avant d'échouer à l'étape. | Entier | Non | 1 |
| inputs | Contient les paramètres requis par le module d'action pour exécuter l'étape. | Dict | Oui | |
## Exemples de documents
Les exemples suivants présentent des documents de AWSTOE composants qui exécutent des tâches pour le système d'exploitation cible.
------
#### [ Linux ]
**Exemple 1 : Exécuter un fichier binaire personnalisé**
Voici un exemple de document qui télécharge et exécute un fichier binaire personnalisé sur une instance Linux.
```
name: LinuxBin
description: Download and run a custom Linux binary file.
schemaVersion: 1.0
phases:
- name: build
steps:
- name: Download
action: S3Download
inputs:
- source: s3://amzn-s3-demo-source-bucket/myapplication
destination: /tmp/myapplication
- name: Enable
action: ExecuteBash
onFailure: Continue
inputs:
commands:
- 'chmod u+x {{ build.Download.inputs[0].destination }}'
- name: Install
action: ExecuteBinary
onFailure: Continue
inputs:
path: '{{ build.Download.inputs[0].destination }}'
arguments:
- '--install'
- name: Delete
action: DeleteFile
inputs:
- path: '{{ build.Download.inputs[0].destination }}'
```
------
#### [ Windows ]
**Exemple 1 : Installation des mises à jour Windows**
Voici un exemple de document qui installe toutes les mises à jour Windows disponibles, exécute un script de configuration, valide les modifications avant la création de l'AMI et teste les modifications après la création de l'AMI.
```
name: RunConfig_UpdateWindows
description: 'This document will install all available Windows updates and run a config script. It will then validate the changes before an AMI is created. Then after AMI creation, it will test all the changes.'
schemaVersion: 1.0
phases:
- name: build
steps:
- name: DownloadConfigScript
action: S3Download
timeoutSeconds: 60
onFailure: Abort
maxAttempts: 3
inputs:
- source: 's3://customer-bucket/config.ps1'
destination: 'C:\config.ps1'
- name: RunConfigScript
action: ExecutePowerShell
timeoutSeconds: 120
onFailure: Abort
maxAttempts: 3
inputs:
file: '{{build.DownloadConfigScript.inputs[0].destination}}'
- name: Cleanup
action: DeleteFile
onFailure: Abort
maxAttempts: 3
inputs:
- path: '{{build.DownloadConfigScript.inputs[0].destination}}'
- name: RebootAfterConfigApplied
action: Reboot
inputs:
delaySeconds: 60
- name: InstallWindowsUpdates
action: UpdateOS
- name: validate
steps:
- name: DownloadTestConfigScript
action: S3Download
timeoutSeconds: 60
onFailure: Abort
maxAttempts: 3
inputs:
- source: 's3://customer-bucket/testConfig.ps1'
destination: 'C:\testConfig.ps1'
- name: ValidateConfigScript
action: ExecutePowerShell
timeoutSeconds: 120
onFailure: Abort
maxAttempts: 3
inputs:
file: '{{validate.DownloadTestConfigScript.inputs[0].destination}}'
- name: Cleanup
action: DeleteFile
onFailure: Abort
maxAttempts: 3
inputs:
- path: '{{validate.DownloadTestConfigScript.inputs[0].destination}}'
- name: test
steps:
- name: DownloadTestConfigScript
action: S3Download
timeoutSeconds: 60
onFailure: Abort
maxAttempts: 3
inputs:
- source: 's3://customer-bucket/testConfig.ps1'
destination: 'C:\testConfig.ps1'
- name: ValidateConfigScript
action: ExecutePowerShell
timeoutSeconds: 120
onFailure: Abort
maxAttempts: 3
inputs:
file: '{{test.DownloadTestConfigScript.inputs[0].destination}}'
```
**Exemple 2 : installer le AWS CLI sur une instance Windows**
Voici un exemple de document qui installe le AWS CLI sur une instance Windows à l'aide du fichier d'installation.
```
name: InstallCLISetUp
description: Install &CLI; using the setup file
schemaVersion: 1.0
phases:
- name: build
steps:
- name: Download
action: S3Download
inputs:
- source: s3://aws-cli/AWSCLISetup.exe
destination: C:\Windows\temp\AWSCLISetup.exe
- name: Install
action: ExecuteBinary
onFailure: Continue
inputs:
path: '{{ build.Download.inputs[0].destination }}'
arguments:
- '/install'
- '/quiet'
- '/norestart'
- name: Delete
action: DeleteFile
inputs:
- path: '{{ build.Download.inputs[0].destination }}'
```
**Exemple 3 : installer le AWS CLI avec le programme d'installation MSI**
Voici un exemple de document qui installe le AWS CLI avec le programme d'installation MSI.
```
name: InstallCLIMSI
description: Install &CLI; using the MSI installer
schemaVersion: 1.0
phases:
- name: build
steps:
- name: Download
action: S3Download
inputs:
- source: s3://aws-cli/AWSCLI64PY3.msi
destination: C:\Windows\temp\AWSCLI64PY3.msi
- name: Install
action: ExecuteBinary
onFailure: Continue
inputs:
path: 'C:\Windows\System32\msiexec.exe'
arguments:
- '/i'
- '{{ build.Download.inputs[0].destination }}'
- '/quiet'
- '/norestart'
- name: Delete
action: DeleteFile
inputs:
- path: '{{ build.Download.inputs[0].destination }}'
```
------
#### [ macOS ]
**Exemple 1 : Exécuter un fichier binaire macOS personnalisé**
Voici un exemple de document qui télécharge et exécute un fichier binaire personnalisé sur une instance de macOS.
```
name: macOSBin
description: Download and run a binary file on macOS.
schemaVersion: 1.0
phases:
- name: build
steps:
- name: Download
action: S3Download
inputs:
- source: s3://amzn-s3-demo-source-bucket/myapplication
destination: /tmp/myapplication
- name: Enable
action: ExecuteBash
onFailure: Continue
inputs:
commands:
- 'chmod u+x {{ build.Download.inputs[0].destination }}'
- name: Install
action: ExecuteBinary
onFailure: Continue
inputs:
path: '{{ build.Download.inputs[0].destination }}'
arguments:
- '--install'
- name: Delete
action: DeleteFile
inputs:
- path: '{{ build.Download.inputs[0].destination }}'
```
------