CLI を使ったセルフホストランナーのインストール

3 weeks ago1 min read

クラウド

Server v4.x

Server v3.x

このページの内容

セルフホストランナーバージョン 1.0 は、2023年 7月 23日にサポートを終了し、2023年 6月28日に一時的利用できなくなります。さらに詳しく

ここでは、CLI を使って マシンセルフホストランナー をインストールする方法を説明します。 Kubernetes でのコンテナランナーのご利用をお考えの場合、コンテナランナーに関する説明のページをご覧ください。

Linux、macOS、Docker、Windows へのセルフホストランナーのインストールは、 CircleCI Web アプリから直接行えます。このオプションをこの UI で使用するには、ランナー規約に同意する必要があります。

前提条件

ジョブのインストールや実行には、ルートアクセスが必要です。また、システムに以下のユーティリティとツールをインストールする必要があります。

CircleCI CLI: サーバー用のランナー をインストールする場合は、サーバー API キーを使って CircleCI CLI を設定する必要があります。 circleci setup を実行して CLI を設定し、必要に応じて新しい API トークンを提供するオプションにアクセスします。
coreutils (Linux のみ)
curl (macOS ではデフォルトでインストール済み)
sha256sum (プリインストールされていない場合):
- macOS の場合は、brew install coreutils ( Homebrew が必要)
- Ubuntu/Debain の場合は、`sudo apt install coreutils
- Red Hat の場合は、sudo yum install coreutils
tar
gzip
sepolicy ( RHEL 8 のみ)
rpmbuild ( RHEL 8 のみ)

セルフホストランナー規約への同意

CLI でセルフホストランナーをインストールし、利用する場合は、 CircleCI ランナー規約に同意したものとみなされます。

コマンドラインのインストール

サーバー用のセルフホストランナー をインストールする場合は、サーバー API キーを使って CircleCI CLI を設定する必要があります。 circleci setup を実行して CLI を設定し、必要に応じて新しい API トークンを提供するオプションにアクセスします。

セルフホストランナーをインストールするには、下記手順を実行し、名前空間と認証トークンを作成する必要があります。リソースクラスとトークンを作成するには、VCS プロバイダーの組織管理者である必要があります。

お客様のランナーは、インベントリのページの左にあるナビゲーションバーで Self-Hosted Runners をクリックするとご覧いただけます。

組織のセルフホストランナーの名前空間を作成します。 CircleCI は組織名に基づき名前空間を自動作成するのでご注意ください。それが使用する名前空間であることを確認してください。 作成できる名前空間は、各組織につき 1 つのみです。 CircleCI の組織のアカウント名を小文字で使用することを推奨します。既に Orb を使用している場合は、Orb で使用しているのと同じ名前空間にします。

名前空間の作成がエラーになる場合は、既存の名前空間があるかを確認し、既存の名前空間を使用して下記のステップ 2 から実行します。

下記のコマンドを使って名前空間を作成することをお勧めします。
```
circleci namespace create <name> --org-id <your-organization-id>
```
次のコマンドを実行して、セルフホストランナーの名前空間用のリソースクラスを作成します。
```
circleci runner resource-class create <namespace>/<resource-class> <description> --generate-token
```
リソースクラスを作成するコマンドには名前空間が必要です。　例: circleci runner resource-class create my-namespace/my-resource-class my-description --generate-token

トークンは再取得できないので、必ず安全な場所に保管してください。

Linux、macOS、サーバーをご使用のお客様は、下記の指示に従ってください。 それ以外のお客様は、プラットフォームごとのインストール方法までスキップします。

Linux、macOS、サーバーの場合

下記の手順に移る前に、必ずコマンドラインのインストールを完了してください。

下記のスクリプトをプロジェクトのルートに download-launch-agent.sh として保存します。このスクリプトの実行 (次のステップを参照) によりローンチエージェントバイナリがダウンロードされる場合は、チェックサムを確認し、circleci-launch-agent のバージョンを設定してください。

クラウド版 CircleCI のセルフホストランナーは、サポートされている最新バージョンに自動的に更新されます。サーバーの場合、特定のセルフホストランナーバージョンの相互運用性は検証されていますが、セルフホストランナーは自動更新されません。

#!/usr/bin/env sh

set -eu pipefail

echo "Installing CircleCI Runner for ${platform}"

base_url="https://circleci-binary-releases.s3.amazonaws.com/circleci-launch-agent"
if [ -z ${agent_version+x} ]; then
  agent_version=$(curl "${base_url}/release.txt")
fi

# Set up runner directory
echo "Setting up CircleCI Runner directory"
prefix=/var/opt/circleci
sudo mkdir -p "${prefix}/workdir"

# Downloading launch-agent (machine runner)
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 | sed 's/^.//')"
mkdir -p "${platform}"
echo "Downloading CircleCI Launch Agent: ${file}"
curl --compressed -L "${base_url}/${agent_version}/${file}" -o "${file}"

# Verifying download
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"

プラットフォームを設定して、 download-launch-agent.sh スクリプトを実行し、バイナリをダウンロード、確認、インストールしてください。 クラウド版 をご利用の場合は、下記の表でプラットフォームの変数を見つけます。

インストール対象	変数
Linux x86_64	`platform=linux/amd64`
Linux ARM64	`platform=linux/arm64`
Linux s390x	`platform=linux/s390x`
Linux ppc64le	`platform=linux/ppc64le`
macOS x86_64	`platform=darwin/amd64`
macOS M1	`platform=darwin/arm64`

例えば クラウド版 の場合、macOS M1 のプラットフォームを設定し、download-launch-agent.sh スクリプトを実行するには、下記を実行します。

export platform=darwin/arm64 && sh ./download-launch-agent.sh

Server v3.1.0 以降 の場合は、下記の表から実行しているサーバーのバージョンに互換性のあるマシンランナーローンチエージェントのバージョンを見つけます。

CircleCI Server のバージョン	ローンチエージェントのバージョン
3.0	ランナーはサポートされていません
3.1	1.0.11147-881b608
3.2	1.0.19813-e9e1cd9
3.3	1.0.29477-605777e
3.4	1.0.48283-583799b
4.0	1.0.48283-583799b

<launch-agent-version> をサーバー用のローンチエージェントバージョンに置き換え、以下を実行します。

export agent_version="<launch-agent-version>" && sh ./download-launch-agent.sh

注: ランナーのセットアップに成功したら、download-launch-agent.sh ファイルを削除します。

次のセクションのプラットフォームごとのインストール方法に従ってインストールを続けます。

各プラットフォームのインストール手順

下記のプラットフォームごとのインストール方法に従ってインストールを続けます。必ず事前に名前空間とリソースクラスの作成を完了し、前のセクションの download-launch-agent.sh スクリプトを実行してください。

Linux
macOS
Windows
Docker
コンテナランナー (現在オープンプレビュー中)

プラットフォームの互換性仕様については、 < ランナーの概要で詳細をご覧ください。

ジョブでセルフホストランナーを参照する

セルフホストランナーのセットアップが完了したら、 .circleci/config.yml ファイルのフィールドを設定してジョブでセルフホストランナーを参照する必要があります。セルフホストランナーを使って実行する特定のジョブについて、以下のフィールドを設定する必要があります。

この設定ファイルを VCS プロバイダーにプッシュすると、セルフホストランナーを使ってジョブが実行されます。

セルフホストランナーのサーバーとの互換性

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
3.2	1.0.19813-e9e1cd9
3.3	1.0.29477-605777e
3.4	1.0.48283-583799b
4.0	1.0.48283-583799b