コンテナイメージの情報を HTTP API から取得する

Apr 06, 2019

たまに Docker Registry HTTP API からコンテナイメージの情報を cURL で取得したくなるのだけど、やり方を毎回忘れるのでメモ。

Docker Hub から情報を取得する場合はコンテナイメージが公開/非公開に関わらず、最初に Token を取得する必要がある。Token 取得の仕様はドキュメントが公開されているので、それに従って HTTP リクエストを組み立てていく。

例えば、コンテナイメージ summerwind/h2spec:latest の情報を取得したいとする。Token なしにコンテナイメージの情報を取得しようとすると、以下のように認証が要求される。

$ curl -s "https://registry-1.docker.io/v2/summerwind/h2spec/manifests/latest" | jq -r
{
  "errors": [
    {
      "code": "UNAUTHORIZED",
      "message": "authentication required",
      "detail": [
        {
          "Type": "repository",
          "Class": "",
          "Name": "summerwind/toolbox",
          "Action": "pull"
        }
      ]
    }
  ]
}

Token を発行してもらうには、以下のように https://auth.docker.io/token に対してトークンの発行を要求する。scope パラメーターに情報の取得対象となるイメージ名を指定してリクエストを送信すると、以下のように JSON 形式のレスポンスが返ってくる。このレスポンスの token の値が API へのアクセスに使用する JWT 形式の Token になる。

$ curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:summerwind/h2spec:pull" | jq -r
{
  "token": "eyJhbG...",
  "access_token": "eyJhbG...",
  "expires_in": 300,
  "issued_at": "2019-04-06T07:54:57.977713527Z"
}

先ほど取得した Token を Authorization ヘッダーに指定して再度リクエストを送信すれば、コンテナイメージの情報を取得することができる。

$ curl -s \
    -H "Authorization: Bearer ${TOKEN}" \
    "https://registry-1.docker.io/v2/summerwind/h2spec/manifests/latest" | jq -r
{
  "schemaVersion": 1,
  "name": "summerwind/h2spec",
  "tag": "latest",
  "architecture": "amd64",
  ...
}

非公開のコンテナイメージの情報を参照する場合は、以下のようにして Token の取得時に認証情報の指定が必要になるので注意する。

$ curl -s \
    -H "Authorization: Basic $(echo -n "${USERNAME}:${PASSWORD}" | base64)" \
    "https://auth.docker.io/token?service=registry.docker.io&scope=repository:summerwind/h2spec:pull" | jq -r