Flux de travail documentaire sur les composants Journalisation des composants Chainage des entrées et des sorties Schéma du document et définitions Exemples de schémas de documents

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.

Rubriques

Flux de travail documentaire sur les composants
Journalisation des composants
Chainage des entrées et des sorties
Schéma du document et définitions
Exemples de schémas de documents
Utiliser des variables dans votre document de composant personnalisé
Utiliser des constructions en boucle dans AWSTOE

Flux de travail documentaire sur les 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, les valeurs d'entrée/sortie et des exemples, voir. Modules d'action pris en charge par le gestionnaire de AWSTOE composants

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 :

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 : /var/lib/amazon/toe/
- Windows : $env:ProgramFiles\Amazon\TaskOrchestratorAndExecutor\
Préfixe de fichier — Il s'agit d'un préfixe standard utilisé pour tous les composants : « »TOE_.
Durée d'exécution : il s'agit d'un horodatage au format YYYY-MM-DD_HH-MM-SS_UTC-0.
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 }}

{{ 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 relatives au 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.	Chaîne	Non
description	Description du document	Chaîne	Non
schemaVersion	Version du schéma du document, actuellement 1.0.	Chaîne	Oui
phases	Une liste des phases avec leurs étapes.	Liste	Oui

Les définitions du schéma d'une phase sont les suivantes.

Champ	Description	Type	Obligatoire
name	Nom de la phase.	Chaîne	Oui
steps	Liste des étapes de la phase.	Liste	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.	Chaîne
action	Mot-clé relatif au module qui exécute l'étape.	Chaîne
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 : Abandonner — Échoue l'étape après le nombre maximum de tentatives et arrête l'exécution. Définit le statut de la phase et du document à`Failed`. Continuer — Échoue l'étape après le nombre maximum de tentatives et continue d'exécuter les étapes restantes. Définit le statut de la phase et du document à`Failed`. Ignorer : définit l'étape `IgnoredFailure` après le nombre maximum de tentatives infructueuses et continue à exécuter les étapes restantes. Définit le statut de la phase et du document à`SuccessWithIgnoredFailure`.	Chaîne	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 schémas de documents

Voici un exemple de schéma de document pour installer toutes les mises à jour Windows disponibles, exécuter un script de configuration, valider les modifications avant la création de l'AMI et tester 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}}'

Voici un exemple de schéma de document pour télécharger et exécuter un fichier binaire Linux personnalisé.


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://<replaceable>mybucket</replaceable>/<replaceable>myapplication</replaceable>
            destination: /tmp/<replaceable>myapplication</replaceable>
      - 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 }}'

Voici un exemple de schéma de document pour installer 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 }}'

Voici un exemple de schéma de document pour installer le à l' AWS CLI aide du 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 }}'

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Vérifier la signature

Utiliser des variables