DockerEngineAPIの使用を開始する方法

2022/06/08

dockerDocker Engineは、 CLIなしでコンテナーを管理するために使用できるRESTAPIを提供します。APIは、HTTPネットワーク呼び出しを使用して同等の機能を提供します。お気に入りのプログラミング言語を使用して標準のDocker操作を作成するか、ホストの1つをリモートで管理できます。CLIは、組み込みコマンドを提供するために内部的に同じAPIに依存しています。

この記事では、APIの有効化と使用の基本について説明します。特定のユースケースを念頭に置いている場合は、APIリファレンスドキュメントを参照して、必要なエンドポイントを決定してください。

DockerEngineAPIを有効にする

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ソケットはデフォルトで保持されるため、DockerCLIは再構成しなくても引き続き機能します。ポート2375は、Dockerの慣例により使用されます。環境に合わせて自由に変更してください。

systemdサービスの構成ファイルを編集することで、Dockerが常にこれらの設定で起動するようにすることができます。編集または作成し/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

これで、でDockerEngineAPIを操作する準備が整いました127.0.0.1:2375。

安全上の注意

上記の手順では、保護なしでAPIを公開しています。ホストのポート2375にアクセスできる人は誰でも、Dockerデーモンに任意のコマンドを送信したり、新しいコンテナーを起動したり、ディスクにイメージを追加したり、既存のワークロードを強制終了したりできます。

Dockerをネットワークに意図的に公開しない限り、ポートへの接続をブロックするようにファイアウォールを構成する必要があります。リモートアクセスを有効にする場合は、デーモンソケットでTLSを構成して、認証されたクライアントへのアクセスを制限する必要があります。

TLSが有効になっている場合は、各クライアントにデーモンのCAをインストールする必要があります。リクエストするたびに、クライアント証明書とクライアントキーを提供する必要があります。実行する必要のある手順は、使用しているツールによって異なります。例を次に示し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の先頭で使用しているバージョンを指定する必要があります。v1.41は、執筆時点でDocker本番ビルドに存在する最新のリリースです。

http://127.0.0.1:2375/v1.41

APIエンドポイントはREST機能ブロックにグループ化されます。これらは、コンテナー、イメージ、ボリュームなどの基本的なDockerオブジェクトタイプに対応します。通常、特定のオブジェクトタイプのAPIは、その名前で始まるベースURLにあります。

# APIs related to container operations

http://127.0.0.1:2375/v1.41/containers

APIは、HTTPクライアントとのすべての通信にJSONを使用します。エンドポイントはJSONリクエスト本文を受け入れ、JSONレスポンスを返します。これにより、プログラミング環境に含まれているJSONライブラリを使用できるため、アプリケーション内でのデータの処理が容易になります。jq端末で実験している場合は、同様のツールを使用して、応答を圧縮、フィルタリング、および並べ替えることができます。

共通のエンドポイント

APIはDockerCLIの機能を複製するため、ここですべてをカバーするにはエンドポイントが多すぎます。代わりに、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を使用する場合、コンテナーの実行は2段階のプロセスです。最初にコンテナを作成してから、別のAPI呼び出しで実行する必要があります。

エンドポイントPOSTにリクエストを送信して、コンテナを作成します。これには、 CLIコマンド/containers/createで受け入れられるフラグに対応するフィールドを持つJSON本文が必要です。docker run

コンテナを作成する最小限の例を次に示します。

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と、コンテナーの作成中に発生した警告が含まれます。/containers/:id/startエンドポイントへの呼び出しでIDを送信します。

curl http://127.0.0.1:2375/v1.41/containers/abc123/start -X POST

これで、コンテナーはDockerホストで実行されます。

コンテナの清掃

エンドポイントPOSTにリクエストを送信して、停止したコンテナを削除します。/containers/prune

curl http://127.0.0.1:2375/v1.41/containers/prune -X POST

ContainersDeletedフィールドと。を含むJSON応答が提供されます。正常に削除されたコンテナIDの配列です。解放されたメモリの合計量をバイト単位で通知します。SpaceReclaimedContainersDeletedSpaceReclaimed

このエンドポイントは、操作を制限するために2つのクエリ文字列パラメーターを受け入れます。このパラメーターは、削除を、またはuntilなどの指定された時間より前に作成されたコンテナーに制限します。このオプションは、指定されたラベルの有無にかかわらずコンテナをフィルタリングします。設定すると、ラベルの付いたコンテナのみが削除されます。until=10muntil=2022-03-01labellabel=demo=exampledemo=example

画像一覧

エンドポイント/images/jsonは、Dockerホストに保存されているイメージを列挙するために使用されます。

curl http://127.0.0.1:2375/v1.41/images/json

フィルタを使用して、応答の内容を変更できます。これらはfilters、Container List APIと同様に、クエリ文字列パラメーターでJSONオブジェクトとして提供されます。注目すべきオプションの1つはreference、特定のタグが付いた画像を選択することですfilters={"reference":"hello-world:latest"}。

画像の作成

APIを使用して、Dockerfilesから新しいDockerイメージを作成できます。アーカイブは/buildエンドポイントに送信する必要があります。tarこのアーカイブの内容は、イメージビルドコンテキストとして使用されます。アーカイブには、ビルド手順を含むDockerfileが含まれている必要があります。

cat context.tar | curl http://127.0.0.1:2375/v1.41/build?t=example-image:latest -X POST

上記のコマンドはDockerデーモンに送信し、内部context.tarを使用してイメージをビルドします。Dockerfileイメージはexample-image:latestDockerホストとしてタグ付けされ、保存されます。

docker buildこのエンドポイントは、コマンドラインインターフェイスの機能に一致するさまざまな追加のクエリ文字列オプションを受け入れます。これには、ビルドによって作成された中間コンテナーを削除するdockerfile=path/to/dockerfileビルドコンテキストのDockerfileへのパスを指定することや、Dockerfileによって参照されるイメージの更新バージョンを取得しようとすることが含まれます。rm=truepull=true

APIでは、ビルドが完了するまでクライアントが接続されたままである必要があります。ネットワークがダウンして接続が閉じられると、ビルドはキャンセルされます。

デーモンイベントログのリスト

APIは、デーモンイベントログデータを表示します。このデータは、 CLIコマンド/eventsからも利用できます。docker eventsこのエンドポイントは、イベントが発生するとリアルタイムでブロードキャストします。

curl http://127.0.0.1:2375/v1.41/events

コンテナの作成、イメージタグ、ボリュームマウント、ネットワークの変更など、いくつかの異なるタイプのイベントが提供されます。クエリパラメータtypeフィールドを使用して、特定のタイプのイベントをフィルタリングできます。filters

# 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をさらに簡単に使用できるようにすることができます。C、C＃、C ++、Go、Java、NodeJS、PHP、Python、Rubyを含むすべての一般的なプログラミング言語では、公式バージョンまたはコミュニティ提供バージョンのいずれかを利用できます。SDKは、APIエンドポイントを便利なクラスと関数にラップしてコードから呼び出すため、Dockerインストールとの対話に必要な定型文を減らします。