Docker CLI Plugin とは

概要

Docker CLI Pluginってご存知でしょうか？

つい最近GAとなったDocker Compose V2^[1]やこちらも最近発表されたdocker sbomコマンド^[2]がDocker CLI Pluginとして提供されています。
こいつがなんなのかよく分かってなかったので調べてみました。

Docker CLI Pluginについて公式のドキュメントがほとんど存在していませんでした。
調べるにあたって以下の記事が大変役立ちました。
https://zenn.dev/skanehira/articles/2021-06-03-new-docker-compose

Docker CLI Plugin

Dockerコマンドにプラグインとしてサブコマンドを追加して機能を拡張できる機構です。
Docker v19.03から追加されているようです。
けっこう前からあるんですね、まったく知りませんでした。

プラグインの使用例

$ docker compose up

$ docker sbom イメージ名

docker infoコマンドを叩くと現在インストールされているプラグインが表示できます

$ docker info
Client:
 Context:    default
 Debug Mode: false
 Plugins:
  buildx: Docker Buildx (Docker Inc., v0.8.2)
  compose: Docker Compose (Docker Inc., v2.4.1)
  sbom: View the packaged-based Software Bill Of Materials (SBOM) for an image (Anchore Inc., 0.6.0)
  scan: Docker Scan (Docker Inc., v0.17.0)

Docker Engineの機能を拡張する仕組みとしてDocker Pluginというものが存在しますが、これはまた別の仕組みなので混同しないように注意が必要です。
https://docs.docker.com/engine/extend/plugin_api/

プラグインに必要な要素

Docker CLI Pluginは以下の要件を満たしている必要があります。

• プラグイン名がdocker-で始まっていること
• docker-cli-plugin-metadataサブコマンドが実装されていること

Metadataのスキーマ

docker-cli-plugin-metadataサブコマンドは、以下のMetadata構造体に従ったJSONを出力するように実装します

https://github.com/docker/cli/blob/4cc4385075205409c835454f6e5055147d8495b4/cli-plugins/manager/metadata.go

参考までにDocker Compose V2では以下のようになっていました

Docker Compose V2 の例

{
  "SchemaVersion": "0.1.0",
  "Vendor": "Docker Inc.",
  "Version": "v2.3.3",
  "ShortDescription": "Docker Compose"
}

プラグインのインストール

docker-からはじまる実行ファイルを特定のディレクトリに配置することで、Dockerコマンドのサブコマンドしてプラグインが使えるようになります。

• ユーザーごとのインストールの場合 ➡ $HOME/.docker/cli-plugins/
• システムへのインストールの場合 ➡ /usr/local/lib/docker/cli-plugins/

プラグインの作り方

Docker CLIのリポジトリに、Docker CLI Pluginのサンプルコードがあったのでこれを参考にしました。
https://github.com/docker/cli

https://github.com/docker/cli/blob/4cc4385075205409c835454f6e5055147d8495b4/cli-plugins/examples/helloworld/main.go

プラグインのEntrypointとなる関数plugin.Run()が用意さているのでこれを利用します。

https://github.com/docker/cli/blob/master/cli-plugins/plugin/plugin.go#L54-L79

前述のDocker CLI Pluginの要件を満たしていればいいので必ずしもGoで書く必要はありません。

実装

docker psxという名前で、docker composeで作成されたプロジェクトごとにコンテナを表示する簡単なプラグインを作ってみました。
https://github.com/kagamirror123/docker-psx

Cobra^[3]のお作法に倣ってディレクトリ構成は以下のようにしました

.
├── commands
│   └── root.go
├── go.mod
├── go.sum
└── main.go

main.goにplugin.Run()を宣言して、メタデータを記述します。

main.go

package main

import (
	"github.com/docker/cli/cli-plugins/manager"
	"github.com/docker/cli/cli-plugins/plugin"
	"github.com/docker/cli/cli/command"
	"github.com/kagamirror123/docker-psx/commands"
	"github.com/spf13/cobra"
)

func main() {

	plugin.Run(func(dockerCli command.Cli) *cobra.Command {
		return commands.NewRootCmd("psx", dockerCli)
	},
		manager.Metadata{
			SchemaVersion:    "0.1.0",
			Vendor:           "kagamirror",
			Version:          "v0.0.1",
			ShortDescription: "this plugin display containers by compose project",
			URL:              "https://github.com/kagamirror123/docker-psx",
		})
}

commands/root.goに実際の処理を書いていきます

commands/root.go

func NewRootCmd(name string, dockerCli command.Cli) *cobra.Command {
	cmd := &cobra.Command{
		Short: "psx",
		Use:   name,
		Run: func(cmd *cobra.Command, _ []string) {
			// ここに処理を書く
		}
	}
}

配置

ビルドして、所定のディレクトリに配置します

$ go build

$ mkdir -p ~/.docker/cli-plugins/
$ chmod +x docker-psx
$ mv docker-psx ~/.docker/cli-plugins/

ちゃんと追加されているかを確認します

$ docker info
Client:
 Context:    default
 Debug Mode: false
 Plugins:
  buildx: Docker Buildx (Docker Inc., v0.8.2)
  compose: Docker Compose (Docker Inc., v2.4.1)
  psx: this plugin display containers by compose project (nkagamirror, v0.0.1)  # ⬅追加された！
  sbom: View the packaged-based Software Bill Of Materials (SBOM) for an image (Anchore Inc., 0.6.0)
  scan: Docker Scan (Docker Inc., v0.17.0)

実行

$ docker psx

無事dockerのサブコマンドとして実行するこができいい感じに表示できました

参考

https://zenn.dev/skanehira/articles/2021-06-03-new-docker-compose#docker-cli-pluginについて
https://github.com/docker/cli/blob/master/cli-plugins
https://github.com/docker/cli/issues/1534

脚注

1. V2の1.0のリリース自体は2021年10月にされていましたが、その時点ではGAではなかったらしい。
   Announcing Compose V2 General Availability - Docker

2. Announcing Docker SBOM: A step towards more visibility into Docker images - Docker

3. GoでCLIツールを作成するためのフレームワーク https://github.com/spf13/cobra