Introduction to Nomad Cluster Operation

Last updated
Tags Server v2.x Server v3.x Server Admin

CircleCI では、プライマリ ジョブ スケジューラとして Nomad を使用します。 This chapter provides a basic introduction to Nomad for understanding how to operate the Nomad Cluster in your CircleCI installation.


Diagram of the Nomad cluster
Figure 1. Nomad クラスタの管理
  • Nomad Server: Nomad servers are the brains of the cluster; they receive and allocate jobs to Nomad clients. In CircleCI, a Nomad server runs on your Services machine as a Docker Container.

  • Nomad Client: Nomad clients execute the jobs they are allocated by Nomad servers. 通常、Nomad クライアントは専用のマシン (多くの場合は VM) 上で実行されるため、マシンの能力を最大限に活用できます。 複数の Nomad クライアントで 1つのクラスタを構成することができ、Nomad サーバーはスケジュールアルゴリズムに従ってクラスタにジョブを割り当てます。

  • Nomad Jobs: A Nomad job is a specification, provided by a user, that declares a workload for Nomad. A Nomad job corresponds to an execution of a CircleCI job. If the job uses parallelism, say 10 parallelism, then Nomad will run 10 jobs.

  • *ビルドエージェント:*ビルドエージェントは CircleCI によって記述された Go プログラムで、ジョブ内のステップを実行し、結果を報告します。 ビルドエージェントは、Nomad ジョブ内部のメイン処理として実行されます。


The following section is a basic guide to operating a Nomad cluster in your installation.

nomad CLI は Service インスタンスにインストールされます。 Nomad クラスタとやり取りするようにあらかじめ設定されているため、nomad コマンドを使用して、以下で説明するコマンドを実行できます。


The get a list of statuses for all jobs in your cluster, run:

nomad status

The Status is the most important field in the output, with the following status type definitions:

  • running: Nomad でジョブの実行が開始されています。 このステータスは通常、CircleCI 上のジョブが開始されたことを意味します。

  • pending: There are not enough resources available to execute the job inside the cluster.

  • dead: Nomad でジョブの実行が終了しました。 対応する CircleCI のジョブまたはビルドが成功したか失敗したかにかかわらず、ステータスは dead になります。


Nomad クライアントの一覧を表示するには、以下のコマンドを実行します。

nomad node-status
nomad node-status コマンドを実行すると、現在稼働中の Nomad クライアント (ステータスが active) と、クラスタから除外された Nomad クライアント (ステータスが down) の両方が報告されます。 したがって、現在のクラスタの容量を知るには、ステータスが active の Nomad クライアントの数を数える必要があります。


nomad node-status -self

This will give information such as how many jobs are running on the client and the resource utilization of the client.


As noted in the Nomad Jobs section above, a Nomad Job corresponds to an execution of a CircleCI job. Therefore, Nomad Job logs can sometimes help to understand the status of a CircleCI job if there is a problem. To get logs for a specific job, run:

nomad logs -job -stderr <nomad-job-id>
Be sure to specify the -stderr flag as this is where most Build Agent logs appear.

nomad logs -job コマンドは便利ですが、-job フラグは指定されたジョブのランダム割り当てを使用するため、必ずしも正確とは限りません。 割り当て(allocation)は Nomad ジョブ内のさらに小さい単位です。 これについては、このドキュメントでは取り上げません。 詳細については、[Nomad の公式ドキュメント]を参照してください。


  1. nomad status コマンドで、ジョブ ID を取得します。

  2. Get the allocation ID of the job with nomad status <job-id> command.

  3. Get the logs from the allocation with nomad logs -stderr <allocation-id>


By default, your Nomad Client is set up within an Auto Scaling Group (ASG) within AWS. To view settings:

  1. Go to your EC2 Dashboard and select Auto Scaling Groups from the left hand menu

  2. Nomad クライアントのシャットダウン

  3. Select Actions > Edit to set Desired/Minimum/Maximum counts. This defines the number of Nomad Clients to spin up and keep available. Use the Scaling Policy tab to scale up your group automatically at your busiest times, see below for best practices for defining scaling policies. Use nomad job metrics to assist in defining your scaling policies.

Auto Scaling ポリシーのベストプラクティス

こちらの連載では、CircleCI のエンジニアリング チームが自動スケーリングの一般的なベスト プラクティスを見つけるために取り組んだコスト削減のシミュレーションについて解説しています。 AWS の Auto Scaling を設定する際は、以下のベストプラクティスを適用することを検討してください。

  1. 原則として、クラスタは、ビルドのキューイングを回避できるくらい十分な大きさにします。 具体的には、一般的なワークロードでキューイングが 1秒未満、高価なハードウェアや高レベルな並列処理で実行されるワークロードでは 10秒未満になるようにします。 Sizing to reduce queuing to zero is best practice because of the high cost of developer time. It is difficult to create a model in which developer time is cheap enough for under-provisioning to be cost-effective.

  2. Create an Auto Scaling Group with a Step Scaling policy that scales up during the normal working hours of the majority of developers and scales back down at night. 平日の勤務時間中にスケールアップし、夜間にスケールダウンしておくことで、トラフィックが少ない夜間にオーバープロビジョニングを発生させることなく、開発のピーク時に待ち時間を抑制するのがベスト プラクティスです。 なお、過去の数多くのビルドデータによると、通常の勤務時間中のデータセットはおおむね正規分布になっています。

This is in contrast to auto scaling throughout the day based on traffic fluctuations, because modelling revealed that boot times are actually too long to prevent queuing in real time. そのような状況では、[ステップ ポリシーに関する Amazon のドキュメント]に従って、Auto Scaling とともに CloudWatch アラームを設定してください。

Nomad クライアントのシャットダウン

Nomad クライアントをシャットダウンするときは、まずクライアントをドレイン (drain) モードに設定する必要があります。 drain モードのクライアントでは、それまでに割り当てられたジョブは完了しますが、新たにジョブを割り当てることはできません。

  1. クライアントをドレインするには、クライアントにログインし、node-drain コマンドを以下のように使用して、クライアントをドレインモードに設定します。

    nomad node-drain -self -enable
  2. Then, make sure the client is in drain mode using the node-status command:

    nomad node-status -self

Alternatively, you can drain a remote node with the following command, substituting the node ID:

nomad node-drain -enable -yes <node-id>


クライアントをシャットダウンするメカニズムを設定するには、まずクライアントを drain モードに変更し、すべてのジョブが完了してから、クライアントを終了させます。 You can also configure an ASG Lifecycle Hook that triggers a script for scaling down instances.


  1. インスタンスをドレイン モードに設定します。

  2. Monitor running jobs on the instance and wait for them to finish

  3. Terminate the instance


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