Amazon ECSデプロイツールのecspressoについて、もうすぐv2.0をリリースする予定ですのでお知らせします。先行してバージョン v1.99.x をプレリリースしていますので、利用できる方はお試し頂ければと思います。
(2022-12-15追記: v2.0.0をリリースしました！)
もし不具合や不審な挙動を見つけた場合、GitHub issue や作者の Twitter (@fujiwara) へのメンションで教えていただけると嬉しいです。
CircleCI Orb をご利用の方に大事なお知らせ
まず最初に大事なお知らせです。CircleCI Orbを利用していて次の条件に両方合致している場合、v2が正式リリースされるとv2がインストールされるため、ワークフローが期待通り動かなくなる恐れがあります。
- CircleCI Orb fujiwara/ecspresso@0.0.15 を利用している
version: latestを指定している
Orbのバージョンを@1.0.0 にあらかじめ変更するか、versionを明示的に v1.7.14 などと明示することをお勧めします。
v2の安定版がリリースされた後、version: latest を指定した場合の挙動は次のようになります。
- fujiwara/ecspresso@0.0.15 (それ以前を含む): v2系の安定版をインストール
- fujiwara/ecspresso@1.0.0 : v1系の安定版をインストール
- ecspresso v2がリリースされた後、@2.0.0をリリース予定です
- fujiwara/ecspresso@2.0.0: v2系の安定版をインストール
なお、GitHub Actionsでは、現時点で以下の挙動になっています。@v1では latest を指定してもv2系がインストールされることはありません。
- kayac/ecspresso@v1 : v1系の安定版最新をインストール
- kayac/ecspresso@v2 : v1.99系のプレリリース版をインストール
- ecspresso v2がリリースされた後、v2系の安定版をリリースするように変更予定です
バージョンを明示的に指定した場合は、v1, v2のリリース状況に関わらず、そのバージョンをインストールします。
v1.99 の利用方法
GitHubのリリースページから､バイナリをダウンロードしてインストールできます。 Release v1.99.5 · kayac/ecspresso · GitHub
homebrewでは、brew install ecspresso@1.99 でインストールできます。これは ecspresso v1 と衝突するため、インストール済の場合は一旦 brew uninstall ecspresso で削除してから ecspresso@1.99 をインストールし直して下さい。
GitHub Actionsでは kayac/ecspresso@v2 で version: latest を指定するか、kayac/ecspresso@v1 で version: v1.99.5 など特定のバージョンを指定できます。
steps: - uses: kayac/ecspresso@v2 with: version: v1.99.5 # or latest
CircleCI Orbでは、fujiwara/ecspresso@1.0.0 を利用して、version に特定のバージョンを指定して下さい。
orbs: ecspresso: fujiwara/ecspresso@1.0.0 jobs: install: steps: - ecspresso/install: version: v1.99.5
v1からv2への変更点
関連するISSUEとPull Request､コントリビューターの方などはドキュメントに記載しています。(もし漏れがあったら教えて下さい)
ecspresso/v1-v2.md at v2 · kayac/ecspresso · GitHub
非互換な変更
基本的にはv1.xと互換を保っています。ただし、次の非互換があります。
ecspresso create コマンドを廃止しました。deployコマンドでサービスを作成できます
事前のサービスの有無に関係なく、常に deploy を実行するだけでよくなりました。
なおこの挙動と Terraformの null_resource を組み合わせることで、TerraformによるECS関連リソースの作成とecspressoのデプロイまでが terraform apply 一発で完了できるようになります。具体的な方法については別途記事にする予定です。
(2022-12-07 追記: カヤックのアドベントカレンダーのほうに書きました) techblog.kayac.com
rollback --deregister-task-definition フラグはデフォルトで真になりました
rollback済のタスク定義を残しておきたい場合(あまりないと思います)、--no-deregister-task-definition を指定できます。
ecspresso render コマンドは、レンダリング対象を指定するフラグの代わりに、引数で指定するようになりました
これまではフラグを何も指定しない場合、空の出力が得られるが正常終了する、という不思議な挙動だったため、必須の引数を指定するように変更しました。複数指定も可能です。
v1
$ ecspresso render --task-definition
v2
$ ecspresso render task-definition service-definition
ecspresso verify コマンドは、ELB関係のAPI呼び出しを taskExecutionRole で行いません
verify時のELB関係のAPI操作を、これまではタスク実行ロールで行うことがありました。
ECSタスク実行ロールには一般的にはELBへの権限は必要がなく、権限を最小化したい場合に不便なため、ｍタスク実行ロールによるELB API呼び出しは行わないようにしました。常に現在のecspressoを実行しているIAM権限で呼び出します。
ecspresso diff --unified フラグはデフォルトで真になりました
短くなるので便利ですね。
ログメッセージの出力でターミナルを同一行で書き換えたり、メッセージを行折り返ししなくなりました
v1ではデプロイ中の進行状況を表示するためにターミナルの同一行を書き換えたり、その都合でメッセージを固定文字数で折り返したりしていました。しかし、
- ecspressoはCI/CD環境で実行される場合も多く、その場合は同一行書き換えに意味がない
- 行が折り返されるとID (task IDとか)をコピーするのに不便
などの理由があったため、ログメッセージは単純に行を送って出力するように変更しました。
設定ファイルでの filter_command 指定は非推奨になりました
filter_commandは、ターミナルでタスクなどを選択する際のキーボード操作をアシストする peco, fzf などのツールを指定する設定です。これは個人向けの性格が強い設定のため、複数人で共通で使用する設定ファイルに定義するのは相応しくないと判断しました。
代わりに 環境変数ECSPRESSO_FILTER_COMMANDを使用して下さい。
設定ファイルの記述も引き続き動作しますが、警告が表示されます。ECSPRESSO_FILTER_COMMANDが指定されている場合はそちらが優先されます。
機能強化
v2で対応予定、としてお待たせしていた機能追加が含まれています！
複数のtfstate読み込みをサポートしました
v1では、読み込む対象のtfstateは1つだけでした。
v2では、プラグイン定義時に func_prefix という設定を指定することで、tfstateごとに呼び出す関数名を変更できます。
# ecspresso.yml plugins: - name: tfstate config: url: s3://tfstate/first.tfstate func_prefix: first_ - name: tfstate config: url: s3://tfstate/second.tfstate func_prefix: second_
このように定義すると、テンプレートで first_tfstate で呼び出すと s3://tfstate/first.tfstate を対象に、second_tfstate を呼び出すと s3://tfstate/second.tfstate を対象にしてtfstate参照を行います。
[ "{{ first_tfstate `aws_s3_bucket.main.arn` }}", "{{ second_tfstate `aws_s3_bucket.main.arn` }}" ]
設定ファイルに Jsonnet が使用できるようになりました
v1では、タスク定義ファイルとサービス定義ファイルがJSONもしくはJsonnet、設定ファイル(ecspresso.yml) がYAMLのみでした。
v2では、設定ファイルに JSON, Jsonnet, YAML のいずれも使用できます。
既存のECSサービスを設定ファイル化する ecspresso init コマンドで --jsonnet を指定することで、全てのファイルがJsonnetで生成されるようになりました。
設定ファイルのデフォルト値は ecspresso.yml のままです。ただし ecspresso.yml が存在しない場合、ecspresso.json, ecspresso.jsonnet を探して見つかったらそれを使用します。
各種ファイルを解釈して標準出力に書き出す ecspresso render コマンドにも --jsonnet フラグが追加されました。
設定ファイルでCodeDeployアプリケーション名とデプロイグループ名を指定できます
CodeDeployを利用する場合、ecspressoはデプロイ対象のECSサービスに関連するCodeDeployアプリケーションとデプロイグループを自動で発見します。
しかしCodeDeployに大量のアプリケーションが存在する場合には、この発見処理のための大量のAPI呼び出しが原因でスロットリングエラーが発生することがありました。
設定ファイルにあらかじめアプリケーション名とデプロイグループ名を明示することで、API呼び出しを減らすことができます。
# ecspresso.yml codedeploy: application_name: myapp deployment_group_name: mydeployment
CodeDeploy でのデプロイ中にプログレスバーが表示されます
デプロイの進行自体はecspresso以外の手段(マネージメントコンソール)で行う必要があります。ecspressoでデプロイ完了を待っている状態で、トラフィックの移行状況がターミナルのプログレスバーに表示されるようになりました。
ecspresso verifyでコンテナイメージのplatformも確認するようになりました
タスク定義でCPUアーキテクチャにARM64を指定している場合に、verifyコマンドでimageを検証する場合にArm64用のイメージが存在するかを確認するようになりました。
SSMパラメータストアを参照するプラグインが追加されました
SSMパラメータストアの値を直接参照できるようになりました。
# ecspresso.yml plugins: - name: ssm
{ "string": "{{ ssm `/path/to/string` }}", "stringlist": "{{ ssm `/path/to/stringlist` 1 }}", "securestring": "{{ ssm `/path/to/securestring` }}" }
秘匿値はタスク定義のsecretsを利用してタスク実行時に取得するべきですが、特に秘匿しなくてもよい値はタスク定義に直接埋め込むことができます。
その他の変更点
見た目の機能の追加/非互換よりも、内部的な変更が実は多かったりします。
AWS SDK Go v2 に切り替えました
AWS SDK Go v1も現時点ではEoL予定はなく引き続き更新されていますが、今後のことを考えて依存ライブラリも含めて v2 への移行を行いました。
CLI option parserを変更しました
alecthomas/kingpin がメンテナンスモードになったため、同作者の alecthomas/kong へ移行しました
単体タスク操作関連のコードを ecsta に切り出しました
ecspresso には tasks, exec など、ECSタスク単体を相手に操作する便利なコマンドがいくつかあります。
これらの操作を ecspresso 管理下以外のタスクにも行いたい需要があったので、ecsta というCLIツールを作成しました。どうぞご利用下さい。
ecspresso側のコマンドはv1と変更ありませんが、内部的にはecstaをライブラリとして呼び出すようになっています。
まとめ
- ecspresso v2をもうすぐリリースします
- v1.99.x を試していただいて、フィードバックを頂けると嬉しいです
- CircleCI Orb @0.0.15 かつ version: latest を指定している方はご注意下さい
