AWS CloudFormation マクロを使用したテンプレートのカスタム処理の実行

マクロを使用すると、検索して置換操作のような単純なアクションからテンプレート全体の広範な変換まで、テンプレートに対してカスタム処理を実行できるようになります。

幅広い可能性を把握するには AWS CloudFormation によってホストされるマクロである AWS::Include および AWS::Serverless トランスフォームを検討してください。

AWS CloudFormation マクロの仕組み

マクロを使用してテンプレートを処理するには、2 つの主要なステップがあります。マクロ自体を作成すること、そして次にマクロを使用してテンプレートに対して処理を実行することです。

マクロ定義を作成するには、以下を作成する必要があります。

マクロを使用するには、テンプレート内の次のマクロを参照してください。

次に、通常は変更セットを作成して実行します。(マクロを処理すると、気付かないうちに複数のリソースが追加されていることがあります。マクロに伴うすべての変更を確実に認識できるように、変更セットを使用することを強くお勧めします。) AWS CloudFormation は、マクロリソースで指定された Lambda 関数に、指定されたテンプレートのコンテンツとその他の指定されたパラメータを渡します。Lambda 関数は、スニペットまたはテンプレート全体で処理されたテンプレートコンテンツを返します。

テンプレート内のすべてのマクロが呼び出された後、AWS CloudFormation は処理されたテンプレートコンテンツを含む変更セットを生成します。変更セットを確認したら、これを実行して変更を適用します。

AWS CloudFormation マクロ定義の作成

マクロ定義を作成すると、そのマクロ定義によって、指定されたアカウントで基盤となる Lambda 関数が使用可能になるため、AWS CloudFormation はそれを呼び出してテンプレートを処理できます。

AWS CloudFormation マクロ機能インターフェース

マクロの場合、AWS CloudFormation は以下のイベントマッピングを使用して基盤となる Lambda 関数を呼び出します。AWS CloudFormation はリクエストを JSON 形式で送信し、関数のレスポンスも JSON としてフォーマットされます。

{
    "region" : "us-east-1",
    "accountId" : "$ACCOUNT_ID",
    "fragment" : { ... },
    "transformId" : "$TRANSFORM_ID",
    "params" : { ... },
    "requestId" : "$REQUEST_ID",
    "templateParameterValues" : { ... }
}

AWS CloudFormation は、基盤となる関数が次の JSON 形式でレスポンスを返すことを意図しています。

{
    "requestId" : "$REQUEST_ID",
    "status" : "$STATUS",
    "fragment" : { ... }
    "errorMessage": "optional error message for failures"
}

マクロを作成する際の追加の考慮事項については、「AWS CloudFormation マクロ定義を作成する際の考慮事項」を参照してください。

AWS CloudFormation マクロアカウントの範囲とアクセス許可

マクロは、リソースとして作成されたアカウントでのみ使用できます。マクロ名は指定のアカウント内で一意である必要があります。ただし、基盤となる Lambda 関数でクロスアカウントアクセスを有効にし、その後複数のアカウントでその機能を参照するマクロ定義を作成することで、同じ機能を複数のアカウントで使用できるようにすることができます。以下の例では、3 つのアカウントにそれぞれ同じ Lambda 関数を指すマクロ定義が含まれています。

詳細については、「AWS Lambda デベロッパーガイド」の「AWS Lambda リソースへの許可の管理の概要」を参照してください。

マクロ定義を作成するには、ユーザーは指定されたアカウント内にスタックまたはスタックセットを作成するための許可を持っていなければなりません。

AWS CloudFormation がテンプレートに含まれているマクロを正常に実行するには、ユーザーは基盤となる Lambda 関数に対する Invoke アクセス許可を持っている必要があります。アクセス権限がエスカレーションしないよう、マクロの実行中に AWS CloudFormation はユーザーとして振る舞います。詳細については、「AWS Lambda デベロッパーガイド」の「Lambda 許可モデル」および「IAM ユーザーガイド」の「AWS Lambda のアクションと条件コンテキストキー」を参照してください。

AWS::Serverless 変換 および AWS::Include 変換 トランスフォームは、AWS CloudFormation によってホストされるマクロです。それらを使用するために特別なアクセス権限は必要ではなく、AWS CloudFormation の任意のアカウント内から使用できます。

AWS CloudFormation マクロのデバッグ

デバッグをサポートするために、マクロの AWS::CloudFormation::Macro リソースタイプを作成する際に、LogGroupName プロパティと LogRoleArn プロパティを指定できます。これらのプロパティを使用すると、マクロの基盤となる AWS Lambda 関数を呼び出すときに AWS CloudFormation がエラーログ情報を送信する CloudWatch ロググループ、およびそれらのログにログエントリを送信するときに AWS CloudFormation が引き受けるロールを指定できます。

「請求」

マクロが実行されると、その関数の実行に関連する料金が Lambda 関数の所有者に請求されます。

AWS::Serverless 変換 および AWS::Include 変換 トランスフォームは、AWS CloudFormation によってホストされるマクロです。これらの使用料は発生しません。

AWS CloudFormation マクロ定義を作成する際の考慮事項

マクロ定義を作成するときは、次の点に留意してください。

テンプレートで AWS CloudFormation マクロを使用する

AWS CloudFormation がマクロ定義を含むスタックの作成に成功すると、そのアカウント内でマクロを使用できるようになります。処理するテンプレートの内容に関連する適切な場所で、テンプレート内でマクロを参照して使用します。

AWS CloudFormation マクロ評価順

AWS::Include 変換 や AWS::Serverless 変換 など、AWS CloudFormation によってホストされているトランスフォームを含む、特定のテンプレート内の複数のマクロを参照できます。

マクロは、テンプレート内の位置に基づいて、最も深く外側にネストされているものから最も一般的なものまで順番に評価されます。テンプレート内の同じ場所にあるマクロは、リストされている順序に基づいて順番に評価されます。

AWS::Include や AWS::Transform などの変換は、アクションの順序と範囲の点で他のマクロと同じように扱われます。

例えば、以下のテンプレートサンプルでは、テンプレートで最も深くネストされているマクロなので、AWS CloudFormation が PolicyAdder マクロを最初に評価します。Transform セクションで AWS::Serverless より前にリストされているため、AWS CloudFormation は AWS::Serverless を評価する前に MyMacro を評価します。

AWSTemplateFormatVersion: 2010-09-09
 Transform: [MyMacro, AWS::Serverless]
 Resources:
    WaitCondition:
      Type: AWS::CloudFormation::WaitCondition
    MyBucket:
      Type: 'AWS::S3::Bucket'
      Properties:
        BucketName: MyBucket
        Tags: [{"key":"value"}]
        'Fn::Transform':
          - Name: PolicyAdder
        CorsConfiguration:[]
    MyEc2Instance:
      Type: 'AWS::EC2::Instance'
      Properties:
        ImageID: "ami-123"

AWS CloudFormation マクロスコープ

テンプレートの Transform セクションで参照されているマクロは、そのテンプレートの内容全体を処理できます。

Fn::Transform 関数で参照されているマクロは、テンプレート内のその Fn::Transform 関数の兄弟要素 (子を含む) の内容を処理できます。

たとえば、以下のテンプレートサンプルでは、AWS::Include は、それ自身を含む Fn::Transform 関数の場所に基づいて、MyBucket プロパティを処理できます。MyMacro は、Transform セクションに含まれているため、テンプレート全体の内容を処理できます。

// Start of processable content for MyMacro
AWSTemplateFormatVersion: 2010-09-09 
 Transform: [MyMacro]
 Resources:
    WaitCondition:
      Type: AWS::CloudFormation::WaitCondition
    MyBucket:
      Type: 'AWS::S3::Bucket'  //Start of processable content for AWS::Include
      Properties:
        BucketName: MyBucket 
        Tags: [{"key":"value"}] 
        'Fn::Transform':
          - Name: 'AWS::Include'
              Parameters:
                Location: s3://DOC-EXAMPLE-BUCKET/MyFileName.yaml
        CorsConfiguration:[]   //End of processable content for AWS::Include
    MyEc2Instance:
      Type: 'AWS::EC2::Instance' 
      Properties:
        ImageID: "ami-123"
// End of processable content for MyMacro         

変更セットおよび AWS CloudFormation マクロ

マクロを参照するテンプレートを使用してスタックを作成または更新するには、通常、変更セットを作成して実行します。変更セットは、処理されたテンプレートに基づいて CloudFormation が実行するアクションを記述します。マクロを処理すると、知らないうちに複数のリソースが追加される可能性があります。マクロに伴うすべての変更を確実に認識できるように、変更セットを使用することを強くお勧めします。変更セットを確認したら、これを実行して実際に変更を適用します。

マクロによってテンプレートに IAM リソースが追加されることがあります。これらのリソースについて、AWS CloudFormation ではその機能を確認する必要があります。AWS CloudFormation では、どのリソースが追加されるかをテンプレートの処理前に認識することはできないため、参照されたマクロに IAM リソースが含まれているかどうかによって、変更セットを作成するときにユーザーが IAM の機能を把握しておく必要がある場合があります。こうすることで、変更セットを実行するときに、AWS CloudFormation が IAM リソースを作成するために必要な機能を持つことができます。

AWS CLI を使用する場合は、package および deploy コマンドを使用して、マクロを参照するテンプレートからスタックを起動する際のステップ数を減らすことができます。詳細については、「AWS Lambda デベロッパーガイド」の「Deploying Lambda-based applications」(Lambda ベースのアプリケーションのデプロイ) を参照してください。

テンプレートのステージと CloudFormation のマクロ

テンプレートのステージは、そのテンプレートがユーザーによって送信されたオリジナルのテンプレートか、AWS CloudFormation によってマクロを処理されたものかを示します。

スタックの問題のトラブルシューティングには、処理済みテンプレートを使用します。テンプレートがマクロを参照していない場合は、オリジナルと処理済みのテンプレートは同一です。

AWS CloudFormation コンソールまたは AWS CLI を使用して、スタックのテンプレートのステージを確認できます。

マクロの例

このガイドの「」のチュートリアルに加えて、GitHub の「Amazon Web Service - ラボ」の「マクロの例」セクションに、ソースコードとテンプレートを含むサンプルマクロの例があります。これらの例は、説明を目的として「現状のまま」提供されています。

以下も参照してください。

AWS::CloudFormation::Macro

変換

Fn::Transform

AWS::Serverless 変換

AWS::Include 変換