Kubernetes での CircleCI ランナーの使用

はじめに

CircleCI runner is available on the Scale Plan and for server customers running server v3.1.0 and up. Please reach out to your sales representative (or contact us) for information on how to sign up for the Scale plan.

ここでは、Kubernetes クラスタに CircleCI ランナーをインストールおよびセットアップする方法について説明します。 また、Pod を簡単にインストールできる Helm チャートを用意しています。

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

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

前提条件

CircleCI Server Installation

When installing the Helm chart for use with a CircleCI server installation the agentVersion will need to be set to the pinned version specified in the Runner Installation instructions.

Upgrading Runner Deployment for Server

  1. Modify the values.yaml file to specify the new agentVersion to update to. Refer to the [チャートの値] section of this document for more details about the values.yaml file.

  2. Deploy the changes to the cluster

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

    Further information about the $ helm upgrade command and its usage can be found in the helm documentation

使用方法

  1. https://github.com/CircleCI-Public/circleci-runner-k8s にあるリポジトリをクローンします。

  2. Modify the chart’s values in values.yaml per your needs. See documentation on the list of values.

  3. Apply your chart to your cluster, setting the required parameters you should have obtained from the authentication step:

    $ helm install "circleci-runner" ./ \
      --set runnerToken=$CIRCLECI_RUNNER_TOKEN \
      --set resourceClass=$CIRCLECI_RUNNER_RESOURCE_CLASS \
      --namespace your-namespace
  4. ステータスとログを調べ、Pod が起動し稼働していることを確認します。 以下のような出力が得られれば成功です。

    $ kubectl get pods --all-namespaces
    NAMESPACE     省略可AME                                                             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
    
    ... (中略)
    
    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 値s

Customizable parameters are left inside the values.yaml file. 各値の詳細を以下の表に示します。

Value デフォルト値 必須? 説明

image.repository image.tag

circleci/runner launch-agent

必須

You can extend a custom Docker image from the CircleCI default runner and use that instead.

replicaCount

1

必須

クラスタ内で使用するランナーのレプリカ数。 現時点では、手動で設定、更新する必要があります。 See Pending Work.

resourceClass

-

必須

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

runnerToken

-

必須

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

agentVersion

-

N

The circleci-task-agent version to pin. This is only used for CircleCI Server installations.

その他すべての値

-

N

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

制限事項/今後解決予定の問題

  • 現時点の CircleCI 製 Helm チャートでは、権限を構成できません。 そのため、コンテナの権限昇格は行なえません。 Docker in Docker (Docker コンテナ内から別の Docker コンテナを操作すること) など、権限昇格が必要な場合はお客様自身でチャートを編集いただく必要があります。

  • The Helm chart currently does not support auto-scaling - you will need to modify the replicaCount parameter inside values.yaml yourself and re-apply the chart to your cluster.

  • 現時点の CircleCI 製 Helm チャートでは、ランナーのリソース クラス タイプとトークンを 1 つのみ使用することを想定しています。 クラスタに複数のランナー リソース クラスを構成する必要がある場合は、リソース クラスごとに個別のチャートを作成してください。



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

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


クリエイティブ・コモンズ・ライセンス
CircleCICircleCI ドキュメントは、クリエイティブ・コモンズの表示--非営利-継承 4.0 国際ライセンス に基づいてライセンス供与されています。