Red Hat SummitChapter 6. Service Registry release notes
Service Registry 2.4 is provided as a General Availability release. Service Registry is a data store for standard event schemas and API designs, and is based on the Apicurio Registry open source community project.
Red Hat build of Apicurio Registry is now available as part of Red Hat Application Foundations. Red Hat build of Apicurio Registry 2.x and Red Hat Integration Service Registry 2.x are functionally identical. For more information, see https://access.redhat.com/products/red-hat-application-foundations/.
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 create optional rules to govern how Service Registry content evolves over time. These rules include validation of content, integrity of artifact references, and backwards or 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:
- PostgreSQL database
- Red Hat AMQ Streams
For more details, see Installing and deploying Service Registry on OpenShift.
6.2. Service Registry supported platforms
Service Registry 2.4 supports the following platforms:
- Red Hat OpenShift Container Platform 4.13, 4.12, 4.11, 4.10
- Red Hat OpenShift Service on AWS
- Microsoft Azure Red Hat OpenShift
- PostgreSQL 15, 14, 13, 12
- Red Hat AMQ Streams 2.4, 2.3, 2.2, 2.1
- OpenJDK 17, 11
For more details, see the following article:
Service Registry 2.4 also supports integration with the following products:
- Red Hat Single Sign-On (RH-SSO) 7.6
- Red Hat build of Debezium 2.1
6.3. Service Registry new features
Service Registry 2.4 includes the following new features:
Service Registry core new features
- Artifact references improvements
- Artifact reference integrity rule: You can now apply a new artifact-specific rule and global rule to enforce the integrity of artifact references when creating or updating artifacts. For all artifact types, the rule detects duplicate artifact references and prevents references to nonexistent artifacts. For a subset of artifact types (Apache Avro, Google Protobuf, OpenAPI, and AsyncAPI), the rule ensures that all artifact references are mapped.
- Automatic artifact reference detection in Maven plug-in: For a subset of artifact types (Apache Avro, Google Protobuf, and JSON Schema), the Maven plug-in can now automatically identify and configure all of the artifact references for a given artifact when creating or updating artifacts.
- Visualization of artifact references in the web console: You can now view both inbound and outbound references for an artifact version, in a new References tab. The REST API now supports the retrieval of both inbound and outbound references. Previously, the REST API retrieved outbound references only, and the web console did not display references.
- Artifact references are now treated as content: This release now considers artifact references when calculating the content hash and ID, and when checking compatibility of an artifact version. If you upload the same schema content with different references, you create a new artifact version.
- Client SDK generation (OpenAPI)
- This release adds a new web console feature to enable users to generate a client SDK from an OpenAPI artifact. This feature uses Kiota from Microsoft to generate the SDK. The feature runs in your browser only, and cannot be automated by using an API. For more information, see https://github.com/microsoft/kiota.
- Artifact version deletion
- This release adds a new REST API operation, and a new Delete artifact version setting in the web console, to enable you to delete artifact versions by using the REST API. Previously, artifact versions were immutable; you could deprecate or disable them, but not delete them. However, it is sometimes necessary to delete an artifact version, despite the semantic implications. For example, you might need to delete an artifact version for regulatory or policy reasons.
- Core Registry REST API improvements
- Version comments API: You can now use the REST API to add comments to artifact versions. Managing comments is not yet available in the web console.
-
Export API supports application/json in the Accept header: You can now send
application/jsonas the value of theAcceptheader in a call to the/admin/exportAPI endpoint. Previously, the only way to return anapplication/jsonformatted response was by using theforBrowserquery parameter. Now you can use either the query parameter or theAcceptheader. - Group management: You can now optionally manage artifact groups directly by using the REST API, rather than implicitly as part of artifact creation.
- Confluent Compatibility REST API improvements
- Updated support for Confluent Compatibility API: Added support for version 7 of the Confluent Schema Registry API. Service Registry now supports both v6 and v7, at different endpoints.
-
Customizable maximum number of Subjects: You can now use the
registry.ccompat.max-subjectsdynamic configuration property to customize the maximum number of Subjects returned by theccompatAPI.
- Other changes
-
Serializer/deserializer artifact resolution with content hash:
SerDeclasses can now resolve artifact coordinates by using the content hash of the schema. - Maven plug-in option to minify Avro: When registering an Avro schema by using the Maven plug-in, you can now minify the content prior to registration.
-
Serializer/deserializer artifact resolution with content hash:
- Community-only: Custom artifact types
Users can potentially extend Service Registry with their own custom artifact types, and remove support for existing types. This feature is available only in the community version of Service Registry, and is not supported.
NoteTo provide this feature, the
ArtifactTypein the REST API was changed from anenumto a simplestring. If you use the REST API client for custom integrations, you might have to edit your code after you upgrade to the newer client.
Service Registry Operator new features
- Operator support for HTTPS
-
Added support for configuring HTTPS connections inside the OpenShift cluster. You can create a Secret containing the certificate and the private key, named
tls.crtandtls.keyrespectively, and reference the Secret by setting thespec.configuration.security.https.secretNamefield in theApicurioRegistrycustom resource definition (CRD) file. The Service Registry Operator can then configure an HTTPS port on the Service RegistryServiceresource. If HTTPS is enabled, you can disable the HTTP connection by settingspec.security.https.disableHttptotrue. - Support for manually managed OpenShift resources
You can now disable certain resource types to ensure that the Service Registry Operator does not create or manage those resources, so that you can configure them manually. Manual configuration provides you with greater flexibility in using features that the Service Registry Operator does not currently support. If you disable a resource type, its existing instance is deleted. If you enable a resource type, the Service Registry Operator attempts to find a resource using the app label (for example,
app=example-apicurioregistry) and start managing it. Otherwise, the Service Registry Operator creates a new instance. You can disable the following resource types in this way:-
Ingress -
NetworkPolicy -
PodDisruptionBudget
-
- Improved log level configuration
-
You can now set the log level for Service Registry and the Service Registry Operator more easily, by using the
spec.configuration.registryLogLevelfield in theApicurioRegistryCRD file. This new field sets the log level for Apicurio application components (excludes non-Apicurio components and libraries), in contrast with thespec.configuration.logLevelfield, which works for non-Apicurio components and libraries. You can now also set the log level for the Service Registry Operator, by setting theLOG_LEVELenvironment variable in the OperatorDeploymentresource. ValidLOG_LEVELvalues aredebug,info,warn, anderror. - CORS allowed origins
Servers can use the Cross-Origin Resource Sharing (CORS) mechanism to control whether a response can be shared with the origin of the request. The Service Registry Operator now sets the
CORS_ALLOWED_ORIGINSenvironment variable, based on the value of thespec.deployment.hostfield in theApicurioRegistryCRD file. This environment variable controls theAccess-Control-Allow-Originheader sent by Service Registry.If you use a custom
Ingress(for example, to configure HTTPS), you can disable the Operator-managedIngressby setting thespec.deployment.managedResources.disableIngressfield totrue, and still set thespec.deployment.hostfield to the appropriate value. If you want to configure a fully customized CORS policy, you can set thespec.deployment.hostfield to be empty, apply the changes, and then use thespec.deployment.envfield to set theCORS_ALLOWED_ORIGINSenvironment variable manually.- Configuring Service Registry deployment by using a pod template
The
ApicurioRegistryCRD file now contains thespec.deployment.podTemplateSpecPreviewfield as a Technology Preview feature. Thespec.deployment.podTemplateSpecPreviewfield has the same structure as thespec.templatefield in an OpenShiftDeploymentresource (thePodTemplateSpecstruct). With some restrictions, the Service Registry Operator forwards the data from this field to the corresponding field in the Service RegistryDeploymentresource. This feature provides greater configuration flexibility, without requiring the Service Registry Operator to natively support each use case.ImportantTechnology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.
Service Registry user documentation and examples
The documentation library has been updated with the new features available in version 2.4:
The open source demonstration applications have also been updated:
6.4. Service Registry deprecated features
Service Registry core deprecated features
- Confluent Schema Registry API version 6 (compatibility API): Service Registry currently supports two versions of the Confluent Schema Registry API on separate endpoints: version 6 and version 7. Use of version 6 is deprecated; the v6 API endpoint will be removed in a future release. Ensure that you replace all references to the v6 endpoint with references to the v7 API endpoint.
- Service Registry Core API version 1: Service Registry support for the original version of the Service Registry Core API (version 1) is now deprecated; the legacy API will be removed in the next major release.
-
Dynamic log level configuration: The
/admin/loggersand/admin/loggers/{logger}API endpoints are now deprecated in the Service Registry Core API (v2). These endpoints will be removed in a future release. - Registry V1 export utility: Service Registry support for the command-line export utility is now deprecated. The export tool, which is used to export data from Service Registry 1.x into a format that can be imported into 2.x, will no longer be released or maintained. All customers should have already upgraded from 1.x to 2.x.
Service Registry Operator deprecated features
-
Setting environment variables by editing the Deployment resource: In previous versions, you could set environment variables for Service Registry by directly editing its
Deploymentresource, which was supported by the Service Registry Operator. Now that you can manage environment variables by using thespec.configuration.envfield in theApicurioRegistryCRD file, the previous procedure is deprecated and the Operator support for it will be removed. Ensure that you use thespec.configuration.envfield to set all environment variables that are not set by the Operator. - Retention of environment variables for features that are not enabled: The Service Registry Operator sets environment variables to enable and configure various features, such as Salted Challenge Response Authentication Mechanism (SCRAM) security when using KafkaSQL storage. When such features are disabled, the Operator currently retains the associated environment variables, which can cause problems. Retention of such environment variables is deprecated, and the Operator support for it will be removed. Ensure that your deployment does not rely on the retention of such environment variables.
-
Environment variable precedence: The Service Registry Operator might attempt to set an environment variable that is already explicitly specified in the
spec.configuration.envfield. If an environment variable has a conflicting value, the value set by the Service Registry Operator takes precedence by default. This behavior will change in the future, to enable users to overwrite most environment variables set by the Operator. Ensure that your deployment does not rely on the original precedence behavior.
6.5. Upgrading and migrating Service Registry deployments
You can upgrade the Service Registry server automatically from Service Registry 2.x to Service Registry 2.4 on OpenShift. There is no automatic upgrade from Service Registry 1.x to Service Registry 2.x, and a migration process is required.
6.5.1. Updating 2.x client dependencies
It is not mandatory to update client dependencies for this release; existing 2.x clients still work with Service Registry 2.4.
However, before the next release of Service Registry, you must update all of your client application dependencies to use the latest Service Registry client version. Client application dependencies include dependencies for Kafka serializers/deserializers (SerDes), Maven plug-in, and Java REST client. For example, to update the Maven dependencies for a Java REST client, specify the version in your pom.xml file as follows:
<dependency>
<groupId>io.apicurio</groupId>
<artifactId>apicurio-registry-client</artifactId>
<version>2.4.3.Final-redhat-00006</version>
</dependency>
<dependency>
<groupId>io.apicurio</groupId>
<artifactId>apicurio-registry-client</artifactId>
<version>2.4.3.Final-redhat-00006</version>
</dependency>For more details, see Legacy REST API date formats enabled by default.
6.5.2. Upgrading from Service Registry 2.x on OpenShift
You can upgrade from Service Registry 2.x on OpenShift 4.9 to Service Registry 2.4 on OpenShift 4.10 or later. You must upgrade both your Service Registry and your OpenShift versions, and upgrade OpenShift one minor version at a time.
Prerequisites
- You already have Service Registry 2.x installed on OpenShift 4.9.
Procedure
- In the OpenShift Container Platform web console, click Administration and then Cluster Settings.
-
Click the pencil icon next to the Channel field, and select the next minor
candidateversion (for example, change fromstable-4.9tocandidate-4.10). - Click Save and then Update, and wait until the upgrade is complete.
-
If the OpenShift version is less than 4.11, repeat steps 2 and 3, and select
candidate-4.11or later. - Click Operators > Installed Operators > Red Hat Integration - Service Registry.
-
Ensure that the Update channel is set to
2.x. -
If the Update approval is set to Automatic, the upgrade should be approved and installed immediately after the
2.xchannel is set. - If the Update approval is set to Manual, click Install.
- Wait until the Operator is deployed and the Service Registry pod is deployed.
- Verify that your Service Registry system is up and running.
Additional resources
- For more details on how to set the Operator update channel in the OpenShift Container Platform web console, see Changing the update channel for an Operator.
6.5.3. Migrating from Service Registry 1.1 on OpenShift
For details on migrating from Service Registry 1.1 to Service Registry 2.x, see Migrating Service Registry deployments.
6.6. Service Registry resolved issues
| Issue | Description |
|---|---|
| Enabling Anonymous read access and Artifact owner-only authorization in web console fails with error. | |
| Key password not optional when configuring KafkaSQL storage to use SSL. | |
|
JSON schema compatibility check fails for | |
|
| |
|
| |
|
Serialization error in | |
|
Cannot upload JSON schemas that reference other schemas with | |
| Compatibility check does not throw exception when empty schema is provided. | |
|
Upload fails with 422 error when schema has default value of | |
| Kafka consumer thread starts before internal database is ready. | |
| Redirect filter configured incorrectly. | |
| Compatibility rules do not order by version number. | |
| SSL configuration does not work unless SASL is enabled. | |
| 'registry.ccompat.use-canonical-hash' setting changes schema to canonized form on save. | |
| Exception not thrown when wrong credentials passed to auth server. | |
|
Uploading new version of Protobuf schema fails with | |
| Name and description populated incorrectly when creating artifact with REST API. | |
| Cannot get latest enabled version of schema if latest version is disabled. | |
| JSON schema validation fails for complex array objects. |
Service Registry Operator resolved issues
| Issue | Description |
|---|---|
| Port name not provided in service created by Operator. | |
| Missing environment variables after deployment destroyed. | |
| Incorrect method documented for managing environment variables. | |
| Log level not set correctly. |
6.7. Service Registry resolved CVEs
| Issue | Description |
|---|---|
| CVE-2023-2976 guava: Insecure temporary directory creation [rhint-serv-2]. | |
| CVE-2021-46877 jackson-databind: Possible DoS if using JDK serialization to serialize JsonNode [rhint-serv-2]. | |
| CVE-2022-3510 protobuf-java: Message-Type Extensions parsing issue leads to DoS [rhint-serv-2]. | |
| CVE-2022-3509 protobuf-java: Textformat parsing issue leads to DoS [rhint- serv-2]. | |
| CVE-2023-28867 graphql-java: crafted GraphQL query causes stack consumption [rhint-serv-2]. | |
| CVE-2022-25881 http-cache-semantics: Regular Expression Denial of Service (ReDoS) vulnerability [rhint-serv-2]. | |
| CVE-2022-3782 keycloak: path traversal via double URL encoding [rhint-serv-2]. | |
| CVE-2022-45787 apache-james-mime4j: Temporary File Information Disclosure in MIME4J TempFileStorageProvider [rhint-serv-2]. | |
| CVE-2022-4742 json-pointer: prototype pollution in json-pointer [rhint-serv-2]. | |
| CVE-2022-40152 woodstox-core: woodstox to serialise XML data was vulnerable to Denial of Service (DoS) attacks [rhint-serv-2]. |
6.8. Service Registry known issues
The following known issues apply in Service Registry 2.4.x:
Service Registry core known issues
Registry-3413 - Legacy REST API date formats enabled by default
For maximum compatibility and for easier upgrades from older versions of Service Registry, the date format used in the REST API is not compliant with OpenAPI standards (because of a bug in older versions).
Before the next release of Service Registry, you must upgrade all of your client applications to use the latest client version. The next release will fix the date format bug, which will result in older clients no longer being compatible with the REST API.
To update your REST API to be OpenAPI compliant, you can fix the date format bug in this version of Service Registry as follows:
-
Update all of your client applications to version
2.4.3.Final-redhat-00006, as described in Updating 2.x client dependencies. Set the following environment variable to the value shown:
REGISTRY_APIS_V2_DATE_FORMAT=yyyy-MM-dd'T'HH:mm:ss'Z'
REGISTRY_APIS_V2_DATE_FORMAT=yyyy-MM-dd'T'HH:mm:ss'Z'Copy to Clipboard Copied! Toggle word wrap Toggle overflow
IPT-814 - Service Registry logout feature incompatible with RH-SSO 7.6
In RH-SSO 7.6, the redirect_uri parameter used with the logout endpoint is deprecated. For more details, see the RH-SSO 7.6 Upgrading Guide. Because of this deprecation, when Service Registry is secured by using the RH-SSO Operator, clicking the Logout button displays the Invalid parameter: redirect_uri error.
For a workaround, see https://access.redhat.com/solutions/6980926.
IPT-701 - CVE-2022-23221 H2 allows loading 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 by 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 - Autogeneration of OpenShift route might use wrong base host value
If multiple routerCanonicalHostname values are specified, autogeneration of the Service Registry OpenShift route might use a wrong base host value.
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}