マシンランナーの Linux へのインストール

1+ year ago2 min read
Last updated • Read time
クラウド
This document is applicable to CircleCI クラウド
Server v4.x
This document is applicable to CircleCI Server v4.x
Server v3.x
This document is applicable to CircleCI Server v3.x

このページでは、Linux に CircleCI のマシンランナーをインストールする方法を説明します。

前提条件

マシンランナーをインストールし、ジョブを実行するには、root 権限があり、以下のユーティリティとツールがシステムにインストールされている必要があります:

  • 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 のみ)

  • コマンドラインからランナーをインストールする場合は、 CircleCI CLIを使用します。

セルフホストランナーの利用条件

Web アプリを介してマシンランナーをインストールする前に、 CircleCI ランナー規約 に同意する必要があります。 CircleCI Web アプリセルフホストランナー のセクションにアクセスするには、組織の管理者が Organization Settings > Self-Hosted Runners に行き、規約に同意する必要があります。

Runner terms and conditions

規約に同意すると、Self-Hosted Runners はサイドナビゲーションバーに常に表示されるようになります。

CircleCI は、組織の VCS 権限をミラーリングします。 組織の VCS の管理者が、CircleCI の管理者です。 不明な場合は、VCS の 管理者の権限を確認してください。

1. ネームスペースとリソースクラスの作成

セルフホストランナーをインストールするには、名前空間とリソースクラストークンを作成する必要があります。 リソース クラスとトークンを作成するには、VCS プロバイダーの組織管理者権限を持っている必要があります。 名前空間やリソースクラスについては、 コンセプト のページを参照してください。

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

  1. CircleCI Web アプリ で、Self-Hostd Runners に移動します。

    Runner set up
  2. 組織でセルフホストランナーを初めて使用する場合、ファーストステップとしてまず名前空間を作成する必要があります。 作成できる名前空間は、各組織につき 1 つのみです。 必須ではありませんが、 CircleCI のアカウント名を小文字で使用することを推奨します。 CircleCI は UI でデフォルトで推奨される名前空間として組織名を入力します。

    もし、お客様の組織が既に Orb を使用しているのであれば、新しい名前空間を作らないでください。 その代わりに、お客様の組織が Orb に使用している名前空間を入力してください。

  3. 2つ目の入力フィールドには、セルフホスト・ランナー・リソース・クラスの名前を入力します。

    Runner set up
  4. リソースクラストークンをコピーし保存します。 セルフホストランナーはこのトークンを使って関連するリソースクラスの作業を要求します。

    Runner set up
  5. 新しいリソースクラスの設定コードが提供されます。 既存の .circleci/config.yml がある場合は、既存の jobs セクションの下に新しいリソースクラスを追加してください。既存のファイルがない場合は、 jobs セクション全体を追加します。 既存の .circleci/config.yml ファイルがない場合は、ファイルを作成し、すべてのコードをコピーします。

    Runner set up

2. launch-agent スクリプトをダウンロードし、バイナリをインストールする。

  1. Save the download-launch-agent script in the root of your project. When run (see the next step) the script will download the launch-agent binary, verify the checksum, and set the launch agent version.

    Self-hosted runners on cloud auto-update to the latest supported versions. For server, specific self-hosted runner versions are validated for interoperability, and self-hosted runners do not auto-update.

  2. Set your target platform and run the download-launch-agent.sh script to download, verify, and install the binary.

    • If you are using cloud, use the table below to find your platform variable:

      Installation TargetVariable
    • For server v3.1.0 and up, use the table below to find the compatible machine runner launch-agent version for the version of server you are running:

      Server versionLaunch agent version

      3.0

      Runner not supported

      3.1

      1.0.11147-881b608

      3.2

      1.0.19813-e9e1cd9

      3.3

      1.0.29477-605777e

      3.4

      1.1.73695-40bf772

      4.0

      1.1.73695-40bf772

      4.1

      1.1.73695-40bf772

      4.2

      1.1.73695-40bf772

      4.3

      1.1.73189-8792751

      Substitute <launch-agent-version> with your launch-agent version for server and run the following:

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

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

RHEL 8 システムでセルフホストランナーがジョブを受け取り、起動するには、SELinux ポリシーが必要です (RHEL 8 より前のバージョンはサポートされていません)。 このポリシーは、このセルフホストランナーインストール環境で実行される個々のジョブで必要となる可能性のある権限を追加するものではないのでご注意ください。 GECOS については、 Wiki ページを参照してください。

Ubuntu/Debian

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

CentOS/RHEL

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

作業ディレクトリを作成し、権限を設定する

sudo mkdir -p /var/opt/circleci
sudo chmod 0750 /var/opt/circleci
sudo chown -R circleci /var/opt/circleci /opt/circleci

セルフホストランナーでクラウド上で動作する認定 Orb をエラーなく使用するには、下記の追加コマンドの実行をご検討ください。 これにより、コードによるマシン上でのルートコマンドの実行が可能になり、システムへの変更はジョブの実行後も保持される場合があるのでご注意ください。

echo "circleci ALL=(ALL) NOPASSWD:ALL" | sudo tee -a /etc/sudoers

4. CircleCI セルフホストランナー設定ファイルを作成する

launch-agent-config.yaml ファイルを、パス /etc/opt/circleci/launch-agent-config.yaml、所有者 circleci、アクセス許可 600 で作成します。 次のコマンドを使用します。

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

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

api:
  auth_token: AUTH_TOKEN
  # On server, set url to the hostname of your server installation. For example,
  # url: https://circleci.example.com

runner:
  name: RUNNER_NAME
  working_directory: /var/opt/circleci/workdir
  cleanup_working_directory: true
  • Replace AUTH_TOKEN with the resource class token created in the set up process.

  • RUNNER_NAME を任意のセルフホストランナー名に置き換えます。 RUNNER_NAME は、ランナーをインストールするマシン一意の名前です。 RUNNER_NAME には、任意の値を設定でき、名前空間やリソースクラス名を含む必要はありません。 CircleCI Web アプリでステータスやジョブ結果を確認する際にエージェントを特定できるよう、名前にはマシンのホスト名を使用することをお勧めします。 The only special characters accepted in RUNNER_NAME are . () - _.

SELinux ポリシーを設定する (RHEL 8)

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

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

sudo mkdir -p /etc/opt/circleci/policy
# Install sepolicy and rpmbuild if you haven't already
sudo yum install -y policycoreutils-devel rpm-build
sudo sepolicy generate --path /etc/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 /etc/opt/circleci/policy/circleci_launch_agent.te
sudo /etc/opt/circleci/policy/circleci_launch_agent.sh

5. マシンランナーを起動する

マシンランナーを以下のように起動できるようになりました。

sudo /opt/circleci/circleci-launch-agent --config /etc/opt/circleci/launch-agent-config.yaml

You can also optionally run machine runner as a systemd service.

マシンランナーの設定例

セルフホストランナーを使って実行する特定のジョブについて、以下のフィールドを設定する必要があります。

  • machine: true

  • resource_class: <namespace>/<resource-class>

以下は、ジョブ設定のシンプルなコード例です。

version: 2.1

workflows:
  build-workflow:
    jobs:
      - runner
jobs:
  runner:
    machine: true
    resource_class: <namespace>/<resource-class>
    steps:
      - run: echo "Hi I'm on Runners!"

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

systemd ユニットを有効にする

このオプション手順を実行するには、バージョン 235 以降の systemd のインストールが必要です。

所有者を root にして /usr/lib/systemd/system/circleci.service を作成し、権限を 755 に設定します。

sudo touch /usr/lib/systemd/system/circleci.service
sudo chown root: /usr/lib/systemd/system/circleci.service
sudo chmod 755 /usr/lib/systemd/system/circleci.service

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

CircleCI のセルフホストランナーがマシン起動時に起動するようにインストール環境を設定する場合、マシンランナーは起動されるとすぐにジョブを開始しようとするので注意が必要です。そのため、起動する前に適切に設定しておく必要があります。 マシンランナーはサービスとして設定することができ、下記のスクリプトで systemd により管理できます。

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

circleci ユーザーの環境を使用するタスクエージェントとは異なり、ローンチエージェントでは、その設定ファイルで明示的に定義されている環境変数 (プロキシ設定など) が必要です。 これは Environment= または EnvironmentFile= で設定できます。 詳細については、 systemd のドキュメント をご覧ください。

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

sudo systemctl enable circleci.service

サービスを起動する

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

sudo systemctl start circleci.service

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

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

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

systemctl status circleci.service --no-pager

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

circleci.service - CircleCI Runner
   Loaded: loaded (/var/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 /etc/opt/circleci/launch-agent-config.yaml

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

journalctl -u circleci

トラブルシューティング

Refer to the Troubleshoot Machine Runner section of the Troubleshoot Self-hosted Runner guide if you encounter issues installing or running machine runner on Linux.