CloudFormation CLI ツール rain の Tips

これは何？

• AWS が公式に提供している CloudFormaiton CLI ツールである rain についての使い方メモ
• https://github.com/aws-cloudformation/rain
• https://aws-cloudformation.github.io/rain/
• 各コマンドのオプションについては、自分が気になったものをピックアップしてメモしているので、詳細については help を参照

rain help

• 各コマンドのヘルプを出力しれくれる
• rain help build, rain help deploy のような感じで指定すれば良い

% rain help
Rain is a command line tool for working with AWS CloudFormation templates and stacks

Usage:
  rain [command]

Stack commands:
  cat         Get the CloudFormation template from a running stack
  deploy      Deploy a CloudFormation stack from a local template
  logs        Show the event log for the named stack
  ls          List running CloudFormation stacks
  rm          Delete a running CloudFormation stack
  watch       Display an updating view of a CloudFormation stack

Template commands:
  build       Create CloudFormation templates
  diff        Compare CloudFormation templates
  fmt         Format CloudFormation templates
  merge       Merge two or more CloudFormation templates
  pkg         Package local artifacts into a template
  tree        Find dependencies of Resources and Outputs in a local template

Other Commands:
  console     Login to the AWS console
  help        Help about any command
  info        Show your current configuration

rain info

• https://aws-cloudformation.github.io/rain/rain_info.html
• rain が動作するよう設定されている AWS アカウント, リージョン, IAM 情報を出力する

% rain info
Account:  123456789012
Region:   ap-northeast-1
Identity: arn:aws:iam::123456789012:user/myusername

rain build

• https://aws-cloudformation.github.io/rain/rain_build.html
• CloudFormation template を作成する
• 作成したいリソースのリソースタイプを指定することで、そのリソースを作成するための CloudFormation template の雛形を出力してくれる
  • リソースタイプについては CloudFormation の公式ドキュメントにリファレンスがあるので、適宜参照
    • https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-template-resource-type-ref.html
  • rain build --list でも出力可能だが、
• オプション
  • -b, --bare: オプションのリソースプロパティを全て省略して、最小限のテンプレートを作成する
  • -j, --json: テンプレートを JSON で出力する
  • -l, --list: 全ての CloudFormation リソースタイプを一覧表示する

IAM Role の雛形を出力したい場合…

% rain build AWS::IAM::Role
AWSTemplateFormatVersion: "2010-09-09"

Description: Template generated by rain

Resources:
  MyRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument: {}
      Description: CHANGEME # Optional
      ManagedPolicyArns:
        - CHANGEME
      MaxSessionDuration: 0 # Optional
      Path: CHANGEME # Optional
      PermissionsBoundary: CHANGEME # Optional
      Policies:
        - PolicyDocument: {}
          PolicyName: CHANGEME
      RoleName: CHANGEME # Optional
      Tags:
        - Key: CHANGEME
          Value: CHANGEME

Outputs:
  MyRoleArn:
    Value: !GetAtt MyRole.Arn

  MyRoleRoleId:
    Value: !GetAtt MyRole.RoleId

ミニマムな雛形を出力したい場合…

% rain build --bare AWS::IAM::Role
AWSTemplateFormatVersion: "2010-09-09"

Description: Template generated by rain

Resources:
  MyRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument: {}

rain cat

• https://aws-cloudformation.github.io/rain/rain_cat.html
• 既存の CloudFormation Stack のテンプレートを取得する
  • 既存の CloudFormation Stack は rain ls で取得できる
• オプション
  • -t, --transformed: CloudFormation によって適用された Transform を含むテンプレートを取得する
    • Transform というは CloudFormation の変換機能のこと
      • https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/transform-section-structure.html
    • AWS SAM (Serverless Application Model) や、その他ユーザーが定義した任意の変換が使用されている場合、 Transform が含まれている
  • -u, --unformatted: テンプレートを raw 形式で出力し、フォーマットしない
    • ちゃんと試していないが、インデント等が狂っているテンプレートをデフォルトでは整形しており、そういった整形を無効化してくれるオプションっぽい

% rain cat my-stack

rain console

• https://aws-cloudformation.github.io/rain/rain_console.html
• AWS マネジメントコンソールにログインする
  • rain に設定されているクレデンシャルを使用して AWS コンソールのサインイン URL を作成し、それを Web ブラウザーで開く
  • スタック名を指定した場合、または -service オプションを使用しなかった場合、ブラウザは、そのスタックが選択された状態で開かれる
  • console コマンドは IAM ロールでのみ有効な機能
    • IAM ユーザーを使用している場合は使用できない
• オプション
  • -r, --region: 対象とする AWS リージョン
  • -s, --service: ブラウザで開く AWS サービスの指定。デフォルトでは CloudFormation

% rain console my-stack

rain deploy

• https://aws-cloudformation.github.io/rain/rain_deploy.html
• ローカルの CloudFormation テンプレートを使ってデプロイを行う
  • テンプレートをデプロイする前にパッケージ化する必要がある場合 rain はテンプレートのパッケージ化を行う
  • この時、パッケージ化してデプロイするアーティファクトを保存するために S3 バケットを作成しようとする
    • S3 バケットの名前は rain-artifacts-<AWS account id>-<AWS region> という形式になる
• オプション
  • -d, --detach: デプロイ時にデプロイ完了を待たずにコマンドは終了とする
  • --params: スタックに使用するパラメーターの指定
    • key1=value1, key2=value2 というフォーマットで指定する
  • --tags: スタックに指定するタグ
    • key1=value1, key2=value2 というフォーマットで指定する
  • -y, --yes: deploy 時の確認プロンプトを無効化する

% rain deploy my-template.yaml my-stack

rain diff

• https://aws-cloudformation.github.io/rain/rain_diff.html
• CloudFormation テンプレートを比較する
  • CloudFormation スタックを変更する前に比較を取りたい場合に便利かもしれない
• オプション
  • -l, --long: 変更されていない elements を diff 出力に含める

% rain diff my-template-from.yaml my-template-to.yaml

rain fmt

• https://aws-cloudformation.github.io/rain/rain_fmt.html
• CloudFormation テンプレートをフォーマットする
  • ファイル名を指定しない場合 stdin からテンプレートを読み取る
• エイリアス
  • fmt, format
• オプション
  • -j, --json: JSON 形式で出力
  • -u, --unsorted: テンプレートのプロパティをソートしない
  • -v, --verify: 入力が既に正しくフォーマットされているかを確認して終了する
    • exit status は問題ない場合には 0 で、そうでない場合は 1 となる
  • -w, --write: 出力を stdout ではなくファイルに書き戻す

% rain fmt my-template.yaml
% cat my-template.yaml | rain fmt

rain logs

• https://aws-cloudformation.github.io/rain/rain_logs.html
• 指定したスタックと、そのネストされたスタックのイベントログを表示する
  • デフォルトでは、失敗メッセージ等の有用なメッセージを含むログエントリのみ表示する
• オプション
  • -a, --all: 全てのイベントを出力に含める

% rain logs my-stack
% rain logs my-stack my-resource

rain ls

• https://aws-cloudformation.github.io/rain/rain_ls.html
• CloudFormation スタックを一覧表示する
• オプション
  • -a, --all: 全てのリージョンのスタックを一覧表示する

% rain ls
% rain ls --all

rain merge

• https://aws-cloudformation.github.io/rain/rain_merge.html
• 2つ 以上のテンプレートをマージする
• オプション
  • -f, --force: attributes の衝突について警告しなくなる代わりに名前を変更する
    • Refs, GetAtts 等の名前は変更されない

% rain merge my-template-1st.yaml my-template-2nd.yaml

rain pkg

• https://aws-cloudformation.github.io/rain/rain_pkg.html
• ローカルアーティファクトをテンプレートにパッケージ化する
  • AWS CLI の aws cloudformation package コマンドと同じ機能を実行するが、機能が追加されている
  • rain pkg でパッケージ化されたテンプレートでは、次の rain 固有のディレクティブを使用できる
    • !Rain::Embed <path>: ファイルの内容を文字列としてテンプレートに埋め込む
    • !Rain::Include <path>: ファイルを YAML/JSON として読み取り、結果のオブジェクトをテンプレートに挿入する
    • !Rain::S3Http <path>: <path> を S3 にアップロードし S3 HTTP URL を文字列としてテンプレートに埋め込む
      • <path> としてディレクトリが指定された場合は、最初に zip 圧縮を行う
    • !Rain::S3 <path>: !Rain::S3Http の S3 URI バージョン
    • !Rain::S3 <object>: 次のプロパティを持つオブジェクトを提供する
      • Path: <path>: S3 にアップロードするファイルまたはディレクトリ
      • Zip: true|false: true の場合、ファイルであっても zip 圧縮を行う
      • BucketProperty: <bucket>: BucketProperty と KeyProperty を指定するとパッケージ化する
      • KeyProperty: <key>: アップロードしたファイル or ディレクトリの詳細を、指定したプロパティ名のオブジェクトとしてテンプレートに含める
      • Format: Uri|Http: rain pkg が S3 の場所を返す形式を指定する。デフォルトでは Uri フォーマットとなる
        • BucketProperty と KeyProperty を指定する場合、このプロパティは指定しないこと
• エイリアス
  • pkg, package

% rain pkg my-template.yaml

rain rm

• https://aws-cloudformation.github.io/rain/rain_rm.html
• CloudFormation スタックを削除する
• エイリアス
  • rm, remove, del, delete
• オプション
  • -d, --detach: スタックの削除完了を待たずにコマンドを終了する
  • -y, --yes: 確認プロンプトを表示しない

% rain rm my-stack

rain tree

• https://aws-cloudformation.github.io/rain/rain_tree.html
• ローカルテンプレートで、パラメーター、リソース、アウトプットの依存関係を見つける
• エイリアス
  • tree, graph
• オプション
  • -a, --all: 依存関係の無い要素を含めて、全ての elements を表示
  • -b, --both: 各要素について、その依存関係と DependsOn を表示する
  • -d, --dot: GraphViz DOT format で出力を行う

% rain tree my-template.yaml

rain watch

• https://aws-cloudformation.github.io/rain/rain_watch.html
• CloudFormation スタックのステータスを繰り返し表示する
  • rain で管理しているものではない CloudFormation Stack のデプロイ進行状況を確認できて便利
• オプション
  • -w, --wait: 変化しないスタックの監視を拒否せず、変更が始まるのを待つ

% rain watch my-stack

この記事を試した環境

% sw_vers
ProductName:	macOS
ProductVersion:	11.4
BuildVersion:	20F71
% rain --version
Rain v1.2.0 darwin/amd64