Migrate to Redpanda Console v3.0.0

This guide provides step-by-step instructions for migrating from Redpanda Console v2.x.x (v2) to v3.0.x (v3). The new release introduces user impersonation to unify authentication and authorization between Redpanda Console and Redpanda, along with several breaking changes. This guide explains these changes and provides examples to help you update your configuration.

For details on the new authentication and authorization system, see Authentication in Redpanda Console. For a list of breaking changes, see What’s New in Redpanda.

Use the migration tool to convert your v2 configuration to v3 format.

Choose your migration path

Your migration approach depends on how you deploy Redpanda Console.

Kubernetes with Redpanda Operator

The operator automatically migrates most v2 configurations when you upgrade. Review the Automatic migration in Kubernetes section to understand what’s handled automatically and what requires manual intervention.

Other deployment methods

Manually migrate your configuration using this guide and the migration tool. Start with Authentication and authorization migration.

Pre-migration checklist

Review your v2 configuration and check which of these breaking changes apply to you:

Authentication decision

You must decide on your v3 authentication strategy before migrating.

Use this option when you want each user’s Console session to use their own Redpanda credentials.

Console role bindings are ignored. Authorization happens in Redpanda with ACLs. Users must be provisioned in Redpanda.

Static credentials

Use this option when you want Console to use a shared service account to access Redpanda.

Console role bindings still apply. One set of credentials is used for all backend API calls.

For most deployments, user impersonation provides better security and auditability.

Track your migration progress

Use this checklist to track your migration:

Automatic migration in Kubernetes

When you deploy Redpanda Console v3 using the Redpanda Operator, the operator automatically attempts to migrate your v2 configuration from the Redpanda custom resource’s console stanza to the new Console custom resource. The migration process handles as many configuration mappings as possible, but some features require manual intervention.

The automatic migration only applies when transitioning from the Redpanda CRD’s console stanza to the Console CRD. If you directly configure the Console CRD yourself, no automatic migration or normalization is performed.

Migration workflow

When you upgrade to Console v3 with the Redpanda Operator:

  1. The operator attempts automatic migration using the mappings described in Supported configuration mappings

  2. Warnings are generated for unsupported configurations and added to the Console custom resource

  3. You review the warnings and manually configure unsupported features

  4. You validate that authentication and authorization work as expected

Check for migration warnings

Before reviewing the migration details, check if your Console custom resource has warnings:

kubectl get console <console-name> -n <namespace> -o jsonpath='{.spec.warnings}'

If you see warnings, they indicate configurations that need your attention. Common warnings and their solutions are documented in Unsupported features.

If you don’t see warnings, review the Supported configuration mappings to verify the automatic migration matches your expectations, especially around authentication strategy (impersonation vs static credentials).

Supported configuration mappings

The operator automatically migrates the following configuration fields:

Table 1. Authentication settings
v2 Configuration v3 Configuration Notes

login.jwtSecret

authentication.jwtSigningKey

Direct mapping

login.useSecureCookies

authentication.useSecureCookies

Direct mapping

login.plain

authentication.basic

Direct mapping

login.[provider]

authentication.oidc

Only one provider is selected if multiple are configured. See Unsupported features.
Table 2. Schema Registry settings
v2 Configuration v3 Configuration Notes

kafka.schemaRegistry.username

schemaRegistry.authentication.basic.username

Moved to top-level schemaRegistry stanza

kafka.schemaRegistry.password

schemaRegistry.authentication.basic.password

Moved to top-level schemaRegistry stanza

kafka.schemaRegistry.bearerToken

schemaRegistry.authentication.bearerToken

Moved to top-level schemaRegistry stanza

kafka.schemaRegistry.*

schemaRegistry.*

impersonateUser automatically set to true when credentials are absent

kafka.schemaRegistry.* (other settings)

schemaRegistry.*

All remaining Schema Registry configuration migrated to top level
Table 3. Kafka and serialization settings
v2 Configuration v3 Configuration Notes

kafka.protobuf

serde.protobuf

Moved to dedicated serde stanza

kafka.cbor

serde.cbor

Moved to dedicated serde stanza

kafka.messagePack

serde.messagePack

Moved to dedicated serde stanza

console.maxDeserializationPayloadSize

serde.maxDeserializationPayloadSize

Moved to serde stanza

N/A

kafka.sasl.enabled and kafka.sasl.impersonateUser

Both set to true by default in v3
Table 4. Other mappings
v2 Configuration v3 Configuration Notes

connect

kafkaConnect

Renamed

redpanda.adminApi credentials

redpanda.adminApi.authentication.basic.*

Converted to structured authentication

Role bindings (user subjects)

authorization.roleBindings

Only user subjects are migrated. Group subjects are removed with warnings.

Unsupported features

The following v2 features are not supported in v3 and cannot be automatically migrated. The operator generates warnings when it encounters these configurations.

Multiple OIDC providers

What changed Impact Action required

V2 allowed multiple OIDC providers (Google, GitHub, Keycloak, Okta, generic OIDC). V3 supports only one.

Operator selects one provider; others are discarded

Review selected provider in warnings. If you need additional authentication methods, configure them separately.
Example warning
Elected 'github' as OIDC provider out of [github, google, keycloak, oidc]. Only one provider is supported in v3.

OIDC groups and realms

Breaking change with significant migration effort required.

What changed Impact Action required

OIDC-based group authorization removed. realm and directory fields removed from OIDC provider configurations.

Group-based access control no longer works

Map OIDC groups to Redpanda RBAC roles. Provision users in Redpanda with appropriate ACLs. See [migrate-redpanda-console-roles-to-redpanda-acls].
Example warnings
Removed 'realm' from 'oidc'. OIDC groups are not supported in v3. Create Roles in Redpanda instead.

Removed 'directory' from 'oidc'. OIDC groups are not supported in v3. Create Roles in Redpanda instead.

Group-based role bindings

What changed Impact Action required

V2 role bindings could include group subjects. V3 only supports user subjects.

Group subjects are removed from role bindings during migration

If using impersonation: Provision individual users with ACLs in Redpanda. If using static credentials: Create individual user role bindings.
Example warning
Removed group subject from role binding 'viewer'. Groups are not supported in v3.

Manual configuration steps

After the operator completes automatic migration, review any warnings and complete the manual configuration steps:

  1. Check for warnings:

    kubectl get console <console-name> -n <namespace> -o jsonpath='{.spec.warnings}'

  2. Review each warning against the Unsupported features section above

  3. Complete the required actions for each unsupported feature

  4. Update your Console custom resource with any manual configuration changes

  5. Validate the migration using the steps in Validate migration

For details on the warnings field structure, see ConsoleSpec.

Authentication and authorization migration

In v2, authentication and authorization was handled by the Redpanda Console. In v3, Redpanda Console uses the same authentication and authorization system as Redpanda. This change unifies the authentication and authorization model across Redpanda and Redpanda Console, enabling a more consistent and secure experience.

Migrate from the plain login provider

In v3, the plain login provider has been removed. Instead, you can either enable user impersonation or use static credentials for authentication. User impersonation forwards the credentials from the logged-in user to the APIs that have user impersonation enabled. With static credentials, the credentials specified in the configuration are used to authenticate with the APIs. For more information, see Authentication in Redpanda Console.

Here is an example of how to migrate from the plain login provider to user impersonation:

V2 plain login with RBAC
login:
  enabled: true
  jwtSecret: "secret-key"
  useSecureCookies: false
  plain:
    enabled: true
    credentials:
      - username: "jane"
        password: "some-other-secret-password"
      - username: "john"
        password: "some-secret-password"
enterprise:
  rbac:
    enabled: true
    roleBindingsFilepath: /tmp/role-bindings.yml
V3 user impersonation
kafka:
  sasl:
    enabled: true
    impersonateUser: true (1)
redpanda:
  adminApi:
    authentication:
      impersonateUser: true
schemaRegistry:
  enabled: true
  authentication:
    impersonateUser: true
authentication:  (2)
  jwtSigningKey: "secret-key"
  useSecureCookies: false
  basic:
    enabled: true  (3)
1 When using user impersonation, the credentials from the logged-in user are forwarded to this API. As a result, any static role-binding settings are ignored for impersonated API calls. Ensure your users are provisioned as SASL/SCRAM users in Redpanda. See Configure Authentication.
2 The authentication stanza replaces the login stanza in v3. Use this stanza to configure authentication settings.
3 The basic block enables basic authentication for Redpanda Console.

Role bindings in Redpanda Console are ignored with user impersonation. Instead, the credentials from the logged-in user are forwarded to the Redpanda APIs that have user impersonation enabled. Ensure that your logged-in users have the necessary ACLs in Redpanda. See Configure Authorization.

If you prefer to disable user impersonation so that static credentials are used instead, modify your configuration as follows:

V3 static credentials
kafka:
  sasl:
    enabled: true
    impersonateUser: false (1)
    username: "jane" (2)
    password: "some-other-secret-password"
    mechanism: SCRAM-SHA-256
schemaRegistry:
  enabled: true
  authentication:
    impersonateUser: false
    basic:
      username: "jane"
      password: "some-other-secret-password"
    #bearerToken: "example-bearer-token" # For OAuth2 bearer token
redpanda:
  adminApi:
    authentication:
      impersonateUser: false
      basic:
        username: "jane"
        password: "some-other-secret-password"
      #bearerToken: "example-bearer-token" # For OAuth2 bearer token
authentication:
  jwtSigningKey: "secret-key"
  useSecureCookies: false
  basic:
    enabled: true
# With static credentials, the role bindings still apply to control Redpanda Console access.
authorization: (3)
  roleBindings:
    - roleName: admin
      users:
        - loginType: basic
          name: "jane"
1 Set impersonateUser to false to disable user impersonation.
2 Specify the username, password, and mechanism for the static credentials.
3 Role bindings are applied when using static credentials.

When impersonation is disabled, the static credentials specified in the kafka.sasl block are used to authenticate with the Kafka API when you log into Redpanda Console. Ensure that these credentials have the necessary ACLs in Redpanda. See Configure Authorization.

Migrate from OIDC providers

In v2, Redpanda Console supported separate configuration for OIDC providers such as Google, GitHub, and Keycloak. In v3, the OIDC configuration has been simplified, and the login stanza has been replaced by the authentication stanza. For more information, see Authentication in Redpanda Console.

OIDC-based group authorization is no longer available in Redpanda Console. With the move to unified authentication, RBAC is now managed directly in Redpanda, which does not support OIDC groups. If you previously relied on OIDC groups to manage access, you must now transition to the RBAC model. Redpanda Data recommends mapping your existing group-based permissions to RBAC roles that reflect the same access levels. This change provides a more unified and fine-grained authorization approach.

Here is an example of how to migrate from Google OIDC in v2 to v3:

V2 Google OIDC
login:
  enabled: true
  jwtSecret: "old-google-secret"
  google:
    enabled: true
    clientId: "google-client-id-v2"
    clientSecret: "google-client-secret-v2"
    issuerUrl: "https://accounts.google.com"
    # issuerTls, displayName, and userIdentifyingClaimKey may be present in v2 but are omitted here for brevity.
V3 Google OIDC
kafka:
  sasl:
    enabled: true
    impersonateUser: true (1)
authentication: (2)
  jwtSigningKey: "old-google-secret"
  useSecureCookies: true
  oidc: (3)
    enabled: true
    issuerUrl: "https://accounts.google.com"
    clientId: "google-client-id-v2"
    clientSecret: "google-client-secret-v2"
1 When using user impersonation, the credentials from the logged-in user are forwarded to the Kafka API. As a result, any static role-binding settings are ignored for impersonated API calls. Ensure your Redpanda cluster has SASL/OAUTHBEARER authentication enabled. See Configure Authorization.
2 The authentication stanza replaces the login stanza in v3. Use this stanza to configure authentication settings.
3 The oidc block enables OIDC authentication for Redpanda Console. See Authentication in Redpanda Console.

Redpanda requires a JWT-encoded access token for authentication. While most identity providers issue JWTs, some (like Google) follow the OAuth spec and issue opaque tokens instead. Since Redpanda relies on JWTs to introspect the audience and subject, providers that do not support JWT access tokens cannot be used for authentication.

Role bindings migration

In v3, role bindings continue to control access to Redpanda Console when using static credentials. However, with user impersonation enabled, role bindings are ignored, and authorization is handled directly by Redpanda using ACLs.

Authentication strategy Role bindings behavior

User impersonation

Role bindings are ignored. Authorization is handled by Redpanda ACLs.

Static credentials

Role bindings apply to control Console access.

Configuration location change

In v2, role bindings could be configured in a separate file. In v3, role bindings are configured directly in the authorization.roleBindings stanza of the main configuration file.

V2 role bindings
enterprise:
  rbac:
    enabled: true
    roleBindingsFilepath: "/path/to/roleBindings.yaml"
# v2: Role bindings configured in a separate file.
roleBindings:
  - roleName: admin
    metadata:
      name: Developers
      creator: John Doe
    subjects:
      - kind: user
        provider: Plain
        name: alice
V3 role bindings
authorization:
  roleBindings:
    - roleName: admin
      users:
        - loginType: basic
          name: alice

Group subject removal

Breaking change: V2 role bindings could reference group subjects (from OIDC providers). V3 only supports user subjects.

If you use OIDC groups for authorization, you must migrate to Redpanda ACLs.

During automatic migration in Kubernetes, group subjects are removed and warnings are generated. See Group-based role bindings.

Migrate Redpanda Console roles to Redpanda ACLs

If you are using impersonation in v3, roleBindings are ignored. Instead, access is controlled by Redpanda using ACLs and RBAC.

You must provision your users in Redpanda and grant them the appropriate permissions.

The following examples show how to map Redpanda Console roles (viewer, editor, admin) to Redpanda ACLs.

Redpanda Console Role Equivalent ACLs in Redpanda

Viewer

read, describe on topics and groups

Editor

read, write, describe on topics and describe on groups

Admin

All of the above, plus add the user as a superuser principal using the cluster configuration

 
# Viewer role in Redpanda Console -> Redpanda ACLs
rpk security acl create \
  --allow-principal User:alice@example.com \
  --operation read,describe \
  --topic '*' \
  --group '*'

# Editor role in Redpanda Console -> Redpanda ACLs
rpk security acl create \
  --allow-principal User:alice@example.com \
  --operation read,write,describe \
  --topic '*'

rpk security acl create \
  --allow-principal User:alice@example.com \
  --operation describe \
  --group '*'

# Admin role in Redpanda Console -> Redpanda superuser
rpk cluster config set superusers "['alice@example.com']"

For details, see:

Configuration structure changes

V3 reorganizes several configuration sections to create a clearer structure. This section covers the changes to Schema Registry, serialization settings, and Kafka Connect.

Schema Registry moves to top level

In v2, the Schema Registry configuration was nested under the kafka stanza. In v3, this configuration is now a top-level stanza with structured authentication.

V2 Schema Registry
kafka:
  brokers:
    - "broker-0.mycompany.com:19092"
  schemaRegistry:
    enabled: true
    urls:
      - "http://schema-registry.mycompany.com:8081"
    # Basic authentication:
    username: "example-user"
    password: "example-password"
    # Bearer token:
    bearerToken: "example-bearer-token"
    # TLS configuration:
    tls:
      enabled: false
      caFilepath: "/path/to/ca-cert.pem"
      certFilepath: "/path/to/client-cert.pem"
      keyFilepath: "/path/to/client-key.pem"
      insecureSkipTlsVerify: false
V3 Schema Registry
schemaRegistry:
  enabled: true
  urls:
    - "http://schema-registry.mycompany.com:8081"
  authentication:
    impersonateUser: false
    basic:
      username: "example-user"
      password: "example-password"
    bearerToken: "example-bearer-token"
  tls:
    enabled: false
    caFilepath: "/path/to/ca-cert.pem"
    certFilepath: "/path/to/client-cert.pem"
    keyFilepath: "/path/to/client-key.pem"
    insecureSkipTlsVerify: false

Serialization consolidated under serde

In v3, all serialization settings are consolidated under the serde stanza. The console.maxDeserializationPayloadSize setting moves to the serde configuration.

Kafka Connect renamed to kafkaConnect

The connect configuration stanza is renamed to kafkaConnect for clarity.

V2 serde and Kafka Connect
kafka:
  protobuf:
    enabled: false
    mappings: []
  cbor:
    enabled: false
  messagePack:
    enabled: false
console:
  maxDeserializationPayloadSize: 20480
connect:
  enabled: false
  clusters: []
V3 serde and Kafka Connect
serde:
  maxDeserializationPayloadSize: 20480
  protobuf:
    enabled: false
    mappings: []
  cbor:
    enabled: false
  messagePack:
    enabled: false
kafkaConnect:
  enabled: false
  clusters: []

Validate migration

After updating your configuration, verify that:

  • Users can log in using the new authentication settings.

  • API calls to Kafka, Schema Registry, and the Admin API are authenticated correctly.

Check migration warnings in Kubernetes

If you’re deploying Redpanda Console using the Redpanda Operator, the Console custom resource includes a warnings field that reports any v2 configuration settings that could not be automatically migrated to v3.

To check for migration warnings:

kubectl get console <console-name> -n <namespace> -o jsonpath='{.spec.warnings}'

If warnings are present, they describe which fields from your v2 configuration require manual intervention. Review these warnings and update your Console configuration accordingly. For a comprehensive list of automatically migrated configurations and unsupported features that generate warnings, see Automatic migration in Kubernetes. For details on the warnings field, see ConsoleSpec.

Troubleshooting

Users cannot log in after migration

If users are unable to log in after migration, review the following common causes and solutions.

Users not provisioned in Redpanda

When using impersonation, users must exist in Redpanda as SASL/SCRAM users.

To create a user in Redpanda, use the following command:

rpk security user create alice -p <password>

For more information, see Configure Authentication.

OIDC provider mismatch

If you had multiple OIDC providers in v2, only one was selected during migration.

Check which provider was selected:

kubectl get console <name> -o jsonpath='{.spec.warnings}'

Review the warning message and ensure your users are authenticating with the selected provider.

JWT token requirement not met

Some identity providers (like Google) issue opaque tokens instead of JWT tokens. Redpanda requires JWT-encoded access tokens.

To resolve this, use an identity provider that issues JWT access tokens, or configure your provider to issue JWTs. See Migrate from OIDC providers for details.

Users can log in but cannot access resources

If users can log in but cannot access topics, consumer groups, or Schema Registry, review the following common causes and solutions.

Missing ACLs with user impersonation

When using user impersonation, user credentials are forwarded to Redpanda. Users must have appropriate ACLs configured in Redpanda.

To check and create ACLs:

# Check existing ACLs for user
rpk security acl list --principal User:alice

# Grant read access to topics
rpk security acl create \
  --allow-principal User:alice \
  --operation read,describe \
  --topic '*'

# Grant access to consumer groups
rpk security acl create \
  --allow-principal User:alice \
  --operation read,describe \
  --group '*'

For more information on mapping Console roles to Redpanda ACLs, see [migrate-redpanda-console-roles-to-redpanda-acls].

Role bindings not migrated correctly

When using static credentials, verify that role bindings are correctly configured in the authorization.roleBindings stanza.

To resolve this, review your v3 configuration and ensure role bindings match your v2 configuration. See Role bindings migration.

Schema Registry or Kafka Connect not working

If Schema Registry or Kafka Connect API calls fail after migration, review the following common causes and solutions.

Configuration location changed

Schema Registry and Kafka Connect configuration moved to different locations in v3.

To resolve this, verify that:

  • Schema Registry configuration is at the top level under schemaRegistry, not under kafka.schemaRegistry

  • Kafka Connect configuration is under kafkaConnect, not connect

  • Authentication is configured under schemaRegistry.authentication with the new structure

See Configuration structure changes for examples.

Impersonation settings incorrect

If impersonation is enabled but not configured correctly, API calls may fail.

To resolve this, ensure impersonateUser settings match your authentication strategy:

  • For user impersonation: Set schemaRegistry.authentication.impersonateUser: true

  • For static credentials: Set impersonateUser: false and configure static credentials

Migration warnings persist after manual fixes (Kubernetes)

Warnings in the Console CR are informational and indicate what was changed during migration. They do not automatically clear after you resolve the issues. You can safely ignore warnings once you’ve addressed the underlying configuration problems and validated that Console works correctly.

Redpanda Console migration tool

This migration tool attempts to convert your Redpanda Console configuration from v2 to v3 format. The tool is provided as a convenience and may not cover all migration scenarios. Always review the output to ensure that your configuration is correct.

To use the tool, paste your v2 YAML configuration into the text box and click Migrate to generate the updated configuration. To test the tool, click Load sample to load a sample configuration.

If you have a separate file for role bindings, paste the contents into the text box along with the main configuration. In v3, role bindings are configured directly in the main configuration file. The tool attempts to convert your role bindings into the new format and adds them to the main configuration file in the output.

Review the output before deploying the new configuration. If you encounter any issues, refer to the examples in this guide to manually update your configuration.

Suggested reading