Docker での CircleCI のマシンランナーのインストール
このページでは、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](/docs/assets/img/docs/runnerui_terms.png)
規約に同意すると、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
-
-
sepolicy ( RHEL 8 のみ)
-
rpmbuild ( RHEL 8 のみ)
-
コマンドラインからランナーをインストールする場合は、 CircleCI CLIを使用します。
Docker による追加前提条件
Docker をホストにインストールしておく必要があります。 runner
コンテナは、起動するとすぐにジョブの実行を試みます。 コンテナは、停止されるまで他のジョブの実行用に再利用され続けます。
ホスト上で並列実行できるコンテナの数は、ホストで利用可能なリソースおよびジョブのパフォーマンス要件によって異なります。
1. ネームスペースとリソースクラスの作成
セルフホストランナーをインストールするには、名前空間とリソースクラストークンを作成する必要があります。 リソース クラスとトークンを作成するには、VCS プロバイダーの組織管理者権限を持っている必要があります。 名前空間やリソースクラスについては、 コンセプト のページを参照してください。
お客様のランナーは、インベントリのページの左にあるナビゲーションバーで Self-Hosted Runners をクリックするとご覧いただけます。
-
CircleCI Web アプリ で、Self-Hostd Runners に移動します。
-
組織でセルフホストランナーを初めて使用する場合、ファーストステップとしてまず名前空間を作成する必要があります。 作成できる名前空間は、各組織につき 1 つのみです。 必須ではありませんが、 CircleCI のアカウント名を小文字で使用することを推奨します。 CircleCI は UI でデフォルトで推奨される名前空間として組織名を入力します。
もし、お客様の組織が既に Orb を使用しているのであれば、新しい名前空間を作らないでください。 その代わりに、お客様の組織が Orb に使用している名前空間を入力してください。
-
2つ目の入力フィールドには、セルフホスト・ランナー・リソース・クラスの名前を入力します。
-
リソースクラストークンをコピーし保存します。 セルフホストランナーはこのトークンを使って関連するリソースクラスの作業を要求します。
トークンは再取得できないので、必ず安全な場所に保管してください。 -
Linux、macOS、または Windows 上でのセルフホスト型ランナーのセットアップに特化したインストール手順については、「Machine」タブを選択してください。 これらのプラットフォーム固有の手順は、このインストールガイドの次のセクションにも含まれています。
Figure 1. Web アプリによるマシンランナーのインストール -
新しいリソースクラスの設定コードが提供されます。 既存の
.circleci/config.yml
がある場合は、既存のjobs
セクションの下に新しいリソースクラスを追加してください。既存のファイルがない場合は、jobs
セクション全体を追加します。 既存の.circleci/config.yml
ファイルがない場合は、ファイルを作成し、すべてのコードをコピーします。
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 コンテナを起動する
環境変数の値は docker コマンドに紐付けられないので、ps 出力ではこれらの環境変数は表示されません。 |
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>;