13.9. 最適化プロポーザルの生成
/rebalance エンドポイントに POST リクエストを行うと、Cruise Control は提供された最適化ゴールを基にして、Kafka クラスターをリバランスするために最適化プロポーザルを生成します。最適化プロポーザルの結果を使用して Kafka クラスターをリバランスできます。
以下のエンドポイントのいずれかを使用して最適化プロポーザルを実行できます。
-
/rebalance -
/add_broker -
/remove_broker
使用するエンドポイントは、Kafka クラスターで実行しているすべてのブローカーでリバランスを行うか、Kafka クラスターをスケールダウンした後にリバランスを行うかによって異なります。詳細は、Rebalancing endpoints with broker scaling を参照してください。
dryrun パラメーターが指定され、false に設定されない限り、最適化プロポーザルは ドライラン として生成されます。「ドライランモード」では、Cruise Control は最適化プロポーザルと推定結果を生成しますが、クラスターをリバランスしてプロポーザルを開始することはありません。
最適化プロポーザルで返される情報を分析し、プロポーザルを承認するかどうかを決定できます。
エンドポイントへの要求を行うには、以下のパラメーターを使用します。
dryrun
型: boolean､デフォルト: true
最適化プロポーザルのみを生成するか (true)、最適化プロポーザルを生成してクラスターのリバランスを実行するか (false) を Cruise Control に通知します。
dryrun=true (デフォルト) の場合は、verbose パラメーターを渡して Kafka クラスターの状態に関する詳細情報を返すこともできます。これには、最適化プロポーザルの適用前および適用後の各 Kafka ブローカーの負荷のメトリックと、前後の値の違いが含まれます。
excluded_topics
型: regex
最適化プロポーザルの計算から除外するトピックと一致する正規表現。
goals
型: 文字列のリスト。デフォルト: 設定済み default.goals リスト
最適化プロポーザルを準備するために使用するユーザー提供の最適化ゴールのリスト。goals が指定されていない場合は、cruisecontrol.properties ファイルに設定されている default.goals リストが使用されます。
skip_hard_goals_check
型: boolean、デフォルト: false
デフォルトでは、Cruise Control はユーザー提供の最適化ゴール (goals パラメーター) に設定済みのハードゴール (hard.goals) がすべて含まれていることを確認します。設定された hard.goals のサブセットではないゴールを指定すると、リクエストは失敗します。
設定されたすべての hard.goals を含まない、ユーザー提供の最適化ゴールで最適化プロポーザルを生成する場合は、skip_hard_goals_check を true に設定します。
json
型: boolean、デフォルト: false
Cruise Control サーバーによって返される応答のタイプを制御します。指定のない場合、または false に設定した場合、Cruise Control はコマンドラインでの表示用に書式設定されたテキストを返します。返された情報の要素をプログラムで抽出する場合は、json=true を設定します。これにより、jq などのツールにパイプ処理できる JSON 形式のテキストを返したり、スクリプトやプログラムで解析することができます。
verbose
型: boolean、デフォルト: false
Cruise Control サーバーが返す応答の詳細レベルを制御します。dryrun=true と併用できます。
その他のパラメーターも利用可能です。詳細は、Cruise Control Wiki の REST APIs を参照してください。
前提条件
- Kafka が実行中である。
- Cruise Control を設定 した。
- (スケールアップ用のオプション) リバランスに追加するために、ホストに新しいブローカーをインストール した。
手順
/rebalance、/add_broker、または/remove_brokerエンドポイントへの POST 要求を使用して最適化プロポーザルを生成します。デフォルトのゴールを使用した
/rebalanceへの要求の例curl -v -X POST 'cruise-control-server:9090/kafkacruisecontrol/rebalance'
キャッシュされた最適化プロポーザルは即座に返されます。
注記NotEnoughValidWindowsが返された場合、Cruise Control は最適化プロポーザルを生成するために十分なメトリクスデータを記録していません。数分待ってからリクエストを再送信します。指定されたゴールを使用した
/rebalanceへの要求の例curl -v -X POST 'cruise-control-server:9090/kafkacruisecontrol/rebalance?goals=RackAwareGoal,ReplicaCapacityGoal'
要求が、指定のゴールを満たしていると、キャッシュされた最適化プロポーザルが即座に返されます。それ以外の場合は、提供されたゴールを使用して新しい最適化プロポーザルが生成されます。計算には時間がかかります。この動作を強制するには、リクエストに
ignore_proposal_cache=trueパラメーターを追加します。ハードゴールなしで指定されたゴールを使用した
/rebalanceへの要求の例curl -v -X POST 'cruise-control-server:9090/kafkacruisecontrol/rebalance?goals=RackAwareGoal,ReplicaCapacityGoal,ReplicaDistributionGoal&skip_hard_goal_check=true'
指定のブローカーが含まれる
/add_brokerへの要求の例curl -v -X POST 'cruise-control-server:9090/kafkacruisecontrol/add_broker?brokerid=3,4'
要求には、新規ブローカーの ID のみが含まれます。たとえば、この要求は ID
3と4のブローカーを追加します。レプリカは、リバランス時に既存のブローカーから新しいブローカーに移動します。指定のブローカーを除外する
/remove_brokerへの要求の例curl -v -X POST 'cruise-control-server:9090/kafkacruisecontrol/remove_broker?brokerid=3,4'
要求には、除外されるブローカーの ID が含まれます。たとえば、この要求は ID が
3と4のブローカーを除外します。レプリカは、リバランス時に他の既存ブローカーから削除されるブローカーから移動されます。注記削除されるブローカーがトピックを除外した場合でも、レプリカは移動されます。
応答に含まれる最適化プロポーザルを確認します。プロパティーは、保留中のクラスターリバランス操作を記述します。
プロポーザルには、提案された最適化の概要、各デフォルトの最適化ゴールの概要、およびプロポーザルの実行後に予想されるクラスター状態が含まれます。
以下の情報に特に注意してください。
-
Cluster load after rebalanceの概要。要件を満たす場合には、概要を使用して、提案された変更の影響を評価する必要があります。 -
n inter-broker replica (y MB) movesはブローカー間でネットワークを介して移動されるデータ量を示します。値が高いほど、リバランス中の Kafka クラスターへの潜在的なパフォーマンスの影響が大きくなります。 -
n intra-broker replica (y MB) movesは、ブローカー内部で (ディスク間) でどれだけのデータを移動させるかを示します。値が大きいほど、個々のブローカーに対する潜在的なパフォーマンスの影響は大きくなります (ただしn inter-broker replica (y MB) movesの影響よりも小さい)。 - リーダーシップ移動の数。これは、リバランス中のクラスターのパフォーマンスにほとんど影響しません。
-
非同期応答
Cruise Control REST API エンドポイントは、デフォルトでは 10 秒後にタイムアウトしますが、プロポーザルの生成はサーバー上で継続されます。最近キャッシュされた最適化プロポーザルが準備状態にない場合や、ユーザー提供の最適化ゴールが ignore_proposal_cache=true で指定された場合は、タイムアウトが発生することがあります。
後で最適化プロポーザルを取得できるようにするには、/rebalance エンドポイントからの応答のヘッダーにあるリクエストの一意識別子を書き留めておきます。
curl を使用して応答を取得するには、詳細 (-v) オプションを指定します。
curl -v -X POST 'cruise-control-server:9090/kafkacruisecontrol/rebalance'
ヘッダーの例を以下に示します。
* Connected to cruise-control-server (::1) port 9090 (#0)
> POST /kafkacruisecontrol/rebalance HTTP/1.1
> Host: cc-host:9090
> User-Agent: curl/7.70.0
> Accept: /
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Date: Mon, 01 Jun 2023 15:19:26 GMT
< Set-Cookie: JSESSIONID=node01wk6vjzjj12go13m81o7no5p7h9.node0; Path=/
< Expires: Thu, 01 Jan 1970 00:00:00 GMT
< User-Task-ID: 274b8095-d739-4840-85b9-f4cfaaf5c201
< Content-Type: text/plain;charset=utf-8
< Cruise-Control-Version: 2.0.103.redhat-00002
< Cruise-Control-Commit_Id: 58975c9d5d0a78dd33cd67d4bcb497c9fd42ae7c
< Content-Length: 12368
< Server: Jetty(9.4.26.v20200117-redhat-00001)
タイムアウト時間内に最適化プロポーザルが準備ができなかった場合、POST リクエストを再送信できます。これには、ヘッダーにある元リクエストの User-Task-ID が含まれます。
curl -v -X POST -H 'User-Task-ID: 274b8095-d739-4840-85b9-f4cfaaf5c201' 'cruise-control-server:9090/kafkacruisecontrol/rebalance'
次のステップ
