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

セルフホストランナーの設定のリファレンス

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

セルフホストランナーの設定のリファレンス

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

設定ファイルの形式は次のとおりです。下記で説明する各種パラメーターを使用します。

api:
  auth_token: AUTH_TOKEN
runner:
  name: RUNNER_NAME

api.auth_token

$LAUNCH_AGENT_API_AUTH_TOKEN

CircleCI へのローンチエージェントを識別するために使用されるトークンで、 CircleCI CLI により生成することができます。 既存のトークンは複数のインストール環境で共用できますが、このトークンでは特定の resource_class しか指定できません。

api.url

$LAUNCH_AGENT_API_URL

セルフホストランナーが CircleCI との通信に使用する完全認証された URL です。 この変数は、3.2 以降のバージョンのサーバーがインストールされたセルフホストランナーのみ要求されます。

api:
  url: https://circleci.example.com

runner.name

$LAUNCH_AGENT_RUNNER_NAME

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

logging.file

$LAUNCH_AGENT_LOGGING_FILE

これにより、ローンチエージェントとタスクエージェントのログが記録されるファイルが制御されます。 ローンチエージェントとタスクエージェントに関する詳細は、 CircleCI ランナーの運用を参照して下さい。

logging:
  file: /Library/Logs/com.circleci.runner.log

runner.command_prefix

$LAUNCH_AGENT_RUNNER_COMMAND_PREFIX

このプレフィックスは、タスクエージェントをラップして実行する引数の YAML リストを取得します。

たとえば、`sudo`により権限が上がります。

runner:
  command_prefix: ["sudo", "-niHu", "USERNAME", "--"]

このプレフィックスは、カスタムスクリプトの場合もあります。 スクリプトに渡される引数により、タスクエージェントが起動します。

カスタムスクリプトは以下の点に注意して下さい。

  1. タスクエージェント (つまり、渡された引数) が確実に実行されるように注意してください。

  2. タスクエージェントからの終了コードを、独自の終了コードとして転送します。

    `/opt/circleci/wrapper.sh`として保存されるスクリプト例:
#!/bin/bash

task_agent_cmd=${@:1}
echo "About to run CircleCI task agent: ${task_agent_cmd}"
$task_agent_cmd
exit=$?
echo "CircleCI task agent finished."
exit $exit

上記の例の設定ファイルスニペット

runner:
  command_prefix: ["/opt/circleci/wrapper.sh"]

runner.working_directory

$LAUNCH_AGENT_RUNNER_WORK_DIR

このディレクトリは、完全修飾パスを使用し、各ジョブで使用されるデフォルトの作業ディレクトリを制御できます。 設定したディレクトリが既に存在する場合は、タスク エージェントがそのディレクトリに書き込みを行うための権限が必要です。 設定したディレクトリが存在しない場合は、タスクエージェントにそのディレクトリの作成権限を付与する必要があります。 1 つのマシーンに複数のローンチエージェントをインストールする場合、各ローンチエージェントごとに一意の作業ディレクトリが必要です。

runner:
  working_directory: /opt/circleci/workdir

runner.cleanup_working_directory

CircleCI では、分かりやすいディレクトリを使用することを推奨していますが、パスに %s を指定することも可能です。 この値は各ジョブでは別の値に置き換えられます。 これは環境変数 $CIRCLE_WORKING_DIRECTORY の下で、ジョブの実行時にのみ分かる置き換えです。

runner:
  working_directory: /opt/circleci/%s

$LAUNCH_AGENT_RUNNER_CLEANUP_WORK_DIR

このフラグを設定すると、各ジョブの完了後に作業ディレクトリを削除するかどうかを指定できます。

値の例:

  • true

  • false

runner:
  cleanup_working_directory: true

runner.mode

$LAUNCH_AGENT_RUNNER_MODE

このパラメータにより、ジョブが完了した時点でセルフホストランナーインスタンスを終了させるか (single-task)、利用可能な新しいジョブを継続的にポーリングするか (continuous) を指定できます。

値の例:

  • continuous

  • single-task

runner:
  mode: continuous

runner.max_run_time

$LAUNCH_AGENT_RUNNER_MAX_RUN_TIME

この値を設定することで、タスク エージェントの各ジョブについてデフォルトの最大実行時間を上書きできます。 値は、単位識別子付きの文字列です。識別子は、時間単位の場合は h、分単位の場合は m、秒単位の場合は s を使用します。

以下に有効な例を示します。

  • 72h - 3 日間

  • 1h30m - 1 時間 30 分

  • 30s - 30 秒

  • 50m - 50 分

  • 1h30m20s - 非常に細かな指定ですが、こうした時間指定も可能です。

runner:
  max_run_time: 5h

ジョブタイムアウトとドレインタイムアウトをカスタマイズする

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

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

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

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

runner.idle_timeout

$LAUNCH_AGENT_RUNNER_IDLE_TIMEOUT

このタイムアウトにより、指定された時間内にタスクが要求されなかった場合に、ローンチエージェントを終了させることができます。 値は、単位識別子付きの文字列です。識別子は、時間単位の場合は h、分単位の場合は m、秒単位の場合は s を使用します (例: 5m は 5 分)。

runner:
  idle_timeout: 1h

runner.disable_auto_update

$DISABLE_AUTO_UPDATE

このパラメーターにより、ローンチエージェントによる自動更新が無効になり、 CircleCI への新しいバージョンの確認要求を停止します。 バージョンが固定されるサーバーでは、このパラメーターは`true`に設定することをお勧めします。

注: このパラメーターを設定すると、セルフホストランナーが手動でアップグレードされ、新機能、セキュリティーに関するアップデート、及びバグの修正点を受け取るようになります。

runner.ssh.advertise_addr

$LAUNCH_AGENT_RUNNER_SSH_ADVERTISE_ADDR

このパラメータにより、「SSH でジョブを再実行する」ことが可能になります。 Before enabling this feature, there are important considerations that should be made.

アドレスは、 host:port という形式で、再実行されたジョブの [Enable SSH (SSHを有効にする)] および [Wait for SSH (SSHを待機する)] セクションに表示されます。

runner:
  ssh:
    advertise_addr: HOSTNAME:54782

SSH デバッグを有効にする前に注意すべき事項

タスクエージェントは、[Rerun job with SSH (SSH でジョブを再実行する)]オプションを有効にすると、専用のポートで内蔵の SSH サーバーとエージェントを実行します。 この機能は、セルフホストランナーがインストールされているシステム上の他の SSH サーバーやエージェントには影響しません。

  • SSH サーバーが使用するホストポートは、現在、`54782`に固定されています。 このポートがブロックされておらず、SSH 接続が可能であることを確認してください。 同じホストに複数のローンチエージェントがインストールされていると、ポートの競合が発生する場合があります。

  • The SSH server will inherit the same user privileges and associated access authorizations as the task agent, defined by the runner.command_prefix parameter.

  • SSH サーバーは、公開キーの認証に設定されます。 ジョブを開始する権限をもつユーザーは誰でも SSH でそのジョブを再実行することができます。 ただし、 SSH セッション中は、再実行を開始したユーザーだけが SSH 公開キーをサーバに追加できます。

  • SSH でジョブを再実行すると、キャンセルされない限り、SSH サーバーに接続されていると 2時間 、接続されない場合は 10分間 、ジョブがオープンな状態になります。 この状態では、ジョブは組織の同時実行制限に反することになり、タスクエージェントは他のジョブを処理できなくなります。 そのため、デバッグが終了したら、SSH の再実行ジョブを明示的に(Web UI または CLI を通じて)キャンセルすることをお勧めします。

セルフホストランナーの全基本設定

セルフホストランナーを使って実行するジョブについて、以下のフィールドを指定します。

  • 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 プロバイダーにプッシュすると、セルフホストランナーを使ってジョブが実行されます。


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

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

サポートが必要ですか

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

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