Linux への CircleCI セルフホストランナーのインストール
このページでは、CircleCI セルフホストランナーを Linux にインストールする方法を説明します。
このページはセルフホストランナーのインストールの続きです。 下記の手順を進めるには、既存の名前空間とリソースクラスが必要です。 これは、https://app.circleci.com/[CircleCI Web アプリ] で Self-Hoseted Runners に移動して実行できます ( Web アプリのインストールのドキュメントを参照)。 また、 CLI もご使用いただけます。 |
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 でご利用いただけます。 ご協力いただき、ありがとうございます。
- このページの編集をご提案ください (最初に「コントリビューションガイド」をご覧ください)。
- ドキュメントの問題点を報告する、またはフィードバックやコメントを送信するには、GitHub で issue を作成してください。
- CircleCI は、ユーザーの皆様の弊社プラットフォームにおけるエクスペリエンスを向上させる方法を常に模索しています。 フィードバックをお寄せいただける場合は、リサーチコミュニティにご参加ください。
サポートが必要ですか
CircleCI のサポートエンジニアによる、サービスに関する問題、請求およびアカウントについての質問への対応、設定の構築に関する問題解決のサポートを行っています。 サポートチケットを送信して、CircleCI のサポートエンジニアにお問い合わせください。日本語でお問い合わせいただけます。
または、 サポートサイト から、サポート記事やコミュニティフォーラム、トレーニングリソースをご覧いただけます。
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.