# CloudFormation モジュールを使用してテンプレート全体に含めることができる再利用可能なリソース設定の作成
*モジュール*は、スタックテンプレート全体に含めるリソース構成をパッケージ化する、透過的で管理しやすく、繰り返し可能な方法です。モジュールは、共通のサービス構成とベストプラクティスを、スタックテンプレートに含めるためのモジュール式のカスタマイズ可能なビルディングブロックとしてカプセル化できます。モジュールを使用すると、リソース実装の複雑さを深く理解することなく、ベストプラクティス、専門分野の知識、承認されたガイドライン (セキュリティ、コンプライアンス、ガバナンス、業界規制などの領域について) をテンプレートに含めることができます。
たとえば、ネットワークのドメイン専門家は、組み込みのセキュリティグループと、セキュリティガイドラインに準拠した入力/出力ルールを含むモジュールを作成できます。そうして、そのモジュールをテンプレートに含めることで、VPC、サブネット、セキュリティグループ、ゲートウェイがどのように機能するかを考えるのに時間を費やすことなく、セキュアなネットワーキングインフラストラクチャをスタックにプロビジョニングできます。また、モジュールはバージョン管理されているため、セキュリティガイドラインが時間の経過とともに変更された場合、モジュールの作成者はそれらの変更を組み込んだ新しいバージョンのモジュールを作成できます。
テンプレートでモジュールを使用することの特徴は次のとおりです。
+ **予測可能性** – モジュールは CloudFormation レジストリに登録されているスキーマに準拠する必要があります。そのため、テンプレートにモジュールを含めると解決できるリソースがわかります。
+ **再利用性** – 複数のテンプレートとアカウントで同じモジュールを使用できます。
+ **トレーサビリティ** – CloudFormation では、スタック内のどのリソースがモジュールからプロビジョニングされたかを把握できるため、リソース変更のソースを簡単に把握できます。
+ **管理機能** – モジュールを登録したら、バージョニング、アカウント、リージョンの可用性など、CloudFormation レジストリを使用してモジュールを管理できます。
モジュールには次のものを含めることができます。
+ モジュールからプロビジョニングされる 1 つ以上のリソース、および出力や条件などの関連データ。
+ 任意のモジュールパラメータ。モジュールが使用されるたびにカスタム値を指定できます。
モジュールの開発の詳細については、「*CloudFormation CLI ユーザーガイド*」の「[モジュールの開発](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/modules.html)」を参照してください。
**Topics**
+ [モジュールを使用するときの考慮事項](#module-considerations)
+ [モジュールのバージョニングの概要](module-versioning.md)
+ [CloudFormation プライベートレジストリのモジュールの使用](modules-using.md)
+ [パラメータを使用してモジュール値を指定する](module-using-params.md)
+ [CloudFormation テンプレートのリファレンスモジュールリソース](module-ref-resources.md)
## モジュールを使用するときの考慮事項
+ モジュールは追加料金なしで使用できます。スタック内でそれらのモジュールが解決したリソースに対してのみお支払いいただきます。
+ CloudFormation クォータ (スタックで許可されるリソースの最大数、テンプレート本文の最大サイズなど) は、テンプレートに含まれるリソースがモジュールから取得されているかどうかにかかわらず、処理されたテンプレートに適用されます。詳細については、「[CloudFormation クォータを理解する](cloudformation-limits.md)」を参照してください。
+ スタックレベルで指定するタグは、モジュールから派生した個々のリソースに割り当てられます。
+ モジュールレベルで指定されたヘルパースクリプトは、CloudFormation がテンプレートを処理するときに、モジュールに含まれる個々のリソースには伝達されません。
+ モジュールで指定された出力は、テンプレートレベルで出力に伝播されます。
各出力には、モジュールで定義されたモジュールの論理名と出力名を連結した論理 ID が割り当てられます。詳細については、「[デプロイされた CloudFormation スタックからエクスポートされた出力を取得する](using-cfn-stack-exports.md)」を参照してください。
+ モジュールで指定されたパラメータは、テンプレートレベルのパラメータには伝達されません。
ただし、モジュールレベルのパラメータを参照するテンプレートレベルのパラメータを作成できます。詳細については、「[パラメータを使用してモジュール値を指定する](module-using-params.md)」を参照してください。
# モジュールのバージョニングの概要
CloudFormation レジストリは、AWS アカウント およびリージョン内で使用するモジュールの登録および管理ができるリポジトリとして機能します。アカウントおよびリージョン内で AWS、サードパーティーのパブリッシャー、独自のカスタム拡張機能など、さまざまなソースからモジュールを登録できます。詳細については、「[CloudFormation レジストリによる拡張機能の管理](registry.md)」を参照してください。
モジュールには異なるバージョンが存在する場合もあるため、使用するモジュールのバージョンを指定できます。このバージョニング機能は、モジュールに依存する既存のスタックを壊さずにモジュールを更新または変更する必要があるときには特に便利です。
複数のバージョンのモジュールを使用するとき、次の点に注意してください。
+ スタックオペレーション中、CloudFormation は、スタックオペレーションが実行されている AWS アカウント およびリージョンで、デフォルトバージョンとして現在登録されているモジュールのバージョンを使用します。これには、他のモジュールにネストされているモジュールも含まれます。
したがって、異なるアカウントまたはリージョンで、同じモジュールの異なるバージョンをデフォルトバージョンとして登録している場合、同じテンプレートを使用しても異なる結果になる可能性があることに注意してください。
+ スタックオペレーション中、CloudFormation は、スタックオペレーションが実行されている AWS アカウント およびリージョンで、デフォルトバージョンとして現在登録されているリソースのバージョンを使用します。これには、モジュールを含めることによって生成されたリソースが含まれます。
+ モジュールのデフォルトバージョンを変更しても、スタックの更新オペレーションは開始されません。ただし、次にそのモジュールを含むテンプレート (スタックの更新など) でスタックオペレーションを実行すると、CloudFormation は新しいデフォルトバージョンをオペレーションで使用します。
これに関する例外の 1 つは、以下で説明するように、[**use previous template**] オプションを指定してスタックの更新を実行することです。
+ スタックの更新オペレーションで、[**use previous template**] (以前のテンプレートを使用) オプションを指定すると、CloudFormation はスタック更新のために以前に処理されたテンプレートを使用し、モジュールに加えた変更については再処理しません。
+ 一貫した結果を保証するには、スタックセットで使用するスタックテンプレートにモジュールを含める場合、スタックインスタンスのデプロイを考えているすべてのアカウントおよびリージョンで、同じバージョンのモジュールがデフォルトバージョンとして設定されていることを確認してください。これは、他のモジュールにネストされているモジュールの場合を含みます。詳細については、「[StackSets を使用したアカウントとリージョン全体でのスタックの管理](what-is-cfnstacksets.md)」を参照してください。
## サードパーティーのパブリックモジュールのアクティブ化における要件
アカウントおよびリージョンでサードパーティのパブリックモジュールを正常にアクティブ化するには、モジュールに含まれる各サードパーティのパブリック拡張機能 (リソースまたはモジュール) に対して次の事項が当てはまる必要があります。
+ **拡張機能のアクティブ化** – 拡張機能は、使用するアカウントおよびリージョンでアクティブ化する必要があります。詳細については、「[CloudFormation レジストリからサードパーティーのパブリック拡張を使用する](registry-public.md)」を参照してください。
+ **エイリアス登録** – モジュール内のエクステンションがタイプ名のエイリアスを使用する場合、エクステンションは同じタイプ名のエイリアスを使用してアカウントおよびリージョンに登録する必要があります。詳細については、「[拡張を参照するエイリアスを使用する](registry-public.md#registry-public-enable-alias)」を参照してください。
+ **バージョン互換性** – 現在アクティブ化されているエクステンションのバージョンは、モジュールで指定されているエクステンションのサポートされているメジャーバージョンのいずれかである必要があります。
適切なサードパーティのパブリック拡張機能および拡張機能のバージョンがアクティブ化されていない場合、CloudFormation はオペレーションに失敗し、モジュールを正常にアクティブ化する前にアクティブ化する必要がある拡張機能およびバージョンを一覧表示したエラーが表示されます。
# CloudFormation プライベートレジストリのモジュールの使用
このトピックでは、CloudFormation テンプレートでモジュールを使用する方法について説明します。モジュールは、テンプレートに追加できるリソースの事前作成されたバンドルと考えてください。
モジュールを使用するには、次の手順を実行してください。
+ **モジュールの登録** – CloudFormation レジストリでモジュールをプライベート拡張機能として登録します。作業している AWS アカウント およびリージョンで登録されていることを確認します。詳細については、「[CloudFormation レジストリの概念](registry-concepts.md)」を参照してください。
+ **テンプレートに含める** – 他のリソースと同様に、モジュールを CloudFormation テンプレートの [Resources](resources-section-structure.md) セクションに追加します。モジュールに必要なプロパティを指定する必要もあります。
+ **スタックの作成または更新** – スタックオペレーションを開始すると、含まれているモジュールを適切なリソースに解決する処理済みテンプレートが CloudFormation によって生成します。
+ **変更のプレビュー** – 変更を行う前に、変更セットを使用して追加または変更されるリソースを確認できます。詳細については、「[変更セットを使用して CloudFormation スタックを更新する](using-cfn-updating-stacks-changesets.md)」を参照してください。
次の例を考えてみましょう。リソースとモジュールの両方を含むテンプレートがあります。テンプレートには、1 つの個別のリソース `ResourceA` とモジュール `ModuleParent` が含まれます。このモジュールには、`ResourceB` および `ResourceC` の 2 つのリソースと、ネストされたモジュール `ModuleChild` が含まれます。`ModuleChild` には、1 つのリソース `ResourceD` が含まれます。このテンプレートからスタックを作成すると、CloudFormation はテンプレートを処理し、モジュールを適切なリソースに解決します。結果のスタックには、`ResourceA`、`ResourceB`、`ResourceC`、`ResourceD` の 4 つのリソースがあります。
![\[スタックオペレーション中、CloudFormation はスタックテンプレートに含まれている 2 つのモジュールを適切な 4 つのリソースに解決します。\]](http://docs.aws.amazon.com/ja_jp/AWSCloudFormation/latest/UserGuide/images/modules-resource-inclusion.png)
CloudFormation は、スタック内のどのリソースがモジュールから作成されたかを追跡します。この情報は、特定のスタックの [**Events**] (イベント)、[**Resources**] (リソース)、および [**Drifts**] (ドリフト) タブに表示できます。また、変更セットのプレビューにも表示されます。
モジュールはテンプレート内のリソースと区別できます。これは、リソースで使用される一般的な 3 つのパート規則とは対照的に、次の 4 つの部分からなる命名規則に従っているためです。
```
organization::service::use-case::MODULE
```
# パラメータを使用してモジュール値を指定する
CloudFormation では、スタックの作成時または更新中に入力値を指定することにより、テンプレートパラメータを使用してスタックをカスタマイズできます。これらのパラメータにより、必要に応じてスタックの特定の特徴を変更できます。テンプレートのパラメータの定義に関する詳細は、「[CloudFormation テンプレートの Parameters 構文](parameters-section-structure.md)」を参照してください。
同様に、モジュールにパラメータを含めることもできます。これらのモジュールパラメータにより、使用しているテンプレート (または別のモジュール) からモジュールにカスタム値を入力できます。モジュールはこれらのカスタム値を使用し、プロパティ値が含まれるリソースにそのプロパティ値を設定できます。
スタック操作時にモジュールに渡される値を入力できるように、モジュールプロパティを設定するテンプレートパラメータを定義することもできます。
独自のモジュールパラメータを持つネストされたモジュールがモジュールに含まれている場合、次のいずれかの操作ができます。
+ ネストされたモジュールのパラメータの値を親モジュールで直接指定します。
+ 親モジュール内の対応するモジュールパラメータを定義して、ネストされたモジュールのパラメータを、親モジュールが含まれているテンプレート (またはモジュール) で設定できるようにします。
## テンプレートパラメータを使用したモジュールパラメータ値の指定
次の例は、モジュールに値を渡すテンプレートパラメータを定義する方法を示しています。
`My::S3::SampleBucket::MODULE` を含むこのテンプレートは、スタック操作時にユーザーが S3 バケット名を指定できるようにするテンプレートパラメータの `BucketName` を定義します。
```
# Template containing My::S3::SampleBucket::MODULE
Parameters:
BucketName:
Description: Name for your sample bucket
Type: String
Resources:
MyBucket:
Type: 'My::S3::SampleBucket::MODULE'
Properties:
BucketName: !Ref BucketName
```
## 親モジュールから子モジュール内のリソースのプロパティを指定する
次の例は、別のモジュール内にネストされているモジュールでパラメータ値を指定する方法を示しています。
この最初のモジュール `My::S3::SampleBucketPrivate::MODULE` は、子モジュールになります。これは、`BucketName` と `AccessControl` の 2 つのパラメータを定義します。これらのパラメータに指定された値は、モジュールに含まれる `AWS::S3::Bucket` リソースの `BucketName` および`AccessControl` プロパティを指定するために使用されます。以下は `My::S3::SampleBucketPrivate::MODULE` のテンプレートフラグメントです。
```
# My::S3::SampleBucketPrivate::MODULE
AWSTemplateFormatVersion: 2010-09-09
Description: A sample S3 Bucket with Versioning and DeletionPolicy.
Parameters:
BucketName:
Description: Name for the bucket
Type: String
AccessControl:
Description: AccessControl for the bucket
Type: String
Resources:
S3Bucket:
Type: AWS::S3::Bucket
Properties:
BucketName: !Ref BucketName
AccessControl: !Ref AccessControl
DeletionPolicy: Retain
VersioningConfiguration:
Status: Enabled
```
次に、前のモジュールは親モジュール `My::S3::SampleBucket::MODULE` 内にネストされます。親モジュール `My::S3::SampleBucket::MODULE` は、次の方法で子モジュールのパラメータを設定します。
+ `My::S3::SampleBucketPrivate::MODULE` の `AccessControl` パラメータを `Private` に設定します。
+ `BucketName` では 、モジュールパラメータを定義します。これにより、`My::S3::SampleBucket::MODULE` を含むテンプレート (またはモジュール) でバケット名を指定できます 。
```
# My::S3::SampleBucket::MODULE
AWSTemplateFormatVersion: 2010-09-09
Description: A sample S3 Bucket. With Private AccessControl.
Parameters:
BucketName:
Description: Name for your sample bucket
Type: String
Resources:
MyBucket:
Type: 'My::S3::SampleBucketPrivate::MODULE'
Properties:
BucketName: !Ref BucketName
AccessControl: Private
```
## モジュールパラメータの制約の指定
モジュールパラメータは、制約の適用をサポートしていません。モジュールパラメータに対して制約チェックを実行するには、必要な制約を持つテンプレートパラメータを作成します。その後、モジュールパラメータでそのテンプレートパラメータを参照します。テンプレートのパラメータの定義に関する詳細は、「[CloudFormation テンプレートの Parameters 構文](parameters-section-structure.md)」を参照してください。
# CloudFormation テンプレートのリファレンスモジュールリソース
CloudFormation テンプレートでは、別のリソースの名前またはプロパティに基づいて、あるリソースのプロパティを設定しなければならないことがよくあります。詳細については、「[リソースの参照](resources-section-structure.md#using-cross-resource-references)」を参照してください。
CloudFormation テンプレートのモジュール内に含まれるリソースを参照するには、次の 2 つの論理名を組み合わせる必要があります。
+ テンプレートにモジュールを含めたときにそのモジュール自体に付けた論理名。
+ そのモジュール内にある特定リソースの論理名。
これらの 2 つの論理名は、それらの間にピリオド (.) を使用するか、使用せずに組み合わせることができます。たとえば、モジュールの論理名が「`MyModule`」でリソースの論理名が「`MyBucket`」の場合、「`MyModule.MyBucket`」または「`MyModuleMyBucket`」とすることで、そのリソースを参照できます。
モジュール内のリソースの論理名を確認するには、CloudFormation レジストリまたは「[https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_DescribeType.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_DescribeType.html)」操作を使用することにより、モジュールのスキーマを参照できます。スキーマリストには、モジュールの一部であるすべてのリソースおよびその論理名が一覧表示されます。
完全な論理名を取得したら、`GetAtt` や `Ref` などの CloudFormation 関数を使用してモジュールリソースのプロパティ値にアクセスできます。
たとえば、「`S3Bucket`」という論理名の `AWS::S3::Bucket` リソースを含む `My::S3::SampleBucket::MODULE` モジュールがあるとします。`Ref` 関数を使用してこのバケットの名前を参照するには、テンプレート (`MyBucket`) のモジュール名をモジュール (`S3Bucket`) のリソースの論理名と組み合わせます。完全な論理名は「`MyBucket.S3Bucket`」または「`MyBucketS3Bucket`」のいずれかです。
**サンプルテンプレート**
次のテンプレート例では、`My::S3::SampleBucket::MODULE` モジュールを使用して S3 バケットを作成します。Amazon SQS キューも作成し、名前をモジュールのバケット名と同じに設定します。さらに、テンプレートは作成された S3 バケットの Amazon リソースネーム (ARN) を出力します。
```
# Template that uses My::S3::SampleBucket::MODULE
Parameters:
BucketName:
Description: Name for your sample bucket
Type: String
Resources:
MyBucket:
Type: My::S3::SampleBucket::MODULE
Properties:
BucketName: !Ref BucketName
exampleQueue:
Type: AWS::SQS::Queue
Properties:
QueueName: !Ref MyBucket.S3Bucket
Outputs:
BucketArn:
Value: !GetAtt MyBucket.S3Bucket.Arn
```