はじめよう

CircleCI ランナーの概要

CircleCI ランナーは、現在、 Scale プラン でのみ提供されます。Scale プランへのお申し込み方法については、営業担当者へお問い合わせください。

はじめに

CircleCI ランナーを利用することで、自社インフラストラクチャでジョブを実行できるようになります。これにより、ビルドとテストが可能なアーキテクチャの幅が広がるだけでなく、環境をより細かく制御することもできます。下図は、CircleCI ランナーが既存のシステムをどのように拡張するのかを示しています。

CircleCI ランナーのアーキテクチャ
Figure 1. ランナーのアーキテクチャ

ランナーのユース ケース

CircleCI では、ランナーのユース ケースとして主に 2 つのシナリオを想定しています。

  • 特権アクセスと制御 - 環境の分離に関する要件が厳しい企業では、オンプレミス環境やアクセス制限されたインフラストラクチャでジョブを実行するよう義務付けられている場合があります。ランナーを使用することで、次のようなことが可能になります。

    • IP 制限 - 自社で制御可能な静的 IP アドレスを使用できます。

    • ID とアクセス管理 (IAM) 権限 - AWS にセットアップしたランナーに、IAM の権限を割り当てることができます。

    • オペレーティング システムの監視

    • プライベート ネットワークへの接続

  • 企業独自のコンピューティング要件 - CircleCI のリソース クラスとして提供されていない環境やアーキテクチャでジョブを実行する必要のあるお客様は、ランナーを使用してニーズを満たすことができます。

ランナーの操作

CircleCI ランナーのインストール後、ランナーは circleci.com をポーリングし動作します、ジョブを実行し、ステータス、ログ、アーティファクトを CircleCI に報告します。新しいバージョンがリリースされると、ランナーはジョブを実行していないときに自動で更新します。

ランナーは、ローンチ エージェントとタスク エージェントという 2 つの要素で構成されます。

  • ローンチ エージェント (launch-agent) - タスクの実行 (1 つのジョブを分解して行う並列実行) に必要な情報の収集と、タスク エージェント プロセスのダウンロードおよび起動を行います。

  • タスク エージェント (task-agent) - ローンチ エージェントによって取得、設定されたタスクの実行を行います。

この仕組みにより、管理者は、task-agent が launch-agent よりも低い権限レベルで実行されるよう構成できます。ジョブの実行を許可したすべてのユーザーには、task-agent と同等の権限が付与されます。以降で説明するデプロイメントの推奨事項は、このアプローチに基づいています (ローンチ エージェントは root ユーザー、タスク エージェントは circleci ユーザーとして実行されます)。

CircleCI ランナーの制限事項

CircleCI ランナーを使用する際には、注意の必要な点がいくつかあります。

現在、ランナーが公式にサポートしているプラットフォームは以下のとおりです。

  • Intel + Ubuntu

  • Arm64 + Ubuntu

  • Intel + macOS

上記以外のプラットフォームについてもテスト済みですが、公式にはまだサポートされていません。テスト済みでサポートされていないプラットフォームとテストされていないプラットフォームの詳細については、「CircleCI ランナーのインストール」を参照してください。

以下の機能は、CircleCI ランナーにはまだ実装されていませんが、今後提供される予定です。

  • SSH での再実行

  • テストの分割

  • add_ssh_keys

パブリック リポジトリ

CircleCI ランナーは、「Build Forked Pull Requests (フォークされたプル リクエストをビルド)」 設定が有効になっているパブリック プロジェクトでの使用は推奨されません。このようなパブリック プロジェクトでは、他のユーザーがリポジトリをフォークし、コードをコミットしてプル リクエストを作成できるため、悪意のあるアクターによってマシンに変更が加えられたり、マシンでコードが実行されたりする可能性があります。CircleCI ランナーで未信頼のジョブが実行されると、ジョブ間で環境が永続化されている場合には特に、マシンやネットワーク環境に重大なセキュリティ リスクが生じます。このようなリスクには、次のものがあります。

  • 悪意のあるプログラムがマシンで実行される。

  • マシンのランナー サンドボックスの外部で操作が行われる。

  • マシンのネットワーク環境に外部からアクセスされる。

  • 不要なデータや危険なデータがマシンに保持される。

前提条件

CircleCI ランナーを使用するには、次の条件が満たされている必要があります。

ジョブでランナーを参照する

ランナーのセットアップが完了したら、ジョブでランナーを参照する必要があります。これを行うには、.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 "CircleCI ランナーへようこそ!"

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

名前空間 (namespace) は、ユーザーまたは組織が要求する一意の識別子です。各ユーザまたは組織は、1つのユニークで不変のネームスペースを持つことができます。デフォルトでは、組織も名前空間を 1 つしか要求できないように制限されています。これは、名前空間の占拠や取り違えを防ぐためです。名前空間を変更する必要がある場合は、 サポート にお問い合わせください。