Release Notes for Apicurio Registry 2.0
What's new in Red Hat build of Apicurio Registry
Abstract
Chapter 1. Apicurio Registry release notes Copy linkLink copied to clipboard!
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 Copy linkLink copied to clipboard!
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 Copy linkLink copied to clipboard!
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 Copy linkLink copied to clipboard!
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, orsr-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
.zipformat CNCF Schema Registry API support - implementation of the Cloud Native Computing Foundation Schema Registry REST API
NoteThe 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
Deploymenton OpenShift (instead ofDeploymentConfig), 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
conditionsfield in thestatusblock 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
Documentation library updated with new features in version 2.0:
Updated Open source demonstration applications:
1.4. Apicurio Registry deprecated and removed features Copy linkLink copied to clipboard!
Apicurio Registry deprecated features
- Apicurio Registry version 1.x has been deprecated in version 2.0 and will soon go out of full support. For more details, see the Red Hat Middleware Product Update and Support Policy.
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 Copy linkLink copied to clipboard!
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 Copy linkLink copied to clipboard!
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 Copy linkLink copied to clipboard!
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.