AWS CloudFormation
ユーザーガイド (API バージョン 2010-05-15)

動的な参照を使用してテンプレート値を指定する

動的な参照を使用すると、Systems Manager パラメータストアなどの他のサービスで格納および管理されている外部値をスタックテンプレートに指定するためのコンパクトで強力な方法が提供されます。動的な参照を使用すると、CloudFormation は、スタックオペレーションおよび変更セットオペレーション中に、必要に応じて指定された参照の値を取得します。

CloudFormation は現在、以下の動的な参照パターンをサポートしています。

  • AWS Systems Manager パラメータストアに格納されているプレーンテキスト値の ssm

  • AWS Systems Manager パラメータストアに格納されている安全な文字列の ssm-secure

  • AWS Secrets Manager に保存されている全体のシークレットまたは特定のシークレットの値に対する secretsmanager

動的な参照を使用する際の考慮事項

  • スタックテンプレートには最大 60 個の動的な参照を含めることができます。

  • AWS::Include や AWS::Serverless などのトランスフォームの場合、AWS CloudFormation はトランスフォームを呼び出す前に動的な参照を解決しません。むしろ、AWS CloudFormation は動的な参照のリテラル文字列をトランスフォームに渡します。動的な参照 (変換の結果として処理済みテンプレートに挿入されたものを含む) は、テンプレートを使用して変更セットを実行すると解決されます。

  • ssm-securesecretsmanager などの安全な値の動的な参照は、現在カスタムリソースではサポートされていません。

注記

最終値としてバックスラッシュ (\) を含む動的な参照は作成しないでください。AWS CloudFormation では、このような参照を解決することができないため、リソースエラーの原因になります。

スタックテンプレートでの動的な参照の指定

動的な参照は次のパターンに従います。

'{{resolve:service-name:reference-key}}'

service-name

値が保管および管理されるサービスを指定します。

必須。

現在、有効な値は以下のとおりです。

  • ssm: Systems Manager パラメータストアのプレーンテキストパラメータ。

  • ssm-secure: Systems Manager パラメータストアの安全な文字列パラメータ。

    注記

    現在、SecureString パラメータは、cn-north-1 および cn-northwest-1 リージョンの Systems Manager ではサポートされていません。

    詳細については、AWS Systems Manager ユーザーガイド の「AWS Systems Manager パラメータストア」を参照してください。

  • secretsmanager: AWS Secrets Manager のシークレット。

reference-key

リファレンスキー。動的な参照の種類によっては、参照キーは複数のセグメントで構成されることがあります。

必須。

SSM パラメータ

ssm の動的な参照を使用して、String 型または StringList 型の Systems Manager パラメータストアに格納されている値をテンプレートに格納します。

リファレンスパターン

SSM パラメータの場合、reference-key セグメントはパラメータ名とバージョン番号で構成されています。次のパターンを使用します。

'{{resolve:ssm:parameter-name:version}}'

参照は、parameter-name と version について、以下の正規表現パターンに従う必要があります。

'{{resolve:ssm:[a-zA-Z0-9_.-/]+:\\d+}}'

parameter-name

Systems Manager パラメータストア内のパラメータの名前。パラメータ名では大文字と小文字が区別されます

必須。

バージョン

使用するパラメータのバージョンを指定する整数。正確なバージョンを指定する必要があります。現在、AWS CloudFormation が最新バージョンのパラメータを使用するように指定することはできません。詳細については、AWS Systems Manager ユーザーガイド の「パラメータバージョンの使用」を参照してください。

必須。

次の例では、ssm の動的な参照を使用して、S3 バケットのアクセス制御を Systems Manager パラメータストアに格納されているパラメータ値に設定します。指定されているとおり、CloudFormation はスタック操作および変更セット操作にバージョン 2 の S3AccessControl パラメータを使用します。

JSON

"MyS3Bucket": { "Type": "AWS::S3::Bucket", "Properties": { "AccessControl": "{{resolve:ssm:S3AccessControl:2}}" } }

YAML

  MyS3Bucket:     Type: 'AWS::S3::Bucket'     Properties:       AccessControl: '{{resolve:ssm:S3AccessControl:2}}'

Systems Manager パラメータストアに格納されているパラメータを指定するには、指定されたパラメータに対して GetParameters を呼び出すためのアクセス権を持っている必要があります。詳細については、AWS Systems Manager ユーザーガイド の「Systems Manager パラメータへのアクセス制御」を参照してください。

ssm の動的な参照パターンを使用するときには以下の追加の考慮事項に注意してください。

  • 現在、CloudFormation はクロスアカウント SSM パラメータアクセスをサポートしていません。

  • カスタムリソースの場合、CloudFormation はリクエストをカスタムリソースに送信する前に ssm の動的な参照を解決します。詳細については、「カスタムリソース」を参照してください。

  • CloudFormation は、動的な参照でのパラメータラベルまたはパブリックパラメータの使用をサポートしません。

    パラメータラベルは、ユーザー定義のエイリアスであり、異なるバージョンのパラメータの管理に役立ちます。詳細については、AWS Systems Manager ユーザーガイド の「パラメータのラベリング」を参照してください。

    パブリックパラメータは、そのサービスで使用するために AWS のサービスによって提供され、AWS Systems Manager パラメータストアに格納されているパラメータです。パブリックパラメータの例については、Amazon Elastic Container Service Developer Guide の「Amazon ECS-Optimized AMI メタデータの取得」を参照してください。

SSM Secure String パラメータ

テンプレートに AWS Systems Manager SecureString タイプパラメータを指定するには、ssm-secure の動的な参照パターンを使用します。ssm-secure の動的な参照の場合、実際のパラメータ値が AWS CloudFormation に保存されることはありません。AWS CloudFormation は、スタックおよび変更セットの作成および更新オペレーション中にパラメータ値にアクセスします。現在、Secure String パラメータは、ssm-secure の動的な参照パターンをサポートするリソースプロパティに対してのみ使用できます。

Secure String パラメータは、セキュアな方法で保存および参照する必要がある機密データです。つまり、パスワードやライセンスキーなど、ユーザーがクリアテキストで変更または参照しないようにするデータです。Secure String の詳細については、AWS Systems Manager ユーザーガイド の「Secure String パラメータを使用する」を参照してください。

Secure String パラメータの値は CloudFormation に保存されず、API コールの結果でも返されません。

リファレンスパターン

ssm-secure の動的な参照の場合、reference-key セグメントはパラメータ名とバージョン番号で構成されています。次のパターンを使用します。

'{{resolve:ssm-secure:parameter-name:version}}'

参照は、parameter-name と version について、以下の正規表現パターンに従う必要があります。

'{{resolve:ssm-secure:[a-zA-Z0-9_.-/]+:\\d+}}'

parameter-name

Systems Manager パラメータストア内のパラメータの名前。パラメータ名では大文字と小文字が区別されます

必須。

バージョン

使用するパラメータのバージョンを指定する整数。正確なバージョンを指定する必要があります。現在、AWS CloudFormation が最新バージョンのパラメータを使用するように指定することはできません。詳細については、AWS Systems Manager ユーザーガイド の「パラメータバージョンの使用」を参照してください。

必須。

次の例では、ssm-secure の動的な参照を使用して、IAM ユーザーのパスワードを Systems Manager パラメータストアに格納されている安全な文字列に設定します。指定されているとおり、CloudFormation はスタック操作および変更セット操作にバージョン 10 の IAMUserPassword パラメータを使用します。

JSON

"MyIAMUser": { "Type": "AWS::IAM::User", "Properties": { "UserName": "MyUserName", "LoginProfile": { "Password": "{{resolve:ssm-secure:IAMUserPassword:10}}" } } }

YAML

  MyIAMUser:     Type: AWS::IAM::User     Properties:       UserName: 'MyUserName'       LoginProfile:         Password: '{{resolve:ssm-secure:IAMUserPassword:10}}'

ssm-secure の動的な参照パターンを使用するときには以下の追加の考慮事項に注意してください。

  • CloudFormation は、どの API 呼び出しでも Secure String の実際のパラメータ値を返しませんが、リテラルな動的参照を返します。

  • CloudFormation は、Secure String のプレーンテキストパラメータ名を含むリテラルな動的参照を格納します。

  • 変更セットの場合、CloudFormation はリテラルな動的参照文字列を比較します。ssm-secure 参照の実際の値の解決および比較はしません。

  • ssm-securesecretsmanager などの安全な値の動的な参照は、現在カスタムリソースではサポートされていません。

  • CloudFormation がスタック更新をロールバックする必要がある場合、以前に指定されたバージョンの Secure String パラメータが使用できなくなると、その更新ロールバックオペレーションは失敗します。

    • リソースをスキップするには CONTINUE_UPDATE_ROLLBACK を使用してください。

    • Systems Manager パラメータストアで Secure String パラメータを再作成し、パラメータのバージョンがテンプレートで使用されているバージョンに達するまでそれを更新します。その後、リソースをスキップせずに CONTINUE_UPDATE_ROLLBACK を使用します。

  • 現在、AWS CloudFormation はクロスアカウント SSM パラメータアクセスをサポートしていません。

  • CloudFormation は、動的な参照でのパラメータラベルまたはパブリックパラメータの使用をサポートしません。

    パラメータラベルは、ユーザー定義のエイリアスであり、異なるバージョンのパラメータの管理に役立ちます。詳細については、AWS Systems Manager ユーザーガイド の「パラメータのラベリング」を参照してください。

    パブリックパラメータは、そのサービスで使用するために AWS のサービスによって提供され、AWS Systems Manager パラメータストアに格納されているパラメータです。パブリックパラメータの例については、Amazon Elastic Container Service Developer Guide の「Amazon ECS-Optimized AMI メタデータの取得」を参照してください。

Secure String のための動的なパラメータパターンをサポートするリソース

ssm-secure の動的な参照パターンをサポートするリソースには、現在以下のものがあります。

Secrets Manager のシークレット

secretsmanager の動的な参照を使用し、AWS Secrets Manager に保存されている全体のシークレットまたはシークレット値をテンプレートで使用するために取得します。シークレットとは、データベース認証情報、パスワード、サードパーティーの API キーなどの任意のテキストです。Secrets Manager を使用すると、これらのシークレットへのアクセスを一元的に保存および制御できます。Secrets Manager を使用すると、コード内のハードコードされた認証情報 (パスワードを含む) を、Secrets Manager への API コールで置き換えて、プログラムでシークレットを取得することができます。詳細については、AWS Secrets Manager ユーザーガイド の「AWS Secrets Manager とは」を参照してください。

Secrets Manager に格納されているシークレットを指定するには、指定されたシークレットに対して GetSecretValue を呼び出すためのアクセス権を持っている必要があります。

重要

secretsmanager の動的な参照は、すべてのリソースプロパティで使用できます。secretsmanager の動的な参照を使用すると、Secrets Manager も CloudFormation も解決されたシークレットの値を記録または保持しなくなります。ただし、シークレット値は、それが使用されているリソースを持つサービスに表示されることがあります。シークレットデータが漏れるのを防ぐために、使用方法を確認する必要があります。

secretsmanager などの安全な値の動的な参照は、現在カスタムリソースではサポートされていません。

リファレンスパターン

Secrets Manager シークレットの場合、reference-key セグメントは、シークレット ID、シークレット値キー、バージョンステージ、およびバージョン ID を含む複数のセグメントで構成されています。次のパターンを使用します。

{{resolve:secretsmanager:secret-id:secret-string:json-key:version-stage:version-id}}

secret-id

シークレットの一意の識別子として機能する名前または Amazon リソースネーム (ARN) です。

AWS アカウントのシークレットにアクセスするには、シークレット名を指定するだけです。別の AWS アカウントのシークレットにアクセスするには、そのシークレットの完全な ARN を指定します。

必須。

secret-string

現在、サポートされている値は SecretString のみです。デフォルト: SecretString

json-key

値を取得するキーと値のペアのキー名を指定します。json-key を指定しない場合、CloudFormation はシークレットテキスト全体を取得します。

このセグメントにはコロン文字 (:) を含めることはできません。

version-stage

バージョンに添付されているステージングラベルによって取得するシークレットのバージョンを指定します。ステージングラベルは、ローテーション処理中にさまざまなバージョンを追跡するために使用されます。version-stage を使用する場合は、version-id を指定することはできません。バージョンステージもバージョン ID も指定しない場合、デフォルトでは AWSCURRENT バージョンステージ値でバージョンが取得されます。

このセグメントにはコロン文字 (:) を含めることはできません。

version-id

スタックオペレーションで使用したいシークレットのバージョンの固有 ID を指定します。version-id を指定した場合は、version-stage を指定しないでください。バージョンステージもバージョン ID も指定しない場合、デフォルトでは AWSCURRENT バージョンステージ値でバージョンが取得されます。

このセグメントにはコロン文字 (:) を含めることはできません。

次の例では、MyRDSSecret シークレットに格納されているユーザー名とパスワードの値を取得するために secret-name セグメントと json-key セグメントを使用しています。デフォルトでは、取得されたシークレットのバージョンは、バージョンステージ値が AWSCURRENT です。

JSON

{ "MyRDSInstance": { "Type": "AWS::RDS::DBInstance", "Properties": { "DBName": "MyRDSInstance", "AllocatedStorage": "20", "DBInstanceClass": "db.t2.micro", "Engine": "mysql", "MasterUsername": "{{resolve:secretsmanager:MyRDSSecret:SecretString:username}}", "MasterUserPassword": "{{resolve:secretsmanager:MyRDSSecret:SecretString:password}}" } } }

YAML

MyRDSInstance: Type: 'AWS::RDS::DBInstance' Properties: DBName: MyRDSInstance AllocatedStorage: '20' DBInstanceClass: db.t2.micro Engine: mysql MasterUsername: '{{resolve:secretsmanager:MyRDSSecret:SecretString:username}}' MasterUserPassword: '{{resolve:secretsmanager:MyRDSSecret:SecretString:password}}'

次のセグメントを指定すると、バージョンステージ値に AWSCURRENT を持つ MySecret シークレットのバージョンの SecretString フィールド全体が取得されます

  '{{resolve:secretsmanager:MySecret}}' or '{{resolve:secretsmanager:MySecret::::}}'

次のセグメントを指定すると、バージョンステージ値に AWSCURRENT を持つ MySecret SecretString のバージョンの password 値が取得されます

  '{{resolve:secretsmanager:MySecret:SecretString:password}}'

次のセグメントを指定すると、バージョン ID 値に EXAMPLE1-90ab-cdef-fedc-ba987EXAMPLE を持つ MySecret シークレットのバージョンの password 値が取得されます

  '{{resolve:secretsmanager:MySecret:SecretString:password:SecretString:EXAMPLE1-90ab-cdef-fedc-ba987EXAMPLE}}'

次のセグメントを指定すると、別の AWS アカウントからバージョンステージ値 AWSCURRENT を持つ MySecret シークレットのバージョンの SecretString 全体が取得されます。別の AWS アカウントのシークレットにアクセスするには、完全なシークレット ARN を指定する必要があります。

  '{{resolve:secretsmanager:arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecret-asd123}}'

次のセグメントを指定すると、別の AWS アカウントからバージョンステージ値 AWSCURRENT を持つ MySecret シークレットのバージョンの password 値が取得されます。別の AWS アカウントのシークレットにアクセスするには、完全なシークレット ARN を指定する必要があります。

  '{{resolve:secretsmanager:arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecret-asd123:SecretString:password}}'

次のセグメントを指定すると、別の AWS アカウントからバージョンステージ値 AWSPENDING を持つ MySecret シークレットのバージョンの password 値が取得されます。別の AWS アカウントのシークレットにアクセスするには、完全なシークレット ARN を指定する必要があります。

  '{{resolve:secretsmanager:arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecretName-asd123:SecretString:password:AWSPENDING}}'