ドキュメント
circleci.com
Start Building for Free

Linux への CircleCI セルフホストランナーのインストール

1 month ago1 min read
クラウド
Server v3.x
On This Page

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

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

launch-agent-config.yaml ファイルを作成します。

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

下記の Linux 用セルフホストランナーの推奨設定を、新しく作成したファイルにコピー & ペーストします。

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: /var/opt/circleci/workdir
  cleanup_working_directory: true

  • AUTH_TOKEN を 認証 で作成したリソースクラストークンに置き換えます。

  • RUNNER_NAME を任意のセルフホストランナー名に置き換えます。

  • RUNNER_NAME は、ランナーをインストールするマシン一意の名前です。

  • RUNNER_NAME には、任意の値を設定でき、名前空間やリソースクラス名を含む必要はありません。

  • USERNAME は、ランナーローンチエージェントを実行するマシンのユーザーです。

  • これは CircleCI アカウントユーザー名ではなく、エージェントがインストールされるマシンのユーザーです。

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

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

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

Ubuntu/Debian

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

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

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

echo "USERNAME ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers

CentOS/RHEL

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

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

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

echo "circleci ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers

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

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

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

  • machine: true

  • resource_class: your-namespace/your-resource

以下に、ジョブのセットアップ方法の簡単な例を示します。

version: 2.1
workflows:
  testing:
    jobs:
      - runner
jobs:
  runner:
    machine: true
    resource_class: your-namespace/your-resource
    steps:
      - run: echo "Hi I'm on Runners!"

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

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

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

systemd ユニットを有効にする

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

`/opt/circleci/circleci.service` を所有者を `root` にして作成し、アクセス許可を `755` に設定します。
sudo chown root: /opt/circleci/circleci.service
sudo chmod 755 /opt/circleci/circleci.service

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

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

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

systemctl enable /opt/circleci/circleci.service

サービスを起動する

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

systemctl start circleci.service

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

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

サポートが必要ですか

CircleCI のサポートエンジニアによる、サービスに関する問題、請求およびアカウントについての質問への対応、設定の構築に関する問題解決のサポートを行っています。 サポートチケットを送信して、CircleCI のサポートエンジニアにお問い合わせください。日本語でお問い合わせいただけます。

または、 サポートサイト から、サポート記事やコミュニティフォーラム、トレーニングリソースをご覧いただけます。

Creative Commons License

CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.