CircleCI のセルフホストランナーに関するよく寄せられるご質問
このページの内容
- FAQ
- CircleCI でのタスクとジョブの違いを教えてください。
- ランナーのリソースクラスとは何ですか？ また、リソースクラストークンとは何ですか？
- CircleCI のセルフホストランナーのセキュリティモデルは、どのようになっていますか。
- マシンランナーを使用するジョブに必要な依存関係をインストールする方法を教えてください。
- どのような接続が必要ですか?
- CircleCI のセルフホストランナーを使用する場合、キャッシュ、ワークスペース、アーティファクトはどのように機能しますか?
- ジョブ間の状態を管理するためのベストプラクティスを教えてください。
- 非アクティブなセルフホストランナーは、どれだけの期間セルフホストランナーのインベントリのページに保持されますか？
- セルフホストランナーのリソースクラスは削除できますか？
- セルフホストランナーのリソースクラスの作成、削除、閲覧が可能なのは？
- ランナーリソースクラストークンは削除できますか？
- ランナーリソースクラストークンは追加で作成できますか？
- OSS プロジェクトのメンバーのジョブで、その人が組織のメンバーではない場合、組織のセルフホストランナーを使用できますか。
- テスト分割ジョブのステップが circleci: command not found でエラーになった理由は？
- コンテナランナーに関してよく寄せられるご質問
- 1 つのコンテナランナーのデプロイで使用できるリソースクラスは 1 つだけですか?
- コンテナランナーで使用されるのは、プッシュベースモデルとプルベースモデルのどちらですか?
- コンテナランナーを使って、現在使用中の Kubernetes クラスタをスケーリングできますか?
- コンテナランナーが扱える同時実行タスクの数に上限はありますか?
- リモート Docker または Docker in Docker (DIND) を介してコンテナランナーで Docker イメージをビルドすることは可能ですか？
- Kubernetes 以外をコンテナランナーで使用できますか？
- コンテナランナーでは特定の Kubernetes プロバイダーを使用する必要がありますか？
- コンテナランナーは、Pod をデプロイしたクラスタに置く必要がありますか？
- コンテナランナーをインストールできるプラットフォームを教えてください。
- コンテナランナーは arm64 Docker イメージをサポートしていますか？
- コンテナランナーのアンインストール方法を教えてください。
- コンテナランナーは、CircleCI の既存のセルフホストランナーの代わりとなる機能ですか。
- agent.ReplicaCount を増やすとどうなりますか。
- 1 つの Kubernetes クラスタに 2 つのコンテナランナーをデプロイした場合、 agent.maxConcurrentTasks パラメーターはどのように適用されますか。
- 最新の Helm チャートへのアップグレード方法は？
- コンテナランナーのバージョンはどのように更新されますか？
- コンテナランナーのバージョンはどのようにサポートされますか？
- コンテナランナーについてセキュリティ上の注意事項はありますか？
- IAM ロールを使って ECR からのイメージのプルを承認するにはどうすればよいですか？
- コンテナランナーを使った設定ファイルのフルサンプルはありますか？
- マシンランナーに関してよく寄せられるご質問
- セルフホストランナーをインストールしたホストがジョブを実行しているかどうかを確認する方法は？
このページでは、CircleCI のセルフホストコンテナとマシンランナーに関してよく寄せられるご質問にお答えします。
FAQ
CircleCI でのタスクとジョブの違いを教えてください。
タスクは CircleCI での作業の最小単位です。 あるジョブに 並列実行 が 1 つある場合、それは 1 つのタスクと見なされます。 ジョブに並列実行が n 個あり、n が 1 より大きい場合、そのジョブは n 個のタスクを作成して実行します。
ランナーのリソースクラスとは何ですか？ また、リソースクラストークンとは何ですか？
リソースクラスは、CircleCI ジョブとそのジョブを処理するために識別されたランナー (またはコンテナランナー) のタイプを一致させるためのラベルです。 リソースクラスの最初の部分は組織の名前空間です。 たとえば、 circleci/documentation などです。
リソースクラスを使用すると、セルフホストランナーのプールを特定して、特定のリソースにジョブを送信するように設定できます。 たとえば、macOS を実行する複数のマシンと Linux を実行する複数のマシンがある場合、ぞれぞれに対して、 orgname/macOS と orgname/linux のリソースクラスを作成することができます。 .circleci/config.yml のジョブレベルでは、リソースクラスに基づいて、ジョブの送信先となるセルフホストランナーのリソースを関連付けることができます。
リソースクラスを作成するたびに、指定したリソースクラスと関連付けられた*リソースクラストークン*が生成されます。 このトークンは、リソースクラスが有効であることを CircleCI が認証する仕組みです。
CircleCI のセルフホストランナーのセキュリティモデルは、どのようになっていますか。
マシンランナーを使うと、セルフホストランナーのインストール時にジョブを実行するユーザーを選択できます。 このユーザーにジョブの実行に必要な権限のみを付与するかどうかは、お客様の判断でお決めいただけます。 コンテナランナーのセキュリティーモデルの詳細については、 コンテナランナー のインストールのページをご覧ください。
| ジョブに Docker デーモンへのアクセスを許可することは、ユーザーにマシンへの root アクセスを許可するのと同じことです。 |
マシンランナーを使用するジョブに必要な依存関係をインストールする方法を教えてください。
依存関係をインストールする方法は、主に 2 つあります。
-
ジョブが必要な依存関係をインストールできるようにする
これは最も柔軟性が高い方法ですが、ツールを全体にインストール、または重複しない方法で (作業ディレクトリなどに) ツールをインストールできる権限をジョブに付与する必要があります。
-
マシンランナーがインストールされているマシンに依存関係をプリインストールする
この方法は最も安全な方法ですが、ジョブの依存関係が変わった場合、セルフホストランナーマシンの再設定が必要になります。
どのような接続が必要ですか?
ジョブの取得と実行の際に CircleCI に接続するために、runner.circleci.com と circleci-binary-releases.s3.amazonaws.com へのアウトバウンド HTTPS 接続が必要です。
| セルフホストランナーにインバウンド接続は必要ありません。 それ以外では、ジョブの内容に応じた接続が必要になります。 |
チェックアウトステップでは、VCS プロバイダーへのアクセスが必要です。 キャッシュ、ワークスペース、アーティファクトを使用する場合は、circleci-tasks-prod.s3.us-east-1.amazonaws.com へのアウトバウンド HTTPS 接続が必要になります。 |
CircleCI のセルフホストランナーを使用する場合、キャッシュ、ワークスペース、アーティファクトはどのように機能しますか?
キャッシュ、ワークスペース、アーティファクトは、ジョブ間でデータを永続化し、ビルドを迅速化するために導入できる方法です。 これらの 3 つの機能はすべて、セルフホストランナーとの互換性があります。
これらの概念の詳細については、下記をご覧ください。
データの永続化 のページでも、詳細をご確認いただけます。
アーティファクトのストレージを自社で完全に管理したい場合は、組み込みのステップを使用せず、ご希望のストレージバックエンドに直接アーティファクトをアップロードすることをお勧めします。
ジョブ間の状態を管理するためのベストプラクティスを教えてください。
マシンランナーには、ジョブ間の状態に関する厳格な決まりはありません。 マシンランナーはジョブごとに一意の作業ディレクトリを作成し、後で削除するように構成できますが、必須ではありません。 デフォルトでは、ジョブが作業ディレクトリの外にファイルを配置することは制限されていません。
一般的には、再現性が高まるよう、ジョブが状態に依存することは最小限に抑えることをお勧めします。 そのためには、前のジョブの結果に依存せずに確実にジョブが実行されるように、ジョブの最初にクリーンアップステップを配置するのが効果的です。
| ホスト上に保持されるキャッシュをジョブ間で利用すると、ビルド時間を短縮できますが、一方で、再現性は低下します。また、長期的には、ディスク容量を使い果たす可能性もあります。 その結果、これにより課金対象の使用量が増える場合があります。 |
非アクティブなセルフホストランナーは、どれだけの期間セルフホストランナーのインベントリのページに保持されますか？
CircleCI へのコンタクトが 12 時間ない場合、そのセルフホストランナーは CircleCI Web アプリ のインベントリのページに表示されなくなります。
セルフホストランナーのリソースクラスは削除できますか？
はい、できます。セルフホストランナーのリソースクラスは、 CLI より削除できます。 このアクションは取り消すことができないため、そのリソースクラスとそれに紐づくトークンを永遠に削除して良いか確認してください。
circleci runner resource-class delete <resource-class> --forceセルフホストランナーのリソースクラスの作成、削除、閲覧が可能なのは？
セルフホストランナーのリソースクラスの作成と削除は、VCS プロバイダーの組織管理者が行えます。 CLI を介したリソースクラスリストの閲覧は、リソースクラスが関連付けられている VCS プロバイダーの組織ユーザーであれば誰でも可能です。
ランナーリソースクラストークンは削除できますか？
はい、できます。ランナーリソースクラストークンは、 CLI より削除することができます。 このアクションは取り消すことができないため、そのトークンを永遠に削除して良いか確認してください。 削除されるのはトークンのみであり、リソースクラス自体は削除されないのでご注意ください。
トークンと識別子のリストを取得するには以下を実行します。
circleci runner token list <resource-class name>トークン自体を削除するには以下を実行します。
circleci runner token delete <token identifier>ランナーリソースクラストークンは追加で作成できますか？
はい、できます、特定のランナーリソースクラスの追加ランナーリソースクラストークンは CLI から作成できます。
トークンを作成するには以下を実行します。
circleci runner token create <resource-class-name> <nickname>OSS プロジェクトのメンバーのジョブで、その人が組織のメンバーではない場合、組織のセルフホストランナーを使用できますか。
使用できません。ランナーのリソースクラスを所有する組織に関連付けられていないジョブでそのランナーのリソースクラスを使用することはできません。 組織のメンバーである OSS プロジェクトのメンバーのみがその組織のセルフホストランナーを使うことができます。
テスト分割ジョブのステップが circleci: command not found でエラーになった理由は？
セルフホストランナーでは、すべてのコマンドで circleci-agent を使用しますが、クラウド版 CircleCI では、テスト分割やステップ停止などのコマンドで circleci-agent または circleci のいずれかを使用します。 circleci を CircleCI のローカル CLI と混同しないようご注意ください。circleci は、単に circleci-agent の別名です。
テストコマンドを circleci-agent にプロキシできるようにするためにセルフホストランナージョブで CircleCI のローカル CLI を使用したい場合は、ジョブのステップから CLI をインストールしてください。 マシンランナー用のマシンに CLI を 依存関係 としてインストールするか、コンテナランナーの Docker イメージに含めます。
コンテナランナーに関してよく寄せられるご質問
ここでは、CircleCI のコンテナランナーに関してよく寄せられるご質問にお答えします。
1 つのコンテナランナーのデプロイで使用できるリソースクラスは 1 つだけですか?
いいえ。コンテナランナーのデプロイにはリソースクラスをいくつでも使用できます。 コンテナランナーでジョブを正常に実行するには、少なくとも 1 つのリソースクラスが必要です。
コンテナランナーで使用されるのは、プッシュベースモデルとプルベースモデルのどちらですか?
コンテナランナーはプルベースモデルを使用します。
コンテナランナーを使って、現在使用中の Kubernetes クラスタをスケーリングできますか?
コンテナランナー自体が単一のレプリカセットを独自にデプロイし、スケーリングは今のところ必要ありません。 コンテナランナーが Kubernetes クラスタ自体をスケーリングすることはありません。 ただし、クラスタ内に利用可能なリソースがあれば、作業をスケジュールします。
クラスタスケーリングのシグナルとして queue depth API の使用をご検討ください。
コンテナランナーが扱える同時実行タスクの数に上限はありますか?
コンテナランナーは、ランナーの最大同時実行数を上限として作業を要求およびスケジュールします。 また、デフォルトでは、コンテナランナーは最大 20 個のタスクを同時にスケジュールおよび実行できるように設定されています。 ご利用のランナーで 20 個を上回る同時実行数が許可されている場合は、Helm を使用して別の値に設定できます。 コンテナランナーページの agent.maxConcurrentTasks パラメータを参照してください。
組織でのランナーの同時実行制限数は、既存の machine セルフホストランナーと共有されます。 組織で使用しているランナーの同時実行制限数がわからない場合は、CircleCI の担当者にお問い合わせいただくか、 サポートチケット をお送りください。
リモート Docker または Docker in Docker (DIND) を介してコンテナランナーで Docker イメージをビルドすることは可能ですか？
詳細については、 コンテナイメージのビルド をお読みください。
Kubernetes 以外をコンテナランナーで使用できますか？
現時点では使用できません。 Kubernetes と Helm をご使用いただく必要があります。
コンテナランナーでは特定の Kubernetes プロバイダーを使用する必要がありますか？
いいえ、どの Kubernetes プロバイダーもご利用いただけます。
コンテナランナーは、Pod をデプロイしたクラスタに置く必要がありますか？
現時点ではその必要があります。
コンテナランナーをインストールできるプラットフォームを教えてください。
コンテナランナーとタスクを実行する Pod をインストールできるのは amd64 と arm64 Linux です。
コンテナランナーは arm64 Docker イメージをサポートしていますか？
はい、コンテナランナーは amd64 イメージか arm64 Docker イメージのいずれかを使用するジョブ、および amd64 ノードや arm64 ノードが混在する Kubernetes クラスタを使用するジョブをサポートしています。 特定のアーキテクチャ用にビルドされたイメージを使用する場合、その CPU アーキテクチャを持つノードをターゲットにするようにリソースクラスを設定する必要があります。 Kubernetes では複数のノードラベルが自動的に用意され、ジョブのリソースクラスの Pod の仕様が正しいノードにデプロイされるように設定する際に役立ちます。 下記の例はリソースクラスの設定例です。 これらのラベルの詳細については、 Kubernetes のドキュメント を参照してください。
agent:
resourceClasses:
<amd64 image resource class>:
token: <amd64 resource class token>
spec:
nodeSelector: # nodeSelector will cause this resource class to only create pods on nodes with the specified labels and values
kubernetes.io/arch=amd64
<arm64 image resource class>:
token: <arm64 resource class token>
spec:
nodeSelector:
kubernetes.io/arch=arm64
<multiarchitecture image resource class>: # note no nodeSelector is defined for the multiarchitecture image resource class
token: <multiarchitecture resource class token>コンテナランナーのアンインストール方法を教えてください。
container-agent デプロイをアンインストールするには、次を実行します。
$ helm uninstall container-agentこのコマンドは、チャートに関連付けられた Kubernetes オブジェクトをすべて削除し、リリースを削除します。
コンテナランナーは、CircleCI の既存のセルフホストランナーの代わりとなる機能ですか。
いいえ、コンテナランナーは、マシンランナーを補完するための機能です。 コンテナランナーとマシンランナーが両方あることで、CircleCI のお客様は、CircleCI のクラウドプラットフォームの場合と同じように、実行環境を柔軟に選べます (コンテナまたはマシン)。
agent.ReplicaCount を増やすとどうなりますか。
現時点では、Kubernetes が追加のコンテナランナーをデプロイしようとします。 このシナリオはテストがまだ完了しておらず、期待どおりに動作しない可能性があるため、現時点では推奨されません。
1 つの Kubernetes クラスタに 2 つのコンテナランナーをデプロイした場合、 agent.maxConcurrentTasks パラメーターはどのように適用されますか。
agent.maxConcurrentTasks パラメーターは、各エージェントに個別に適用されます。 ただし、1 つの Kubernetes クラスタに複数のコンテナランナーをデプロイすることは、現時点では推奨されません。
最新の Helm チャートへのアップグレード方法は？
Helm チャートの更新内容は、次のコマンドを使用して 適用 できます。
$ helm repo update
$ helm upgrade container-agentコンテナランナーのバージョンはどのように更新されますか？
コンテナランナーは、コンテナランナーアプリケーションおよび Helm チャートでインストールしたどちらの場合も セマンティックバージョニング を使用します。 コンテナランナーのイメージ には、メジャーバージョンとマイナーバージョンごとにフローティングタグが用意されています。このタグは、各バージョンの最新リリースと、マイナーバージョンの特定のパッチリリースを示す完全修飾タグを指定します。
コンテナランナーのバージョンはどのようにサポートされますか？
コンテナランナーアプリケーションは、同じメジャーバージョンにおけるリリースとの下位互換性と最新のマイナーバージョンにおける脆弱性やバグに対するサポートを保証します。 コンテナランナーの Helm チャートでは、同じメジャーバージョン内の値ファイルとの下位互換性を保証します。
コンテナランナーについてセキュリティ上の注意事項はありますか？
コンテナランナーでは、マシンランナーと同じく、コンテナランナーをホストするインフラストラクチャ内でユーザーが任意のコードを実行できます。つまり悪意のある攻撃者が、内部システムに関する情報を得るためにこれを悪用する可能性があります。 このリスクを軽減するため、セキュリティに関するすべてのベストプラクティスに従ってください。
IAM ロールを使って ECR からのイメージのプルを承認するにはどうすればよいですか？
IAM ロールは、 AWS ドキュメント に従って、コンテナランナーで使用するサービスアカウントに関連付けることができます。 ジョブの設定ファイルのイメージで AWS 認証情報が指定されている場合、コンテナランナーのサービスアカウントに付与されている IAM ロールの代わりに AWS 認証情報が使用されます。 コンテナランナーのサービスアカウントの詳細については、 コンテナランナー を参照してください。
コンテナランナーを使った設定ファイルのフルサンプルはありますか？
CI ジョブを Kubernetes を使わずにコンテナ内で実行したい場合は、Docker がインストールされた マシンランナー を使用できます。
マシンランナーに関してよく寄せられるご質問
ここでは、CircleCI のマシンランナーに関してよく寄せられるご質問に回答します。
セルフホストランナーをインストールしたホストがジョブを実行しているかどうかを確認する方法は？
現時点では、以下のコマンドを使ってホストをクエリすることを推奨します。
ps aux | pgrep -f circleci-launch-agent上記コマンドの結果、3 つ以上のプロセスが返された場合、セルフホストランナーがタスクを実行していると想定できます。
grep プロセス自体も 1 つのプロセスとしてカウントされ、 ローンチエージェント プロセスは別のプロセスとしてカウントされるため、必ず 2 つを超える数のプロセスがあることを確認してください。