diff --git a/docs/source/kafka.rst b/docs/source/kafka.rst index 792410d4427..6e5dca95254 100644 --- a/docs/source/kafka.rst +++ b/docs/source/kafka.rst @@ -69,17 +69,14 @@ Additional considerations #. **Preferred message size.** In Step 4 above (see `Steps`_ section) you can also set the preferred size of blocks by setting the ``Orderer.Batchsize.PreferredMaxBytes`` key. Kafka offers higher throughput when dealing with relatively small messages; aim for a value no bigger than 1 MiB. #. **Using environment variables to override settings.** When using the sample Kafka and Zookeeper Docker images provided with Fabric (see ``images/kafka`` and ``images/zookeeper`` respectively), you can override a Kafka broker or a ZooKeeper server's settings by using environment variables. Replace the dots of the configuration key with underscores — e.g. ``KAFKA_UNCLEAN_LEADER_ELECTION_ENABLE=false`` will allow you to override the default value of ``unclean.leader.election.enable``. The same applies to the OSNs for their *local* configuration, i.e. what can be set in ``orderer.yaml``. For example ``ORDERER_KAFKA_RETRY_SHORTINTERVAL=1s`` allows you to override the default value for ``Orderer.Kafka.Retry.ShortInterval``. -Supported Kafka versions and upgrading --------------------------------------- +Kafka Protocol Version Compatibility +------------------------------------ -Fabric uses the `sarama client library `_ and vendors a version of it that supports the following Kafka client versions: +Fabric uses the `sarama client library `_ and vendors a version of it that supports Kafka 0.10 to 1.0, yet is still known to work with older versions. -* ``Version: 0.9.0`` -* ``Version: 0.10.0`` -* ``Version: 0.10.1`` -* ``Version: 0.10.2`` +Using the ``Kafka.Version`` key in ``orderer.yaml``, you can configure which version of the Kafka protocol is used to communicate with the Kafka cluster's brokers. Kafka brokers are backward compatible with older protocol versions. Because of a Kafka broker's backward compatibility with older protocol versions, upgrading your Kafka brokers to a new version does not require an update of the ``Kafka.Version`` key value, but the Kafka cluster might suffer a `performance penalty `_ while using an older protocol version. -The sample Kafka server image provided by Fabric contains Kafka server version ``0.10.2``. Out of the box, Fabric's ordering service nodes default to configuring their embedded Kafka client to match this version. If you are not using the sample Kafka server image provided by Fabric, ensure that you configure a Kafka client version that is compatible with your Kafka server using the ``Kafka.Version`` key in ``orderer.yaml``. +The sample Kafka server image provided by Fabric contains Kafka server version ``0.10.2.1``. Out of the box, Fabric's ordering service nodes are configured to use the Kafka protocol messages that correspond to this version. On a production deployment, or if you are simply not using the sample Kafka server images provided by Fabric, consider configuring ``Kafka.Version`` to match your Kafka broker version in order to take advantage of any enhancements (if any) enabled by the corresponding Kafka protocol version. Debugging --------- diff --git a/sampleconfig/orderer.yaml b/sampleconfig/orderer.yaml index 9687ec41e0d..c9bff1b60e2 100644 --- a/sampleconfig/orderer.yaml +++ b/sampleconfig/orderer.yaml @@ -244,7 +244,8 @@ Kafka: # value of RootCAs. #File: path/to/RootCAs - # Kafka version of the Kafka cluster brokers (defaults to 0.10.2.0) + # Kafka protocol version used to communicate with the Kafka cluster brokers + # (defaults to 0.10.2.0 if not specified) Version: 0.10.2.0 ################################################################################