Docker 実行環境の使用

Docker 実行環境を使用して Docker コンテナで ジョブを実行できます。 Docker 実行環境には、 Docker Executor を使ってアクセスできます。 Docker を使ってアプリケーションに必要なものだけをビルドすることにより、パフォーマンスが向上します。

コンテナをスピンアップするには、 .circleci/config.yml ファイルで Docker イメージを指定します。 ジョブのステップはすべてこのコンテナで実行されます。

jobs:
  my-job:
    docker:
      - image: cimg/node:lts
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference

コンテナは指定した Docker イメージのインスタンスです。 ジョブの設定ファイル内で最初にリストしたイメージが_プライマリ_コンテナイメージとなり、すべてのステップがこのイメージ上で実行されます。 セカンダリ コンテナも、データベースなどのサービスを実行するために指定することもできます。 Docker を初めて使用するときには、 Docker の概要についてのドキュメントを確認してください。

CircleCI では、一般的な言語用にすぐに使えるイメージを Docker Hub で提供しています。 イメージ名やタグの全リストは、 CircleCI Developer Hubを参照してください。

注: Docker をインストールした Git を含む Docker イメージが必要な場合は、cimg/base:current をご使用ください。

Docker イメージは以下の方法で指定することができます。

• イメージ名や Docker Hub 上のバージョンタグ
• レジストリのイメージへの URL を使用

config.yml ファイルで docker: キーを指定すると、デフォルトで Docker Hub と Docker レジストリ上のほぼすべてのパブリックイメージがサポートされます。 プライベートのイメージまたはレジストリを操作する場合は、 Docker の認証付きプルの使用」を参照してください。

下記の例により、様々なソースからパブリックイメージを使用する方法を紹介します。

• name:tag
  • cimg/node:14.17-browsers
• name@digest
  • cimg/node@sha256:aa6d08a04d13dd8a...

• name:tag
  • alpine:3.13
• name@digest
  • alpine@sha256:e15947432b813e8f...

• image_full_url:tag
  • gcr.io/google-containers/busybox:1.24
• image_full_url@digest
  • gcr.io/google-containers/busybox@sha256:4bdd623e848417d9612...

resource_class キーを使用すると、ジョブごとに CPU と RAM のリソース量を設定できます。 Docker では、次のリソース クラスを使用できます。

注: 2xlarge と 2xlarge+ はサポートチームのレビューが必要です。 ご利用の際は、 サポートチケットをオープンしてください。

resource_class キーを使ってリソースクラスを以下のように指定します。

jobs:
  build:
    docker:
      - image: cimg/base:current
    resource_class: xlarge
    steps:
    #  ...  other config

Docker にはもともとイメージのキャッシュ機能があり、 リモート Docker を介した Docker イメージのビルド、実行、パブリッシュを可能にしています。 開発しているアプリケーションで Docker を利用する必要があるかどうか、再確認してください。 アプリケーションが下記内容に合致するなら、Docker を使うと良いでしょう。

• 自己完結型のアプリケーションである.
• テストのために他のサービスが必要なアプリケーションである.
• アプリケーションが Docker イメージとして配布される ( リモート Docker の使用が必要)。
• docker-compose を使用したい ( リモート Docker の使用が必要)。

Docker を使うと、Docker コンテナのなかで可能な範囲の機能に実行が制限されることになります (CircleCI における リモート Docker の機能も同様です)。 たとえば、ネットワークへの低レベルアクセスが必要な場合や、外部ボリュームをマウントする必要がある場合は、machine の使用を検討してください。

コンテナ環境として docker イメージを使用する場合と、Ubuntu ベースの machine イメージを使用する場合では、下表のような違いがあります。

⁽¹⁾ カスタム Docker イメージの使用 を参照してください。

⁽²⁾ リモート Docker を使用する必要があります。

⁽³⁾ Docker で複数のデータベースを実行することもできますが、その場合、すべてのイメージ (プライマリおよびセカンダリ) の間で、基になるリソース制限が共有されます。 このときのパフォーマンスは、ご契約のコンテナ プランで利用できるコンピューティング能力に左右されます。

machine の詳細については、次のセクションを参照してください。

• レジストリ プロバイダーのレート制限によって問題が発生した場合は、 認証済みの Docker プルを使用することで解決できる可能性があります。

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

• config.yml のなかでは、イメージのバージョンを示す latest や 1 といった、いずれ変わる可能性の高いタグはできるだけ使わないでください。 例で示している通り、redis:3.2.7 や redis@sha256:95f0c9434f37db0a4f... のように正確にバージョンとハッシュ値を使うのが適切です。 指し示すものが変わりやすいタグは、ジョブの実行環境において予想できない結果になる場合があります。 そういった変化しやすいタグがそのイメージの最新版を指し示すかどうかについて、CircleCI は検知できません。 alpine:latest と指定すると、1 カ月前の古いキャッシュを取得することもありえます。

• 実行中に追加ツールをインストールするために実行時間が長くなる場合は、これらのツールが事前にインストールされているカスタムビルドイメージの作成および使用をお勧めします。 詳細については、 カスタムビルドの Docker イメージの使用を参照してください。

• AWS ECR イメージを使用する場合は、us-east-1 リージョンを使用することをお勧めします。 CircleCI のジョブ実行インフラストラクチャは us-east-1 リージョンにあるので、同じリージョンにイメージを配置すると、イメージのダウンロードにかかる時間が短縮されます。

• プロジェクトをほとんどあるいはまったく変更していないのにパイプラインが失敗した場合は、Docker イメージが使用されているアップストリームで問題が生じていないか確認してみることをお勧めします。

Docker Executor の詳細については、 CircleCI を設定するを参照してください。

ジョブのなかでは複数のイメージを指定することが可能です。 テストにデータベースを使う必要があったり、それ以外にも何らかのサービスが必要になったりする場合に、複数イメージの指定が役に立ちます。 全てのコンテナが共通ネットワーク上で実行され、開放されるポートはいずれも プライマリコンテナのローカルホスト上で利用できます。

複数のイメージを指定して設定されたジョブでは、最初にリストしたイメージによって作成されるコンテナで、すべてのステップが実行されます。

jobs:
  build:
    docker:
    # すべてのステップが実行されるプライマリ コンテナ イメージ
     - image: cimg/base:current
    # Secondary container image on common network.
     - image: cimg/mariadb:10.6

    steps:
      # command will execute in an Ubuntu-based container
      # and can access MariaDB on localhost
      - run: sleep 5 && nc -vz localhost 3306

RAM ディスクは /mnt/ramdisk に配置され、/dev/shm を使用する場合と同様に 一時ファイル用ファイルシステムとして利用できます。 使用する resource_class でプロジェクトのコンテンツすべて (Git からチェックアウトされたすべてのファイル、依存関係、生成されたアセットなど) をまかなえるだけのメモリを確保できている場合、RAM ディスクを使用することでビルドを高速化できます。

RAM ディスクの最もシンプルな使用方法は、ジョブの working_directory を /mnt/ramdisk に設定することです。

jobs:
  build:
    docker:
     - image: alpine

    working_directory: /mnt/ramdisk

    steps:
      - run: |
          echo '#!/bin/sh' > run.sh
          echo 'echo Hello world!' >> run.sh
          chmod +x run.sh
      - run: ./run.sh

Docker コンテナのスピンアップからジョブの実行までに要する時間は、複数の要因により変わることがあります。要因としては、イメージのサイズのほか、レイヤーの一部または全部が基盤となる Docker ホストマシンに既にキャッシュされているかどうかも影響します。

CircleCI イメージなどのより広く利用されているイメージほど、多くのレイヤーがキャッシュでヒットする可能性が高くなります。 よく使われる CircleCI イメージの多くで、同じ基本イメージが使用されています。 各イメージ間で大部分の基本レイヤーが同じなため、キャッシュがヒットする確率が高くなっています。

環境のスピンアップは新しいジョブごとに必要です (新規ジョブが同じワークフロー内にある場合でも、ジョブの再実行や 2 回目以降の実行の場合でも)。 CircleCI ではセキュリティ上の理由から、コンテナを再利用することはありません。 ジョブが終了すると、コンテナは破棄されます。 たとえ同じワークフロー内にある場合でも、ジョブが同じ Docker ホストマシンで実行される保証はありません。　 これは、キャッシュステータスが異なる可能性があることを意味します。

いかなる場合でも、キャッシュのヒットは保証されるものではなく、ヒットすればラッキーな景品のようなものと言えるでしょう。 そのため、すべてのジョブでキャッシュがまったくヒットしないケースも想定しておいてください。

つまり、キャッシュのヒット率は設定や構成で制御することはできません。 CircleCI イメージなど、広く利用されているイメージを選択すれば、”環境のスピンアップ” ステップでレイヤーがキャッシュでヒットする可能性が高まるでしょう。

Docker Executor での CircleCI イメージ の使用に関する詳細をご確認ください。