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 des variables dans votre document de composant personnalisé Les variables permettent d'étiqueter les données avec des noms significatifs qui peuvent être utilisés dans l'ensemble d'une application. Vous pouvez définir des variables personnalisées avec des formats simples et lisibles pour les flux de travail complexes, et les référencer dans le document du composant d'application YAML correspondant à un AWSTOE composant. Cette section fournit des informations pour vous aider à définir les variables de votre AWSTOE composant dans le document du composant d'application YAML, notamment la syntaxe, les contraintes de nom et des exemples. ## Constantes Les constantes sont des variables immuables qui ne peuvent pas être modifiées ou remplacées une fois définies. Les constantes peuvent être définies à l'aide des valeurs figurant dans la `constants` section d'un AWSTOE document. **Règles pour les noms de constantes** + Le nom doit comporter entre 3 et 128 caractères. + Le nom ne peut contenir que des caractères alphanumériques (a-z, 0-9) A-Z, des tirets (-) ou des traits de soulignement (\_). + Le nom doit être unique dans le document. + Le nom doit être spécifié sous forme de chaîne YAML. **Syntaxe** ``` constants: - : type: value: ``` | Nom de la touche | Obligatoire | Description | | --- | --- | --- | | `name` | Oui | Nom de la constante. Doit être unique pour le document (il ne doit pas être identique aux autres noms de paramètres ou constantes). | | `value` | Oui | Valeur de la constante. | | `type` | Oui | Type de constante. Le type pris en charge eststring. | **Valeurs constantes de référence dans un document** Vous pouvez référencer des constantes dans les entrées d'étape ou de boucle dans votre document YAML, comme suit : + Les références constantes distinguent les majuscules et minuscules, et le nom doit correspondre exactement. + Le nom doit être placé entre accolades `{{` {{MyConstant}} `}}` doubles. + Les espaces sont autorisés à l'intérieur des bretelles et sont automatiquement découpés. Par exemple, toutes les références suivantes sont valides : `{{ {{MyConstant}} }}`, `{{ {{MyConstant}}}}`, `{{{{MyConstant}} }}`, `{{{{MyConstant}}}}` + La référence dans le document YAML doit être spécifiée sous forme de chaîne (entre guillemets simples ou doubles). Par exemple : n'`- {{ {{MyConstant}} }}`est pas valide, car il n'est pas identifié comme une chaîne. Toutefois, les références suivantes sont toutes deux valides : `- '{{ {{MyConstant}} }}'` et`- "{{ {{MyConstant}} }}"`. **Exemples** Constante référencée dans les entrées d'étape ``` name: Download AWS CLI version 2 schemaVersion: 1.0 constants: - Source: type: string value: https://awscli.amazonaws.com/AWSCLIV2.msi phases: - name: build steps: - name: Download action: WebDownload inputs: - source: '{{ Source }}' destination: 'C:\Windows\Temp\AWSCLIV2.msi' ``` Constante référencée dans les entrées de boucle ``` name: PingHosts schemaVersion: 1.0 constants: - Hosts: type: string value: 127.0.0.1,amazon.com phases: - name: build steps: - name: Ping action: ExecuteBash loop: forEach: list: '{{ Hosts }}' delimiter: ',' inputs: commands: - ping -c 4 {{ loop.value }} ``` ## Parameters Les paramètres sont des variables mutables, avec des paramètres que l'application appelante peut fournir au moment de l'exécution. Vous pouvez définir des paramètres dans la `Parameters` section du document YAML. **Règles relatives aux noms de paramètres** + Le nom doit comporter entre 3 et 128 caractères. + Le nom ne peut contenir que des caractères alphanumériques (a-z, 0-9) A-Z, des tirets (-) ou des traits de soulignement (\_). + Le nom doit être unique dans le document. + Le nom doit être spécifié sous forme de chaîne YAML. ### Syntaxe ``` parameters: - : type: default: description: ``` | Nom de la touche | Obligatoire | Description | | --- | --- | --- | | `name` | Oui | Nom du paramètre. Doit être unique pour le document (il ne doit pas être identique aux autres noms de paramètres ou constantes). | | `type` | Oui | Type de données du paramètre. Les types pris en charge incluent :`string`. | | `default` | Non | La valeur par défaut du paramètre. | | `description` | Non | Décrit le paramètre. | ### Valeurs des paramètres de référence dans un document Vous pouvez référencer des paramètres dans des entrées par étapes ou en boucle dans votre document YAML, comme suit : + Les références aux paramètres distinguent les majuscules et minuscules, et le nom doit correspondre exactement. + Le nom doit être placé entre accolades `{{` {{MyParameter}} `}}` doubles. + Les espaces sont autorisés à l'intérieur des bretelles et sont automatiquement découpés. Par exemple, toutes les références suivantes sont valides : `{{ {{MyParameter}} }}`, `{{ {{MyParameter}}}}`, `{{{{MyParameter}} }}`, `{{{{MyParameter}}}}` + La référence dans le document YAML doit être spécifiée sous forme de chaîne (entre guillemets simples ou doubles). Par exemple : n'`- {{ {{MyParameter}} }}`est pas valide, car il n'est pas identifié comme une chaîne. Toutefois, les références suivantes sont toutes deux valides : `- '{{ {{MyParameter}} }}'` et`- "{{ {{MyParameter}} }}"`. **Exemples** Les exemples suivants montrent comment utiliser des paramètres dans votre document YAML : + Référez-vous à un paramètre dans les entrées d'étape : ``` name: Download AWS CLI version 2 schemaVersion: 1.0 parameters: - Source: type: string default: 'https://awscli.amazonaws.com/AWSCLIV2.msi' description: The AWS CLI installer source URL. phases: - name: build steps: - name: Download action: WebDownload inputs: - source: '{{ Source }}' destination: 'C:\Windows\Temp\AWSCLIV2.msi' ``` + Référez-vous à un paramètre dans les entrées de boucle : ``` name: PingHosts schemaVersion: 1.0 parameters: - Hosts: type: string default: 127.0.0.1,amazon.com description: A comma separated list of hosts to ping. phases: - name: build steps: - name: Ping action: ExecuteBash loop: forEach: list: '{{ Hosts }}' delimiter: ',' inputs: commands: - ping -c 4 {{ loop.value }} ``` ### Remplacer les paramètres lors de l'exécution Vous pouvez utiliser l'`--parameters`option AWS CLI avec une paire clé-valeur pour définir une valeur de paramètre lors de l'exécution. + Spécifiez la paire clé-valeur du paramètre sous forme de nom et de valeur, séparés par un signe égal (=). + Les paramètres multiples doivent être séparés par une virgule. + Les noms de paramètres introuvables dans le document du composant YAML sont ignorés. + Le nom et la valeur du paramètre sont tous deux obligatoires. **Important** Les paramètres des composants sont des valeurs en texte brut et sont connectés AWS CloudTrail. Nous vous recommandons d'utiliser AWS Secrets Manager le AWS Systems Manager Parameter Store pour stocker vos secrets. Pour plus d'informations sur Secrets Manager, voir [Qu'est-ce que Secrets Manager ?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) dans le *guide de AWS Secrets Manager l'utilisateur*. Pour plus d'informations sur AWS Systems Manager Parameter Store, voir [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) dans le *guide de AWS Systems Manager l'utilisateur*. #### Syntaxe ``` --parameters {{name1}}={{value1}},{{name2}}={{value2}}... ``` | Option CLI | Obligatoire | Description | | --- | --- | --- | | --paramètres {{name}} ={{value}},... | Non | Cette option prend une liste de paires clé-valeur, avec le nom du paramètre comme clé. | **Exemples** Les exemples suivants montrent comment utiliser des paramètres dans votre document YAML : + La paire clé-valeur du paramètre spécifiée dans cette `--parameter` option n'est pas valide : ``` --parameters ntp-server= ``` + Définissez une paire clé-valeur de paramètre avec l'`--parameter`option dans le champ : AWS CLI ``` --parameters ntp-server=ntp-server-windows-qe.us-east1.amazon.com ``` + Définissez plusieurs paires clé-valeur de paramètres à l'aide de l'`--parameter`option suivante : AWS CLI ``` --parameters ntp-server=ntp-server.amazon.com,http-url=https://internal-us-east1.amazon.com ``` ## Utiliser les paramètres du magasin de paramètres de Systems Manager Vous pouvez référencer les AWS Systems Manager paramètres du magasin de paramètres (paramètres SSM) dans les documents de vos composants en préfixant les variables par. `aws:ssm` Par exemple, `{{ aws:ssm:/my/param }}`se résout à la valeur du paramètre `/my/param` SSM. Cette fonctionnalité prend en charge les types de paramètres SSM suivants : + Chaîne — Correspond au type de AWSTOE chaîne. + StringList — Correspond au AWSTOE `stringList` type. + SecureString — Correspond au type de AWSTOE chaîne. Pour plus d'informations sur le magasin de paramètres, voir [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) dans le *guide de AWS Systems Manager l'utilisateur*. Vous pouvez également référencer des AWS Secrets Manager secrets à l'aide d'un paramètre `SecureString` SSM. Par exemple : `{{ aws:ssm:/aws/reference/secretsmanager/test/test-secret }}`. Pour plus d'informations, consultez la section [Référencement de AWS Secrets Manager secrets à partir des paramètres du Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/integration-ps-secretsmanager.html). **Important** Image Builder exclut la résolution des `SecureString` paramètres de ses journaux. Cependant, vous devez également vous assurer que les informations sensibles ne sont pas enregistrées par le biais des commandes émises dans le document du composant. Par exemple, si vous utilisez la `echo` commande avec une chaîne sécurisée, la commande écrit une valeur en texte brut dans le journal. ### Autorisations IAM requises Pour utiliser les paramètres de Systems Manager dans vos composants, votre rôle d'instance doit disposer de l'`ssm:GetParameter`autorisation pour l'ARN de la ressource de paramètres. Par exemple : ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "ssm:GetParameter", "Resource": "arn:aws:ssm:*:{{111122223333}}:parameter/ImageBuilder-*" } ] } ``` ------ Pour accéder aux valeurs chiffrées, vous devez également disposer des autorisations suivantes : + Ajoutez `kms:Decrypt` des `SecureString` paramètres ou AWS Secrets Manager des valeurs chiffrés gérés par un client AWS KMS key. + Ajoutez `secretsmanager:GetSecretValue` si vous faites référence à un secret du Secrets Manager. ### Référencer un paramètre SSM dans un document de composant L'exemple suivant montre comment faire référence à un paramètre de magasin de paramètres de Systems Manager dans un composant : ``` name: UseSSMParameterVariable description: This is a sample component document that prints out the value of an SSM Parameter. Never do this for a SecureString parameter. schemaVersion: 1.0 phases: - name: verify steps: - name: EchoParameterValue action: ExecuteBash inputs: commands: - echo "Log SSM parameter name: {{/my/test/param}}, value {{ aws:ssm:{{/my/test/param}} }}." ``` ### Résolution des variables d'exécution dynamiques pour les paramètres SSM AWSTOE fournit la fonction intégrée suivante que vous pouvez utiliser dans les références de variables pour manipuler ou transformer des valeurs lors de l'exécution. #### fonction de résolution La `resolve` fonction résout une référence de variable à l'intérieur d'une autre référence de variable, permettant le référencement dynamique des noms de variables. Cela est utile lorsque vous travaillez avec des paramètres SSM où une partie du chemin du paramètre peut être variable et transmise en tant que paramètre de document. La `resolve` fonction prend uniquement en charge la résolution dynamique de la partie du nom d'un paramètre SSM. ##### Syntaxe `dynamic_variable`Dans l'exemple suivant, le nom d'un paramètre SSM doit être l'un des suivants : + Une référence de paramètre SSM (par exemple,`aws:ssm:{{/my/param}}`) + Une référence aux paramètres d'un document de composant (par exemple,`{{parameter-name}}`) ``` {{ aws:ssm:resolve({{dynamic_variable}}) }} ``` ##### Exemple : résolution d'un paramètre SSM lors de l'exécution L'exemple suivant montre comment utiliser la `resolve` fonction dans un document de composant YAML : ``` name: SsmParameterTest description: This component verifies an SSM parameter variable reference with the echo command. schemaVersion: 1.0 parameters: - parameter-name: type: string description: "test" phases: - name: validate steps: - name: PrintDynamicVariable action: ExecuteBash inputs: commands: - echo "{{ aws:ssm:resolve(parameter-name) }}" ``` ## Utiliser des variables d'environnement AWSTOE peut résoudre les variables d'environnement du système d'exploitation définies sur l'instance de build ou de test. Pour référencer une variable d'environnement, préfixez le nom de la variable avec`env:`. Par exemple, `{{ env:{{MY_VAR}} }}` résout la valeur de la variable d'`MY_VAR`environnement sur l'instance. AWSTOE correspond exactement aux noms des variables d'environnement. Un nom peut contenir tous les caractères valides pour le système d'exploitation, notamment des points, des espaces et des parenthèses. Par exemple, `{{ env:ProgramFiles(x86) }}` est une référence valide sous Windows. L'exemple suivant montre comment référencer une variable d'environnement dans un composant : ``` name: UseEnvironmentVariable description: This sample component prints out the value of an environment variable. schemaVersion: 1.0 phases: - name: build steps: - name: EchoEnvironmentVariable action: ExecuteBash inputs: commands: - echo "The value of SOME_VAR is {{ env:{{SOME_VAR}} }}." ``` ### Variables d'environnement fournies par Image Builder Lorsqu'Image Builder exécute un composant sur une instance de build ou de test, il définit des variables d'environnement qui décrivent la génération d'image actuelle. Vos composants lisent ces valeurs avec le préfixe de AWSTOE `env:` variable décrit plus haut dans cette rubrique. Image Builder fournit les variables d'environnement suivantes. | Nom | Description | | --- | --- | | `IMAGE_WORKFLOW_EXECUTION_ID` | ID de l'exécution du flux de travail pour la génération d'image en cours. | | `IMAGE_STEP_EXECUTION_ID` | ID de l'exécution de l'étape du flux de travail qui exécute le composant. | | `IMAGE_BUILD_VERSION_ARN` | Le nom de ressource Amazon (ARN) de la version de création d'image créée par Image Builder. | | `IMAGE_PIPELINE_ARN` | L'ARN du pipeline d'images. Cette valeur est une chaîne vide lorsque le build ne s'exécute pas à partir d'un pipeline. | | `IMAGE_PHASE` | L'étape de création de l'image en `BUILDING` cours : pendant la phase de génération ou `TESTING` pendant la phase de test.
Cette étape est distincte des phases du document AWSTOE composant (`build``validate`, et`test`). La `IMAGE_PHASE` valeur ne prend jamais le nom de phase d'un document de composant. | | `IMAGE_VERSION` | Version sémantique de l'image (par exemple,`2.1.1`). | | `IMAGE_BUILD_VERSION` | Le numéro de version de compilation de l'image (par exemple,`1`). | L'exemple suivant montre comment lire les variables d'environnement Image Builder dans un composant : ``` name: UseImageBuilderEnvironmentVariables description: This sample component prints out Image Builder environment variable values. schemaVersion: 1.0 phases: - name: build steps: - name: EchoImageBuildValues action: ExecuteBash inputs: commands: - echo "Image phase: {{ env:IMAGE_PHASE }}." - echo "Image build version ARN: {{ env:IMAGE_BUILD_VERSION_ARN }}." ``` ## Utiliser des variables de métadonnées d'instance (IMDS) AWSTOE peut résoudre les valeurs issues du service de métadonnées d'instance Amazon EC2 (IMDS) lors de la création ou de l'instance de test. Pour référencer une valeur de métadonnées, préfixez le chemin des métadonnées avec`aws:imds:`. Le chemin est relatif à la `meta-data/` catégorie de métadonnées de l'instance. Par exemple, `{{ aws:imds:instance-id }}` résout l'ID de l'instance. La référence se `{{ aws:imds:placement/region }}` résout en Région AWS. **Chemins de métadonnées non pris en charge** AWSTOE ne prend pas en charge les chemins de `identity-credentials/` métadonnées `iam/` et. Ces chemins renvoient des données d'identification sensibles. AWSTOE rejette les références à ces derniers lorsqu'il valide le document du composant. Pour plus d'informations sur les métadonnées d'instance, consultez la section [Utiliser les métadonnées d'instance pour gérer votre instance EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) dans le guide de l'*utilisateur Amazon EC2*. L'exemple suivant montre comment référencer une valeur IMDS dans un composant : ``` name: UseInstanceMetadataVariable description: This sample component prints out the instance ID from IMDS. schemaVersion: 1.0 phases: - name: build steps: - name: EchoInstanceId action: ExecuteBash inputs: commands: - echo "The instance ID is {{ aws:imds:instance-id }}." ``` ## Utiliser des variables de contexte AWSTOE fournit des variables de contexte qui décrivent l'exécution et l'instance en cours. Pour référencer une variable de contexte, préfixez la clé avec`context:`. Par exemple, `{{ context:accountId }}` correspond à l'identifiant du AWS compte. AWSTOE fournit les variables de contexte suivantes. | Clé | Description | | --- | --- | | `executionId` | ID de l' AWSTOE exécution en cours. | | `accountId` | L'ID du AWS compte sur lequel l'instance est exécutée. | | `region` | Le dans Région AWS lequel l'instance s'exécute. | | `osPlatform` | La plate-forme du système d'exploitation de l'instance (par exemple, `linux` ou`windows`). | | `osName` | Le nom du système d'exploitation (par exemple, `Amazon Linux` ou`Ubuntu`). Sous Linux, AWSTOE lit cette valeur à partir de`/etc/os-release`. | | `osVersion` | Version du système d'exploitation (par exemple,`2023`). Sous Linux, AWSTOE lit cette valeur à partir de`/etc/os-release`. Sous Windows et macOS, cette valeur est une chaîne vide. | | `date` | La date actuelle en UTC, au `YYYY-MM-DD` format (par exemple,`2026-06-15`). | | `dateTime` | La date et l'heure actuelles en UTC, au format RFC 3339 (par exemple,`2026-06-15T10:30:00Z`). | | `uuid` | Un UUID de version 4 généré aléatoirement. | | `hostname` | Le nom d'hôte de l'instance. | | `phase` | Nom de la phase en cours d'exécution. | | `step` | Nom de l'étape en cours d'exécution. | **Note** Pour obtenir l'ID d'instance, utilisez la variable IMDS `{{ aws:imds:instance-id }}` plutôt qu'une variable de contexte. L'exemple suivant montre comment référencer des variables de contexte dans un composant : ``` name: UseContextVariables description: This sample component prints out context variable values. schemaVersion: 1.0 phases: - name: build steps: - name: EchoContextValues action: ExecuteBash inputs: commands: - echo "Account: {{ context:accountId }}, OS: {{ context:osName }}." ```