Red Hat Summit Red Hat Summitサポートコンソール開発者トライアルの開始お問い合わせ

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

Chapter 10. Migration scripts reference

The migration scripts automate key steps in the workflow. All scripts support interactive and automated modes using environment variables, with OAuth2 authentication support.

Understanding migration scripts

The migration scripts are production-ready tools that handle the most critical and error-prone aspects of migration:

  • apicurio-capture-metrics.sh - Captures metrics before/after migration (for comparison)
  • apicurio-export-registry-data.sh - Exports all data from 2.6
  • apicurio-import-registry-data.sh - Imports data into Apicurio Registry 3.x
  • apicurio-verify-registry-version.sh - Verifies registry version and health
  • apicurio-verify-v3-api-features.sh - Tests v3-specific API features

Find all scripts in the Apicurio Registry GitHub repository under docs/scripts/.

Understanding common features

All migration scripts share these common features:

Interactive and automated modes:

  • Interactive mode: Scripts prompt for required inputs with sensible defaults
  • Automated mode: Set environment variables to skip prompts (useful for CI/CD)

OAuth2 authentication support:

  • Client credentials grant type
  • Configurable token endpoint and client credentials
  • Optional: Run without authentication for testing environments

TLS/HTTPS support:

  • Works with trusted certificates by default
  • Option to skip TLS verification for development/testing (SKIP_TLS_VERIFY=true)

Clear output and error handling:

  • Color-coded output (info, success, warning, error)
  • Detailed progress indicators
  • Clear exit codes for automation (0 = success, 1 = failure)

Script: apicurio-capture-metrics.sh

Purpose: Captures metrics from registry before and after migration.

What it captures:

  • Total artifact count
  • Sample of up to 5 artifacts with full metadata
  • Global rule configurations
  • Output saved to text file for post-migration comparison

Usage (interactive): 

./apicurio-capture-metrics.sh
Copy to Clipboard Toggle word wrap

Usage (automated): 

export REGISTRY_URL="https://registry.example.com"
export REGISTRY_API_VERSION="v2"
export AUTH_ENABLED="true"
export AUTH_TOKEN_URL="https://keycloak.example.com/realms/registry/protocol/openid-connect/token"
export AUTH_CLIENT_ID="admin-client"
export AUTH_CLIENT_SECRET="your-secret"
export OUTPUT_FILE="registry-baseline.txt"

./apicurio-capture-metrics.sh
Copy to Clipboard Toggle word wrap

Environment variables:

Expand
VariableDescription

REGISTRY_URL

Registry base URL (for example, https://registry.example.com)

REGISTRY_API_VERSION

API version to use (default: v2)

AUTH_ENABLED

Set to true to enable OAuth2 authentication

AUTH_TOKEN_URL

OAuth2 token endpoint URL

AUTH_CLIENT_ID

OAuth2 client ID

AUTH_CLIENT_SECRET

OAuth2 client secret

OUTPUT_FILE

Output file path (default: registry-baseline.txt)

SKIP_TLS_VERIFY

Set to true to skip TLS certificate verification

Output:

Text file containing artifact summary and global rules (default: registry-baseline.txt).

Script: apicurio-export-registry-data.sh

Purpose: Exports all data from 2.6 deployment to a ZIP file.

What it exports:

  • All artifacts and versions
  • Artifact metadata (labels, properties, descriptions)
  • Global and artifact-specific rules
  • Artifact references

Usage (interactive): 

./apicurio-export-registry-data.sh
Copy to Clipboard Toggle word wrap

Usage (automated): 

export REGISTRY_URL="https://registry-v2.example.com"
export REGISTRY_API_VERSION="v2"
export AUTH_ENABLED="true"
export AUTH_TOKEN_URL="https://keycloak.example.com/realms/registry/protocol/openid-connect/token"
export AUTH_CLIENT_ID="admin-client"
export AUTH_CLIENT_SECRET="your-secret"
export EXPORT_FILE="registry-export.zip"

./apicurio-export-registry-data.sh
Copy to Clipboard Toggle word wrap

Environment variables:

Expand
VariableDescription

REGISTRY_URL

Registry base URL (for example, https://registry-v2.example.com)

REGISTRY_API_VERSION

API version to use (default: v2)

AUTH_ENABLED

Set to true to enable OAuth2 authentication

AUTH_TOKEN_URL

OAuth2 token endpoint URL

AUTH_CLIENT_ID

OAuth2 client ID

AUTH_CLIENT_SECRET

OAuth2 client secret

EXPORT_FILE

Export file path (default: registry-export.zip)

SKIP_TLS_VERIFY

Set to true to skip TLS certificate verification

Output:

ZIP file containing complete registry export (default: registry-export.zip).

Important notes:

  • Run this script while the registry is in read-only mode to maintain data consistency
  • The export file size varies depending on registry size

Script: apicurio-import-registry-data.sh

Purpose: Imports data from a v2 export file into Apicurio Registry 3.x deployment.

What it does:

  • Validates the import ZIP file
  • Checks Apicurio Registry 3.x accessibility and version
  • Imports all data from the export file
  • Verifies artifact count after import
  • Reports global rules configuration

Usage (interactive): 

./apicurio-import-registry-data.sh
Copy to Clipboard Toggle word wrap

Usage (automated): 

export REGISTRY_URL="https://registry-v3.example.com"
export REGISTRY_API_VERSION="v3"
export AUTH_ENABLED="true"
export AUTH_TOKEN_URL="https://keycloak.example.com/realms/registry/protocol/openid-connect/token"
export AUTH_CLIENT_ID="admin-client"
export AUTH_CLIENT_SECRET="your-secret"
export IMPORT_FILE="registry-export.zip"

./apicurio-import-registry-data.sh
Copy to Clipboard Toggle word wrap

Environment variables:

Expand
VariableDescription

REGISTRY_URL

Registry base URL (for example, https://registry-v3.example.com)

REGISTRY_API_VERSION

API version to use (default: v3)

AUTH_ENABLED

Set to true to enable OAuth2 authentication

AUTH_TOKEN_URL

OAuth2 token endpoint URL

AUTH_CLIENT_ID

OAuth2 client ID

AUTH_CLIENT_SECRET

OAuth2 client secret

IMPORT_FILE

Import file path (default: registry-export.zip)

SKIP_TLS_VERIFY

Set to true to skip TLS certificate verification

Important notes:

  • Import adds to existing data (does not replace)
  • Script warns if registry already contains artifacts
  • Import into an empty v3 registry for best results

Script: apicurio-verify-registry-version.sh

Purpose: Verifies the version and health of a Apicurio Registry deployment.

What it checks:

  • Health endpoint (200 OK)
  • System information retrieval
  • Version verification (2.x or 3.x)

Usage (interactive): 

./apicurio-verify-registry-version.sh
Copy to Clipboard Toggle word wrap

Usage (automated): 

export REGISTRY_URL="https://registry.example.com"
export REGISTRY_VERSION="v3"
export AUTH_ENABLED="true"
export AUTH_TOKEN_URL="https://keycloak.example.com/realms/registry/protocol/openid-connect/token"
export AUTH_CLIENT_ID="admin-client"
export AUTH_CLIENT_SECRET="your-secret"

./apicurio-verify-registry-version.sh
Copy to Clipboard Toggle word wrap

Environment variables:

Expand
VariableDescription

REGISTRY_URL

Registry base URL (for example, https://registry.example.com)

REGISTRY_VERSION

Registry version to test (default: v3)

AUTH_ENABLED

Set to true to enable OAuth2 authentication

AUTH_TOKEN_URL

OAuth2 token endpoint URL

AUTH_CLIENT_ID

OAuth2 client ID

AUTH_CLIENT_SECRET

OAuth2 client secret

SKIP_TLS_VERIFY

Set to true to skip TLS certificate verification

Exit codes:

  • 0 - All checks passed
  • 1 - One or more checks failed

Script: apicurio-verify-v3-api-features.sh

Purpose: Verifies that v3-specific API features are available and functioning correctly.

What it tests:

  • v3 system endpoints (/system/info, /system/limits)
  • v3 search endpoints (/search/groups, /search/versions)
  • Admin endpoints

Usage (interactive): 

./apicurio-verify-v3-api-features.sh
Copy to Clipboard Toggle word wrap

Usage (automated): 

export REGISTRY_URL="https://registry-v3.example.com"
export AUTH_ENABLED="true"
export AUTH_TOKEN_URL="https://keycloak.example.com/realms/registry/protocol/openid-connect/token"
export AUTH_CLIENT_ID="admin-client"
export AUTH_CLIENT_SECRET="your-secret"

./apicurio-verify-v3-api-features.sh
Copy to Clipboard Toggle word wrap

Environment variables:

Expand
VariableDescription

REGISTRY_URL

Registry base URL (for example, https://registry-v3.example.com)

AUTH_ENABLED

Set to true to enable OAuth2 authentication

AUTH_TOKEN_URL

OAuth2 token endpoint URL

AUTH_CLIENT_ID

OAuth2 client ID

AUTH_CLIENT_SECRET

OAuth2 client secret

SKIP_TLS_VERIFY

Set to true to skip TLS certificate verification

Exit codes:

  • 0 - All feature tests passed
  • 1 - One or more feature tests failed

Configuring authentication

All scripts support OAuth2 authentication using client credentials grant type.

Interactive mode (prompts):

If environment variables are not set, scripts prompt for:

  • Auth token endpoint URL
  • Client ID
  • Client secret (hidden input)

Automated mode (environment variables):

For automation, set these environment variables: 

export AUTH_ENABLED="true"
export AUTH_TOKEN_URL="https://keycloak.example.com/realms/registry/protocol/openid-connect/token"
export AUTH_CLIENT_ID="admin-client"
export AUTH_CLIENT_SECRET="your-secret"
Copy to Clipboard Toggle word wrap

Unauthenticated deployments:

If your Apicurio Registry does not use authentication: 

export AUTH_ENABLED="false"
Copy to Clipboard Toggle word wrap

Alternatively, press Enter when prompted for authentication.

Configuring TLS/HTTPS support

Production (trusted certificates):

The scripts use trusted certificates by default. To configure this explicitly: 

export SKIP_TLS_VERIFY="false"
Copy to Clipboard Toggle word wrap

Development (self-signed certificates):

For testing with self-signed certificates: 

export SKIP_TLS_VERIFY="true"
Copy to Clipboard Toggle word wrap
Warning

Use SKIP_TLS_VERIFY=true only in non-production environments.

Troubleshooting scripts

Issue: "Failed to obtain access token"

Solution:

  • Verify AUTH_TOKEN_URL is correct.
  • Check that client credentials are valid.
  • Confirm the client has appropriate roles (for example, sr-admin).
  • Test manually with curl.

Issue: "Registry is not accessible"

Solution:

  • Verify REGISTRY_URL is correct.
  • Check network connectivity.
  • Confirm the registry is running and healthy.
  • Verify firewall and security group rules.

Issue: "Export file is too small"

Solution:

  • Check that authentication is working.
  • Verify admin permissions.
  • Review registry logs for errors.
  • Confirm the export endpoint is accessible.

Issue: "Import failed"

Solution:

  • Verify the export file is a valid ZIP: unzip -t registry-export.zip
  • Check that registry v3 has sufficient storage.
  • Review registry v3 logs for errors.
  • Confirm registry v3 is healthy before import.

Issue: "Artifact count mismatch"

Solution:

  • Wait a few seconds after import (processing delay).
  • Check import logs for errors.
  • Verify export file integrity.
  • Consider re-exporting and re-importing.

10.1. Installing dependencies
リンクのコピー

All scripts require:

  • bash (version 4.0+)
  • curl
  • jq (for JSON parsing)
  • unzip (optional, for ZIP validation)
Red Hat logoGithubredditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

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

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。 最新の更新を見る.

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

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

Theme

© 2026 Red Hatトップに戻る