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

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

Linux、macOS、Docker、および Windows プラットフォームへの CircleCI ランナーのインストール方法について説明します。 他のプラットフォームに関する詳細は、「利用可能な CircleCI ランナー プラットフォーム」を参照してください。

前提条件

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

  • CircleCI CLI

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

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

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

  • sepolicy (RHEL 8 のみ)

  • rpmbuild (RHEL 8 のみ)

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

認証

以下のコマンドを実行できるのは、組織のオーナーまたは管理者だけです。

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

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

    作成できる名前空間は、組織ごとに 1 つだけです。 Orb を既に使用中の場合、この名前空間は Orb で使用しているのと同じものになります。

    次のコマンドを実行します。

    circleci namespace create <name> <vcs-type> <org-name>

    例: 組織の GitHub URL が https://github.com/circleci の場合、circleci namespace create my-namespace github circleci

  2. 次のコマンドを実行して、名前空間内にランナー用のリソース クラスを作成します。

    circleci runner resource-class create <resource-class> <description>

    例: circleci runner resource-class create my-namespace/my-resource-class my-description

    リソース クラスとトークンを作成するには、VCS プロバイダーの組織管理者権限を持っている必要があります。
  3. 次のコマンドを実行して、上記リソース クラスのための認証用トークンを作成します。

    circleci runner token create <resource-class> <nickname>

    例: circleci runner token create my-namespace/my-resource-class my-token。 このコマンドを実行すると、認証トークンを含むランナー設定ファイルが生成され、表示されます。

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

ジョブ実行の要件

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

  • tar

  • gzip

  • coreutils (Linux のみ)

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

インストール

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

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

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

インストール対象 変数

Linux x86_64

platform=linux/amd64

Linux ARM64

platform=linux/arm64

macOS x86_64

platform=darwin/amd64

macOS M1

platform=darwin/arm64

次に、circleci-launch-agent バージョンを設定します。 クラウド版 CircleCI のランナーは、サポートされている最新バージョンに自動的に更新されます。 CircleCI Server の場合、特定のランナー バージョンの相互運用性は検証されていますが、ランナーは自動更新されません。 A table of server circleci-launch-agent versions can be found here.

クラウド版 CircleCI の場合、以下を実行します。

export base_url="https://circleci-binary-releases.s3.amazonaws.com/circleci-launch-agent"
export agent_version=$(curl "${base_url}/release.txt")

For server v3.1.0 and up, run the following, substituting <launch-agent-version> with the correct launch agent version for the version of server you are running (see [runner-for-server-compatibility] to find the correct version):

export agent_version="<launch-agent-version>"

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

# ランナー ディレクトリのセットアップ
prefix=/opt/circleci
sudo mkdir -p "$prefix/workdir"

# ローンチ エージェントのダウンロード
echo "Using CircleCI Launch Agent version $agent_version"
echo "Downloading and verifying CircleCI Launch Agent Binary"
base_url="https://circleci-binary-releases.s3.amazonaws.com/circleci-launch-agent"
curl -sSL "$base_url/$agent_version/checksums.txt" -o checksums.txt
file="$(grep -F "$platform" checksums.txt | cut -d ' ' -f 2 | sed 's/^.//')"
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"
grep "$file" checksums.txt | sha256sum --check && chmod +x "$file"; sudo cp "$file" "$prefix/circleci-launch-agent" || echo "Invalid checksum for CircleCI Launch Agent, please try download again"

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

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

CircleCI Runner Installation (Linux)

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

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

api:
  auth_token: AUTH_TOKEN
  # CircleCI Server の場合 url に CircleCI Server のホスト名を設定します。 例:
  # url: https://circleci.example.com

runner:
  name: RUNNER_NAME
  command_prefix: ["sudo", "-niHu", "circleci", "--"]
  working_directory: /opt/circleci/workdir/%s
  cleanup_working_directory: true

Replace AUTH_TOKEN with the token created in the Authentication step. RUNNER_NAME には、任意の値を指定できます。

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 ユーザーと作業ディレクトリを作成する

タスク エージェントの実行時に使用するユーザーとディレクトリを作成します。 以下のコマンドは、他のユーザーを作成する権限を持ったユーザーとして実行する必要があります (例: root)。 GECOS については、https://en.wikipedia.org/wiki/Gecos_field[Wiki ページ]を参照してください。

Ubuntu/Debian

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

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

CentOS/RHEL

id -u circleci &>/dev/null || adduser --uid 1500 -c GECOS circleci

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

SELinux ポリシーを構成する (RHEL 8)

RHEL 8 システムでランナーがジョブを受け取り、実行するには、SELinux ポリシーが必要です (RHEL 8 より前のバージョンはサポートされていません)。 このポリシーは、このランナーが実行する個別のジョブで必要になる可能性がある権限を追加するものではないことに留意してください。

/opt/circleci/policy というディレクトリを作成し、最初のポリシー モジュールを生成します。

sudo mkdir -p /opt/circleci/policy

# まだインストールしていない場合 sepolicy と rpmbuild をインストールする
sudo yum install -y policycoreutils-devel
sudo yum install -y rpm-build

sudo sepolicy generate --path /opt/circleci/policy --init /opt/circleci/circleci-launch-agent

次の Type Enforcement ファイル circleci_launch_agent.te をダウンロードして、ポリシーをインストールします。

sudo curl https://raw.githubusercontent.com/CircleCI-Public/runner-installation-files/main/rhel8-install/circleci_launch_agent.te --output /opt/circleci/policy/circleci_launch_agent.te

sudo /opt/circleci/policy/circleci_launch_agent.sh

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

CircleCI Runner Installation (macOS)

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

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

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

api:
  auth_token: AUTH_TOKEN
  # CircleCI Server の場合 url に CircleCI Server のホスト名を設定します。 例:
  # url: https://circleci.example.com

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" の部分を確認してください。

Docker Installation

ホストには、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>

Windows Installation

以下のインストール方法は、Windows Server 2019 と Windows Server 2016 の両方について、デスクトップ エクスペリエンス搭載 Datacenter エディションでテスト済みです。

この手順では、CircleCI ローンチ エージェントとその依存関係 (Chocolatey、Git、Gzip) を Windows Server にインストールします。

セットアップ中、CircleCI ジョブを実行する新しいローカル管理者ユーザーを作成します。そのため、Windows Server で、ローカル ユーザーを作成して、そのユーザーのリモート ログオンを許可できる必要があります。

  • また、このセットアップをドメイン環境で行う際には、Windows Server はドメイン メンバーである必要があります。 ランナー インスタンスは、ドメイン コントローラーとして動作している Windows Server では実行できません。

インストール手順

  1. GitHub から Install-CircleCIRunner.ps1 スクリプトをダウンロードし、アクセスしやすい場所に配置します。

  2. PowerShell を管理者として開き、スクリプト ファイルを配置したディレクトリに移動します。

  3. 以下を PowerShell で実行します。

    Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072;
    ./Install-CircleCIRunner.ps1

    PowerShell インターフェイスにインストール結果が出力されます。

  4. インストール中、ランナー (launch-agent-config.yaml) の設定ファイルがメモ帳で開かれます。 Please fill the file out with the requested information (see 設定ファイルのリファレンス). The configuration file is located in the installation directory - C:\Program Files\CircleCI, by default.

セットアップが完了すると、ローンチ エージェントが自動的に起動し、処理対象のジョブの検索を開始します。

Kubernetes へのインストール方法

Kubernetes での CircleCI ランナーの使用」を参照してください。

Configuration file reference

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

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

api:
  auth_token: AUTH_TOKEN
runner:
  name: RUNNER_NAME

runner.name

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

api.auth_token

ここには、CircleCI でのローンチ エージェントの認証に使用するトークンを設定します。このトークンは、CircleCI CLI から生成できます。 既存のトークンは複数のインストール環境で共用できますが、このトークンでは特定の resource_class しか指定できません。

runner.command_prefix

このプレフィックスを設定することで、タスク エージェント プロセスの起動方法をカスタマイズできます。 ここでカスタム スクリプトを使用すると、タスク ランナーの前後で任意のコマンドを実行できます。 指定した引数が実行され、完了時にスクリプトから正しい終了コードが返されるよう特に注意してください。

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 時間です。
ジョブ タイムアウトとドレイン タイムアウトをカスタマイズする

ジョブ タイムアウト設定をカスタマイズする場合、ローンチ エージェントに終了 (TERM) シグナルを送信して、ジョブを "ドレイン" できます。このシグナルは、ローンチ エージェントに対し、安全なシャットダウンを試みるよう指示するものです。 ローンチ エージェントは、TERM シグナルを受け取ると "ドレイン" モードに入ります。このモードでは、ローンチ エージェントが新しいジョブを受け付けなくなりますが、現在アクティブなジョブは完了するまで引き続き実行できます。 "ドレイン" の終了時、ローンチ エージェントはタスク エージェントに対して、アクティブなジョブをすべてキャンセルするようにシグナルを出します (TERM シグナルを送信します)。

TERM シグナルの送信後、しばらく経ってもタスク エージェントが終了しない場合、ローンチ エージェントはタスク エージェントに KILL シグナルを送信して強制終了します。

ドレインは、次の 2 つのうちいずれかの条件で終了します。

  • タスクがドレイン状態になった後、max_run_time の設定値以上の時間が経過する。

  • "ドレイン" 中に、ローンチ エージェントが追加の TERM シグナルを受け取る。

CircleCI Server とランナーの互換性

CircleCI ランナーは CircleCI Server v3.1.0 以上で使用できます。

CircleCI Server のマイナー バージョンはそれぞれ、特定バージョンの circleci-launch-agent と互換性があります。 以下の表に、CircleCI Server バージョンごとに、ランナーのインストール時に使用できる circleci-launch-agent のバージョンを示します。

CircleCI Server のバージョン ローンチ エージェントのバージョン

3.0

ランナーはサポートされていません

3.1

1.0.11147-881b608



Help make this document better

This guide, as well as the rest of our docs, are open-source and available on GitHub. We welcome your contributions.