Kafka topics are a fundamental concept in Apache Kafka. Topics are logical names or labels representing a stream of messages that Kafka clients can produce and consume.
What makes them interesting is the variety of settings that can be applied to them. These settings, amongst others include:
- Partition count: The number of partitions that a topic should be split into.
- Replication factor: The number of replicas that should be maintained for each partition.
- Retention period: The time that messages should be retained in the topic.
- Minimum and maximum in-sync replicas: The minimum number of replicas that must be in sync before a producer can receive acknowledgment for a write operation.
- Cleanup policy: The policy used for deleting old messages from the topic.
When looking from a management perspective, topics are similar to database tables. They have names, a set of settings that apply to them, and their constraints. And on top of all of that, they need to be managed.
Declarative topics management
The management approach that I like and support in Karafka is called Declarative Topics Management. It allows for automatic topic creation and configuration based on predefined rules. It is a way to automate the process of managing Kafka topics by defining the desired topic properties and configurations in a declarative manner rather than manually creating and managing topics.
With Declarative Topics Management, you can define a set of rules that specify how topics should be created and configured. These rules can be based on various factors, such as the topic's name, number of partitions, replication factor, retention policy, and more.
Example of a declarative repartitioning using karafka topics migrate command
Keeping Kafka topics configuration as code has several benefits:
-
Version Control: By keeping the topic settings as code, you can track changes over time and easily understand historical changes related to the topics. This is particularly important in a production environment where changes need to be carefully managed.
-
Reproducibility: When you define Kafka topics settings as code, you can easily recreate the same topic with the same settings in multiple environments. This ensures that your development, staging, and production environments are consistent, which can help prevent unexpected issues and bugs.
-
Automation: If you use code to define Kafka topics settings, you can automate the process of creating and updating topics. This can save time and reduce the risk of human error.
-
Collaboration: When you keep Kafka topics settings as code, you can collaborate with other developers on the configuration. You can use tools like Git to manage changes and merge different configurations.
-
Documentation: Code is self-documenting, meaning anyone can look at the configuration and understand what is happening. This can make it easier for new team members to get up to speed and help troubleshoot issues.
In-app topics management
There are many ways to manage declaratively Kafka topics. For complex systems, you may want to look into tools like topicctl.
Often, however, your setup won't be overcomplicated. The primary thing that needs to happen is to ensure that all of your environments and developers use topics with the same configuration.
Partition count is a simple example where a config difference can impact the business logic and create hard-to-track issues. By default, topics created automatically by Kafka always have one partition. Assume a developer is working on something that requires strong ordering. If his development and test environments operate on only one partition, problems emerging from invalid partition key selection may only occur once the code hits production. Those types of race conditions can be both critical and hard to detect.
To mitigate risks of that nature, Karafka ships with a Declarative Topics feature. This feature lets you describe your topics' configuration in your routing, ensuring that the set of settings is the same across all the managed environments.
Defining topic configuration
All the configuration for a given topic needs to be defined using the topic scope #config method:
class KarafkaApp < Karafka::App
routes.draw do
topic :events do
config(
partitions: 6,
replication_factor: Rails.env.production? ? 3 : 1,
'retention.ms': 86_400_000 # 1 day in ms,
'cleanup.policy': 'delete'
)
consumer EventsConsumer
end
end
endSuch a configuration can be then applied by running the following command: bundle exec karafka topics migrate. This command will create the topic if missing or repartition in case there are not enough partitions.
Karafka ships with following topics management related commands:
karafka topics create- creates topics with appropriate settings.karafka topics delete- deletes all the topics defined in the routes.karafka topics repartition- adds additional partitions to topics with fewer partitions than expected.karafka topics reset- deletes and re-creates all the topics.karafka topics migrate- creates missing topics and repartitions existing to match expected partitions count.
The below example illustrates the usage of the migrate command to align the number of partitions and to add one additional topic:
Limitations
This API has few limitations about which you can read here. There are two primary things you need to keep in mind:
- Topics management API does not provide any means of concurrency locking when CLI commands are being executed. This means it is up to you to ensure that two topic CLI commands are not running in parallel during the deployments.
- Karafka currently does not update settings different than the partition count on existing topics. This feature is under development.
Summary
Karafka declarative topics management API is an excellent solution for low and medium-complexity systems to ensure consistency of their topics across multiple environments, and that is available out-of-the-box with the framework itself.
Getting started with Kafka and Karafka
If you want to get started with Karafka as fast as possible, then the best idea is to visit our Getting started guides and the example Rails app repository.
