Skip to content

Upgrading to Web UI 0.11

Version Compatibility Requirement

Karafka Web UI 0.11 requires Karafka 2.5 - these components must be upgraded together. Attempting to run Web UI 0.11 with older versions of Karafka will result in compatibility errors. Please ensure you upgrade both components as part of the same deployment process. Karafka 2.5 Upgrade Guide can be found here.

Before upgrading to Karafka Web UI 0.11, please review our General Karafka Upgrade Guide first. This document provides essential advice on upgrading Karafka and its components and general best practices to ensure a smooth transition. The general guide contains fundamental steps that apply to all upgrades, while this specific guide focuses only on the changes introduced in the Web UI 0.11 release. Following both guides will help you navigate the upgrade process with minimal disruption to your production systems.

Topics Configuration Structure Change

The most significant change in this release is the restructuring of the topics configuration. Previously, topic names were configured directly as strings, but now they are nested objects with both name and configuration properties.

Before:

Karafka::Web.setup do |config|
  config.topics.consumers.states = 'karafka_consumers_states'
  config.topics.consumers.metrics = 'karafka_consumers_metrics'
  config.topics.consumers.reports = 'karafka_consumers_reports'
  config.topics.consumers.commands = 'karafka_consumers_commands'
  config.topics.errors = 'karafka_errors'
end

After:

Karafka::Web.setup do |config|
  # Topic configurations now include both name and config properties
  config.topics.consumers.states.name = 'karafka_consumers_states'
  config.topics.consumers.metrics.name = 'karafka_consumers_metrics'
  config.topics.consumers.reports.name = 'karafka_consumers_reports'
  config.topics.consumers.commands.name = 'karafka_consumers_commands'
  config.topics.errors.name = 'karafka_errors'

  # Optional: You can also customize the topic configs if needed
  # Example:
  # config.topics.errors.config = {
  #   'cleanup.policy': 'delete',
  #   'retention.ms': 7 * 24 * 60 * 60 * 1_000 # 7 days
  # }
end

Configuration Requirements

The topic configurations now have validation requirements:

  1. The name attribute must be a string and match the topic naming pattern
  2. The config attribute must:
    • Be a non-empty hash
    • Have all keys as symbols (not strings)

Direct Topic References

If you have any code that directly references the topic configuration, update it to use the .name attribute:

Before:

topic_name = Karafka::Web.config.topics.errors

After:

topic_name = Karafka::Web.config.topics.errors.name

Cross-Platform Compatibility

This release includes significant improvements for compatibility across Debian, Alpine, and Wolfi operating systems:

  • Dependency Reduction: The grep command is no longer required on any operating system
  • Linux Simplification: On Linux systems (Debian, Alpine, Wolfi), the head, w, and sysctl commands are no longer needed
  • macOS Requirements: These commands (head, w, and sysctl) are still required only on macOS (Darwin)

These changes simplify deployments, especially in containerized environments where minimal images are preferred. The code now uses more platform-agnostic methods for gathering statistics, resulting in more consistent behavior across different operating systems without requiring additional dependencies.

Cache System Rename

If you're using custom cache configurations with the Web UI, be aware that Karafka::Web::Ui::Lib::TtlCache has been renamed to Karafka::Web::Ui::Lib::Cache. If you've customized the cache settings in your configuration, you'll need to update the reference:

Before

Karafka::Web.setup do |config|
  config.ui.cache = Karafka::Web::Ui::Lib::TtlCache.new(
    # Your TTL settings
    60_000 * 10 # Example: 10 minutes
  )
end

After:

Karafka::Web.setup do |config|
  config.ui.cache = Karafka::Web::Ui::Lib::Cache.new(
    # Your TTL settings
    60_000 * 10 # Example: 10 minutes
  )
end

Deployment

Because of the reporting schema update, it is recommended to:

  1. Make sure you have upgraded to 0.10.4 before and that it was fully deployed.
  2. Test the upgrade on a staging or dev environment.
  3. The Web UI interface may throw 500 errors during the upgrade because of schema incompatibility (until Puma is deployed and all consumers redeployed). This will have no long-term effects and can be ignored.
  4. Karafka::Web::Errors::Processing::IncompatibleSchemaError is expected. It is part of the Karafka Web UI zero-downtime deployment strategy. This error allows the Web UI materialization consumer to back off and wait for it to be replaced with a new one.
  5. Perform a rolling deployment (or a regular one) and replace all consumer processes.
  6. Update the Web UI Puma.
  7. No CLI command execution is required.
  8. Enjoy.

Last modified: 2025-10-18 20:42:18