cfndk 0.0.7 → 0.1.2

data/README.md

@@ -1,13 +1,16 @@
 # AWS CloudFormation Development Kit
 
 This is easy operation/integration support tool for AWS CloudFormation.
+This tool drives DevOps and Infrastructure as Code.
+
+[![CircleCI](https://circleci.com/gh/Amakata/cfndk/tree/master.svg?style=svg)](https://circleci.com/gh/Amakata/cfndk/tree/master)
 
 このツールは、AWS CloudFromationのための簡単な運用/構築サポートツールです。
 
 kumogata, SparkleFormation, CoffeeFormation など、CloudFormationのテンプレートを書かずにDSLで表現するツールには様々な物があります。
 しかし、これらのツールはサードパーティツールであるため、CloudFormationの対応への追従に不安がのこります。
-本ツールは、標準のCloudFromationテンプレートの枠組みを変えずに、その利用を支援するツールとなっています。
-最悪このツールが使えなくなっても僅かなコストで標準のAWS CLIを使ってオペレーションを続行することが可能です。
+本ツールは、標準のCloudFromationテンプレートの枠組みを変えずに、その利用を支援するツールをを目指しています。
+最悪の場合、このツールが使えなくなっても僅かなコストで標準のAWS CLIを使いオペレーションを続行することが可能です
 
 ## ハイライト
 
@@ -15,14 +18,20 @@ kumogata, SparkleFormation, CoffeeFormation など、CloudFormationのテンプ
 * 複数のスタックの依存関係を考慮した操作
 * CloudFormationでバージョンコントロールシステムと連動した継続的インテグレーションのための基盤対応
 * Keypairの作成/削除
+* コマンド、サブコマンド、冪統性を考慮したコマンドライン体系、オプションの整理、ヘルプの追加
+* チェンジセットの作成/実行/削除/レポート
+* Keypair/スタック毎のregionのサポート
+* 512000バイト以上の大きなテンプレートファイルの場合に自動的にS3にテンプレートファイルをアップロードして処理する機能
+* aws cloudformation package相当の機能(nested templateやlambda functionの自動アップロード) (experimental)
+* cfndk全体での共通設定
 
-## インストール
+## Install
 
 ```
 $ gem install cfndk
 ```
 
-## 使い方
+## Usage
 
 ```
 $ mkdir cfn-project
@@ -31,11 +40,11 @@ $ cfndk init
 $ export AWS_REGION=ap-northeast-1
 $ export AWS_PROFILE=default
 $ cfndk create
-$ cfndk report-event
+$ cfndk report
 $ cfndk destroy -f
 ```
 
-## Credentials設定
+## Credentials configuration
 
 次の順番でCredentialsを評価して最初に有効なCredentialsを使用します。
 
@@ -50,57 +59,32 @@ $ cfndk destroy -f
 4. EC2/ECS Instance ProfileによるCredentials
    * AWS_CONTAINER_CREDENTIALS_RELATIVE_URI環境変数が設定された場合のみECSが使われます。
 
-## コマンド
-
-```
-cfndk [cmd] [options]
-```
+## Command
 
-### [cmd]
+### ```init```
 
-#### ```init```
-
-カレントディレクトリにcfndk.yamlのひな形を作成します。
+カレントディレクトリにcfndk.ymlのひな形を作成します。
 
 ```
-cfndk init [option]
+cfndk init
 ```
 
-#### ```create```
-
-cfndk.yamlで定義されているスタックを作成します。
-
-```
-cfndk create [option]
-```
+### ```create```
 
-#### ```update```
+cfndk.ymlで定義されているキーペアとスタックを作成します。
 
-cfndk.yamlで定義されているスタックを更新します。
+```cfndk create [option]```
 
-```
-cfndk update [option]
-```
 
-#### ```create-or-changeset```
+### ```destroy```
 
-cfndk.yamlで定義されているスタックが存在しない場合は作成を、存在する場合はチェンジセットを作成します。
-チェンジセットの実行は行いません。
-コマンドを実行後に手動で実行する必要があります。
-
-```
-cfndk create-or-changeset [option]
-```
-
-#### ```destroy```
-
-cfndk.yamlで定義されているスタックを削除します。
+cfndk.ymlで定義されているるキーペアとスタックを削除します。
 
 ```
 cfndk destroy [option]
 ```
 
-#### ```generate-uuid```
+### ```generate-uuid```
 
 UUIDを生成して標準出力に出力します。
 
@@ -117,67 +101,96 @@ cfndk destroy
 unset CFNDK_UUID
 ```
 
-#### ```validate```
+### ```report```
 
-cfndk.yamlで定義されているスタックのテンプレートをvalidationします。
+cfndk.ymlで定義されているスタックについてレポートします。
 
-#### ```report-event```
+```
+cfndk report [option]
+```
+### ```keypair```
 
-cfndk.yamlで定義されているスタックのイベント情報をレポートします。
+cfndk.ymlで定義されているキーペアの作成/削除を行うサブコマンドです。
+
+詳細は
 
 ```
-cfndk report-event [option]
+cfndk keypair help
 ```
 
-#### ```report-stack```
+で確認できます。
+
+### ```stack```
+
+cfndk.ymlで定義されているスタックの作成/更新/削除/レポート/テンプレート検証を行うサブコマンドです。
 
-cfndk.yamlで定義されているスタックの情報をレポートします。
+詳細は
 
 ```
-cfndk report-stack [option]
+cfndk stack help
 ```
 
-#### ```report-stack-resource```
+で確認できます。
 
-cfndk.yamlで定義されているスタックのリソース情報をレポートします。
+
+### ```changeset``` (experimental)
+
+cfndk.ymlで定義されているスタックのチェンジセットの作成/実行/削除/レポートを行うサブコマンドです。
+
+詳細は
 
 ```
-cfndk report-stack-resource [option]
+cfndk changeset help
 ```
 
-### [option]
+で確認できます。
+
+### option
 
 #### ```-v --verbose```
 
 実行時に詳細な情報を表示します。
 
-#### ```-c, --config_path cfndi.yml```
+#### ```-c, --config-path=cfndk.yml```
 
 カレントディレクトリのcfndi.ymlの代わりに、ファイルを指定します。
 
-#### ```-p, --properties name=value```
+#### ```-p, --properties=name:value```
 
 プロパティを追加します。
 cfndi.ymlのparametersのerb内で値で参照することができます。
 
-#### ```-a, --auto-uuid```
+####  ```-u, --uuid uuid```
 
-UUIDを自動生成し使用します。
-UUIDが指定されるとスタック名に付加されます。
+スタック名、チェンジセット名に指定されたUUIDを使用します。
+UUIDが指定されるとスタック名、チェンジセット名に付加されます。
 またcfndi.ymlのparametersの値で参照することができます。
-```-a```と```-u```は最後に指定されたものが有効になります。
 
-####  ```-u, --uuid uuid```
+スタック名は下記のようになります。
+何も指定されない場合はcfndk.ymlで定義されたスタック名がそのまま使われます。
 
-指定されたUUIDを使用します。
-UUIDが指定されるとスタック名に付加されます。
-またcfndi.ymlのparametersの値で参照することができます。
-```-a```と```-u```は最後に指定されたものが有効になります。
+```[Stack Original Name]-[Stack's UUID]```
+
+####  ```--change-set-uuid uuid```
+
+チェンジセット名に指定されたUUIDを使用します。
+UUIDが指定されるとチェンジセット名に付加されます。
+
+このオプションが指定された場合チェンジセット名は下記のようになります。
+何も指定されない場合はチェンジセット名にはスタック名がそのまま使われます。
 
-#### ```-s, --stack-names name1,name2```
+```[Stack Name]-[Changeset's UUID]```
+
+
+#### ```--stack-names=name1 name2```
 
 指定されたスタック名のみを操作します。
 
+#### ```--keypair-names=name1 name2```
+
+指定されたキーペア名のみを操作します。
+
+
 #### ```--no-color```
 
 メッセージ出力でカラーを抑制します。
@@ -186,29 +199,45 @@ UUIDが指定されるとスタック名に付加されます。
 
 動作の確認メッセージと入力をスキップします。
 
-## 環境変数
+他にもオプションはあります。
+詳細はコマンドヘルプを参照してください。
+
+## Environment Variables
 
 ### ```CFNDK_UUID```
 
 この環境変数が指定されている場合、```--uuid $CFNDK_UUID```が指定されたものとして動作します。
-```-a```や```-u```のほうが優先されます。
+```--uuid```のほうが優先されます。
+
+### ```CFNDK_CHANGE_SET_UUID```
 
+この環境変数が指定されている場合、```--change-set-uuid $CFNDK_CHANGE_SET_UUID```が指定されたものとして動作します。
 
-## cfndk.yaml
+## cfndk.yml
 
 * example
 
 ```
+global:
+  region: ap-northeast-1
+  s3_template_bucket: cfndk-templates
+  timeout_in_minutes: 10
+  role_arn: arn:aws:iam::XXXXXXXXXXX:role/XXXXXXXXXXXXX
+  package: true
+  default_profile: profile_name
 keypairs:
   Key1:
+    region: us-east-1
   Key2:
     key_file: key/key2<%= append_uuid %>.pem
 stacks:
   Stack1:
+    region: us-east-1
     template_file: stack1/stack1.yaml 
     parameter_input: stack1/env.json
     parameters:
       VpcName: Prod<%= append_uuid %>
+    package: true
   Stack2:
     template_file: stack2/stack2.yaml 
     parameter_input: stack2/env.json
@@ -218,16 +247,29 @@ stacks:
       - CAPABILITY_IAM
       - CAPABILITY_NAMED_IAM
     depends:
-      - Stack1      
+      - Stack1
     timeout_in_minutes: 10
 ```
 
 ```
+global:
+  region: [String]
+  s3_template_bucket: [String]
+  timeout_in_minutes: [Integer]
+  package: [Boolean]
+  default_profile: [String]
+  pre_command: [String]
+  post_command: [String]
 keypairs:
   [String]:
+    region: [String]
     key_file: [String]
+    enabled: [Boolean]
+    pre_command: [String]
+    post_command: [String]
 stacks:
   [String]:
+    region: [String]
     template_file: [String]
     parameter_input: [String]
     parameters:
@@ -239,8 +281,74 @@ stacks:
     timeout_in_minutes: [Integer]
     depends:
       - [String]
-      - [String]      
+      - [String]
+    package: [Boolean]
+    enabled: [Boolean]
+    pre_command: [String]
+    post_command: [String]
+```
+
+### ```global:```
+
+全体設定を定義します。
+
+#### region (デフォルト: us-east-1)
+
+全体で利用するリージョンを指定します。
+指定されない場合は、AWS_REGION環境変数の値をリージョンとして使用します。
+AWS_REGIONも指定されない場合はus-east-1を利用します。
+
+#### timeout_in_minutes (デフォルト: 1)
+
+全体で利用するタイムアウト時間を分で指定します。
+
+#### role_arn
+
+利用するロールのARN
+
+#### s3_template_bucket (デフォルト: cfndk-templates)
+
+スタックのCloudFormationテンプレートファイルをアップロードするS3のバケット名を指定します。
+
+実際のバケット名は
+```
+[region]-[s3_template_bucket]
 ```
+が使用されます。
+regionはスタック毎で指定されたものを利用します。
+
+S3バケットは一日で自動的に中身のオブジェクトが削除されるように設定されます。
+
+#### package (デフォルト: false)
+
+trueを指定した場合に、
+スタックのテンプレートで、ネステッドスタックや、CloudFormationのコードがローカルパス形式で指定されている場合に
+```aws cloudformation package```
+相当の処理を行います。
+
+yaml、jsonの意図しない加工がされる可能性があるためデフォルトではfalseとなっています。
+
+例えば、```package: true```を指定して下記の様に記述すると、 ```./lambda_function``` フォルダをzipアーカイブしてS3にアップロードし、Codeを適切なS3のパスに更新します。
+
+```
+  LambdaFunction:
+    Type: AWS::Lambda::Function
+    Properties:
+      Code: ./lambda_function
+```
+
+#### default_profile
+
+default_profileで指定されたAWSプロファイルを利用してスタックを作成します。
+AWS_PROFILE環境変数が指定された場合にはAWS_PROFILE環境変数が優先して使用されます。
+
+#### pre_command
+
+スタックのcreate、updateやチェンジセットのcreateで、処理の開始前に実施するコマンドを指定します。
+
+#### post_command
+
+スタックのcreate、updateやチェンジセットのcreateで、処理の完了後に実施するコマンドを指定します。
 
 ### ```keypairs:```
 
@@ -254,6 +362,11 @@ cfndkで管理するキーペアを定義します。
 通常は、キーペアを作成するとこの名称が利用されます。
 UUIDを利用すると、```[Keypair Original Name]-[UUID]```のような形式のキーペア名が利用されます。
 
+#### region
+
+キーペアのリージョンを指定します。
+globalのregionより優先されます。
+
 #### key_file
 
 キーペア作成時にキーペアのファイルを指定された相対パスに作成します。
@@ -265,6 +378,17 @@ erbの記法が利用できます。
     key_file: key/key<%= append_uuid %>.pem
 ```
 
+#### enabled　(デフォルト: true)
+
+falseを指定した場合、そのkey pairを無視します
+
+#### pre_command
+
+ker pairのcreateの処理の開始前に実施するコマンドを指定します。
+
+#### post_command
+
+key pairのcreateの処理の完了後に実施するコマンドを指定します。
 
 ### ```stacks:```
 
@@ -278,13 +402,18 @@ stacksの配下には、管理するスタックのオリジナル名を定義
 通常は、stackを作成するとこの名称が利用されます。
 UUIDを利用すると、```[Stack Original Name]-[UUID]```のような形式のスタック名が利用されます。
 
+#### region
+
+スタックのリージョンを指定します。
+globalのregionより優先されます。
+
 #### template_file 
 
-必須。CloudFormationテンプレートファイルのパスをcfndk.yamlからの相対パスで指定します。
+必須。CloudFormationテンプレートファイルのパスをcfndk.ymlからの相対パスで指定します。
 
 #### parameter_input
 
-必須。CloudFormationのパラメータJSONファイルをcfndk.yamlからの相対パスで指定します。
+必須。CloudFormationのパラメータJSONファイルをcfndk.ymlからの相対パスで指定します。
 
 #### parameters
 
@@ -327,7 +456,7 @@ Parameter Valueではerbの記法が利用できます。
 スタックに依存している別のスタックを指定します。
 複数指定することができます。
 dependsを指定すると、create,update,create-or-changeset,destoryのコマンドを実行する際に、依存関係に従ってスタックを処理します。
-dependsが循環するような指定をすることはできません。
+存在しないタスタックやdependsが循環するような指定をすることはできません。
 
 ```
     depends:
@@ -335,7 +464,29 @@ dependsが循環するような指定をすることはできません。
       - Stack2  
 ```
 
-#### timeout_in_minutes (デフォルト: 1)
+#### package (デフォルト: false)
+
+trueを指定した場合に、
+スタックのテンプレートで、ネステッドスタックや、CloudFormationのコードがローカルパス形式で指定されている場合に
+```aws cloudformation package```
+相当の処理を行います。
+
+yaml、jsonの意図しない加工がされる可能性があるためデフォルトではfalseとなっています。
+
+例えば、```package: true```を指定して下記の様に記述すると、 ```./lambda_function``` フォルダをzipアーカイブしてS3にアップロードし、Codeを適切なS3のパスに更新します。
+
+```
+  LambdaFunction:
+    Type: AWS::Lambda::Function
+    Properties:
+      Code: ./lambda_function
+```
+
+#### enabled　(デフォルト: true)
+
+falseを指定した場合、そのスタックを無視します
+
+#### timeout_in_minutes
 
 スタックを作成する際などのタイムアウト時間を分で指定します。
 
@@ -343,20 +494,62 @@ dependsが循環するような指定をすることはできません。
     timeout_in_minutes: 5
 ```
 
+#### pre_command
+
+スタックのcreate、updateやチェンジセットのcreateで、処理の開始前に実施するコマンドを指定します。
+
+#### post_command
+
+スタックのcreate、updateやチェンジセットのcreateで、処理の完了後に実施するコマンドを指定します。
+
 
 ### erbで使用できるメソッド
 
   * ```append_uuid(glue='-')```
 
-    UUIDガ指定されている場合、```[glueの文字列] + [UUID]```を返します。
+    スタックのUUIDガ指定されている場合、```[glueの文字列] + [Stack's UUID]```を返します。
     UUIDが指定されてい無い場合は空文字が返ります。
     glueで接続文字を置き換えることができます。
 
   * ```uuid```
 
-    UUIDを返します。
+    スタックのUUIDを返します。
     UUIDが指定されてい無い場合は空文字が返ります。
 
   * ```properties(key)```
 
     オプション```--properties```で指定したキーに対応する値を参照することができます。
+
+## Execution Environment
+
+### Vagrant
+
+Vagrantを利用してLinux環境とcfndkのインストールを行うリファレンス環境を用意しました。
+
+```
+cd vagrant
+vagrant up
+vagrant ssh
+```
+
+### Docker
+
+gemで直接インストールする代わりに、Dockerコンテナを利用して、cfndkコマンドを実行できるようにします。
+
+```
+cp docker/cfndk.sh /usr/local/bin/cfndk.sh
+chmod +x /usr/local/bin/cfndk.sh
+AWS_PROFILE=default cfndk.sh help
+```
+
+## Test
+
+cfndkコマンドのテストを行うことができます。
+CFNDK_COVERAGE環境変数に1を設定することで、カバレッジを取ることができます。
+
+```
+export AWS_REGION=ap-northeast-1
+export AWS_PROFILE=default
+export CFNDK_COVERAGE=1 
+bundle exec rspec
+```