此内容没有您所选择的语言版本。

Chapter 7. Migrating Apicurio Registry client applications

Review every application that integrates with Apicurio Registry 2.6 to verify compatibility with the v3 REST API, SDKs, and client libraries. Update dependency coordinates, reconfigure endpoints, and adjust automation to account for the new data model.

Before you begin

Ensure you have the following:

Existing Apicurio Registry 2.6 applications that rely on the v2 REST API or legacy client libraries.
Access to the source code or deployment configuration for each application you must update.
Understanding of your client application types (Kafka SerDes, REST API clients, SDK-based applications).
Required dependencies for running migration scripts. See Installing dependencies.

Note

Apicurio Registry 3.x maintains backward compatibility with v2 client libraries and SerDes. You can continue using v2 clients with a v3 registry during your migration period, allowing gradual client updates.

Backward compatibility

Apicurio Registry 3.x provides backward compatibility for existing v2 clients:

v2 REST API remains available at /apis/registry/v2
v2 SerDes libraries continue to work with v3 registry
v3 SerDes can consumes v2 client Kafka messages (with proper configuration)
No immediate client updates required during migration

This approach lets you:

Migrate the registry to v3 first.
Test with existing v2 clients.
Gradually update clients to v3 libraries over time.

7.1. Choosing a migration strategy
复制链接

Gradual migration

Migrate registry first, then update clients incrementally:

Deploy Apicurio Registry 3.x
Verify v2 clients continue working
Update high-priority clients to v3 SerDes or SDKs
Gradually migrate remaining clients
Deprecate v2 API access once all clients updated

Benefits:

Lower risk: clients continue working during migration
Flexible timeline for client updates
Easier rollback if issues occur

Big-bang migration

Update all clients and registry simultaneously:

Prepare all client updates in advance
Deploy Apicurio Registry 3.x
Deploy updated client applications
Verify all integrations work

Benefits:

Clean cutover to v3
No mixed v2/v3 client environment

Risks:

Higher complexity and coordination required
More difficult to troubleshoot if issues arise

Migrating Kafka SerDes applications

Kafka SerDes applications require careful migration planning.

Maven dependency changes

Update SerDes library dependencies from v2 to v3:

Registry 2.x dependencies:

<dependency>
    <groupId>io.apicurio</groupId>
    <artifactId>apicurio-registry-serdes-avro-serde</artifactId>
    <version>2.6.13.Final</version>
</dependency>

<dependency>
    <groupId>io.apicurio</groupId>
    <artifactId>apicurio-registry-serdes-avro-serde</artifactId>
    <version>2.6.13.Final</version>
</dependency>

Copy to Clipboard

Toggle word wrap

Registry 3.x dependencies:

<dependency>
    <groupId>io.apicurio</groupId>
    <artifactId>apicurio-registry-avro-serde-kafka</artifactId>
    <version>3.1.2</version>
</dependency>

<dependency>
    <groupId>io.apicurio</groupId>
    <artifactId>apicurio-registry-avro-serde-kafka</artifactId>
    <version>3.1.2</version>
</dependency>

Copy to Clipboard

Toggle word wrap

Note

Artifact IDs changed in v3. The v2 artifact ID was apicurio-registry-serdes-avro-serde, while v3 uses apicurio-registry-avro-serde-kafka.

Configuration changes

Update SerDes configuration properties for v3:

Registry 2.x SerDes configuration:

Properties props = new Properties();

// v2 SerDes configuration
props.put(SerdeConfig.REGISTRY_URL, "https://registry-v2.example.com/apis/registry/v2");
props.put(SerdeConfig.AUTO_REGISTER_ARTIFACT, Boolean.TRUE);
props.put(SerdeConfig.ENABLE_HEADERS, false);
props.put(SerdeConfig.ENABLE_CONFLUENT_ID_HANDLER, true);
props.put(SerdeConfig.USE_ID, IdOption.contentId.name());

// v2 OAuth2 configuration
props.put(SerdeConfig.AUTH_SERVICE_URL, "https://keycloak.example.com");
props.put(SerdeConfig.AUTH_REALM, "registry");
props.put(SerdeConfig.AUTH_CLIENT_ID, "kafka-client");
props.put(SerdeConfig.AUTH_CLIENT_SECRET, "secret");

Properties props = new Properties();

// v2 SerDes configuration
props.put(SerdeConfig.REGISTRY_URL, "https://registry-v2.example.com/apis/registry/v2");
props.put(SerdeConfig.AUTO_REGISTER_ARTIFACT, Boolean.TRUE);
props.put(SerdeConfig.ENABLE_HEADERS, false);
props.put(SerdeConfig.ENABLE_CONFLUENT_ID_HANDLER, true);
props.put(SerdeConfig.USE_ID, IdOption.contentId.name());

// v2 OAuth2 configuration
props.put(SerdeConfig.AUTH_SERVICE_URL, "https://keycloak.example.com");
props.put(SerdeConfig.AUTH_REALM, "registry");
props.put(SerdeConfig.AUTH_CLIENT_ID, "kafka-client");
props.put(SerdeConfig.AUTH_CLIENT_SECRET, "secret");

Copy to Clipboard

Toggle word wrap

Registry 3.x SerDes configuration:

Properties props = new Properties();

// v3 SerDes configuration
props.put(SerdeConfig.REGISTRY_URL, "https://registry-v3.example.com/apis/registry/v3");
props.put(SerdeConfig.AUTO_REGISTER_ARTIFACT, Boolean.TRUE);

// v3 OAuth2 configuration (simplified)
props.put(SerdeConfig.AUTH_TOKEN_ENDPOINT, "https://keycloak.example.com/realms/registry/protocol/openid-connect/token");
props.put(SerdeConfig.AUTH_CLIENT_ID, "kafka-client");
props.put(SerdeConfig.AUTH_CLIENT_SECRET, "secret");

Properties props = new Properties();

// v3 SerDes configuration
props.put(SerdeConfig.REGISTRY_URL, "https://registry-v3.example.com/apis/registry/v3");
props.put(SerdeConfig.AUTO_REGISTER_ARTIFACT, Boolean.TRUE);

// v3 OAuth2 configuration (simplified)
props.put(SerdeConfig.AUTH_TOKEN_ENDPOINT, "https://keycloak.example.com/realms/registry/protocol/openid-connect/token");
props.put(SerdeConfig.AUTH_CLIENT_ID, "kafka-client");
props.put(SerdeConfig.AUTH_CLIENT_SECRET, "secret");

Copy to Clipboard

Toggle word wrap

Key configuration differences:

Expand

Property	Registry 2.x	Registry 3.x
OAuth2 endpoint	`AUTH_SERVICE_URL` + `AUTH_REALM`	`AUTH_TOKEN_ENDPOINT` (full URL)
ID Handler	`ID_HANDLER` (optional default "8 byte handler")	`ID_HANDLER` (optional default "4 byte handler")
Confluent ID handler	`ENABLE_CONFLUENT_ID_HANDLER` (optional convenience property)	Removed
Content ID usage	`USE_ID` with `IdOption` (default "globalId")	`USE_ID` with `IdOption` (default "contentId")

Note

The default ID option changed from globalId to contentId in v3. Both v2 and v3 SerDes can read messages using either ID type, ensuring compatibility during migration. If your v2 applications explicitly set USE_ID=contentId, you can remove this configuration in v3 as it is now the default.

TLS and HTTPS configuration

TLS configuration differs between v2 and v3 SerDes clients. Update your configuration as follows:

Registry 2.x (system properties):

// v2 SerDes clients use system properties for TLS configuration
System.setProperty("javax.net.ssl.trustStore", "/path/to/truststore.jks");
System.setProperty("javax.net.ssl.trustStorePassword", "password");

// v2 SerDes clients use system properties for TLS configuration
System.setProperty("javax.net.ssl.trustStore", "/path/to/truststore.jks");
System.setProperty("javax.net.ssl.trustStorePassword", "password");

Copy to Clipboard

Toggle word wrap

Registry 3.x (SerdeConfig properties):

// v3 SerDes clients use SerdeConfig properties for TLS configuration
Properties props = new Properties();

// Configure trust store for Registry HTTPS connections
props.put(SerdeConfig.TLS_TRUSTSTORE_LOCATION, "/path/to/truststore.jks");
props.put(SerdeConfig.TLS_TRUSTSTORE_PASSWORD, "password");
props.put(SerdeConfig.TLS_TRUSTSTORE_TYPE, "JKS");

// System properties for OAuth2 Keycloak connections
System.setProperty("javax.net.ssl.trustStore", "/path/to/truststore.jks");
System.setProperty("javax.net.ssl.trustStorePassword", "password");

// v3 SerDes clients use SerdeConfig properties for TLS configuration
Properties props = new Properties();

// Configure trust store for Registry HTTPS connections
props.put(SerdeConfig.TLS_TRUSTSTORE_LOCATION, "/path/to/truststore.jks");
props.put(SerdeConfig.TLS_TRUSTSTORE_PASSWORD, "password");
props.put(SerdeConfig.TLS_TRUSTSTORE_TYPE, "JKS");

// System properties for OAuth2 Keycloak connections
System.setProperty("javax.net.ssl.trustStore", "/path/to/truststore.jks");
System.setProperty("javax.net.ssl.trustStorePassword", "password");

Copy to Clipboard

Toggle word wrap

Important

v3 SerDes requires both SerdeConfig TLS properties (for Registry SDK connections) and system properties (for OAuth2 Keycloak connections). This is different from v2, which only used system properties.

Message format compatibility

With proper configuration, Apicurio Registry 3.x SerDes reads messages serialized by v2 SerDes:

v3 consumers read messages produced by v2 producers
v2 consumers read messages produced by v3 producers
Mixed environment (v2 and v3 clients) is fully supported

This helps avoid data loss during migration.

Migrating REST API clients

For applications using Apicurio Registry REST API directly (not Kafka SerDes):

SDK migration

Update to v3 Kiota-generated SDKs:

Registry 2.x SDK:

<dependency>
    <groupId>io.apicurio</groupId>
    <artifactId>apicurio-registry-client</artifactId>
    <version>2.6.13.Final</version>
</dependency>

<dependency>
    <groupId>io.apicurio</groupId>
    <artifactId>apicurio-registry-client</artifactId>
    <version>2.6.13.Final</version>
</dependency>

Copy to Clipboard

Toggle word wrap

Registry 3.x SDK:

<dependency>
    <groupId>io.apicurio</groupId>
    <artifactId>apicurio-registry-java-sdk</artifactId>
    <version>3.1.2</version>
</dependency>

<dependency>
    <groupId>io.apicurio</groupId>
    <artifactId>apicurio-registry-java-sdk</artifactId>
    <version>3.1.2</version>
</dependency>

Copy to Clipboard

Toggle word wrap

TLS and HTTPS configuration

TLS configuration differs between v2 and v3 clients. Update your configuration as follows:

Registry 2.x (system properties):

// v2 clients use system properties
System.setProperty("javax.net.ssl.trustStore", "/path/to/truststore.jks");
System.setProperty("javax.net.ssl.trustStorePassword", "password");

// v2 clients use system properties
System.setProperty("javax.net.ssl.trustStore", "/path/to/truststore.jks");
System.setProperty("javax.net.ssl.trustStorePassword", "password");

Copy to Clipboard

Toggle word wrap

Registry 3.x (RegistryClientOptions):

// v3 clients use RegistryClientOptions
RegistryClientOptions options = RegistryClientOptions.builder()
    .trustStore(new File("/path/to/truststore.jks"))
    .trustStorePassword("password")
    .build();

props.put(SerdeConfig.REGISTRY_CLIENT_OPTIONS, options);

// v3 clients use RegistryClientOptions
RegistryClientOptions options = RegistryClientOptions.builder()
    .trustStore(new File("/path/to/truststore.jks"))
    .trustStorePassword("password")
    .build();

props.put(SerdeConfig.REGISTRY_CLIENT_OPTIONS, options);

Copy to Clipboard

Toggle word wrap

Migrating client authentication

OAuth2/OIDC configuration changes for REST API client applications:

Registry 2.x client authentication:

import io.apicurio.registry.rest.client.RegistryClient;
import io.apicurio.registry.rest.client.RegistryClientFactory;
import io.apicurio.rest.client.auth.Auth;
import io.apicurio.rest.client.auth.OidcAuth;
import io.apicurio.rest.client.auth.exception.AuthErrorHandler;
import io.apicurio.rest.client.spi.ApicurioHttpClient;
import io.apicurio.rest.client.spi.ApicurioHttpClientFactory;

// v2 clients configure auth server URL, not the full token URL
String authServerUrl = "https://keycloak.example.com/realms/registry";
String clientId = "my-client";
String clientSecret = "my-secret";

// Create HTTP client for OIDC authentication
ApicurioHttpClient httpClient = ApicurioHttpClientFactory.create(authServerUrl,
    new AuthErrorHandler());

// Create OIDC auth with client credentials
Auth auth = new OidcAuth(httpClient, clientId, clientSecret, null, null);

// Create registry client with auth
RegistryClient client = RegistryClientFactory.create(registryUrl, Collections.emptyMap(), auth);

import io.apicurio.registry.rest.client.RegistryClient;
import io.apicurio.registry.rest.client.RegistryClientFactory;
import io.apicurio.rest.client.auth.Auth;
import io.apicurio.rest.client.auth.OidcAuth;
import io.apicurio.rest.client.auth.exception.AuthErrorHandler;
import io.apicurio.rest.client.spi.ApicurioHttpClient;
import io.apicurio.rest.client.spi.ApicurioHttpClientFactory;

// v2 clients configure auth server URL, not the full token URL
String authServerUrl = "https://keycloak.example.com/realms/registry";
String clientId = "my-client";
String clientSecret = "my-secret";

// Create HTTP client for OIDC authentication
ApicurioHttpClient httpClient = ApicurioHttpClientFactory.create(authServerUrl,
    new AuthErrorHandler());

// Create OIDC auth with client credentials
Auth auth = new OidcAuth(httpClient, clientId, clientSecret, null, null);

// Create registry client with auth
RegistryClient client = RegistryClientFactory.create(registryUrl, Collections.emptyMap(), auth);

Copy to Clipboard

Toggle word wrap

Registry 3.x SDK authentication:

import io.apicurio.registry.client.RegistryClientFactory;
import io.apicurio.registry.client.RegistryClientOptions;
import io.apicurio.registry.rest.client.RegistryClient;

// v3 clients use RegistryClientOptions builder with full token endpoint URL
String tokenEndpoint = "https://keycloak.example.com/realms/registry/protocol/openid-connect/token";
String clientId = "my-client";
String clientSecret = "my-secret";

// Create options with OAuth2 client credentials
RegistryClientOptions options = RegistryClientOptions.create(registryUrl)
    .oauth2(tokenEndpoint, clientId, clientSecret, null);

// Create registry client
RegistryClient client = RegistryClientFactory.create(options);

import io.apicurio.registry.client.RegistryClientFactory;
import io.apicurio.registry.client.RegistryClientOptions;
import io.apicurio.registry.rest.client.RegistryClient;

// v3 clients use RegistryClientOptions builder with full token endpoint URL
String tokenEndpoint = "https://keycloak.example.com/realms/registry/protocol/openid-connect/token";
String clientId = "my-client";
String clientSecret = "my-secret";

// Create options with OAuth2 client credentials
RegistryClientOptions options = RegistryClientOptions.create(registryUrl)
    .oauth2(tokenEndpoint, clientId, clientSecret, null);

// Create registry client
RegistryClient client = RegistryClientFactory.create(options);

Copy to Clipboard

Toggle word wrap

Key authentication differences:

Expand

Aspect	Registry 2.x	Registry 3.x
Configuration approach	Separate `Auth` object with `OidcAuth`	Fluent builder with `RegistryClientOptions`
OAuth2 endpoint	Full auth server URL with realm path	Full OIDC token endpoint URL
Factory method	`RegistryClientFactory.create(url, map, auth)`	`RegistryClientFactory.create(options)`

此内容没有您所选择的语言版本。

Chapter 7. Migrating Apicurio Registry client applications

7.1. Choosing a migration strategy
复制链接

学习

尝试、购买和销售

社区

关于红帽文档

让开源更具包容性

關於紅帽

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

此内容没有您所选择的语言版本。

Chapter 7. Migrating Apicurio Registry client applications

7.1. Choosing a migration strategy复制链接链接已复制到粘贴板!

学习

尝试、购买和销售

社区

关于红帽文档

让开源更具包容性

關於紅帽

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

7.1. Choosing a migration strategy
复制链接