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

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

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

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

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

• AWS Secrets Manager に格納されている全体のシークレットまたはシークレットの値に対する secretsmanager。

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

以下は、動的参照を使用する際に考慮すべき考慮事項です。

重要

リソースのプライマリ識別子の一部であるリソースプロパティには、動的参照や機密データを含めないことを強くお勧めします。

プライマリリソース識別子を形成するプロパティに動的参照パラメータが含まれている場合、CloudFormation はプライマリリソース識別子に実際の平文値を使用する場合があります。このリソース ID は、派生した出力または送信先に表示されます。

リソースタイプのプライマリ識別子を構成するリソースプロパティを確認するには、そのリソースの「リソースリファレンスドキュメント」を参照してください。[Return values] (戻り値) セクションの Ref 関数の戻り値は、リソースタイプのプライマリ識別子を構成するリソースプロパティを表します。

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

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

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

注記

最終値としてバックスラッシュ (\) を持つ動的参照を作成しないでください。AWS CloudFormation はそれらの参照を解決できないため、リソース障害が発生します。

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

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

'{{resolve:service-name:reference-key}}'-または-'{{resolve:ssm:[a-zA-Z0-9_.\-/]+(:\d+)?}}'

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: 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 パラメータストア内のパラメータの名前。パラメータ名では大文字と小文字が区別されます

必須。

バージョン

使用するパラメータのバージョンを指定する整数。正確なバージョンを指定しない場合、CloudFormation は、スタックを作成または更新するたびに最新バージョンのパラメータを使用します。詳細については、「AWS Systems Manager ユーザーガイド」の「Working with parameter versions」(パラメータバージョンの使用) を参照してください。

オプション。

例

次の例では、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 ユーザーガイド」の「Controlling access to Systems Manager parameters」(Systems Manager パラメータへのアクセス制御) を参照してください。

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

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

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

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

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

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

• CloudFormation は現在、動的参照でのドリフト検出をサポートしていません。パラメータのバージョンを指定していない ssm 動的参照の場合、SSM でパラメータのバージョンを更新する際は、最新バージョンのパラメータに変更するために、ssm 動的参照を含むすべてのスタックでスタックの更新オペレーションも実施することをお勧めします。

• スタック操作で使用する ssm 動的リファレンスのバージョンを確認するには、スタック操作の変更セットを作成します。次に、[Template] (テンプレート) タブで [review the processed template] (処理されたテンプレートを確認) します。

• バージョンのない SSM パラメータは、パラメータブロックではサポートされていないので、代わりに SSM パラメータタイプを使用します。SSM パラメータを使用する場合は、AWS CloudFormation で使用する Systems Manager パラメータのバージョンを指定する必要があります。

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 ユーザーガイド」の「Use secure string parameters」(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 ユーザーガイド」の「Working with parameter versions」(パラメータバージョンの使用) を参照してください。

オプション。

例

次の例では、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-secure や secretsmanager などの安全な値の動的な参照は、現在カスタムリソースではサポートされていません。

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

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

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

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

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

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

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

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

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

リソース	プロパティタイプ	プロパティ
AWS::DirectoryService::MicrosoftAD		Password
AWS::DirectoryService::SimpleAD		Password
AWS::ElastiCache::ReplicationGroup		AuthToken
AWS::IAM::User	LoginProfile	Password
AWS::KinesisFirehose::DeliveryStream	RedshiftDestinationConfiguration	Password
AWS::OpsWorks::App	ソース	Password
AWS::OpsWorks::Stack	CustomCookbooksSource	Password
AWS::OpsWorks::Stack	RdsDbInstances	DbPassword
AWS::RDS::DBCluster		MasterUserPassword
AWS::RDS::DBInstance		MasterUserPassword
AWS::Redshift::Cluster		MasterUserPassword

Secrets Manager のシークレット

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

Secrets Manager のシークレットに動的参照を使用する際の重要な考慮事項

動的参照を使用してスタックテンプレートで Secrets Manager のシークレットを指定する場合は、次の重要なセキュリティ上の考慮事項を検討する必要があります。

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

• Secrets Manager でシークレットを更新しても、CloudFormation のシークレットは自動的に更新されません。CloudFormation で secretsmanager 動的な参照を更新するには、動的な参照を含むリソースを更新するか、リソースの別のプロパティを更新することによって、secretsmanager 動的な参照を含むリソースを更新するスタック更新を実行する必要があります。

  たとえば、テンプレートで、AWS::RDS::DBInstance リソースの MasterPassword プロパティを secretsmanager 動的な参照として指定し、テンプレートからスタックを作成するとします。後で Secrets Manager でそのシークレットの値を更新しますが、テンプレートの AWS::RDS::DBInstance リソースは更新しません。この場合、スタックの更新を実行しても、MasterPassword プロパティのシークレット値は更新されず、以前のシークレット値のままになります。

  また、Secrets Manager を使用して、セキュリティで保護されたサービスまたはデータベースのシークレットを自動的にローテーションすることを検討してください。詳細については、「AWS Secrets Manager シークレットのローテーション」を参照してください。

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

必要な許可

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

リファレンスパターン

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

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

シークレットID

シークレット名またはシークレット ARN。

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

必須。

secret-string

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

json-key

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

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

version-stage

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

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

version-id

使用したいシークレットのバージョンの固有識別子を指定します。version-id を指定した場合は、version-stage を指定しないでください。version-stage または version-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}}'

次のセグメントを指定すると、MySecret の SecretString が取得されます。

'{{resolve:secretsmanager:MySecret}}'、または '{{resolve:secretsmanager:MySecret::::}}'

次のセグメントを指定すると、MySecret の password 値が取得されます。

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

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

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

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

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

次のセグメントを指定すると、MySecret の AWSPREVIOUS バージョンの password 値が取得されます。

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