このコンテンツは選択した言語では利用できません。

Chapter 8. Updating Apicurio Registry configuration

Configuration keys in Apicurio Registry 3.x adopt a unified apicurio. namespace and reorganize authentication, eventing, UI, and storage settings. Review and update your deployment descriptors to match the new naming scheme.

Important

Configuration property changes are extensive in 3.x. Review all sections carefully and test in a staging environment before migrating production deployments.

Understanding configuration changes

Apicurio Registry 3.x introduces major configuration changes:

Namespace consolidation: Most properties now use the apicurio. prefix
Storage configuration: Database settings moved out of quarkus.datasource.* namespace
Authentication: OAuth2/OIDC configuration uses full realm URLs
KafkaSQL: New apicurio.kafkasql.* namespace with different topic requirements
API features: New granular deletion control properties

8.1. Configuring storage
リンクのコピー

SQL storage (PostgreSQL, MySQL, H2)

You must use separate database instances or schemas for v2 and v3 because the database schemas are incompatible.

Expand

Registry 2.x property	Registry 3.x property
`REGISTRY_DATASOURCE_URL`	`APICURIO_DATASOURCE_URL`
`REGISTRY_DATASOURCE_USERNAME`	`APICURIO_DATASOURCE_USERNAME`
`REGISTRY_DATASOURCE_PASSWORD`	`APICURIO_DATASOURCE_PASSWORD`
`QUARKUS_DATASOURCE_DB_KIND`	Not required (auto-detected from URL)
`REGISTRY_SQL_INIT`	`APICURIO_SQL_INIT`
Not applicable	`APICURIO_STORAGE_KIND=sql` (required)
Not applicable	`APICURIO_STORAGE_SQL_KIND` (PostgreSQL, MySQL, H2)

Example migration:

# Registry 2.x SQL configuration
REGISTRY_DATASOURCE_URL=jdbc:postgresql://postgres:5432/registry
REGISTRY_DATASOURCE_USERNAME=apicurio
REGISTRY_DATASOURCE_PASSWORD=password123
QUARKUS_DATASOURCE_DB_KIND=postgresql

# Registry 3.x SQL configuration
APICURIO_STORAGE_KIND=sql
APICURIO_STORAGE_SQL_KIND=postgresql
APICURIO_DATASOURCE_URL=jdbc:postgresql://postgres:5432/registry_v3
APICURIO_DATASOURCE_USERNAME=apicurio
APICURIO_DATASOURCE_PASSWORD=password123

# Registry 2.x SQL configuration
REGISTRY_DATASOURCE_URL=jdbc:postgresql://postgres:5432/registry
REGISTRY_DATASOURCE_USERNAME=apicurio
REGISTRY_DATASOURCE_PASSWORD=password123
QUARKUS_DATASOURCE_DB_KIND=postgresql

# Registry 3.x SQL configuration
APICURIO_STORAGE_KIND=sql
APICURIO_STORAGE_SQL_KIND=postgresql
APICURIO_DATASOURCE_URL=jdbc:postgresql://postgres:5432/registry_v3
APICURIO_DATASOURCE_USERNAME=apicurio
APICURIO_DATASOURCE_PASSWORD=password123

Copy to Clipboard

Toggle word wrap

Important

Use separate database instances or different database names for v2 and v3. The v3 database schema is incompatible with v2.

KafkaSQL storage

You must use a different Kafka topic for v3 than v2 because the journal formats are incompatible.

Expand

Registry 2.x property	Registry 3.x property
`KAFKA_BOOTSTRAP_SERVERS`	`APICURIO_KAFKASQL_BOOTSTRAP_SERVERS`
`REGISTRY_KAFKASQL_TOPIC`	`APICURIO_KAFKASQL_TOPIC`
`REGISTRY_KAFKASQL_CONSUMER_GROUP_ID`	`APICURIO_KAFKASQL_CONSUMER_GROUP_ID` (optional)
Not applicable	`APICURIO_STORAGE_KIND=kafkasql` (required)

Example migration:

# Registry 2.x KafkaSQL configuration
KAFKA_BOOTSTRAP_SERVERS=kafka:9092
REGISTRY_KAFKASQL_TOPIC=kafkasql-journal-v2
REGISTRY_KAFKASQL_CONSUMER_GROUP_ID=registry-v2-consumer

# Registry 3.x KafkaSQL configuration
APICURIO_STORAGE_KIND=kafkasql
APICURIO_KAFKASQL_BOOTSTRAP_SERVERS=kafka:9092
APICURIO_KAFKASQL_TOPIC=kafkasql-journal-v3

# Registry 2.x KafkaSQL configuration
KAFKA_BOOTSTRAP_SERVERS=kafka:9092
REGISTRY_KAFKASQL_TOPIC=kafkasql-journal-v2
REGISTRY_KAFKASQL_CONSUMER_GROUP_ID=registry-v2-consumer

# Registry 3.x KafkaSQL configuration
APICURIO_STORAGE_KIND=kafkasql
APICURIO_KAFKASQL_BOOTSTRAP_SERVERS=kafka:9092
APICURIO_KAFKASQL_TOPIC=kafkasql-journal-v3

Copy to Clipboard

Toggle word wrap

Important

Use a different topic name for v3 (kafkasql-journal-v3) than v2 (kafkasql-journal-v2). The v3 journal format is incompatible with v2.

Understanding KafkaSQL storage

Apicurio Registry 3.x completely re-engineers the KafkaSQL storage implementation with significant architectural improvements.

Architectural changes in v3

Apicurio Registry 3.x introduces a fundamentally different KafkaSQL implementation:

True journaling approach: The new implementation uses a true event journaling pattern
No log compaction: Unlike v2, the v3 implementation does not rely on Kafka log compaction
Immutable event log: All registry operations are stored as immutable events in the journal topic
Improved consistency: Better handling of concurrent operations and edge cases

Kafka topic configuration

The v3 KafkaSQL journal topic requires specific Kafka topic settings:

Cleanup policy:

v3 KafkaSQL topic must use "delete" cleanup policy (NOT "compact")
cleanup.policy=delete

# Set infinite retention to preserve all journal events
retention.ms=-1
retention.bytes=-1

# v3 KafkaSQL topic must use "delete" cleanup policy (NOT "compact")
cleanup.policy=delete

# Set infinite retention to preserve all journal events
retention.ms=-1
retention.bytes=-1

Copy to Clipboard

Toggle word wrap

Important

Configure the journal topic with cleanup.policy=delete and infinite retention (retention.ms=-1). Do not use log compaction. You must preserve all journal events for proper registry operation.

Creating the topic:

# Create v3 KafkaSQL topic with correct settings
kafka-topics.sh --bootstrap-server kafka:9092 --create \
  --topic kafkasql-journal-v3 \
  --partitions 1 \
  --replication-factor 3 \
  --config cleanup.policy=delete \
  --config retention.ms=-1 \
  --config retention.bytes=-1

# Create v3 KafkaSQL topic with correct settings
kafka-topics.sh --bootstrap-server kafka:9092 --create \
  --topic kafkasql-journal-v3 \
  --partitions 1 \


  --replication-factor 3 \
  --config cleanup.policy=delete \
  --config retention.ms=-1 \
  --config retention.bytes=-1

Copy to Clipboard

Toggle word wrap

1: The partition count is configurable. All journal messages use a global partition key for ordering, so a single partition is sufficient. Adjust based on your Kafka cluster configuration.

Verifying topic configuration:

# Check topic configuration
kafka-topics.sh --bootstrap-server kafka:9092 --describe \
  --topic kafkasql-journal-v3

# Should show:
  cleanup.policy=delete
  retention.ms=-1
  retention.bytes=-1

# Check topic configuration
kafka-topics.sh --bootstrap-server kafka:9092 --describe \
  --topic kafkasql-journal-v3

# Should show:
#   cleanup.policy=delete
#   retention.ms=-1
#   retention.bytes=-1

Copy to Clipboard

Toggle word wrap

Snapshotting feature (advanced)

Apicurio Registry 3.x KafkaSQL includes an optional snapshotting feature for advanced use cases.

What is snapshotting?

Snapshotting creates periodic database snapshots of the registry state, providing:

Faster startup times: Registry loads from the snapshot instead of replaying the entire journal
Backup capability: Use snapshots for disaster recovery
Optional journal cleanup: When snapshotting is enabled, you can configure finite retention to remove older journal events

When to use snapshotting:

Large registries with many artifacts (thousands+)
Long-running deployments with growing journal topics
Need for faster registry startup/recovery times

Important

Without snapshotting enabled, you must preserve all journal events (infinite retention). If you enable snapshotting and want to use finite retention, set apicurio.kafkasql.topic-configuration-verification-override-enabled=true and ensure snapshots are created more frequently than messages are deleted.

Note

Snapshotting is an advanced feature. Most deployments do not need snapshotting enabled. Consult the official Apicurio Registry documentationfor more information on how to configure and use the snapshotting feature.

Configuring authentication and authorization

Authentication configuration changes significantly in 3.x, particularly for OAuth2/OIDC integration. Update your configuration properties as shown in the following table.

Expand

Registry 2.x property	Registry 3.x property
`AUTH_ENABLED`	`QUARKUS_OIDC_TENANT_ENABLED`
`KEYCLOAK_URL`	Use `QUARKUS_OIDC_AUTH_SERVER_URL` with full realm path
`KEYCLOAK_REALM`	Included in `QUARKUS_OIDC_AUTH_SERVER_URL`
`KEYCLOAK_API_CLIENT_ID`	`QUARKUS_OIDC_CLIENT_ID`
`ROLE_BASED_AUTHZ_ENABLED`	`APICURIO_AUTH_ROLE-BASED-AUTHORIZATION`
`REGISTRY_AUTH_ROLES_ADMIN`	`APICURIO_AUTH_ROLES_ADMIN`
`REGISTRY_AUTH_ROLES_DEVELOPER`	`APICURIO_AUTH_ROLES_DEVELOPER`
`REGISTRY_AUTH_ROLES_READONLY`	`APICURIO_AUTH_ROLES_READONLY`
`QUARKUS_OIDC_TLS_VERIFICATION`	`QUARKUS_OIDC_TLS_VERIFICATION` (same)

Example migration with Keycloak:

# Registry 2.x authentication
AUTH_ENABLED=true
KEYCLOAK_URL=https://keycloak:8443
KEYCLOAK_REALM=registry
KEYCLOAK_API_CLIENT_ID=registry-api
ROLE_BASED_AUTHZ_ENABLED=true
REGISTRY_AUTH_ROLES_ADMIN=sr-admin
REGISTRY_AUTH_ROLES_DEVELOPER=sr-developer
REGISTRY_AUTH_ROLES_READONLY=sr-readonly

# Registry 3.x authentication
QUARKUS_OIDC_TENANT_ENABLED=true
QUARKUS_OIDC_AUTH_SERVER_URL=https://keycloak:8443/realms/registry
QUARKUS_OIDC_CLIENT_ID=registry-api
APICURIO_AUTH_ROLE-BASED-AUTHORIZATION=true
APICURIO_AUTH_ROLES_ADMIN=sr-admin
APICURIO_AUTH_ROLES_DEVELOPER=sr-developer
APICURIO_AUTH_ROLES_READONLY=sr-readonly

# Registry 2.x authentication
AUTH_ENABLED=true
KEYCLOAK_URL=https://keycloak:8443
KEYCLOAK_REALM=registry
KEYCLOAK_API_CLIENT_ID=registry-api
ROLE_BASED_AUTHZ_ENABLED=true
REGISTRY_AUTH_ROLES_ADMIN=sr-admin
REGISTRY_AUTH_ROLES_DEVELOPER=sr-developer
REGISTRY_AUTH_ROLES_READONLY=sr-readonly

# Registry 3.x authentication
QUARKUS_OIDC_TENANT_ENABLED=true
QUARKUS_OIDC_AUTH_SERVER_URL=https://keycloak:8443/realms/registry
QUARKUS_OIDC_CLIENT_ID=registry-api
APICURIO_AUTH_ROLE-BASED-AUTHORIZATION=true
APICURIO_AUTH_ROLES_ADMIN=sr-admin
APICURIO_AUTH_ROLES_DEVELOPER=sr-developer
APICURIO_AUTH_ROLES_READONLY=sr-readonly

Copy to Clipboard

Toggle word wrap

Important

The QUARKUS_OIDC_AUTH_SERVER_URL property in v3 requires the full realm path (for example, https://keycloak.example.com/realms/registry). In v2, you specified the realm using a separate property.

Configuring API and deletion settings

Apicurio Registry 3.x introduces granular control over deletion operations.

Expand

Registry 2.x property	Registry 3.x property
`REGISTRY_REST_ARTIFACT_DELETION_ENABLED`	`APICURIO_REST_DELETION_ARTIFACT_ENABLED`
Not available	`APICURIO_REST_DELETION_ARTIFACT-VERSION_ENABLED`
Not available	`APICURIO_REST_DELETION_GROUP_ENABLED`
`REGISTRY_UI_FEATURES_READONLY`	`APICURIO_UI_FEATURES_READ-ONLY_ENABLED`
`CORS_ALLOWED_ORIGINS`	`QUARKUS_HTTP_CORS_ORIGINS`

Example migration:

# Registry 2.x API configuration
REGISTRY_REST_ARTIFACT_DELETION_ENABLED=true
REGISTRY_UI_FEATURES_READONLY=false
CORS_ALLOWED_ORIGINS=*

# Registry 3.x API configuration
APICURIO_REST_DELETION_ARTIFACT_ENABLED=true
APICURIO_REST_DELETION_ARTIFACT-VERSION_ENABLED=true
APICURIO_REST_DELETION_GROUP_ENABLED=true
APICURIO_UI_FEATURES_READ-ONLY_ENABLED=false
QUARKUS_HTTP_CORS_ORIGINS=*

# Registry 2.x API configuration
REGISTRY_REST_ARTIFACT_DELETION_ENABLED=true
REGISTRY_UI_FEATURES_READONLY=false
CORS_ALLOWED_ORIGINS=*

# Registry 3.x API configuration
APICURIO_REST_DELETION_ARTIFACT_ENABLED=true
APICURIO_REST_DELETION_ARTIFACT-VERSION_ENABLED=true
APICURIO_REST_DELETION_GROUP_ENABLED=true
APICURIO_UI_FEATURES_READ-ONLY_ENABLED=false
QUARKUS_HTTP_CORS_ORIGINS=*

Copy to Clipboard

Toggle word wrap

Configuring TLS/HTTPS

TLS configuration remains unchanged between v2 and v3 for server-side settings. Use the same properties as shown in the following table.

Expand

Registry 2.x property	Registry 3.x property
`QUARKUS_HTTP_SSL_PORT`	`QUARKUS_HTTP_SSL_PORT` (same)
`QUARKUS_HTTP_SSL_CERTIFICATE_KEY_STORE_FILE`	`QUARKUS_HTTP_SSL_CERTIFICATE_KEY_STORE_FILE` (same)
`QUARKUS_HTTP_SSL_CERTIFICATE_KEY_STORE_PASSWORD`	`QUARKUS_HTTP_SSL_CERTIFICATE_KEY_STORE_PASSWORD` (same)
`QUARKUS_HTTP_INSECURE_REQUESTS`	`QUARKUS_HTTP_INSECURE_REQUESTS` (same)

Example (same for v2 and v3):

# TLS configuration (unchanged)
QUARKUS_HTTP_SSL_PORT=8443
QUARKUS_HTTP_SSL_CERTIFICATE_KEY_STORE_FILE=/certs/registry-keystore.p12
QUARKUS_HTTP_SSL_CERTIFICATE_KEY_STORE_PASSWORD=password123
QUARKUS_HTTP_INSECURE_REQUESTS=disabled

# TLS configuration (unchanged)
QUARKUS_HTTP_SSL_PORT=8443
QUARKUS_HTTP_SSL_CERTIFICATE_KEY_STORE_FILE=/certs/registry-keystore.p12
QUARKUS_HTTP_SSL_CERTIFICATE_KEY_STORE_PASSWORD=password123
QUARKUS_HTTP_INSECURE_REQUESTS=disabled

Copy to Clipboard

Toggle word wrap

Note

TLS configuration is identical for v2 and v3. If the hostname and routes remain the same, reuse the same certificates.

Using the migration checklist

Inventory all configuration files, including deployment manifests, application.properties, and environment variables.
Create a mapping spreadsheet documenting v2 properties and their v3 equivalents.
Update configuration for v3 deployment:
- Storage: Change database name or topic name
- Authentication: Update to full realm URL format
- Properties: Apply apicurio.* namespace
Deploy v3 to staging environment with updated configuration.
Monitor startup logs for configuration errors or warnings.
Test all functionality:
- Storage connectivity
- Authentication and authorization
- API operations (create, read, update, delete)
- UI access
Document any custom or undocumented properties for future reference.

Issue: v3 fails to start with "Storage not configured"

Symptoms: * Registry pod/container fails to start * Logs show: Storage kind not configured

Cause: Missing APICURIO_STORAGE_KIND property.

Solution:

# For SQL storage
APICURIO_STORAGE_KIND=sql
APICURIO_STORAGE_SQL_KIND=postgresql

# For KafkaSQL storage
APICURIO_STORAGE_KIND=kafkasql

# For SQL storage
APICURIO_STORAGE_KIND=sql
APICURIO_STORAGE_SQL_KIND=postgresql

# For KafkaSQL storage
APICURIO_STORAGE_KIND=kafkasql

Copy to Clipboard

Toggle word wrap

Issue: v3 authentication fails with "User is not authenticated"

Symptoms: * All API requests return 401 Unauthorized * Even with valid access token

Cause: Incorrect OAuth2/OIDC configuration, typically missing realm path.

Solution:

Check that QUARKUS_OIDC_AUTH_SERVER_URL includes the full realm path:

# Wrong (v2 style)
QUARKUS_OIDC_AUTH_SERVER_URL=https://keycloak:8443

# Correct (v3 requires realm path)
QUARKUS_OIDC_AUTH_SERVER_URL=https://keycloak:8443/realms/registry

# Wrong (v2 style)
QUARKUS_OIDC_AUTH_SERVER_URL=https://keycloak:8443

# Correct (v3 requires realm path)
QUARKUS_OIDC_AUTH_SERVER_URL=https://keycloak:8443/realms/registry

Copy to Clipboard

Toggle word wrap

Verify Keycloak is accessible from the registry container:

curl -k https://keycloak:8443/realms/registry/.well-known/openid-configuration

curl -k https://keycloak:8443/realms/registry/.well-known/openid-configuration

Copy to Clipboard

Toggle word wrap

Issue: Database connection fails

Symptoms: * Registry fails to start * Logs show JDBC connection errors

Cause: Using old REGISTRY_DATASOURCE_* or QUARKUS_DATASOURCE_* properties.

Solution:

Update to v3 datasource properties:

# Remove these v2 properties
# REGISTRY_DATASOURCE_URL=...
# REGISTRY_DATASOURCE_USERNAME=...

# Use v3 properties
APICURIO_DATASOURCE_URL=jdbc:postgresql://postgres:5432/registry_v3
APICURIO_DATASOURCE_USERNAME=apicurio
APICURIO_DATASOURCE_PASSWORD=password123

# Remove these v2 properties
# REGISTRY_DATASOURCE_URL=...
# REGISTRY_DATASOURCE_USERNAME=...

# Use v3 properties
APICURIO_DATASOURCE_URL=jdbc:postgresql://postgres:5432/registry_v3
APICURIO_DATASOURCE_USERNAME=apicurio
APICURIO_DATASOURCE_PASSWORD=password123

Copy to Clipboard

Toggle word wrap

Issue: CORS errors in browser when accessing UI

Symptoms: * UI loads but API calls fail * Browser console shows CORS errors

Cause: CORS property name changed in v3.

Solution:

# Wrong (v2 property name)
CORS_ALLOWED_ORIGINS=*

# Correct (v3 property name)
QUARKUS_HTTP_CORS_ORIGINS=*

# Wrong (v2 property name)
CORS_ALLOWED_ORIGINS=*

# Correct (v3 property name)
QUARKUS_HTTP_CORS_ORIGINS=*

Copy to Clipboard

Toggle word wrap

Issue: Role-based authorization not working

Symptoms: * Users can access registry but cannot perform admin operations * No 403 Forbidden errors, but operations fail silently

Cause: Role configuration properties not updated to v3 namespace.

Solution:

# Update all role properties
APICURIO_AUTH_ROLE-BASED-AUTHORIZATION=true
APICURIO_AUTH_ROLES_ADMIN=sr-admin
APICURIO_AUTH_ROLES_DEVELOPER=sr-developer
APICURIO_AUTH_ROLES_READONLY=sr-readonly

# Update all role properties
APICURIO_AUTH_ROLE-BASED-AUTHORIZATION=true
APICURIO_AUTH_ROLES_ADMIN=sr-admin
APICURIO_AUTH_ROLES_DEVELOPER=sr-developer
APICURIO_AUTH_ROLES_READONLY=sr-readonly

Copy to Clipboard

Toggle word wrap

Verify user has correct roles in Keycloak and token includes expected roles:

# Decode JWT token to check roles
echo $ACCESS_TOKEN | cut -d. -f2 | base64 -d | jq .realm_access.roles

# Decode JWT token to check roles
echo $ACCESS_TOKEN | cut -d. -f2 | base64 -d | jq .realm_access.roles

Copy to Clipboard

Toggle word wrap

このコンテンツは選択した言語では利用できません。

Chapter 8. Updating Apicurio Registry configuration

8.1. Configuring storage
リンクのコピー

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

多様性を受け入れるオープンソースの強化

会社概要

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

このコンテンツは選択した言語では利用できません。

Chapter 8. Updating Apicurio Registry configuration

8.1. Configuring storageリンクのコピーリンクがクリップボードにコピーされました!

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

多様性を受け入れるオープンソースの強化

会社概要

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

8.1. Configuring storage
リンクのコピー