Versioning and support policy

Apicurio Registry follows a defined versioning scheme and support policy, offers multiple release channels, and supports upgrading between versions with guidance for handling rollbacks.

Version numbering scheme

Apicurio Registry follows Semantic Versioning with a clear distinction between minor and patch releases.

Release type Contents Example

Minor (for example, 3.3.0 to 3.4.0)

New features, enhancements, and bug fixes

Scheduled development milestones

Patch (for example, 3.3.0 to 3.3.1)

CVE and security fixes only

Dependency upgrades, security patches

Patch releases do not contain new features or bug fixes. They are limited to changes that address known security vulnerabilities.

Support window

Apicurio Registry maintains the two most recent minor versions with security patches.

When a new minor version is released, the oldest supported minor version reaches end-of-life and no longer receives updates.

The following example illustrates how the support window moves forward as new minor versions are released. Version numbers after the current release are illustrative, not announcements.

Table 1. Example support timeline
Event Supported versions End-of-life

3.3.0 released

3.3.x, 3.2.x

3.1.x and older

Next minor release (a future 3.4.0)

3.4.x, 3.3.x

3.2.x and older

Release channels

Apicurio Registry provides multiple release channels so that you can choose the update cadence that suits your deployment.

Choose the channel type that matches how you deploy Apicurio Registry: container images or the Apicurio Registry Operator.

Docker image tags

Apicurio Registry container images use several tag conventions that determine how frequently your deployment receives updates.

Tag Description

3.3.0

Pinned to an exact release. Never changes.

3.3

Floating tag that always points to the latest patch in the 3.3.x series (for example, 3.3.0, then 3.3.1, then 3.3.2).

latest / latest-release

Always points to the most recent stable release across all minor versions.

latest-snapshot

Most recent build from the main branch. Unstable and not recommended for production.

Use the minor-series floating tag (for example, 3.3) to automatically receive security patches without upgrading to a new minor version.

OLM channels (Kubernetes operator)

If you deploy Apicurio Registry by using the Apicurio Registry Operator, each minor version has its own OLM channel.

Channel Description

3.3.x

Receives only patch updates within the 3.3 minor version.

3.x

Rolling channel that always tracks the latest minor version.

Subscribe to a minor-version channel (for example, 3.3.x) for stability, or to the 3.x rolling channel to always receive the latest features.

Upgrade overview

Apicurio Registry supports forward upgrades. Database schema migrations run automatically on startup and do not require manual intervention.

Always back up your database before upgrading to a new minor version.
Additional resources

Performing patch upgrades

You can apply a patch upgrade (for example, 3.3.0 to 3.3.1) at any time. Patch releases contain only CVE fixes and do not introduce behavioral changes.

Procedure

  1. Back up your database.

  2. Replace the Apicurio Registry container image with the new patch version or use the minor-series floating tag.

  3. Start Apicurio Registry. Any required schema migrations run automatically.

Performing minor upgrades

You can upgrade to a new minor version (for example, from 3.3.x to the next minor release) to receive new features, enhancements, and bug fixes.

Procedure

  1. Review the release notes for the target version to understand new features and any behavioral changes.

  2. Back up your database.

  3. Replace the Apicurio Registry container image with the new minor version.

  4. Start Apicurio Registry. Database schema migrations run automatically.

  5. Verify that your client applications work correctly with the new version.

Upgrades across multiple minor versions

You can upgrade across multiple minor versions in one step (for example, from 3.2.x directly to a later minor version). Database migrations are cumulative, and Apicurio Registry applies them in order on startup.

Review the release notes for all intermediate versions to understand the full set of changes.

Downgrades and rollbacks

Apicurio Registry does not support downgrades.

Database schema migrations are forward-only and irreversible. Starting an older version of Apicurio Registry against a database that has been migrated to a newer schema version fails.

If you deploy Apicurio Registry by using the Apicurio Registry Operator, switching to an older OLM channel is also not supported.

Handling a failed upgrade

If an upgrade introduces issues, restore your Apicurio Registry deployment from the database backup taken before the upgrade.

Procedure

  1. Stop Apicurio Registry.

  2. Restore the database from the backup taken before the upgrade.

  3. Deploy the previous version of Apicurio Registry.

  4. Investigate the issue before attempting the upgrade again.

    Do not attempt to manually revert database schema changes.

Backing up before an upgrade

Before any minor version upgrade, create a backup of your Apicurio Registry database.

Procedure

  1. For PostgreSQL deployments, create a database dump:

    pg_dump -h <host> -U <username> -d <database> -F c -f registry-backup-$(date +%Y%m%d).dump

    For KafkaSQL deployments, back up both the Kafka topic data and the SQL snapshot database.

  2. Store the backup in a secure location.

  3. Verify that the backup can be restored before proceeding with the upgrade.

Additional resources