ランナー

ランナーを使用すると、Semaphore UI とは別のサーバーでタスクを実行できます。

Semaphore のランナーは、GitLab や GitHub Actions のランナーと同じ原理で動作します。

• 別のサーバーで、Semaphore サーバーのアドレスと認証トークンを指定してランナーを起動します。
• ランナーは Semaphore に接続し、タスクを受け付ける準備ができたことを通知します。
• 新しいタスクが発生すると、Semaphore は必要な情報をすべてランナーに渡します。ランナーはリポジトリをクローンし、Ansible、Terraform、PowerShell などを実行します。
• ランナーはタスクの実行結果を Semaphore に送り返します。

エンドユーザーにとっては、ランナーの有無にかかわらず、Semaphore の使い方は同じです。

ランナーが定義されていない場合は、Semaphore UI サーバー自身がランナーとして動作します。すべてのタスクは Semaphore UI サーバーのコンテキスト内で実行され、ファイルシステムにアクセスできます。

ランナーを使用すると、次の利点があります。

• タスクをより安全に実行できます。たとえば、ランナーを閉じたサブネット内や隔離された Docker コンテナ内に配置できます。
• 複数のサーバーに負荷を分散できます。複数のランナーを起動すると、タスクはそれらの間でランダムに分配されます。

セットアップ

サーバーのセットアップ

ランナーを使用できるようにサーバーをセットアップするには、Semaphore サーバーの設定に次のオプションを追加します。

{
  "use_remote_runner": true,
  "runner_registration_token": "long string of random characters"
}

または、環境変数を使用します。

SEMAPHORE_USE_REMOTE_RUNNER=True
SEMAPHORE_RUNNER_REGISTRATION_TOKEN=long_string_of_random_characters

ランナーのセットアップ

ランナーをセットアップするには、次のコマンドを使用します。

semaphore runner setup --config /path/to/your/config/file.json

このコマンドは /path/to/your/config/file.json に設定ファイルを作成します。

ただし、このコマンドを使用する前に、ランナーがサーバーにどのように登録されるかを理解しておく必要があります。

サーバーへのランナーの登録

Semaphore サーバーにランナーを登録する方法は 2 つあります。

1. Web インターフェースまたは API から追加する。
2. コマンドラインで semaphore runner register コマンドを使用する。

Web UI からランナーを追加する

CLI から登録する

この方法でランナーを登録するには、Semaphore サーバーの設定ファイルに runner_registration_token オプションを追加する必要があります。このオプションには任意の文字列を設定します。セキュリティ上の問題を避けるため、十分に複雑な文字列を選んでください。

semaphore runner setup コマンドでランナートークンを持っているかどうか尋ねられたら、No と答えます。その後、次のコマンドでランナーを登録します。

semaphore runner register --config /path/to/your/config/file.json

または

echo REGISTRATION_TOKEN | semaphore runner register --stdin-registration-token --config /path/to/your/config/file.json

設定ファイル

semaphore runner setup コマンドを実行すると、次のような設定ファイルが作成されます。

{
  "tmp_path": "/tmp/semaphore",
  "web_host": "https://semaphore_server_host",

  // Here you can provide other settings, for example: git_client, ssh_config_path, etc.
  // ...
  
  // Runner specific options
  "runner": {
    "token": "your runner's token",
    // or
    "token_file": "path/to/the/file/where/runner/saves/token",

    // How often (in seconds) the runner polls the server for jobs.
    // Default: 5. Raise this when many runners share one server.
    "check_interval_seconds": 5

    // Other runner-specific options: max_parallel_tasks, webhook, one_off, etc.
  }
}

このファイルは、semaphore runner setup を再度実行しなくても手動で編集できます。

ランナーを再登録するには、semaphore runner register コマンドを使用します。これにより、設定で指定されたファイル内のトークンが上書きされます。

ランナーの実行

次のコマンドでランナーを起動できます。

semaphore runner start --config /path/to/your/config/file.json

これでランナーはタスクを実行する準備ができました。

Docker でランナーを実行する

semaphoreui/runner イメージはランナーを自動的に起動します。サーバーの URL と登録トークンは環境変数で渡します。

docker run -d \
  -e SEMAPHORE_WEB_ROOT=https://semaphore.example.com \
  -e SEMAPHORE_RUNNER_REGISTRATION_TOKEN=<token> \
  semaphoreui/runner:latest

playbook で追加の Python パッケージが必要な場合は、requirements.txt を /etc/semaphore/requirements.txt にマウントします。コンテナは起動のたびに、ランナーがサーバーに接続する前に pip3 でこれをインストールします。

docker run -d \
  -e SEMAPHORE_WEB_ROOT=https://semaphore.example.com \
  -e SEMAPHORE_RUNNER_REGISTRATION_TOKEN=<token> \
  -v "$(pwd)/requirements.txt:/etc/semaphore/requirements.txt:ro" \
  semaphoreui/runner:latest

パッケージのインストール先や失敗時の扱いの詳細については、追加の Python 依存関係のインストールを参照してください。

ポーリング間隔(check_interval_seconds)

各ランナーは、新しいジョブを取得するために一定の間隔で Semaphore サーバーをポーリングします。 ランナーの設定ファイルで設定します。

{
  "runner": {
    "check_interval_seconds": 5
  }
}

または、環境変数を使用します。

SEMAPHORE_RUNNER_CHECK_INTERVAL_SECONDS=5

値	効果
1	ジョブは約 1 秒以内に取得されます。低レイテンシーの実行に最適です。
5(デフォルト)	取得の遅延とリクエスト量のバランスを取ります。
より大きい値(例: 10〜30)	1 台のサーバーに対して多数のランナーを運用する場合に HTTP トラフィックを削減します。ジョブの開始がやや遅れる場合があります。

Semaphore UI のランナーページでは、セットアップ用スニペット(設定ファイル、Docker、環境変数の例)を生成する際に、 この設定を詳細オプションとして表示します。

無効な値または 0 を指定した場合は、デフォルトの 5 秒にフォールバックします。

タスクの進捗報告は、この設定とは独立して固定の 1 秒間隔で行われます。進捗リクエストはランナーの ハートビートも兼ねているためです。

リクエストのタイムアウト(connection.timeout_seconds)

ランナーがサーバーへ送信するすべてのリクエストには上限が設けられています。TCP 接続、TLS ハンドシェイク、レスポンスヘッダーの待機のそれぞれに、この秒数が割り当てられます。これがないと、 接続を受け付けたあとに応答しなくなったサーバーによって、オペレーティングシステムが諦めるまで ランナーが停止します。さらに、リクエストが詰まるとランナーは以降のサイクルをスキップするため、 ハートビートが止まり、サーバーはランナーをオフラインと判定します。

{
  "runner": {
    "connection": {
      "timeout_seconds": 3
    }
  }
}

または、環境変数を使用します。

SEMAPHORE_RUNNER_CONNECTION_TIMEOUT_SECONDS=3

デフォルトは 3 秒です。詰まったリクエストが、それを開始したポーリングサイクルより長く残らないように、 check_interval_seconds より小さい値にしてください。低速または輻輳した回線でサーバーに接続しており、 ランナーのログに timeout awaiting response headers が出る場合は値を大きくします。タイムアウトした 進捗報告はログレコードを保持し、次のサイクルで再送されるため、タスクの出力が失われることはありません。

リクエストボディのアップロードは意図的に制限していません。大量のタスクログが転送中に 切り捨てられることはありません。

ランナータグ(Pro)

プロジェクトのランナーに 1 つ以上のタグを割り当てられます。テンプレートでタグを必須にすると、タスクは一致するランナーでのみ実行されます。タグはプロジェクトの UI でランナーを追加する際に設定し、必須タグはテンプレートの設定で指定します。

ランナーの登録解除

Web インターフェースからランナーを削除できます。

---

または、CLI からランナーの登録を解除します。

semaphore runner unregister --config /path/to/your/config/file.json

セキュリティ

ランナーは、登録時に発行される不透明なベアラートークン(X-Runner-Token)を使用してサーバーに認証します。 このトークンは他の認証情報と同様に保護してください。アクセスが制限された設定ファイルや シークレットマネージャーに保存することを推奨します。

警告

サーバーとランナー間の通信には HTTPS を使用してください。特に、両者が同じプライベートネットワーク上にない場合は 必須です。自己署名証明書や内部 CA の証明書を使用する場合は、ランナー側で runner.connection.server_ca_cert_file を設定してください。 本番環境では runner.connection.skip_tls_verify を使用しないでください。