nixos/modules/services/misc/kafka.md

   1 # Apache Kafka {#module-services-apache-kafka}
   2
   3 [Apache Kafka](https://kafka.apache.org/) is an open-source distributed event
   4 streaming platform
   5
   6 ## Basic Usage {#module-services-apache-kafka-basic-usage}
   7
   8 The Apache Kafka service is configured almost exclusively through its
   9 [settings](#opt-services.apache-kafka.settings) option, with each attribute
  10 corresponding to the [upstream configuration
  11 manual](https://kafka.apache.org/documentation/#configuration) broker settings.
  12
  13 ## KRaft {#module-services-apache-kafka-kraft}
  14
  15 Unlike in Zookeeper mode, Kafka in
  16 [KRaft](https://kafka.apache.org/documentation/#kraft) mode requires each log
  17 dir to be "formatted" (which means a cluster-specific a metadata file must
  18 exist in each log dir)
  19
  20 The upstream intention is for users to execute the [storage
  21 tool](https://kafka.apache.org/documentation/#kraft_storage) to achieve this,
  22 but this module contains a few extra options to automate this:
  23
  24 - [](#opt-services.apache-kafka.clusterId)
  25 - [](#opt-services.apache-kafka.formatLogDirs)
  26 - [](#opt-services.apache-kafka.formatLogDirsIgnoreFormatted)
  27
  28 ## Migrating to settings {#module-services-apache-kafka-migrating-to-settings}
  29
  30 Migrating a cluster to the new `settings`-based changes requires adapting removed options to the corresponding upstream settings.
  31
  32 This means that the upstream [Broker Configs documentation](https://kafka.apache.org/documentation/#brokerconfigs) should be followed closely.
  33
  34 Note that dotted options in the upstream docs do _not_ correspond to nested Nix attrsets, but instead as quoted top level `settings` attributes, as in `services.apache-kafka.settings."broker.id"`, *NOT* `services.apache-kafka.settings.broker.id`.
  35
  36 Care should be taken, especially when migrating clusters from the old module, to ensure that the same intended configuration is reproduced faithfully via `settings`.
  37
  38 To assist in the comparison, the final config can be inspected by building the config file itself, ie. with: `nix-build <nixpkgs/nixos> -A config.services.apache-kafka.configFiles.serverProperties`.
  39
  40 Notable changes to be aware of include:
  41
  42 - Removal of `services.apache-kafka.extraProperties` and `services.apache-kafka.serverProperties`
  43   - Translate using arbitrary properties using [](#opt-services.apache-kafka.settings)
  44   - [Upstream docs](https://kafka.apache.org/documentation.html#brokerconfigs)
  45   - The intention is for all broker properties to be fully representable via [](#opt-services.apache-kafka.settings).
  46   - If this is not the case, please do consider raising an issue.
  47   - Until it can be remedied, you *can* bail out by using [](#opt-services.apache-kafka.configFiles.serverProperties) to the path of a fully rendered properties file.
  48
  49 - Removal of `services.apache-kafka.hostname` and `services.apache-kafka.port`
  50   - Translate using: `services.apache-kafka.settings.listeners`
  51   - [Upstream docs](https://kafka.apache.org/documentation.html#brokerconfigs_listeners)
  52
  53 - Removal of `services.apache-kafka.logDirs`
  54   - Translate using: `services.apache-kafka.settings."log.dirs"`
  55   - [Upstream docs](https://kafka.apache.org/documentation.html#brokerconfigs_log.dirs)
  56
  57 - Removal of `services.apache-kafka.brokerId`
  58   - Translate using: `services.apache-kafka.settings."broker.id"`
  59   - [Upstream docs](https://kafka.apache.org/documentation.html#brokerconfigs_broker.id)
  60
  61 - Removal of `services.apache-kafka.zookeeper`
  62   - Translate using: `services.apache-kafka.settings."zookeeper.connect"`
  63   - [Upstream docs](https://kafka.apache.org/documentation.html#brokerconfigs_zookeeper.connect)