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.

Syntaxe

constants:
  - <name>:
      type: <constant type>
      value: <constant value>

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 :

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.

Syntaxe

parameters:
  - <name>:
      type: <parameter type>
      default: <parameter value>
      description: <parameter description>

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 :

Exemples

Les exemples suivants montrent comment utiliser des paramètres dans votre document YAML :

Remplacer les paramètres lors de l'exécution

Vous pouvez utiliser l'--parametersoption AWS CLI avec une paire clé-valeur pour définir une valeur de paramètre lors de l'exécution.

Syntaxe

--parameters name1=value1,name2=value2...

Exemples

Les exemples suivants montrent comment utiliser des paramètres dans votre document YAML :

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 :

Pour plus d'informations sur le magasin de paramètres, voir AWS Systems Manager Parameter Store 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.

Autorisations IAM requises

Pour utiliser les paramètres de Systems Manager dans vos composants, votre rôle d'instance doit disposer de l'ssm:GetParameterautorisation 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 :

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_variableDans l'exemple suivant, le nom d'un paramètre SSM doit être l'un des suivants :

{{ 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 avecenv:. Par exemple, {{ env:MY_VAR }} résout la valeur de la variable d'MY_VARenvironnement 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.

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 avecaws: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.

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 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é aveccontext:. Par exemple, {{ context:accountId }} correspond à l'identifiant du AWS compte.

AWSTOE fournit les variables de contexte suivantes.

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 }}."