Chapter 6. Service Registry release notes

Red Hat Integration - Service Registry 2.0 is available as a General Availability component in Red Hat Integration 2021.Q3. 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 backwards and forwards compatibility of schema or API versions.

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

6.2. Service Registry platform component versions

Service Registry 2.0.2 supports the following versions:

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

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

Service Registry core

  • Registry artifact groups - optionally organize schema and API artifacts into custom named logical groupings
  • Refactored Kafka serializer/deserializer (SerDe) classes - significant updates to the Java SerDe 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

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

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

6.6. Service Registry resolved issues

Service Registry core resolved issues

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 v2.0.2 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-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 should not be empty

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

6.7. Service Registry known issues

Service Registry core known issues

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 is caused by Kafka log compaction, which removes messages that control database sequences. The workaround is to disable log compaction and to use the Service Registry export/import feature to force a reset of the database sequences so that the error no longer occurs.

For a detailed explanation, see the Apicurio community blog post on Resolving a bug in KafkaSQL storage for Apicurio Registry.

Registry-1610 - Service Registry web console does not properly disable user roles for authorization

You can configure the Service Registry server to disable role-based authorization. When configured, authentication credentials are required, but roles are ignored, and any authenticated user can preform any action. The web console does not support this, and assumes that if authentication is enabled, role-based authorization is also enabled.

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.

Service Registry operator known issues

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.

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.