CircleCI Runner Overview

Last updated
Tags Cloud Server v3.x

はじめに

CircleCI ランナーを利用することで、自社インフラストラクチャでジョブを実行できるようになります。 This means you will be able to build and test on a wider variety of architectures, as well as have additional control over the environment. 下図は、CircleCI ランナーが既存のシステムをどのように拡張するのかを示しています。

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

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

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

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

    • IP restrictions - Runners can have static IP addresses that you can control

    • Identity Access Management (IAM) permissions - If you set up runners in AWS, they can be assigned IAM permissions

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

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

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

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

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

サポート対象

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

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

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

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

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

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

  • RHEL8 (x86_64 または ARM64)

  • Mac OS X 10.15 以降 (Intel)

  • macOS 11.2 以降 (Apple M1)

  • Docker (x86_64 または ARM64)

  • Kubernetes (x86_64)

  • Windows Server 2019, 2016 (x86_64)

プレビュー

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

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

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

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

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

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

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

  • 上記以外の Linux ディストリビューション - RHEL、SUSEなど (x86_64 または 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 (launch-agent) - manages gathering the information required to run a task (defined as a parallel run of a job) while also downloading and launching a task agent process

  • task agent (task-agent) - handles running a task retrieved and configured by the launch agent

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

Runner concurrency

To achieve better throughput, you can break your single build process into different steps and run them concurrently (at the same time). CircleCI offers the flexibility of deploying work to runners across all your resource classes.

Rather than limit the total number of registered runners, CircleCI runners are limited by the total number of runner jobs (tasks) across your resource classes.

SSH での再実行 (英語)

CircleCI ランナーでは、デバッグのために SSHでジョブの再実行することが可能です。 Instructions on using this feature can be found at Debugging with SSH.

「SSH でジョブを再実行する」機能は、デフォルトでは無効になっています。 この機能を有効にするには、 CircleCI ランナーのインストールをご覧くださいい。

パブリック リポジトリ

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

  • Malicious programs running on the machine

  • Escaping the machine’s runner sandbox

  • Exposing access to the machine’s network environment

  • Persisting unwanted or dangerous data on the machine

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

After setting up the runner, you will need to reference it on a job by setting some fields in your .circleci/config.yml file. ランナーを使って実行するジョブについて、以下のフィールドを指定します。

  • machine: true

  • resource_class: your-namespace/your-resource

Here is a simple example of how you could set up a job:

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[サポート]にお問い合わせください。

制限事項

Almost all standard CircleCI features are available for use with runner jobs, however, a few features are not yet supported. ランナー ジョブを使用するうえでそれらの機能が重要な場合は、以下の canny ページのうち該当するものからお知らせください。

詳細を確認する

CircleCI Academy の ランナーコース を受講すると、インフラ上でのジョブの実行についてさらに詳しく学ぶことができます。



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

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