ドキュメント
circleci.com
Start Building for Free

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

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

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

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

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

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

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

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

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

    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

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

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

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

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

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

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

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

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

    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

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

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

TLS 証明書の更新プラン

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

  1. /root/tls の証明書とプライベートキーを更新する。

  2. docker restart through-cache-secure を実行する。

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

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

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

    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'

  2. Docker デーモンをリロード し、設定を適用します。

    sudo systemctl restart docker.service

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

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

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

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

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

    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

  3. 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
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    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

  run:
    jobs:
      - remote-docker
      - machine

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

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

設定を元に戻すには

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

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

  1. 下記コマンドを実行して、/etc/docker/daemon.json の registry-mirrors オプションを削除します。

    sudo bash -c 'cat <<< $(jq "del(.\"registry-mirrors\")" /etc/docker/daemon.json) > /etc/docker/daemon.json'

  2. sudo systemctl restart docker.service を実行して変更を適用します。

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

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

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

    echo 'unset JAVA_OPTS' | sudo tee -a /etc/circleconfig/vm-service/customizations

  2. sudo docker restart vm-service を実行して変更を適用します。

次のステップ

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

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

サポートが必要ですか

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

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

Creative Commons License

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