🐳

Docker CLI Plugin とは

2022/05/08に公開

概要

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

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

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 CLI Pluginは以下の要件を満たしている必要があります。

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

Metadataのスキーマ

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

参考までに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

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

実装

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

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のサブコマンドとして実行するこができいい感じに表示できました

result

参考

脚注

V2の1.0のリリース自体は2021年10月にされていましたが、その時点ではGAではなかったらしい。
Announcing Compose V2 General Availability - Docker ↩︎
Announcing Docker SBOM: A step towards more visibility into Docker images - Docker ↩︎
GoでCLIツールを作成するためのフレームワーク https://github.com/spf13/cobra ↩︎

GitHubで編集を提案