Using Docker Authenticated Pulls

1 week ago • 1 min read

Cloud Server v2.x Server v3.x

ここでは、Docker レジストリのプロバイダーでイメージのプルを認証する方法について説明します。

プルを認証することで、プライベートの Docker イメージにアクセスできるようになります。お使いのレジストリプロバイダーによっては、レート制限が引き上げられる可能性もあります。

CircleCI は Docker と連携して、ユーザーの皆さまが今後もレート制限なしで Docker Hub にアクセスできるようにしています。 2020 年 11 月 1 日時点では、いくつかの例外を除き、CircleCI を通じて Docker Hub からイメージをプルする際に、レート制限の影響を受けることはありません。ただし、今後 CircleCI ユーザーにもレート制限が適用される可能性があります。そのため、将来的にレート制限の影響を受けることのないよう、お使いの CircleCI 設定ファイルに Docker Hub 認証を追加すると共に、必要に応じてご利用中の Docker Hub プランのアップグレードを検討することをお勧めします。

Docker Executor
machine Executor (Docker Orb を使用)
machine Executor (Docker CLI を使用)
AWS ECR
関連項目

Docker Executor

Docker Executor を使用する場合は、https://circleci.com/docs/ja/2.0/configuration-reference[config.yml] ファイルの auth フィールドにユーザー名とパスワードを指定します。パスワードを保護したい場合は、https://circleci.com/docs/ja/2.0/contexts/[コンテキスト]を作成するか、プロジェクトごとの環境変数を使用します。

CircleCI Server 2.x をご利用であれば、代わりに、レジストリミラー経由の Docker Hub プルをセットアップすることができます。 Pulls through Docker Hub registry mirrors are not yet available on server 3.x.

コンテキストを作成するほうがより柔軟性の高い方法です。 CircleCI は複数のコンテキストをサポートしており、シークレットをモジュール化したり、ジョブが*必要*なものだけにアクセスできるようにしたりするのにとても便利です。

次の例では、既存の build-env-vars コンテキストを肥大化させずに、build ジョブに Docker 認証情報の docker-hub-creds コンテキストへのアクセスを付与しています。

workflows:
  my-workflow:
    jobs:
      - build:
          context:
            - build-env-vars
            - docker-hub-creds

jobs:
  build:
    docker:
      - image: acme-private/private-image:321
        auth:
          username: mydockerhub-user  # 文字列リテラル値を指定します
          password: $DOCKERHUB_PASSWORD  # または、プロジェクトの環境変数を参照するように指定します

If you have two-factor authentication set up on Docker Hub, you can simply use your personal access token for the password key instead. たとえば下記のようにします。

- image: acme-private/private-image:321
  auth:
    username: mydockerhub-user
    password: $DOCKERHUB_ACCESS_TOKEN

また、https://cloud.google.com/container-registry[gcr.io] や quay.io などのプライベートリポジトリにあるイメージも使用できます。 image キーに対してリポジトリ/イメージのフル URL を指定し、auth キーに対して適切なユーザー名とパスワードを使用してください。具体的な例は、次のようになります。

- image: quay.io/project/image:tag
  auth:
    username: $QUAY_USERNAME
    password: $QUAY_PASSWORD

machine Executor (Docker Orb を使用)

または、以下のように machine Executor と Docker Orb を使用する場合にも同じ結果が得られます。

version: 2.1
orbs:
  docker: circleci/docker@1.4.0

workflows:
  my-workflow:
    jobs:
      - machine-job:
          context:
            - build-env-vars
            - docker-hub-creds

jobs:
  machine-job:
    machine: true
    steps:
      - docker/check:
          docker-username: DOCKERHUB_LOGIN  # DOCKER_LOGIN がデフォルト値です。存在する場合、自動的に使用されます。
          docker-password: DOCKERHUB_PASSWORD  # DOCKER_PASSWORD がデフォルト値です。
      - docker/pull:
          images: 'circleci/node:latest'

machine Executor (Docker CLI を使用)

または、CLI を使用します。

version: 2
jobs:
  build:
    machine: true
    working_directory: ~/my_app
    steps:
      # Docker と docker-compose がプリインストールされています
      - checkout

      # プライベート Docker イメージを使用して固有の所有 DB を開始します
      - run: |
          docker login -u $DOCKER_USER -p $DOCKER_PASS
          docker run -d --name db company/proprietary-db:1.2.3

AWS ECR

現在 CircleCI では、Amazon の ECR サービスからのプライベートイメージのプルをサポートしています。

任意のリージョンの ECR リポジトリから、プライベートイメージをプルできます。ただし、最高のエクスペリエンスを得るために、us-east-1 リージョンにイメージのコピーを作成し、その us-east-1 のイメージを Docker Executor に指定することを強くお勧めします。 CircleCI のジョブ実行インフラストラクチャは us-east-1 リージョンにあります。そのため、us-east-1 のイメージを使用すると、環境のスピンアッププロセスにかかる時間が短縮されます。

以下の 2 つの方法のいずれかで、ECR のプライベートイメージを使用できるようになります。

CircleCI 標準のプライベート環境変数を使用して、AWS 認証情報を設定する
aws_auth を使用して、.circleci/config.yml に AWS 認証情報を指定する

version: 2
jobs:
  build:
    docker:
      - image: account-id.dkr.ecr.us-east-1.amazonaws.com/org/repo:0.1
        aws_auth:
          aws_access_key_id: AKIAQWERVA  # 文字列リテラル値を指定します
          aws_secret_access_key: $ECR_AWS_SECRET_ACCESS_KEY  # または、プロジェクトの UI 環境変数を参照するように指定します

いずれの方法もほぼ同じですが、2 番目の方法では認証情報に対して任意の変数名を指定できます。これは、インフラストラクチャごとに異なる AWS 認証情報を持っている場合に便利です。たとえば、SaaS アプリケーションに対して短時間のテストを実行し、コミットのたびに Git タグを付けながらステージングインフラストラクチャにデプロイして、本番へのデプロイ前に本格的なテストスイートを実行する場合は、次のように記述します。

version: 2
jobs:
  build:
    docker:
      - image: account-id.dkr.ecr.us-east-1.amazonaws.com/org/repo:0.1
        aws_auth:
          aws_access_key_id: $AWS_ACCESS_KEY_ID_STAGING
          aws_secret_access_key: $AWS_SECRET_ACCESS_KEY_STAGING
    steps:
      - run:
          name: "毎日のテスト"
          command: "....
      cli"
  deploy:
    docker:
      - image: account-id.dkr.ecr.us-east-1.amazonaws.com/org/repo:0.1
        aws_auth:
          aws_access_key_id: $AWS_ACCESS_KEY_ID_PRODUCTION
          aws_secret_access_key: $AWS_SECRET_ACCESS_KEY_PRODUCTION
    steps:
      - run:
          name: "フル テスト スイート"
          command: ".... のテスト"
      - run:
          name: "本番インフラストラクチャへのデプロイ"
          command: "なんらかのコマンド....
      cli"

workflows:
  version: 2
  main:
    jobs:
      - build:
          filters:
            tags:
              only: /^\d{4}\.\d+$/
      - deploy:
          requires:
            - build
          filters:
            branches:
              ignore: /.*/
            tags:
              only: /^\d{4}\.\d+$/

Using Docker Authenticated Pulls

Docker Executor

machine Executor (Docker Orb を使用)

machine Executor (Docker CLI を使用)

AWS ECR

関連項目

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