Streaming

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.

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 Redpanda Authorization Mechanisms.

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 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 Redpanda Authorization Mechanisms.

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 Redpanda Authorization Mechanisms.
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

In Console 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.

If you do not use impersonation, you can continue to use role bindings to control access within Redpanda Console. Each role binding maps users to roles in Redpanda Console using their login type and identity.

Here is an example of how to migrate role bindings from a separate file to the main configuration:

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

Migrate 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 Console roles (viewer, editor, admin) to Redpanda ACLs.

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:

Schema Registry migration

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

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

Serde and Kafka Connect migration

In v3, all serialization settings are consolidated under the serde stanza. The connect configuration has been renamed to kafkaConnect, and the console.maxDeserializationPayloadSize setting is now part of the serde configuration.

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.

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