ecspresso v2.4.0をリリースしました

Amazon ECSデプロイツール ecspresso v2.4.0 をリリースしたのでお知らせです。

github.com

目玉機能は Jsonnet native functions と ignore.tags です。どうぞご利用下さい。

github.com

新機能

Jsonnet native functions を追加

Add Jsonnet native functions by fujiwara · Pull Request #702 · kayac/ecspresso · GitHub

Jsonnet で利用できる関数として env, must_env, tfstate, ssm など、テンプレート関数と同等のものを追加しました。

これまでの以下のような設定ファイルは

# ecspresso.yml
region: '{{ must_env `AWS_REGION` }}'
cluster: '{{ env `CLUSTER` `default` }}'

Jsonnet でこう書けるようになります。

// ecspresso.jsonnet
local env = std.native('env');
local must_env = std.native('must_env');
{
  region: must_env('AWS_REGION'),
  cluster: env('CLUSTER', 'default'),
  // ...
}

複数の tfstate を使う例。

// ecs-service-def.jsonnet
local env = std.native('env');
local tfstate = std.native('tfstate');
local vpc_tfstate = std.native('vpc_tfstate'); // func_prefix: vpc_
{
  desiredCount: std.parseInt(env('DESIRED_COUNT', '1')),
  loadBalancers: [
    {
      containerName: 'nginx',
      containerPort: 80,
      targetGroupArn: tfstate('aws_lb_target_group.nginx.arn'),
    },
  ],
  networkConfiguration: {
    awsvpcConfiguration: {
      securityGroups: [ vpc_tfstate('aws_security_group.foo.id') ],
      subnets: [
        vpc_tfstate('aws_subnet.az-a.id'),
        vpc_tfstate('aws_subnet.az-b.id'),
      ],
    },
  },

背景

これまで ecspresso では設定・定義ファイルで変数展開する記法として、{{ must_env `FOO` }} や {{ tfstate `aws_subnet.az-a.id` }} のようにGoの text/template の処理時に関数が利用できました。この機能を使うと値をハードコードせず、実行時に環境によって異なる値を展開できるため柔軟に利用できます。

しかし、この記法はあくまで設定・定義ファイルを単純なテキストファイルと見做して置換を行うため、記法がJSONと衝突することがあります。特に文字列以外の値を変数展開したい場合に問題が起きていました。

また、Jsonnet を設定・定義ファイルとして利用する場合には過去のバージョンとの互換性のため、以下の順で処理を行っています。

  1. Jsonnet としてファイルをパースしてJSONに変換
  2. 変換後のJSONをテキストファイルとしてテンプレートで置換

文字列以外をテンプレート記法で展開する場合、最初に Jsonnet としてパースする段階で不正な Jsonnet としてエラーになってしまうため、利用が難しい状態でした。

{
  // 環境変数に数値文字列を入れて数値として扱いたい…
  // が {{ が衝突するのでエラー
  desiredCount: {{ must_env `COUNT` }},
}

{
  // std.parseIntで文字列を数値にすれば…
  // が Jsonnet が解釈される時点ではテンプレート関数は処理されていないのでエラー
  desiredCount: std.parseInt('{{ must_env `COUNT` }}'),
}

v2.4では Jsonnet の関数として各種テンプレート関数と同等のものを追加したため、Jsonnet のみで処理が完結します。これで、記法の衝突を気にせず各種関数を使えます。また、Jsonnet のデフォルトの組み込み関数との組み合わせも可能になりました。

local must_env = std.native('must_env');
{
  desiredCount: std.parseInt( must_env('COUNT') ),
}

diff 処理を外部コマンドで実行できる --external ECSPRESSO_DIFF_COMMAND 追加

Add diff --external. Runs external diff command. by fujiwara · Pull Request #727 · kayac/ecspresso · GitHub

定義ファイルと現在のリソースの差分を表示する ecspresso diff コマンドで、差分表示に外部の任意のコマンドを指定できるようになりました。各位お好みのコマンドを指定して下さい。

たとえば difftastic を引数 --external=difft (もしくは環境変数 ECSPRESSO_DIFF_COMMAND=difft) で指定すると以下のようになります。

指定したコマンドはステータス 0 で終了する必要があります。たとえば一般的な diff(1) コマンドは差分がある場合に非0でexitするため、なんらかのwrapperを使用する必要があります。

特定のタグを無視できる ignore.tags 設定を追加

ECSサービスやタスク定義に ecspresso で管理していないタグが付与されている場合、デフォルトでは ecspresso の定義ファイルに記述されていないタグはデプロイ時に削除されます。

コスト管理タグなど、ecspresso 以外の手段で統一的に管理したいタグがある場合に削除したくないという要望があったため、設定ファイルに記述することでそのタグを無視することができるようになりました。

# ecspresso.yml
ignore:
  tags:
    - foo
    - bar

の場合、タグ foo, bar はデプロイ時に無視されます。ecspresso diff での比較時にも無視されるため、差分になりません。

出力の色づけを制御する --color, --no-color オプション追加

add disables colorized output option by ch1aki · Pull Request #718 · kayac/ecspresso · GitHub

ecspresso diff やログ出力の色づけを制御するオプションを追加しました。デフォルトでは従来通り --color (色づけ有効) です。無効にしたい場合は --no-color (環境変数 ECSPRESSO_COLOR=false) を指定して下さい。

非互換変更

ローリングデプロイ時にサーキットブレーカーが発動した場合、異常終了するように

Exit non-zero status when deployment is rolled back. by fujiwara · Pull Request #733 · kayac/ecspresso · GitHub

これまでは、ローリングデプロイ時に ECS のサーキットブレーカーが発動した場合でも、ecspresso deploy は exit 0 で正常終了してしまうことがありました。

v2.4では、ecspresso deploy 完了時 (サービスが stable になった時点) で、PRIMARY deployment のタスク定義がデプロイ開始時点に指定したものになっていない場合、異常終了するように変更されました。

ecspresso run で --revision と --latest-task-definition を同時に指定できなくなりました

revisionを指定しつつlatestを指定する、という矛盾した指定になるため、エラーになります。(v2.0の時点で将来廃止すると予告済)

ecspresso verify で SSM パラメータストアの値を検証する GetParameter API への fallbackを 廃止

remove fallback to ssm.GetParmater API by fujiwara · Pull Request #720 · kayac/ecspresso · GitHub

v2.3.3 でこれまで GetParameter API を使用していた箇所を、GetParameters (sあり) API を使用するように変更しました。これは ECS/Fargate Agent の挙動にあわせた修正です。

v2.3.x では GetParameters API が権限不足でエラーになった場合に GetParameter API を試すようになっていましたが、v2.4 でこの fallback を廃止しました。

ssm.GetParameter が許可されているが ssm.GetParameters が許可されていない権限で実行した場合、エラーになります。

その他の変更