Docker Engine APIの使い方を始めるには
DockerエンジンはREST APIを公開しており、これを使用してコンテナを制御できます。
dockerCLI。APIはHTTPネットワークコールを使用して同等の機能を提供します。お気に入りのプログラミング言語を使用して一般的なDocker操作をスクリプト化したり、ホストの1つをリモートで制御したりできます。CLIは内部的に同じAPIに依存して、組み込みコマンドを提供しています。
この記事では、APIを有効にして使用するための基本について説明します。特定の使用例がある場合は、APIリファレンスドキュメントを参照して必要なエンドポイントを特定してください。
DockerエンジンのAPIを有効にする
APIはDockerエンジンと統合されています。機能しているDockerホストは、すでにAPIのやり取りに対応しています。このサービスを公開するには、DockerデーモンをTCPソケットにバインドする必要があります。または、デフォルトのUnixソケットの代わりにバインドすることもできます。開始
dockerdと共に
-Hリスニングするソケットを指定するフラグ:
sudo dockerd -H unix:///var/run/docker.sock -H tcp://0.0.0.0:2375このコマンドは、ポート2375でAPIを公開します。デフォルトのUnixソケットは保持されるため、Docker CLIは再構成なしで引き続き機能します。ポート2375は慣例としてDockerに使用されますが、環境に合わせて変更しても構いません。
これらの設定でDockerを常に起動するには、systemdサービス設定ファイルを編集します。/etc/systemd/system/docker.service.d/options.confを編集または作成し、ExecStart行を見つけて、追加のフラグを含むように修正します:
[Service]
ExecStart=/usr/bin/dockerd -H unix:///var/run/docker.sock -H tcp://0.0.0.0:2375
変更を適用するには、systemd 設定を再読み込みしてください:
sudo systemctl daemon-reloadこれで、127.0.0.1:2375 の Docker Engine API と対話できる準備が整いました。
セキュリティに関する注意事項
上記の手順では、APIが全く保護されずに公開されます。あなたのホストのポート2375にアクセスできる誰でも、Dockerデーモンに任意のコマンドを送信し、新しいコンテナを起動したり、ディスクをイメージで埋めたり、既存の作業負荷を破壊したりすることができます。
ファイアウォールは、ネットワーク上でDockerを意図的に公開しない限り、ポートへの接続をブロックするように設定する必要があります。リモートアクセスを有効にしたい場合は、認証されたクライアントのアクセスを制限するために、デーモンソケットのTLSを設定する必要があります。
TLSが有効な場合、各クライアントにデーモンの証明書認証局をインストールする必要があります。リクエストを行うたびにクライアント証明書とクライアントキーを提供しなければなりません。必要な手順は使用しているツールによって異なります。以下はcurlの例です:
curl https://127.0.0.1:2375/v1.41/containers/json --cert client-cert.pem --key client-key.pem使用ケースによっては、TCPソケットを全くバインドする必要がないかもしれません。もしクライアントがUnixソケットをサポートしている場合、接続にDockerの既存のソケットを使用することができます:
curl --unix-socket /var/run/docker.sock http://localhost/v1.41/containersこれはTCPソケットの意図しない露出を危険にさらすよりも、より安全な選択となることがあります。
APIを使用して
APIはバージョン管理されたエンドポイントを使用しているため、リクエストおよびレスポンスフォーマットの特定のバージョンに固定できます。各エンドポイントURLの最初に使用しているバージョンを示す必要があります。執筆時点での本番Dockerビルドに存在する最新のリリースはv1.41です。
http://127.0.0.1:2375/v1.41APIエンドポイントはRESTの機能単位にグループ化されています。これらは、コンテナ、イメージ、ボリュームなど、Dockerの基本的なオブジェクトタイプにマッピングされます。特定のオブジェクトタイプのAPIは、通常、その名前で始まるベースURL内にあります。
APIs related to container operations
http://127.0.0.1:2375/v1.41/containers
APIはすべてのデータ交換にJSONを使用します。エンドポイントはJSONリクエストボディを受け入れ、JSONレスポンスを返します。これにより、プログラミング環境に含まれているJSONライブラリを使用してアプリケーション内のデータ処理が簡素化されるはずです。ターミナルで実験する際には、jqのようなツールを使用して、レスポンスを圧縮、フィルタリング、並べ替えることができます。
一般的なエンドポイント
このAPIはDockerのCLIの機能を複製するため、すべてのエンドポイントをここでカバーするのは難しいです。代わりに、Dockerのコア機能に関連する最も一般的に使用されるいくつかのオプションを示します。
コンテナのリスト
ホスト上のコンテナの完全なリストは、/containers/jsonエンドポイントから取得できます。
curl http://127.0.0.1:2375/v1.41/containers/json
デフォルトでは、実行中のコンテナのみが表示されます。停止したコンテナも含めるには、クエリ文字列にall=trueを追加してください。返されるコンテナの総数をlimitパラメーターで制限できます。例えば、limit=10と設定します。最新に作成された10個のコンテナのみが含まれます。
特定の属性を持つコンテナのリストを絞り込むために、いくつかの異なるフィルターが利用可能です。これらは次の構文で設定されます:
curl http://127.0.0.1:2375/v1.41/containers/json?filters={"name":"demo"}このURLはdemoコンテナに関連する情報を返します。他のフィルターも同様の方法で表現できます。たとえば、実行中および一時停止中のコンテナを取得するために{"status":["running","paused"]}や、健康なコンテナのみを取得するために{"health":["healthy"]}を使用できます。
新しいコンテナを開始する
APIを使用する場合、コンテナを開始するのは二段階のプロセスです。最初にコンテナを作成し、その後、別のAPIコールで開始する必要があります。
コンテナを作成するには、/containers/create エンドポイントに POST リクエストを送信します。これには、docker run CLI コマンドで受け入れられるフラグに対応するフィールドを持つ JSON ボディが必要です。
こちらはコンテナを作成するための最小限の例です:
curl http://127.0.0.1:2375/v1.41/containers/create
-X POST
-H "Content-Type: application/json"
-d '{"Image": "example-image:latest"}'
JSONレスポンスには新しいコンテナのIDと、その作成に伴う警告が含まれます。IDを/containers/:id/startエンドポイントへの呼び出しに送信します:
curl http://127.0.0.1:2375/v1.41/containers/abc123/start -X POSTコンテナは現在、Dockerホスト上で実行されています。
コンテナの掃除
停止したコンテナを削除するには、/containers/prune エンドポイントに POST リクエストを発行します:
curl http://127.0.0.1:2375/v1.41/containers/prune -X POST
JSONレスポンスには、ContainersDeletedとSpaceReclaimedのフィールドが含まれます。ContainersDeletedは、正常に削除されたコンテナIDの配列です。SpaceReclaimedは、バイト単位で解放された総ストレージスペースを示します。
このエンドポイントは、操作を制限するために2つのクエリ文字列パラメータを受け入れます。untilパラメータは、指定した時刻より前に作成されたコンテナの削除を制限します。例えば、until=10mやuntil=2022-03-01などです。labelオプションは、指定されたラベルを持つかどうかでコンテナをフィルタリングします；label=demo=exampleを設定すると、demo=exampleラベルを持つコンテナのみが削除されます。
リスティング画像
/images/json エンドポイントは、Docker ホストに保存されているイメージを列挙するために使用されます:
curl http://127.0.0.1:2375/v1.41/images/json
応答の内容を変更するためにフィルターを使用できます。これらは、コンテナリストAPIと同様に、filtersクエリ文字列パラメータ内のJSONオブジェクトとして提供されます。一つの注目すべきオプションはreferenceで、特定のタグを持つ画像を選択します：filters={"reference":"hello-world:latest"}.
イメージを構築する
APIを使用して、Dockerfileから新しいDockerイメージをビルドできます。/buildエンドポイントにはtarアーカイブを送信する必要があります。このアーカイブの内容は、イメージのビルドコンテキストとして使用されます。アーカイブには、ビルド用の指示を含むDockerfileが含まれている必要があります。
cat context.tar | curl http://127.0.0.1:2375/v1.41/build?t=example-image:latest -X POST上記のコマンドは、context.tarをDockerデーモンに送信し、その中のDockerfileを使用してイメージをビルドします。イメージはexample-image:latestとしてタグ付けされ、Dockerホストに保存されます。
このエンドポイントは、docker build CLIの機能に一致する追加のクエリ文字列パラメータを多数受け入れます。これには、ビルドコンテキストのDockerfileへのパスを指定するdockerfile=path/to/dockerfile、ビルドによって作成された中間コンテナを削除するrm=true、およびDockerfileで参照されるイメージの更新版を取得しようとするpull=trueが含まれます。
APIは、ビルドが完了するまでクライアントが接続されている必要があります。ネットワークが切断されて接続が閉じられると、ビルドはキャンセルされます。
デーモンイベントログの一覧表示
/events API は、docker events CLI コマンドでもアクセスできるデーモンイベントログデータを表示します。このエンドポイントは、イベントが発生するたびにリアルタイムでイベントをストリーミングします。
curl http://127.0.0.1:2375/v1.41/events
コンテナの作成、イメージタグ、ボリュームマウント、ネットワークの変更など、さまざまな種類のイベントが公開されています。filtersクエリパラメーターのtypeフィールドを使用して、特定の種類のイベントにフィルタリングすることができます:
Only get container events
curl http://127.0.0.1:2375/v1.41/events?filters={'type':'container'}
特定のオブジェクトに関連するイベントに制約を設けることも可能です。
Get events pertaining to the container with ID abc123
curl http://127.0.0.1:2375/v1.41/events?filters={'container':'id'}
他の2つのクエリ文字列パラメータ、sinceおよびuntilを使用すると、履歴イベントを表示するためのタイムスタンプ範囲を指定できます。
システム情報を取得する
Docker Engine APIは、それが実行されている物理ホストに関する情報を取得するために使用できます。
curl http://127.0.0.1:2375/v1.41/info
このエンドポイントは、ホストとDockerデーモンの現在の状態と構成を説明する詳細情報を提供します。応答には、実行中のコンテナ、ポーズ中のコンテナ、停止中のコンテナの数、Dockerのインストールディレクトリへのパス、ハードウェアおよびOSの詳細、クラスタ内で動作しているときのサーバーのSwarm構成が含まれています。
結論
Docker Engine APIは、HTTP経由でホストのDockerデーモンにコマンドを送る方法を提供します。これにより、特定のDocker CLIの動作に依存することなく、プログラム的なインタラクションをスクリプト化することが簡単になります。また、このAPIを使用して、Dockerサーバーをリモートで管理することで、強化された監視とメンテナンスの容易さを実現することもできます。
APIを呼び出すのは簡単なはずですが、TCPソケットの周囲にあるセキュリティ保護に注意する必要があります。TLSで保護されていない限り、ネットワーク上でソケットを公開しないようにしてください。そうすることで、承認されたクライアントのみが接続できます。この追加のセットアップ段階を省略すると、侵入者があなたのデーモンインスタンスを見つけてコマンドを発行し始めた場合、高くつく可能性があります。
自分のアプリケーションでAPIをさらに使いやすくするために、SDKのいずれかを採用できます。C、C#、C++、Go、Java、NodeJS、PHP、Python、Rubyなどのすべての人気プログラミング言語に対して、公式またはコミュニティ提供のオプションが利用可能です。SDKは、APIのエンドポイントを便利なクラスと関数でラップし、コードから呼び出すことができるようにし、Dockerインストールとの対話に必要なボイラープレートの量を減らします。