Docker での CircleCI のマシンランナーのインストール

1+ year ago1 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

このページでは、CircleCI のマシンランナーを Docker Executor を使用してインストールする方法を説明します。 プライベート Kubernetes クラスタでのセルフホストランナーのセットアップをお考えの場合、 コンテナランナー に関する説明のページをご覧ください。

コンテナランナーは、セルフホストランナーでコンテナ化したジョブを実行する際に推奨される方法です。 コンテナランナーは、ジョブ実行時に、カスタム Docker イメージをシームレスに定義、パブリッシュ、使用する機能を提供し、.circleci/config.yml ファイル内の steps の一部として依存関係を列挙せずに、カスタム Docker イメージを使って依存関係やライブラリを簡単に管理する機能も提供します。

Docker を使うマシンベースのアプローチ

上記リンクのコンテナランナーを使用できない場合は、マシンランナーを使って下記の方法で Docker をインストールできます。

ランナー条件

Web アプリを介してマシンランナーをインストールする前に、 CircleCI ランナー規約 に同意する必要があります。 CircleCI Web アプリセルフホストランナー のセクションにアクセスするには、組織の管理者が Organization Settings > Self-Hosted Runners に行き、規約に同意する必要があります。

Runner terms and conditions

規約に同意すると、Self-Hosted Runners はサイドナビゲーションバーに常に表示されるようになります。

CircleCI は、組織の VCS 権限をミラーリングします。 組織の VCS の管理者が、CircleCI の管理者です。 不明な場合は、VCS の 管理者の権限を確認してください。

前提条件

マシンランナーをインストールし、ジョブを実行するには、root 権限があり、以下のユーティリティとツールがシステムにインストールされている必要があります:

  • coreutils (Linux のみ)

  • curl (macOS ではデフォルトでインストール済み)

  • sha256sum (プリインストールされていない場合):

    • macOS の場合は、brew install coreutils ( Homebrew が必要)

    • Ubuntu/Debain の場合は、`sudo apt install coreutils

    • Red Hat の場合は、sudo yum install coreutils

  • tar

  • gzip

  • sepolicy ( RHEL 8 のみ)

  • rpmbuild ( RHEL 8 のみ)

  • コマンドラインからランナーをインストールする場合は、 CircleCI CLIを使用します。

Docker による追加前提条件

Docker をホストにインストールしておく必要があります。 runner コンテナは、起動するとすぐにジョブの実行を試みます。 コンテナは、停止されるまで他のジョブの実行用に再利用され続けます。

ホスト上で並列実行できるコンテナの数は、ホストで利用可能なリソースおよびジョブのパフォーマンス要件によって異なります。

1. ネームスペースとリソースクラスの作成

セルフホストランナーをインストールするには、名前空間とリソースクラストークンを作成する必要があります。 リソース クラスとトークンを作成するには、VCS プロバイダーの組織管理者権限を持っている必要があります。 名前空間やリソースクラスについては、 コンセプト のページを参照してください。

お客様のランナーは、インベントリのページの左にあるナビゲーションバーで Self-Hosted Runners をクリックするとご覧いただけます。

  1. CircleCI Web アプリ で、Self-Hostd Runners に移動します。

    Runner set up
  2. 組織でセルフホストランナーを初めて使用する場合、ファーストステップとしてまず名前空間を作成する必要があります。 作成できる名前空間は、各組織につき 1 つのみです。 必須ではありませんが、 CircleCI のアカウント名を小文字で使用することを推奨します。 CircleCI は UI でデフォルトで推奨される名前空間として組織名を入力します。

    もし、お客様の組織が既に Orb を使用しているのであれば、新しい名前空間を作らないでください。 その代わりに、お客様の組織が Orb に使用している名前空間を入力してください。

  3. 2つ目の入力フィールドには、セルフホスト・ランナー・リソース・クラスの名前を入力します。

    Runner set up
  4. リソースクラストークンをコピーし保存します。 セルフホストランナーはこのトークンを使って関連するリソースクラスの作業を要求します。

    Runner set up
  5. Linux、macOS、または Windows 上でのセルフホスト型ランナーのセットアップに特化したインストール手順については、「Machine」タブを選択してください。 これらのプラットフォーム固有の手順は、このインストールガイドの次のセクションにも含まれています。

    Machine runner in the web app
    Figure 1. Web アプリによるマシンランナーのインストール
  6. 新しいリソースクラスの設定コードが提供されます。 既存の .circleci/config.yml がある場合は、既存の jobs セクションの下に新しいリソースクラスを追加してください。既存のファイルがない場合は、 jobs セクション全体を追加します。 既存の .circleci/config.yml ファイルがない場合は、ファイルを作成し、すべてのコードをコピーします。

    Runner set up

2. マシンランナーのイメージを拡張した Dockerfile を作成する

Dockerfile.runner.extended ファイルを作成します。 次の例では、ベースイメージ上に Python 3 をインストールします。

FROM circleci/runner:launch-agent
RUN sudo apt-get update; \
    sudo apt-get install --no-install-recommends -y \
        python3

3. Docker イメージをビルドする

docker build --file ./Dockerfile.runner.extended .

4. Docker コンテナを起動する

CIRCLECI_RESOURCE_CLASS=<resource-class> CIRCLECI_API_TOKEN=<runner-token> docker run --env CIRCLECI_API_TOKEN --env CIRCLECI_RESOURCE_CLASS --name <container-name> <image-id-from-previous-step>

コンテナは、起動するとすぐにジョブの実行を試みます。

サーバー上で Docker コンテナを起動する

サーバー上で Docker コンテナを起動する場合、--env フラグを使って agent_version`と `LAUNCH_AGENT_API_URL の環境変数を渡す必要があります。

CIRCLECI_RESOURCE_CLASS=<resource-class> CIRCLECI_API_TOKEN=<runner-token> agent_version=<agent_version_for_server> LAUNCH_AGENT_API_URL=<server_host_name> docker run --env agent_version --env LAUNCH_AGENT_API_URL --env CIRCLECI_API_TOKEN --env CIRCLECI_RESOURCE_CLASS --name <container-name> <image-id-from-previous-step>

Docker コンテナを停止する

docker stop <container-name>

Docker コンテナを削除する

同じ名前のコンテナを再作成する場合など、停止したマシンランナーコンテナをシステムから完全に削除する必要がある場合があります。

docker stop <container-name>; docker rm <container-name>;