How to Roll Back the Apicurio v3 Upgrade

This guide shows you how to point the production hostname back at Apicurio Registry v2, lift the v2 registration freeze and check that v2 serves production again after a failed switch to v3.

Type

How-to guide

Goal

Serve production schema traffic from Apicurio Registry v2 again, with schema registration open.

Audience

Platform Operator with Helm access to the Axual Streaming release in the kafka namespace.

When to use

Use this guide when v3 misbehaves after the ingress switch in How to Migrate Schemas to Apicurio v3, and before How to Remove Apicurio v2.

Contents

The sections below cover each task in this guide:

Prerequisites

Confirm the following before you begin.

Access and permissions required

You need Helm access to the Axual Streaming release in the kafka namespace, and the client secret of the platform’s apicurio-api Keycloak client for the verification.

Tools and versions required

You need the following tools:

  • helm

  • curl and jq

Resources that must exist before starting

The following resources must already exist before you start:

  • Apicurio v2 still enabled and reachable on its legacy hostname. Once v2 is disabled, there is nothing to roll back to.

Schemas registered in v3 after the switch aren’t present in v2. Rollback loses them, so list them before you start and re-add them to v2 afterwards. Moving data from v3 back to v2 isn’t supported.
Replace every <VALUE> placeholder and every example.com hostname with your actual value before running a command. [same as configured for your apicurio-registry] means copy the value from the matching key of your existing apicurio-registry block.

Step 1: Point the production hostname back at v2

Disable the v3 ingresses and give the production hostname back to v2. Revert the v2 webRedirectUrl, ingress host and tls.hosts you moved to the legacy hostname, so the v2 UI redirect and certificate match the production hostname again:

axual-streaming:
  apicurio-registry-v3:
    ingress:
      backend:
        enabled: false
      ui:
        enabled: false

  apicurio-registry:
    security:
      authentication:
        keycloak:
          webRedirectUrl: "https://apicurio.example.com"
    ingress:
      hosts:
        - host: "apicurio.example.com"
      tls:
        - secretName: [same as configured for your apicurio-registry]
          hosts:
            - "apicurio.example.com"

If you moved the Auth Proxy ingresses, move the v2 Auth Proxy ingress back to the production auth-proxy hostname and disable the v3 one in the same way.

Step 2: Lift the registration freeze in v2

Undo the freeze from Step 2: Block schema registration in v2, so v2 accepts schema registrations again:

  • Remove the REGISTRY_AUTH_ROLES_DEVELOPER and REGISTRY_AUTH_ROLES_ADMIN remaps and REGISTRY_AUTH_AUTHENTICATED_READS_ENABLED from apicurio-registry.env.

  • Remove the registry.auth.admin-override.enabled: "false" line from apicurio-registry.config to restore the chart default.

Step 3: Apply and verify the rollback

Apply both changes with a Helm upgrade of the Streaming release:

helm upgrade --install streaming oci://registry.axual.io/axual-charts/axual-streaming --version=2.0.0 -n kafka -f values.yaml

Then check that the production hostname reaches v2 again. v2 doesn’t serve the /apis/registry/v3 path, so the first request fails once the rollback is in effect, while the /apis/registry/v2 path keeps answering:

TOKEN=$(curl -skS --fail-with-body -X POST \
  "https://<APICURIO_KEYCLOAK_HOST>/auth/realms/<APICURIO_REALM>/protocol/openid-connect/token" \
  -d "grant_type=client_credentials&client_id=apicurio-api&client_secret=<APICURIO_API_CLIENT_SECRET>" \
  | jq -r '.access_token')

# Prints a 4xx status code: the v3 API is no longer reachable on the production hostname.
curl -sk -o /dev/null -w '%{http_code}\n' \
  "https://apicurio.example.com/apis/registry/v3/search/artifacts?limit=1" \
  -H "Authorization: Bearer $TOKEN"

# Prints the v2 artifact count.
curl -skS --fail-with-body \
  "https://apicurio.example.com/apis/registry/v2/search/artifacts?limit=1" \
  -H "Authorization: Bearer $TOKEN" | jq '.count'

Re-add any schemas that were registered in v3 after the switch. To try the upgrade again later, empty v3 first with Restore the Apicurio v3 topics.