翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # カスタムコンポーネントドキュメントでの変数の使用 変数を使用すると、アプリケーション全体で使用できるわかりやすい名前でデータにラベルを付けることができます。複雑なワークフローでは、シンプルで読み取り可能な形式でカスタム変数を定義し、 AWSTOE コンポーネントの YAML アプリケーションコンポーネントドキュメントで参照できます。 このセクションでは、構文、名前の制約、例など、YAML アプリケーション AWSTOE コンポーネントドキュメントでコンポーネントの変数を定義するのに役立つ情報を提供します。 ## 定数 定数は不変の変数で、一度定義すると変更したりオーバーライドしたりすることはできません。定数は、 AWSTOE ドキュメントの `constants`セクションの値を使用して定義できます。 **定数命名規則** + 名前は 3 文字以上 128 文字以下でなければならない。 + 名前には、英数字（a-z, A-Z, 0-9）、ダッシュ（-）、アンダースコア（\$1）のみを含めることができます。 + 名前は文書内で一意でなければならない。 + 名前は YAML 文字列として指定する必要があります。 **[Syntax]** (構文) ``` constants: - : type: value: ``` | キー名 | 必要 | 説明 | | --- | --- | --- | | `name` | はい | 定数の名前。ドキュメント内で一意である必要があります (他のパラメータ名や定数と同じであってはなりません)。 | | `value` | はい | 定数の値。 | | `type` | はい | 定数のタイプ。対応タイプはstring。 | **文書内の参照定数値** 次のように、YAML ドキュメント内のステップもしくはループ入力で定数を参照できます： + 定数参照は大文字と小文字を区別し、名前は正確に一致しなければならない。 + 名前は二重中括弧 `{{` *MyConstant* `}}` で囲む必要があります。 + 中括弧内にはスペースを入れてもかまいませんが、自動的に切り捨てられます。例えば、以下のリファレンスはすべて有効です。 `{{ MyConstant }}`, `{{ MyConstant}}`, `{{MyConstant }}`, `{{MyConstant}}` + YAML ドキュメント内の参照は文字列 (一重引用符または二重引用符で囲む) として指定する必要があります。 例えば、`- {{ MyConstant }}` は文字列として識別されないため無効です。 ただし、参照先 `- '{{ MyConstant }}'` と `- "{{ MyConstant }}"` はどちらも有効です。 **例** ステップ入力で参照される定数 ``` 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' ``` ループ入力で参照される定数 ``` 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 }} ``` ## パラメータ パラメータは、呼び出し元のアプリケーションがランタイムに提供できる設定を含む可変変数です。YAML ドキュメントの `Parameters` セクションでパラメータを定義できます。 **パラメータ命名規則** + 名前は 3 文字以上 128 文字以下でなければならない。 + 名前には、英数字（a-z, A-Z, 0-9）、ダッシュ（-）、アンダースコア（\$1）のみを含めることができます。 + 名前は文書内で一意でなければならない。 + 名前は YAML 文字列として指定する必要があります。 ### 構文 ``` parameters: - : type: default: description: ``` | キー名 | 必要 | 説明 | | --- | --- | --- | | `name` | はい | パラメータの名前。ドキュメント内で一意である必要があります (他のパラメータ名や定数と同じであってはなりません)。 | | `type` | はい | パラメータのデータ型。対応するタイプは `string` を含みます。 | | `default` | いいえ | パラメータのデフォルト値。 | | `description` | いいえ | パラメータを記述します。 | ### ドキュメント内の参照パラメータ値 次のように、YAML ドキュメント内のステップ入力またはループ入力でパラメータを参照できます。 + パラメータ参照は大文字と小文字が区別され、名前は完全に一致する必要があります。 + 名前は二重中括弧 `{{` *MyParameter* `}}` で囲む必要があります。 + 中括弧内にはスペースを入れてもかまいませんが、自動的に切り捨てられます。例えば、以下のリファレンスはすべて有効です。 `{{ MyParameter }}`, `{{ MyParameter}}`, `{{MyParameter }}`, `{{MyParameter}}` + YAML ドキュメント内の参照は文字列 (一重引用符または二重引用符で囲む) として指定する必要があります。 例えば、`- {{ MyParameter }}` は文字列として識別されないため無効です。 ただし、参照先 `- '{{ MyParameter }}'` と `- "{{ MyParameter }}"` はどちらも有効です。 **例** 次の例は YAML ドキュメントでのパラメータの使用方法を示しています。 + ステップ入力のパラメータを参照してください。 ``` 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' ``` + ループ入力のパラメータを参照する： ``` 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 }} ``` ### ランタイムにパラメータをオーバーライドする の `--parameters`オプションをキーと値のペア AWS CLI とともに使用して、実行時にパラメータ値を設定できます。 + パラメータのキーと値のペアを等号 (=) で区切って名前と値として指定します。 + 複数のパラメータはカンマで区切る必要があります。 + YAML コンポーネントドキュメントにないパラメータ名は無視されます。 + パラメータ名と値はどちらも必須です。 **重要** コンポーネントパラメータはプレーンテキストの値で、 AWS CloudTrailに記録されます。シークレットを保存するには、 AWS Secrets Manager または AWS Systems Manager Parameter Store を使用することをお勧めします。Secrets Manager の詳細については、AWS Secrets Manager ユーザーガイドの [Secrets Manager とは](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)を参照してください。 AWS Systems Manager パラメータストアについては、AWS Systems Manager ユーザーガイドの[AWS Systems Manager パラメータストア](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html)を参照。 #### 構文 ``` --parameters name1=value1,name2=value2... ``` | CLI オプション: | 必要 | 説明 | | --- | --- | --- | | --parameters *name*=*value*,... | いいえ | このオプションは、パラメータ名をキーとして、キーと値のペアのリストを取得します。 | **例** 次の例は YAML ドキュメントでのパラメータの使用方法を示しています。 + この `--parameter` オプションで指定されたパラメータのキーと値のペアは無効です。 ``` --parameters ntp-server= ``` + AWS CLIに `--parameter` オプションでパラメータのキーと値のペアを 1 つ設定します。 ``` --parameters ntp-server=ntp-server-windows-qe.us-east1.amazon.com ``` + AWS CLIの `--parameter` オプションで複数のパラメータのキーと値のペアを設定します。 ``` --parameters ntp-server=ntp-server.amazon.com,http-url=https://internal-us-east1.amazon.com ``` ## Systems Manager パラメータストアパラメータを使用する 変数の前に を付けることで、コンポーネントドキュメントで AWS Systems Manager Parameter Store パラメータ (SSM パラメータ) を参照できます`aws:ssm`。例えば、 `{{ aws:ssm:/my/param }}` は SSM パラメータ の値に解決されます`/my/param`。 この機能は、次の SSM パラメータタイプをサポートしています。 + 文字列 – AWSTOE 文字列タイプにマッピングされます。 + StringList – タイプにマッピングします AWSTOE `stringList`。 + SecureString – AWSTOE 文字列タイプにマッピングします。 パラメータストアの詳細については、 *AWS Systems Manager ユーザーガイド*の[AWS Systems Manager 「パラメータストア](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html)」を参照してください。 SSM パラメータ を使用してシー AWS Secrets Manager クレットを参照することもできます`SecureString`。例: `{{ aws:ssm:/aws/reference/secretsmanager/test/test-secret }}`。詳細については、[「Parameter Store パラメータからのシークレットの参照 AWS Secrets Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/integration-ps-secretsmanager.html)」を参照してください。 **重要** Image Builder は、ログから`SecureString`パラメータ解決を除外します。ただし、コンポーネントドキュメントで発行されたコマンドによって機密情報がログに記録されないようにする責任もあります。たとえば、安全な文字列で `echo` コマンドを使用すると、コマンドはプレーンテキストの値をログに書き込みます。 ### 必要な IAM 許可 コンポーネントで Systems Manager パラメータを使用するには、インスタンスロールにパラメータリソース ARN のアクセス`ssm:GetParameter`許可が必要です。例えば、次のようになります。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "ssm:GetParameter", "Resource": "arn:aws:ssm:*:111122223333:parameter/ImageBuilder-*" } ] } ``` ------ 暗号化された値にアクセスするには、次のアクセス許可も必要です。 + カスタマーマネージドで暗号化された`SecureString`パラメータまたは AWS Secrets Manager 値`kms:Decrypt`に を追加します AWS KMS key。 + Secrets Manager シークレットを参照`secretsmanager:GetSecretValue`する場合は、 を追加します。 ### コンポーネントドキュメントで SSM パラメータを参照する 次の例は、コンポーネント内の Systems Manager パラメータの Systems Manager パラメータストアパラメータを参照する方法を示しています。 ``` 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 }}." ``` ### SSM パラメータの動的ランタイム変数解決 AWSTOE には、変数参照内で実行時に値を操作または変換するために使用できる以下の組み込み関数が用意されています。 #### 関数の解決 `resolve` 関数は、別の変数参照内の変数参照を解決し、動的変数名参照を可能にします。これは、パラメータパスの一部が可変で、ドキュメントパラメータとして渡される可能性がある SSM パラメータを使用する場合に便利です。 `resolve` 関数は、SSM パラメータの名前部分の動的解決のみをサポートします。 ##### 構文 `dynamic_variable` 次の例では、 は SSM パラメータの名前を表し、次のいずれかである必要があります。 + SSM パラメータリファレンス (例: `aws:ssm:/my/param`) + コンポーネントドキュメントのパラメータリファレンス (例: `parameter-name`) ``` {{ aws:ssm:resolve(dynamic_variable) }} ``` ##### 例: 実行時に SSM パラメータを解決する 次の例は、YAML コンポーネントドキュメントで `resolve`関数を使用する方法を示しています。 ``` 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) }}" ```