Upgrade Apicurio Registry from v2 to v3

This reference describes who must upgrade Apicurio Registry from v2 to v3 on Axual Streaming 2.0.0, the deadline per release track, the impact on clients, and the order of the upgrade guides.

Type

Reference

Goal

Know the deadline and impact of the Apicurio v3 upgrade, and run its guides in the right order.

Audience

Platform Operator responsible for an Axual Streaming installation.

When to use

Use these guides when an Axual Streaming 2.0.0 (Axual Platform 2026.2) installation still runs Apicurio Registry v2.

Contents

The sections below cover each area of the upgrade:

Who must upgrade and by when

Axual Streaming 2.0.0 ships Apicurio Registry v2 and v3 side by side, so you can move your schemas, switch traffic to v3 and then retire v2. Upgrade Axual Streaming to 2.0.0 first; see Upgrade Axual Streaming to 2.0.0.

Apicurio v2 is fully supported in 2026.2, but 2026.3 removes it. The upgrade deadline depends on your release track:

  • Non-LTS users: complete the upgrade before you move to 2026.3.

  • LTS users: you can keep running v2 until you upgrade to 2027.2 (the next LTS), where v2 is no longer available.

Apicurio v3 is a major version with breaking changes. The data Apicurio stores in Kafka is not compatible between v2 and v3, so the upgrade is an export from v2 and import into v3, not an in-place version bump.

Impact on clients and downtime

Plan for the following downtime:

  • Reads: near-zero.

  • Writes: schema registration is blocked during the export and import, typically for 30 to 45 minutes, until you switch ingress to v3.

The upgrade changes only the Apicurio Registry server. The v2 client libraries (for example the Java client and SerDes, 2.x) remain supported against the v3 registry, so your applications don’t need to change. Applications that use the Confluent-compatible API are the one exception. For the endpoint change and the API timeline per release, see Apicurio v2 and v3 Differences.

Upgrade guides in order

Run the guides below in order. Each one ends in a stable state, so you can see where you are:

  1. How to Create the Apicurio Migration Client. Ends with a Keycloak client that keeps export access during the freeze.

  2. How to Deploy Apicurio v3 Alongside v2. Ends with an empty v3 on a temporary hostname; clients still use v2.

  3. How to Migrate Schemas to Apicurio v3. Run it in one sitting. Ends with v3 serving production and v2 on a legacy hostname.

  4. How to Remove Apicurio v2. Run it after your rollback window. Ends with v2 removed and the migration client deleted.

If v3 misbehaves after the switch, and before you remove v2, follow How to Roll Back the Apicurio v3 Upgrade. For known failures at any stage, see How to Troubleshoot the Apicurio v3 Upgrade.