動的な参照を使用する際の考慮事項スタックテンプレートでの動的な参照の指定 Systems Manager パラメータ Systems Manager Secure String パラメータ Secrets Manager のシークレット

動的参照を使用して他のサービスに格納されている値を指定する

動的参照には、他のサービスに格納および管理されている外部値を指定し、Infrastructure as Code (IaC) テンプレートから機密情報を切り離すことができる便利な方法があります。CloudFormation は、スタックオペレーションおよび変更セットオペレーション中に、必要に応じて指定された参照の値を取得します。

次のタイプの動的参照を指定することができます。

AWS Systems Manager パラメータストアに格納されているプレーンテキスト値。
AWS Systems Manager パラメータストアに格納されている安全な文字列。
AWS Secrets Manager に格納されている全体のシークレットまたはシークレットの値。

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

動的参照を使用する際の考慮事項は次のとおりです。

重要

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

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

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

スタックテンプレートには最大 60 個の動的な参照を含めることができます。
AWS::Include および AWS::Serverless のような変換の場合、CloudFormation は変換を呼び出す前に動的参照を解決しません。むしろ、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

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

必須。

Systems Manager パラメータ

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

リファレンスパターン

Systems Manager パラメータの場合、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 はクロスアカウント Systems Manager パラメータアクセスをサポートしていません。
カスタムリソースの場合、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 動的参照の場合、Systems Manager でパラメータのバージョンを更新する際は、最新バージョンのパラメータに変更するために、ssm 動的参照を含むすべてのスタックでスタックの更新オペレーションも実施することをお勧めします。
スタック操作で使用する ssm 動的リファレンスのバージョンを確認するには、スタック操作の変更セットを作成します。次に、[Template] (テンプレート) タブで [review the processed template] (処理されたテンプレートを確認) します。
CloudFormation では、動的参照を使用してテンプレートの Parameters セクションでパラメータ値を指定することができます。ただし、Parameters セクションのパラメータ値を指定する ssm または ssm-secure の動的なパラメータパターンを使用する場合は、使用する CloudFormation の Systems Manager パラメータのバージョンを指定する必要があります。バージョンのない Systems Manager パラメータは、Parameters セクションではサポートされていません。または、Systems Manager パラメータタイプを使用して、CloudFormation が代わりに最新バージョンを取得できるようにします。詳細については、「Systems Manager パラメータタイプ」を参照してください。

Systems Manager Secure String パラメータ

テンプレートに AWS Systems Manager SecureString タイプパラメータを指定するには、ssm-secure の動的な参照パターンを使用します。ssm-secure 動的参照の場合、CloudFormation は実際のパラメータ値を格納しません。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 を使用します。
現在、CloudFormation はクロスアカウント Systems Manager パラメータアクセスをサポートしていません。
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 ユーザーガイド』の「What is 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}}'

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

AWS::Lambda::Function 書き込み専用プロパティ

デプロイされたスタックから情報をエクスポートする