自分が開発している aqua という OSS について何回かに分けて紹介します。

aqua の概要(aqua とは?)
aqua の何が良いのか
tour of aqua の公式サイト

Shunsuke Suzuki 2022/07/16に更新

概要

CLI Version Manager
Go 製であり、シングルバイナリを PATH 配下に置いて環境変数を設定すれば動く。インストールが容易
Windows, macOS, Linux をサポート ~~macOS と Linux をサポート。 Windows はサポートしていない~~

YAML でツールとそのバージョンを定義し、コマンドを実行するとインストールできる
- aqua のことを知らなくてもなんとなく理解できるシンプルな内容

aqua.yaml

---
# aqua - Declarative CLI Version Manager
# https://aquaproj.github.io/
registries:
- type: standard
  ref: v3.0.0 # renovate: depName=aquaproj/aqua-registry
packages:
- name: cli/cli@v2.12.1
- name: gohugoio/hugo@v0.100.2
- name: stedolan/jq@jq-1.6
- name: hashicorp/terraform@v1.2.2

設定ファイルごとにバージョンを定義でき、同じマシンに同じツールを複数バージョンインストールし、使い分けることが出来る
- pyenv や rbenv で Python や Ruby を複数バージョン使い分けるのと同じイメージだが、 aqua はより汎用的なツール
aqua に似たツールとして asdf があるが、これとの違いは次回以降話す

ユースケース

個人単位: 個人の dotfiles で aqua.yaml を管理し、 PC にツールをインストール
- 複数マシンでバージョンを揃える
- PC の初期セットアップを容易にする
Project 単位: Project 用の Git Repository で管理し、 CI やローカル開発で使うツールを管理
- Project の開発・CI に必要なツールを簡単にインストールできるようにする
- 各開発者や CI で使うツールのバージョンを揃える

組織・ team 単位: 個人の dotfies の組織・ team 版
- 組織・ team でツールのバージョンを揃える
- 組織・team の private なツールを配布する

Registry

各ツールのインストール方法を定義した設定ファイル(YAML or JSON)

e.g.

aqua.yaml でどの Registry を利用するか指定する

aqua.yaml

registries:
- type: standard
  ref: v2.21.0 # renovate: depName=aquaproj/aqua-registry
- type: local
  name: foo
  path: foo.yaml # aqua.yaml と同じディレクトリの foo.yaml を Registry として参照
packages:
- name: cli/cli@v2.12.1
  # standard registry を使う場合は "registry" を省略できる
- name: suzuki-shunsuke/yoo@v1.1.0
  registry: foo # Custom Registry "foo" を参照

aqua.yaml から Registry を切り離す
- ツールのインストール方法を隠蔽し、エンドユーザーはツールとそのバージョンを指定するだけでインストールできるようになる
  - ユーザーは Registry の詳細を知らなくても使える
- 再利用可能になる

Standard Registry

公式でメンテしている Registry
600 以上のツールをサポートしている
Registry の実態はただのテキストファイルなので、 Registry は誰でも自由に作ることが可能だが、多くのユーザーは Standard Registry だけを使えば良い
Standard Registry も OSS なので気軽に Pull Request を投げられる
- aqua 本体に Pull Request を投げるより遥かに簡単に貢献できる
packages の各 package ではそのパッケージが定義されている registry name を指定するが、デフォルトは standard なので基本書かなくて良い

以下の 2 つは同じ。

- name: cli/cli@v2.2.0

- name: cli/cli@v2.2.0
  registry: standard

Custom Registry

Standard Registry ではない、独自の Registry
Private Repository で管理されているツールを配布したりするのにも使える

Reference

Shunsuke Suzuki 2022/06/12に更新

tour of aqua の公式サイト

https://aquaproj.github.io/

Tutorial

ハンズオンで aqua について学べます。
Katacoda を使うと PC に何もインストールしなくてもハンズオンが出来ます。
Katacoda のアカウントを作りたくない人は、 PC でもハンズオンは出来るのでそれをやりましょう。

memo

bin 配下のファイルは aqua-proxy へのシンボリックリンク
- 実態は aqua which コマンドで確認できる

$ which gh
/Users/shunsukesuzuki/.local/share/aquaproj-aqua/bin/gh # これはシンボリックリンク

$ aqua which gh
/Users/shunsukesuzuki/.local/share/aquaproj-aqua/pkgs/github_release/github.com/cli/cli/v2.12.1/gh_2.12.1_macOS_amd64.tar.gz/gh_2.12.1_macOS_amd64/bin/gh # バイナリ

aqua とそれ以外のバージョン管理ツールを併用する場合の注意点

Experimental Feature

Shunsuke Suzuki 2022/06/11

Slide, Blog, etc

https://zenn.dev/topics/aquaclivm

Shunsuke Suzuki 2022/06/23に更新

Renovate による継続的な update

aqua の非常に強力なポイントは、 Renovate で簡単に継続的な自動 update が出来ることです。

GitHub Actions や shell script, asdf でバージョンを指定する場合は通常自動で update されません。
結果として古いバージョンがずっと使われることが少なからずあります。

e.g.

curl -fLq -o tfcmt.tar.gz \
  https://github.com/suzuki-shunsuke/tfcmt/releases/download/v2.0.0/tfcmt_linux_amd64.tar.gz

      - name: golangci-lint
        uses: golangci/golangci-lint-action@v3
        with:
          version: v1.29

.too-versions

nodejs 16.5.0

Renovate の Regex Manager を使えば update は出来ますが、 Regex Manager の設定をツールごとに逐一書くのは面倒ですし、 Renovate に関する知識が必要ですし、設定の確認・問題が合ったときの調査が大変です。

aqua は公式で Renovate Config Preset を提供しており、何も考えなくても update 出来てしまいます。

renovate.json

{
  "extends": [
    "github>aquaproj/aqua-renovate-config#1.1.0"
  ]
}

Shunsuke Suzuki 2022/06/23に更新

aqua の何が良いのか

aqua の競合

手作業でのインストール: (e.g. https://github.com/suzuki-shunsuke/tfcmt/releases からポチポチダウンロード)
シェルスクリプト
Homebrew, apt, yum
asdf
binenv
GitHub Actions, CircleCI Orb, etc
etc

手作業が不要
シェルスクリプトを書かなくて良い
同じマシンでプロジェクトごとにバージョンを切り替えられる
- 色々競合を上げたが、そもそもこれが出来るのは aqua 以外では asdf くらいしかない
ツールのバージョンを固定することで、バージョンの違いによるトラブルを解消する
- ツール実行時に自動でツールのインストールが実行されるため、設定ファイルと実際のバージョンの乖離も起こらない
- インストールが自動で行われるため、態々インストールコマンドを実行する手間がない
Renovate で継続的に update 出来る

コマンドや設定ファイルがシンプルで使うのが簡単
- aqua init: aqua.yaml の scaffold
- aqua g [-i]: ツールの検索、 aqua.yaml への追加
- aqua i [-l] [-a]: インストール

aqua.yaml

registries:
- type: standard
  ref: v2.22.0 # renovate: depName=aquaproj/aqua-registry
packages:
- name: cli/cli@v2.12.1
- name: minamijoyo/tfmigrate@v0.3.3

検索の体験が良い aqua g -i
- fuzzy finder
- -i をつけると aqua.yaml に追記される

aqua g

GitHub Actions などと違い、ローカルでも使える。ツールのインストール方法をローカルと CI で統一できる
Lazy Install が便利
- ツールが実行されるまでツールのインストールを遅延できる
- 余談: Lazy Install というネーミングは、 Vim の Lazy Load にインスパイアされている
- 不要なツールのインストールを省略できる(省略しつつ、いざ実行されたら自動でインストールされる)
  - dotfiles にどんどんツールを追加していくと、不要なものも出てくる
  - CI では使うけど、ローカル開発では使わないようなツールもある
Standard Registry へのツールの追加が楽
- 設定が宣言的な YAML で記述されるため、メンテしやすい

ツールの新しいバージョンが出るたびに CI が実行されるため、信頼性が高い
- GitHub Releases のアセット名が変わったりしたら対応している
- 古いバージョンもサポートするように対応している。 asdf の plugin だとこの対応は plugin 開発者に委ねられるはずで、多分あまりちゃんとしてないのではないかと予想している

renovate-failure

Shunsuke Suzuki 2022/06/12

asdf との比較

https://asdf-vm.com/

シンプルで学習コストが低い
- 個人で使う分には学習コストが高くても自分が使いたいものを使えばよいが、組織・チームに導入していく上では学習コストの低さは特に重要
Renovate で継続的に update 出来る
検索の体験が良い
インストールが自動で行われるため、体験が良い
- asdf の場合、事前にインストールしておかないとコマンドが失敗する
設定ファイルを分割できる
- 特定のツールがアップデートされたときに CI を実行したい場合に便利: https://aquaproj.github.io/docs/tutorial-extras/split-config
asdf plugin と aqua registry の比較
- どの registry を利用するかも aqua.yaml で管理される
- 事前に plugin をインストールしなくて良い
- 設定が宣言的な YAML で記述されるため、メンテしやすい
- ツールの新しいバージョンが出るたびに CI が実行されるため、信頼性が高い
- インストール時に任意のコマンド実行が出来ないので、悪意のあるコードが実行されるリスクが低い

任意のスクリプトが実行できる asdf と違い、 aqua はインストール方法に制限があるため、
仕組み上 asdf のほうが多くのツールをサポートできる。
AWS CLI や Python, Ruby などは aqua でサポートできない。
ただし asdf plugin より aqua registry に登録されているツールの数のほうが実は多い。

aqua は他のツールとも併用できるようになっているので、 aqua でインストールできないツールは aqua 以外で管理してください。