Release Notes for Apicurio Registry 2.0


Red Hat build of Apicurio Registry 2.0

What's new in Red Hat build of Apicurio Registry

Red Hat build of Apicurio Registry Documentation Team

Abstract

Describes the Red Hat build of Apicurio Registry product and provides the latest details on what's new in this release.

Chapter 1. Apicurio Registry release notes

Red Hat build of Apicurio Registry 2.0 is available as a General Availability release. Apicurio Registry is a datastore for standard event schemas and API designs, and is based on the Apicurio Registry open source community project.

You can use Apicurio Registry to manage and share the structure of your data using a web console, REST API, Maven plug-in, or Java client. For example, client applications can dynamically push or pull the latest schema updates to or from Apicurio Registry without needing to redeploy. You can also use Apicurio Registry to create optional rules to govern how registry content evolves over time. For example, this includes rules for content validation or for backwards and forwards compatibility of schema or API versions.

1.1. Apicurio Registry installation options

You can install Apicurio Registry on OpenShift with either of the following data storage options:

  • AMQ Streams
  • PostgreSQL database

For more details, see Installing and deploying Red Hat build of Apicurio Registry on OpenShift.

1.2. Apicurio Registry platform component versions

Apicurio Registry 2.0.3 supports the following versions:

  • OpenShift Container Platform 4.9 or 4.6
  • OpenJDK 11
  • AMQ Streams 1.8
  • PostgreSQL 12
  • Debezium 1.4
  • Camel Kafka Connector - Technology Preview

1.3. Apicurio Registry new features

Apicurio Registry security
  • Authentication based on Red Hat Single Sign-On - optionally protect the registry so that its REST API requires users to authenticate (OAuth and HTTP basic are supported)
  • Role-based authorization - when authentication is enabled, users must have at least one role of sr-admin, sr-developer, or sr-readonly
  • Creator-only authorization - option to prevent changes to artifacts unless the authenticated user originally created the artifact
  • Kafka OAuth authentication - for storage in AMQ Streams, you can configure access to a Kafka cluster that requires OAuth authentication
Apicurio Registry core
  • Registry artifact groups - optionally organize schema and API artifacts into custom named logical groupings
  • Refactored Kafka serializer/deserializer (SerDes) classes - significant updates to the Java SerDes layer to address ease of use, consistency, and functionality
  • Event sourcing - option to configure the registry to trigger events whenever a change is made, based on the CloudEvents specification
Apicurio Registry data storage
  • SQL-based storage - new SQL storage implementation with support for PostgreSQL database
  • Kafka-based storage - new hybrid storage using AMQ Streams to store artifact data and an embedded SQL database to represent it in memory
Apicurio Registry v2 REST API
  • Custom versioning - option to provide a custom version number when using the REST API to create or update artifacts
  • Improved artifact searching - updates to the REST API to allow improved searching of artifacts
  • Import/export API - updates to the REST API with operations to export and import registry data in .zip format
  • CNCF Schema Registry API support - implementation of the Cloud Native Computing Foundation Schema Registry REST API

    Note

    The Apicurio Registry v2 REST API is compatible with the Confluent Schema Registry REST API, which does not include the new artifact groups. Backwards compatibility is also maintained with the existing Apicurio Registry v1 REST API.

Apicurio Registry Operator
  • Improved performance and streamlining - Operator uses Deployment on OpenShift (instead of DeploymentConfig), predictable resource naming (no random suffixes), and resources created in parallel.
  • Registry data storage - support for the new SQL and Kafka-based storage options.
  • Registry security - support for authentication and authorization configuration using Red Hat Single Sign-On.
  • ApicurioRegistry CRD v1 - uses standardized conditions field in the status block to better indicate issues or errors in the Operator or the application.
  • Multi-namespace deployment - When the Operator is installed in a namespace, it can watch all namespaces (or a selected subset), so applications can be deployed in any or multiple namespaces.
  • Disconnected installation - Support for installing on OpenShift in a restricted network was added in versions 2.0.1 and 1.1.2. For more details, see Mirroring images for a disconnected installation.
Apicurio Registry user documentation and examples
Apicurio Registry deprecated features
Apicurio Registry removed features
  • Infinispan cache-based storage option has been removed
  • Java Persistence API (JPA) storage option has been replaced by the new PostgreSQL database storage option
  • Kafka-based storage option in AMQ Streams has been replaced by the new hybrid storage option in AMQ Streams with in-memory H2 database
  • Apicurio Registry Java client no longer supports OpenJDK 8 and supports OpenJDK 11 instead

1.5. Migrating Apicurio Registry deployments

For details migrating from Apicurio Registry version 1.1 to 2.x, see Migrating Red Hat build of Apicurio Registry deployments.

For details on migrating registry data between Apicurio Registry version 2.x instances, see Exporting and importing registry content using the Registry REST API.

1.6. Apicurio Registry resolved issues

Apicurio Registry core resolved issues

IPT-651 - Error deserializing Protobuf message when getting schema from Apicurio Registry

The Kafka producer application can set the schema, but the consumer application fails to get the schema from the registry and raises a org.apache.kafka.common.errors.SerializationException with an error such as:

Error deserializing Protobuf message for id 3\nCaused by: java.io.IOException: Invalid schema syntax = \"proto3\";\npackage …​commons;\n\nimport \"head.proto\";\n\noption java_package = \"packaget\";\noption java_multiple_files = true;\n\nmessage AuditMessage {\n commons.Head head = 1;\n int64 id = 5;\n string user = 6;\n bytes extraData = 7;\n string signature = 8;\n}\n with refs [] of type AVRO\n\tat

IPT-625 - Error uploading artifact to Apicurio Registry with KafkaSQL storage

When Apicurio Registry is installed with the KafkaSQL storage option, an io.apicurio.registry.storage.RegistryStorageException is raised when a new artifact is uploaded. Possible error messages include SQL error: Expected one element, but found none.

This error was caused by Kafka log compaction, which removed messages that control database sequences. This issue is now fixed by preventing the messages that control the database sequence from being compacted. For more details, see the Apicurio community blog post on Resolving a bug in KafkaSQL storage for Apicurio Registry.

IPT-159 - Registry v1 API and Confluent compatibility API mismatch

Existing users migrating to Apicurio Registry v2.x were required to upgrade all of their Kafka client applications that use Apicurio Registry v1 serializers/deserializers (SerDes) to use the Apicurio Registry v2 SerDes instead.

Apicurio Registry provides a new environment variable named ENABLE_CCOMPAT_LEGACY_ID_MODE that you can use to revert to the legacy behavior of the v1 compatibility API. When this variable is set to true, Apicurio Registry uses globalId instead of contentId as the unique integer identifier for schemas uploaded using the compatibility API.

Registry-1619 - Apicurio Registry server cannot be properly configured to require authentication without role-based authorization

When role-based authorization is disabled in the Apicurio Registry server, authentication is effectively also disabled. Even when OpenID Connect is enabled in Quarkus, users are not required to provide credentials. If a user provides invalid credentials, a request fails. However, if a user provides no credentials, the request succeeds on behalf of an anonymous user. And because roles are disabled, no additional checking is done.

Registry-1289 - Registry does not work on IPv6

When trying to deploy Apicurio Registry using the Operator on a Kubernetes server with Internet Protocol v6, the registry server fails to start.

Registry-1151 - Error fetching JavaScript libraries when running in a closed network

When running in a closed network, the Redoc JavaScript libraries do not load properly because they reference a CDN rather than get included or bundled in the application.

Registry-1007 - Registry REST API returns 406 error

The Registry REST API returns a 406 error when the Accept: application/json header is included in the request.

Registry-711 - Apicurio Registry client does not work with Jersey HTTP client

When the Jersey and RESTEasy JAX-RS providers are both in the classpath, RESTEasy takes precedence and breaks other HTTP client functionality relying on Jersey client support for the application/octet-stream transport, which RESTEasy does not seem to support.

Apicurio Registry Operator resolved issues

Operator-41 - Example CRD is empty

The provided example ApicurioRegistry custom resource definition should not be empty.

1.7. Apicurio Registry known issues

Apicurio Registry core known issues

Registry-2394 - Apicurio Registry API endpoint for core v1 compatibility not properly protected by authentication

The legacy MY-REGISTRY-URL/api/ endpoint is an alias for the v1 core registry API that moved to MY-REGISTRY-URL/apis/registry/v1 in Apicurio Registry v2.x. This legacy endpoint is currently not protected when authentication is configured. This issue is fixed in Apicurio Registry v2.1.x, where the authentication layer no longer uses the Quarkus policies configured in application.properties.

To work around this issue in Apicurio Registry v2.0.x, disable the core v1 legacy endpoint by setting the REGISTRY_DISABLE_APIS environment variable to a value of /apis/ibmcompat/.,/api/..

IPT-701 - CVE-2022-23221 H2: Loading of custom classes from remote servers through JNDI

When Apicurio Registry data is stored in AMQ Streams, the H2 database console allows remote attackers to execute arbitrary code using the JDBC URL. Apicurio Registry is not vulnerable by default and a malicious configuration change is required.

Apicurio Registry operator known issues

Operator-42 - Auto-generation of OpenShift route may use wrong base host value

The auto-generation of the Apicurio Registry OpenShift route may use a wrong base host value if there are multiple routerCanonicalHostname values.

Operator-32 - Operator should support SCRAM authorization without TLS, not only SCRAM+TLS

The Apicurio Registry Operator should support Salted Challenge Response Authentication Mechanism (SCRAM) authorization without Transport Layer Security (TLS), not only SCRAM+TLS.

Legal Notice

Copyright © 2022 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red Hat