CloudFormation は、リソース同士の依存関係を自分で解決してくれる。テンプレートの中でどの順に書いても、正しい順序で作成・更新される。
それでも、書く順序は決めておいたほうがいい。 理由は 3 つあり、どれも「参照の向き」から来ている。
社内の技術共有会でこの整理をやったので、外向けに書き直して残しておく。対象は CloudFormation を触ったことがない人で、読み終えたときに書き方の順序が分かる状態を目指す。
■ IaC で解決すること
コンソールを手で操作してインフラを作ると、困ることが決まっている。
・誰が何をクリックしたか、記録に残らない
・同じ環境をもう 1 つ作るのが大変(dev 環境の再現など)
・レビューできない。Git で差分が見えない
・手順を知っている人が限られ、属人化する
IaC(Infrastructure as Code)は、インフラの構成を定義ファイルで管理する手法である。コードにすれば Git で管理でき、レビューでき、同じものを何度でも作れる。
CloudFormation は AWS が提供する IaC のサービスである。YAML か JSON で構成を「テンプレート」として書き、AWS がそれを元に作って管理する実体を「スタック」と呼ぶ。AWS CLI に同梱されているので、追加のツールは要らない。AWS CDK も、内部では CloudFormation のテンプレートを生成している。
■ テンプレートは主に 4 つのセクションで書く
よく使うのは次の 4 つである。必須は Resources だけで、残りは必要なときに足す。
・Parameters — デプロイ時に外から渡す値(環境名、ドメイン名など)
・Conditions — パラメータの値によって構成を出し分ける条件
・Resources — 実際に作る AWS リソースの定義。唯一の必須セクション
・Outputs — デプロイ後に他から参照したい値(URL、ID など)
最小のテンプレートはこれだけで済む。
AWSTemplateFormatVersion: "2010-09-09"
Description: 最小構成の S3 バケット
Resources:
MyBucket:
Type: AWS::S3::Bucket
Properties:
BucketName: my-sample-bucket
Outputs:
BucketName:
Value: !Ref MyBucket
「Type」 に AWS リソースの種類を書き、「Properties」 に設定値を書く。これを 「aws cloudformation deploy」 に渡せば、S3 バケットが 1 つ作られる。
先頭の 「AWSTemplateFormatVersion」 は、テンプレートの書式のバージョンである。有効な値は 「2010-09-09」 の 1 つだけで、省略もできる。自分のテンプレートの版を書く欄ではない。
Parameters と Conditions を組み合わせると、1 つのテンプレートから複数の環境を作れる。たとえば環境名 「EnvName」 に 「dev」 / 「prod」 だけを許し、「EnableAlarms」 が 「"true"」 のときだけアラームを作る、という書き方になる。
■ リソースを繋ぐ 4 つの組み込み関数
テンプレートの中でリソース同士を繋ぐには、組み込み関数を使う。最初に覚えるのは 4 つである。
・「!Ref」 — パラメータの値や、リソースの既定の戻り値を参照する(例: 「!Ref EnvName」)
・「!GetAtt」 — リソースの属性を取得する(例: 「!GetAtt MyBucket.RegionalDomainName」)
・「!Sub」 — パラメータや疑似変数を文字列に埋め込む(例: バケット名の中に環境名を埋め込む)
・「!If」 — 条件によって値を出し分ける(例: 「!If [UseCustomDomain, ..., !Ref "AWS::NoValue"]」)
「!Ref」 がリソースに対して返す値は、リソースの種類ごとに違う。Lambda 関数なら関数名、S3 バケットならバケット名を返す。ARN が要る場所では 「!GetAtt X.Arn」 を使う。
■ ARN は、リソースの住所である
ARN(Amazon Resource Name)は、AWS 上のリソースを一意に指す識別子である。IAM ポリシーでも API でも、リソースを曖昧さなく指すときはこれを使う。
「arn:aws:iam::123456789012:role/my-app-role」 を分解すると、次のようになる。
・「arn」 — すべての ARN がこれで始まる
・「aws」 — パーティション。中国リージョンなどは別の値になる
・「iam」 — どの AWS サービスのリソースか
・(空)— リージョン。IAM はリージョンを持たないので空になる。S3 バケットも空
・「123456789012」 — どの AWS アカウントのものか。12 桁の数字(AWS 公式ドキュメントの例示値)
・「role/my-app-role」 — リソースの種類と名前。書式はサービスごとに違う
「!GetAtt MyFunctionRole.Arn」 は「作ったロールの ARN を持ってくる」という意味になる。名前をベタ書きしないので、dev と prod で名前が変わっても壊れない。
□ 信頼ポリシーと権限ポリシーは別物
IAM ロールには 2 種類のポリシーが付く。誰がこのロールを引き受けられるか(信頼ポリシー)と、このロールで何ができるか(権限ポリシー)である。IAM で最初につまずくのはここになる。
テンプレートでは、信頼ポリシーを 「AssumeRolePolicyDocument」 に書く。Lambda に使わせるロールなら、「Principal」 に 「lambda.amazonaws.com」 を置き、「Action」 に 「sts:AssumeRole」 を置く。ポリシー言語の版を示す 「Version」 は 「2012-10-17」 を書く。
■ 層は 5 段。参照されるだけのものが一番下
ここからがこの記事の本題である。テンプレートのリソースは、参照の向きで 5 段に分けられる。その下に、リソースではない「前提」が 1 段敷かれる。
・前提 — Parameters / Conditions / Mappings。全部の層が参照する入力と条件
・① 土台 — IAM ロール・ポリシー、ロググループ、KMS キー、VPC など。他の層から参照されるだけで、他の層は参照しない
・② 入れ物 — S3、DynamoDB、RDS、SQS など。データの置き場で、名前や ARN が他から参照される
・③ 処理 — Lambda、ECS、Step Functions など。①の権限と②の置き場を参照して初めて作れる
・④ 入口 — API Gateway、ALB、CloudFront など。③の処理を指定して、外から入れるようにする
・⑤ 仕上げ — CloudFront Functions、WAF、アラームなど。無くても本体は動き、後から足せる
迷ったら参照の向きを見る。他のリソースの ARN や ID を書く必要があるものは、その参照先より後の層に置く。参照されるだけのものは先の層に置く。
⑤ の仕上げだけは、向きの例外を含む。CloudFront Functions や、CloudFront に付ける WAF は、入口の側から参照される(ALB や API Gateway に付ける WAF は、関連付け用のリソースが両方を参照するので、向きどおりになる)。それでも最後に置くのは、無くても本体が動き、後から足して入口を更新すれば済むからである。
■ なぜこの順で作るのか — 理由は 3 つ
CloudFormation は依存関係を自分で解決してくれる。それでも積む順を決めておく理由が 3 つある。
1 つ目は、参照先が無いものは書けないこと。「!Ref」 も 「!GetAtt」 も「すでにある物」を指す書き方である。Lambda は IAM ロールの ARN を参照するので、ロールが無いと定義そのものが成り立たない。次のコード片は参照の関係だけを見せる抜粋で、各リソースの必須プロパティや 「MyFunctionLogGroup」 の定義は省いている。
MyFunctionRole: # 土台: まず Lambda が使うロールを作る
Type: AWS::IAM::Role
Properties:
AssumeRolePolicyDocument:
Version: "2012-10-17"
Statement:
- Effect: Allow
Principal: { Service: lambda.amazonaws.com }
Action: sts:AssumeRole
MyFunction: # 処理: 土台ができて初めて書ける
Type: AWS::Lambda::Function
DependsOn: MyFunctionLogGroup # 参照の無い依存は DependsOn で明示する
Properties:
Role: !GetAtt MyFunctionRole.Arn # 上のロールの ARN を参照する
MyIntegration: # 入口: 処理ができてから外に出す口
Type: AWS::ApiGatewayV2::Integration
Properties:
IntegrationUri: !GetAtt MyFunction.Arn
順序は好みではなく、参照の向きで決まっている。参照を書かない依存(ロググループを先に作っておきたい、など)は、「DependsOn」 で明示できる。
2 つ目は、失敗の切り分けが効くこと。土台から順に積むと、失敗したときに「どの層までは立っていたか」がはっきりする。上から一気に作ると、権限の問題なのか設定の問題なのか区別できず、原因探しに時間を取られる。
3 つ目は、やり直しの範囲が小さいこと。上の層(Functions・スケジューラ・ドメイン)を差し替えても、土台は動かない。逆に土台を後から直すと、その上に載せた全部が作り直しになる。
先に土台を硬く作る。IAM ロールとログの出力先を最初に固めるだけで、その後の作業がまっすぐ進む。
■ ハマりどころ
エラーメッセージは正確である。ただ、原因が CloudFormation の外にあることも多い。
□ capabilities の付け忘れ
IAM リソースを作るテンプレートは、デプロイ時に 「--capabilities CAPABILITY_IAM」 を付けて「IAM リソースを作ることを承知した」と明示する必要がある。付け忘れると 「InsufficientCapabilitiesException」 で止まる。ロールに名前を付けている場合は 「CAPABILITY_NAMED_IAM」 が要る。
もう 1 つ地味なのが、環境名のパラメータの変え忘れである。名前に環境名を埋め込んでいると、変え忘れた瞬間に dev と prod が同じデータストアを共有してしまう。最初の数回はチェックリストで回すのが安全である。
□ クロスリージョンの制約
CloudFront で ACM の証明書を使うなら、証明書は米国東部(バージニア北部、「us-east-1」)で発行する必要がある。東京リージョンで作った証明書の ARN を渡すと、CloudFront が見つけられずスタックの作成が失敗する。
1 スタックは 1 リージョンが原則である。リージョンをまたぐ依存があるなら、スタックを分ける。証明書だけを 「us-east-1」 のスタックで作り、その ARN を本体のスタックに渡す形になる。
□ サービス側の制限
あるサイト配信構成で踏んだのが、CloudFront Functions の関連付けの制限である。CloudFront では、1 つのキャッシュビヘイビアに対して、イベントの種類ごとに関連付けられる関数は 1 つだけである。
ビヘイビアは、URL のパスパターンごとの処理ルールである。転送先・キャッシュ設定・関数の関連付けを、ビヘイビア単位で決める。イベントは 4 つあり、CloudFront Functions が使えるのは viewer request と viewer response の 2 つだけである(origin 側は Lambda@Edge)。
viewer request で動かしたい処理が 2 つあり、別々の関数として関連付けようとして、この制限にぶつかった。結局、2 つの処理を 1 つの関数に統合した。テンプレートを書く前に、対象サービス自体の制約を先に調べておくべきだった。
■ CloudFormation では完結しないこと
全部をコード化できるわけではない。事前に、あるいは別の経路で対応するものが残る。
・独自ドメインの新規取得。 CloudFormation にドメイン登録のリソースタイプが無い。コンソールか CLI で取得する
・SES のサンドボックス解除。 AWS 側の審査を経る。時間がかかるので早めに申請する
・Lambda の実コードの反映。 関数のコード本体は、S3 に置いたパッケージを指すか、「update-function-code」 などで別に反映する
・Cognito の初期管理者。 セルフサインアップを無効にしたユーザープールなら、最初の管理者は CLI で作る
対象外なのはドメインの「新規取得」だけである。ホストゾーンとレコードは CloudFormation で作れる。外側にある準備を先に段取りしておかないと、着手してから足止めを食う。
逆に、コードにしたことで得られるものもはっきりしている。環境名を変えるだけで dev と prod を分けて作れる。インフラの変更も Pull Request でレビューできる。同じコマンドを再実行しても、差分だけが適用される。
■ Terraform との違いは「state を誰が持つか」
「なぜ Terraform ではないのか」と聞かれることがある。違いはいくつもあるが、日々の運用に一番効くのは 1 点である。状態(state)を誰が持つか。
CloudFormation では、状態はスタックとして AWS 側が持つ。置き場所も、同時実行を防ぐ仕組みも用意しなくてよい。Terraform では、状態は既定で 「terraform.tfstate」 というファイルになり、自分の持ち物になる。チームで使うなら、保管先・ロック・権限・バックアップを自分で設計して運用する。
ほかの違いは次のとおりである。
・対応範囲。 CloudFormation は AWS のみ。Terraform は AWS 以外のクラウドや SaaS も扱える
・導入。 CloudFormation は AWS CLI に同梱。Terraform はバイナリを別に入れる
・差分の事前確認。 CloudFormation はチェンジセット、Terraform は 「terraform plan」
・失敗時の挙動。 CloudFormation は既定で自動的にロールバックする(成功した分を残す設定もある)
・ライセンス。 HashiCorp は 2023 年 8 月 10 日、以後のリリースを MPL 2.0 から BUSL 1.1 に変えると発表した。フォークに OpenTofu がある
選び分けの目安は単純である。対象が AWS だけなら CloudFormation で足りる。マルチクラウドや多数の SaaS まで一元管理する必要が出たら、Terraform を検討する。
■ 参考
・CloudFormation template sections — AWS CloudFormation User Guide(https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-anatomy.html)
・CloudFormation template format version syntax — AWS CloudFormation User Guide(https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/format-version-structure.html)
・AWS::Lambda::Function — AWS CloudFormation Template Reference(https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-lambda-function.html)
・Identify AWS resources with Amazon Resource Names (ARNs) — IAM User Guide(https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html)
・IAM JSON policy elements: Version — IAM User Guide(https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_version.html)
・Acknowledging IAM resources in CloudFormation templates — AWS CloudFormation User Guide(https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/control-access-with-iam.html)
・Requirements for using SSL/TLS certificates with CloudFront — Amazon CloudFront Developer Guide(https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cnames-and-https-requirements.html)
・Restrictions on all edge functions — Amazon CloudFront Developer Guide(https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/edge-function-restrictions-all.html)
・Associate functions with distributions — Amazon CloudFront Developer Guide(https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/associate-function.html)
・Amazon Route 53 resource types — AWS CloudFormation Template Reference(https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/AWS_Route53.html)
・Request production access (Moving out of the Amazon SES sandbox) — Amazon SES Developer Guide(https://docs.aws.amazon.com/ses/latest/dg/request-production-access.html)
・Choose how to handle failures when provisioning resources — AWS CloudFormation User Guide(https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stack-failure-options.html)
・Update CloudFormation stacks using change sets — AWS CloudFormation User Guide(https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets.html)
・State — Terraform Documentation(https://developer.hashicorp.com/terraform/language/state)
・HashiCorp adopts Business Source License — HashiCorp Blog(https://www.hashicorp.com/blog/hashicorp-adopts-business-source-license)
■ この記事を書いている会社について
株式会社MIRAILABS では、こうした検証を社内で持ち寄りながら、業務への組み込み方を詰めています。システム開発や AI を使った開発の進め方について、相談したいことがあればお問い合わせください。
MIRAILABS では一緒に働く仲間を募集しています。手を動かして確かめる進め方に心当たりのある方は、採用ページをご覧ください。
・採用情報(https://mirailabs.co.jp/recruit/)