Docker Hub プルスルーミラーの設定

Server v2.x

サーバー管理者

概要

2020 年 11 月 1 日より、Docker Hub で匿名ユーザーに対する発信元 IP に基づいたプル回数制限が導入されています。運用中のサービスでの混乱を避けるために、Docker Hub から認証付きでプル操作を行うようにすることをお勧めします。認証は設定ファイルで行えます ( Docker の認証つきプルを参照)。

または、Docker Hub アカウントの認証情報を使って事前に設定した Docker Hub プルスルーレジストリミラーを設定するという方法もあります。プルスルーレジストリミラーを使用により、設定ファイルの変更を何度も行うよりも作業を簡易化できます。また、Docker Hub への通信が減るため、パフォーマンスの更なる向上も期待できます。

この設定には、以下の 3 つの手順があります。まず、プルスルーキャッシュレジストリを設定し、次にこのレジストリをミラーとして使用するよう Nomad クライアントを設定します。最後に、Machine Executor やリモート Docker ジョブでこのレジストリをミラーとして使用するよう VM サービスを設定します。

サービスマシンには、ミラーを使用するように設定する必要はありません。サービスマシンは、Docker イメージを定期的にプルせず (初期セットアップ時とアップグレード処理時のみ) 、ほとんどのイメージが Replicated からプルされます。そのため、レート制限に達することはほとんどありません。

プルスルーキャッシュレジストリの設定

ここでは、Docker Hub のミラーおよびリバースプロキシとして機能するプルスルーキャッシュレジストリの設定について説明します。プルスルーキャッシュレジストリには 2 つのオプションがあり、HTTP を使用した設定が簡単な基本的なものと、HTTPS を使用したよりセキュアなものがあります。どちらもほとんどのケースに対応できますが、よりセキュアなオプションが必要になるケースもあります。

前提条件: Docker Hub アカウントの設定

プルスルーキャッシュレジストリを設定する前に、Docker Hub アカウントを設定します。このアカウントは、Docker Hub でのプルスルーキャッシュレジストリの認証に使用します。

専用アカウントを設定することをお勧めします。このアカウントでアクセスできるリソースには、お客様の CircleCI サーバーを使用するすべてのエンドユーザーがアクセスできます。このアカウントが Docker Hub に プライベート イメージを登録している場合、 お客様の CircleCI サーバーを利用するすべてのユーザーがそのプライベートイメージにアクセスできるため、専用アカウントの設定が特に重要です。

無料のアカウントも使用できますが、有料アカウントを設定すると回数制限を気にせずに使用できるのでお勧めです。有料アカウントの場合、無制限にイメージをプルできます。詳細は、 https://www.docker.com/pricing を参照してください。

基本的なプルスルーキャッシュレジストリ (Docker Hub の HTTP プロキシ) の設定

Docker がインストールされた独立した Linux サーバー を設定します。

このレジストリを独立したサーバー (CircleCI 環境外のサーバー) として設定し、このキャッシュサーバーの負荷が他の CircleCI Server のサービスに影響を与えないようにします。

例えば、このサーバーの IP アドレスを 192.0.2.1 とし、設定するレジストリの URL は、 http://192.0.2.1 とします。この URL は後で Nomad クライアントと VM サービスを設定する際に必要になります。

以下のコマンドを実行して、レジストリを起動します。

DOCKER_HUB_USERNAME は Docker Hub アカウントのユーザー名に、DOCKER_HUB_ACCESS_TOKEN は https://hub.docker.com/settings/security で取得したアクセストークンに、それぞれ置き換えてください。

sudo docker run \
  -d \
  -p 80:5000 \
  --restart=always \
  --name=through-cache \
  -e REGISTRY_PROXY_REMOTEURL="https://registry-1.docker.io" \
  -e REGISTRY_PROXY_USERNAME=DOCKER_HUB_USERNAME \
  -e REGISTRY_PROXY_PASSWORD=DOCKER_HUB_ACCESS_TOKEN \
  registry

最後に、TCP ポート 80 (つまり HTTP) が開いていてアクセス可能であることを確認します。セキュリティーを強化するために、Nomad クライアントと machine とリモート Docker Engine の VM にのみポートを開くことをお勧めします。

たとえば AWS では、セキュリティグループと OS レベルのファイアウォールの両方が Nomad クライアントからの接続を HTTP 経由で受け入れるように正しく設定されていることを確認する必要があります。

セキュアなプルスルーキャッシュレジストリ (Docker Hub の HTTPS プロキシ) の設定

特に machine Executor とリモート Docker Engine で BuildKit を有効にしている場合などの特定の状況において、プルスルーキャッシュレジストリが HTTPS での接続を受け入れる必要がある場合があります。ここでは、HTTPS 接続をリッスンするプルスルーキャッシュの設定方法を紹介します。

Docker がインストールされた独立した Linux サーバー を設定します。

このレジストリを独立したサーバー (CircleCI 環境外のサーバー) として設定し、このキャッシュサーバーの負荷が他の CircleCI Server のサービスに影響を与えないようにします。

このサーバーはホストネームでアクセスできるようにする必要があります。 つまり、ホスト名 (your-mirror.example.com とします) がこのサーバーの IP アドレスに正しく解決されるように、DNS を設定する必要があります。このガイドでは、設定しているレジストリの URL を https://your-mirror.example.com とします (URL スキームは http ではなく、 https ですのでご注意ください)。この URL は後で Nomad クライアントと VM サービスを設定する際に必要になります。

your-mirror.example.com の TLS 証明書を取得し 、TLS 証明書とプライベートキーをサーバーの /root/tls に置きます。

このガイドでは、自己署名証明書ではなく、既知の CA が発行した証明書を取得することを想定しています。自己署名証明書の使用はまだテストされていません。

以下のコマンドを実行して、レジストリを起動 します。

fullchain.pem は証明書のファイル名に、 privkey.pem はプライベートキーのファイル名にそれぞれ置き換えてください。 ここで指定する証明書は、リーフからルートへの証明書パスの追跡が可能な正確にチェーンされた証明書である必要があります。

sudo docker run \
  -d \
  -p 443:5000 \
  --restart=always \
  --name=through-cache-secure \
  -v /root/tls:/data/tls \
  -e REGISTRY_PROXY_REMOTEURL="https://registry-1.docker.io" \
  -e REGISTRY_PROXY_USERNAME=DOCKER_HUB_USERNAME \
  -e REGISTRY_PROXY_PASSWORD=DOCKER_HUB_ACCESS_TOKEN \
  -e REGISTRY_HTTP_TLS_CERTIFICATE=/data/tls/fullchain.pem \
  -e REGISTRY_HTTP_TLS_KEY=/data/tls/privkey.pem \
  registry

最後に、 TCP ポート 443 (つまり HTTPS) が開いていてアクセス可能であることを確認します。 セキュリティーを強化するために、Nomad クライアントと machine とリモート Docker Engine の VM にのみポートを開くことをお勧めします。

たとえば AWS では、セキュリティグループと OS レベルのファイアウォールの両方が machine/setup_remote_docker ジョブの Nomad クライアントと VM からの接続をHTTPS 経由で受け入れるように正しく設定されていることを確認する必要があります。

TLS 証明書の更新プラン

TLS 証明書は定期的な更新が必要です。証明書の更新に必要な手順は以下のとおりです。

/root/tls の証明書とプライベートキーを更新する。
docker restart through-cache-secure を実行する。

技術的には、この処理は自動化できます。たとえば、証明書に Let’s Encrypt を使用している場合、certbot renew と上記手順を実行する cron タスクを設定できます。

プルスルーキャッシュレジストリを使用するように Nomad クライアントを設定する (Nomad クライアントごとに実行)

以下のコマンドを実行して、 Docker デーモンの registry-mirrors オプションを指定 します。

192.0.2.1 は実際のプルスルーキャッシュサーバーの IP アドレスに置き換えてください。
```
sudo bash -c 'cat <<< $(jq ".\"registry-mirrors\" = [\"http://192.0.2.1.or.https.your-mirror.example.com\"]" /etc/docker/daemon.json) > /etc/docker/daemon.json'
```
Docker デーモンをリロード し、設定を適用します。

sudo systemctl restart docker.service

マシン/リモート Docker VM でプルスルーキャッシュレジストリを使用するように VM サービスを設定する

サービスマシンで、以下の手順を実行します。

以下のコマンドを実行して、カスタマイズファイル用のディレクトリを作成します。

sudo mkdir -p /etc/circleconfig/vm-service

vm-service でロードするように、 カスタマイズスクリプトを挿入 します。 下記のスクリプトを /etc/circleconfig/vm-service/customizations に追加します。

DOCKER_MIRROR_HOSTNAME 変数の http://192.0.2.1.or.https.your-mirror.example.com を該当するプルスルーキャッシュレジストリの URL に置き換えます。

このカスタマイズは 2.19.0 以降のバージョンでのみ可能です。

export JAVA_OPTS='-cp /resources:/service/app.jar'
export DOCKER_MIRROR_HOSTNAME="http://192.0.2.1.or.https.your-mirror.example.com"

mkdir -p /resources/ec2
cat > /resources/ec2/linux_cloud_init.yaml << EOD
#cloud-config
system_info:
  default_user:
    name: "%1\$s"
ssh_authorized_keys:
  - "%2\$s"
runcmd:
  - bash -c 'if [ ! -f /etc/docker/daemon.json ]; then mkdir -p /etc/docker; echo "{}" > /etc/docker/daemon.json; fi'
  - bash -c 'cat <<< \$(jq ".\"registry-mirrors\" = [\"$DOCKER_MIRROR_HOSTNAME\"]" /etc/docker/daemon.json) > /etc/docker/daemon.json'
  - systemctl restart docker.service
EOD

VM サービスを再起動 して、カスタマイズした内容を適用します。

sudo docker restart vm-service

設定した内容のテスト

明示的な認証なしでプライベートイメージを使用する

キャッシュレジストリの Docker ID にプライベートイメージがある場合、エンドユーザーの明示的な認証なしでアクセスできるはずです。

下記は、アクセスをテストするためのサンプル設定ファイルです。キャッシュレジストリで Docker ID yourmachineaccount を使用し、プライベートイメージ yourmachineaccount/private-image-with-docker-client があると想定します。

version: 2

jobs:
  remote-docker:
    docker:
      - image: yourmachineaccount/private-image-with-docker-client # A copy of library/docker
    steps:
      - setup_remote_docker
      - run: docker pull yourmachineaccount/private-image-with-docker-client

  machine:
    machine: true
    steps:
      - run: docker pull yourmachineaccount/private-image-with-docker-client

workflows:
  version: 2

キャッシュレジストリのログの確認

sudo docker logs through-cache (セキュアなレジストリを設定した場合は sudo docker logs through-cache-secure) を実行すると、キャッシュレジストリからログ出力を確認できます。正常に稼働している場合は、HTTP ステータスコード 200 で、マニュフェストと blob のリクエストにレジストリが応答していることを示すメッセージが表示されます。

設定を元に戻すには

Nomad クライアントの設定を解除する

Nomad クライアントごとに下記手順を実行します。

下記コマンドを実行して、/etc/docker/daemon.json の registry-mirrors オプションを削除します。
```
sudo bash -c 'cat <<< $(jq "del(.\"registry-mirrors\")" /etc/docker/daemon.json) > /etc/docker/daemon.json'
```
sudo systemctl restart docker.service を実行して変更を適用します。

VM サービスの設定を解除する

サービスマシンで、以下の手順を実行します。

下記コマンドを実行して、 JAVA_OPTS 環境変数を無効にします。

echo 'unset JAVA_OPTS' | sudo tee -a /etc/circleconfig/vm-service/customizations
sudo docker restart vm-service を実行して変更を適用します。

次のステップ

ドキュメントの改善にご協力ください

このガイドは、CircleCI の他のドキュメントと同様にオープンソースであり、 GitHub でご利用いただけます。ご協力いただき、ありがとうございます。

このページの編集をご提案ください (最初に「コントリビューションガイド」をご覧ください)。
ドキュメントの問題点を報告する、またはフィードバックやコメントを送信するには、GitHub で issue を作成してください。
CircleCI は、ユーザーの皆様の弊社プラットフォームにおけるエクスペリエンスを向上させる方法を常に模索しています。フィードバックをお寄せいただける場合は、リサーチコミュニティにご参加ください。

サポートが必要ですか

CircleCI のサポートエンジニアによる、サービスに関する問題、請求およびアカウントについての質問への対応、設定の構築に関する問題解決のサポートを行っています。サポートチケットを送信して、CircleCI のサポートエンジニアにお問い合わせください。日本語でお問い合わせいただけます。

または、サポートサイトから、サポート記事やコミュニティフォーラム、トレーニングリソースをご覧いただけます。

CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.