CircleCI ランナーのインストール

CircleCI ランナーは、現在、 Scale プラン でのみ提供されます。Scale プランへのお申し込み方法については、営業担当者へお問い合わせください。

Linux プラットフォームおよび macOS プラットフォームへの CircleCI ランナーのインストール方法について説明します。

前提条件

サポート レベル

現在、CircleCI ランナーの対応プラットフォームは以下の 3 つのレベルに分けられています。

  • サポート対象

  • 未検証

  • サポート対象外

サポート対象

  • CircleCI でランナーをビルドおよび検証済みのプラットフォームです。

  • サポート内容:

    • カスタマー エンジニアによるサポートを受けられます。

    • CircleCI 作成のドキュメントとベスト プラクティスが提供されます。

    • 問題発生時には、ゴールド サポートで規定されている通常のサービス レベル アグリーメント (SLA) の範囲内で CircleCI が問題解決を支援します。

未検証

  • CircleCI によるランナーの検証が行われていないプラットフォームです。ただし、当該プラットフォームには 1 つ以上のサポート対象プラットフォームと類似性があるため、ランナーは適切に動作すると考えられます。

  • サポート内容:

    • CircleCI からドキュメントは提供されません。

    • 未検証プラットフォームで CircleCI ランナーを実行することは可能ですが、当該プラットフォームでのランナーの実行方法についてはお客様自身でお調べいただく必要があります。

    • 未検証プラットフォームでの問題発生時には、CircleCI アカウント チームが支援を行いますが、場合によってサポートできないことがあります。

    • カスタマー エンジニアから、CircleCI ランナーのベスト プラクティスに基づく (当該プラットフォームに限定されない) 一般的なガイダンスを受けられます。

    • お客様が未検証なプラットフォームでのランナーのセットアップに成功した場合、アカウント チームはその設定情報を収集し、他のお客様向けの情報として再利用します。

サポート対象外

  • CircleCI から CircleCI ランナーの実行用バイナリが提供されていないプラットフォームです。

  • サポート内容:

    • 当該プラットフォームでは、CircleCI ランナーは動作しません。

    • このプラットフォームで CircleCI ランナーを実行できるかどうかを試すのはお客様の自由ですが、成功する確率は低いと考えられます。

    • CircleCI 作成のドキュメントは提供されません。また、カスタマー エンジニアによるサポートも受けられません。

サポート対象プラットフォーム

次のプラットフォームは、CircleCI ランナーが動作することを検証済みです。

  • Intel + Ubuntu

  • Arm64 + Ubuntu

  • Intel + macOS

未検証プラットフォーム

次のプラットフォームは未検証ですが、CircleCI ランナーが動作すると考えられます。

  • Intel + Ubuntu 以外の Linux (Debian、Red Hat、SUSE など)

  • Arm64 + Ubuntu 以外の Linux (Debian、Red Hat、SUSE など)

  • Docker

CircleCI では上記プラットフォーム用のドキュメントを提供していません。

サポート対象外プラットフォーム

次のプラットフォームは、現在 CircleCI ランナーの動作が保証されていません。

  • Intel + Windows

  • Arm + Windows

  • Apple Silicon + macOS

  • Arm32 + Linux

  • Kubernetes、Rancher、その他コンテナ オーケストレーション ソリューションでのネイティブ実行

認証

認証のために、下記手順を実行して名前空間と認証トークンを作成する必要があります。

  1. CircleCI コマンドライン ツールをインストールします

  2. 組織のランナー リソース用の名前空間を作成します。

    作成できる名前空間は、組織ごとに 1 つだけです。Orbs をすでに使用中の場合、この名前空間は Orbs で使用しているのと同じものになります。次のコマンドを実行します。circleci namespace create <name> <vcs-type> <org-name> (例: 組織の GitHub URL が https://github.com/circleci の場合、circleci namespace create my-namespace github circleci)。
  3. 次のコマンドを実行して、名前空間内にランナー用のリソース クラスを作成します。circleci runner resource-class create <resource-class> <description> (例: circleci runner resource-class create my-namespace/my-resource-class my-description)

  4. 次のコマンドを実行して、上記リソース クラスのための認証用トークンを作成します。circleci runner token create <resource-class> <nickname> (例: circleci runner token create my-namespace/my-resource-class my-token)。このコマンドを実行すると、認証トークンを含むランナー設定ファイルが生成され、表示されます。

トークンを再取得することはできませんので、必ず安全な場所に保管してください。

インストールに必要なツール

インストール プロセスでは、システムに以下のユーティリティをインストール済みであることを前提としています。

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

  • sha256sum (Linux では apt または yum により coreutils の一部としてインストール、macOS では brew によりインストール)

  • バージョン 235 以降の systemd (Linux のみ)

  • ユーザーの作成権限および /opt 以下のディレクトリの作成権限

ジョブ実行の要件

ジョブを実行するには、マシンに次のツールを用意する必要があります。

  • tar

  • gzip

  • coreutils (Linux のみ)

  • git (推奨。ただし任意)

インストール

ローンチ エージェント バイナリのダウンロードとチェックサムの検証

ローンチ エージェントは次のスクリプトでインストールできます。このスクリプトでは、ベースのインストール場所に opt/circleci を指定しています。

まず、インストール対象のプラットフォームに応じて、次のいずれかの変数を設定します。

インストール対象 変数

Linux x86_64

platform=linux/amd64

Linux ARM64

platform=linux/arm64

macOS x86_64

platform=darwin/amd64

次のスクリプトを実行して、バイナリをダウンロードして検証し、インストールします。

prefix=/opt/circleci
sudo mkdir -p "$prefix/workdir"
base_url="https://circleci-binary-releases.s3.amazonaws.com/circleci-launch-agent"
echo "Determining latest version of CircleCI Launch Agent"
agent_version=$(curl "$base_url/release.txt")
echo "Using CircleCI Launch Agent version $agent_version"
echo "Downloading and verifying CircleCI Launch Agent Binary"
curl -sSL "$base_url/$agent_version/checksums.txt" -o checksums.txt
file="$(grep -F "$platform" checksums.txt | cut -d ' ' -f 2)"
file="${file:1}"
mkdir -p "$platform"
echo "Downloading CircleCI Launch Agent: $file"
curl --compressed -L "$base_url/$agent_version/$file" -o "$file"
echo "Verifying CircleCI Launch Agent download"
sha256sum --check --ignore-missing checksums.txt && chmod +x "$file"; sudo cp "$file" "$prefix/circleci-launch-agent" || echo "Invalid checksum for CircleCI Launch Agent, please try download again"

プラットフォームごとのインストール方法

次のセクションでは、プラットフォーム固有のインストール方法を説明します。

  • linux

  • macOS

Linux への CircleCI ランナーのインストール方法

CircleCI ランナー設定ファイルを作成する

Linux 用の推奨される CircleCI ランナー設定ファイルを次に示します。

api:
  auth_token: AUTH_TOKEN
runner:
  name: RUNNER_NAME
  command_prefix: ["/opt/circleci/launch-task"]
  working_directory: /opt/circleci/workdir/%s
  cleanup_working_directory: true

CircleCI ランナー設定ファイルをインストールする

作成した設定ファイルを /opt/circleci/launch-agent-config.yaml として保存し、所有者を root に、パーミッションを 600 に設定します。

sudo chown root: /opt/circleci/launch-agent-config.yaml
sudo chmod 600 /opt/circleci/launch-agent-config.yaml

CircleCI ユーザーと作業ディレクトリを作成する

build-agent の実行時に使用するユーザーとディレクトリを作成します。

id -u circleci &>/dev/null || adduser --uid 1500 --disabled-password --gecos GECOS circleci

mkdir -p /opt/circleci/workdir
chown -R circleci /opt/circleci/workdir

タスク起動用スクリプトを作成する

次のラッパー スクリプトを作成します。これは、ローンチ エージェントで適切なサンドボックス処理とクリーン シャットダウンを確保しながら、タスク エージェントを実行するために使用します。

次のスクリプトを /opt/circleci/launch-task として作成し、所有者を root に、権限を 755 に設定します。

#!/bin/bash

set -euo pipefail

## このスクリプトでは、終了時に子プロセスすべてを適切にクリーンアップするため、
## systemd-run を使用して build-agent を起動し、これらの子プロセスがすべて所属する cgroup を
## 作成します。

# build-agent の実行ユーザーは数値で指定する必要があります
USER_ID=$(id -u circleci)

# 一時的な systemd ユニットにわかりやすい名前をつけます
unit="circleci-$CIRCLECI_LAUNCH_ID"

# プロセスの終了時に systemd ユニットをシャットダウンします
abort() {
  if systemctl is-active --quiet "$unit"; then
    systemctl stop "$unit"
  fi
}
trap abort EXIT

systemd-run \
    --pipe --collect --quiet --wait \
    --uid "$USER_ID" --unit "$unit" -- "$@"

systemd ユニットを有効にする

次のスクリプトを /opt/circleci/circleci.service として作成し、所有者を root に、パーミションを 755 に設定します。

TimeoutStopSec のデフォルト値は 5 時間ですが、タスクの総実行時間よりも大きい値を指定する必要があります。

CircleCI ランナーがマシン起動時に実行されるよう設定する場合、ローンチ エージェントは起動されるとジョブを開始しようとすることに注意が必要です。つまり、ジョブの実行に必要な他のサービスがローンチ エージェントより先に起動するよう構成する必要があります。ローンチ エージェントはサービスとして設定可能であり、次のスクリプトで systemd により管理できます。

[Unit]
Description=CircleCI Runner
After=network.target
[Service]
ExecStart=/opt/circleci/circleci-launch-agent --config /opt/circleci/launch-agent-config.yaml
Restart=always
User=root
NotifyAccess=exec
TimeoutStopSec=18300
[Install]
WantedBy = multi-user.target

次に、下記コマンドによりサービスを有効化します。

prefix=/opt/circleci
systemctl enable $prefix/circleci.service

サービスを起動する

CircleCI ランナー サービスは起動するとすぐにジョブを実行しようとするため、サービスの初回起動前に設定を適切に行なっておく必要があります。

systemctl start circleci.service

サービスの実行状態を確認する

systemctl コマンドで表示されるシステム レポートの Status フィールドで、簡単な実行状態を確認できます。このフィールドには、CircleCI API との接続状態に応じて、Healthy (正常) または Unhealthy (異常) と表示されます。

エージェントの状態は、次のコマンドを実行して確認できます。

systemctl status circleci.service --no-pager

このコマンドの出力は次のようになります。

circleci.service - CircleCI Runner
   Loaded: loaded (/opt/circleci/circleci.service; enabled; vendor preset: enabled)
   Active: active (running) since Fri 2020-05-29 14:33:31 UTC; 18min ago
 Main PID: 5592 (circleci-launch)
   Status: "Healthy"
    Tasks: 8 (limit: 2287)
   CGroup: /system.slice/circleci.service
           └─5592 /opt/circleci/circleci-launch-agent --config /opt/circleci/launch-agent-config.yaml

また、次のコマンドを実行してシステムのログを確認することもできます。

journalctl -u circleci

macOS への CircleCI ランナーのインストール方法

CircleCI ランナー設定ファイルを作成する

CircleCI ランナーを実行するユーザーを選択します。以下の手順では、選択するユーザーを USERNAME としています。

下記のテンプレートを、大文字で記載されたパラメーターを適切な値で置き換えて完成させます。完成したら、launch-agent-config.yaml として保存します。

api:
    auth_token: AUTH_TOKEN
runner:
    name: RUNNER_NAME
    command_prefix: ["sudo", "-niHu", "USERNAME", "--"]
    working_directory: /tmp/%s
    cleanup_working_directory: true
logging:
    file: /Library/Logs/com.circleci.runner.log

CircleCI ランナー設定ファイルをインストールする

root ユーザーとして、CircleCI ランナー設定ファイルの保存ディレクトリを作成します。

sudo mkdir -p '/Library/Preferences/com.circleci.runner'

このディレクトリに、先ほど作成した launch-agent-config.yaml をコピーします。

sudo cp 'launch-agent-config.yaml' '/Library/Preferences/com.circleci.runner/launch-agent-config.yaml'

launchd .plist をインストールする

次の内容を /Library/LaunchDaemons/com.circleci.runner.plist にコピーし、所有者を root に、パーミッションを 644 に設定します。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <dict>
        <key>Label</key>
        <string>com.circleci.runner</string>

        <key>Program</key>
        <string>/opt/circleci/circleci-launch-agent</string>

        <key>ProgramArguments</key>
        <array>
            <string>circleci-launch-agent</string>
            <string>--config</string>
            <string>/Library/Preferences/com.circleci.runner/launch-agent-config.yaml</string>
        </array>

        <key>RunAtLoad</key>
        <true/>

        <!-- ランナーは実行状態を維持する必要があります -->
        <key>KeepAlive</key>
        <true/>

        <!-- ランナーによるリソースの使用が macOS で制限されないようにする設定です-->
        <key>ProcessType</key>
        <string>Interactive</string>

        <!-- 失敗時または更新後にランナーを再起動する頻度を増やします -->
        <key>ThrottleInterval</key>
        <integer>3</integer>

        <!-- ランナーがシャットダウンするまで 10 分間待機します (ランナー自体はタスクが完了するまで待機します) -->
        <key>ExitTimeOut</key>
        <integer>600</integer>

        <!-- ログの出力とローテーションの設定はランナー固有のものを使用します -->
        <key>StandardOutPath</key>
        <string>/dev/null</string>
        <key>StandardErrorPath</key>
        <string>/dev/null</string>
    </dict>
</plist>

launchd サービスを有効にする

2 回目以降に有効化の手順を実行する場合、次の手順で既存サービスをアンロードする必要があります。

sudo launchctl unload '/Library/LaunchDaemons/com.circleci.runner.plist'

これで、サービスをロードできます。

sudo launchctl load '/Library/LaunchDaemons/com.circleci.runner.plist'

サービスの実行状態を確認する

macOS のコンソールを使用して、CircleCI ランナーのログを確認できます。com.circleci.runner.log という名前のログに含まれる "Log Reports" の部分を確認してください。

設定ファイルのリファレンス

ローンチ エージェント本体、およびサーバーとエージェントの通信方法やタスク エージェントの起動方法の設定は、YAML ファイルを使用して行います。

設定ファイルの書式は次のとおりであり、以下で説明する各種パラメーターを使用可能です。

api:
  auth_token: AUTH_TOKEN
runner:
  name: RUNNER_NAME
runner.name

RUNNER_NAME には、このローンチ エージェントに割り当てる一意の名前を設定します。CircleCI UI でのステータスやジョブ結果の確認時にランナーを特定できるよう、名前にはマシンのホスト名を使用することをお勧めします。

api.auth_token

ここには、CircleCI でのローンチ エージェントの認証に使用するトークンを設定します。このトークンは、カスタマー サクセス マネージャーから提供されます。既存のトークンは複数のインストール環境で共用できますが、このトークンでは特定の resource_class しか指定できません。

runner.command_prefix

このプレフィックスを設定することで、タスク エージェント プロセスの起動方法をカスタマイズできます。このページの例では、前述の launch-task スクリプトを設定しています。

runner.working_directory

ここでディレクトリを設定することで、ジョブごとに使用するデフォルトの作業ディレクトリを指定できます。設定したディレクトリがすでに存在する場合は、タスク エージェントがそのディレクトリに書き込みを行えるようパーミッションが設定されている必要があります。設定したディレクトリが存在しない場合は、タスク エージェントにそのディレクトリの作成権限を付与する必要があります。設定値に %s を含めた場合、この変数はジョブごとに異なる値で置き換えられます。設定した作業ディレクトリは自動的には削除されないことに注意してください。

runner.cleanup_working_directory

この値を設定すると、各ジョブの完了後に作業ディレクトリを削除するかどうかを指定できます。デフォルト値は false です。

runner.max_run_time

この値を設定することで、タスク エージェントの各ジョブについてデフォルトの最大実行時間を上書きできます。値は、単位識別子付きの文字列で指定します。識別子は、時間単位の場合は h、分単位の場合は m、秒単位の場合は s を使用します。

以下に有効な例を示します。

  • 72h - 3 日間

  • 1h30m - 1 時間 30 分

  • 30s - 30 秒

  • 50m - 50 分

  • 1h30m20s - 非常に厳密ですが、こうした時間指定も可能です

デフォルト値は 5 時間です。

Docker のインストール

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

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

CircleCI ランナーのイメージを展開する Dockerfile を作成する

次の例では、ベース イメージ上に python3 をインストールします。

Dockerfile.runner.extended

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

Docker イメージをビルドする

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

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 stop <container-name>