Chapter 5. Service Registry release notes

Red Hat Integration - Service Registry 2.0 is available as a General Availability component in Red Hat Integration 2022.Q1. Service Registry is a datastore for standard event schemas and API designs, which is based on the Apicurio Registry open source community project.

You can use Service 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 Service Registry without needing to redeploy. You can also use Service 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.

5.1. Service Registry installation options

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

  • AMQ Streams
  • PostgreSQL database

For more details, see Installing and deploying Service Registry on OpenShift.

5.2. Service Registry platform component versions

Service 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

5.3. Service Registry new features

Service 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

Service 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

Service 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

Service 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 Service 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 Service Registry v1 REST API.

Service 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.

Service Registry user documentation and examples

5.4. Service Registry deprecated and removed features

Service Registry deprecated features

Service 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
  • Service Registry Java client no longer supports OpenJDK 8 and supports OpenJDK 11 instead

5.5. Migrating Service Registry deployments

For details migrating from Service Registry version 1.1 to 2.x, see Migrating Service Registry deployments.

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

5.6. Service Registry resolved issues

Service Registry core resolved issues

IPT-651 - Error deserializing Protobuf message when getting schema from Service 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 Service Registry with KafkaSQL storage

When Service 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 Service Registry v2.x were required to upgrade all of their Kafka client applications that use Service Registry v1 serializers/deserializers (SerDes) to use the Service Registry v2 SerDes instead.

Service 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, Service Registry uses globalId instead of contentId as the unique integer identifier for schemas uploaded using the compatibility API.

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

When role-based authorization is disabled in the Service 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 Service 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 - Service 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.

Service Registry Operator resolved issues

Operator-41 - Example CRD is empty

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

5.7. Service Registry known issues

Service Registry core known issues

Registry-2394 - Service 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 Service 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 Service 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 Service Registry data is stored in AMQ Streams, the H2 database console allows remote attackers to execute arbitrary code using the JDBC URL. Service Registry is not vulnerable by default and a malicious configuration change is required.

Service Registry operator known issues

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

The auto-generation of the Service 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 Service Registry Operator should support Salted Challenge Response Authentication Mechanism (SCRAM) authorization without Transport Layer Security (TLS), not only SCRAM+TLS.