Configure a Connection to a Redpanda Cluster

Redpanda Console connects to your Redpanda cluster using dedicated configuration blocks for the Kafka API, Schema Registry API, and Admin API. Each connection serves a different purpose:

  • Kafka API: Enables core messaging operations and authenticates requests to your Kafka cluster.

  • Schema Registry API: Allows Redpanda Console to manage and display schema information.

  • Admin API: Unlocks management features such as viewing cluster details, managing users, and generating debug bundles.

To ensure secure and reliable communication, each connection must be configured with the appropriate authentication, TLS, and startup settings. The authentication mechanism you configure in Redpanda Console must match the one set up in your Redpanda cluster, ensuring that the user’s credentials are properly verified.

This guide provides detailed instructions and examples for configuring each of these connections.

Prerequisites

Ensure that you have:

  • Access to your Redpanda cluster’s broker URLs.

  • The necessary configuration details if your cluster requires authentication, TLS, or other security measures.

Configure a connection to the Kafka API

Redpanda Console must be configured to communicate with the Kafka API on your Redpanda brokers. This configuration involves specifying the broker endpoints and, if needed, configuring client identification, SASL, and TLS settings.

Here is an example configuration for the Kafka API using OAuth for SASL authentication:

kafka:
  brokers:
    - "broker1.example.com:9092"
    - "broker2.example.com:9092"
  # Optional client identification:
  # clientId: "console"
  # rackId: "zone-a"

  sasl:
    enabled: true
    mechanism: OAUTHBEARER
    impersonateUser: false
    oauth:
      # token: "example-oauth-token" (for static token)
      clientId: "example-client-id"
      clientSecret: "example-client-secret"
      tokenEndpoint: "https://accounts.google.com/token"
      scope: "openid"

  startup:
    establishConnectionEagerly: true   # Test the connection at startup.
    maxRetries: 5                      # Maximum number of retry attempts.
    retryInterval: 1s                  # Initial wait time between retries.
    maxRetryInterval: 60s              # Maximum wait time between retries.
    backoffMultiplier: 2               # Multiplier for increasing retry intervals.

  # TLS configuration (only needed if self-signed certificates or mTLS are used):
  # tls:
    # enabled: true
    # caFilepath: "/path/to/ca-cert.pem"
    # certFilepath: "/path/to/client-cert.pem"
    # keyFilepath: "/path/to/client-key.pem"
    # insecureSkipTlsVerify: false

For clusters using Kerberos, the configuration may resemble the following:

kafka:
  brokers:
    - "broker1.example.com:9092"
  sasl:
    enabled: true
    mechanism: GSSAPI
    impersonateUser: false  # Must be false when using Kerberos with Redpanda Console
    gssapi:
      authType: KEYTAB_AUTH
      keyTabPath: "/path/to/keytab"
      kerberosConfigPath: "/path/to/krb5.conf"
      serviceName: "kafka"
      username: "example-user"
      password: "example-password"
      realm: "EXAMPLE.REALM"
      enableFast: true
Because Redpanda Console supports only OIDC and basic authentication for its own login authentication, Kerberos (GSSAPI) configurations cannot be used with user impersonation enabled. Ensure impersonateUser is set to false when using Kerberos.
Kafka API Configuration Option Description

brokers

A list of broker endpoints in the format <hostname>:<port>. For high availability, include all broker URLs.

clientId (optional)

An identifier used by Redpanda Console to identify itself to the cluster.

rackId (optional)

Specifies the rack for multi-zone clusters to optimize local message consumption.

sasl (optional)

Contains settings for SASL-based authentication. Configure this block if your cluster requires authentication through one of the following mechanisms:

  • Basic authentication: Provide username and password.

  • OAuth 2.0: Provide token to use a static token or provide clientId, clientSecret, tokenEndpoint, and scope to acquire new tokens at runtime.

  • Kerberos (GSSAPI): Provide parameters such as authType, keyTabPath, kerberosConfigPath, serviceName, username, password, realm, and enableFast.

Supported mechanisms:

  • PLAIN

  • SCRAM-SHA-256 or SCRAM-SHA-512

  • GSSAPI

  • OAUTHBEARER

Because Redpanda Console supports only OIDC and basic authentication for its own login authentication, Kerberos (GSSAPI) configurations must be used with impersonateUser set to false.

For more detailed instructions on configuring authentication, see Authentication.

startup (optional)

Controls connection behavior at startup:

  • establishConnectionEagerly: Tests the connection immediately.

  • maxRetries, retryInterval, maxRetryInterval, backoffMultiplier: Define the retry logic for establishing a connection.

tls (optional)

Contains settings to secure the connection using TLS. Specify paths for the CA certificate, client certificate, and client key. Optionally configure insecureSkipTlsVerify for testing purposes.

Configure access to the Schema Registry

To enable schema management features, you must configure Redpanda Console to connect to the Schema Registry API. This includes specifying the service endpoints and, if needed, setting up authentication.

Example Schema Registry configuration:

schemaRegistry:
  enabled: true
  urls:
    - "broker1.example.com:8081"
    - "broker2.example.com:8081"

  # Optional authentication settings
  authentication:
    impersonateUser: true
    #basic:
      #username: "example-user"
      #password: "example-password"
    #bearerToken: "example-bearer-token"
Schema Registry Configuration Option Description

urls

A list of Schema Registry endpoints in the format <hostname>:<port>. Include all endpoints for redundancy.

authentication (optional)

Configure authentication for the Schema Registry. Options include basic authentication or bearer tokens. For more detailed instructions on configuring authentication, see Authentication.

Configure access to the Redpanda Admin API

Configuring a connection to the Redpanda Admin API unlocks additional features in Redpanda Console, including viewing the current Redpanda version, managing data transforms, administering SASL-SCRAM users, and generating debug bundles. This section details the configuration options and how they interact.

Example configuration template:

redpanda:
  adminApi:
    enabled: true # Enable connection to the Admin API.
    urls:
      - "broker1.example.com:9644" # Provide all endpoints (host:port) for high availability.
      - "broker2.example.com:9644"
    # Optional authentication settings
    authentication:
      impersonateUser: true # Use the logged-in user's credentials for authentication.
      # For basic authentication.
      #basic:
        #username: "example-user"
        #password: "example-password"
      # For OIDC, use the `bearerToken` field instead of `basic`.
      #bearerToken: "example-bearer-token"
    startup:
      establishConnectionEagerly: true   # Test the connection at startup.
      maxRetries: 5                      # Maximum number of retry attempts.
      retryInterval: 1s                  # Initial wait time between retries.
      maxRetryInterval: 60s              # Maximum wait time between retries.
      backoffMultiplier: 2               # Multiplier for increasing retry intervals.
Include the URLs of all endpoints in the redpanda.adminApi.urls array. For some requests such as collecting debug bundles, Redpanda Console must be able to communicate with all brokers individually.
Redpanda Admin API Configuration Option Description

enabled

Activates the connection to the Admin API. Set to true to enable the integration.

urls

A list of endpoints (host:port) for all brokers serving the Admin API. Providing all URLs enhances reliability.

authentication (optional)

Provides credentials using basic authentication or bearer tokens when impersonation is disabled. For more detailed instructions on configuring authentication, see Authentication.

startup (optional)

Controls connection behavior at startup:

  • establishConnectionEagerly: Tests the connection immediately.

  • maxRetries, retryInterval, maxRetryInterval, backoffMultiplier: Define the retry logic for establishing a connection.

Suggested reading