hookの拡張

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

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

hook とは

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

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

フックには失敗モード（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 が指定可能です。
設定画面の選択肢

〇フックのターゲット: スタック(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関数 を利用して作成できます。

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

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

* 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) が追加されています。

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

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

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

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

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

ステップ１
ルールファイルのS3 URIを指定して、「次へ」ボタンで進みます。

＊「Guard出力レポートのS3バケット」を指定すればguardの評価結果などをログ出力できます。

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

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

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

作成完了画面

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

スタック作成のテスト

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

sampleS3ExpressError.yaml

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

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

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

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

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

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

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

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

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

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

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

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

終わりに

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

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