Docker 実行環境の使用

7 months ago2 min read
Last updated • Read time
クラウド
This document is applicable to CircleCI クラウド
Server v4.x
This document is applicable to CircleCI Server v4.x
Server v3.x
This document is applicable to CircleCI Server v3.x

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

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

NOTE: Docker実行環境を使用する場合は、イメージ・レジストリ(image registries)から Docker プルを認証することを推奨します。 認証されたプルでは、プライベートな Docker イメージにアクセスすることができ、レジストリのプロバイダによっては、より高いレート制限が付与される場合もあります。 詳細は、 link:/docs/ja/private-images[Docker の認証付きプルの使用] を参照して下さい。

jobs:
  my-job:
    docker:
      - image: cimg/node:lts

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

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

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

Docker イメージを指定する

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

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

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

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

Docker Hub 上のパブリック CircleCI イメージ

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

Docker Hub 上のパブリックイメージ

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

Docker レジストリ上のパブリックイメージ

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

使用可能な Docker リソース クラス

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

リソースクラスは resource_class キーで指定します:

クラスvCPURAM
small12 GB
medium24 GB
medium+36 GB
large48 GB
xlarge816 GB
2xlarge1632 GB
2xlarge+2040 GB

: リソースクラスはご利用のプランによって異なります。利用可能なリソースクラスの詳細については、 料金ページをご覧ください。

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

x86

Docker実行環境では、以下のリソース・クラスが x86 アーキテクチャで利用可能です:

ClassvCPUsRAMCloudServer
small12GB
medium24GB
medium+36GB
large48GB
xlarge816GB
2xlarge1632GB
2xlarge+2040GB

Arm

以下のリソース・クラスは、Docker で Arm を使用できます:

ClassvCPUsRAMCloudServer
arm-medium24 GB
arm-large48 GB
arm-xlarge816 GB
arm-2xlarge1632 GB

リソースの使用状況を見る

CircleCI Web アプリでジョブの期間中のコンピュートリソース使用量を表示するには:

  1. サイドバーメニューから Dashboard を選択する。
  2. ドロップダウンメニューを使って、project と branch を選択する。
  3. ワークフローの拡大 ( )
  4. ジョブ名をクリックしてジョブを選択する。
  5. Resourcesタブを選択し、ジョブ期間中のCPUとRAMの使用量を表示する。

これらのインサイトを使用して、ジョブの構成済みリソースクラスに変更を加えるかどうかを決定できます。 resource class Insightsにもアクセスできます。

Resources tab

Docker のメリットと制限事項

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

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

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

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

機能dockermachine
起動時間即時30 ~ 60 秒
クリーン環境はいはい
カスタム イメージはい (1)いいえ
Docker イメージのビルドはい (2)はい
ジョブ環境の完全な制御いいえはい
完全なルート アクセスいいえはい
複数データベースの実行はい (3)はい
同じソフトウェアの複数バージョンの実行いいえはい
Docker レイヤーキャッシュはいはい
特権コンテナの実行いいえはい
Docker Compose とボリュームの使用いいえはい
構成可能なリソース (CPU/RAM)はいはい

(1) カスタム Docker イメージの使用 を参照してください。

(2) リモート Docker を使用する必要があります。

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

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

Docker イメージのベストプラクティス

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

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

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

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

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

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

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

複数の Docker イメージを使用する

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

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

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 ディスク

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

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

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

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

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

次のステップ

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