Go to Qiita Advent Calendar 2024 Top
LoginSignup
3
3

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@a-shiosalt(A Shio)

CloudFormation 2024/11の更新 : hookの拡張 解説と操作例

Posted at

hookの拡張

11/20-21 にCloudFormation のフック(hook)の機能拡張が4件発表されました。

機能拡張の整理と、実際にGuardルールからhookを作成する手順をメモしておきます。

hook とは

CloudFormation フック(hook)は、リソースを作成・更新・削除する前にテンプレートの内容を確認（評価）する機能です。
基準に満たない場合はリソースの作成・更新・削除を拒否できます。

下記はフックでリソース DirectoryBucket の作成を拒否した例です。
image.png （ターゲット：スタック）

フックには失敗モード（FailureMode）設定があり、失敗(Fail)と警告(Warn)から選択します。
通常は失敗(Fail)モードに設定します。
警告(Warn)の場合はイベント履歴に警告通知を表示するのみで、リソース操作はそのまま行われます。

AWS CloudFormation 詳解
2章 CloudFormationの機能とコンソール画面
2-19 拡張機能とレジストリ
2-19-3 フック

３つの機能拡張

「1.フックのターゲット(hook targets) 設定の新設」と「2.Guard ルールやLambda関数を使った簡易なhook実装方法を提供」が主な機能拡張です。
併せて「3. Cloud Control API (CCAPI) でhookが利用可能」も提供されました。

1. フックのターゲット(hook targets) 設定の新設

hookの実行タイミングが追加され、フックのターゲット（hook targets）で指定可能になりました。

フックのターゲットは STACK / Resources / CHANGE_SET / CLOUD_CONTROL が指定可能です。
設定画面の選択肢
image.png

〇フックのターゲット: スタック(STACK)

スタック操作（作成・更新・削除）開始時、リソース操作前にテンプレートを確認します。
既存のhook実行タイミングと同じです。
評価がNRの場合、スタックでエラーとなりリソース操作は行われません。（hookのモードが失敗(Fail)の場合）

フロー図

〇フックのターゲット: リソース(Resources)

リソース操作（作成・更新・削除）の最初にテンプレートを確認します。
評価がNGの場合、リソースの操作（作成・更新・削除）エラーとなります。（hookのモードが失敗(Fail)の場合）

フロー図

〇フックのターゲット: 変更セット(CHANGE_SET)

スタックの変更セット作成時にテンプレートを確認します。
評価がNGの場合、変更セットはエラーとなります。（hookのモードが失敗(Fail)の場合）

CloudFormationでスタックを直接更新する操作は可能です。
但しスタック更新時の「変更セットのプレビュー」はエラー表示となります。

〇フックのターゲット: Cloud Control API(CLOUD_CONTROL)

Cloud Control API実行時に設定内容を確認するようです。動作未調査。
CloudFormationでのスタック操作・変更セットの操作には影響しません。
以下の3. Cloud Control API (CCAPI) でhookが利用可能の実装です。

2. Guard ルールやLambda関数を使った簡易なhook実装方法を提供

簡易にhook作成が可能になりました。

CloudFormation Guard ルール または Lambda関数 を利用して作成できます。
image.png

GuardルールとLambda関数でのhook実装は、それぞれPrivate::Guard::xxxx とPrivate::Lambda::XXXX と名前付けされます。
これはAWS::Hooks::GuardHookフックとAWS::Hooks::LambdaHookフックのエイリアスで実装されています。

新メニューフック の一覧。「元のフックタイプ」にエイリアス元のフックが表示されます。
image.png

* Guard/Guard ルール とは

GuardはAWS CloudFormation Guardの略で、CloudFormationテンプレートファイルが独自の制限事項（ルール）に従っているか、を評価するのに利用します。
Guard ルールファイル（ルールセットファイル）へ、テンプレートファイルの制限事項を記載します。

下記ルールの例では、AWS::EC2::Instance に ImageId が存在しなければエラーとなります。

sampleEC2.guard
# sampleEC2.guard

let ec2_instances = Resources.*[Type == 'AWS::EC2::Instance']

rule IMAGEID_NOT_FOUND_ERROR
  when %ec2_instances !empty {
    %ec2_instances.Properties.ImageId exists
}

次の例では、S3Express の必須属性 DataRedundancyとLocationNameをチェックする３つのルールを記載しています。

sampleS3Express.guard
# sampleS3Express.guard

let s3express   = Resources.*[Type == 'AWS::S3Express::DirectoryBucket']
let s3expressLN = Resources.*[Type == 'AWS::S3Express::DirectoryBucket' Properties.LocationName is_string ]

rule S3EXPRESS_DATAREDUNDANCY_VALUE_ERR
  when %s3express !empty {
    %s3express.Properties.DataRedundancy == 'SingleAvailabilityZone'
  }

rule S3EXPRESS_LOCATIONNAME_MUST_EXIST
  when %s3express !empty {
    %s3express.Properties.LocationName exists
  }

rule S3EXPRESS_LOCATIONNAME_IS_WRONG
  when %s3expressLN !empty {
    %s3expressLN.Properties.LocationName in
      ['use1-az4','use1-az5','use1-az6','use2-az1','use2-az2','usw2-az1','usw2-az3','usw2-az4','aps1-az1','aps1-az3','apne1-az1','apne1-az4','euw1-az1','euw1-az3','eun1-az1','eun1-az2','eun1-az3']
      << check latest LocationName list at https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-Endpoints.html >>
  }

AWS CloudFormation 詳解
6章 CloudFormation用ツール
6-5 AWS CloudFormation Guard(cfn-guard)
6-5-3 ルールセットファイル（ガードファイル）の文法

今回の拡張により、Guard ルールで直接hookの評価が実装できるようになりました。
利用時はGuard ルールファイルをS3へ保存しS3 URLで指定します。

3. Cloud Control API (CCAPI) でhookが利用可能

CCAPI はCloudFormationと、それ以外のIaC用に共通で提供されているAPIです。
CloudFormation以外でCCAPIを利用した操作でもhookが利用可能になりました。

Guard ルールでhookを作成して新機能を確認

Web管理コンソール

Web管理コンソール左のメニューに「フック」(hooks) が追加されています。
image.png

フックのトップ画面。11/24現在、なぜか左メニューが英語になります。
image.png

「フックの概要(hooks overview)」も追加されています。
こちらは hook 機能の紹介です。
image.png

フックを作成（Guardを利用）

先に、Guard ルールファイル（sampleS3Express.guard）を同じリージョンのS3バケットへ保存しておきます。

「フックを作成」ボタンで「Guardを利用」を指定します。
image.png

ステップ１
ルールファイルのS3 URIを指定して、「次へ」ボタンで進みます。
image.png
＊「Guard出力レポートのS3バケット」を指定すればguardの評価結果などをログ出力できます。

ステップ２
フック名、フックのターゲット、アクション、フックのモード、実行ロールを指定します。
image.png

ステップ３
デフォルトままにしておきます。
なお、ステップ２でフックのターゲットに「スタック」を指定した場合、「リソースフィルター」は空欄にしてください。指定すると動作しない現象を確認しています。
image.png

ステップ４
設定内容が表示されます。確認して「フックをアクティブ化」をクリックします。
image.png

作成完了画面
image.png

今回はフック「Private::Guard::S3ExpressCheckProperties」が作成されました。
image.png

スタック作成のテスト

不正なスタックを作成して動作を確認してみます。
下記 sampleS3ExpressError.yaml ファイルを使います。LocationNameが不正です。
リソースタイプ AWS::S3Express::DirectoryBucketについてはこちら をご覧ください

sampleS3ExpressError.yaml
Resources:
  DirectoryBucket:
    Type: AWS::S3Express::DirectoryBucket
    Properties:
      DataRedundancy: SingleAvailabilityZone
      LocationName: ERRORapne1-az99

スタックメニューから、「スタックの作成」ボタンの「新しいリソースを使用（標準）」を指定します。
image.png

ステップ１
「テンプレートファイルのアップロード」でsampleS3ExpressError.yaml ファイルをアップロードします。
image.png

ステップ２
スタック名を指定します。
image.png

ステップ３
全てデフォルトままで「次へ」
image.png

ステップ４
設定を確認して「送信」ボタン
image.png

イベントにて、スタック作成が失敗しているのを確認します。
フックの呼び出しが２つ表示されています。
image.png

フックの呼び出しをクリックすると情報が確認できます。下記はフックが開始したメッセージです。
image.png

フック名 Private::Guard::S3ExpressCheckProperties がエラーを発生させています。
image.png

理由には、Guardルールファイルで検知対象となったルール名が表示されます。

"フックのスタータス理由"
Hook failed with message: Template failed validation, the following rule(s) failed: 
S3EXPRESS_LOCATIONNAME_IS_WRONG.

「Guard出力レポートのS3バケット」を有効にした場合は、出力先も表示されます。
image.png

終わりに

今回のhookの拡張には、組織統制の面だけでなく、テンプレート設定不備などの事前チェックとしての活用の可能性も感じます。

フックのターゲット STACK / Resources の違いと使い分けの説明、Lambdaでの作成例なども、時間ができれば書きたいのですが。。

3
3
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
3
3

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?