Skip to content

Upgrading to Web UI 1.0

Version Compatibility Requirement

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

Before upgrading to Karafka Web UI 1.0, 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 1.0 release. Following both guides will help you navigate the upgrade process with minimal disruption to your production systems.

Version Numbering Change

Web UI 1.0 is the direct successor to 0.11.x, continuing directly from 0.11.6. The version was promoted from 0.x to 1.0 to reflect the long-standing production stability of the Web UI, not because of a large batch of breaking changes - see Commanding Pause Configuration below for the one breaking change this release does ship, which affects only Pro users who set a custom commanding pause duration.

Starting with Karafka 3.0, Web UI versioning will align with Karafka's major version - both will release as 3.0 together and move in lockstep from that point forward.

CSRF Protection Change

The CSRF protection mechanism has been replaced. The previous token-based approach (route_csrf plugin) has been removed in favour of header-based protection using the Sec-Fetch-Site header (sec_fetch_site_csrf plugin).

For most users this is transparent - all modern browsers automatically include the Sec-Fetch-Site header and the new approach requires no changes to your application.

Only unsafe HTTP methods (POST, PUT, PATCH, DELETE) are checked; GET and HEAD requests are always allowed regardless of the header.

If you have non-browser clients, custom HTTP clients, or integration tests that issue such requests directly to the Web UI without browser-standard headers, those clients must include the Sec-Fetch-Site: same-origin header. Only the same-origin value is accepted - requests with same-site, cross-site, or with the header missing entirely will be rejected as potential cross-site forgeries.

Commanding Pause Configuration

The commanding pause configuration has been namespaced under config.commanding.pause, mirroring the pause configuration namespacing introduced in Karafka 2.6. The flat config.commanding.pause_timeout setting has been removed in favor of the nested config.commanding.pause.timeout namespace.

This affects only Pro users who explicitly set a custom commanding pause duration. If you did, update your configuration:

# Before (removed)
config.commanding.pause_timeout = 30_000

# After
config.commanding.pause.timeout = 30_000

Dynamic Worker Count in the UI

The Web UI now reads the live worker count from Karafka::Server.workers.size instead of the static Karafka::App.config.concurrency value. This means the UI accurately reflects runtime thread pool changes when dynamic worker pool scaling (introduced in Karafka 2.6) is in use.

No configuration change is required. The display updates automatically.

Poll Interval Monitoring

Consumer reporting now tracks poll_interval (max.poll.interval.ms) per subscription group alongside the existing poll_age metric. This gives you visibility into how close each subscription group is to its polling timeout, helping catch slow consumers before they are kicked out of the group.

The consumer schema has been bumped to 1.7.0 to carry this additional field.

Deployment

Because of the consumer schema version bump to 1.7.0, follow the standard zero-downtime upgrade procedure:

  1. Make sure you have upgraded to 0.11.6 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 redeployed and all consumers are replaced). 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: 2026-08-11 16:34:24