Docker Hub 上のリポジトリ

Docker Hub リポジトリは、共同作業者、顧客、Docker コミュニティ全般に対してコンテナの共有を可能にします。 イメージの構築を内部で行っているとして、Docker デーモンを扱っていたり、継続的インテグレーションサービスを利用していたりする場合、これらを Docker Hub リポジトリにプッシュすることができます。 そのリポジトリは、自身の Docker Hub ユーザー、組織で利用するアカウントのいずれでも問いません。

別の方法として Docker イメージのソースコードを GitHub や Bitbucket 上に管理しているなら、「自動ビルド」(Automated build)リポジトリを利用することができます。 これは Docker Hub サービスによってビルドされるものです。 このサービスにはさまざまな機能が提供されているので、詳しくは 自動ビルドのドキュメント を参照してください。

リポジトリ

イメージの検索

Docker Hub のレジストリは、検索インターフェース、あるいはコマンドラインインターフェースを使って検索することができます。 検索の際には、イメージ名、ユーザー名、説明を用いて検索することができます。

$ docker search centos
NAME                                 DESCRIPTION                                     STARS     OFFICIAL   AUTOMATED
centos                               The official build of CentOS.                   1034      [OK]
ansible/centos7-ansible              Ansible on Centos7                              43                   [OK]
tutum/centos                         Centos image with SSH access. For the root...   13                   [OK]
...

上では centosansible/centos7-ansible という 2 つの結果が示されました。 2 つめの結果は、ansible/ というユーザが所有する公開リポジトリであることがわかります。 その一方、1 つめの結果 である centos にはリポジトリに関する情報が明確には示されていません。 というのも 1 つめは 公式イメージ における最上位の名前空間であることを意味しています。 文字 / は、ユーザのリポジトリ名とイメージ名を分けるためのものです。

目的のイメージが見つかったら docker pull <imagename> によってダウンロードします。

$ docker pull centos
latest: Pulling from centos
6941bfcbbfca: Pull complete
41459f052977: Pull complete
fd44297e2ddb: Already exists
centos:latest: The image you are pulling has been verified. Important: image verification is a tech preview feature and should not be relied on to provide security.
Digest: sha256:d601d3b928eb2954653c59e65862aabb31edefa868bd5148a41fa45004c12288
Status: Downloaded newer image for centos:latest

イメージを入手したので、ここからコンテナを実行することができます。

リポジトリ・タグの参照

Docker Hub リポジトリ上の「タグ」(Tags)画面では、利用可能なタグと、関連するイメージのサイズ情報が示されています。

イメージサイズは、そのイメージと親イメージを含んだすべての容量です。 これはイメージを保存する際に docker save によって生成される .tar ファイルの容量でもあります。

タグの一覧

Docker Hub 上でのリポジトリ新規生成

初めて Docker Hub ユーザーを生成した際には「Get started with Docker Hub」画面が表示されます。 ここから「Create Repository」を直接クリックします。 あるいは「Create ▼」メニューを利用して「Create Repository」を実行することもできます。

リポジトリを新規に生成する際には、そのリポジトリをどこに置くかを選択することができます。 1 つは自身の Docker ID 名前空間内です。 もう 1 つは 組織 の名前空間であって、「所有者」(Owners)チームに属している場合です。 リポジトリ名は、その名前空間内においてユニークである必要があります。 そして 2 文字以上 255 文字までで構成され、英小文字、数字、-_ を用いることができます。

「Short Description」(簡易説明)の 100 文字は検索結果に表示されます。 「Full Description」(詳細説明)は、リポジトリの Readme として利用できます。 またマークダウンを使って簡単な書式を加えることができます。

「Create」ボタンをクリックした後は、docker push を実行してこの Hub ベースのリポジトリに対してイメージをプッシュすることが必要です。

リポジトリの Docker Hub へのプッシュ

リポジトリを Docker Hub へプッシュするには、利用している Docker Hub ユーザ名を使って、ローカルイメージに名前をつける必要があります。 また前の手順において生成したリポジトリ名を用いる必要があります。 リポジトリへは複数のイメージを追加することができます。 その際にはイメージを特定するタグを :<tag> のようにつけます(たとえば docs/base:testing )。 このタグ指定を行わなかった場合、タグにはデフォルトとして latest がつきます。 ローカルイメージに名前をつけるのは、ビルド時には docker build -t <hub-user>/<repo-name>[:<tag>] のようにして行いますが、すでにあるローカルイメージに対しては docker tag <existing-image> <hub-user>/<repo-name>[:<tag>]、またコミットの際には docker commit <existing-container> <hub-user>/<repo-name>[:<tag>] としてタグ名を再設定することができます。

このリポジトリを、名前またはタグにより指定したレジストリにプッシュします。

$ docker push <hub-user>/<repo-name>:<tag>

そのイメージがアップロードされます。 こうして開発チームメンバーやコミュニティが利用できるようになります。

星マーク

リポジトリは他の方から星マークをつけてもらうことがあり、逆に他のリポジトリへ星マークをつけることができます。 星マークをつけるのは、好きなリポジトリが何かを公開する方法として使えます。 またお気に入りのリポジトリをブックマークしておくということもできます。

コメント

Docker コミュニティや保守担当メンバーとの間で、リポジトリにコメントを書き込んでやり取りすることができます。 不適切に思うコメントがある場合には、フラグづけを行ってレビューを求めることができます。

コラボレータとそのロール

コラボレータ(collaborator)とは、プライベートリポジトリに対してアクセスする許可を与えた人のことです。 この許可を与えたら、コラボレータはプライベートリポジトリに対して pushpull を行えるようになります。 ただしコラボレータは、管理操作を実行する権限までは与えられません。 したがってリポジトリを削除したり、リポジトリをプライベートから公開に変更したりするようなことはできません。

注釈

コラボレータが他のコラボレータを追加することはできません。 リポジトリに対する管理アクセスが可能なのは、その所有者のみです。

Docker Hub 上において組織とチームに関する機能を利用すれば、コラボレータのより詳細な権限(「読み込み」、「書き込み」、「管理」)を割り当てることが可能になります。 詳細は 組織に関するドキュメント を参照してください。

プライベート・リポジトリ

プライベート・リポジトリは、イメージがあるリポジトリをプライベートに管理できるようにするものです。 自身のアカウント用でも、また組織や開発チーム用でも管理可能です。

Docker Hub 上においてプライベート・リポジトリを使う場合は、Add Repository ボタンから追加することができます。 Docker Hub の 1 ユーザーアカウントに対しては、無料で 1 つのプライベートリポジトリを生成することができます(これはメンバーとなっている組織においては利用できません)。 ユーザーアカウントにおいて、それ以上のプライベートリポジトリを必要とする場合は、Docker Hub プランをアップグレードしてください。

プライベート・リポジトリを生成したら Docker を利用して、イメージの pushpull ができるようになります。

注釈

プライベート・リポジトリにアクセスして作業を進めるには、サインインが必要です。

プライベート・リポジトリは、公開リポジトリと同じようなものです。 しかし公開レジストリ上において、ブラウズしたり中身を検索したりすることはできません。 また公開リポジトリとは異なり、キャッシュは行われません。

プライベート・リポジトリに対して、指定した者からのアクセスを許可にするには「Settings」ページにて設定します。 その設定ページでは、リポジトリのステータス切り替えを行うこともできます(公開からプライベートへ、あるいはその逆)。 プライベート・リポジトリへの切り替えを行う場合には、プライベート・リポジトリ用の利用可能スロットが必要です。 利用可能スロットがない場合は、Docker Hub プランのアップグレードを行ってください。

ウェブフック

ウェブフック(webhook)は、特定のイベントにより駆動される HTTP コールバックです。 Docker Hub リポジトリのウェブフックを使えば、リポジトリ上に新たなイメージがプッシュされた際に、このことを関係者、サービス、他のアプリケーションに通知できます(これは自動ビルドリポジトリでも利用可能です)。 たとえばイメージが公開されたらすぐに、自動テストやデプロイを実行するようにできます。

ウェブフックの追加を行うには、Docker Hub 内の対象リポジトリを表示して、「Settings」ボックス内にある「Webhooks」をクリックします。 ウェブフックが呼び出されるのは、イメージのプッシュが正常に行われたときです。 ウェブフック呼び出しは、JSON 形式による HTTP POST リクエストです。 たとえば以下のようなものです。

JSON 形式のウェブフック例

{
  "callback_url": "https://registry.hub.docker.com/u/svendowideit/busybox/hook/2141bc0cdec4hebec411i4c1g40242eg110020/",
  "push_data": {
    "images": [
        "27d47432a69bca5f2700e4dff7de0388ed65f9d3fb1ec645e2bc24c223dc1cc3",
        "51a9c7c1f8bb2fa19bcd09789a34e63f35abb80044bc10196e304f6634cc582c",
        "..."
    ],
    "pushed_at": 1.417566822e+09,
    "pusher": "svendowideit"
  },
  "repository": {
    "comment_count": 0,
    "date_created": 1.417566665e+09,
    "description": "",
    "full_description": "webhook triggered from a 'docker push'",
    "is_official": false,
    "is_private": false,
    "is_trusted": false,
    "name": "busybox",
    "namespace": "svendowideit",
    "owner": "svendowideit",
    "repo_name": "svendowideit/busybox",
    "repo_url": "https://registry.hub.docker.com/u/svendowideit/busybox/",
    "star_count": 0,
    "status": "Active"
  }
}

注釈

ウェブフックをテストしたい場合、requestb.in のようなツールを利用することをお勧めします。 なお Docker Hub サーバは IP アドレスによるフィルタリングができないので注意してください。

ウェブフック・チェーン

ウェブフック・チェーン(webhook chain)は、ウェブフック呼び出しを複数サービスに向けて連鎖して行うものです。 たとえば手元にあるコンテナーのテストが正常終了した後に、このコンテナーのデプロイイベントを起動し、デプロイが完全に行われたときに限って、別に存在する ChangeLog を更新するような場合です。 「Add webhook」ボタンをクリックしたら、単に連鎖に必要な数の URL を加えるだけで実現できます。

チェーン内にある最初のウェブフックは、プッシュが成功した直後に呼び出されます。 これに続く URL ごとの呼び出しは、最初のコールバックが確認された後に行われます。

コールバックの検証

ウェブフック・チェーンにおいてコールバックを検証するには、以下が必要になります。

  1. リクエストにおける JSON データ内の callback_url 値を取り出します。

  2. 取得したその URL に対して、適正な JSON データ本体とともに POST リクエストを送信します。

注釈

最後のコールバックが正常であれば、チェーンによるリクエストは完了したものとみなされます。

ウェブフックの処理結果をデバッグする、あるいは単に確認する場合は、Settings ページ上にあるウェブフックの「History」を参照してください。

コールバック JSON データ

コールバックデータ内では、以下のパラメータが認識されます。

  • state (必須): 許容される値は success, failure, error のいずれか。 この値が success でない場合、ウェブフック・チェーンは中断されます。

  • description : Docker Hub 上にて利用可能なさまざまな情報を含んだ文字列。 最大 255 文字。

  • context : 操作に関するコンテキストを含む文字列。 Docker Hub から抽出される情報。 最大 100 文字。

  • target_url : 操作結果として得られた URL。 Docker Hub から抽出される情報。

コールバック・データの例

{
  "state": "success",
  "description": "387 tests PASSED",
  "context": "Continuous integration by Acme CI",
  "target_url": "http://ci.acme.com/results/afd339c1c3d27"
}

参考

Repositories on Docker Hub

https://docs.docker.com/docker-hub/repos/