Docker の認証付きプルの使用

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

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

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

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 プルをセットアップすることができます。 Docker Hub レジストリ ミラー経由のプルは、CircleCI Server 3.x ではまだ使用できません。 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  # または、プロジェクトの環境変数を参照するように指定します

また、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'
          存在する場合、自動的に使用されます。
          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 のプライベート イメージを使用できるようになります。

  1. CircleCI 標準のプライベート環境変数を使用して、AWS 認証情報を設定する

  2. 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+$/


Help make this document better

This guide, as well as the rest of our docs, are open-source and available on GitHub. We welcome your contributions.