CircleCI ランナーの概要

CircleCI ランナーは、https://circleci.com/ja/pricing[Scale プラン]をご利用のお客様と、CircleCI Server v3.1.0 以上をご利用のお客様に提供されています。 Please reach out to your sales representative (or contact us) for information on how to sign up for the Scale plan.

はじめに

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

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

CircleCI ランナーのユース ケース

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

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

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

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

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

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

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

利用可能な CircleCI ランナー プラットフォーム

CircleCI ランナーは、複数のプラットフォームに対応しています。 サポート レベルは、次の 2 つのカテゴリに分かれます。

Supported

*サポート対象*レベルのプラットフォームでは、各システムで CircleCI ランナーのビルドとテストが完了しています。

*サポート対象*プラットフォームには、以下が提供されます。

  • ドキュメントとベスト プラクティス

  • サポート: CircleCI カスタマー エンジニアによる、ゴールド サポートで規定されている通常のサービス レベル アグリーメント (SLA) の範囲内の問題解決支援

*サポート対象*の CircleCI ランナーは、次のプラットフォームで利用できます。

  • Ubuntu 18.04 以降 (x86_64 または ARM64)

  • RHEL8-x86_64

  • Mac OS X 10.15 以降 (Intel)

  • macOS 11.2 以降 (Apple M1)

  • Docker (x86_64)

  • Kubernetes (x86_64)

  • Windows Server 2019, 2016 (x86_64)

Preview

プレビュー レベルのプラットフォームでは、CircleCI ランナーは開発途中であり、テストが完了していません。

プレビュー プラットフォームには、以下が提供されます。

  • 試作段階の完全なインテグレーション (そのため、インストール、構成、デプロイには、手動の構成作業がある程度必要な可能性があります)

  • 試作段階のドキュメントとベスト プラクティス

  • サポート: CircleCI カスタマー エンジニアによる、CircleCI ランナーのインストール、構成、運用のベスト プラクティスの支援とガイダンス

    • CircleCI ランナーのユーザー エクスペリエンスを迅速に改善し、ランナーが*サポート対象*プラットフォームの必須基準を満たせるよう、ぜひフィードバックをお寄せください。

*プレビュー*の CircleCI ランナーは、次のプラットフォームで利用できます。

  • 上記以外の Linux ディストリビューション - RHEL、SUSE、Debian など (x86_64 または ARM64)

  • Docker (ARM64)

  • Kubernetes (ARM64)

プレビューの CircleCI ランナーは現在鋭意開発中です。環境に対するサポートやユースケースに関するご質問がある場合はhttps://circleci.com/ja/contact/[お問い合わせ]ください。 また、https://circleci.canny.io/cloud-feature-requests[フィードバック]やhttps://discuss.circleci.com/t/self-hosted-runners-are-here/38159[ランナーのディスカッション ページ]への投稿もぜひお寄せください。開発の参考にさせていただきます。

使用方法

CircleCI ランナーの利用を開始するには、次の手順を実行します。

CircleCI ランナーの運用

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

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

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

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

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

SSH での再実行 (英語)

CircleCI runner supports rerunning a job with SSH for debugging purposes. Instructions on using this feature can be found at Debugging with SSH.

The 'Rerun job with SSH' feature is disabled by default. To enable this feature, see Installing the CircleCI Runner.

パブリック リポジトリ

CircleCI ランナーは、[Build Forked Pull Requests (フォークされたプル リクエストをビルド)] 設定が有効になっているパブリック プロジェクトでの使用は推奨されません。 このようなパブリック プロジェクトでは、他のユーザーがリポジトリをフォークし、コードをコミットしてプル リクエストを作成できるため、悪意のあるアクターによってマシンに変更が加えられたり、マシンでコードが実行されたりする可能性があります。 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 "Hi I'm on Runners!"

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

名前空間 (namespace) は、ユーザーまたは組織が要求する一意の識別子です。 各ユーザーまたは組織が要求できる一意の名前空間は 1 つだけで、後から変更することはできません。 デフォルトでは、組織も名前空間を 1 つしか要求できないように制限されています。 これは、名前空間の占拠や取り違えを防ぐためです。 名前空間を変更する必要がある場合は、https://support.circleci.com/hc/ja-jp[サポート]にお問い合わせください。

制限事項

標準的な CircleCI 機能のほとんどすべてをランナー ジョブで使用できますが、現時点では、まだいくつかサポートされていない機能があります。 ランナー ジョブを使用するうえでそれらの機能が重要な場合は、以下の canny ページのうち該当するものからお知らせください。

Learn more

Take the runner course with CircleCI Academy to learn more about running jobs on your infrastructure.



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

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


クリエイティブ・コモンズ・ライセンス
CircleCICircleCI ドキュメントは、クリエイティブ・コモンズの表示--非営利-継承 4.0 国際ライセンス に基づいてライセンス供与されています。