Child pages
  • KIP-36 Rack aware replica assignment
Skip to end of metadata
Go to start of metadata



Current state: Accepted

Discussion thread: here

JIRA: KAFKA-1215 - Rack-Aware replica assignment option Resolved

Github Pull Request:

Please keep the discussion on the mailing list rather than commenting on the wiki (wiki discussions get unwieldy fast).


Machines in data center are sometimes grouped in racks. Racks provide isolation as each rack may be in a different physical location and has its own power source. When resources are properly replicated across racks, it provides fault tolerance in that if a rack goes down,  the remaining racks can continue to serve traffic.

In Kafka, if there are more than one replica for a partition, it would be nice to have replicas placed in as many different racks as possible so that the partition can continue to function if a rack goes down. In addition, it makes maintenance of  Kafka cluster easier as you can take down the whole rack at a time.

In AWS, racks are usually mapped to the concept of availability zones

Public Interfaces

Changes to Broker property

An optional broker property will be added 

rack will be an optional field of version 3 JSON schema for a broker. The API ZkUtils.registerBrokerInZk will be updated to increment the JSON version.

For example:


If no rack information is specified, the field will not be included in JSON.

Rack can be specified in the broker property file as

For example, 



Consequently, Broker.writeTo will append rack at the end of ByteBuffer and Broker.readFrom will read it:

Same kind of string serialization (as how host is serialized) will be applied to rack, which means it will first write the size of the string as a short, followed by the actual string content. If rack is not available, it will write size -1 only without any actual string content. When reading from ByteBuffer, -1 will be interpreted as "null".

Changes to UpdateMetadataRequest

The version will be incremented to 2 from 1 and rack will be included. For version 0, only broker ID, host and port will be serialized. For version 1 and 2, the complete Broker object will be serialized. This is done by calling Broker.writeTo and Broker.readFrom. Therefore, for version 2 the rack information will be automatically handled and the the serialization format is the same as the above.

The complete new format of UpdateMetadataRequest is the following:

Changes to TopicMetadataRequest and TopicMetadataResponse

TopicMetadataRequest will increment its version from 0 to 1. If Kafka receives TopicMetadataRequest with version 1, it will create TopicMetadataResponse with rack as part of BrokerEndPoint. Here is the new format for TopicMetadataResponse:


Proposed Changes

  • AdminUtils.assignReplicasToBrokers will be updated to create broker-rack mapping from ZooKeeper data before doing replica assignment. 
  • When making the rack aware assignment, it has the following properties:
    • When the number of partition is N (where N is a positive integer) times number of brokers
      • if each rack has the same broker count, each broker will have the same leader count and replica count.
      • if each rack has different broker count, each broker will have the same leader count, but may have different replica count
    • Assign to as many racks as possible. That means if the number of racks are more than or equal to the number of replicas, each rack will have at most one replica. On the other hand, if the number of racks is less than the the number of replicas (which should happen very infrequently), each rack should have at least one replica and no other guarantees are made on how the replicas will be distributed among racks. For example, if there are 2 racks and 4 replicas, one rack can have 3 replicas, 2 replicas or 1 replica. This is to keep the algorithm simple while still keeping other replica distribution properties and fault tolerance from the racks.
  • Implementation detail of the rack aware assignment (copied from pull request with slight modification):

  • If one or more brokers does NOT have rack information
    • For auto topic creation, AdminUtils.assignReplicasToBrokers will create the same assignment as the current implementation (as if no broker has the rack information) and continue with topic creation. This allows auto topic creation to work when doing rolling upgrade.
    • For command line tools (TopicCommand and ReassignPartitionsCommand), an exception will be thrown. This will alert the user that a broker may be misconfigured. An additional command line argument --ignore-racks can be supplied to suppress such error and continue with topic creation ignoring all rack information.

Compatibility, Deprecation, and Migration Plan

  • Rack will be included in inter-broker protocol. Therefore, rolling upgrade requires these steps:
    1. Update file on all brokers and add the following property:
    2. Upgrade the brokers. This can be done a broker at a time by simply bringing it down, updating the code, and restarting it.
    3. Once the entire cluster is upgraded, bump the protocol version by editing and setting it to new version, for example, 0.10.0.
    4. Restart the brokers one by one for the new protocol version to take effect
  • Rack property will be included in version 3 broker JSON schema and version 2 of UpdateMetadataRequest. Controller will include version specific broker information in its wire format so that broker with old version can still interoperate with broker with new version and rack.
  • Due to a bug introduced in in ZkUtils.getBrokerInfo(), old clients will throw an exception when it sees the broker JSON version is not 1 or 2. Therefore, a minor release is required to fix the problem first so that old clients can parse future version of broker JSON in ZooKeeper. That means clients must be upgraded to before 0.10.0 upgrade can start. In addition, since ZkUtils.getBrokerInfo() is also used by broker, version specific code has to be used when registering broker with ZooKeeper. This is outlined as follows:

    • When is set to 0.9.0.X, the broker will write
      the broker info in ZK using version 2, ignoring the rack info.

    • When is set to 0.10.0, the broker will write
      the broker info in ZK using version 3, including the rack info.

    • If one follows the upgrade process, after the 2nd round of rolling bounces,
      every broker is capable of parsing version 3 of broker info in ZK. This is
      when the rack-aware feature will be used.

  • No labels