Kubernetes への CircleCI セルフホストランナーのインストール

クラウド

Server v3.x

はじめに

ここでは、Kubernetes クラスタに CircleCI セルフホストランナーをセットアップする方法について説明します。また、インストールプロセスを簡易化できる Helm チャートを提供しています。

この Helm チャートにより、 同じセルフホストランナーリソースクラス のポッドを 1 つまたは複数スピンアップできます。これは、同じ実行環境が必要なジョブを複数のセルフホストランナーすべてで実行する場合に便利です。各ランナーは、ジョブが利用可能になり次第キューからジョブをプルします。

ワークロードごとに専用のセルフホストランナーが必要な場合は、セルフホストランナーリソースクラスを複数作成して下記手順を繰り返し実行し、作成する各セルフホストランナークラス用に個別の Helm チャートを作成することをお勧めします。

サーバー利用のお客様は、必ず CircleCI Server のインストールをお読み下さい。

前提条件

セルフホストランナーのデプロイ先で Kubernetes クラスタを稼動させている。
CircleCI セルフホストランナーリソースクラスの作成手順と認証手順を実行済みである。

はじめよう

https://github.com/CircleCI-Public/circleci-runner-k8sにあるリポジトリをクローンします。
必要に応じて、values.yaml 内のチャートの値を変更します。 lチャートの値を参照してください。
認証手順で取得した必要なパラメータを指定して、チャートをクラスタに適用します。
```
$ helm install "circleci-runner" ./ \
  --set runnerToken=$CIRCLECI_RUNNER_TOKEN \
  --set resourceClass=$CIRCLECI_RUNNER_RESOURCE_CLASS \
  --namespace your-namespace
```
Helm チャートの設定に関する詳細は、 README を参照してください。

ステータスとログを調べ、Pod が起動し稼働していることを確認します。以下のような出力が得られれば成功です。

$ kubectl get pods --all-namespaces
NAMESPACE     NAME                                                             READY   STATUS    RESTARTS   AGE
default       circleci-runner-test-7d6b8fc6f-4z5wl                             1/1     Running   0          28h
default       circleci-runner-test-7d6b8fc6f-h97jz                             1/1     Running   0          28h
default       circleci-runner-test-7d6b8fc6f-pksc6                             1/1     Running   0          28h
default       circleci-runner-test-7d6b8fc6f-q74p4                             1/1     Running   0          28h
default       circleci-runner-test-7d6b8fc6f-wh6m2                             1/1     Running   0          28h

$ kubectl logs -f circleci-runner-test-7d6b8fc6f-4z5wl

... (output truncated)

time="2021-03-25T20:55:40Z" level=info msg="CircleCI launcher starting" config=/opt/circleci/launch-agent-config.yaml
time="2021-03-25T20:55:40Z" level=info msg="loaded config" name=circleci-runner-test-7d6b8fc6f-4z5wl url="https://runner.circleci.com"
time="2021-03-25T20:55:40Z" level=info msg="no task found"

Chart 値

values.yaml ファイルに、カスタマイズ可能なチャートのパラメーターが記載されています。各値の詳細を以下の表に示します。

値デフォルト値必須？説明

値	デフォルト値	必須？	説明
`image.repository` `image.tag`	`circleci/runner` `launch-agent`	○	デフォルトの CircleCI セルフホストランナーからカスタム Docker イメージを拡張し、代わりに使用できます。 CircleCI Enterprise のインストールでは、`image.tag` を使ってローンチエージェントの指定されたバージョンを設定できます。互換性のあるバージョンタグについては、セルフホストランナーのインストールを参照して下さい。
`replicaCount`	1	○	クラスタ内で使用するセルフホストランナーのレプリカ数。現時点では、手動で設定、更新する必要があります。今後解決予定の問題を参照して下さい。
`resourceClass`	-	○	セルフホストランナー用に作成したリソースクラス。ここで入力してチャートに指定することも、上記で示したようにチャートの適用時に直接渡すこともできます。
`runnerToken`	-	○	ランナーリソースクラス用に作成したトークン。ここで入力してチャートに指定することも、上記で示したようにチャートの適用時に直接渡すこともできます。
`env`	-	×	`launch-agent` ポッドで設定する環境変数。ランナー設定用の値を含みます。
その他すべての値	-	×	変更はお客様自身の判断と責任で行ってください。

image.repository image.tag

circleci/runner launch-agent

○

デフォルトの CircleCI セルフホストランナーからカスタム Docker イメージを拡張し、代わりに使用できます。

CircleCI Enterprise のインストールでは、image.tag を使ってローンチエージェントの指定されたバージョンを設定できます。互換性のあるバージョンタグについては、セルフホストランナーのインストールを参照して下さい。

replicaCount

○

クラスタ内で使用するセルフホストランナーのレプリカ数。現時点では、手動で設定、更新する必要があります。今後解決予定の問題を参照して下さい。

resourceClass

○

セルフホストランナー用に作成したリソースクラス。ここで入力してチャートに指定することも、上記で示したようにチャートの適用時に直接渡すこともできます。

runnerToken

○

ランナーリソースクラス用に作成したトークン。ここで入力してチャートに指定することも、上記で示したようにチャートの適用時に直接渡すこともできます。

env

launch-agent ポッドで設定する環境変数。ランナー設定用の値を含みます。

その他すべての値

変更はお客様自身の判断と責任で行ってください。

CircleCI Server へのインストール

CircleCI Server 上で使用するために Helmチャートをインストールする場合、 image.tag をセルフホストランナーのインストールで指定されているバージョンのローンチエージェントに設定する必要があります。 LAUNCH_AGENT_API_URL は、環境変数としても設定する必要があります。これは、--set フラグを使って、またはサーバーのホストネームやアドレスを指定する values.yaml ファイルの env のセクションで行えます。

サーバーのセルフホストランナーのデプロイをアップグレードする

values.yaml ファイルを修正してアップデート先に新しい image.tag を指定します。 values.yaml ファイルの詳細については、このドキュメントの [Chart Values] を参照してください。

変更内容をクラスターにデプロイします。

$ helm upgrade -f values.yaml "circleci-runner" ./ \
  --set runnerToken=$CIRCLECI_RUNNER_TOKEN \
  --set resourceClass=$CIRCLECI_RUNNER_RESOURCE_CLASS \
  --set env.LAUNCH_AGENT_API_URL=<server_host> \
  --namespace your-namespace

$ helm upgrade コマンドおよび使用方法に関する詳細は、 Helm に関するドキュメントをご覧ください。

Limitations and pending work

現時点の CircleCI 製 Helm チャートでは、権限を構成できません。そのため、コンテナの権限昇格は行なえません。 Docker in Docker (Docker コンテナ内から別の Docker コンテナを操作すること) など、権限昇格が必要な場合はお客様自身でチャートを編集いただく必要があります。
現時点の Helm チャートは自動スケーリングに対応していません。自動スケーリングを設定するには、お客様自身で values.yaml 内の replicaCount パラメーターを変更し、チャートをクラスタに再適用する必要があります。
現時点の Helm チャートでは、セルフホストランナーのリソースクラスタイプとトークンを 1 つのみ使用することを想定しています。複数のセルフホストランナーリソースクラスを設定する必要がある場合は、リソースクラスごとに個別のチャートを作成してください。

ドキュメントの改善にご協力ください

このガイドは、CircleCI の他のドキュメントと同様にオープンソースであり、 GitHub でご利用いただけます。ご協力いただき、ありがとうございます。

このページの編集をご提案ください (最初に「コントリビューションガイド」をご覧ください)。
ドキュメントの問題点を報告する、またはフィードバックやコメントを送信するには、GitHub で issue を作成してください。
CircleCI は、ユーザーの皆様の弊社プラットフォームにおけるエクスペリエンスを向上させる方法を常に模索しています。フィードバックをお寄せいただける場合は、リサーチコミュニティにご参加ください。

サポートが必要ですか

CircleCI のサポートエンジニアによる、サービスに関する問題、請求およびアカウントについての質問への対応、設定の構築に関する問題解決のサポートを行っています。サポートチケットを送信して、CircleCI のサポートエンジニアにお問い合わせください。日本語でお問い合わせいただけます。

または、サポートサイトから、サポート記事やコミュニティフォーラム、トレーニングリソースをご覧いただけます。

CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.