이 콘텐츠는 선택한 언어로 제공되지 않습니다.
Chapter 14. Cruise Control for cluster rebalancing
Cruise Control for cluster rebalancing is a Technology Preview only. Technology Preview features are not supported with Red Hat production service-level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend implementing any Technology Preview features in production environments. This Technology Preview feature provides early access to upcoming product innovations, enabling you to test functionality and provide feedback during the development process. For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.
You can deploy Cruise Control to your AMQ Streams cluster and use it to rebalance the load across the Kafka brokers.
Cruise Control is an open source system for automating Kafka operations, such as monitoring cluster workload, rebalancing a cluster based on predefined constraints, and detecting and fixing anomalies. It consists of four components (Load Monitor, Analyzer, Anomaly Detector, and Executor) and a REST API.
When AMQ Streams and Cruise Control are both deployed to Red Hat Enterprise Linux, you can access Cruise Control features through the Cruise Control REST API. The following features are supported:
- Configuring optimization goals and capacity limits
Using the
/rebalance
endpoint to:- Generate optimization proposals, as dry runs, based on the configured optimization goals or user-provided goals supplied as request parameters
- Initiate an optimization proposal to rebalance the Kafka cluster
-
Checking the progress of an active rebalance operation using the
/user_tasks
endpoint -
Stopping an active rebalance operation using the
/stop_proposal_execution
endpoint
All other Cruise Control features are not currently supported, including anomaly detection, notifications, write-your-own goals, and changing the topic replication factor. The web UI component (Cruise Control Frontend) is not supported.
Cruise Control for AMQ Streams on Red Hat Enterprise Linux is provided as a separate zipped distribution. For more information, see Section 14.2, “Downloading a Cruise Control archive”.
14.1. Why use Cruise Control?
Cruise Control reduces the time and effort involved in running an efficient Kafka cluster, with a more evenly balanced workload across the brokers.
A typical cluster can become unevenly loaded over time. Partitions that handle large amounts of message traffic might be unevenly distributed across the available brokers. To rebalance the cluster, administrators must monitor the load on brokers and manually reassign busy partitions to brokers with spare capacity.
Cruise Control automates this cluster rebalancing process. It constructs a workload model of resource utilization, based on CPU, disk, and network load. Using a set of configurable optimization goals, you can instruct Cruise Control to generate dry run optimization proposals for more balanced partition assignments.
After you have reviewed a dry run optimization proposal, you can instruct Cruise Control to initiate a cluster rebalance based on that proposal, or generate a new proposal.
When a cluster rebalancing operation is complete, the brokers are used more effectively and the load on the Kafka cluster is more evenly balanced.
14.2. Downloading a Cruise Control archive
A zipped distribution of Cruise Control for AMQ Streams on Red Hat Enterprise Linux is available for download from the Red Hat Customer Portal.
Procedure
- Download the latest version of the Red Hat AMQ Streams Cruise Control archive from the Red Hat Customer Portal.
Create the
/opt/cruise-control
directory:sudo mkdir /opt/cruise-control
Extract the contents of the Cruise Control ZIP file to the new directory:
unzip amq-streams-y.y.y-cruise-control-bin.zip -d /opt/cruise-control
Change the ownership of the
/opt/cruise-control
directory to thekafka
user:sudo chown -R kafka:kafka /opt/cruise-control
14.3. Deploying the Cruise Control Metrics Reporter
Before starting Cruise Control, you must configure the Kafka brokers to use the provided Cruise Control Metrics Reporter.
When loaded at runtime, the Metrics Reporter sends metrics to the __CruiseControlMetrics
topic, one of three auto-created topics. Cruise Control uses these metrics to create and update the workload model and to calculate optimization proposals.
Prerequisites
-
You are logged in to Red Hat Enterprise Linux as the
kafka
user. - Kafka and ZooKeeper are running.
- Section 14.2, “Downloading a Cruise Control archive”.
Procedure
For each broker in the Kafka cluster and one at a time:
Stop the Kafka broker:
/opt/kafka/bin/kafka-server-stop.sh
Copy the Cruise Control Metrics Reporter
.jar
file to the Kafka libraries directory:cp /opt/cruise-control/libs/cruise-control-metrics-reporter-y.y.yyy.redhat-0000x.jar /opt/kafka/libs
In the Kafka configuration file (
/opt/kafka/config/server.properties
) configure the Cruise Control Metrics Reporter:Add the
CruiseControlMetricsReporter
class to themetric.reporters
configuration option. Do not remove any existing Metrics Reporters.metric.reporters=com.linkedin.kafka.cruisecontrol.metricsreporter.CruiseControlMetricsReporter
Add the following configuration options and values to the Kafka configuration file:
cruise.control.metrics.topic.auto.create=true cruise.control.metrics.topic.num.partitions=1 cruise.control.metrics.topic.replication.factor=1
These options enable the Cruise Control Metrics Reporter to create the
__CruiseControlMetrics
topic with a log cleanup policy ofDELETE
. For more information, see Auto-created topics and Log cleanup policy for Cruise Control Metrics topic.
Configure SSL, if required.
In the Kafka configuration file (
/opt/kafka/config/server.properties
) configure SSL between the Cruise Control Metrics Reporter and the Kafka broker by setting the relevant client configuration properties.The Metrics Reporter accepts all standard producer-specific configuration properties with the
cruise.control.metrics.reporter
prefix. For example:cruise.control.metrics.reporter.ssl.truststore.password
.In the Cruise Control properties file (
/opt/cruise-control/config/cruisecontrol.properties
) configure SSL between the Kafka broker and the Cruise Control server by setting the relevant client configuration properties.Cruise Control inherits SSL client property options from Kafka and uses those properties for all Cruise Control server clients.
Restart the Kafka broker:
/opt/kafka/bin/kafka-server-start.sh
- Repeat steps 1-5 for the remaining brokers.
14.4. Configuring and starting Cruise Control
Configure the properties used by Cruise Control and then start the Cruise Control server using the cruise-control-start.sh
script. The server is hosted on a single machine for the whole Kafka cluster.
Three topics are auto-created when Cruise Control starts. For more information, see Auto-created topics.
Prerequisites
-
You are logged in to Red Hat Enterprise Linux as the
kafka
user. - Section 14.2, “Downloading a Cruise Control archive”
- Section 14.3, “Deploying the Cruise Control Metrics Reporter”
Procedure
-
Edit the Cruise Control properties file (
/opt/cruise-control/config/cruisecontrol.properties
). Configure the properties shown in the following example configuration:
# The Kafka cluster to control. bootstrap.servers=localhost:9092 1 # The replication factor of Kafka metric sample store topic sample.store.topic.replication.factor=2 2 # The configuration for the BrokerCapacityConfigFileResolver (supports JBOD, non-JBOD, and heterogeneous CPU core capacities) #capacity.config.file=config/capacity.json #capacity.config.file=config/capacityCores.json capacity.config.file=config/capacityJBOD.json 3 # The list of goals to optimize the Kafka cluster for with pre-computed proposals default.goals={List of default optimization goals} 4 # The list of supported goals goals={list of master optimization goals} 5 # The list of supported hard goals hard.goals={List of hard goals} 6 # How often should the cached proposal be expired and recalculated if necessary proposal.expiration.ms=60000 7 # The zookeeper connect of the Kafka cluster zookeeper.connect=localhost:2181 8
- 1
- Host and port numbers of the Kafka broker (always port 9092).
- 2
- Replication factor of the Kafka metric sample store topic. If you are evaluating Cruise Control in a single-node Kafka and ZooKeeper cluster, set this property to 1. For production use, set this property to 2 or more.
- 3
- The configuration file that sets the maximum capacity limits for broker resources. Use the file that applies to your Kafka deployment configuration. For more information, see Capacity configuration.
- 4
- Comma-separated list of default optimization goals, using fully-qualified domain names (FQDNs). A number of master optimization goals (see 5) are already set as default optimization goals; you can add or remove goals if desired. For more information, see Section 14.5, “Optimization goals overview”.
- 5
- Comma-separated list of master optimization goals, using FQDNs. To completely exclude goals from being used to generate optimization proposals, remove them from the list. For more information, see Section 14.5, “Optimization goals overview”.
- 6
- Comma-separated list of hard goals, using FQDNs. Seven of the master optimization goals are already set as hard goals; you can add or remove goals if desired. For more information, see Section 14.5, “Optimization goals overview”.
- 7
- The interval, in milliseconds, for refreshing the cached optimization proposal that is generated from the default optimization goals. For more information, see Section 14.6, “Optimization proposals overview”.
- 8
- Host and port numbers of the ZooKeeper connection (always port 2181).
Start the Cruise Control server. The server starts on port 9092 by default; optionally, specify a different port.
cd /opt/cruise-control/ ./bin/cruise-control-start.sh config/cruisecontrol.properties PORT
To verify that Cruise Control is running, send a GET request to the
/state
endpoint of the Cruise Control server:curl 'http://HOST:PORT/kafkacruisecontrol/state'
Auto-created topics
The following table shows the three topics that are automatically created when Cruise Control starts. These topics are required for Cruise Control to work properly and must not be deleted or changed.
Auto-created topic | Created by | Function |
---|---|---|
| Cruise Control Metrics Reporter | Stores the raw metrics from the Metrics Reporter in each Kafka broker. |
| Cruise Control | Stores the derived metrics for each partition. These are created by the Metric Sample Aggregator. |
| Cruise Control | Stores the metrics samples used to create the Cluster Workload Model. |
To ensure that log compaction is disabled in the auto-created topics, make sure that you configure the Cruise Control Metrics Reporter as described in Section 14.3, “Deploying the Cruise Control Metrics Reporter”. Log compaction can remove records that are needed by Cruise Control and prevent it from working properly.
Additional resources
14.5. Optimization goals overview
To rebalance a Kafka cluster, Cruise Control uses optimization goals to generate optimization proposals. Optimization goals are constraints on workload redistribution and resource utilization across a Kafka cluster.
AMQ Streams on Red Hat Enterprise Linux supports all the optimization goals developed in the Cruise Control project. The supported goals, in the default descending order of priority, are as follows:
- Rack-awareness
- Minimum number of leader replicas per broker for a set of topics
- Replica capacity
- Capacity: Disk capacity, Network inbound capacity, Network outbound capacity
- CPU capacity
- Replica distribution
- Potential network output
- Resource distribution: Disk utilization distribution, Network inbound utilization distribution, Network outbound utilization distribution
- Leader bytes-in rate distribution
- Topic replica distribution
- CPU usage distribution
- Leader replica distribution
- Preferred leader election
- Kafka Assigner disk usage distribution
- Intra-broker disk capacity
- Intra-broker disk usage
For more information on each optimization goal, see Goals in the Cruise Control Wiki.
Goals configuration in the Cruise Control properties file
You configure optimization goals in the cruisecontrol.properties
file in the cruise-control/config/
directory. There are configurations for hard optimization goals that must be satisfied, as well as master and default optimization goals.
Optional, user-provided optimization goals are set at runtime as parameters in requests to the /rebalance
endpoint.
Optimization goals are subject to any capacity limits on broker resources.
The following sections describe each goal configuration in more detail.
Master optimization goals
The master optimization goals are available to all users. Goals that are not listed in the master optimization goals are not available for use in Cruise Control operations.
The following master optimization goals are preset in the cruisecontrol.properties
file, in the goals
property, in descending priority order:
RackAwareGoal; MinTopicLeadersPerBrokerGoal; ReplicaCapacityGoal; DiskCapacityGoal; NetworkInboundCapacityGoal; NetworkOutboundCapacityGoal; ReplicaDistributionGoal; PotentialNwOutGoal; DiskUsageDistributionGoal; NetworkInboundUsageDistributionGoal; NetworkOutboundUsageDistributionGoal; CpuUsageDistributionGoal; TopicReplicaDistributionGoal; LeaderReplicaDistributionGoal; LeaderBytesInDistributionGoal; PreferredLeaderElectionGoal
For simplicity, we recommend that you do not change the preset master optimization goals, unless you need to completely exclude one or more goals from being used to generate optimization proposals. The priority order of the master optimization goals can be modified, if desired, in the configuration for default optimization goals.
If you need to modify the preset master optimization goals, specify a list of goals, in descending priority order, in the goals
property. Use fully-qualified domain names as shown in the cruisecontrol.properties
file.
You must specify at least one master goal, or Cruise Control will crash.
If you change the preset master optimization goals, you must ensure that the configured hard.goals
are a subset of the master optimization goals that you configured. Otherwise, errors will occur when generating optimization proposals.
Hard goals and soft goals
Hard goals are goals that must be satisfied in optimization proposals. Goals that are not configured as hard goals are known as soft goals. You can think of soft goals as best effort goals: they do not need to be satisfied in optimization proposals, but are included in optimization calculations.
Cruise Control will calculate optimization proposals that satisfy all the hard goals and as many soft goals as possible (in their priority order). An optimization proposal that does not satisfy all the hard goals is rejected by the Analyzer and is not sent to the user.
For example, you might have a soft goal to distribute a topic’s replicas evenly across the cluster (the topic replica distribution goal). Cruise Control will ignore this goal if doing so enables all the configured hard goals to be met.
The following master optimization goals are preset as hard goals in the cruisecontrol.properties
file, in the hard.goals
property:
RackAwareGoal; MinTopicLeadersPerBrokerGoal; ReplicaCapacityGoal; DiskCapacityGoal; NetworkInboundCapacityGoal; NetworkOutboundCapacityGoal; CpuCapacityGoal
To change the hard goals, edit the hard.goals
property and specify the desired goals, using their fully-qualified domain names.
Increasing the number of hard goals reduces the likelihood that Cruise Control will calculate and generate valid optimization proposals.
Default optimization goals
Cruise Control uses the default optimization goals list to generate the cached optimization proposal. For more information, see Section 14.6, “Optimization proposals overview”.
You can override the default optimization goals at runtime by setting user-provided optimization goals.
The following default optimization goals are preset in the cruisecontrol.properties
file, in the default.goals
property, in descending priority order:
RackAwareGoal; MinTopicLeadersPerBrokerGoal; ReplicaCapacityGoal; DiskCapacityGoal; NetworkInboundCapacityGoal; NetworkOutboundCapacityGoal; CpuCapacityGoal; ReplicaDistributionGoal; PotentialNwOutGoal; DiskUsageDistributionGoal; NetworkInboundUsageDistributionGoal; NetworkOutboundUsageDistributionGoal; CpuUsageDistributionGoal; TopicReplicaDistributionGoal; LeaderReplicaDistributionGoal; LeaderBytesInDistributionGoal
You must specify at least one default goal, or Cruise Control will crash.
To modify the default optimization goals, specify a list of goals, in descending priority order, in the default.goals
property. Default goals must be a subset of the master optimization goals; use fully-qualified domain names.
User-provided optimization goals
User-provided optimization goals narrow down the configured default goals for a particular optimization proposal. You can set them, as required, as parameters in HTTP requests to the /rebalance
endpoint. For more information, see Section 14.9, “Generating optimization proposals”.
User-provided optimization goals can generate optimization proposals for different scenarios. For example, you might want to optimize leader replica distribution across the Kafka cluster without considering disk capacity or disk utilization. So, you send a request to the /rebalance
endpoint containing a single goal for leader replica distribution.
User-provided optimization goals must:
- Include all configured hard goals, or an error occurs
- Be a subset of the master optimization goals
To ignore the configured hard goals in an optimization proposal, add the skip_hard_goals_check=true
parameter to the request.
Additional resources
- Section 14.8, “Cruise Control configuration”
- Configurations in the Cruise Control Wiki.
14.6. Optimization proposals overview
An optimization proposal is a summary of proposed changes that, if applied, will produce a more balanced Kafka cluster, with partition workloads distributed more evenly among the brokers. Each optimization proposal is based on the set of optimization goals that was used to generate it, subject to any configured capacity limits on broker resources.
When you make a POST request to the /rebalance
endpoint, an optimization proposal is returned in response. Use the information in the proposal to decide whether to initiate a cluster rebalance based on the proposal. Alternatively, you can change the optimization goals and then generate another proposal.
By default, optimization proposals are generated as dry runs that must be initiated separately. There is no limit to the number of optimization proposals that can be generated.
Cached optimization proposal
Cruise Control maintains a cached optimization proposal based on the configured default optimization goals. Generated from the workload model, the cached optimization proposal is updated every 15 minutes to reflect the current state of the Kafka cluster.
The most recent cached optimization proposal is returned when the following goal configurations are used:
- The default optimization goals
- User-provided optimization goals that can be met by the current cached proposal
To change the cached optimization proposal refresh interval, edit the proposal.expiration.ms
setting in the cruisecontrol.properties
file. Consider a shorter interval for fast changing clusters, although this increases the load on the Cruise Control server.
Contents of optimization proposals
The following table describes the properties contained in an optimization proposal.
Property | Description |
---|---|
|
Performance impact during rebalance operation: Relatively high.
Performance impact during rebalance operation: Variable. The larger the number of MBs, the longer the cluster rebalance will take to complete. |
|
Performance impact during rebalance operation: Relatively high, but less than
Performance impact during rebalance operation: Variable. The larger the number, the longer the cluster rebalance will take to complete. Moving a large amount of data between disks on the same broker has less impact than between separate brokers (see |
| The number of topics excluded from the calculation of partition replica/leader movements in the optimization proposal. You can exclude topics in one of the following ways:
In the
In a POST request to the Topics that match the regular expression are listed in the response and will be excluded from the cluster rebalance. |
|
Performance impact during rebalance operation: Relatively low. |
|
|
|
|
| Measurements of the overall balance of a Kafka Cluster.
Cruise Control assigns a
The |
14.7. Rebalance performance tuning overview
You can adjust several performance tuning options for cluster rebalances. These options control how partition replica and leadership movements in a rebalance are executed, as well as the bandwidth that is allocated to a rebalance operation.
Partition reassignment commands
Optimization proposals are composed of separate partition reassignment commands. When you initiate a proposal, the Cruise Control server applies these commands to the Kafka cluster.
A partition reassignment command consists of either of the following types of operations:
Partition movement: Involves transferring the partition replica and its data to a new location. Partition movements can take one of two forms:
- Inter-broker movement: The partition replica is moved to a log directory on a different broker.
- Intra-broker movement: The partition replica is moved to a different log directory on the same broker.
- Leadership movement: Involves switching the leader of the partition’s replicas.
Cruise Control issues partition reassignment commands to the Kafka cluster in batches. The performance of the cluster during the rebalance is affected by the number of each type of movement contained in each batch.
To configure partition reassignment commands, see Rebalance tuning options.
Replica movement strategies
Cluster rebalance performance is also influenced by the replica movement strategy that is applied to the batches of partition reassignment commands. By default, Cruise Control uses the BaseReplicaMovementStrategy
, which applies the commands in the order in which they were generated. However, if there are some very large partition reassignments early in the proposal, this strategy can slow down the application of the other reassignments.
Cruise Control provides three alternative replica movement strategies that can be applied to optimization proposals:
-
PrioritizeSmallReplicaMovementStrategy
: Order reassignments in ascending size. -
PrioritizeLargeReplicaMovementStrategy
: Order reassignments in descending size. -
PostponeUrpReplicaMovementStrategy
: Prioritize reassignments for replicas of partitions which have no out-of-sync replicas.
These strategies can be configured as a sequence. The first strategy attempts to compare two partition reassignments using its internal logic. If the reassignments are equivalent, then it passes them to the next strategy in the sequence to decide the order, and so on.
To configure replica movement strategies, see Rebalance tuning options.
Rebalance tuning options
Cruise Control provides several configuration options for tuning rebalance parameters. These options are set in the following ways:
-
As properties, in the default Cruise Control configuration, in the
cruisecontrol.properties
file -
As parameters in POST requests to the
/rebalance
endpoint
The relevant configurations for both methods are summarized in the following table.
Property and request parameter configurations | Description | Default Value |
---|---|---|
| The maximum number of inter-broker partition movements in each partition reassignment batch | 5 |
| ||
| The maximum number of intra-broker partition movements in each partition reassignment batch | 2 |
| ||
| The maximum number of partition leadership changes in each partition reassignment batch | 1000 |
| ||
| The bandwidth (in bytes per second) to assign to partition reassignment | Null (no limit) |
| ||
|
The list of strategies (in priority order) used to determine the order in which partition reassignment commands are executed for generated proposals. There are three strategies:
For the property, use a comma-separated list of the fully qualified names of the strategy classes (add For the parameter, use a comma-separated list of the class names of the replica movement strategies. |
|
|
Changing the default settings affects the length of time that the rebalance takes to complete, as well as the load placed on the Kafka cluster during the rebalance. Using lower values reduces the load but increases the amount of time taken, and vice versa.
Additional resources
- Configurations in the Cruise Control Wiki.
- REST APIs in the Cruise Control Wiki.
14.8. Cruise Control configuration
The config/cruisecontrol.properties
file contains the configuration for Cruise Control. The file consists of properties in one of the following types:
- String
- Number
- Boolean
You can specify and configure all the properties listed in the Configurations section of the Cruise Control Wiki.
Capacity configuration
Cruise Control uses capacity limits to determine if certain resource-based optimization goals are being broken. An attempted optimization fails if one or more of these resource-based goals is set as a hard goal and then broken. This prevents the optimization from being used to generate an optimization proposal.
You specify capacity limits for Kafka broker resources in one of the following three .json
files in cruise-control/config
:
-
capacityJBOD.json
: For use in JBOD Kafka deployments (the default file). -
capacity.json
: For use in non-JBOD Kafka deployments where each broker has the same number of CPU cores. -
capacityCores.json
: For use in non-JBOD Kafka deployments where each broker has varying numbers of CPU cores.
Set the file in the capacity.config.file
property in cruisecontrol.properties
. The selected file will be used for broker capacity resolution. For example:
capacity.config.file=config/capacityJBOD.json
Capacity limits can be set for the following broker resources in the described units:
-
DISK
: Disk storage in MB -
CPU
: CPU utilization as a percentage (0-100) or as a number of cores -
NW_IN
: Inbound network throughput in KB per second -
NW_OUT
: Outbound network throughput in KB per second
To apply the same capacity limits to every broker monitored by Cruise Control, set capacity limits for broker ID -1
. To set different capacity limits for individual brokers, specify each broker ID and its capacity configuration.
Example capacity limits configuration
{ "brokerCapacities":[ { "brokerId": "-1", "capacity": { "DISK": "100000", "CPU": "100", "NW_IN": "10000", "NW_OUT": "10000" }, "doc": "This is the default capacity. Capacity unit used for disk is in MB, cpu is in percentage, network throughput is in KB." }, { "brokerId": "0", "capacity": { "DISK": "500000", "CPU": "100", "NW_IN": "50000", "NW_OUT": "50000" }, "doc": "This overrides the capacity for broker 0." } ] }
For more information, see Populating the Capacity Configuration File in the Cruise Control Wiki.
Log cleanup policy for Cruise Control Metrics topic
It is important that the auto-created __CruiseControlMetrics
topic (see auto-created topics) has a log cleanup policy of DELETE
rather than COMPACT
. Otherwise, records that are needed by Cruise Control might be removed.
As described in Section 14.3, “Deploying the Cruise Control Metrics Reporter”, setting the following options in the Kafka configuration file ensures that the COMPACT
log cleanup policy is correctly set:
-
cruise.control.metrics.topic.auto.create=true
-
cruise.control.metrics.topic.num.partitions=1
-
cruise.control.metrics.topic.replication.factor=1
If topic auto-creation is disabled in the Cruise Control Metrics Reporter (cruise.control.metrics.topic.auto.create=false
), but enabled in the Kafka cluster, then the __CruiseControlMetrics
topic is still automatically created by the broker. In this case, you must change the log cleanup policy of the __CruiseControlMetrics
topic to DELETE
using the kafka-configs.sh
tool.
Get the current configuration of the
__CruiseControlMetrics
topic:bin/kafka-configs.sh --bootstrap-server <BrokerAddress> --entity-type topics --entity-name __CruiseControlMetrics --describe
Change the log cleanup policy in the topic configuration:
bin/kafka-configs.sh --bootstrap-server <BrokerAddress> --entity-type topics --entity-name __CruiseControlMetrics --alter --add-config cleanup.policy=delete
If topic auto-creation is disabled in both the Cruise Control Metrics Reporter and the Kafka cluster, you must create the __CruiseControlMetrics
topic manually and then configure it to use the DELETE
log cleanup policy using the kafka-configs.sh
tool.
For more information, see Section 5.9, “Modifying a topic configuration”.
Logging configuration
Cruise Control uses log4j1
for all server logging. To change the default configuration, edit the log4j.properties
file in /opt/cruise-control/config/log4j.properties
.
You must restart the Cruise Control server before the changes take effect.
14.9. Generating optimization proposals
When you make a POST request to the /rebalance
endpoint, Cruise Control generates an optimization proposal to rebalance the Kafka cluster, based on the provided optimization goals.
The optimization proposal is generated as a dry run, unless the dryrun
parameter is supplied and set to false
. In "dry run mode", Cruise Control generates the optimization proposal and the estimated result, but doesn’t initiate the proposal by rebalancing the cluster.
You can analyze the information returned in the optimization proposal and decide whether to initiate it.
Following are the key parameters for requests to the /rebalance
endpoint. For information about all the available parameters, see REST APIs in the Cruise Control Wiki.
dryrun
type: boolean, default: true
Informs Cruise Control whether you want to generate an optimization proposal only (true
), or generate an optimization proposal and perform a cluster rebalance (false
).
When dryrun=true
(the default), you can also pass the verbose
parameter to return more detailed information about the state of the Kafka cluster. This includes metrics for the load on each Kafka broker before and after the optimization proposal is applied, and the differences between the before and after values.
excluded_topics
type: regex
A regular expression that matches the topics to exclude from the calculation of the optimization proposal.
goals
type: list of strings, default: the configured default.goals
list
List of user-provided optimization goals to use to prepare the optimization proposal. If goals are not supplied, the configured default.goals
list in the cruisecontrol.properties
file is used.
skip_hard_goals_check
type: boolean, default: false
By default, Cruise Control checks that the user-provided optimization goals (in the goals
parameter) contain all the configured hard goals (in hard.goals
). A request fails if you supply goals that are not a subset of the configured hard.goals
.
Set skip_hard_goals_check
to true
if you want to generate an optimization proposal with user-provided optimization goals that do not include all the configured hard.goals
.
json
type: boolean, default: false
Controls the type of response returned by the Cruise Control server. If not supplied, or set to false
, then Cruise Control returns text formatted for display on the command line. If you want to extract elements of the returned information programmatically, set json=true
. This will return JSON formatted text that can be piped to tools such as jq
, or parsed in scripts and programs.
verbose
type: boolean, default: false
Controls the level of detail in responses that are returned by the Cruise Control server. Can be used with dryrun=true
.
Prerequisites
- Kafka and ZooKeeper are running
- Cruise Control is running
Procedure
To generate a "dry run" optimization proposal formatted for the console, send a POST request to the
/rebalance
endpoint.To use the configured
default.goals
:curl -v -X POST 'cruise-control-server:9090/kafkacruisecontrol/rebalance'
The cached optimization proposal is immediately returned.
NoteIf
NotEnoughValidWindows
is returned, Cruise Control has not yet recorded enough metrics data to generate an optimization proposal. Wait a few minutes and then resend the request.To specify user-provided optimization goals instead of the configured
default.goals
, supply one or more goals in thegoals
parameter:curl -v -X POST 'cruise-control-server:9090/kafkacruisecontrol/rebalance?goals=RackAwareGoal,ReplicaCapacityGoal'
If it satisfies the supplied goals, the cached optimization proposal is immediately returned. Otherwise, a new optimization proposal is generated using the supplied goals; this takes longer to calculate. You can enforce this behavior by adding the
ignore_proposal_cache=true
parameter to the request.To specify user-provided optimization goals that do not include all the configured hard goals, add the
skip_hard_goal_check=true
parameter to the request:curl -v -X POST 'cruise-control-server:9090/kafkacruisecontrol/rebalance?goals=RackAwareGoal,ReplicaCapacityGoal,ReplicaDistributionGoal&skip_hard_goal_check=true'
Review the optimization proposal contained in the response. The properties describe the pending cluster rebalance operation.
The proposal contains a high level summary of the proposed optimization, followed by summaries for each default optimization goal, and the expected cluster state after the proposal has executed.
Pay particular attention to the following information:
-
The
Cluster load after rebalance
summary. If it meets your requirements, you should assess the impact of the proposed changes using the high level summary. -
n inter-broker replica (y MB) moves
indicates how much data will be moved across the network between brokers. The higher the value, the greater the potential performance impact on the Kafka cluster during the rebalance. -
n intra-broker replica (y MB) moves
indicates how much data will be moved within the brokers themselves (between disks). The higher the value, the greater the potential performance impact on individual brokers (although less than that ofn inter-broker replica (y MB) moves
). - The number of leadership moves. This has a negligible impact on the performance of the cluster during the rebalance.
-
The
Asynchronous responses
The Cruise Control REST API endpoints timeout after 10 seconds by default, although proposal generation continues on the server. A timeout might occur if the most recent cached optimization proposal is not ready, or if user-provided optimization goals were specified with ignore_proposal_cache=true
.
To allow you to retrieve the optimization proposal at a later time, take note of the request’s unique identifier, which is given in the header of responses from the /rebalance
endpoint.
To obtain the response using curl
, specify the verbose (-v
) option:
curl -v -X POST 'cruise-control-server:9090/kafkacruisecontrol/rebalance'
Here is an example header:
* 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 2020 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)
If an optimization proposal is not ready within the timeout, you can re-submit the POST request, this time including the User-Task-ID
of the original request in the header:
curl -v -X POST -H 'User-Task-ID: 274b8095-d739-4840-85b9-f4cfaaf5c201' 'cruise-control-server:9090/kafkacruisecontrol/rebalance'
What to do next
14.10. Initiating a cluster rebalance
If you are satisfied with an optimization proposal, you can instruct Cruise Control to initiate the cluster rebalance and begin reassigning partitions, as summarized in the proposal.
Leave as little time as possible between generating an optimization proposal and initiating the cluster rebalance. If some time has passed since you generated the original optimization proposal, the cluster state might have changed. Therefore, the cluster rebalance that is initiated might be different to the one you reviewed. If in doubt, first generate a new optimization proposal.
Only one cluster rebalance, with a status of "Active", can be in progress at a time.
Prerequisites
- You have generated an optimization proposal from Cruise Control.
Procedure
To execute the most recently generated optimization proposal, send a POST request to the
/rebalance
endpoint, with thedryrun=false
parameter:curl -X POST 'cruise-control-server:9090/kafkacruisecontrol/rebalance?dryrun=false'
Cruise Control initiates the cluster rebalance and returns the optimization proposal.
- Check the changes that are summarized in the optimization proposal. If the changes are not what you expect, you can stop the rebalance.
Check the progress of the cluster rebalance using the
/user_tasks
endpoint. The cluster rebalance in progress has a status of "Active".To view all cluster rebalance tasks executed on the Cruise Control server:
curl 'cruise-control-server:9090/kafkacruisecontrol/user_tasks' USER TASK ID CLIENT ADDRESS START TIME STATUS REQUEST URL c459316f-9eb5-482f-9d2d-97b5a4cd294d 0:0:0:0:0:0:0:1 2020-06-01_16:10:29 UTC Active POST /kafkacruisecontrol/rebalance?dryrun=false 445e2fc3-6531-4243-b0a6-36ef7c5059b4 0:0:0:0:0:0:0:1 2020-06-01_14:21:26 UTC Completed GET /kafkacruisecontrol/state?json=true 05c37737-16d1-4e33-8e2b-800dee9f1b01 0:0:0:0:0:0:0:1 2020-06-01_14:36:11 UTC Completed GET /kafkacruisecontrol/state?json=true aebae987-985d-4871-8cfb-6134ecd504ab 0:0:0:0:0:0:0:1 2020-06-01_16:10:04 UTC
To view the status of a particular cluster rebalance task, supply the
user-task-ids
parameter and the task ID:curl 'cruise-control-server:9090/kafkacruisecontrol/user_tasks?user_task_ids=c459316f-9eb5-482f-9d2d-97b5a4cd294d'
14.11. Stopping an active cluster rebalance
You can stop the cluster rebalance that is currently in progress.
This instructs Cruise Control to finish the current batch of partition reassignments and then stop the rebalance. When the rebalance has stopped, completed partition reassignments have already been applied; therefore, the state of the Kafka cluster is different when compared to before the start of the rebalance operation. If further rebalancing is required, you should generate a new optimization proposal.
The performance of the Kafka cluster in the intermediate (stopped) state might be worse than in the initial state.
Prerequisites
- A cluster rebalance is in progress (indicated by a status of "Active").
Procedure
Send a POST request to the
/stop_proposal_execution
endpoint:curl -X POST 'cruise-control-server:9090/kafkacruisecontrol/stop_proposal_execution'
Additional resources