Docker Hub プルスルーミラーの設定
On This Page
- 概要
- プルスルーキャッシュレジストリの設定
- 前提条件: Docker Hub アカウントの設定
- 基本的なプルスルーキャッシュレジストリ (Docker Hub の HTTP プロキシ) の設定
- セキュアなプルスルーキャッシュレジストリ (Docker Hub の HTTPS プロキシ) の設定
- TLS 証明書の更新プラン
- プルスルーキャッシュレジストリを使用するように Nomad クライアントを設定する (Nomad クライアントごとに実行)
- マシン/リモート Docker VM でプルスルーキャッシュレジストリを使用するように VM サービスを設定する
- 設定した内容のテスト
- 明示的な認証なしでプライベートイメージを使用する
- キャッシュレジストリのログの確認
- 設定を元に戻すには
- Nomad クライアントの設定を解除する
- VM サービスの設定を解除する
- 次のステップ
CircleCI Server version 2.x は、リリースのサポートが終了しています。 リリースがサポートされているバージョンへのアップグレードについては、お客様のアカウントチームにご相談ください。 |
ここでは、Docker Hub プルスルーレジストリミラーを設定する方法について説明します。
概要
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 が発行した証明書を取得することを想定しています。 自己署名証明書の使用はまだテストされていません。 -
以下のコマンドを実行して、レジストリを起動 します。
DOCKER_HUB_USERNAME
は Docker Hub アカウントのユーザー名に、DOCKER_HUB_ACCESS_TOKEN
は https://hub.docker.com/settings/security で取得したアクセストークンに、それぞれ置き換えてください。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.