# Self-Managed - Full Markdown Export > This file contains all Self-Managed documentation pages in markdown format for AI agent consumption. > Generated from 506 pages on 2026-04-10T19:52:50.565Z > Component: ROOT | Version: 26.1 > Site: https://docs.redpanda.com ## About This Export This export includes the **latest version** (26.1) of the Self-Managed documentation. ### AI-Friendly Documentation Formats We provide multiple formats optimized for AI consumption: - **https://docs.redpanda.com/llms.txt**: Curated overview of all Redpanda documentation - **https://docs.redpanda.com/llms-full.txt**: Complete documentation export with all components - **https://docs.redpanda.com/ROOT-full.txt**: This file - Self-Managed documentation only - **Individual markdown pages**: Each HTML page has a corresponding .md file ### Accessing Older Versions This component has versioned documentation. Older versions can be accessed by replacing the version segment in the URL: - Latest: `https://docs.redpanda.com/current/page-path` - Specific version: `https://docs.redpanda.com/24.3/page-path`, `https://docs.redpanda.com/25.1/page-path`, etc. --- # Page 1: Introduction to Redpanda Console **URL**: https://docs.redpanda.com/current/console.md --- # Introduction to Redpanda Console --- title: Introduction to Redpanda Console latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/console/pages/index.adoc description: "Learn about Redpanda Console: a web interface for managing and interacting with Redpanda clusters." page-git-created-date: "2023-05-17" page-git-modified-date: "2025-12-04" support-status: supported --- Redpanda Console v3.x [Redpanda Console v2.x](../../24.3/console/) [Redpanda Console v3.x](./) Redpanda Console is a web interface for managing and interacting with Redpanda clusters. Built to provide a seamless experience for developers working with streaming data, Redpanda Console simplifies tasks associated with managing data streams, offering a UI that helps you monitor, troubleshoot, and optimize your streaming workloads. ![overview](_images/overview.png) ## [](#cluster-management)Cluster management Explore a comprehensive overview of your cluster, including: - **Broker monitoring**: View and manage the health, status, and configurations of your brokers. - **Topic management**: Create, configure, and monitor topics, including detailed information on partitions, replicas, and message counts. - **Consumer group insights**: Track the activity and performance of your consumer groups, manage offsets, and identify potential bottlenecks. - [**Shadow link management**](../manage/disaster-recovery/shadowing/overview/): Create shadow links for asynchronous, offset-preserving replication between distinct Redpanda clusters. The shadow cluster operates in read-only mode while continuously receiving updates from the source cluster. During a disaster, you can failover individual topics or an entire shadow link to make resources fully writable for production traffic. ![broker overview](_images/broker-overview.png) ## [](#data-observability-and-debugging)Data observability and debugging Observe and debug your streaming data: - **Message inspection**: Browse and filter messages within your topics, with options to search by key, timestamp, or custom filters. - [**Programmable push filters**](ui/programmable-push-filters/): Write custom JavaScript filters to isolate specific messages, enabling deep inspection and debugging. - **Rewind and Replay**: Roll back consumer offsets to reprocess messages, allowing you to correct issues or replay data as needed. ![topic](_images/topic.png) ## [](#access-control)Access control Manage Redpanda users and control who has access to Redpanda Console: - **Visual ACL management**: Create, view, and manage ACLs, ensuring that your data is secure and access is properly controlled. - **Rotate credentials**: Update user and service account passwords to maintain security without downtime. - **Identity provider integration**: For enterprise users, Redpanda Console integrates with identity providers (IdPs) for single sign-on (SSO), making user management straightforward and secure. ![user](_images/user.png) ## [](#schema-management)Schema management [Manage and browse your schemas](ui/schema-reg/), ensuring your data is correctly structured and validated across your streams. ![schema reg](_images/schema-reg.png) ## [](#connectivity-and-integrations)Connectivity and integrations View and manage Kafka Connect clusters and connectors, simplifying the integration of external systems with your streaming data. > 📝 **NOTE: Community** > > **Kafka Connect is community-supported on [Redpanda Community Slack](https://redpanda.com/slack)**. Redpanda Data does not provide enterprise support for Kafka Connect with Redpanda Console. For a supported and scalable Kafka Connect alternative, try [Redpanda Connect](../../redpanda-connect/get-started/). ## [](#who-should-use-redpanda-console)Who should use Redpanda Console? Redpanda Console is designed for: - **Developers** who need to manage, monitor, and debug streaming data without the overhead of complex CLI tools. - **Data engineers** who require a robust interface to manage Redpanda clusters and ensure data pipelines are running smoothly. - **DevOps engineers** who want a single place to monitor the health and performance of streaming data infrastructure. - **Security teams** who need to configure and audit access controls within the data streaming environment. ## [](#suggested-videos)Suggested videos - [Demo: Redpanda Console](https://www.youtube.com/watch?v=ezDYSpC7JcU) ## [](#next-steps)Next steps [Get started](../get-started/quick-start/) --- # Page 2: Redpanda Console Telemetry **URL**: https://docs.redpanda.com/current/console/config/analytics.md --- # Redpanda Console Telemetry --- title: Redpanda Console Telemetry latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: config/analytics page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: config/analytics.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/console/pages/config/analytics.adoc description: Learn what telemetry Redpanda Console collects by default, how it is handled, and how to disable it. page-git-created-date: "2025-08-04" page-git-modified-date: "2025-12-04" support-status: supported --- Redpanda Console collects telemetry (analytics) data for purposes including product improvements and user experience optimization. This document explains what data is collected, how it is processed, and how you can disable telemetry if desired. ## [](#what-is-tracked-by-default)What is tracked by default When telemetry is enabled, which is the default behavior, Redpanda Console collects metadata and sends it securely to Redpanda. ### [](#redpanda-console-metadata)Redpanda Console metadata The following information is collected from the running instance of Redpanda Console: - Startup timestamp (when the Redpanda Console process starts) - Runtime UUID (a unique ID generated per instance) - Redpanda Console version and build timestamp - License hash, license type, and license organization - Kafka configuration hash (anonymized) - Whether Kafka is connected as `localhost` - Behavioral user analytics ### [](#cluster-metadata)Cluster metadata The following information is collected from the connected Kafka cluster: - Cluster configuration details (excluding sensitive values) - Broker log dir statistics such as the size - Topic configurations (settings only, no message contents) - Consumer group metadata (total count, and counts by protocol and state) - General cluster metadata: - Number of brokers - Number of topics - Number of partitions - Number of racks - Cluster ID ## [](#how-telemetry-data-is-handled)How telemetry data is handled Telemetry data is processed with the following features: - All telemetry payloads are signed and encoded as JWTs - Data is sent using HTTPS POST requests to Redpanda’s telemetry endpoint - Configuration data is anonymized using secure hashes - No message contents or credentials are collected or transmitted ## [](#disable-telemetry)Disable telemetry To turn off telemetry and user tracking, set the following in your Redpanda Console configuration: ### Standalone ```yaml analytics: enabled: false ``` ### Kubernetes embedded When Redpanda Console is part of the Redpanda Helm chart or Operator: #### Operator `redpanda-console`.yaml ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Console metadata: name: redpanda-console spec: clusterRef: name: redpanda config: analytics: enabled: false ``` #### Helm `redpanda-values.yaml` ```yaml console: enabled: true console: config: analytics: enabled: false ``` ### Kubernetes standalone When using the standalone Redpanda Console Helm chart: `console-values.yaml` ```yaml config: analytics: enabled: false ``` Restart the Redpanda Console service to apply the change and stop all telemetry and user tracking. --- # Page 3: Configure Redpanda Console **URL**: https://docs.redpanda.com/current/console/config/configure-console.md --- # Configure Redpanda Console --- title: Configure Redpanda Console latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: config/configure-console page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: config/configure-console.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/console/pages/config/configure-console.adoc description: Learn how to configure Redpanda Console using environment variables, YAML files, or command-line arguments. page-git-created-date: "2024-09-11" page-git-modified-date: "2025-12-04" support-status: supported --- Redpanda Console v3.x [Redpanda Console v2.x](../../../../24.3/console/config/configure-console/) [Redpanda Console v3.x](./) Redpanda Console loads configuration properties from three sources, in the following order of precedence: 1. Environment variables 2. YAML file configuration 3. Command-line arguments Environment variables and YAML configurations can overwrite input that is set on the command line. ## [](#environment-variable-mapping)Environment variable mapping Configuration options can be set using environment variables. The key for the environment variable is auto-generated by converting the [YAML equivalent](#config-yaml) to uppercase and adding an underscore for each indentation level. For example: | YAML | Environment variable | | --- | --- | | kafka.rackId | KAFKA_RACKID | | kafka.tls.caFilepath | KAFKA_TLS_CAFILEPATH | For configuration properties that expect a list of values, use commas between each value. For example: ```bash KAFKA_BROKERS=redpanda-0:9092,redpanda-1:9092,redpanda-2:9092 ``` > 📝 **NOTE** > > You cannot use environment variables to configure object arrays, such as the configuration for Kafka Connect clusters. In this case, use a YAML file, and provide secrets using environment variables or command line arguments. ## [](#platform-specific-configuration)Platform-specific configuration Redpanda Console can be deployed in several ways. The configuration method and file structure you use depends on your deployment scenario. Use the tabs on this page and throughout the docs to find the instructions and examples for your environment. - **Standalone (binary, Docker, or systemd):** For users running Redpanda Console as a separate service, either on a VM, bare metal, or in a container (not managed by Kubernetes or the Redpanda Operator/Helm chart). - **Kubernetes embedded:** For users running Redpanda Console as part of a Redpanda cluster managed by the Redpanda Operator or the Redpanda Helm chart. - **Kubernetes standalone:** For users deploying Redpanda Console in Kubernetes using the dedicated Redpanda Console Helm chart (not as part of a Redpanda cluster). ### Standalone Use this method when deploying Redpanda Console as a standalone service (binary, Docker, or systemd). The recommended configuration source is a YAML file. You can specify the path to the configuration file by setting either the `-config.filepath` flag or the `CONFIG_FILEPATH` environment variable. In Linux package installations, this file is located in `/etc/redpanda/redpanda-console-config.yaml` by default and Redpanda Console is configured to read from this file path. In containerized environments, ensure that the configuration file is mounted to a directory accessible by the Redpanda Console container. When the file is mounted, you can specify its file path using the `-config.filepath` flag or the `CONFIG_FILEPATH` environment variable. ### Kubernetes embedded Use this method when Redpanda Console is deployed as part of the Redpanda Helm chart or Redpanda Operator. > 📝 **NOTE** > > When Redpanda Console is embedded in the Redpanda deployment, the Kafka broker configuration is automatically set to connect to the Redpanda cluster in the same deployment. #### Operator Configure Redpanda Console in the `console` section of your Redpanda custom resource: `redpanda-console`.yaml ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Console metadata: name: redpanda-console spec: clusterRef: name: redpanda # Reference to your Redpanda cluster config: server: listenPort: 8080 auditLog: enabled: false additionalHeaders: - "X-Forwarded-For" - "User-Agent" # Add any other Redpanda Console configuration here ``` Apply the configuration: ```bash kubectl apply -f redpanda-console.yaml --namespace ``` #### Helm Configure Redpanda Console in the `console` section of your Redpanda Helm values file: `redpanda-values.yaml` ```yaml console: enabled: true console: config: #kafka: #brokers: [] # You can leave this empty. The chart is already auto-configured to connect to your Redpanda cluster server: listenPort: 8080 auditLog: enabled: false # default; set to true to write audit logs to stdout additionalHeaders: # specifies HTTP headers to include in audit logs # Add any other Redpanda Console configuration here ``` Apply the configuration: ```bash helm upgrade --install redpanda redpanda/redpanda \ --namespace \ --values redpanda-values.yaml ``` ### Kubernetes standalone Use this method when deploying Redpanda Console as a standalone service in Kubernetes using the dedicated Redpanda Console Helm chart. When using the standalone Redpanda Console Helm chart, configure Redpanda Console through the `config` section of your values file: `console-values.yaml` ```yaml config: kafka: brokers: - redpanda-0.redpanda.svc.cluster.local:9092 - redpanda-1.redpanda.svc.cluster.local:9092 server: listenPort: 8080 auditLog: enabled: false # default; set to true to write audit logs to stdout additionalHeaders: # specifies HTTP headers to include in audit logs - "X-Forwarded-For" - "User-Agent" # Add any other Redpanda Console configuration here ``` Apply the configuration: ```bash helm upgrade --install console redpanda/console \ --namespace redpanda \ --values console-values.yaml ``` ## [](#docker-compose-example)Docker Compose example If you are using Docker Compose, you can mount the configuration file and set the environment variable in your `docker-compose.yml` file: ```yaml console: container_name: redpanda-console image: docker.redpanda.com/redpandadata/console:v3.7.1 entrypoint: /bin/sh command: -c 'echo "$$CONSOLE_CONFIG_FILE" > /tmp/config.yml' volumes: - ./config:/tmp/config/ environment: CONFIG_FILEPATH: ${CONFIG_FILEPATH:-/tmp/config.yml} CONSOLE_CONFIG_FILE: | # Configure a connection to the Redpanda cluster # See https://docs.redpanda.com/current/console/config/connect-to-redpanda/ kafka: brokers: ["redpanda-0:9092","redpanda-1:9092","redpanda-2:9092"] auditLog: enabled: false # default; set to true to write audit logs to stdout additionalHeaders: # specifies HTTP headers to include in audit logs - "X-Forwarded-For" - "User-Agent" ``` ## [](#config-yaml)Complete configuration file example The following YAML file contains a complete list of all Redpanda Console configuration properties and their descriptions. All values are default values. > ⚠️ **CAUTION** > > - Where necessary, ensure that values are enclosed in quotes and escaped. For example, put passwords with special characters in single quotes. > > - This configuration file contains both Redpanda Enterprise and Redpanda Community Edition configurations. If you don’t provide an enterprise license, Redpanda Console ignores configurations for enterprise features. [Download the sample file](../../../shared/_attachments/redpanda-console-config.yaml). redpanda-console-config.yaml ```yaml # This is an example configuration file for Redpanda Console v3.x.x #---------------------------------------------------------------------------- # Kafka configuration #---------------------------------------------------------------------------- kafka: # Brokers is a list of bootstrap servers with ports. brokers: - "broker-0.mycompany.com:19092" - "broker-1.mycompany.com:19092" - "broker-2.mycompany.com:19092" # Optional: Client ID used to identify Redpanda Console to the Kafka cluster. # clientId: "console" # Optional: Rack identifier to optimize message consumption in multi-zone clusters. # rackId: "zone-a" # sasl: # enabled: true # Supported mechanisms include: # - OAUTHBEARER (OIDC) # - SCRAM-SHA-256 or SCRAM-SHA-512 (basic authentication) # - GSSAPI (Kerberos); if using Kerberos, ensure impersonateUser is false. # - AWS_MSK_IAM (AWS MSK IAM) # mechanism: SCRAM-SHA-256 # impersonateUser: false # oauth: # token: "example-oauth-token" # clientId: "example-client-id" # clientSecret: "example-client-secret" # tokenEndpoint: "https://accounts.google.com/token" # tokenFilepath: "/var/run/secrets/kafka/serviceaccount/token" # scope: "openid" # Example for basic authentication (uncomment to use): # username: "your-username" # password: "your-password" # Example for GSSAPI (Kerberos) - impersonateUser must be false: # gssapi: # authType: KEYTAB_AUTH # keyTabPath: "/path/to/keytab" # kerberosConfigPath: "/path/to/krb5.conf" # serviceName: "kafka" # username: "your-username" # password: "your-password" # realm: "MY.REALM" # enableFast: true # tls: # enabled: false # Uncomment and set the following paths if TLS is required: # caFilepath: "/path/to/ca-cert.pem" # certFilepath: "/path/to/client-cert.pem" # keyFilepath: "/path/to/client-key.pem" # insecureSkipTlsVerify: false # Startup is a configuration block to specify how often and with what delays # we should try to connect to the Kafka service. If all attempts fail the # application exits with code 1. # startup: # maxRetries: 5 # retryInterval: 1s # maxRetryInterval 60s # backoffMultiplier: 2 #---------------------------------------------------------------------------- # Schema Registry configuration (top-level) #---------------------------------------------------------------------------- schemaRegistry: enabled: true urls: - "http://schema-registry.mycompany.com:8081" # Optional: Authentication for Schema Registry. # authentication: # basic: # username: "example-user" # password: "example-password" # bearerToken: "example-bearer-token" tls: enabled: false # Uncomment and configure if TLS is required: # caFilepath: "/path/to/ca-cert.pem" # certFilepath: "/path/to/client-cert.pem" # keyFilepath: "/path/to/client-key.pem" # insecureSkipTlsVerify: false #---------------------------------------------------------------------------- # Redpanda Console authentication #---------------------------------------------------------------------------- authentication: jwtSigningKey: "secret-value" useSecureCookies: true # Maximum browser session age (Enterprise). Accepts duration strings (for example, "90d", "24h", "30m"). Default: 1 year. # maximumSessionAge: "90d" # Optionally enable cookie chunking if cookie size is an issue. # useCookieChunking: false # OIDC configuration (if using OIDC): # oidc: # enabled: true # issuerUrl: "https://accounts.google.com" # clientId: "your-oidc-client-id" # clientSecret: "your-oidc-client-secret" # redirectUrl: "http://localhost:9090/auth/callbacks/oidc" # successfulLoginRedirectUrl: "http://localhost:3000" # accessType: "offline" # prompt: "consent" # issuerTls: # enabled: true # caFilepath: "/path/to/ca.pem" # certFilepath: "/path/to/issuer-cert.pem" # keyFilepath: "/path/to/issuer-key.pem" # insecureSkipTlsVerify: false # Basic authentication is supported by default. #---------------------------------------------------------------------------- # Redpanda Console authorization and role bindings #---------------------------------------------------------------------------- authorization: roleBindings: - roleName: admin users: - loginType: oidc name: "admin@mycompany.com" - roleName: viewer users: - loginType: basic name: "user@mycompany.com" #---------------------------------------------------------------------------- # Redpanda Admin API configuration #---------------------------------------------------------------------------- redpanda: adminApi: enabled: true urls: - "admin-0.mycompany.com:9644" - "admin-1.mycompany.com:9644" authentication: impersonateUser: true # If impersonateUser is false, configure static credentials here: # authentication: # basic: # username: "example-user" # password: "example-password" startup: establishConnectionEagerly: true maxRetries: 5 retryInterval: 1s maxRetryInterval: 60s backoffMultiplier: 2 tls: enabled: true caFilepath: "/path/to/ca-cert.pem" certFilepath: "/path/to/client-cert.pem" keyFilepath: "/path/to/client-key.pem" insecureSkipTlsVerify: false #---------------------------------------------------------------------------- # Kafka Connect configuration (optional) #---------------------------------------------------------------------------- kafkaConnect: enabled: false # connectTimeout: 15s # readTimeout: 60s # requestTimeout: 6s clusters: [] # Example: # clusters: # - name: my-connect-cluster # url: "http://connect.mycompany.com:8083" # tls: # enabled: false # username: "connect-user" # password: "connect-password" # token: "optional-token" #---------------------------------------------------------------------------- # Enterprise License configuration (optional) #---------------------------------------------------------------------------- # To mount an enterprise license, set either license or licenseFilepath. # This is only required if you want to use an enterprise feature # such as SSO or RBAC. # Filepath to your redpanda.license file # licenseFilepath: "" # License string. # license: "" #---------------------------------------------------------------------------- # Serde settings #---------------------------------------------------------------------------- serde: maxDeserializationPayloadSize: 20480 # protobuf: # enabled: false # mappings: [] # Map the Proto type names for each of your topics. # These Proto types will be used for deserialization. # - topicName: xy # You can specify the Proto type for the record key # and/or value (just one will work too) # valueProtoType: fake_model.Order # keyProtoType: package.Type # Configure the fileSystem if you want Redpanda Console to # search the local file system for the Proto files # fileSystem: # enabled: false # paths: [] # refreshInterval: 5m # importPaths is a list of paths from which to import Proto files into Redpanda Console. # Paths are relative to the root directory. # The `git` configuration must be enabled to use this feature. #importPaths: [] # Git is where the Proto files come from. # git: # enabled: false # repository: # url: # branch: (defaults to primary/default branch) # baseDirectory: (defaults to the root directory of the repo/branch above) # How often Redpanda Console pulls the repository to look for new files. # Set to 0 to disable periodic pulls. # refreshInterval: 5m # To use GitHub's personal access tokens, use `token` # as username and pass the same token as password. # basicAuth: # enabled: true # username: # Password can also be set using the --serde.protobuf.git.basic-auth.password flag. # password: # You can pass the private key file directly using a flag on the command line, or you can specify it in the # yaml configuration file. Another alternative is to provide the filepath to a mounted key # file in this configuration block. # ssh: # enabled: false # username: # privateKey can also be set using the --serde.protobuf.git.ssh.private-key flag. # privateKey: # privateKeyFilepath: # Passphrase can also be set using the --serde.protobuf.git.ssh.passphrase flag. # passphrase: # messagePack: # enabled: false # List of topic name regexes, defaults to /.*/ # topicNames: ["/.*/"] #---------------------------------------------------------------------------- # Redpanda Console settings #---------------------------------------------------------------------------- console: topicDocumentation: enabled: false # git: # enabled: false # repository: # url: # branch: (defaults to primary/default branch) # baseDirectory: . # # How often Redpanda Console pulls the repository to look for new files. # # Set to 0 to disable periodic pulls. # # refreshInterval: 1m # # To use GitHub's personal access tokens, use `token` as username and pass the actual token as the password. # basicAuth: # enabled: true # username: token # password: # # You can pass the private key file directly using a flag on the command line, or you can specify it in the yaml configuration file. Another alternative is to provide the filepath to a mounted key file in this configuration block. # ssh: # enabled: false # username: git # privateKey: | # -----BEGIN PRIVATE KEY----- # ... # -----END PRIVATE KEY----- # privateKeyFilepath: /path/to/private/key # passphrase: auditLog: enabled: false # default; set to true to write audit logs to stdout additionalHeaders: # specifies HTTP headers to include in audit logs - "X-Forwarded-For" - "User-Agent" #---------------------------------------------------------------------------- # Server settings #---------------------------------------------------------------------------- server: listenAddress: "0.0.0.0" listenPort: 8080 httpsListenPort: 8081 advertisedHttpsListenPort: 443 gracefulShutdownTimeout: 30s readTimeout: 30s writeTimeout: 30s idleTimeout: 30s compressionLevel: 4 basePath: "" setBasePathFromXForwardedPrefix: true stripPrefix: true tls: enabled: false # Uncomment and configure if HTTPS is required: # certFilepath: "/path/to/https-cert.pem" # keyFilepath: "/path/to/https-key.pem" allowedOrigins: [] #---------------------------------------------------------------------------- # Logger settings #---------------------------------------------------------------------------- logger: level: info #---------------------------------------------------------------------------- # Developer settings #---------------------------------------------------------------------------- # Only relevant for developers who want to run the frontend separately. # Uncomment the following line to serve the frontend separately. # serveFrontend: true #---------------------------------------------------------------------------- # Metrics settings #---------------------------------------------------------------------------- # Prefix for all exported Prometheus metrics. # Uncomment and set your metrics namespace. # metricsNamespace: "console" #---------------------------------------------------------------------------- # Analytics / telemetry (optional) #---------------------------------------------------------------------------- analytics: enabled: true ``` --- # Page 4: Configure Redpanda Console to Connect to a Redpanda Cluster **URL**: https://docs.redpanda.com/current/console/config/connect-to-redpanda.md --- # Configure Redpanda Console to Connect to a Redpanda Cluster --- title: Configure Redpanda Console to Connect to a Redpanda Cluster latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: config/connect-to-redpanda page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: config/connect-to-redpanda.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/console/pages/config/connect-to-redpanda.adoc description: Learn how to configure Redpanda Console to connect to a Redpanda cluster and ensure communication with your Redpanda brokers. page-git-created-date: "2024-09-11" page-git-modified-date: "2025-12-04" support-status: supported --- Redpanda Console v3.x [Redpanda Console v2.x](../../../../24.3/console/config/connect-to-redpanda/) [Redpanda Console v3.x](./) 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)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)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: ### Standalone ```yaml 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" ``` ### Kubernetes embedded Operator When deploying Redpanda Console with the Redpanda Operator, you can connect Console to your Redpanda cluster in two ways: - **clusterRef:** Reference the Redpanda cluster by name for automatic connection. This is the recommended approach for most users. - **staticConfiguration:** Manually specify connection details for Kafka, Admin API, and Schema Registry if you need custom settings. The Operator will automatically configure Console to connect to the referenced cluster when using `clusterRef`. Use `staticConfiguration` only if you need to override the default connection or connect to a different cluster. Helm chart Redpanda Console is automatically configured to connect to the Redpanda cluster managed by the Helm chart. No additional connection configuration is required. Only configure the `kafka` block if you need to override the default connection settings (for example, to connect to a different cluster or use custom authentication). ### Kubernetes standalone When using the standalone Redpanda Console Helm chart: `console-values.yaml` ```yaml config: 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" ``` > 📝 **NOTE** > > When Redpanda Console is embedded in the Redpanda deployment, you can usually omit the broker addresses as they are automatically configured to connect to the Redpanda cluster in the same deployment. For clusters using Kerberos, the configuration may resemble the following: ```yaml 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" realm: "EXAMPLE.REALM" enableFast: true ``` > 📝 **NOTE** > > Kerberos (GSSAPI) configurations cannot be used with user impersonation enabled, because Redpanda Console supports only OIDC and basic authentication for its own login authentication. When using Kerberos, ensure `impersonateUser` is set to `false`. | Kafka API Configuration Option | Description | | --- | --- | | brokers | A list of Kafka broker endpoints including the URL scheme (http:// or https://), hostname, and port. Include all brokers in your cluster for high availability. | | 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:PLAINSCRAM-SHA-256 or SCRAM-SHA-512GSSAPIOAUTHBEARERFor more detailed instructions on configuring authentication, see Authentication in Redpanda Console. | | 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)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: ```yaml 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 including the URL scheme (http:// or https://), hostname, and 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 in Redpanda Console. | ## [](#admin)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: ```yaml 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. ``` > 📝 **NOTE** > > 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 Admin API endpoints including the URL scheme (http:// or https://), hostname, and port. 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 in Redpanda Console. | | 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)Suggested reading - [Redpanda Console Security](../security/) - [Configure Message Deserialization in Redpanda Console](../deserialization/) --- # Page 5: Configure Message Deserialization in Redpanda Console **URL**: https://docs.redpanda.com/current/console/config/deserialization.md --- # Configure Message Deserialization in Redpanda Console --- title: Configure Message Deserialization in Redpanda Console latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: config/deserialization page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: config/deserialization.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/console/pages/config/deserialization.adoc description: Learn how to configure Redpanda Console to use Schema Registry, Protobuf files, and other deserialization methods to ensure your data is correctly interpreted and displayed. page-git-created-date: "2024-09-11" page-git-modified-date: "2025-12-04" support-status: supported --- Redpanda Console v3.x [Redpanda Console v2.x](../../../../24.3/console/config/deserialization/) [Redpanda Console v3.x](./) Redpanda Console provides tools for deserializing and inspecting messages in Kafka topics. This topic explains how to configure Redpanda Console to use Schema Registry, Protobuf files, and other deserialization methods to ensure your data is correctly interpreted and displayed. ## [](#sr)Use Schema Registry The Schema Registry allows Redpanda Console to dynamically retrieve schemas for deserializing Avro, Protobuf, and JSON messages. This setup is important to ensure that messages are correctly interpreted based on your schema definitions. See [Configure access to the Schema Registry](../connect-to-redpanda/#sr). ## [](#protobuf-configuration)Protobuf configuration Redpanda Console supports several methods for providing Protobuf schemas, including the Schema Registry, local file system, and GitHub repositories. > 📝 **NOTE** > > You don’t need to provide standard types, such as Google’s timestamp, in your schemas. These standard types are included by default. Most Kafka clients that serialize Protobuf messages put the serialized byte array into a binary wrapper that contains meta information, like the schema ID or the used prototypes, so the application that deserializes the Kafka records must recognize the format. The deserialization process requires Redpanda Console to be aware of the used Protobuf files as well as a mapping of what prototype should be used for each topic. This information can either be sourced from the Schema Registry or it can be provided with additional configuration so the files can be pulled from the local file system or a GitHub repository. ### [](#sr-protobuf)Use Schema Registry for Protobuf If you use a Schema Registry for Protobuf deserialization, Redpanda Console can automatically fetch and use the required schemas without the need for manual topic mappings or additional configuration. When using Schema Registry for Protobuf, you must not configure `serde.protobuf`. Redpanda Console detects and uses the Protobuf schemas from the Schema Registry automatically. If you configure `serde.protobuf`, it enables manual deserialization mode, which requires you to specify topic mappings and source providers. Without those, Redpanda Console fails to start due to validation errors. When using Schema Registry for Protobuf, you do not need to provide specific topic mappings, as the schemas will be fetched dynamically. ### [](#topic-mapping)Topic mapping If you’re not [using a Schema Registry for Protobuf deserialization](#sr-protobuf), you must manually provide mappings between Kafka topics and their corresponding Protobuf types. This is necessary to inform Redpanda Console of the correct types to use for deserialization. Consider a Kafka topic called `address-v1` and a corresponding `address.proto` file with the following structure: `address.proto` ```proto syntax = "proto3"; package fake_models; option go_package = "pkg/protobuf"; message Address { int32 version = 1; string id = 2; message Customer { string customer_id = 1; string customer_type = 2; } } ``` To map this topic to the Protobuf schema, use the following configuration: #### Standalone ```yaml serde: protobuf: enabled: true mappings: - topicName: address-v1 valueProtoType: fake_models.Address # The full Protobuf type name # keyProtoType: Not specified because the key is a plain string ``` #### Kubernetes embedded When Redpanda Console is part of the Redpanda Helm chart or Operator: ##### Operator `redpanda-cluster`.yaml ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Console metadata: name: redpanda-console spec: clusterRef: name: redpanda config: serde: protobuf: enabled: true mappings: - topicName: address-v1 valueProtoType: fake_models.Address # keyProtoType: Not specified because the key is a plain string ``` ##### Helm `redpanda-values.yaml` ```yaml console: enabled: true console: config: serde: protobuf: enabled: true mappings: - topicName: address-v1 valueProtoType: fake_models.Address # The full Protobuf type name # keyProtoType: Not specified because the key is a plain string ``` #### Kubernetes standalone When using the standalone Redpanda Console Helm chart: `console-values.yaml` ```yaml config: serde: protobuf: enabled: true mappings: - topicName: address-v1 valueProtoType: fake_models.Address # The full Protobuf type name # keyProtoType: Not specified because the key is a plain string ``` - `serde.protobuf.enabled`: Set to `true` to enable Protobuf deserialization. - `serde.protobuf.mappings.topicName`: The name of the Kafka topic. - `serde.protobuf.mappings.valueProtoType`: The fully-qualified Protobuf type for the message value. - `serde.protobuf.mappings.keyProtoType`: Specify the key Protobuf type if the key is not a plain string. ### [](#local-file-system)Local file system You can mount Protobuf files directly from your local file system. Redpanda Console will search the specified paths for Protobuf files and build a registry with all the available types. Configuration example: #### Standalone ```yaml serde: protobuf: enabled: true mappings: - topicName: orders valueProtoType: fake_models.Order keyProtoType: fake_models.OrderKey fileSystem: enabled: true # How often to refresh the Protobuf files from the filesystem refreshInterval: 5m # Directories containing the Protobuf files paths: - /etc/protos ``` #### Kubernetes embedded When using the Redpanda Operator or the Redpanda Helm chart, configure Protobuf deserialization through the cluster configuration: ##### Operator ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Console metadata: name: redpanda-console spec: clusterRef: name: redpanda config: serde: protobuf: enabled: true mappings: - topicName: orders valueProtoType: fake_models.Order keyProtoType: fake_models.OrderKey fileSystem: enabled: true refreshInterval: 5m paths: - /etc/protos ``` ##### Helm ```yaml console: enabled: true console: config: serde: protobuf: enabled: true mappings: - topicName: orders valueProtoType: fake_models.Order keyProtoType: fake_models.OrderKey fileSystem: enabled: true refreshInterval: 5m paths: - /etc/protos ``` #### Kubernetes standalone When using the standalone Redpanda Console Helm chart: ```yaml config: serde: protobuf: enabled: true mappings: - topicName: orders valueProtoType: fake_models.Order keyProtoType: fake_models.OrderKey fileSystem: enabled: true refreshInterval: 5m paths: - /etc/protos ``` Apply with: ```bash helm upgrade --install redpanda-console redpanda/console -f console-values.yaml ``` - `serde.protobuf.enabled`: Set to `true` to enable Protobuf deserialization. - `serde.protobuf.fileSystem.paths`: Paths to directories where Protobuf files are stored. - `serde.protobuf.fileSystem.refreshInterval`: The frequency at which Redpanda Console checks for updates to these files. ### [](#github-repository)GitHub repository If your Protobuf files are stored in a GitHub repository, Redpanda Console can fetch and use them directly. This is particularly useful if your organization maintains Protobuf definitions in version control. Configuration example: #### Standalone ```yaml serde: protobuf: enabled: true mappings: - topicName: orders valueProtoType: fake_models.Order keyProtoType: fake_models.OrderKey git: enabled: true repository: url: https://github.com/myorg/kafka-proto-files.git branch: master # How often to pull the git repository to refresh the schema files refreshInterval: 10m # Where all .proto files are stored in the git repository paths: - ./ ``` #### Kubernetes embedded When using the Redpanda Operator or the Redpanda Helm chart, configure GitHub repository access through the cluster configuration: ##### Operator ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Console metadata: name: redpanda-console spec: clusterRef: name: redpanda config: serde: protobuf: enabled: true mappings: - topicName: orders valueProtoType: fake_models.Order keyProtoType: fake_models.OrderKey git: enabled: true repository: url: https://github.com/myorg/kafka-proto-files.git branch: master refreshInterval: 10m paths: - ./ ``` ##### Helm ```yaml console: enabled: true console: config: serde: protobuf: enabled: true mappings: - topicName: orders valueProtoType: fake_models.Order keyProtoType: fake_models.OrderKey git: enabled: true repository: url: https://github.com/myorg/kafka-proto-files.git branch: master refreshInterval: 10m paths: - ./ ``` #### Kubernetes standalone When using the standalone Redpanda Console Helm chart: ```yaml config: serde: protobuf: enabled: true mappings: - topicName: orders valueProtoType: fake_models.Order keyProtoType: fake_models.OrderKey git: enabled: true repository: url: https://github.com/myorg/kafka-proto-files.git branch: master refreshInterval: 10m paths: - ./ ``` Apply with: ```bash helm upgrade --install redpanda-console redpanda/console -f console-values.yaml ``` - `serde.protobuf.enabled`: Set to `true` to enable Protobuf deserialization. - `serde.protobuf.git.repository.url`: The URL of the GitHub repository containing your Protobuf files. - `serde.protobuf.git.basicAuth`: Basic authentication credentials, often an API token for private repositories. - `serde.protobuf.git.refreshInterval`: Frequency at which the repository is polled for updates. #### [](#private-git-repositories)Private Git repositories If Protobuf files are stored in a private GitHub repository, Redpanda Console must authenticate using one of the following methods: - A [GitHub Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) (PAT) over HTTPS (basic auth) - An [SSH private key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) ##### [](#authenticate-using-a-github-personal-access-token-pat)Authenticate using a GitHub Personal Access Token (PAT) Use this method to authenticate to GitHub over HTTPS using a personal access token. ###### Standalone 1. Set environment variables: ```bash SERDE_PROTOBUF_GIT_BASICAUTH_USERNAME=token SERDE_PROTOBUF_GIT_BASICAUTH_PASSWORD= ``` 2. Configure Redpanda Console: ```yaml serde: protobuf: enabled: true mappings: - topicName: valueProtoType: git: enabled: true repository: url: https://github.com//.git branch: refreshInterval: 10m paths: - ./ basicAuth: enabled: true ``` ###### Kubernetes embedded 1. Create a secret: ```yaml apiVersion: v1 kind: Secret metadata: name: protobuf-git-auth namespace: redpanda type: Opaque stringData: SERDE_PROTOBUF_GIT_BASICAUTH_PASSWORD: ``` 2. Reference the secret and set the username: ###### Operator ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Console metadata: name: redpanda-console spec: clusterRef: name: redpanda extraEnv: - name: SERDE_PROTOBUF_GIT_BASICAUTH_USERNAME value: token extraEnvFrom: - secretRef: name: protobuf-git-auth config: serde: protobuf: enabled: true mappings: - topicName: valueProtoType: git: enabled: true repository: url: https://github.com//.git branch: refreshInterval: 10m paths: - ./ basicAuth: enabled: true ``` ###### Helm ```yaml console: enabled: true extraEnv: - name: SERDE_PROTOBUF_GIT_BASICAUTH_USERNAME value: token extraEnvFrom: - secretRef: name: protobuf-git-auth console: config: serde: protobuf: enabled: true mappings: - topicName: valueProtoType: git: enabled: true repository: url: https://github.com//.git branch: refreshInterval: 10m paths: - ./ basicAuth: enabled: true ``` ###### Kubernetes standalone 1. Create a secret: ```yaml apiVersion: v1 kind: Secret metadata: name: protobuf-git-auth namespace: redpanda type: Opaque stringData: SERDE_PROTOBUF_GIT_BASICAUTH_PASSWORD: ``` 2. Update Helm values: ```yaml config: serde: protobuf: enabled: true mappings: - topicName: valueProtoType: git: enabled: true repository: url: https://github.com//.git branch: refreshInterval: 10m paths: - ./ basicAuth: enabled: true extraEnv: - name: SERDE_PROTOBUF_GIT_BASICAUTH_USERNAME value: token extraEnvFrom: - secretRef: name: protobuf-git-auth ``` Replace the following values: - ``: A GitHub personal access token that has `repo` scope - ``: Kafka topic to be deserialized - ``: Fully qualified Protobuf message type (for example, `com.example.Order`) - ``: GitHub organization or user that owns the repository - ``: Name of the repository containing `.proto` files - ``: Git branch to clone (for example, `main`) #### [](#authenticate-using-ssh)Authenticate using SSH Use this method to authenticate with GitHub over SSH using a private key. ##### Standalone 1. Save the SSH private key on the local filesystem (for example, `/etc/redpanda/ssh/id_rsa`). 2. Set environment variables: ```bash SERDE_PROTOBUF_GIT_SSH_ENABLED=true SERDE_PROTOBUF_GIT_SSH_USERNAME=git SERDE_PROTOBUF_GIT_SSH_PRIVATEKEYFILEPATH=/etc/redpanda/ssh/id_rsa SERDE_PROTOBUF_GIT_SSH_PASSPHRASE= ``` 3. Configure Redpanda Console: ```yaml serde: protobuf: enabled: true mappings: - topicName: valueProtoType: git: enabled: true repository: url: git@github.com:/.git branch: refreshInterval: 10m paths: - ./ ssh: enabled: true ``` ##### Kubernetes embedded 1. Create a secret with the SSH key: ```yaml apiVersion: v1 kind: Secret metadata: name: protobuf-git-ssh namespace: redpanda type: Opaque stringData: privateKey: | -----BEGIN OPENSSH PRIVATE KEY----- -----END OPENSSH PRIVATE KEY----- passphrase: ``` 2. Mount the secret and configure environment variables: ###### Operator ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Console metadata: name: redpanda-console spec: clusterRef: name: redpanda extraVolumeMounts: - name: git-ssh mountPath: /etc/git-ssh readOnly: true extraVolumes: - name: git-ssh secret: secretName: protobuf-git-ssh extraEnv: - name: SERDE_PROTOBUF_GIT_SSH_ENABLED value: "true" - name: SERDE_PROTOBUF_GIT_SSH_USERNAME value: git - name: SERDE_PROTOBUF_GIT_SSH_PRIVATEKEYFILEPATH value: /etc/git-ssh/privateKey - name: SERDE_PROTOBUF_GIT_SSH_PASSPHRASE value: ``` ###### Helm ```yaml console: enabled: true extraVolumeMounts: - name: git-ssh mountPath: /etc/git-ssh readOnly: true extraVolumes: - name: git-ssh secret: secretName: protobuf-git-ssh extraEnv: - name: SERDE_PROTOBUF_GIT_SSH_ENABLED value: "true" - name: SERDE_PROTOBUF_GIT_SSH_USERNAME value: git - name: SERDE_PROTOBUF_GIT_SSH_PRIVATEKEYFILEPATH value: /etc/git-ssh/privateKey - name: SERDE_PROTOBUF_GIT_SSH_PASSPHRASE value: ``` ##### Kubernetes standalone 1. Create a secret: ```yaml apiVersion: v1 kind: Secret metadata: name: protobuf-git-ssh namespace: redpanda type: Opaque stringData: privateKey: | -----BEGIN OPENSSH PRIVATE KEY----- -----END OPENSSH PRIVATE KEY----- passphrase: ``` 2. Update Helm values: ```yaml config: serde: protobuf: enabled: true mappings: - topicName: valueProtoType: git: enabled: true repository: url: git@github.com:/.git branch: refreshInterval: 10m paths: - ./ ssh: enabled: true extraVolumeMounts: - name: git-ssh mountPath: /etc/git-ssh readOnly: true extraVolumes: - name: git-ssh secret: secretName: protobuf-git-ssh extraEnv: - name: SERDE_PROTOBUF_GIT_SSH_ENABLED value: "true" - name: SERDE_PROTOBUF_GIT_SSH_USERNAME value: git - name: SERDE_PROTOBUF_GIT_SSH_PRIVATEKEYFILEPATH value: /etc/git-ssh/privateKey - name: SERDE_PROTOBUF_GIT_SSH_PASSPHRASE value: ``` Replace the following values: - ``: Kafka topic to be deserialized - ``: Fully qualified Protobuf message type (for example, `com.example.Order`) - ``: GitHub organization or user that owns the repository - ``: Name of the repository containing `.proto` files - ``: Git branch to clone (for example, `main`) - ``: SSH private key content used to authenticate to GitHub (must be base64-safe if stored in secrets) - ``: Passphrase used to decrypt the SSH private key, if applicable ## [](#messagepack-deserialization)MessagePack deserialization If your data is serialized using MessagePack, Redpanda Console can be configured to deserialize it. ### Standalone ```yaml serde: messagePack: enabled: true # Define which topics use MessagePack serialization # Regex to match all topics by default topicNames: ["/.*/"] ``` ### Kubernetes embedded #### Operator ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Console metadata: name: redpanda-console spec: clusterRef: name: redpanda config: serde: messagePack: enabled: true topicNames: - "/.*/" ``` #### Helm ```yaml console: enabled: true console: config: serde: messagePack: enabled: true topicNames: ["/.*/"] ``` ### Kubernetes standalone When using the standalone Redpanda Console Helm chart: ```yaml config: serde: messagePack: enabled: true topicNames: ["/.*/"] ``` Apply with: ```bash helm upgrade --install redpanda-console redpanda/console -f console-values.yaml ``` - `serde.messagePack.enabled`: Enables MessagePack deserialization. - `serde.messagePack.topicNames`: A list of topic name regex patterns that specify which topics use MessagePack serialization. The default pattern (`/.*/`) matches all topics. ## [](#best-practices)Best practices - Use Schema Registry when possible. Schema Registry simplifies schema management and ensures that all messages are serialized and deserialized consistently across your Kafka ecosystem. - Organize Protobuf files. Whether using a local file system or a GitHub repository, keep your Protobuf files organized and use consistent naming conventions to avoid confusion. - Monitor deserialization performance. Regularly check the performance impact of deserialization, especially when using complex Protobuf schemas or large numbers of messages. Adjust refresh intervals and schema caching as needed. - Secure access. Ensure that credentials for accessing the Schema Registry or GitHub repositories are securely managed and rotated regularly. ## [](#troubleshooting)Troubleshooting If you encounter issues with deserialization: - Ensure that the Schema Registry URL and credentials are correctly configured and accessible. - Check your topic mappings and Protobuf type names for accuracy. - Review the Redpanda Console for insights into any errors occurring during deserialization. --- # Page 6: Add a License Key to Redpanda Console **URL**: https://docs.redpanda.com/current/console/config/enterprise-license.md --- # Add a License Key to Redpanda Console --- title: Add a License Key to Redpanda Console latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: config/enterprise-license page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: config/enterprise-license.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/console/pages/config/enterprise-license.adoc description: Learn how to apply or update a license key to Redpanda Console. page-git-created-date: "2024-12-03" page-git-modified-date: "2025-12-04" support-status: supported --- Redpanda Console v3.x [Redpanda Console v2.x](../../../../24.3/console/config/enterprise-license/) [Redpanda Console v3.x](./) To enable [enterprise features for Redpanda Console](../../../get-started/licensing/overview/#console), you must have an Enterprise Edition license to load at startup. This guide explains how to configure Redpanda Console to load the license key from its local configuration. > 💡 **TIP** > > This option is best for deployments that are not connected to a Redpanda cluster. If you plan to connect Redpanda Console to a Redpanda cluster, consider uploading the license to the Redpanda cluster. See [Add an Enterprise Edition License to Redpanda Console](../../../get-started/licensing/add-license-console/). ## [](#prerequisites)Prerequisites You must have an Enterprise Edition license. To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). If Redpanda Console has enterprise features enabled and cannot find a valid license locally or in the connected Redpanda cluster, it shuts down. See [Redpanda Licenses and Enterprise Features](../../../get-started/licensing/overview/). ## [](#add-a-new-license-to-redpanda-console)Add a new license to Redpanda Console To add a new license to Redpanda Console, you have two options: - [Provide the path to the license file](#file). - [Provide the license key contents directly](#inline). ### [](#file)Use a license file #### Standalone Set the `licenseFilepath` property in the `/etc/redpanda/redpanda-console-config.yaml` configuration file: ```yaml licenseFilepath: ``` Or set the `REDPANDA_LICENSE_FILEPATH` environment variable: ```bash export REDPANDA_LICENSE_FILEPATH= ``` #### Kubernetes embedded By default, when deploying Redpanda Console with the Redpanda Operator or Redpanda Helm chart, Redpanda Console inherits the license provided to Redpanda in `enterprise.license` or `enterprise.licenseSecretRef`. See [Add an Enterprise Edition License to Redpanda in Kubernetes](../../../get-started/licensing/add-license-redpanda/kubernetes/) for details. You cannot override the inherited license. #### Kubernetes standalone For production deployments, the safest and most secure way to provide your license is to store it in a Kubernetes Secret and reference it using `enterprise.licenseSecretRef` in your `values.yaml`. This keeps sensitive license data out of your Helm values and version control. Example: ```yaml enterprise: licenseSecretRef: name: key: ``` Alternatively, you can set the license directly in your Helm values using `console.config.license` or `console.config.licenseFilepath`, or with environment variables, but these methods are less secure for production environments. ```yaml console: extraEnv: - name: REDPANDA_LICENSE value: ``` Apply with: ```bash helm upgrade --install redpanda-console redpanda/console -f console-values.yaml ``` ### [](#inline)Use the license key contents directly If you don’t want to provide a path to the license file, you can use the contents of the license key directly. #### Standalone Set the `license` property in the `/etc/redpanda/redpanda-console-config.yaml` configuration file: ```yaml license: ``` Or set the `REDPANDA_LICENSE` environment variable: ```bash export REDPANDA_LICENSE= ``` #### Kubernetes embedded By default, when deploying Redpanda Console with the Redpanda Operator or Redpanda Helm chart, Redpanda Console inherits the license provided to Redpanda in `enterprise.license` or `enterprise.licenseSecretRef`. See [Add an Enterprise Edition License to Redpanda in Kubernetes](../../../get-started/licensing/add-license-redpanda/kubernetes/) for details. You cannot override the inherited license. #### Kubernetes standalone For production deployments, the safest and most secure way to provide your license is to store it in a Kubernetes Secret and reference it using `enterprise.licenseSecretRef` in your `values.yaml`. This keeps sensitive license data out of your Helm values and version control. Example: ```yaml enterprise: licenseSecretRef: name: key: ``` Alternatively, you can set the license directly in your Helm values using `console.config.license` or `console.config.licenseFilepath`, or with environment variables, but these methods are less secure for production environments. ```yaml console: extraEnv: - name: REDPANDA_LICENSE value: ``` Apply with: ```bash helm upgrade --install redpanda-console redpanda/console -f console-values.yaml ``` ## [](#update-an-existing-license)Update an existing license To update an existing license: 1. Update your configuration file or environment variables with one of the following: - [The path to your new license file](#file) - [The contents of your new license key](#inline) 2. Restart Redpanda Console to make the changes take effect. ## [](#next-steps)Next steps [Check the Status of Licenses](../../../get-started/licensing/check-status/). ## [](#suggested-reading)Suggested reading - [Redpanda Licensing](../../../get-started/licensing/) - [Manage Enterprise Edition Licenses through Redpanda Console](../../ui/add-license/) --- # Page 7: HTTP Path Rewrites in Redpanda Console **URL**: https://docs.redpanda.com/current/console/config/http-path-rewrites.md --- # HTTP Path Rewrites in Redpanda Console --- title: HTTP Path Rewrites in Redpanda Console latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: config/http-path-rewrites page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: config/http-path-rewrites.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/console/pages/config/http-path-rewrites.adoc description: Learn how to configure Redpanda Console to work with your URL path rewrites, particularly when hosted under a subpath. page-git-created-date: "2024-09-11" page-git-modified-date: "2025-12-04" support-status: supported --- Redpanda Console v3.x [Redpanda Console v2.x](../../../../24.3/console/config/http-path-rewrites/) [Redpanda Console v3.x](./) If you want to host Redpanda Console under a subpath rather than the root path, you need to configure HTTP path rewrites. This allows you to serve Redpanda Console under a subpath of your domain, such as `https://my-company.com/redpanda/console`, instead of directly from `https://my-company.com`. This type of configuration is often necessary when: - You have multiple services and applications running under the same domain. - Redpanda Console is behind a reverse proxy. The proxy might add a path prefix based on routing rules, and Redpanda Console needs to know about this prefix to handle requests correctly. > 📝 **NOTE** > > If you host Redpanda Console at a root path, for example under a sub-domain such as `https://console.redpanda.my-company.com`, you don’t need to configure HTTP path rewrites. ## [](#configuration)Configuration To configure HTTP path rewrites, set the following properties within the `server` object in your Redpanda Console configuration file: | Configuration | Description | Default | | --- | --- | --- | | basePath | The subpath under which Redpanda Console is hosted.If you have a proxy in front of Redpanda Console that sets the X-Forwarded-Prefix header and setBasePathFromXForwardedPrefix is enabled, you do not need to set basePath manually.See Custom subpath scenario. | '' | | setBasePathFromXForwardedPrefix | Tells Redpanda Console to use the X-Forwarded-Prefix header on incoming requests for determining the path prefix.If this header is present, its value will be used as the path prefix, and the value set in basePath will be ignored.See Custom subpath scenario. | true | | stripPrefix | Removes the specified prefix from the request path before routing it to Redpanda Console.If your proxy is configured to remove the prefix, you should disable stripPrefix in Redpanda Console.See Prefix removal scenario. | true | ## [](#custom-subpath-scenario)Custom subpath scenario Consider the following setup where you want to host Redpanda Console at `https://my-company.com/redpanda/console/` and are using a reverse proxy to manage the routing: 1. Nginx is configured to route requests from `/redpanda/console` to Redpanda Console, running on `http://localhost:8080`. ### Standalone Nginx configuration ```nginx location /redpanda/console/ { proxy_pass http://localhost:8080/; proxy_set_header X-Forwarded-Prefix /redpanda/console; } ``` ### Kubernetes ```yaml apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: redpanda-console annotations: # Pass the base-path header through to Redpanda Console nginx.ingress.kubernetes.io/configuration-snippet: | proxy_set_header X-Forwarded-Prefix /redpanda/console; spec: ingressClassName: nginx # or your ingress class name tls: - hosts: - my-company.com secretName: my-company-tls # optional rules: - host: my-company.com http: paths: - path: /redpanda/console pathType: Prefix backend: service: name: redpanda-console # your Service name port: number: 8080 # your Service port ``` 2. Redpanda Console is configured to use the `X-Forwarded-Prefix` header for determining the base path. ### Standalone ```yaml server: setBasePathFromXForwardedPrefix: true stripPrefix: true ``` ### Kubernetes embedded When Redpanda Console is part of the Redpanda Helm chart or Operator: #### Operator ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Console metadata: name: redpanda-console spec: clusterRef: name: redpanda config: server: setBasePathFromXForwardedPrefix: true stripPrefix: true ``` #### Helm ```yaml console: enabled: true console: config: server: setBasePathFromXForwardedPrefix: true stripPrefix: true ``` ### Kubernetes standalone When using the standalone Redpanda Console Helm chart: ```yaml config: server: setBasePathFromXForwardedPrefix: true stripPrefix: true ``` 3. A user navigates to `https://my-company.com/redpanda/console/topics` in their browser. 4. Nginx receives the request and recognizes the `/redpanda/console` subpath. It forwards the request to Redpanda Console at `http://localhost:8080/topics`, while adding the `X-Forwarded-Prefix: /redpanda/console` header. 5. Because `setBasePathFromXForwardedPrefix` is set to `true`, Redpanda Console checks the `X-Forwarded-Prefix` header. It identifies that the base path is `/redpanda/console` and removes this prefix from the incoming request path. The request path `/topics` is now correctly routed in Redpanda Console. If Nginx were configured without the `X-Forwarded-Prefix` header, or if `setBasePathFromXForwardedPrefix` was set to `false`, Redpanda Console would not correctly recognize the subpath, leading to routing issues. This configuration is particularly useful when multiple environments or proxies might route to the same Redpanda Console instance under different subpaths. ## [](#prefix-removal-scenario)Prefix removal scenario Some proxies, such as Traefik, can remove a prefix from the URL path before forwarding it. If both the proxy and Redpanda Console attempt to remove the prefix, Redpanda Console may fail to route the request correctly. Only one part of the stack (either the proxy or Redpanda Console) should remove the prefix. To better understand this problem, consider the following scenario: 1. Traefik is configured to route `/topics` to Redpanda Console with the "StripPrefix" middleware enabled. 2. Redpanda Console is configured with the default settings, which includes `stripPrefix: true`. 3. A user enters the following address in their browser: `example.com/topics/topics/example-topic`. 4. Traefik removes the first `/topics` from the path, leaving `/topics/example-topic`, and sets `/topics` in the `X-Forwarded-Prefix` header. 5. Redpanda Console sees the `X-Forwarded-Prefix` and attempts to remove what it thinks is the prefix. The path becomes `/example-topic`. 6. Redpanda Console then tries to find a handler for `/example-topic`, but no such route exists, leading to a failure. To avoid this issue, either disable `stripPrefix` in Redpanda Console or ensure that the proxy does not modify the request path in a conflicting manner. ## [](#proxy-rewrites)Proxy rewrites If you have a reverse proxy between Redpanda Console and Kafka Connect, ensure that any rewrite rules retain the necessary expand parameters in the query string. These parameters are crucial for Kafka Connect to return the correct details about the connectors: `://:8083/connectors?expand=info&expand=status` This ensures that Redpanda Console can correctly communicate with Kafka Connect even when hosted behind a proxy that rewrites URLs. --- # Page 8: Connect Redpanda Console to Kafka Connect Clusters **URL**: https://docs.redpanda.com/current/console/config/kafka-connect.md --- # Connect Redpanda Console to Kafka Connect Clusters --- title: Connect Redpanda Console to Kafka Connect Clusters latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: config/kafka-connect page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: config/kafka-connect.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/console/pages/config/kafka-connect.adoc description: Learn how to connect one or more Kafka Connect clusters with Redpanda Console. page-git-created-date: "2024-09-11" page-git-modified-date: "2025-12-04" support-status: supported --- Redpanda Console v3.x [Redpanda Console v2.x](../../../../24.3/console/config/kafka-connect/) [Redpanda Console v3.x](./) > 📝 **NOTE: Community** > > **Kafka Connect is community-supported on [Redpanda Community Slack](https://redpanda.com/slack)**. Redpanda Data does not provide enterprise support for Kafka Connect with Redpanda Console. For a supported and scalable Kafka Connect alternative, try [Redpanda Connect](../../../../redpanda-connect/get-started/). Redpanda Console provides a user interface that lets you manage multiple Kafka Connect clusters. You can inspect or patch connectors; restart, pause, and resume connector tasks; and delete connectors. Redpanda Console queries all configured Kafka Connect clusters for their status, so you have an overview of all your Kafka Connect clusters. ## [](#prerequisites)Prerequisites You must [deploy a Kafka Connect cluster separately](../../../deploy/kafka-connect/deploy-kafka-connect/) before configuring Redpanda Console to connect to it. ## [](#configure-a-connection-to-kafka-connect)Configure a connection to Kafka Connect For each cluster, provide a unique name, the HTTP address of the cluster, and the authentication settings, if required. The name can be any unique string that helps you to identify the Kafka Connect cluster. See all available configuration options in the [Redpanda Console Configuration](../configure-console/). ### Standalone ```yaml kafkaConnect: enabled: true clusters: - name: datawarehouse # Required field, will be used as identifier in the frontend url: http://dwh-connect.mycompany.com:8083 tls: enabled: false # Trusted certs are still allowed by default username: admin # password: # Set using flag --kafkaConnect.clusters.0.password=secret - name: analytics # Required field, will be used as identifier in the frontend url: http://analytics.mycompany.com:8083 # No auth configured on that cluster, hence no username/password set ``` ### Kubernetes embedded When Redpanda Console is part of the Redpanda Helm chart or Operator: #### Operator `redpanda-console`.yaml ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Console metadata: name: redpanda-console spec: clusterRef: name: redpanda config: kafkaConnect: enabled: true clusters: - name: datawarehouse url: http://dwh-connect.mycompany.com:8083 tls: enabled: false username: admin # password: (add if needed) - name: analytics url: http://analytics.mycompany.com:8083 # No auth configured on this cluster ``` #### Helm `redpanda-values.yaml` ```yaml console: enabled: true console: config: kafkaConnect: enabled: true clusters: - name: datawarehouse # Required field, will be used as identifier in the frontend url: http://dwh-connect.mycompany.com:8083 tls: enabled: false # Trusted certs are still allowed by default username: admin # password: - name: analytics # Required field, will be used as identifier in the frontend url: http://analytics.mycompany.com:8083 # No auth configured on that cluster, hence no username/password set ``` ### Kubernetes standalone When using the standalone Redpanda Console Helm chart: `console-values.yaml` ```yaml config: kafkaConnect: enabled: true clusters: - name: datawarehouse # Required field, will be used as identifier in the frontend url: http://dwh-connect.mycompany.com:8083 tls: enabled: false # Trusted certs are still allowed by default username: admin # password: - name: analytics # Required field, will be used as identifier in the frontend url: http://analytics.mycompany.com:8083 # No auth configured on that cluster, hence no username/password set ``` --- # Page 9: Redpanda Console Security **URL**: https://docs.redpanda.com/current/console/config/security.md --- # Redpanda Console Security --- title: Redpanda Console Security latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: config/security/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: config/security/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/console/pages/config/security/index.adoc description: Learn about security topics for Redpanda Console. page-git-created-date: "2024-09-11" page-git-modified-date: "2025-12-04" support-status: supported --- Redpanda Console v3.x [Redpanda Console v2.x](../../../../24.3/console/config/security/) [Redpanda Console v3.x](./) - [Authentication in Redpanda Console](authentication/) Learn how authentication in Redpanda Console enables users to log in and optionally forward their credentials to the connected Redpanda cluster, ensuring all API requests are executed under the user's identity. - [Authorization in Redpanda Console](authorization/) Learn how to configure role-based access control (RBAC) in Redpanda Console to restrict system access to authorized users. - [TLS Termination in Redpanda Console](tls-termination/) Learn how to secure Redpanda Console using TLS, either by letting Redpanda Console handle TLS termination or by offloading it to an upstream component, such as a reverse proxy or a Cloud HTTPS LoadBalancer. --- # Page 10: Authentication in Redpanda Console **URL**: https://docs.redpanda.com/current/console/config/security/authentication.md --- # Authentication in Redpanda Console --- title: Authentication in Redpanda Console latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: config/security/authentication page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: config/security/authentication.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/console/pages/config/security/authentication.adoc description: Learn how authentication in Redpanda Console enables users to log in and optionally forward their credentials to the connected Redpanda cluster, ensuring all API requests are executed under the user's identity. page-git-created-date: "2024-09-11" page-git-modified-date: "2026-01-28" support-status: supported --- Redpanda Console v3.x [Redpanda Console v2.x](../../../../../24.3/console/config/security/authentication/) [Redpanda Console v3.x](./) > 📝 **NOTE** > > This feature requires an [enterprise license](../../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda Console has enterprise features enabled and it cannot find a valid license, it redirects you to the license expiration landing page, and all other access is restricted. This topic describes how to enable authentication in Redpanda Console and how it integrates with the Kafka, Admin, and Schema Registry APIs in Redpanda. Authentication in Redpanda Console lets users log in and optionally forward their credentials to the connected cluster. This ensures API requests run under the user’s identity. Redpanda Console supports the following authentication methods: - **OIDC (OpenID Connect):** Integrates with external identity providers (IdPs) for single sign-on (SSO). - **Basic authentication:** Uses traditional username and password credentials. ![login](../../../_images/login.png) ## [](#how-authentication-works)How authentication works Redpanda Console can authenticate to Redpanda APIs in two ways: - **User impersonation:** Uses the same credentials you log in with to authenticate API requests. This ensures accurate audit logs and unified identity enforcement. - **Static service account credentials:** Uses preconfigured credentials defined in the Redpanda Console configuration file. Useful when impersonation is disabled or [RBAC](https://docs.redpanda.com/current/reference/glossary/#rbac) needs to be separated from Redpanda identities. Upon login, Redpanda Console generates a secure session with a JSON Web Token (JWT), signed by the `authentication.jwtSigningKey`. The JWT can be stored as a secure cookie and is used to authenticate API requests. For OIDC-based login flows, Redpanda Console reuses the OAuth 2.0 access token from the identity provider (IdP) to authenticate to Redpanda’s Kafka and HTTP APIs. These access tokens must be in JWT format to be compatible with Redpanda’s SASL/OAUTHBEARER authentication. Some IdPs, such as Google, issue opaque access tokens that are not JWTs. While these tokens work for logging in to Redpanda Console (the ID token is a JWT), they cannot be used for impersonation with the Kafka API. In such cases, impersonation must be disabled, and Redpanda Console must be configured to use static service account credentials instead. flowchart TD A((User authenticates with OIDC or SASL credentials)) --> B\[Redpanda Console\] B --> C\["Re-use OIDC token or basic credentials (if configured)"\] B --> D\[Get credentials from Redpanda Console config\] C --> E\[Kafka API\] C --> F\[Admin API\] C --> G\[Schema API\] E & F & G --> H((Redpanda)) D --> J\[Kafka Connect API\] D --> L\[Git\] Figure 1. Redpanda Console authenticates users and then authorizes their access based on the impersonation mode and configured RBAC or ACLs. ## [](#prerequisites)Prerequisites - You must have at least one superuser in Redpanda. - The authentication method used in Redpanda Console must match the configuration of the Kafka API: - **If using OIDC:** You must have SASL/OAUTHBEARER authentication configured for the Kafka API. - **If using basic authentication:** You must have SASL/SCRAM authentication configured for the Kafka API. [Learn how to configure authentication for Redpanda](../../../../manage/security/authentication/). ## [](#enable-authentication)Enable authentication Redpanda Console supports enabling both OIDC and basic authentication simultaneously. If both are enabled, users can choose how to log in. ### [](#enable-oidc-authentication)Enable OIDC authentication When you enable OIDC authentication, Redpanda Console uses an external IdP to authenticate users. This allows for single sign-on (SSO) and centralized user management. Redpanda and Redpanda Console require OAuth 2.0-compliant JWT tokens for user authentication. When using OIDC, your IdP must issue JWTs. Redpanda Console uses these tokens to authenticate to Redpanda APIs through SASL/OAUTHBEARER or Bearer headers. #### Standalone ```yaml authentication: jwtSigningKey: "" (1) useSecureCookies: false (2) oidc: enabled: true (3) issuerUrl: "https://login.microsoftonline.com/a5da3be7-35c1-44ff-b6e8-b3b755686ae2/v2.0" (4) clientId: "" (5) clientSecret: "" (6) additionalScopes: - "" (7) issuerTls: enabled: true (8) caFilepath: "/path/to/ca.pem" certFilepath: "/path/to/issuer-cert.pem" keyFilepath: "/path/to/issuer-key.pem" insecureSkipTlsVerify: false redirectUrl: "http://localhost:8080/auth/callbacks/oidc" (9) accessType: "offline" (10) prompt: "consent" (11) principalMapping: "$.sub" (12) ``` #### Kubernetes embedded When using the Redpanda Operator or the Redpanda Helm chart, configure Redpanda Console authentication through the cluster configuration: ##### Operator ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: clusterSpec: console: enabled: true console: config: authentication: jwtSigningKey: "" (1) useSecureCookies: false (2) oidc: enabled: true (3) issuerUrl: "https://login.microsoftonline.com/a5da3be7-35c1-44ff-b6e8-b3b755686ae2/v2.0" (4) clientId: "" (5) clientSecret: "" (6) additionalScopes: - "" (7) issuerTls: enabled: true (8) caFilepath: "/path/to/ca.pem" certFilepath: "/path/to/issuer-cert.pem" keyFilepath: "/path/to/issuer-key.pem" insecureSkipTlsVerify: false redirectUrl: "http://localhost:8080/auth/callbacks/oidc" (9) accessType: "offline" (10) prompt: "consent" (11) principalMapping: "$.sub" (12) ``` ##### Helm ```yaml console: enabled: true console: config: authentication: jwtSigningKey: "" (1) useSecureCookies: false (2) oidc: enabled: true (3) issuerUrl: "https://login.microsoftonline.com/a5da3be7-35c1-44ff-b6e8-b3b755686ae2/v2.0" (4) clientId: "" (5) clientSecret: "" (6) additionalScopes: - "" (7) issuerTls: enabled: true (8) caFilepath: "/path/to/ca.pem" certFilepath: "/path/to/issuer-cert.pem" keyFilepath: "/path/to/issuer-key.pem" insecureSkipTlsVerify: false redirectUrl: "http://localhost:8080/auth/callbacks/oidc" (9) accessType: "offline" (10) prompt: "consent" (11) principalMapping: "$.sub" (12) ``` #### Kubernetes standalone When using the standalone Redpanda Console Helm chart, configure OIDC in your Helm values: ```yaml config: authentication: jwtSigningKey: "" (1) useSecureCookies: false (2) oidc: enabled: true (3) issuerUrl: "https://login.microsoftonline.com/a5da3be7-35c1-44ff-b6e8-b3b755686ae2/v2.0" (4) clientId: "" (5) clientSecret: "" (6) additionalScopes: - "" (7) issuerTls: enabled: true (8) caFilepath: "/path/to/ca.pem" certFilepath: "/path/to/issuer-cert.pem" keyFilepath: "/path/to/issuer-key.pem" insecureSkipTlsVerify: false redirectUrl: "http://localhost:8080/auth/callbacks/oidc" (9) accessType: "offline" (10) prompt: "consent" (11) principalMapping: "$.sub" (12) ``` Apply with: ```bash helm upgrade --install redpanda-console redpanda/console -f console-values.yaml ``` | 1 | Required. Secret key for signing JWTs. Must be at least 32 characters. Store securely. You can also use the AUTHENTICATION_JWTSIGNINGKEY environment variable. | | --- | --- | | 2 | Recommended in production. Marks cookies as secure. | | 3 | Required. Enables OIDC authentication. | | 4 | Required. URL of the OIDC identity provider (IdP). | | 5 | Required. The client ID from your IdP. | | 6 | Required. The client secret from your IdP. You can also use the AUTHENTICATION_OIDC_CLIENTSECRET environment variable. | | 7 | Requested scopes. Some IdPs such as Azure Entra ID require additional scopes to request OAuth 2.0-compliant tokens. | | 8 | Optional. TLS configuration for secure connections to the IdP. Configure TLS only if you require mTLS or use a self-signed certificate. | | 9 | Optional. Redirect URI registered with the IdP. This URI must point to the /auth/callbacks/oidc path in Redpanda Console. If not set, Redpanda Console constructs the URL from the request. Configure this option explicitly if you’re using HTTP path rewrites. | | 10 | Optional. Controls whether a refresh token is requested. offline (default) requests a refresh token. Set to online to disable refresh token requests. | | 11 | Optional. Determines how the authorization prompt appears. Use consent (default) to force re-consent. Other options include none and select_account. Some IdPs require consent to issue a refresh token. | | 12 | Optional. Extracts and optionally transforms a claim from the OIDC token to use as the user’s identity in Redpanda Console role bindings. The default is "$.sub", which uses the sub (subject) claim from the token. This value is then compared to the name field in your authorization.roleBindings configuration. For full syntax and transformation examples, see Transform identities with principal mappings. | > ❗ **IMPORTANT** > > For any secret values, [use environment variables](../../configure-console/) instead of hardcoding them in the configuration file. For example, use `AUTHENTICATION_OIDC_CLIENTSECRET` for the client secret. #### [](#oidc-limitations)OIDC limitations - Redpanda requires JWT-formatted access tokens (not ID tokens) for Kafka API authentication using SASL/OAUTHBEARER. Access tokens issued by some IdPs, such as Google, are opaque and not supported. - The `rpk` CLI does not support OIDC login. - Redpanda requires OIDC principals to be set as superusers to access the Admin API. Granular authorization is not supported. - The `rpk` CLI does not support the SASL/OAUTHBEARER mechanism for deploying data transforms. Use SASL/SCRAM instead. #### [](#supported-identity-providers)Supported identity providers You can use any OIDC-compliant IdP with Redpanda Console. Here are common providers: | Provider | Example issuerUrl | | --- | --- | | Okta | https:///oauth2/default | | Microsoft Entra ID (Azure AD) | https://login.microsoftonline.com//v2.0 | | Keycloak | https:///realms/ | Some IdPs, such as Google, issue opaque access tokens that are not JWTs. While these tokens work for logging in to Redpanda Console (the ID token is a JWT), they cannot be used for impersonation with the Kafka API. In such cases, impersonation must be disabled, and Redpanda Console must be configured to use static service account credentials instead. For example, this is how to configure Redpanda Console with Entra ID: ##### Standalone ```yaml authentication: jwtSigningKey: vazxnT+ZHtxKslK6QlDGovcYnSjTk/lKMmZ+mHrBVE+YdVDkLgSuP6AszAKe9Gvq basic: enabled: true oidc: enabled: true issuerUrl: "https://login.microsoftonline.com//v2.0" clientId: "" clientSecret: "" redirectUrl: "http://localhost:8080/auth/callbacks/oidc" accessType: "offline" prompt: "consent" additionalScopes: - "api:///entraid.v2-access-tokens" (1) ``` ##### Kubernetes embedded When using the Redpanda Operator or the Redpanda Helm chart, configure Redpanda Console authentication through the cluster configuration: ###### Operator ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: clusterSpec: console: enabled: true console: config: authentication: jwtSigningKey: vazxnT+ZHtxKslK6QlDGovcYnSjTk/lKMmZ+mHrBVE+YdVDkLgSuP6AszAKe9Gvq basic: enabled: true oidc: enabled: true issuerUrl: "https://login.microsoftonline.com//v2.0" clientId: "" clientSecret: "" redirectUrl: "http://localhost:8080/auth/callbacks/oidc" accessType: "offline" prompt: "consent" additionalScopes: - "api:///entraid.v2-access-tokens" (1) ``` ###### Helm ```yaml console: enabled: true console: config: authentication: jwtSigningKey: vazxnT+ZHtxKslK6QlDGovcYnSjTk/lKMmZ+mHrBVE+YdVDkLgSuP6AszAKe9Gvq basic: enabled: true oidc: enabled: true issuerUrl: "https://login.microsoftonline.com//v2.0" clientId: "" clientSecret: "" redirectUrl: "http://localhost:8080/auth/callbacks/oidc" accessType: "offline" prompt: "consent" additionalScopes: - "api:///entraid.v2-access-tokens" (1) ``` ##### Kubernetes standalone When using the standalone Redpanda Console Helm chart, configure authentication in your Helm values: ```yaml config: authentication: jwtSigningKey: vazxnT+ZHtxKslK6QlDGovcYnSjTk/lKMmZ+mHrBVE+YdVDkLgSuP6AszAKe9Gvq basic: enabled: true oidc: enabled: true issuerUrl: "https://login.microsoftonline.com//v2.0" clientId: "" clientSecret: "" redirectUrl: "http://localhost:8080/auth/callbacks/oidc" accessType: "offline" prompt: "consent" additionalScopes: - "api:///entraid.v2-access-tokens" (1) ``` Apply with: ```bash helm upgrade --install redpanda-console redpanda/console -f console-values.yaml ``` | 1 | In Entra ID, scopes are required to explicitly request OAuth 2.0-compliant access tokens. See Microsoft documentation for more information. | | --- | --- | #### [](#connect-clients-to-redpanda)Connect clients to Redpanda When using OIDC, clients authenticate to Redpanda using OAuth 2.0 access tokens (JWTs). These tokens are issued by your identity provider (IdP) and must be refreshed before they expire. Token refresh can be handled in different ways depending on the Kafka client library. For example, with [KafkaJS](https://kafka.js.org/docs/configuration#oauthbearer-example), use the `oauthBearerProvider` option to provide a token refresh function. ### [](#enable-basic-authentication)Enable basic authentication To configure basic authentication, choose the configuration method that matches your deployment: #### Standalone ```yaml authentication: jwtSigningKey: "" (1) useSecureCookies: true (2) basic: enabled: true (3) ``` #### Kubernetes embedded When Redpanda Console is part of the Redpanda Helm chart or Operator: ##### Operator `redpanda-cluster`.yaml ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: clusterSpec: console: enabled: true console: config: authentication: jwtSigningKey: "" (1) useSecureCookies: true (2) basic: enabled: true (3) ``` ##### Helm `redpanda-values.yaml` ```yaml console: enabled: true console: config: authentication: jwtSigningKey: "" (1) useSecureCookies: true (2) basic: enabled: true (3) ``` #### Kubernetes standalone When using the standalone Redpanda Console Helm chart: `console-values.yaml` ```yaml config: authentication: jwtSigningKey: "" (1) useSecureCookies: true (2) basic: enabled: true (3) ``` | 1 | Required. Secret key for JWTs. Must be at least 32 characters. | | --- | --- | | 2 | Recommended in production. Marks cookies as secure. | | 3 | Required. Enables username/password login. | #### [](#connect-clients-to-redpanda-2)Connect clients to Redpanda When using basic authentication, clients authenticate to Redpanda using a SASL/SCRAM username and password. The credentials must match a user configured in the Redpanda cluster. Most Kafka client libraries support SASL/SCRAM out of the box. You must configure the client with: - `sasl.mechanism`: One of `SCRAM-SHA-256` or `SCRAM-SHA-512` - `sasl.username`: The Redpanda username - `sasl.password`: The corresponding password ## [](#configure-session-duration)Configure session duration By default, Redpanda Console sessions remain valid for one year. For enterprise deployments, you can limit the maximum session duration using the `maximumSessionAge` configuration parameter. When a session exceeds the configured maximum age, users must re-authenticate to continue using Redpanda Console. ### Standalone ```yaml authentication: jwtSigningKey: "" useSecureCookies: true maximumSessionAge: "90d" (1) basic: enabled: true ``` ### Kubernetes embedded When using the Redpanda Operator or the Redpanda Helm chart: #### Operator ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: clusterSpec: console: enabled: true console: config: authentication: jwtSigningKey: "" useSecureCookies: true maximumSessionAge: "90d" (1) basic: enabled: true ``` #### Helm ```yaml console: enabled: true console: config: authentication: jwtSigningKey: "" useSecureCookies: true maximumSessionAge: "90d" (1) basic: enabled: true ``` ### Kubernetes standalone ```yaml config: authentication: jwtSigningKey: "" useSecureCookies: true maximumSessionAge: "90d" (1) basic: enabled: true ``` | 1 | Maximum duration for browser sessions. Accepts duration strings such as 90d (90 days), 24h (24 hours), or 30m (30 minutes). If not specified, sessions remain valid for one year. | | --- | --- | ## [](#configure-api-authentication)Configure API authentication After enabling authentication, you must configure how Redpanda Console authenticates to each Redpanda API: Kafka, Admin, and Schema Registry. Choose one method per API: - **User impersonation:** Uses the login credentials of the current user. - **Static credentials:** Uses preconfigured credentials of a superuser to communicate with Redpanda, and role bindings to control access in Redpanda Console for logged in users. > 💡 **TIP** > > Redpanda Data recommends user impersonation so that access control is fine-grained and centralized within Redpanda. This way, audit logs are also more accurate, as they reflect the actual user identity. > 📝 **NOTE** > > When using OIDC with static credentials, Redpanda Console authenticates to Redpanda as the OIDC client itself (usually a service principal). In this case, Redpanda evaluates access based on the `sub` claim in the token. Ensure you grant ACLs for your principals. For help creating ACLs, see [Configure Access Control Lists](../../../../manage/security/authorization/acl/). ### [](#kafka-api-examples)Kafka API examples This section provides examples of how to configure authentication for communicating with the Kafka API from Redpanda Console. You can choose between user impersonation or static credentials. #### [](#user-impersonation)User impersonation This option is useful when you want to use the same login credentials to authenticate Kafka API requests in Redpanda. This ensures accurate audit logs and enforces unified identity. ##### Standalone ```yaml kafka: brokers: ["broker1:9092"] sasl: enabled: true impersonateUser: true ``` ##### Kubernetes embedded When using the Redpanda Operator or the Redpanda Helm chart, configure Kafka authentication through the cluster configuration: ###### Operator ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: clusterSpec: console: enabled: true console: config: kafka: sasl: enabled: true impersonateUser: true ``` ###### Helm ```yaml console: enabled: true console: config: kafka: sasl: enabled: true impersonateUser: true ``` ##### Kubernetes standalone When using the standalone Redpanda Console Helm chart: ```yaml config: kafka: brokers: ["broker1:9092"] sasl: enabled: true impersonateUser: true ``` Apply with: ```bash helm upgrade --install redpanda-console redpanda/console -f console-values.yaml ``` #### [](#static-credentials-with-scram)Static credentials with SCRAM This option is useful when you want to use basic authentication. Redpanda Console uses the provided credentials for authentication. ##### Standalone ```yaml kafka: brokers: ["broker1:9092"] sasl: enabled: true impersonateUser: false username: "console-superuser" password: "superuser-password" mechanism: "SCRAM-SHA-256" authorization: roleBindings: - roleName: viewer users: - loginType: basic name: "matt" ``` ##### Kubernetes embedded When using the Redpanda Operator or the Redpanda Helm chart, configure Kafka authentication through the cluster configuration: ###### Operator ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: clusterSpec: console: enabled: true console: config: kafka: sasl: enabled: true impersonateUser: false username: "console-superuser" password: "superuser-password" mechanism: "SCRAM-SHA-256" authorization: roleBindings: - roleName: viewer users: - loginType: basic name: "matt" ``` ###### Helm ```yaml console: enabled: true console: config: kafka: sasl: enabled: true impersonateUser: false username: "console-superuser" password: "superuser-password" mechanism: "SCRAM-SHA-256" authorization: roleBindings: - roleName: viewer users: - loginType: basic name: "matt" ``` ##### Kubernetes standalone When using the standalone Redpanda Console Helm chart: ```yaml config: kafka: brokers: ["broker1:9092"] sasl: enabled: true impersonateUser: false username: "console-superuser" password: "superuser-password" mechanism: "SCRAM-SHA-256" authorization: roleBindings: - roleName: viewer users: - loginType: basic name: "matt" ``` Apply with: ```bash helm upgrade --install redpanda-console redpanda/console -f console-values.yaml ``` #### [](#static-credentials-with-oidc-token-acquired-at-runtime)Static credentials with OIDC (token acquired at runtime) This option is useful when you want to use OIDC. This configuration instructs Redpanda Console to fetch an OAuth 2.0 access token at runtime using the client credentials grant flow. ##### Standalone ```yaml kafka: brokers: ["broker1:9092"] sasl: enabled: true impersonateUser: false mechanism: OAUTHBEARER oauth: clientId: "" (1) clientSecret: "" (2) tokenEndpoint: "https://login.microsoftonline.com//oauth2/v2.0/token" (3) scope: "api:///.default" (4) ``` ##### Kubernetes embedded When using the Redpanda Operator or the Redpanda Helm chart, configure Kafka authentication through the cluster configuration: ###### Operator ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: clusterSpec: console: enabled: true console: config: kafka: sasl: enabled: true impersonateUser: false mechanism: OAUTHBEARER oauth: clientId: "" (1) clientSecret: "" (2) tokenEndpoint: "https://login.microsoftonline.com//oauth2/v2.0/token" (3) scope: "api:///.default" (4) ``` ###### Helm ```yaml console: enabled: true console: config: kafka: sasl: enabled: true impersonateUser: false mechanism: OAUTHBEARER oauth: clientId: "" (1) clientSecret: "" (2) tokenEndpoint: "https://login.microsoftonline.com//oauth2/v2.0/token" (3) scope: "api:///.default" (4) ``` ##### Kubernetes standalone When using the standalone Redpanda Console Helm chart: ```yaml config: kafka: brokers: ["broker1:9092"] sasl: enabled: true impersonateUser: false mechanism: OAUTHBEARER oauth: clientId: "" (1) clientSecret: "" (2) tokenEndpoint: "https://login.microsoftonline.com//oauth2/v2.0/token" (3) scope: "api:///.default" (4) ``` Apply with: ```bash helm upgrade --install redpanda-console redpanda/console -f console-values.yaml ``` | 1 | Client ID registered with the identity provider (IdP). | | --- | --- | | 2 | Client secret associated with the client ID. Store securely using an environment variable, such as KAFKA_SASL_OAUTH_CLIENTSECRET. | | 3 | OAuth 2.0 token endpoint URL provided by the IdP. | | 4 | Requested scope to authorize access. Required by some IdPs, such as Azure Entra ID. | #### [](#static-credentials-with-oidc-pre-acquired-token)Static credentials with OIDC (pre-acquired token) This option is suitable when a token is issued externally and injected into the environment (for example, through CI/CD, Vault, or other automation workflows). Redpanda Console does not attempt to refresh or renew the token. ##### Standalone ```yaml kafka: brokers: ["broker1:9092"] sasl: enabled: true impersonateUser: false mechanism: OAUTHBEARER oauth: token: "" (1) ``` | 1 | A valid OAuth 2.0 JWT. Redpanda Console uses this token when authenticating to Kafka. To avoid hardcoding sensitive data, provide this value using the KAFKA_SASL_OAUTH_TOKEN environment variable. | | --- | --- | ##### Kubernetes embedded When using the Redpanda Operator or the Redpanda Helm chart, configure Kafka authentication through the cluster configuration: | 1 | A valid OAuth 2.0 JWT. Redpanda Console uses this token when authenticating to Kafka. To avoid hardcoding sensitive data, provide this value using the KAFKA_SASL_OAUTH_TOKEN environment variable. | | --- | --- | ###### Operator ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: clusterSpec: console: enabled: true console: config: kafka: sasl: enabled: true impersonateUser: false mechanism: OAUTHBEARER oauth: token: "" (1) ``` ###### Helm ```yaml console: enabled: true console: config: kafka: sasl: enabled: true impersonateUser: false mechanism: OAUTHBEARER oauth: token: "" (1) ``` ##### Kubernetes standalone When using the standalone Redpanda Console Helm chart: ```yaml config: kafka: brokers: ["broker1:9092"] sasl: enabled: true impersonateUser: false mechanism: OAUTHBEARER oauth: token: "" (1) ``` | 1 | A valid OAuth 2.0 JWT. Redpanda Console uses this token when authenticating to Kafka. To avoid hardcoding sensitive data, provide this value using the KAFKA_SASL_OAUTH_TOKEN environment variable. | | --- | --- | Apply with: ```bash helm upgrade --install redpanda-console redpanda/console -f console-values.yaml ``` #### [](#static-credentials-with-oidc-token-from-file)Static credentials with OIDC (token from file) This option is useful when running Redpanda Console in Kubernetes, where a service account token is mounted to the Pod filesystem. Redpanda Console reads this token at startup and uses it for authentication. Redpanda Console does not monitor the token file for changes after startup. To ensure the token is refreshed, restart the Redpanda Console periodically or implement a sidecar that triggers restarts on token rotation. ##### Standalone ```yaml kafka: brokers: ["broker1:9092"] sasl: enabled: true impersonateUser: false mechanism: OAUTHBEARER oauth: tokenFilepath: "/var/run/secrets/kafka/serviceaccount/token" (1) ``` | 1 | Path to a file containing a valid OAuth 2.0 JWT token. Redpanda Console reads this file at startup and uses its contents as the access token. | | --- | --- | ##### Kubernetes embedded When using the Redpanda Operator or the Redpanda Helm chart, configure Kafka authentication through the cluster configuration: | 1 | Path to a file containing a valid OAuth 2.0 JWT token. Redpanda Console reads this file at startup and uses its contents as the access token. | | --- | --- | ###### Operator ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: clusterSpec: console: enabled: true console: config: kafka: sasl: enabled: true impersonateUser: false mechanism: OAUTHBEARER oauth: tokenFilepath: "/var/run/secrets/kafka/serviceaccount/token" (1) ``` ###### Helm ```yaml console: enabled: true console: config: kafka: sasl: enabled: true impersonateUser: false mechanism: OAUTHBEARER oauth: tokenFilepath: "/var/run/secrets/kafka/serviceaccount/token" (1) ``` ##### Kubernetes standalone When using the standalone Redpanda Console Helm chart: ```yaml config: kafka: brokers: ["broker1:9092"] sasl: enabled: true impersonateUser: false mechanism: OAUTHBEARER oauth: tokenFilepath: "/var/run/secrets/kafka/serviceaccount/token" (1) ``` | 1 | Path to a file containing a valid OAuth 2.0 JWT token. Redpanda Console reads this file at startup and uses its contents as the access token. | | --- | --- | Apply with: ```bash helm upgrade --install redpanda-console redpanda/console -f console-values.yaml ``` ### [](#schema-registry-api-examples)Schema Registry API examples This section provides examples of how to configure authentication for communicating with the Schema Registry API from Redpanda Console. You can choose between user impersonation or static credentials. #### [](#user-impersonation-2)User impersonation This option is useful when you want to use the same login credentials to authenticate API requests in the Schema Registry. This ensures accurate audit logs and enforces unified identity. ##### Standalone ```yaml schemaRegistry: urls: ["broker1:8081"] authentication: enabled: true impersonateUser: true ``` ##### Kubernetes embedded When using the Redpanda Operator or the Redpanda Helm chart, configure Schema Registry authentication through the cluster configuration: ###### Operator ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: clusterSpec: console: enabled: true console: config: schemaRegistry: authentication: enabled: true impersonateUser: true ``` ###### Helm ```yaml console: enabled: true console: config: schemaRegistry: authentication: enabled: true impersonateUser: true ``` ##### Kubernetes standalone When using the standalone Redpanda Console Helm chart: ```yaml config: schemaRegistry: urls: ["broker1:8081"] authentication: enabled: true impersonateUser: true ``` Apply with: ```bash helm upgrade --install redpanda-console redpanda/console -f console-values.yaml ``` #### [](#static-credentials-with-basic-auth)Static credentials with basic auth This option is useful when you want to use basic authentication. Redpanda Console uses the provided credentials for authentication. ##### Standalone ```yaml schemaRegistry: urls: ["broker1:8081"] authentication: enabled: true impersonateUser: false basic: username: "console-superuser" password: "superuser-password" authorization: roleBindings: - roleName: editor users: - loginType: basic name: "matt" ``` ##### Kubernetes embedded When using the Redpanda Operator or the Redpanda Helm chart, configure Schema Registry authentication through the cluster configuration: ###### Operator ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: clusterSpec: console: enabled: true console: config: schemaRegistry: authentication: enabled: true impersonateUser: false basic: username: "console-superuser" password: "superuser-password" authorization: roleBindings: - roleName: editor users: - loginType: basic name: "matt" ``` ###### Helm ```yaml console: enabled: true console: config: schemaRegistry: authentication: enabled: true impersonateUser: false basic: username: "console-superuser" password: "superuser-password" authorization: roleBindings: - roleName: editor users: - loginType: basic name: "matt" ``` ##### Kubernetes standalone When using the standalone Redpanda Console Helm chart: ```yaml config: schemaRegistry: urls: ["broker1:8081"] authentication: enabled: true impersonateUser: false basic: username: "console-superuser" password: "superuser-password" authorization: roleBindings: - roleName: editor users: - loginType: basic name: "matt" ``` Apply with: ```bash helm upgrade --install redpanda-console redpanda/console -f console-values.yaml ``` #### [](#static-credentials-with-oidc-bearer-token)Static credentials with OIDC bearer token This option is useful when you want to use OIDC but do not want to implement a custom token refresh mechanism. Redpanda Console uses a pre-fetched token for authentication. ##### Standalone ```yaml schemaRegistry: urls: ["broker1:8081"] authentication: enabled: true impersonateUser: false bearerToken: "" authorization: roleBindings: - roleName: editor users: - loginType: OIDC name: "" ``` ##### Kubernetes embedded When using the Redpanda Operator or the Redpanda Helm chart, configure Schema Registry authentication through the cluster configuration: ###### Operator ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: clusterSpec: console: enabled: true console: config: schemaRegistry: authentication: enabled: true impersonateUser: false bearerToken: "" authorization: roleBindings: - roleName: editor users: - loginType: OIDC name: "" ``` ###### Helm ```yaml console: enabled: true console: config: schemaRegistry: authentication: enabled: true impersonateUser: false bearerToken: "" authorization: roleBindings: - roleName: editor users: - loginType: OIDC name: "" ``` ##### Kubernetes standalone When using the standalone Redpanda Console Helm chart: ```yaml config: schemaRegistry: urls: ["broker1:8081"] authentication: enabled: true impersonateUser: false bearerToken: "" authorization: roleBindings: - roleName: editor users: - loginType: OIDC name: "" ``` Apply with: ```bash helm upgrade --install redpanda-console redpanda/console -f console-values.yaml ``` > 📝 **NOTE** > > You can supply a static bearer token here, but this token must be refreshed manually before it expires. For automatic token acquisition, configure a background token refresher or consider using impersonation where possible. ### [](#admin-api-examples)Admin API examples This section provides examples of how to configure authentication for communicating with the Admin API from Redpanda Console. You can choose between user impersonation or static credentials. #### [](#user-impersonation-3)User impersonation This option is useful when you want to use the same login credentials to authenticate API requests in the Admin API. This ensures accurate audit logs and enforces unified identity. ##### Standalone ```yaml redpanda: adminApi: enabled: true urls: ["broker1:9644"] authentication: impersonateUser: true ``` ##### Kubernetes embedded When using the Redpanda Operator or the Redpanda Helm chart, configure Admin API authentication through the cluster configuration: ###### Operator ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: clusterSpec: console: enabled: true console: config: redpanda: adminApi: enabled: true authentication: impersonateUser: true ``` ###### Helm ```yaml console: enabled: true console: config: redpanda: adminApi: enabled: true authentication: impersonateUser: true ``` ##### Kubernetes standalone When using the standalone Redpanda Console Helm chart: ```yaml config: redpanda: adminApi: enabled: true urls: ["broker1:9644"] authentication: impersonateUser: true ``` Apply with: ```bash helm upgrade --install redpanda-console redpanda/console -f console-values.yaml ``` #### [](#static-credentials-with-basic-auth-2)Static credentials with basic auth This option is useful when you want to use basic authentication. Redpanda Console uses the provided credentials for authentication. ##### Standalone ```yaml redpanda: adminApi: enabled: true urls: ["broker1:9644"] authentication: impersonateUser: false basic: username: "console-superuser" password: "superuser-password" authorization: roleBindings: - roleName: admin users: - loginType: basic name: "matt" ``` ##### Kubernetes embedded When using the Redpanda Operator or the Redpanda Helm chart, configure Admin API authentication through the cluster configuration: ###### Operator ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: clusterSpec: console: enabled: true console: config: redpanda: adminApi: enabled: true authentication: impersonateUser: false basic: username: "console-superuser" password: "superuser-password" authorization: roleBindings: - roleName: admin users: - loginType: basic name: "matt" ``` ###### Helm ```yaml console: enabled: true console: config: redpanda: adminApi: enabled: true authentication: impersonateUser: false basic: username: "console-superuser" password: "superuser-password" authorization: roleBindings: - roleName: admin users: - loginType: basic name: "matt" ``` ##### Kubernetes standalone When using the standalone Redpanda Console Helm chart: ```yaml config: redpanda: adminApi: enabled: true urls: ["broker1:9644"] authentication: impersonateUser: false basic: username: "console-superuser" password: "superuser-password" authorization: roleBindings: - roleName: admin users: - loginType: basic name: "matt" ``` Apply with: ```bash helm upgrade --install redpanda-console redpanda/console -f console-values.yaml ``` #### [](#static-credentials-with-oidc-bearer-token-2)Static credentials with OIDC bearer token This option is useful when you want to use OIDC but do not want to implement a custom token refresh mechanism. Redpanda Console uses a pre-fetched token for authentication. ##### Standalone ```yaml redpanda: adminApi: enabled: true urls: ["broker1:9644"] authentication: impersonateUser: false bearerToken: "" authorization: roleBindings: - roleName: admin users: - loginType: OIDC name: "" ``` ##### Kubernetes embedded When using the Redpanda Operator or the Redpanda Helm chart, configure Admin API authentication through the cluster configuration: ###### Operator ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: clusterSpec: console: enabled: true console: config: redpanda: adminApi: enabled: true authentication: impersonateUser: false bearerToken: "" authorization: roleBindings: - roleName: admin users: - loginType: OIDC name: "" ``` ###### Helm ```yaml console: enabled: true console: config: redpanda: adminApi: enabled: true authentication: impersonateUser: false bearerToken: "" authorization: roleBindings: - roleName: admin users: - loginType: OIDC name: "" ``` ##### Kubernetes standalone When using the standalone Redpanda Console Helm chart: ```yaml config: redpanda: adminApi: enabled: true urls: ["broker1:9644"] authentication: impersonateUser: false bearerToken: "" authorization: roleBindings: - roleName: admin users: - loginType: OIDC name: "" ``` Apply with: ```bash helm upgrade --install redpanda-console redpanda/console -f console-values.yaml ``` ## [](#next-steps)Next steps - [Configure role-based access control (RBAC) in Redpanda Console](../authorization/) - [Configure authentication for Redpanda APIs](../../../../manage/security/authentication/) ## Suggested labs - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) [Search all labs](/redpanda-labs) --- # Page 11: Authorization in Redpanda Console **URL**: https://docs.redpanda.com/current/console/config/security/authorization.md --- # Authorization in Redpanda Console --- title: Authorization in Redpanda Console latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: config/security/authorization page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: config/security/authorization.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/console/pages/config/security/authorization.adoc description: Learn how to configure role-based access control (RBAC) in Redpanda Console to restrict system access to authorized users. page-git-created-date: "2024-09-11" page-git-modified-date: "2025-12-04" support-status: supported --- Redpanda Console v3.x [Redpanda Console v2.x](../../../../../24.3/console/config/security/authorization/) [Redpanda Console v3.x](./) > 📝 **NOTE** > > This feature requires an [enterprise license](../../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda Console has enterprise features enabled and it cannot find a valid license, it redirects you to the license expiration landing page, and all other access is restricted. Authentication allows users to log in, but authorization determines what they can do once authenticated. Redpanda Console supports two authorization modes, depending on whether **user impersonation** is enabled in the authentication configuration: | Mode | Who Evaluates Permissions? | | --- | --- | | Impersonation disabled (impersonateUser: false) | Redpanda Console evaluates permissions using role bindings defined in its configuration. Redpanda sees all requests as coming from a static service account. | | Impersonation enabled (impersonateUser: true) | Redpanda evaluates permissions using its internal RBAC and ACLs. Any role bindings in the Redpanda Console configuration are ignored. | For more information about authentication options, see the [Redpanda Console authentication](../authentication/). ## [](#modes-of-service-account-usage)Modes of service account usage **When impersonation is disabled**, Redpanda Console uses a static service account to connect to Redpanda APIs. This service account must be listed as a superuser principal in the Redpanda `superusers` configuration. In Redpanda, a principal is the authenticated identity (such as a username or OIDC subject) used for access control. For details, see [Users, Principals, and Superusers](../../../../manage/security/authentication/#principals). > ❗ **IMPORTANT** > > For any secret values, [use environment variables](../../configure-console/) instead of hardcoding them in the configuration file. For example, use `KAFKA_SASL_PASSWORD` for the service account password. There are two ways to use this service account: ### [](#static-service-account-only-no-login)Static service account only (no login) Use this mode to connect Redpanda Console to Redpanda with a static service account and **no user login**. When using the static service account (no login) mode: - There is no login screen. - All users share the same access level. - Redpanda Console roles and RBAC are not enforced. - It can be useful for internal tools. Example ```yaml authentication: basic: enabled: false oidc: enabled: false kafka: sasl: enabled: true impersonateUser: false username: "console-superuser" password: "secret" ``` ### [](#static-service-account-with-user-login)Static service account with user login Use this mode to allow users to log in, while still having all API calls executed under a single service account. When using static service accounts with user login: - Users authenticate to the UI using basic or OIDC login. - All backend communication to Redpanda APIs uses the service account. - Redpanda Console roles (`roleBindings`) determine what users can see or do in the UI. - Redpanda authorization is evaluated against the service account. #### Standalone ```yaml authentication: basic: enabled: true oidc: enabled: true kafka: sasl: enabled: true impersonateUser: false username: "console-superuser" password: "secret" authorization: roleBindings: - roleName: admin users: - loginType: basic name: alice ``` #### Kubernetes embedded When Redpanda Console is part of the Redpanda Helm chart or Operator: ##### Operator `redpanda-cluster`.yaml ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: clusterSpec: console: enabled: true console: config: authentication: basic: enabled: true oidc: enabled: true kafka: sasl: enabled: true impersonateUser: false username: "console-superuser" password: "secret" authorization: roleBindings: - roleName: admin users: - loginType: basic name: alice ``` ##### Helm `redpanda-values.yaml` ```yaml console: enabled: true console: config: authentication: basic: enabled: true oidc: enabled: true kafka: sasl: enabled: true impersonateUser: false username: "console-superuser" password: "secret" authorization: roleBindings: - roleName: admin users: - loginType: basic name: alice ``` #### Kubernetes standalone When using the standalone Redpanda Console Helm chart: `console-values.yaml` ```yaml config: authentication: basic: enabled: true oidc: enabled: true kafka: sasl: enabled: true impersonateUser: false username: "console-superuser" password: "secret" authorization: roleBindings: - roleName: admin users: - loginType: basic name: alice ``` This model is recommended if you want to manage RBAC in Redpanda Console, but still want to use a service account for API calls. ## [](#roles)Roles Roles in Redpanda Console determine which UI features users can access. These roles are configured in the `roleBindings` stanza of the Redpanda Console configuration file and are evaluated only when impersonation is disabled. Do you have user impersonation enabled? Redpanda Console roles are not used when user impersonation is enabled for an API. When impersonation is enabled, the user’s identity is forwarded to Redpanda, which then authorizes access based on RBAC and ACL rules. To successfully log in and access the UI, users must have valid Redpanda credentials and ACLs that permit access to the Kafka API. To access full Redpanda Console functionality (for example, downloading debug bundles or viewing broker configs), the user must also be a superuser in Redpanda. For information on assigning ACLs and superuser status, see [Configure Access Control Lists](../../../../manage/security/authorization/acl/). When impersonation is disabled, Redpanda Console authorizes access to features in the UI based on the configured roles in `roleBindings`. However: - Redpanda Console roles are not shown in the **Roles** tab on the **Security** page. - Redpanda Console roles do not grant access to Redpanda APIs (such as the Kafka API). - A Redpanda Console Admin is not a Redpanda superuser by default. To perform protected actions (for example, creating topics, managing ACLs, or accessing the Admin API), users must be granted corresponding permissions in Redpanda. > ❗ **IMPORTANT** > > If you’re running Redpanda Console with impersonation disabled, ensure the Redpanda Console service account is listed as a superuser in Redpanda. Otherwise, Redpanda Console cannot perform administrative actions on behalf of logged in users. Redpanda Console provides the following predefined roles: | Role | Permissions | Limitations | | --- | --- | --- | | Viewer | View topic data (messages, configs, partitions with search filters)View cluster data (node configs, ACLs, service accounts, quotas)View consumer group data (consumer groups, group offsets, lags)View Schema Registry data (registered schemas with contents)View Kafka Connect data (configured clusters, connectors including status and configs) | Cannot view the list of users | | Editor | Inherits all Viewer permissions, plus:Manage topics (create, edit configurations, delete topics, publish and delete records)Manage cluster configurations (edit node or cluster settings)Manage consumer groups (edit or delete group offsets)Manage Kafka Connect (create, update, delete, start, pause, or stop connectors) | Cannot create or remove ACLs or service accounts | | Admin | Inherits all Editor permissions, plus:View and manage all users and ACLsGenerate debug bundles | No limitations | > 📝 **NOTE: Community** > > **Kafka Connect is community-supported on [Redpanda Community Slack](https://redpanda.com/slack)**. Redpanda Data does not provide enterprise support for Kafka Connect with Redpanda Console. For a supported and scalable Kafka Connect alternative, try [Redpanda Connect](../../../../../redpanda-connect/get-started/). ## [](#grant-permissions-through-role-bindings)Grant permissions through role bindings When impersonation is disabled, Redpanda Console connects to Redpanda APIs using the service account defined in: - `kafka.sasl`: For the Kafka API - `schemaRegistry.authentication`: For the Schema Registry API - `redpanda.adminApi.authentication`: For the Admin API The Redpanda Console service account must be a superuser principal in Redpanda. Without superuser privileges, Redpanda Console is unable to perform actions such as listing topics, retrieving cluster metrics, managing ACLs, or accessing administrative endpoints. To grant superuser permissions to the service account: ```bash rpk cluster config set superusers '["console-superuser"]' \ -X user= -X pass= ``` Before login, Redpanda Console authenticates the user by validating their credentials against the Kafka API. If the user does not exist in Redpanda (for example, if they have not been created or their identity is not mapped through OIDC), login fails. After login, all API communication is performed using the service account’s credentials, not the end-user’s. This ensures Redpanda Console can act on the user’s behalf. As such, the service account must have sufficient privileges to cover the actions users are allowed to perform in the UI. ### [](#example-assign-the-viewer-role)Example: Assign the Viewer role This example shows how to grant the Viewer role to a user named `matt`. The Redpanda Console service account (`console-superuser`) is used to authenticate to all Redpanda services. #### Standalone ```yaml kafka: brokers: ["broker1.example.com:9092"] sasl: enabled: true impersonateUser: false (1) username: "console-superuser" (1) password: "secret-password" mechanism: "SCRAM-SHA-256" schemaRegistry: enabled: true urls: - "broker1.example.com:8081" - "broker2.example.com:8081" authentication: impersonateUser: false basic: username: "console-superuser" (1) password: "secret-password" redpanda: adminApi: enabled: true urls: - "broker1.example.com:9644" authentication: impersonateUser: false basic: username: "console-superuser" (1) password: "secret-password" authorization: roleBindings: - roleName: viewer (2) users: - loginType: basic name: "matt" (2) ``` #### Kubernetes embedded When using the Redpanda Operator or the Redpanda Helm chart, configure authorization through the cluster configuration: ##### Operator ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: clusterSpec: console: enabled: true console: config: kafka: sasl: enabled: true impersonateUser: false (1) username: "console-superuser" (1) password: "secret-password" mechanism: "SCRAM-SHA-256" schemaRegistry: enabled: true authentication: impersonateUser: false basic: username: "console-superuser" (1) password: "secret-password" redpanda: adminApi: enabled: true authentication: impersonateUser: false basic: username: "console-superuser" (1) password: "secret-password" authorization: roleBindings: - roleName: viewer (2) users: - loginType: basic name: "matt" (2) ``` ##### Helm ```yaml console: enabled: true console: config: kafka: sasl: enabled: true impersonateUser: false (1) username: "console-superuser" (1) password: "secret-password" mechanism: "SCRAM-SHA-256" schemaRegistry: enabled: true authentication: impersonateUser: false basic: username: "console-superuser" (1) password: "secret-password" redpanda: adminApi: enabled: true authentication: impersonateUser: false basic: username: "console-superuser" (1) password: "secret-password" authorization: roleBindings: - roleName: viewer (2) users: - loginType: basic name: "matt" (2) ``` #### Kubernetes standalone When using the standalone Redpanda Console Helm chart: ```yaml config: kafka: brokers: ["broker1.example.com:9092"] sasl: enabled: true impersonateUser: false (1) username: "console-superuser" (1) password: "secret-password" mechanism: "SCRAM-SHA-256" schemaRegistry: enabled: true urls: - "broker1.example.com:8081" - "broker2.example.com:8081" authentication: impersonateUser: false basic: username: "console-superuser" (1) password: "secret-password" redpanda: adminApi: enabled: true urls: - "broker1.example.com:9644" authentication: impersonateUser: false basic: username: "console-superuser" (1) password: "secret-password" authorization: roleBindings: - roleName: viewer (2) users: - loginType: basic name: "matt" (2) ``` Apply with: ```bash helm upgrade --install redpanda-console redpanda/console -f console-values.yaml ``` | 1 | With impersonation disabled, Redpanda Console uses the static service account (console-superuser) to connect to the Redpanda APIs. For security, store private data such as passwords in environment variables. For example: KAFKA_SASL_PASSWORD. | | --- | --- | | 2 | Role bindings map UI users to Redpanda Console roles. This does not grant Redpanda-level permissions. The user (matt) must also exist in Redpanda. | All APIs must be accessible using a superuser principal. If the service account lacks superuser status, Redpanda Console may not be able to fetch cluster status, access the Admin API, or interact with the Schema Registry. ### [](#transform-identities-with-principal-mappings)Transform identities with principal mappings If you use OIDC login, the identity in the JWT token is extracted using a JSONPath expression. By default, this expression is `$.sub`, which means the value of the `sub` claim is used as the username. You can override this expression using the `principalMapping` option to transform or extract a different claim to match the `name` values in your `roleBindings` configuration. To keep authorization consistent between Redpanda Console and Redpanda, set `principalMapping` to match Redpanda’s cluster configuration value for [`oidc_principal_mapping`](../../../../reference/properties/cluster-properties/#oidc_principal_mapping). Example: Map email to local username ```yaml authentication: oidc: enabled: true issuerUrl: https://auth.dev.cloud.redpanda.com/ clientId: R1iX7Pls9UMXiUoYBOn4NcIUTbaGX4JG clientSecret: redacted redirectUrl: http://localhost:9090/auth/callbacks/oidc successfulLoginRedirectUrl: http://localhost:3000 principalMapping: $.email/([^@]+)@example.com/$1/L ``` This example: - Extracts the `email` field from the OIDC token - Uses a regular expression to capture the username part - Replaces the value with the captured group `$1` - Converts the result to lowercase (`L` modifier) As a result, the user identity becomes `matt` when the email is `matt@example.com`. You can then define role bindings like this: #### Standalone ```yaml authorization: roleBindings: - roleName: admin users: - loginType: OIDC name: matt ``` #### Kubernetes embedded When using the Redpanda Operator or the Redpanda Helm chart, configure role bindings through the cluster configuration: ##### Operator ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: clusterSpec: console: enabled: true console: config: authorization: roleBindings: - roleName: admin users: - loginType: OIDC name: matt ``` ##### Helm ```yaml console: enabled: true console: config: authorization: roleBindings: - roleName: admin users: - loginType: OIDC name: matt ``` #### Kubernetes standalone When using the standalone Redpanda Console Helm chart: ```yaml config: authorization: roleBindings: - roleName: admin users: - loginType: OIDC name: matt ``` Apply with: ```bash helm upgrade --install redpanda-console redpanda/console -f console-values.yaml ``` #### [](#match-syntax-and-modifiers)Match syntax and modifiers The `principalMapping` syntax uses this format: /// - `jsonpath`: Path to the claim field in the token (such as `$.email`) - `regex`: A regular expression to extract part of the claim - `replacement`: A replacement string using a captured group (such as `$1`) - `modifiers`: Optional flags, such as: - `L` — convert to lowercase - `U` — convert to uppercase > 📝 **NOTE** > > If `principalMapping` is not set, Redpanda Console defaults to using the `sub` claim as the user identity. ## [](#multiple-roles-and-duplicate-bindings)Multiple roles and duplicate bindings You can assign multiple roles to the same user through role bindings. In this case, the user receives the union of all permissions associated with those roles. For example, if a user is assigned both `viewer` and `editor`, they can perform all actions granted to each role. Example: User with multiple role assignments ```yaml authorization: roleBindings: - roleName: viewer users: - loginType: OIDC name: john.doe@redpanda.com - roleName: editor users: - loginType: OIDC name: john.doe@redpanda.com ``` Duplicate role assignments do not cause errors. If the same role is assigned more than once to a user, the user receives the permissions only once. ## [](#suggested-reading)Suggested reading For details on how to assign Redpanda-level permissions through ACLs or RBAC, see: - [Configure Access Control Lists](../../../../manage/security/authorization/acl/) - [Configure Role-Based Access Control](../../../../manage/security/authorization/rbac/) ## Suggested labs - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) [Search all labs](/redpanda-labs) --- # Page 12: TLS Termination in Redpanda Console **URL**: https://docs.redpanda.com/current/console/config/security/tls-termination.md --- # TLS Termination in Redpanda Console --- title: TLS Termination in Redpanda Console latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: config/security/tls-termination page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: config/security/tls-termination.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/console/pages/config/security/tls-termination.adoc description: Learn how to secure Redpanda Console using TLS, either by letting Redpanda Console handle TLS termination or by offloading it to an upstream component, such as a reverse proxy or a Cloud HTTPS LoadBalancer. page-git-created-date: "2024-09-11" page-git-modified-date: "2026-01-05" support-status: supported --- Redpanda Console v3.x [Redpanda Console v2.x](../../../../../24.3/console/config/security/tls-termination/) [Redpanda Console v3.x](./) To secure Redpanda Console using TLS (Transport Layer Security), you can either let Redpanda Console handle TLS termination or you can offload it to an upstream component, such as a reverse proxy or a cloud HTTPS load balancer. TLS termination refers to the process of decrypting incoming TLS-encrypted traffic. Choosing the right approach depends on various factors, such as your application’s traffic load, the complexity of your infrastructure, security requirements, and resource availability: - Redpanda Console handles TLS termination | Advantages | Drawbacks | | --- | --- | | Simplicity: You don’t need an additional component to handle the TLS termination. | Performance: TLS termination can be computationally expensive, especially for high-traffic applications. | | Control: Because the TLS termination happens within Redpanda Console, you have direct control over the process, which can be beneficial for troubleshooting and custom configurations. | | - An upstream component handles TLS termination | Advantages | Drawbacks | | --- | --- | | Performance: Offloading the task of TLS termination to another component can help improve the performance of Redpanda Console by reducing its computational load. | Complexity: Using another component for TLS termination can increase the overall complexity of your system. | | Flexibility: You can use different types of upstream components (like various reverse proxies or load balancers) depending on your infrastructure needs and preferences. | | | Simplicity: Reverse proxies like NGINX Ingress can integrate with other components such as cert-manager, which automatically renews certificates from LetsEncrypt. | | ## [](#use-redpanda-console-for-tls-termination)Use Redpanda Console for TLS termination When you use Redpanda Console to terminate the TLS connection, Redpanda Console starts two HTTP servers: - An HTTPS server on the configured HTTPS port. - An HTTP server on the configured HTTP port which redirects HTTP requests to the HTTPS port. #### Standalone Add the following configuration to your `/etc/redpanda/redpanda-console-config.yaml` file: ```yaml server: # httpsListenPort defines the port on which Redpanda Console is listening for TLS connections, while advertisedHttpsListenPort defines the port that is advertised to clients, which may be different due to network configurations such as load balancers or proxies. advertisedHttpsListenPort is needed when redirecting a HTTP request to an HTTPS URL. httpsListenPort: 443 advertisedHttpsListenPort: 443 listenPort: 8080 tls: enabled: true certFilepath: keyFilepath: # AllowedOrigins is a list of origins that can send requests from a browser to the Redpanda Console # API. By default, a same-site policy is enforced to prevent CSRF-attacks. # Only in very specific deployment models you may need to change the secure default. # For example, during development, it's common to have the API server and the client running on different ports of localhost, which are treated as different origins by browsers. In this case, you would need to set `allowedOrigins` to include the origin of your client's development server. # allowedOrigins: [] ``` Replace `` and `` with the paths of your TLS certificate and key, respectively. #### Kubernetes embedded When using the Redpanda Operator or the Redpanda Helm chart, configure Redpanda Console TLS through the cluster configuration: ##### Operator ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda-sample spec: chartRef: {} clusterSpec: console: config: server: httpsListenPort: 443 advertisedHttpsListenPort: 443 listenPort: 8080 tls: enabled: true certFilepath: keyFilepath: ``` ##### Helm ```yaml console: enabled: true console: config: server: httpsListenPort: 443 advertisedHttpsListenPort: 443 listenPort: 8080 tls: enabled: true certFilepath: keyFilepath: ``` #### Kubernetes standalone When using the standalone Redpanda Console Helm chart, configure TLS in your Helm values: ```yaml config: server: httpsListenPort: 443 advertisedHttpsListenPort: 443 listenPort: 8080 tls: enabled: true certFilepath: keyFilepath: ``` Apply with: ```bash helm upgrade --install redpanda-console redpanda/console -f console-values.yaml ``` In this example, Redpanda Console is serving HTTPS traffic on port 443, where both `httpsListenPort` and `advertisedHttpsListenPort` are set to the same value. Any requests to the `listenPort` 8080 are redirected to the `advertisedHttpsListenPort`. If you want Redpanda Console to serve HTTPS on a non-standard port like 8081, but you want to present the URL to users as though it’s serving on the standard HTTPS port 443, you can set `httpsListenPort` to 8081 and `advertisedHttpsListenPort` to 443. This configuration might be useful in development or testing scenarios. For example, if Redpanda Console’s internal address is `https://192.168.1.100:8081` but externally it’s accessed through `https://public-address.com:443`, set `httpsListenPort` to 8081 and `advertisedHttpsListenPort` to 443. Despite listening internally on 8081, Redpanda Console will generate URLs for clients using port 443. > 📝 **NOTE** > > If you host Redpanda Console under a sub-path of your domain, such as `https://my-company.com/redpanda/console`, configure [HTTP path rewrites](../../http-path-rewrites/) in Redpanda Console. ### [](#http-strict-transport-security-hsts)HTTP Strict Transport Security (HSTS) When TLS is enabled, Redpanda Console server automatically adds the HTTP Strict Transport Security (HSTS) header to all responses: ```none Strict-Transport-Security: max-age=31536000 ``` The HSTS header instructs web browsers to: - Always connect to Redpanda Console using HTTPS, never HTTP - Automatically upgrade any HTTP requests to HTTPS for the next 365 days (31536000 seconds) - Refuse connections if there are certificate errors or warnings This behavior begins after the browser’s first successful HTTPS connection to Redpanda Console. HSTS provides protection against: - Protocol downgrade attacks: Prevents attackers from forcing connections to use insecure HTTP - Accidental insecure connections: Users typing `http://` in their browser are automatically redirected to HTTPS - Session hijacking: Eliminates the risk window where HTTP traffic could be intercepted before redirect You can verify that HSTS is enabled by checking the response headers: ```none curl -svk https://localhost:9091/ 2>&1 | grep -i strict-transport-security ``` Expected output: ```none < strict-transport-security: max-age=31536000 ``` ## [](#use-an-upstream-component-for-tls-termination)Use an upstream component for TLS termination When you use an upstream component for TLS termination, the upstream component handles the secure TLS connection, and Redpanda Console receives unencrypted HTTP traffic from this component. You can use various upstream components, including reverse proxies, such as NGINX and HAProxy, as well as cloud HTTPS load balancers. To use this option, you must: 1. Configure the upstream component to handle TLS termination. 2. Ensure that the upstream component routes traffic to the address and port of Redpanda Console. 3. Ensure that the upstream component is configured to pass along the original host header so that Redpanda Console can generate correct URLs, even when it’s behind a reverse proxy or load balancer. 4. Disable TLS in Redpanda Console: ### Standalone Add the following configuration to your `/etc/redpanda/redpanda-console-config.yaml` file: ```yaml server: listenPort: 8080 tls: enabled: false ``` ### Kubernetes embedded When using the Redpanda Operator or the Redpanda Helm chart, disable Redpanda Console TLS through the cluster configuration: #### Operator ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda-sample spec: chartRef: {} clusterSpec: console: config: server: listenPort: 8080 tls: enabled: false ``` #### Helm ```yaml console: config: server: listenPort: 8080 tls: enabled: false ``` ### Kubernetes standalone When using the standalone Redpanda Console Helm chart, disable TLS in your Helm values: ```yaml config: server: listenPort: 8080 tls: enabled: false ``` Apply with: ```bash helm upgrade --install redpanda-console redpanda/console -f console-values.yaml ``` > 📝 **NOTE** > > TLS is disabled by default. Although Redpanda Console isn’t using TLS, the traffic remains secure because the upstream component handles TLS. If you host Redpanda Console under a sub-path of your domain, such as `https://my-company.com/redpanda/console`, configure [HTTP path rewrites](../../http-path-rewrites/) in Redpanda Console. ## [](#suggested-reading)Suggested reading - [`server` configuration options](../../configure-console/) - NGINX - [NGINX Beginner’s Guide](http://nginx.org/en/docs/beginners_guide.html) - [NGINX SSL Termination](https://docs.nginx.com/nginx/admin-guide/security-controls/terminating-ssl-http/) - [HAProxy documentation](https://www.haproxy.com/documentation/) - [AWS Elastic Load Balancing documentation](https://docs.aws.amazon.com/elasticloadbalancing/) - [Cloud Load Balancing documentation](https://cloud.google.com/load-balancing/docs) - [OpenSSL documentation](https://www.openssl.org/docs/) --- # Page 13: Enable Topic Documentation in Redpanda Console **URL**: https://docs.redpanda.com/current/console/config/topic-documentation.md --- # Enable Topic Documentation in Redpanda Console --- title: Enable Topic Documentation in Redpanda Console latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: config/topic-documentation page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: config/topic-documentation.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/console/pages/config/topic-documentation.adoc description: Learn how to embed your Kafka topic documentation into the Redpanda Console UI by linking a Git repository that contains the topic documentation files. page-git-created-date: "2024-09-11" page-git-modified-date: "2025-12-04" support-status: supported --- Redpanda Console v3.x [Redpanda Console v2.x](../../../../24.3/console/config/topic-documentation/) [Redpanda Console v3.x](./) You can embed topic documentation into the Redpanda Console user interface by providing access to a public or private Git repository that hosts the documentation files in Markdown format. ![topic documentation](../../_images/topic-documentation.png) Redpanda Console clones the provided Git repository and stores all Markdown files it finds in memory. The **Documentation** tab in the frontend displays the content of the Markdown file that matches the name of the Kafka topic. | Path/Filename | Topic Name | Matches | | --- | --- | --- | | ordersv2.md | orders-v2 | ✗ | | Orders-v2.md | orders-v2 | ✗ | | orders-v2.md | orders-v2 | ✓ | | /orders/orders-v2.md | orders-v2 | ✓ | ## [](#repository-information)Repository information Start by specifying the Git repository that contains the Markdown documentation files. Provide the repository URL, the branch, and the base directory that contains the documentation. ### Standalone ```yaml console: topicDocumentation: git: enabled: true repository: url: https://github.com//.git branch: baseDirectory: ``` ### Kubernetes embedded When Redpanda Console is part of the Redpanda Helm chart or Operator: #### Operator ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Console metadata: name: redpanda-console spec: clusterRef: name: redpanda config: console: topicDocumentation: git: enabled: true repository: url: https://github.com//.git branch: baseDirectory: ``` #### Helm ```yaml console: enabled: true console: config: console: topicDocumentation: git: enabled: true repository: url: https://github.com//.git branch: baseDirectory: ``` ### Kubernetes standalone When using the standalone Redpanda Console Helm chart: ```yaml config: console: topicDocumentation: git: enabled: true repository: url: https://github.com//.git branch: baseDirectory: ``` ## [](#refresh-interval)Refresh interval Define how often Redpanda Console should refresh the documentation from the repository. ```yaml console: topicDocumentation: git: enabled: true refreshInterval: 10m ``` - `refreshInterval`: Set a duration like `10m` to refresh documentation every 10 minutes. Use `0` to disable automatic refresh. ## [](#authenticate-with-private-git-repositories)Authenticate with private Git repositories If the Git repository is private, Redpanda Console must authenticate using either: - A [GitHub Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) (PAT) over HTTPS (basic auth) - An [SSH private key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) ### [](#authenticate-using-a-github-personal-access-token-pat)Authenticate using a GitHub Personal Access Token (PAT) #### Standalone 1. Set the environment variables: ```bash TOPICDOCUMENTATION_GIT_BASICAUTH_USERNAME=token TOPICDOCUMENTATION_GIT_BASICAUTH_PASSWORD= ``` Replace `` with a GitHub personal access token that has `repo` scope. 2. Configure Redpanda Console: ```yaml console: topicDocumentation: git: enabled: true repository: url: https://github.com//.git branch: baseDirectory: refreshInterval: 10m basicAuth: enabled: true ``` #### Kubernetes embedded 1. Create the Secret: ```yaml apiVersion: v1 kind: Secret metadata: name: topic-doc-git-auth namespace: redpanda type: Opaque stringData: TOPICDOCUMENTATION_GIT_BASICAUTH_PASSWORD: ``` 2. Configure the deployment: ##### Operator ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Console metadata: name: redpanda-console spec: clusterRef: name: redpanda extraEnv: - name: TOPICDOCUMENTATION_GIT_BASICAUTH_USERNAME value: token extraEnvFrom: - secretRef: name: topic-doc-git-auth config: console: topicDocumentation: git: enabled: true repository: url: https://github.com//.git branch: baseDirectory: refreshInterval: 10m basicAuth: enabled: true ``` ##### Helm ```yaml console: enabled: true extraEnv: - name: TOPICDOCUMENTATION_GIT_BASICAUTH_USERNAME value: token extraEnvFrom: - secretRef: name: topic-doc-git-auth console: config: console: topicDocumentation: git: enabled: true repository: url: https://github.com//.git branch: baseDirectory: refreshInterval: 10m basicAuth: enabled: true ``` #### Kubernetes standalone 1. Create the Secret: ```yaml apiVersion: v1 kind: Secret metadata: name: topic-doc-git-auth namespace: redpanda type: Opaque stringData: TOPICDOCUMENTATION_GIT_BASICAUTH_PASSWORD: ``` 2. Reference it in Helm values: ```yaml config: console: topicDocumentation: git: enabled: true repository: url: https://github.com//.git branch: baseDirectory: refreshInterval: 10m basicAuth: enabled: true extraEnv: - name: TOPICDOCUMENTATION_GIT_BASICAUTH_USERNAME value: token extraEnvFrom: - secretRef: name: topic-doc-git-auth ``` ### [](#authenticate-using-ssh)Authenticate using SSH #### Standalone 1. Save the SSH key to a secure path (for example, `/etc/redpanda/ssh/id_rsa`). 2. Set the environment variables: ```bash TOPICDOCUMENTATION_GIT_SSH_ENABLED=true TOPICDOCUMENTATION_GIT_SSH_USERNAME=git TOPICDOCUMENTATION_GIT_SSH_PRIVATEKEYFILEPATH=/etc/redpanda/ssh/id_rsa TOPICDOCUMENTATION_GIT_SSH_PASSPHRASE= ``` 3. Configure Redpanda Console: ```yaml console: topicDocumentation: git: enabled: true repository: url: git@github.com:/.git branch: baseDirectory: refreshInterval: 10m ssh: enabled: true ``` #### Kubernetes embedded 1. Create the Secret: ```yaml apiVersion: v1 kind: Secret metadata: name: topic-doc-git-ssh namespace: redpanda type: Opaque stringData: privateKey: | -----BEGIN OPENSSH PRIVATE KEY----- -----END OPENSSH PRIVATE KEY----- passphrase: ``` 2. Mount the secret and set environment variables: ##### Operator ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Console metadata: name: redpanda-console spec: clusterRef: name: redpanda extraVolumeMounts: - name: git-ssh mountPath: /etc/git-ssh readOnly: true extraVolumes: - name: git-ssh secret: secretName: topic-doc-git-ssh extraEnv: - name: TOPICDOCUMENTATION_GIT_SSH_ENABLED value: "true" - name: TOPICDOCUMENTATION_GIT_SSH_USERNAME value: git - name: TOPICDOCUMENTATION_GIT_SSH_PRIVATEKEYFILEPATH value: /etc/git-ssh/privateKey - name: TOPICDOCUMENTATION_GIT_SSH_PASSPHRASE value: ``` ##### Helm ```yaml console: enabled: true extraVolumeMounts: - name: git-ssh mountPath: /etc/git-ssh readOnly: true extraVolumes: - name: git-ssh secret: secretName: topic-doc-git-ssh extraEnv: - name: TOPICDOCUMENTATION_GIT_SSH_ENABLED value: "true" - name: TOPICDOCUMENTATION_GIT_SSH_USERNAME value: git - name: TOPICDOCUMENTATION_GIT_SSH_PRIVATEKEYFILEPATH value: /etc/git-ssh/privateKey - name: TOPICDOCUMENTATION_GIT_SSH_PASSPHRASE value: ``` #### Kubernetes standalone 1. Create the Secret: ```yaml apiVersion: v1 kind: Secret metadata: name: topic-doc-git-ssh namespace: redpanda type: Opaque stringData: privateKey: | -----BEGIN OPENSSH PRIVATE KEY----- -----END OPENSSH PRIVATE KEY----- passphrase: ``` 2. Configure Helm values: ```yaml config: console: topicDocumentation: git: enabled: true repository: url: git@github.com:/.git branch: baseDirectory: refreshInterval: 10m ssh: enabled: true extraVolumeMounts: - name: git-ssh mountPath: /etc/git-ssh readOnly: true extraVolumes: - name: git-ssh secret: secretName: topic-doc-git-ssh extraEnv: - name: TOPICDOCUMENTATION_GIT_SSH_ENABLED value: "true" - name: TOPICDOCUMENTATION_GIT_SSH_USERNAME value: git - name: TOPICDOCUMENTATION_GIT_SSH_PRIVATEKEYFILEPATH value: /etc/git-ssh/privateKey - name: TOPICDOCUMENTATION_GIT_SSH_PASSPHRASE value: ``` Replace the following values throughout the examples: - ``: GitHub organization or user that owns the repository - ``: Name of the GitHub repository containing the topic documentation files - ``: Name of the Git branch to use (for example, `main` or `docs`) - ``: Relative path inside the repository where Markdown documentation files are stored - ``: GitHub personal access token with `repo` scope (used for basic authentication) - ``: SSH private key content used to authenticate to GitHub (must be base64-safe if stored in secrets) - ``: Passphrase used to decrypt the SSH private key, if applicable ## [](#example-configuration)Example configuration This example is for a setup where documentation needs frequent updates and is stored in a private repository accessed through SSH: ```yaml console: topicDocumentation: enabled: true git: enabled: true repository: url: https://github.com/example/redpanda-docs branch: main baseDirectory: path/to/documentation refreshInterval: 10m ssh: enabled: true username: git privateKeyFilepath: "/home/user/.ssh/redpanda_docs_key" passphrase: "passphrase" ``` This configuration is designed for a secure and automated integration of topic documentation into the Redpanda Console, using SSH for secure repository access and a refresh interval that keeps the documentation consistently updated without manual intervention. --- # Page 14: Manage Enterprise Edition Licenses through Redpanda Console **URL**: https://docs.redpanda.com/current/console/ui/add-license.md --- # Manage Enterprise Edition Licenses through Redpanda Console --- title: Manage Enterprise Edition Licenses through Redpanda Console latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: ui/add-license page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: ui/add-license.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/console/pages/ui/add-license.adoc description: Learn how to manage Enterprise Edition licenses in Redpanda Console. page-git-created-date: "2024-12-03" page-git-modified-date: "2025-12-04" support-status: supported --- Redpanda Console v3.x [Redpanda Console v2.x](../../../../24.3/console/ui/add-license/) [Redpanda Console v3.x](./) You can add or update an [Enterprise Edition license](../../../get-started/licensing/overview/#console) for both Redpanda and Redpanda Console directly through the Redpanda Console UI. ## [](#prerequisites)Prerequisites - You must have an Enterprise Edition license. [Request a license](https://www.redpanda.com/contact) if you don’t have one already. - Redpanda Console must be [connected to a Redpanda cluster](../../config/connect-to-redpanda/). - Redpanda Console must be [configured to connect to the Redpanda Admin API](../../config/connect-to-redpanda/#admin). > 💡 **TIP** > > You can also [configure Redpanda Console to load the license key from its local configuration](../../config/enterprise-license/). ## [](#upload-a-license)Upload a license When a license is uploaded through Redpanda Console, it is replicated across the connected Redpanda cluster and stored persistently in Redpanda’s internal metadata, ensuring it is retained across restarts. > ⚠️ **CAUTION** > > If you use Kubernetes to deploy Redpanda, do not use Redpanda Console to update the license if it’s already set in your Kubernetes resources. During upgrades or redeployments, license values in your Kubernetes resources will override the license set using Redpanda Console. For consistent license management, set the license using either Redpanda Console or Kubernetes resources, but not both. To upload a new license directly through the Redpanda Console UI: 1. Open the **Upload License** page, using one of the following methods: - **Cluster Overview** page: Navigate to the **Cluster Overview** page in Redpanda Console. Under the **Licensing** section, click on the **Upload new license** link to upload a new license key. - Expiration warning banner: If the existing license expires soon, you can click the **Upload license** button in the expiration warning banner. 2. Upload your license. You can drag and drop a license file into the box or copy and paste the license string into the text input. ![license](../../_images/license.png) When a new license is uploaded, enterprise features in Redpanda Self-Managed are unlocked immediately without requiring a cluster restart. However, to unlock enterprise features in Redpanda Console, you must restart the Redpanda Console instance. After restarting Redpanda Console, enterprise features such as RBAC are unlocked. However, to enable and use these features, you must configure them. See [Redpanda Console](../../../manage/console/). ## [](#next-steps)Next steps [Check the Status of Licenses](../../../get-started/licensing/check-status/). ## [](#suggested-reading)Suggested reading - [Check License Status in Redpanda Console](../check-license/) - [Redpanda Licensing](../../../get-started/licensing/) - [Redpanda Licenses and Enterprise Features](../../../get-started/licensing/overview/) --- # Page 15: Check License Status in Redpanda Console **URL**: https://docs.redpanda.com/current/console/ui/check-license.md --- # Check License Status in Redpanda Console --- title: Check License Status in Redpanda Console latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: ui/check-license page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: ui/check-license.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/console/pages/ui/check-license.adoc description: Learn how to check the status of your Redpanda Enterprise Edition license using the Redpanda Console. This topic includes steps to check license details and understand license warnings. page-git-created-date: "2024-12-17" page-git-modified-date: "2025-12-04" support-status: supported --- Redpanda Console v3.x [Redpanda Console v2.x](../../../../24.3/console/ui/check-license/) [Redpanda Console v3.x](./) You can check the expiration date of a license on the **Cluster Overview** page in Redpanda Console, under the **Licensing** section. Redpanda Console tries to load a valid license at startup in the following order: 1. From the local configuration file or environment variables. 2. From the connected Redpanda cluster (if available). ## [](#prerequisites)Prerequisites - Redpanda Console must have an Enterprise Edition license. [Request a license](https://www.redpanda.com/try-enterprise) if you don’t have one already. ## [](#check-the-expiration-date-of-a-license)Check the expiration date of a license 1. Go to the **Cluster Overview** page. 2. Locate the **Licensing** section. 3. Review the license details. ## [](#license-warnings-in-redpanda-console)License warnings in Redpanda Console Redpanda Console displays warnings in the following scenarios: - **Upcoming license expiration**: Redpanda Console checks the license status at startup. If the license expires within 30 days, a warning is displayed in the UI. Redpanda Console also logs the license details at startup, including the expiration date. For example: ```json {"level":"info","msg":"successfully loaded Redpanda Enterprise license","license_org":"redpanda","license_type":"enterprise","expires_at":"Oct 12 2024"} ``` - **Redpanda Console enterprise features are in use without a valid license**: Redpanda Console fails to start if enterprise features for Redpanda Console are enabled without a valid license. ```json {"level":"fatal","ts":"2024-12-16T11:27:27.308Z","msg":"Looks like you've enabled a Redpanda Enterprise feature(s) without a valid license. Please enter an active Redpanda license key. If you don't have one, please request a new/trial license at https://redpanda.com/license-request"} ``` - **Redpanda enterprise features are in use without a valid license**: If the connected Redpanda cluster is using enterprise features without a valid license, Redpanda Console displays a warning specifying the features in use without proper licensing. ## [](#next-steps)Next steps For more detailed information about a license such as the type, organization, and a list of enterprise features that are in use, use one of the following tools: - [`rpk`](../../../get-started/licensing/check-status/rpk/) - [Redpanda Operator (Kubernetes)](../../../get-started/licensing/check-status/redpanda-operator/) --- # Page 16: Manage Data Transforms in Redpanda Console **URL**: https://docs.redpanda.com/current/console/ui/data-transforms.md --- # Manage Data Transforms in Redpanda Console --- title: Manage Data Transforms in Redpanda Console latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: ui/data-transforms page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: ui/data-transforms.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/console/pages/ui/data-transforms.adoc description: Use Redpanda Console to monitor the status and performance metrics of your transform functions. You can also view detailed logs and delete transform functions when they are no longer needed. page-git-created-date: "2024-09-11" page-git-modified-date: "2025-12-04" support-status: supported --- Redpanda Console v3.x [Redpanda Console v2.x](../../../../24.3/console/ui/data-transforms/) [Redpanda Console v3.x](./) Use Redpanda Console to monitor the status and performance metrics of your transform functions. You can also view detailed logs and delete transform functions when they are no longer needed. ## [](#prerequisites)Prerequisites Before you begin, ensure that you have the following: - Redpanda Console must be [connected to a Redpanda cluster](../../config/connect-to-redpanda/). - Redpanda Console must be [configured to connect to the Redpanda Admin API](../../config/connect-to-redpanda/#admin). - [Data transforms enabled](../../../develop/data-transforms/configure/#enable-transforms) in your Redpanda cluster. - At least one transform function deployed to your Redpanda cluster. ## [](#monitor)Monitor transform functions To monitor transform functions: 1. Navigate to the **Transforms** menu. 2. Click the name of a transform function to view detailed information: - The partitions that the function is running on - The broker (node) ID - Any lag (the amount of pending records on the input topic that have yet to be processed by the transform) ## [](#logs)View logs To view logs for a transform function: 1. Navigate to the **Transforms** menu. 2. Click on the name of a transform function. 3. Click the **Logs** tab to see the logs. Redpanda Console displays a limited number of logs for transform functions. To view the full history of logs, use the [`rpk` command-line tool](../../../develop/data-transforms/monitor/#logs). ## [](#delete)Delete transform functions To delete a transform function: 1. Navigate to the **Transforms** menu. 2. Find the transform function you want to delete from the list. 3. Click the delete icon at the end of the row. 4. Confirm the deletion when prompted. Deleting a transform function will remove it from the cluster and stop any further processing. ## [](#suggested-reading)Suggested reading - [How Data Transforms Work](../../../develop/data-transforms/how-transforms-work/) - [Deploy Data Transforms](../../../develop/data-transforms/deploy/) - [Monitor Data Transforms](../../../develop/data-transforms/monitor/) --- # Page 17: Edit Topic Configuration in Redpanda Console **URL**: https://docs.redpanda.com/current/console/ui/edit-topic-configuration.md --- # Edit Topic Configuration in Redpanda Console --- title: Edit Topic Configuration in Redpanda Console latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: ui/edit-topic-configuration page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: ui/edit-topic-configuration.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/console/pages/ui/edit-topic-configuration.adoc description: Learn how to use Redpanda Console to edit the configuration of existing topics in a cluster. page-git-created-date: "2024-09-11" page-git-modified-date: "2026-03-31" support-status: supported --- Redpanda Console v3.x [Redpanda Console v2.x](../../../../24.3/console/ui/edit-topic-configuration/) [Redpanda Console v3.x](./) Learn how to use Redpanda Console to edit the configuration of existing topics in a cluster. 1. In the menu, go to **Topics**. 2. Select a topic, and open the **Configuration** tab. 3. Click the pencil icon in the row of the property that you want to edit. 4. Make your changes, and click **Save changes**. ## [](#suggested-reading)Suggested reading - [Topic Configuration Properties](../../../reference/properties/topic-properties/) - [Manage Topics](../../../develop/manage-topics/config-topics/) --- # Page 18: Manage Debug Bundles in Redpanda Console **URL**: https://docs.redpanda.com/current/console/ui/generate-bundle.md --- # Manage Debug Bundles in Redpanda Console --- title: Manage Debug Bundles in Redpanda Console latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: ui/generate-bundle page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: ui/generate-bundle.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/console/pages/ui/generate-bundle.adoc description: Learn how to generate, download, and delete debug bundles in Redpanda Console for comprehensive cluster diagnostics. page-git-created-date: "2024-12-03" page-git-modified-date: "2025-12-04" support-status: supported --- Redpanda Console v3.x [Redpanda Console v2.x](../../../../24.3/console/ui/generate-bundle/) [Redpanda Console v3.x](./) > 📝 **NOTE** > > This feature requires an [enterprise license](../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda Console has enterprise features enabled and it cannot find a valid license, it redirects you to the license expiration landing page, and all other access is restricted. Learn how to generate, download, and delete debug bundles in Redpanda Console for comprehensive cluster diagnostics. When your cluster is unhealthy, Redpanda Console displays debugging data on the **Overview** page. If you are logged in as an admin user, you also get a link to generate a debug bundle. ![degraded cluster](../../_images/degraded-cluster.png) ## [](#prerequisites)Prerequisites - Redpanda Console must be [connected to a Redpanda cluster](../../config/connect-to-redpanda/) and [configured to connect to the Redpanda Admin API](../../config/connect-to-redpanda/#admin). ## [](#generate-a-debug-bundle)Generate a debug bundle You can generate a debug bundle for all brokers in the cluster and download it onto your local computer for inspection. > 📝 **NOTE** > > Only one debug bundle can exist at a time. If you generate a new debug bundle, any existing bundle from a previous run will be automatically deleted. 1. Click **Debug bundle**. 2. Click **Generate default**. 3. Wait until the process is complete. 4. Click **debug-bundle.zip** to download the bundle on your local computer. 5. Unzip the file to inspect the contents. For guidance on reading the debug bundle, see [Inspect a Debug Bundle](../../../troubleshoot/debug-bundle/inspect/). ## [](#delete-a-debug-bundle)Delete a debug bundle To manually delete a debug bundle: 1. Click **Debug bundle**. 2. Click the trash icon next to **debug-bundle.zip** to delete the bundle. ## [](#next-steps)Next steps - [Inspect a Debug Bundle](../../../troubleshoot/debug-bundle/inspect/) - [Cluster Diagnostics](../../../troubleshoot/cluster-diagnostics/) - [Error Messages and Solutions](../../../troubleshoot/errors-solutions/) --- # Page 19: Filter Messages with JavaScript in Redpanda Console **URL**: https://docs.redpanda.com/current/console/ui/programmable-push-filters.md --- # Filter Messages with JavaScript in Redpanda Console --- title: Filter Messages with JavaScript in Redpanda Console latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: ui/programmable-push-filters page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: ui/programmable-push-filters.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/console/pages/ui/programmable-push-filters.adoc description: Learn how to filter Kafka records using custom JavaScript code within Redpanda Console. page-git-created-date: "2024-09-11" page-git-modified-date: "2025-12-04" support-status: supported --- Redpanda Console v3.x [Redpanda Console v2.x](../../../../24.3/console/ui/programmable-push-filters/) [Redpanda Console v3.x](./) You can use push-down filters in Redpanda Console to search through large Kafka topics that may contain millions of records. Filters are JavaScript functions executed on the backend, evaluating each record individually. Your function must return a boolean: - `true`: record is included in the frontend results. - `false`: record is skipped. Multiple filters combine logically with `AND` conditions. ## [](#add-a-javascript-filter)Add a JavaScript filter To add a JavaScript filter: 1. Navigate to the topic’s **Messages** page. 2. Click **Add filter > JavaScript Filter**. 3. Define your JavaScript filtering logic in the provided input area. ![JavaScript filter in Redpanda Console](../../_images/js-filter.png) ## [](#resource-usage-and-performance)Resource usage and performance JavaScript filters are executed on the backend, consuming CPU and network resources. The performance of your filter depends on the complexity of your JavaScript code and the volume of data being processed. Complex JavaScript logic or large data volumes may increase CPU load and network usage. ## [](#available-javascript-properties)Available JavaScript properties Redpanda Console injects these properties into your JavaScript context: | Property | Description | Type | | --- | --- | --- | | headers | Record headers as key-value pairs (ArrayBuffers) | Object | | key | Decoded record key | String | | keySchemaID | Schema Registry ID for key (if present) | Number | | partitionId | Partition ID of the record | Number | | offset | Record offset within partition | Number | | timestamp | Timestamp as JavaScript Date object | Date | | value | Decoded record value | Object/String | | valueSchemaID | Schema Registry ID for value (if present) | Number | > 📝 **NOTE** > > Values, keys, and headers are deserialized before being injected into your script. ## [](#javascript-filter-examples)JavaScript filter examples ### [](#filter-by-header-value)Filter by header value **Scenario:** Records tagged with headers specifying customer plan type. Sample header data (string value) ```json headers: { "plan_type": "premium" } ``` JavaScript filter ```javascript let headerValue = headers["plan_type"]; if (headerValue) { let stringValue = String.fromCharCode(...new Uint8Array(headerValue)); return stringValue === "premium"; } return false; ``` **Scenario:** Records include a header with JSON-encoded customer metadata. Sample header data (JSON value) ```json headers: { "customer": "{"orgID":"123-abc","name":"ACME Inc."}" } ``` JavaScript filter ```javascript let headerValue = headers["customer"]; if (headerValue) { let stringValue = String.fromCharCode(headerValue); let valueObj = JSON.parse(stringValue); return valueObj["orgID"] === "123-abc"; } return false; ``` ### [](#filter-by-timestamp)Filter by timestamp **Scenario:** Retrieve records from a promotional event. JavaScript filter ```javascript return timestamp.getMonth() === 10 && timestamp.getDate() === 24; ``` ### [](#filter-by-schema-id)Filter by schema ID **Scenario:** Filter customer activity records based on Avro schema version. JavaScript filter ```javascript return valueSchemaID === 204; ``` ### [](#filter-json-record-values)Filter JSON record values **Scenario:** Filter transactions by customer ID. Sample JSON record ```json { "transaction_id": "abc123", "customer_id": "cust789", "amount": 59.99 } ``` JavaScript filter (top-level property) ```javascript return value.customer_id === "cust789"; ``` **Scenario:** Filter orders by item availability. Sample JSON record ```json { "order_id": "ord456", "inventory": { "item_id": "itm001", "status": "in_stock" } } ``` JavaScript filter (nested property) ```javascript return value.inventory.status === "in_stock"; ``` **Scenario:** Filter products missing price information. JavaScript filter (property absence) ```javascript return !value.hasOwnProperty("price"); ``` ### [](#filter-string-keys)Filter string keys **Scenario:** Filter sensor data records by IoT device ID. JavaScript filter ```javascript return key === "sensor-device-1234"; ``` --- # Page 20: View Deserialized Messages in Redpanda Console **URL**: https://docs.redpanda.com/current/console/ui/record-deserialization.md --- # View Deserialized Messages in Redpanda Console --- title: View Deserialized Messages in Redpanda Console latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: ui/record-deserialization page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: ui/record-deserialization.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/console/pages/ui/record-deserialization.adoc description: Learn how Redpanda Console deserializes messages. page-git-created-date: "2024-09-11" page-git-modified-date: "2025-12-04" support-status: supported --- Redpanda Console v3.x [Redpanda Console v2.x](../../../../24.3/console/ui/record-deserialization/) [Redpanda Console v3.x](./) In Redpanda, the messages exchanged between producers and consumers contain raw bytes. Schemas work as an agreed-upon format, like a contract, for producers and consumers to serialize and deserialize those messages. If a producer breaks this contract, consumers can fail. Redpanda Console automatically tries to deserialize incoming messages and displays them in human-readable format. It tests different deserialization strategies until it finds one with no errors. If no deserialization attempts are successful, Redpanda Console renders the byte array in a hex viewer. Sometimes, the payload is displayed in hex bytes because it’s encrypted or because it uses a serializer that Redpanda Console cannot deserialize. When this happens, Redpanda Console displays troubleshooting information. You can also download the raw bytes of the message to feed it directly to your client deserializer or share it with a support team. All deserialized messages are rendered as JSON objects and can be used as JavaScript objects in [JavaScript filters (push filters)](../programmable-push-filters/). ## [](#prerequisites)Prerequisites Ensure that Redpanda Console is configured to handle the specific deserialization formats you plan to use, such as Avro, Protobuf, or MessagePack. Encoding formats that rely on external schemas or metadata may require additional configuration. See [Configure Message Deserialization in Redpanda Console](../../config/deserialization/). ## [](#display-messages-in-a-specific-format)Display messages in a specific format Redpanda Console tries to automatically identify the correct deserialization type by decoding the message’s key, value, or header with all available deserialization methods. To display your messages in another format: 1. Open your topic. 2. Click the cog icon. 3. Click **Deserialization**. 4. Choose a new deserializer for either the keys or values in your messages. Supported deserializers include: - Plain text - Kafka’s internal binary formats; for example, the `__consumer_offsets` topic - JSON - JSON with Schema Registry encoding - Smile - XML - Avro with Schema Registry encoding - Protobuf - Protobuf with Schema Registry encoding - Messagepack (for topics explicitly enabled to test MessagePack) - UTF-8 / strings - `uint8`, `uint16`, `uint32`, `uint64` ## [](#suggested-reading)Suggested reading - [Redpanda Schema Registry](../../../manage/schema-reg/schema-reg-overview/) --- # Page 21: Use Schema Registry in Redpanda Console **URL**: https://docs.redpanda.com/current/console/ui/schema-reg.md --- # Use Schema Registry in Redpanda Console --- title: Use Schema Registry in Redpanda Console latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: ui/schema-reg page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: ui/schema-reg.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/console/pages/ui/schema-reg.adoc description: Learn how to perform common Schema Registry management operations in the Redpanda Console. page-git-created-date: "2024-09-11" page-git-modified-date: "2025-12-04" support-status: supported --- Redpanda Console v3.x [Redpanda Console v2.x](../../../../24.3/console/ui/schema-reg/) [Redpanda Console v3.x](./) In Redpanda Console, the **Schema Registry** menu lists registered and verified schemas, including their serialization format and versions. Select an individual schema to see which topics it applies to. > 📝 **NOTE** > > The Schema Registry is built into Redpanda, and you can use it with the Schema Registry API or with the UI. This section describes Schema Registry operations available in the UI. ## [](#prerequisites)Prerequisites You must add a valid `schemaRegistry` configuration in Redpanda Console. For help configuring Redpanda Console to connect to Schema Registry, see [Configure Message Deserialization in Redpanda Console](../../config/deserialization/). ## [](#create-or-edit-a-schema)Create or edit a schema A schema is registered in the registry with a _subject_, which is a name that is associated with the schema as it evolves. To register a schema, click **Create new schema**. 1. On the **Create schema** page, select the strategy type for how to derive the subject name. - **Topic** (default): The subject name is derived from the Redpanda topic name. See [Topic strategy use case](#topic-strategy-use-case). - **Record**: The subject name is derived from the Kafka record name. See [Record strategy use case](#record-strategy-use-case). - **TopicRecord**: The subject name is derived from both topic name and record name, allowing for finer-grained schema organization. See [TopicRecord strategy use case](#topicrecord-strategy-use-case). - **Custom**: The subject name is user-defined. 2. Select the serialization format with the schema definition. 3. To build more complex schema definitions, add a reference to other schemas. For example, the two `import` statements are references to the `PhoneNumber` and `Address` schemas: ```json { syntax = "proto3"; import "PhoneNumber.proto"; import "Address.proto"; message Person { string name = 1; string email = 2; PhoneNumber phone = 3; repeated Address address = 4; } } ``` 4. After registering a schema, you can add a new version to it, change its compatibility, or delete it. ### [](#topic-strategy-use-case)Topic strategy use case The Topic strategy is suitable when you want to group schemas by the topics to which they are associated. Suppose you’re tracking product order information in a topic named `Transactions`. When a producer sends records to the `OrderInfo` topic, you want the record names to look something like: - `Transactions - Record1` - `Transactions - Record2` Where `Record1` and `Record2` are unique identifiers. This is usually defined in your producer settings. Create your schema with the Topic strategy, and the subject name is always `Transactions`, with all customer transactions under the same topic. ### [](#record-strategy-use-case)Record strategy use case The Record strategy is most useful when you have multiple schemas within a topic and need more granular categorization that’s influenced by the record name. Suppose there’s an `Events` topic with event types A and B. You may want each of those event types to have their own subject, their own schemas, and their own fully-qualified record names (for example, `com.example.EventTypeA`). If each event type has its own schema with the Record strategy, then when producers send these event types to the `Events` topic, their subjects are those record names: - `com.example.EventTypeA` - `com.example.EventTypeB` The record names in the Events topic look like this: - `Events-com.example.EventTypeA-Record1` - `Events-com.example.EventTypeB-Record1` - `Events-com.example.EventTypeA-Record2` - `Events-com.example.EventTypeB-Record2` ### [](#topicrecord-strategy-use-case)TopicRecord strategy use case The TopicRecord strategy is suitable when you want to organize schemas based on both topics and logical record types. Suppose there’s a microservices architecture where different services produce to the same topic: `SharedEvents`. Each microservice has a schema of its own for the shared events, but each schema uses the TopicRecord strategy. This results in the following subject names: - `SharedEvents-com.example.MicroserviceAEvent` - `SharedEvents-com.example.MicroserviceBEvent` The record names look like this: - `SharedEvents-com.example.MicroserviceAEvent-Record1` - `SharedEvents-com.example.MicroserviceBEvent-Record1` - `SharedEvents-com.example.MicroserviceAEvent-Record2` - `SharedEvents-com.example.MicroserviceBEvent-Record2` This allows for multiple schemas to govern the same shared events for different microservices, allowing granular organization. ## [](#configure-schema-compatibility)Configure schema compatibility Applications are often modeled around a specific business object structure. As applications change and the shape of their data changes, producer schemas and consumer schemas may no longer be compatible. You can decide how a consumer handles data from a producer that uses an older or newer schema, and reduce the chance of consumers hitting deserialization errors. You can configure different types of schema compatibility, which are applied to a subject when a new schema is registered. The Schema Registry supports the following compatibility types: - `BACKWARD` (**default**) - Consumers using the new schema (for example, version 10) can read data from producers using the previous schema (for example, version 9). - `BACKWARD_TRANSITIVE` - Consumers using the new schema (for example, version 10) can read data from producers using all previous schemas (for example, versions 1-9). - `FORWARD` - Consumers using the previous schema (for example, version 9) can read data from producers using the new schema (for example, version 10). - `FORWARD_TRANSITIVE` - Consumers using any previous schema (for example, versions 1-9) can read data from producers using the new schema (for example, version 10). - `FULL` - A new schema and the previous schema (for example, versions 10 and 9) are both backward and forward compatible with each other. - `FULL_TRANSITIVE` - Each schema is both backward and forward compatible with all registered schemas. - `NONE` - No schema compatibility checks are done. ### [](#compatibility-uses-and-constraints)Compatibility uses and constraints - A consumer that wants to read a topic from the beginning (for example, an AI learning process) benefits from backward compatibility. It can process the whole topic using the latest schema. This allows producers to remove fields and add attributes. - A real-time consumer that doesn’t care about historical events but wants to keep up with the latest data (for example, a typical streaming application) benefits from forward compatibility. Even if producers change the schema, the consumer can carry on. - Full compatibility can process historical data and future data. This is the safest option, but it limits the changes that can be done. This only allows for the addition and removal of optional fields. If you make changes that are not inherently backward-compatible, you may need to change compatibility settings or plan a transitional period, updating producers and consumers to use the new schema while the old one is still accepted. | Schema format | Backward-compatible tasks | Not backward-compatible tasks | | --- | --- | --- | | Avro | Add fields with default valuesMake fields nullable | Remove fieldsChange data types of fieldsChange enum valuesChange field constraintsChange record of field names | | Protobuf | Add fieldsRemove fields | Remove required fieldsChange data types of fields | | JSON | Add optional propertiesRelax constraints, for example:Decrease a minimum value or increase a maximum valueDecrease minItems, minLength, or minProperties; increase maxItems, maxLength, maxPropertiesAdd more property types (for example, "type": "integer" to "type": ["integer", "string"])Add more enum valuesReduce multipleOf by an integral factorRelaxing additional properties if additionalProperties was not previously specified as falseRemoving a uniqueItems property that was false | Remove propertiesAdd required propertiesChange property names and typesTighten or add constraints | ## [](#delete-a-schema)Delete a schema Select a schema to soft-delete a version of it or all schemas of its subject. Schemas cannot be deleted if any other schemas reference it. A soft-deleted schema can be recovered, but a permanently-deleted schema cannot be recovered. Redpanda does not recommend permanently deleting schemas in a production environment. ## [](#suggested-reading)Suggested reading - [Configure Message Deserialization in Redpanda Console](../../config/deserialization/) - [Redpanda Schema Registry](../../../manage/schema-reg/schema-reg-overview/) --- # Page 22: Self-Managed Deployment **URL**: https://docs.redpanda.com/current/deploy.md --- # Self-Managed Deployment --- title: Self-Managed Deployment latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/index.adoc description: Learn about Redpanda Self-Managed deployments. page-git-created-date: "2023-05-30" page-git-modified-date: "2024-08-12" support-status: supported --- - [Deploy Redpanda](redpanda/) Overview of Redpanda deployment options and links to platform-specific guides. - [Deploy Redpanda Console](console/) Overview of Redpanda Console deployment options and links to platform-specific guides. - [Redpanda Connect Documentation](../../redpanda-connect/home/) Home page for the Redpanda Connect docs. - [Deploy Kafka Connect](kafka-connect/) Overview of Kafka Connect deployment options and links to platform-specific guides. --- # Page 23: Deploy Redpanda Console **URL**: https://docs.redpanda.com/current/deploy/console.md --- # Deploy Redpanda Console --- title: Deploy Redpanda Console latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: console/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: console/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/console/index.adoc description: Overview of Redpanda Console deployment options and links to platform-specific guides. page-git-created-date: "2025-08-15" page-git-modified-date: "2025-08-15" support-status: supported --- Redpanda Console provides a web-based UI for managing and monitoring your Redpanda clusters. This section describes the available deployment methods and links to detailed, platform-specific instructions. See the platform-specific pages for prerequisites, configuration, and deployment steps. - [Deploy Redpanda Console on Kubernetes](kubernetes/) Learn about deployment options for Redpanda Console on Kubernetes, as well as requirements for installation. - [Deploy Redpanda Console on Linux](linux/) Learn about deployment options for Redpanda Console on Linux, as well as requirements for installation. --- # Page 24: Deploy Redpanda Console on Kubernetes **URL**: https://docs.redpanda.com/current/deploy/console/kubernetes.md --- # Deploy Redpanda Console on Kubernetes --- title: Deploy Redpanda Console on Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: console/kubernetes/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: console/kubernetes/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/console/kubernetes/index.adoc description: Learn about deployment options for Redpanda Console on Kubernetes, as well as requirements for installation. page-git-created-date: "2025-08-15" page-git-modified-date: "2025-08-15" support-status: supported --- Redpanda Console provides a web-based UI for managing and monitoring your Redpanda clusters. This topic describes how to deploy Redpanda Console on Kubernetes and links to detailed, platform-specific instructions. - [Redpanda Console Kubernetes Requirements and Recommendations](k-requirements/) System requirements and recommendations for deploying Redpanda Console on Kubernetes in production. - [Deploy Redpanda Console on Kubernetes](deploy/) Deploy Redpanda Console on Kubernetes using the Redpanda Operator, Helm charts, or YAML manifests. --- # Page 25: Deploy Redpanda Console on Kubernetes **URL**: https://docs.redpanda.com/current/deploy/console/kubernetes/deploy.md --- # Deploy Redpanda Console on Kubernetes --- title: Deploy Redpanda Console on Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: console/kubernetes/deploy page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: console/kubernetes/deploy.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/console/kubernetes/deploy.adoc description: Deploy Redpanda Console on Kubernetes using the Redpanda Operator, Helm charts, or YAML manifests. page-topic-type: how-to personas: platform_operator learning-objective-1: Deploy Redpanda Console on Kubernetes using the Redpanda Operator, Helm charts, or YAML manifests learning-objective-2: Configure TLS and SASL authentication for Redpanda Console learning-objective-3: Verify and scale a Redpanda Console deployment page-git-created-date: "2025-08-15" page-git-modified-date: "2026-03-31" support-status: supported --- This page shows you how to deploy Redpanda Console as a standalone service on Kubernetes using the Redpanda Operator (Console custom resource), Helm charts, or YAML manifests. > 📝 **NOTE** > > When you deploy a Redpanda cluster using the [Redpanda Operator or Redpanda Helm chart](../../../redpanda/kubernetes/k-production-deployment/), Redpanda Console is automatically deployed alongside your cluster. > > Use this standalone deployment guide only when you need to: > > - Connect to a Redpanda cluster running outside Kubernetes. > > - Deploy Redpanda Console independently from your Redpanda cluster. > > - Deploy multiple Redpanda Console instances for different environments. After reading this page, you will be able to: - Deploy Redpanda Console on Kubernetes using the Redpanda Operator, Helm charts, or YAML manifests - Configure TLS and SASL authentication for Redpanda Console - Verify and scale a Redpanda Console deployment ## [](#prerequisites)Prerequisites - You must have a running Redpanda or Kafka cluster available to connect to. Redpanda Console requires a cluster to function. For instructions on deploying a Redpanda cluster, see [Deploy on Kubernetes](../../../redpanda/kubernetes/). - Review the [system requirements for Redpanda Console on Kubernetes](../k-requirements/). ## [](#install-redpanda-console)Install Redpanda Console Choose your deployment method. #### Operator The Redpanda Operator provides a `Console` custom resource (CR) that lets you deploy and manage Redpanda Console declaratively. The operator handles the lifecycle of the Console deployment, including creating the underlying Deployment, Service, and ConfigMap resources. 1. Create a Console custom resource: `console.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Console metadata: name: redpanda-console namespace: redpanda spec: cluster: clusterRef: (1) name: redpanda replicaCount: 2 (2) resources: (3) requests: cpu: 100m memory: 512Mi limits: cpu: 4000m memory: 2Gi service: (4) type: LoadBalancer port: 8080 ingress: (5) enabled: true annotations: cert-manager.io/cluster-issuer: letsencrypt-prod className: nginx hosts: - host: console.example.com paths: - path: / pathType: Prefix tls: - secretName: console-tls hosts: - console.example.com ``` | 1 | Reference to your Redpanda cluster CR. The operator automatically configures broker addresses, TLS, and authentication based on the referenced cluster. If your Redpanda cluster is not managed by the operator, use staticConfiguration instead of clusterRef. See the TLS section for staticConfiguration examples. | | --- | --- | | 2 | For production, run at least two replicas for high availability and rolling upgrades. | | 3 | Adjust resource requests and limits based on your expected workload and available node resources. | | 4 | Use LoadBalancer for cloud environments or when you want Redpanda Console to be accessible from outside the cluster. Use ClusterIP for internal-only access. | | 5 | Enable and configure Ingress if you want to expose Redpanda Console using a domain name and use TLS/HTTPS. Make sure your cluster has an Ingress controller installed. | 2. Apply the Console CR: ```bash kubectl apply -f console.yaml --namespace redpanda ``` The operator reconciles the Console CR and creates the necessary Deployment, Service, and ConfigMap resources. #### Helm 1. Create a values file: The values file is where you configure how Redpanda Console connects to your Redpanda or Kafka cluster. You must specify the broker addresses in the `config.kafka.brokers` section. `console-values.yaml` ```yaml config: kafka: brokers: - redpanda-0.redpanda.redpanda.svc.cluster.local:9092 (1) - redpanda-1.redpanda.redpanda.svc.cluster.local:9092 - redpanda-2.redpanda.redpanda.svc.cluster.local:9092 # Resource configuration resources: (2) requests: cpu: 100m memory: 512Mi limits: cpu: 4000m memory: 2Gi # High availability configuration replicaCount: 2 (3) # Pod anti-affinity for node separation affinity: podAntiAffinity: preferredDuringSchedulingIgnoredDuringExecution: - weight: 100 podAffinityTerm: labelSelector: matchLabels: app.kubernetes.io/name: console topologyKey: kubernetes.io/hostname # Service configuration service: (4) type: LoadBalancer port: 8080 # Ingress configuration (optional) ingress: (5) enabled: true annotations: cert-manager.io/cluster-issuer: letsencrypt-prod ingressClassName: nginx hosts: - host: console.example.com paths: - path: / pathType: Prefix tls: - secretName: console-tls hosts: - console.example.com ``` | 1 | Replace these addresses with the internal DNS names or external addresses of your Redpanda brokers. If you deployed Redpanda using the Redpanda Helm chart or Redpanda Operator, you can find the broker service names by running:kubectl get svc -n Look for services named like redpanda-0, redpanda-1, etc. The port is typically 9092 for Kafka traffic. If your brokers are outside the cluster, use their reachable addresses instead. | | --- | --- | | 2 | Adjust resource requests and limits based on your expected workload and available node resources. | | 3 | For production, run at least two replicas for high availability and rolling upgrades. | | 4 | Use LoadBalancer for cloud environments or when you want Redpanda Console to be accessible from outside the cluster. Use ClusterIP for internal-only access. | | 5 | Enable and configure Ingress if you want to expose Redpanda Console using a domain name and use TLS/HTTPS. Make sure your cluster has an Ingress controller installed. | 2. Install the chart: ```bash helm install redpanda-console redpanda/console \ --namespace redpanda \ --create-namespace \ --values console-values.yaml ``` ### [](#connect-to-redpanda-clusters-with-tls)Connect to Redpanda clusters with TLS If your Redpanda cluster uses TLS encryption (the default for Helm deployments), you must configure Redpanda Console to connect securely. #### Operator When you use `clusterRef` to reference a Redpanda cluster managed by the operator, TLS is configured automatically. No additional steps are required. If you use `staticConfiguration` to connect to an external cluster with TLS: 1. Extract the CA certificate: ```bash kubectl get secret redpanda-default-root-certificate -n redpanda -o jsonpath='{.data.ca\.crt}' | base64 -d > ca.crt ``` 2. Create a secret with the CA certificate: ```bash kubectl create secret generic redpanda-console-tls --from-file=ca.crt=ca.crt -n redpanda ``` 3. Configure the Console CR: ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Console metadata: name: redpanda-console namespace: redpanda spec: cluster: staticConfiguration: kafka: brokers: - redpanda-0.redpanda.redpanda.svc.cluster.local:9093 tls: caCertSecretRef: name: redpanda-console-tls key: ca.crt secretMounts: - name: redpanda-console-tls secretName: redpanda-console-tls path: /etc/console/secrets ``` 4. Apply the updated Console CR: ```bash kubectl apply -f console.yaml --namespace redpanda ``` #### Helm 1. Run the following command to extract the CA certificate from the Redpanda Helm deployment: ```bash kubectl get secret redpanda-default-root-certificate -n redpanda -o jsonpath='{.data.ca\.crt}' | base64 -d > ca.crt ``` 2. Create a secret named `redpanda-console` in the `redpanda` namespace with the CA certificate: ```bash kubectl create secret generic redpanda-console --from-file=ca.crt=ca.crt -n redpanda ``` 3. In your `console-values.yaml`: ```yaml config: kafka: brokers: - redpanda-0.redpanda.redpanda.svc.cluster.local:9093 tls: enabled: true caFilepath: /etc/console/secrets/ca.crt insecureSkipTlsVerify: true # For local/testing only secretMounts: - name: redpanda-console secretName: redpanda-console path: /etc/console/secrets ``` 4. Upgrade or install Redpanda Console: ```bash helm upgrade --install redpanda-console redpanda/console \ --namespace redpanda \ --values console-values.yaml ``` Redpanda Console now connects securely to your Redpanda cluster using TLS. For production, set `insecureSkipTlsVerify: false` and use a trusted CA. ## [](#deploy-redpanda-console-as-standalone-service-with-yaml-manifests)Deploy Redpanda Console as standalone service with YAML manifests If you prefer to deploy using YAML manifests, you can create the following resources: console-deployment.yaml ```yaml apiVersion: apps/v1 kind: Deployment metadata: name: redpanda-console namespace: redpanda labels: app.kubernetes.io/name: console app.kubernetes.io/component: console spec: replicas: 2 selector: matchLabels: app.kubernetes.io/name: console template: metadata: labels: app.kubernetes.io/name: console spec: affinity: podAntiAffinity: preferredDuringSchedulingIgnoredDuringExecution: - weight: 100 podAffinityTerm: labelSelector: matchLabels: app.kubernetes.io/name: console topologyKey: kubernetes.io/hostname containers: - name: console image: docker.redpanda.com/redpandadata/console:v3.7.1 ports: - containerPort: 8080 name: http resources: requests: cpu: 200m memory: 512Mi limits: cpu: 1000m memory: 2Gi env: - name: KAFKA_BROKERS value: "redpanda-0.redpanda.redpanda.svc.cluster.local:9092,redpanda-1.redpanda.redpanda.svc.cluster.local:9092,redpanda-2.redpanda.redpanda.svc.cluster.local:9092" livenessProbe: httpGet: path: /health port: http initialDelaySeconds: 30 periodSeconds: 10 readinessProbe: httpGet: path: /health port: http initialDelaySeconds: 5 periodSeconds: 5 ``` console-service.yaml ```yaml apiVersion: v1 kind: Service metadata: name: redpanda-console namespace: redpanda labels: app.kubernetes.io/name: console spec: type: LoadBalancer ports: - port: 8080 targetPort: http protocol: TCP name: http selector: app.kubernetes.io/name: console ``` For more complex configurations, create a ConfigMap: console-config.yaml ```yaml apiVersion: v1 kind: ConfigMap metadata: name: redpanda-console-config namespace: redpanda data: config.yaml: | kafka: brokers: - redpanda-0.redpanda.redpanda.svc.cluster.local:9092 - redpanda-1.redpanda.redpanda.svc.cluster.local:9092 - redpanda-2.redpanda.redpanda.svc.cluster.local:9092 server: listenPort: 8080 console: enabled: true ``` Apply the manifests: ```bash kubectl apply -f console-config.yaml kubectl apply -f console-deployment.yaml kubectl apply -f console-service.yaml ``` ## [](#configuration)Configuration Make sure to configure the following settings in your Console CR, values file, or ConfigMap: ### [](#connect-to-redpanda)Connect to Redpanda Configure the connection to your Redpanda cluster by setting the broker addresses in your Console CR or values file. See [Configure Redpanda Console to Connect to a Redpanda Cluster](../../../../console/config/connect-to-redpanda/). ### [](#authentication-and-security)Authentication and security For production deployments, configure: - **TLS encryption**: Enable TLS for secure communication - **SASL authentication**: Configure SASL if Redpanda uses authentication - **RBAC**: Set up role-based access control Configure authentication based on your deployment method. #### Operator When you use `clusterRef`, the operator automatically inherits SASL and TLS settings from the referenced Redpanda cluster. No additional Console configuration is needed. To configure SASL manually with `staticConfiguration`: ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Console metadata: name: redpanda-console namespace: redpanda spec: cluster: staticConfiguration: kafka: brokers: - redpanda-0.redpanda.redpanda.svc.cluster.local:9092 sasl: enabled: true mechanism: SCRAM-SHA-256 secret: kafka: saslPassword: ``` You can also reference an existing Kubernetes Secret for credentials: ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Console metadata: name: redpanda-console namespace: redpanda spec: cluster: staticConfiguration: kafka: brokers: - redpanda-0.redpanda.redpanda.svc.cluster.local:9092 sasl: enabled: true mechanism: SCRAM-SHA-256 username: console-user passwordFilepath: /etc/console/secrets/password secretMounts: - name: kafka-credentials secretName: console-kafka-credentials path: /etc/console/secrets ``` #### Helm Example with SASL authentication: ```yaml config: kafka: brokers: - redpanda-0.redpanda.redpanda.svc.cluster.local:9092 sasl: enabled: true mechanism: SCRAM-SHA-256 username: console-user password: console-password ``` See [Redpanda Console Security](../../../../console/config/security/). ## [](#verify-deployment)Verify deployment Use the following steps to confirm that Redpanda Console is running and accessible. ### Operator 1. Check the Console CR status: ```bash kubectl get console -n redpanda ``` The output shows the replica status of your Console deployment: ```bash NAME REPLICAS UPDATED READY AVAILABLE redpanda-console 2 2 2 2 ``` 2. Check pod status: ```bash kubectl get pods -n redpanda -l app.kubernetes.io/name=console ``` 3. Check service status: ```bash kubectl get svc -n redpanda redpanda-console ``` 4. Access the Redpanda Console: 1. If using LoadBalancer: ```bash kubectl get svc -n redpanda redpanda-console -o jsonpath='{.status.loadBalancer.ingress[0].ip}' ``` 2. If using port-forward for testing: ```bash kubectl port-forward -n redpanda svc/redpanda-console 8080:8080 ``` Open [http://localhost:8080](http://localhost:8080) in your browser. ### Helm 1. Check pod status: ```bash kubectl get pods -n redpanda -l app.kubernetes.io/name=console ``` 2. Check service status: ```bash kubectl get svc -n redpanda redpanda-console ``` 3. Access the Redpanda Console: 1. If using LoadBalancer: ```bash kubectl get svc -n redpanda redpanda-console -o jsonpath='{.status.loadBalancer.ingress[0].ip}' ``` 2. If using port-forward for testing: ```bash kubectl port-forward -n redpanda svc/redpanda-console 8080:8080 ``` Open [http://localhost:8080](http://localhost:8080) in your browser. ## [](#scaling)Scaling For production deployments, consider the following scaling strategies: ### [](#horizontal-scaling)Horizontal scaling Scale the deployment: ```bash kubectl scale deployment redpanda-console -n redpanda --replicas=3 ``` ### [](#auto-scaling)Auto-scaling Create an HPA for automatic scaling: console-hpa.yaml ```yaml apiVersion: autoscaling/v2 kind: HorizontalPodAutoscaler metadata: name: redpanda-console-hpa namespace: redpanda spec: scaleTargetRef: apiVersion: apps/v1 kind: Deployment name: redpanda-console minReplicas: 2 maxReplicas: 10 metrics: - type: Resource resource: name: cpu target: type: Utilization averageUtilization: 70 - type: Resource resource: name: memory target: type: Utilization averageUtilization: 80 ``` ## [](#monitoring)Monitoring Configure metrics exposure and Prometheus scraping for Redpanda Console. Enable monitoring for Redpanda Console: ```yaml config: server: metrics: enabled: true port: 9090 ``` ### [](#prometheus-servicemonitor)Prometheus ServiceMonitor If you use the [Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator), deploy a `ServiceMonitor` resource alongside Redpanda Console. Prometheus then discovers and scrapes Console metrics from the `/admin/metrics` endpoint. #### Operator To enable the ServiceMonitor in the Console custom resource, set `monitoring.enabled` to `true`: ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Console metadata: name: redpanda-console namespace: redpanda spec: monitoring: enabled: true (1) scrapeInterval: "30s" (2) labels: (3) release: kube-prometheus-stack cluster: clusterRef: name: redpanda ``` | 1 | Set to true to create a ServiceMonitor resource. Default: false. | | --- | --- | | 2 | How often Prometheus scrapes the metrics endpoint. Default: 1m. | | 3 | Additional labels to apply to the ServiceMonitor. Match your Prometheus Operator’s serviceMonitorSelector by applying the same labels here. | Apply the Console CR: ```bash kubectl apply -f console.yaml --namespace redpanda ``` #### Helm To enable the ServiceMonitor in the Console Helm chart, add the following to your `console-values.yaml`: ```yaml monitoring: enabled: true (1) scrapeInterval: "30s" (2) labels: {} (3) ``` | 1 | Set to true to create a ServiceMonitor resource. Default: false. | | --- | --- | | 2 | How often Prometheus scrapes the metrics endpoint. Default: 1m. | | 3 | Additional labels to apply to the ServiceMonitor. Match your Prometheus Operator’s serviceMonitorSelector by applying the same labels here. For example:monitoring: enabled: true labels: release: kube-prometheus-stack | If you deploy Redpanda Console as a subchart of the Redpanda Helm chart, configure monitoring under the `console` key. All `monitoring` options are available under this key. ```yaml console: monitoring: enabled: true ``` When the Console server is configured with TLS (`config.server.tls.enabled: true`), the ServiceMonitor uses HTTPS and configures CA validation for scraping. ## [](#troubleshooting)Troubleshooting - **Connection refused**: Verify Redpanda broker addresses and network policies - **Authentication failed**: Check SASL credentials and configuration - **Resource limits**: Monitor CPU and memory usage, adjust limits as needed ### [](#logs)Logs Check Redpanda Console logs: ```bash kubectl logs -n redpanda -l app.kubernetes.io/name=console -f ``` ## [](#next-steps)Next steps - [Configure Redpanda Console](../../../../console/config/configure-console/) - [Authentication in Redpanda Console](../../../../console/config/security/authentication/) - [Authorization in Redpanda Console](../../../../console/config/security/authorization/) --- # Page 26: Redpanda Console Kubernetes Requirements and Recommendations **URL**: https://docs.redpanda.com/current/deploy/console/kubernetes/k-requirements.md --- # Redpanda Console Kubernetes Requirements and Recommendations --- title: Redpanda Console Kubernetes Requirements and Recommendations latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: console/kubernetes/k-requirements page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: console/kubernetes/k-requirements.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/console/kubernetes/k-requirements.adoc description: System requirements and recommendations for deploying Redpanda Console on Kubernetes in production. page-git-created-date: "2025-08-15" page-git-modified-date: "2025-08-15" support-status: supported --- This page provides the system requirements and recommendations for deploying Redpanda Console on Kubernetes in production environments. ## [](#operating-system)Operating system - **Linux**: All major distributions (Ubuntu, CentOS, RHEL, Debian) - **Container platforms**: Docker, Kubernetes, OpenShift - **Cloud platforms**: AWS, GCP, Azure ## [](#cpu-and-memory)CPU and memory - **CPU**: Minimum 2 cores. Recommended 4+ cores for production. - **Memory**: Minimum 1 GiB per replica. Recommended 1-2 GiB for most workloads, 2 GiB+ for high concurrency or large data sets. ### [](#resource-requests-and-limits)Resource requests and limits Set resource requests to ensure Redpanda Console always has enough CPU and memory to start, and set higher limits to allow for bursts. For production, use conservative requests and higher limits. ```yaml resources: requests: cpu: 100m memory: 512Mi limits: cpu: 4000m memory: 2Gi ``` - **Requests**: Minimum guaranteed resources. Set conservatively to ensure scheduling on most nodes. - **Limits**: Maximum allowed resources. Set higher to allow for bursts. HPA can scale replicas based on CPU/memory utilization. ### [](#scheduling-constraints)Scheduling constraints Use node affinity and tolerations to control where Redpanda Console Pods are scheduled. Example: Node affinity to prefer nodes with a specific label ```yaml affinity: nodeAffinity: requiredDuringSchedulingIgnoredDuringExecution: nodeSelectorTerms: - matchExpressions: - key: node-role.kubernetes.io/console operator: In values: - "true" ``` Example: Tolerate a taint so Redpanda Console can run on tainted nodes ```yaml tolerations: - key: "console-only" operator: "Exists" effect: "NoSchedule" ``` - **Node affinity**: Ensures Pods are scheduled only on nodes with matching labels. - **Tolerations**: Allow Pods to be scheduled on nodes with specific taints. - Combine affinity and tolerations for advanced scheduling and isolation patterns. ### [](#auto-scaling)Auto-scaling Use the Horizontal Pod Autoscaler (HPA) to automatically scale based on CPU and memory utilization. ## [](#storage)Storage - **Minimum**: 1 GiB available disk space ## [](#network-requirements)Network requirements - **Redpanda connectivity**: TCP access to Redpanda brokers on configured ports - **Web interface**: HTTP/HTTPS access for users (typically port 8080 or 443) - **Schema Registry**: TCP access to Schema Registry, if used ## [](#security-considerations)Security considerations - **TLS encryption**: Configure TLS for all network communications - **Authentication**: Set up appropriate authentication mechanisms - **RBAC**: Implement role-based access control where supported - **Network policies**: Use Kubernetes Network Policies to restrict access ## [](#scaling-and-high-availability)Scaling and high availability - Deploy multiple Redpanda Console replicas for high availability and rolling updates. - Use pod anti-affinity to spread replicas across nodes. - For production, run at least two replicas. ## [](#separate-node-deployment)Separate node deployment Run Redpanda Console on separate nodes from Redpanda brokers for resource isolation and operational independence. ## [](#schema-registry-integration)Schema Registry integration - Allocate extra memory for schema caching if using Schema Registry. - Ensure reliable network connectivity and configure authentication as needed. ## [](#next-steps)Next steps - [Deploy Redpanda Console on Kubernetes](../deploy/) - [Configure Redpanda Console](../../../../console/config/configure-console/) ## [](#suggested-reading)Suggested reading - [Redpanda Console Security](../../../../console/config/security/) - [Redpanda Console Helm Chart Specification](../../../../reference/k-console-helm-spec/) --- # Page 27: Deploy Redpanda Console on Linux **URL**: https://docs.redpanda.com/current/deploy/console/linux.md --- # Deploy Redpanda Console on Linux --- title: Deploy Redpanda Console on Linux latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: console/linux/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: console/linux/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/console/linux/index.adoc description: Learn about deployment options for Redpanda Console on Linux, as well as requirements for installation. page-git-created-date: "2025-08-15" page-git-modified-date: "2025-08-15" support-status: supported --- Redpanda Console provides a web-based UI for managing and monitoring your Redpanda clusters. This topic describes how to deploy Redpanda Console on Linux and links to detailed, platform-specific instructions. - [Redpanda Console Linux Requirements and Recommendations](requirements/) System requirements and recommendations for deploying Redpanda Console on Linux in production. - [Deploy Redpanda Console on Linux](deploy/) Deploy Redpanda Console using Docker or the Linux packages. --- # Page 28: Deploy Redpanda Console on Linux **URL**: https://docs.redpanda.com/current/deploy/console/linux/deploy.md --- # Deploy Redpanda Console on Linux --- title: Deploy Redpanda Console on Linux latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: console/linux/deploy page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: console/linux/deploy.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/console/linux/deploy.adoc description: Deploy Redpanda Console using Docker or the Linux packages. page-git-created-date: "2025-08-15" page-git-modified-date: "2025-11-19" support-status: supported --- This page shows you how to deploy Redpanda Console on Linux using Docker or the packages. ## [](#prerequisites)Prerequisites - You must have a running Redpanda or Kafka cluster available to connect to. Redpanda Console requires a cluster to function. For instructions on deploying a Redpanda cluster, see [Linux Deployment Options](../../../redpanda/manual/production/). - Review the [system requirements for Redpanda Console on Linux](../requirements/). ## [](#deploy-with-docker)Deploy with Docker Run Redpanda Console as a Docker container: ```bash docker run -d \ --name redpanda-console \ -p 8080:8080 \ -e KAFKA_BROKERS=localhost:19092 \ docker.redpanda.com/redpandadata/console:v3.7.1 ``` ## [](#packaged)Deploy the packaged Redpanda Console Redpanda Console is available as OS packages (`deb`/`rpm`) for Linux distributions. The following instructions install the `redpanda-console` package from the official repositories and enable the systemd service for Redpanda Console. 1. Install Redpanda Console: ### Fedora/RedHat ```bash curl -1sLf 'https://dl.redpanda.com/nzc4ZYQK3WRGd9sy/redpanda/cfg/setup/bash.rpm.sh' | \ sudo -E bash && sudo yum install redpanda-console -y ``` ### Debian/Ubuntu ```bash curl -1sLf 'https://dl.redpanda.com/nzc4ZYQK3WRGd9sy/redpanda/cfg/setup/bash.deb.sh' | \ sudo -E bash && sudo apt-get install redpanda-console -y ``` 2. Start Redpanda Console: ```bash sudo systemctl enable --now redpanda-console ``` 3. Make sure that Redpanda Console is active and running: ```bash sudo systemctl status redpanda-console ``` ## [](#configuration)Configuration You can configure Redpanda Console using environment variables, command-line flags, or a YAML config file. See [Configure Redpanda Console](../../../../console/config/configure-console/) for details. ## [](#verify-deployment)Verify deployment Check that Redpanda Console is running and accessible at [http://localhost:8080](http://localhost:8080). ## [](#next-steps)Next steps - [Configure Redpanda Console](../../../../console/config/configure-console/) - [Authentication in Redpanda Console](../../../../console/config/security/authentication/) - [Authorization in Redpanda Console](../../../../console/config/security/authorization/) --- # Page 29: Redpanda Console Linux Requirements and Recommendations **URL**: https://docs.redpanda.com/current/deploy/console/linux/requirements.md --- # Redpanda Console Linux Requirements and Recommendations --- title: Redpanda Console Linux Requirements and Recommendations latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: console/linux/requirements page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: console/linux/requirements.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/console/linux/requirements.adoc description: System requirements and recommendations for deploying Redpanda Console on Linux in production. page-git-created-date: "2025-08-15" page-git-modified-date: "2025-08-15" support-status: supported --- This page provides the system requirements and recommendations for deploying Redpanda Console on Linux in production environments. ## [](#operating-system)Operating system - **Linux**: All major distributions (Ubuntu, CentOS, RHEL, Debian) - **Container platforms**: Docker, Kubernetes, OpenShift - **Cloud platforms**: AWS, GCP, Azure ## [](#cpu-and-memory)CPU and memory - **CPU**: Minimum 2 cores. Recommended 4+ cores for production. - **Memory**: Minimum 1 GiB per replica. Recommended 1-2 GiB for most workloads, 2 GiB+ for high concurrency or large data sets. ## [](#storage)Storage - **Minimum**: 1 GiB available disk space ## [](#network-requirements)Network requirements - **Redpanda connectivity**: TCP access to Redpanda brokers on configured ports - **Web interface**: HTTP/HTTPS access for users (typically port 8080 or 443) - **Schema Registry**: TCP access to Schema Registry, if used ## [](#security-considerations)Security considerations - **TLS encryption**: Configure TLS for all network communications - **Authentication**: Set up appropriate authentication mechanisms - **RBAC**: Implement role-based access control where supported - **Firewall rules**: Configure appropriate firewall rules to restrict access ## [](#scaling-and-high-availability)Scaling and high availability - Deploy multiple Redpanda Console replicas for high availability and rolling updates. - Use pod anti-affinity to spread replicas across nodes. - For production, run at least two replicas. ## [](#separate-node-deployment)Separate node deployment Run Redpanda Console on separate nodes from Redpanda brokers for resource isolation and operational independence. ## [](#schema-registry-integration)Schema Registry integration - Allocate extra memory for schema caching if using Schema Registry. - Ensure reliable network connectivity and configure authentication as needed. ## [](#next-steps)Next steps - [Deploy Redpanda Console on Linux](../deploy/) - [Configure Redpanda Console](../../../../console/config/configure-console/) ## [](#suggested-reading)Suggested reading - [Redpanda Console Security](../../../../console/config/security/) --- # Page 30: Deploy Kafka Connect **URL**: https://docs.redpanda.com/current/deploy/kafka-connect.md --- # Deploy Kafka Connect --- title: Deploy Kafka Connect latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kafka-connect/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kafka-connect/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/kafka-connect/index.adoc description: Overview of Kafka Connect deployment options and links to platform-specific guides. page-git-created-date: "2025-08-15" page-git-modified-date: "2025-08-15" support-status: supported --- Kafka Connect enables scalable and reliable streaming data integration with Redpanda. This section provides an overview of deployment options and links to platform-specific instructions. > 💡 **TIP** > > Try [Redpanda Connect](../../../redpanda-connect/home/) for a faster way to build streaming data pipelines. It’s fully compatible with the Kafka API but eliminates the complex setup and maintenance of Kafka Connect. Redpanda Connect also comes with built-in connectors to support AI integrations. Refer to the platform-specific pages for prerequisites, configuration, and deployment steps. - [Deploy Kafka Connect in Kubernetes](k-deploy-kafka-connect/) Learn how to deploy and configure Kafka Connect using the standalone `connectors` Helm chart. - [Deploy Kafka Connect in Docker](deploy-kafka-connect/) Learn how to use the Docker image to configure connectors for Redpanda. --- # Page 31: Deploy Kafka Connect in Docker **URL**: https://docs.redpanda.com/current/deploy/kafka-connect/deploy-kafka-connect.md --- # Deploy Kafka Connect in Docker --- title: Deploy Kafka Connect in Docker latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kafka-connect/deploy-kafka-connect page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kafka-connect/deploy-kafka-connect.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/kafka-connect/deploy-kafka-connect.adoc description: Learn how to use the Docker image to configure connectors for Redpanda. page-git-created-date: "2025-08-15" page-git-modified-date: "2025-08-15" support-status: supported --- > 📝 **NOTE: Community** > > **The Redpanda Connectors Docker image is a community-supported artifact**. Redpanda Data does not provide enterprise support for this image. For support, reach out to the Redpanda team in [Redpanda Community Slack](https://redpanda.com/slack). > 💡 **TIP** > > Try [Redpanda Connect](../../../../redpanda-connect/home/) for a faster way to build streaming data pipelines. It’s fully compatible with the Kafka API but eliminates the complex setup and maintenance of Kafka Connect. Redpanda Connect also comes with built-in connectors to support AI integrations. The [Redpanda Connectors Docker image](https://hub.docker.com/r/redpandadata/connectors/tags) includes a pre-configured instance of [Kafka Connect](https://redpanda.com/guides/kafka-tutorial/what-is-kafka-connect) that works with Redpanda. This image contains _only_ the MirrorMaker2 connector but you can build a custom image to install additional connectors. The latest Docker image contains: - Red Hat Enterprise Linux 8.9 - OpenJDK 21 LTS - Kafka Connect - JMX-Exporter JMX Prometheus JavaAgent The image also includes the following connectors as plugins: - MirrorSourceConnector - MirrorCheckpointConnector - MirrorHeartbeatConnector ## [](#docker-image-configuration-properties)Docker image configuration properties The following table lists the available Docker image properties. | Property | Description | | --- | --- | | CONNECT_BOOTSTRAP_SERVERS | Comma-separated list of host and port pairs that are the addresses of the Redpanda brokers. | | CONNECT_CONFIGURATION | Properties-based Kafka Connect configuration. | | CONNECT_ADDITIONAL_CONFIGURATION | Comma-separated Kafka Connect properties. This can be used as an alternative to the CONNECT_CONFIGURATION property. If the same Kafka Connect property is defined in CONNECT_CONFIGURATION and CONNECT_ADDITIONAL_CONFIGURATION, the one from CONNECT_ADDITIONAL_CONFIGURATION is used.Example: offset.flush.interval.ms=1000,producer.linger.ms=1 | | CONNECT_SASL_MECHANISM | SASL mechanism. Allowed values: "plain","scram-sha-256", or "scram-sha-512". Do not set if SASL is not used.Default: not set | | CONNECT_SASL_USERNAME | SASL username used to authenticate connecting to a Redpanda broker.Default: not set | | CONNECT_SASL_PASSWORD_FILE | Relative path to a file containing the SASL password, relative to the /opt/kafka/connect-password directory. If the file is in /opt/kafka/connect-password/pass-dir/password, then set pass-dir/password. The SASL password is given in plain text.Default: not set | | CONNECT_TLS_ENABLED | Set to "true" if TLS enabled, and "false" if not.Default: "false" | | CONNECT_TLS_AUTH_CERT | TLS authentication certificate location (relative path from /opt/kafka/connect-certs/).For example: "user-secret/user.crt" when file is in /opt/kafka/connect-certs/user-secret/user.crt | | CONNECT_TLS_AUTH_KEY | TLS authentication key location (relative path from /opt/kafka/connect-certs/).For example: "user-secret/user.key" when file is in /opt/kafka/connect-certs/user-secret/user.key | | CONNECT_TRUSTED_CERTS | Truststore locations (relative path from /opt/kafka/connect-certs/).For example: "my-secret/ca.crt;my-secret/new-cert.crt" when file is in /opt/kafka/connect-certs/my-secret/ca.crt and /opt/kafka/connect-certs/my-secret/new-cert.crt | | CONNECT_ADDITIONAL_TLS_AUTH_CERT | Additional TLS authentication certificate location, used, for example, to connect with the source MM2 cluster, (relative path from /opt/kafka/connect-certs/).For example: "user-secret/user.crt" when file is in /opt/kafka/connect-certs/user-secret/user.crt | | CONNECT_ADDITIONAL_TLS_AUTH_KEY | Additional TLS authentication key location, used, for example, to connect with the source MM2 cluster (relative path from /opt/kafka/connect-certs/).For example: "user-secret/user.key" when file is in /opt/kafka/connect-certs/user-secret/user.key | | CONNECT_ADDITIONAL_TRUSTED_CERTS | Additional truststore locations, used, for example, to connect with the source MM2 cluster (relative path from /opt/kafka/connect-certs/).For example: "my-secret/cert.crt;my-secret/new-cert.crt" when file is in /opt/kafka/connect-certs/my-secret/cert.crt and /opt/kafka/connect-certs/my-secret/new-cert.crt | | CONNECT_METRICS_ENABLED | Set to "true" to enable Prometheus metrics, port 9404. Set to "false" to disable. Default: "true" | | CONNECT_PLUGIN_PATH | Comma-separated list of directories with plugins to load by Kafka Connect.Default: /opt/kafka/redpanda-plugins | | CONNECT_GC_LOG_ENABLED | Set to "true" to enable GC logging. Set to "false" to disable GC logs.Default: "false" | | CONNECT_HEAP_OPTS | JVM heap options. For example -Xms2G -Xmx2G.Default: -Xms256M -Xmx256M | | CONNECT_LOG4J_CONFIGURATION | By default, Kafka Connect logs at "info" info level using Redpanda Console appender. Use this property to pass custom log4j properties-based configuration. | | CONNECT_LOG_LEVEL | By default, Kafka Connect logs at "warn" info level using Redpanda Console appender. Use "info" to change the log level to info or "debug" for debug log level. | ## [](#install-new-connector-type)Install new connector type To install a new connector type: 1. Prepare a new connector jar. Place a fat-jar or a jar with all dependent jars in a dedicated directory. For example: `./connect-plugins/snowflake-sink/snowflake-sink-fat.jar` 2. Mount a volume to bind the directory with a container. For example, make the `./connect-plugins` directory content visible in `/opt/kafka/connect-plugins` in a container: ```yaml volumes: - ./connect-plugins:/opt/kafka/connect-plugins ``` 3. Use the `CONNECT_PLUGIN_PATH` image property to configure a directory with the new connector. Use Kafka Connect to discover new connectors. For example: ```yaml CONNECT_PLUGIN_PATH: "/opt/kafka/connect-plugins" ``` 4. The new connector type should be discovered by Kafka Connect automatically on startup. Use the `/connector-plugins` Kafka Connect REST endpoint to check available connector types. For example: `curl localhost:8083/connector-plugins` > 💡 **TIP** > > Create a separate child directory for each connector, and place the connector’s jar files and other resource files in that child directory. ## [](#configure-sasl)Configure SASL To configure SASL: 1. Prepare the SASL user and password, making sure the user has necessary permissions. - Required: Write access for internal topics and access to consumer groups (so all workers in the cluster can communicate with each other). - ACLs depend on used connector type (source/sink) and topics used by the connectors. 2. Create a file containing the plain text password in a dedicated directory. For example, `./connect-password/redpanda-password/password` where the `password` file contains just the password 3. Mount a volume to bind the directory with a container. For example, make the `./connect-password` directory content visible in `/opt/kafka/connect-password` in a container: ```yaml volumes: - ./connect-password:/opt/kafka/connect-password ``` 4. Use `CONNECT_SASL_USERNAME` to set the SASL username, and use `CONNECT_SASL_PASSWORD_FILE` to set the relative path to a password file. For example, if the file is in `/opt/kafka/connect-password/redpanda-password/password`, use the `redpanda-password/password` value. ```yaml CONNECT_SASL_USERNAME: "connect-user" CONNECT_SASL_PASSWORD_FILE: "redpanda-password/password" ``` ## [](#configure-tls)Configure TLS To configure TLS: 1. Prepare Redpanda cluster certificate and key, and place them in a dedicated directory. For example: ./connect-certs/ca.crt ./connect-certs/client.crt ./connect-certs/client.key 2. Mount a volume to bind the directory with a container. For example, make the `./connect-certs` directory content visible in `/opt/kafka/connect-certs/user-secret` in a container: ```yaml volumes: - ./connect-certs:/opt/kafka/connect-certs/user-secret ``` 3. Set the `CONNECT_TLS_ENABLED` property to `"true"`. 4. Use the `CONNECT_TLS_AUTH_CERT`, `CONNECT_TRUSTED_CERTS`, and `CONNECT_TLS_AUTH_KEY` image properties to configure the relative path to the certificate and key. For example, if the files are in `/opt/kafka/connect-certs/user-secret`, use: ```yaml CONNECT_TRUSTED_CERTS: "user-secret/ca.crt" CONNECT_TLS_AUTH_CERT: "user-secret/client.crt" CONNECT_TLS_AUTH_KEY: "user-secret/client.key" ``` ## [](#connect-with-docker-compose)Connect with Docker Compose You can use the following Docker Compose sample file to connect: docker-compose.yml ```yaml version: '3.8' services: connect: image: docker.redpanda.com/redpandadata/connectors:latest volumes: - ./connect-password:/opt/kafka/connect-password - ./connect-plugins:/opt/kafka/connect-plugins - ./connect-certs:/opt/kafka/connect-certs/user-secret hostname: connect ports: - "8083:8083" environment: CONNECT_CONFIGURATION: | key.converter=org.apache.kafka.connect.converters.ByteArrayConverter value.converter=org.apache.kafka.connect.converters.ByteArrayConverter group.id=connectors-group offset.storage.topic=_connectors_offsets config.storage.topic=_connectors_configs status.storage.topic=_connectors_status config.storage.replication.factor=-1 offset.storage.replication.factor=-1 status.storage.replication.factor=-1 CONNECT_BOOTSTRAP_SERVERS: ...data.redpanda:30499,...data.redpanda:30499,...data.redpanda:30499 CONNECT_GC_LOG_ENABLED: "false" CONNECT_HEAP_OPTS: -Xms1G -Xmx1G CONNECT_METRICS_ENABLED: "false" CONNECT_SASL_MECHANISM: "scram-sha-256" CONNECT_SASL_USERNAME: "connect-user" CONNECT_SASL_PASSWORD_FILE: "redpanda-password/password" CONNECT_TLS_ENABLED: "true" CONNECT_TRUSTED_CERTS: "user-secret/ca.crt" CONNECT_TLS_AUTH_CERT: "user-secret/client.crt" CONNECT_TLS_AUTH_KEY: "user-secret/client.key" CONNECT_PLUGIN_PATH: "/opt/kafka/connect-plugins" ``` ├── ... ├── connect-certs │ ├── ca.crt # A file with Redpanda cluster CA cert │ ├── client.crt # A file with Redpanda cluster cert │ └── client.key # A file with Redpanda cluster key ├── connect-password │ └── redpanda-password │ └──password # A file with SASL password ├── connect-plugins │ └── custom-connector │ └── custom-sink-connector-fat.jar # Connector fat jar or jar and dependencies jars └── docker-compose.yaml # A docker-compose file To connect with Docker Compose: 1. From a directory containing the `docker-compose.yaml` file, run: ```bash docker-compose up ``` 2. To list installed plugins, run: ```bash curl localhost:8083/connector-plugins ``` 3. To get Kafka Connect basic information, run: ```bash curl localhost:8083/ ``` 4. Metrics are available at `localhost:9404/`. 5. Use the Redpanda Console or Kafka Connect REST API to manage connectors. ## [](#connect-to-a-redpanda-cloud-cluster)Connect to a Redpanda Cloud cluster To connect to a Redpanda Cloud cluster with Docker Compose: 1. Use `rpk` or Redpanda Console (**Security** tab) to create a Redpanda user. 2. Create ACLs for the user. 3. Set the username in the `CONNECT_SASL_USERNAME` property. 4. Create a file containing the user password (for example, in the path `passwords/redpanda-password/password`). Specify this path in the `CONNECT_SASL_PASSWORD_FILE` property. 5. Specify a value in the `CONNECT_BOOTSTRAP_SERVERS` property. You can view this value in Redpanda Console > **Overview** > **Kafka API**, in the `Bootstrap server URL` option. 6. Set the `CONNECT_SASL_MECHANISM` property value to `"scram-sha-256"`. 7. Set the `CONNECT_TLS_ENABLED` property value to `"true"`. docker-compose.yml ```yaml version: '3.8' connect: image: docker.redpanda.com/redpandadata/connectors:latest volumes: - ./passwords:/opt/kafka/connect-password/passwords hostname: connect ports: - "8083:8083" environment: CONNECT_CONFIGURATION: | key.converter=org.apache.kafka.connect.converters.ByteArrayConverter value.converter=org.apache.kafka.connect.converters.ByteArrayConverter group.id=connectors-group offset.storage.topic=_connectors_offsets config.storage.topic=_connectors_configs status.storage.topic=_connectors_status config.storage.replication.factor=-1 offset.storage.replication.factor=-1 status.storage.replication.factor=-1 CONNECT_BOOTSTRAP_SERVERS: seed-....redpanda.com:9092 CONNECT_GC_LOG_ENABLED: "false" CONNECT_HEAP_OPTS: -Xms1G -Xmx1G CONNECT_SASL_MECHANISM: "scram-sha-256" CONNECT_SASL_USERNAME: "connectors-user" CONNECT_SASL_PASSWORD_FILE: "passwords/redpanda-password/password" CONNECT_TLS_ENABLED: "true" ``` ├── ... ├── passwords │ └── redpanda-password │ └──password # A file with SASL password └── docker-compose.yaml # A docker-compose file ### [](#redpanda-cloud-schema-registry)Redpanda Cloud Schema Registry For converters using Schema Registry (like AvroConverter, JsonConverter), use the following connector configuration properties to set up a connection with Schema Registry: | Property | Description | | --- | --- | | key.converter | Key converter class to use for the connector. | | key.converter.schema.registry.url | Key converter Schema Registry URL, which you can view in the cluster Overview > Schema Registry. | | key.converter.basic.auth.credentials.source | Key converter authentication method, should be USER_INFO. | | key.converter.basic.auth.user.info | Key converter user and password used for authentication, separated by a colon. | | value.converter | Value converter class to use for the connector. | | value.converter.schema.registry.url | Value converter Schema Registry URL, which you can view in the cluster Overview > Schema Registry. | | value.converter.basic.auth.credentials.source | Value converter authentication method, should be USER_INFO. | | value.converter.basic.auth.user.info | Value converter user and password used for authentication, separated by a colon. | Example: ```json { .... "value.converter.schema.registry.url": "https://schema-registry-....redpanda.com:30081", "value.converter.basic.auth.credentials.source": "USER_INFO", "value.converter.basic.auth.user.info": "connect-user:secret-password" } ``` ## [](#manage-connectors-with-kafka-connect)Manage connectors with Kafka Connect You can manage connectors using the Kafka Connect REST API. ### [](#view-version-of-kafka-connect-worker)View version of Kafka Connect worker To view the version of the Kafka Connect worker, run: ```bash curl localhost:8083 | jq ``` ### [](#view-list-of-connector-plugins)View list of connector plugins To view the list of available connector plugins, run: ```bash curl localhost:8083/connector-plugins | jq ``` ### [](#view-list-of-active-connectors)View list of active connectors To view the list of active connectors, run: ```bash curl 'http://localhost:8083/connectors?expand=status&expand=info' | jq ``` ### [](#create-connector)Create connector To create the connector, run: ```bash curl "localhost:8083/connectors" -H 'Content-Type: application/json' --data-raw '' ``` For example: ```bash curl "localhost:8083/connectors" \ -H 'Content-Type: application/json' \ --data-raw '{ "name": "heartbeat-connector", "config": { "connector.class": "org.apache.kafka.connect.mirror.MirrorHeartbeatConnector", "heartbeats.topic.replication.factor": "1", "replication.factor": "1", "source.cluster.alias": "source", "source.cluster.bootstrap.servers": "redpanda:29092", "target.cluster.bootstrap.servers": "redpanda:29092"}}' ``` ### [](#view-connector-status)View connector status To view connector status, run: ```bash curl localhost:8083/connectors//status ``` For example: ```bash curl localhost:8083/connectors/heartbeat-connector/status ``` ### [](#delete-connector)Delete connector To delete the connector, run: ```bash curl "localhost:8083/connectors/" -X 'DELETE' ``` For example: ```bash curl "localhost:8083/connectors/heartbeat-connector" -X 'DELETE' ``` ## [](#manage-connectors-with-redpanda-console)Manage connectors with Redpanda Console Redpanda Console provides a user interface that lets you manage multiple Kafka Connect clusters. You can inspect or patch connectors; restart, pause, and resume connector tasks; and delete connectors. For details on how to set it up, see [Connect Redpanda Console to Kafka Connect Clusters](../../../console/config/kafka-connect/). ## Suggested labs - [Disaster Recovery with Envoy and Shadowing](/redpanda-labs/docker-compose/envoy-shadowing/) - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Stream Jira Issues to Redpanda for Real-Time Metrics](/redpanda-labs/docker-compose/jira-metrics-pipeline/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) - [Set Up MySQL CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-mysql-json/) - [Set Up Postgres CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-postgres-json/) See more [Search all labs](/redpanda-labs) --- # Page 32: Deploy Kafka Connect in Kubernetes **URL**: https://docs.redpanda.com/current/deploy/kafka-connect/k-deploy-kafka-connect.md --- # Deploy Kafka Connect in Kubernetes --- title: Deploy Kafka Connect in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kafka-connect/k-deploy-kafka-connect page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kafka-connect/k-deploy-kafka-connect.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/kafka-connect/k-deploy-kafka-connect.adoc description: Learn how to deploy and configure Kafka Connect using the standalone connectors Helm chart. page-git-created-date: "2025-08-15" page-git-modified-date: "2025-08-15" support-status: supported --- This topic describes how to deploy Kafka Connect in Kubernetes using the standalone `connectors` Helm chart. > 📝 **NOTE: Community** > > **The Connectors Helm chart is a community-supported artifact**. Redpanda Data does not provide enterprise support for this chart. For support, reach out to the Redpanda team in [Redpanda Community Slack](https://redpanda.com/slack). > 💡 **TIP** > > Try [Redpanda Connect](../../../../redpanda-connect/home/) for a faster way to build streaming data pipelines. It’s fully compatible with the Kafka API but eliminates the complex setup and maintenance of Kafka Connect. Redpanda Connect also comes with built-in connectors to support AI integrations. The `connectors` Helm chart is a standalone chart that deploys an instance of [Kafka Connect](https://redpanda.com/guides/kafka-tutorial/what-is-kafka-connect). The underlying Docker image contains _only_ the MirrorMaker2 connector but you can build a custom image to install additional connectors. | Built-In Connector | Description | | --- | --- | | MirrorSourceConnector | A source connector that replicates records between multiple Kafka clusters. It is part of Kafka’s MirrorMaker, which provides capabilities for mirroring data across Kafka clusters. | | MirrorCheckpointConnector | A source connector that ensures the mirroring process can resume from where it left off in case of failures. It tracks and emits checkpoints that mirror the offsets of the source and target clusters. | | MirrorHeartbeatConnector | A source connector that emits heartbeats to target topics at a defined interval, enabling MirrorMaker to track active topics on the source cluster and synchronize consumer groups across clusters. | > 📝 **NOTE** > > If you want to use other connectors, you must create a custom Docker image that includes them as plugins. See [Install a new connector](#install-a-new-connector). ## [](#prerequisites)Prerequisites - A Kubernetes cluster. You must have `kubectl` with at least version 1.27.0-0. To check if you have `kubectl` installed: ```bash kubectl version --client ``` - [Helm](https://helm.sh/docs/intro/install/) installed with at least version 3.10.0. To check if you have Helm installed: ```bash helm version ``` - You need [jq](https://stedolan.github.io/jq/download/) to parse JSON results when using the Kafka Connect REST API. - An understanding of [Kafka Connect](https://kafka.apache.org/20/documentation.html#connect_overview). ## [](#migrating-from-the-subchart)Migrating from the subchart If you’re currently using the connectors subchart (part of the Redpanda Helm chart), you need to migrate to the standalone connectors chart. Follow these steps: > 📝 **NOTE** > > The example values assume a Redpanda deployment named `redpanda` in the `default` namespace. Adjust the values according to your actual deployment. 1. Copy your existing connectors configuration from your Redpanda values file: Extract the `connectors` section from your current Redpanda Helm values and create a new values file for the standalone chart. Example migration ```yaml # Before (in Redpanda values.yaml) connectors: enabled: true auth: sasl: enabled: true brokerTLS: enabled: true # After (in new connectors-values.yaml) connectors: bootstrapServers: "redpanda-0.redpanda.default.svc.cluster.local:9093,redpanda-1.redpanda.default.svc.cluster.local:9093,redpanda-2.redpanda.default.svc.cluster.local:9093" auth: sasl: enabled: true brokerTLS: enabled: true ``` 2. Remove the connectors configuration from your Redpanda values file: ```yaml # Remove or comment out the entire connectors section # connectors: # enabled: true # ... ``` 3. Upgrade your Redpanda deployment: ```bash helm upgrade redpanda redpanda/redpanda \ --namespace \ --values redpanda-values.yaml ``` This will remove the connectors subchart deployment. 4. Deploy the standalone connectors chart: ```bash helm install redpanda-connectors redpanda/connectors \ --namespace \ --values connectors-values.yaml ``` 5. [Update your Redpanda Console configuration](#console) to point to the new service name if needed. ## [](#deploy-the-standalone-helm-chart)Deploy the standalone Helm chart The `connectors` Helm chart is a standalone chart that you deploy separately from your Redpanda cluster. The chart includes a Pod that runs Kafka Connect and the built-in connectors. The Pod is managed by a Deployment that you configure through Helm values. To connect Redpanda Console to your Kafka Connect deployment, you’ll need to configure Redpanda Console with the appropriate service endpoint. ![Redpanda Connectors deployed in a Kubernetes cluster with three worker nodes.](../../../shared/_images/k-connectors-architecture.png) > 📝 **NOTE** > > Do not schedule Pods that run Kafka Connect on the same nodes as Redpanda brokers. Redpanda brokers require access to all node resources. See [Tolerations](#tolerations) and [Affinity rules](#affinity-rules). ### [](#deploy-kafka-connect)Deploy Kafka Connect To deploy Kafka Connect using the standalone chart, you need to configure connection settings to your Redpanda cluster. 1. Create a values file for the connectors chart: `connectors-values.yaml` ```yaml # Connection to Redpanda brokers connectors: bootstrapServers: "" # Configure TLS if your Redpanda cluster has TLS enabled brokerTLS: enabled: true ca: secretRef: "redpanda-default-cert" secretNameOverwrite: "ca.crt" # Configure SASL if your Redpanda cluster has SASL enabled auth: sasl: enabled: false mechanism: "SCRAM-SHA-512" userName: "" secretRef: "" ``` > 📝 **NOTE** > > To get the correct bootstrap servers for your Redpanda cluster, run: > > ```bash > kubectl run -it --restart=Never --rm --image busybox busybox -- ash -c 'nslookup -type=srv _kafka._tcp...svc.cluster.local | tail -n +4 | head -n -1 | awk '"'"'{print $7 ":" $6}'"'"'' > ``` > > Replace `` and `` with your actual release name and namespace. 2. Deploy the connectors chart: ```bash helm upgrade --install redpanda-connectors redpanda/connectors \ --namespace \ --create-namespace \ --values connectors-values.yaml ``` Replace `` with the namespace where you want to deploy Kafka Connect. 3. [Verify the deployment](#verify-the-deployment) using the Kafka Connect REST API or by configuring Redpanda Console. ### [](#example-values-file)Example values file Here’s a complete example values file that shows common configuration options: `connectors-values.yaml` ```yaml # Connection to Redpanda brokers connectors: bootstrapServers: "redpanda-0.redpanda.redpanda.svc.cluster.local:9093" # TLS configuration (disabled for local testing) brokerTLS: enabled: false # SASL authentication (disabled for local testing) auth: sasl: enabled: false # Resource configuration for local testing container: resources: requests: cpu: "0.5" memory: 1Gi limits: cpu: "1" memory: 1Gi javaMaxHeapSize: 512M # Single replica for local testing (testing scaling to 2) deployment: replicas: 2 # Monitoring disabled for local testing monitoring: enabled: false # Logging logging: level: "info" ``` ## [](#console)Configure Redpanda Console to connect to Kafka Connect To use Redpanda Console to manage your Kafka Connect deployment, you need to configure Redpanda Console to connect to the Kafka Connect service. ### [](#check-your-redpanda-console-version)Check your Redpanda Console version Redpanda Console configuration syntax varies by major version. Before configuring, determine which version you’re using: ```bash # Check console version from deployment kubectl get deployment -n redpanda-console -o jsonpath='{.spec.template.spec.containers[0].image}' # Or check from running pod kubectl get pod -n -l app.kubernetes.io/name=console -o jsonpath='{.items[0].spec.containers[0].image}' # Or check from console logs kubectl logs -n -l app.kubernetes.io/name=console | grep "started Redpanda Console" ``` If you see output like `redpandadata/console:v2.8.0`, you’re using Redpanda Console v2.x. If you see `redpandadata/console:v3.0.0`, you’re using Redpanda Console v3.x. ### [](#redpanda-console-deployed-as-part-of-redpanda-chart)Redpanda Console deployed as part of Redpanda chart If the Redpanda Console is deployed as part of the Redpanda Helm chart (the default), add the following configuration to your Redpanda values: #### Redpanda Console v2.x ```yaml console: enabled: true console: config: connect: enabled: true clusters: - name: "redpanda-connectors" url: "http://redpanda-connectors:8083" tls: enabled: false ``` #### Redpanda Console v3.x ```yaml console: enabled: true console: config: kafkaConnect: enabled: true clusters: - name: "redpanda-connectors" url: "http://redpanda-connectors:8083" tls: enabled: false ``` > 📝 **NOTE** > > If you deployed the connectors chart with a different release name, update the URL accordingly. The service name follows the pattern `:8083`. If Redpanda Console is deployed in a different namespace than Kafka Connect, use the fully qualified service name: #### Redpanda Console v2.x ```yaml console: enabled: true console: config: connect: enabled: true clusters: - name: "redpanda-connectors" url: "http://redpanda-connectors..svc.cluster.local:8083" tls: enabled: false ``` #### Redpanda Console v3.x ```yaml console: enabled: true console: config: kafkaConnect: enabled: true clusters: - name: "redpanda-connectors" url: "http://redpanda-connectors..svc.cluster.local:8083" tls: enabled: false ``` Update your Redpanda deployment: ```bash helm upgrade redpanda redpanda/redpanda \ --namespace \ --values redpanda-values.yaml ``` ### [](#troubleshooting-redpanda-console-connectivity)Troubleshooting Redpanda Console connectivity If you see "Kafka Connect is not configured in Redpanda Console" or cannot access connectors: 1. Ensure you’re using the correct configuration syntax for your Redpanda Console version (see [Check your Redpanda Console version](#check-your-redpanda-console-version)). 2. Check if Redpanda Console can connect to Kafka Connect: ```bash kubectl logs -n -l app.kubernetes.io/name=console --tail=20 ``` Look for these successful connection messages: "creating Kafka connect HTTP clients and testing connectivity to all clusters" "tested Kafka connect cluster connectivity","successful\_clusters":1,"failed\_clusters":0" "successfully create Kafka connect service" 3. Verify Redpanda Console can reach Kafka Connect service: ```bash kubectl exec -n deployment/redpanda-console -- curl -s http://redpanda-connectors..svc.cluster.local:8083 ``` This should return Kafka Connect version information. 4. Verify the connector service exists and is accessible: ```bash kubectl get svc -n | grep connectors ``` 5. If configuration changes aren’t taking effect: ```bash kubectl delete pod -n -l app.kubernetes.io/name=console ``` ### [](#verification-test)Verification test After you’ve deployed the connectors chart, you can verify everything is working with this test: 1. Get the connector Pod name: ```bash POD_NAME=$(kubectl get pod -l app.kubernetes.io/name=connectors --namespace -o jsonpath='{.items[0].metadata.name}') ``` 2. Test basic connectivity: ```bash echo "Testing Kafka Connect REST API..." kubectl exec $POD_NAME --namespace -- curl -s localhost:8083 | jq '.version' ``` 3. List available connector plugins: ```bash echo "Available connector plugins:" kubectl exec $POD_NAME --namespace -- curl -s localhost:8083/connector-plugins | jq '.[].class' ``` 4. Test cluster connectivity: ```bash echo "Testing Redpanda cluster connectivity..." kubectl exec $POD_NAME --namespace -- curl -s localhost:8083/connectors ``` If all commands completed without errors, Kafka Connect is working correctly. If any command fails, refer to the [Troubleshoot common issues](#troubleshoot-common-issues) section. ## [](#configuration-advice)Configuration advice This section provides advice for configuring the standalone `connectors` Helm chart. For all available settings, see [Redpanda Connectors Helm Chart Specification](../../../reference/k-connector-helm-spec/). ### [](#security-configuration)Security configuration This section covers security-related configuration for the `connectors` Helm chart. #### [](#authentication)Authentication If your Redpanda cluster has SASL enabled, configure SASL authentication for secure communication with your Kafka connectors. ```yaml auth: sasl: enabled: true mechanism: "SCRAM-SHA-512" userName: "admin" secretRef: "sasl-password-secret" ``` For all available settings, see the [Helm specification](../../../reference/k-connector-helm-spec/#auth). #### [](#tls-configuration)TLS configuration If your Redpanda cluster has TLS enabled, configure TLS settings for secure communication: ```yaml brokerTLS: enabled: true ca: secretRef: "redpanda-default-cert" secretNameOverwrite: "ca.crt" ``` For all available settings, see the [Helm specification](../../../reference/k-connector-helm-spec/#brokertls). #### [](#service-account)Service account Restricting permissions is a best practice. Assign a dedicated service account for each deployment or app. ```yaml serviceAccount: create: true name: "redpanda-connector-service-account" ``` For all available settings, see the [Helm specification](../../../reference/k-connector-helm-spec/#serviceaccount). ### [](#scalability-and-reliability)Scalability and reliability This section covers configuration for scalable and reliable deployments. #### [](#number-of-replicas)Number of replicas You can scale the Kafka Connect Pods by modifying the `deployment.replicas` parameter in the Helm values. This parameter allows you to handle varying workloads by increasing or decreasing the number of running instances. ```yml deployment: replicas: 3 ``` The `replicas: 3` setting ensures that three instances of the Kafka Connect Pod will be running. You can adjust this number based on your needs. > 💡 **TIP** > > Redpanda Data recommends using an autoscaler such as [Keda](https://keda.sh/) to increase the number of Pod replicas automatically when certain conditions, such as high CPU or memory usage, are met. #### [](#container-resources)Container resources Specify resource requests and limits. Ensure that `javaMaxHeapSize` is not greater than `container.resources.limits.memory`. ```yaml container: resources: requests: cpu: 1 memory: 1Gi limits: cpu: 2 memory: 2Gi javaMaxHeapSize: 2G javaGCLogEnabled: false ``` For all available settings, see the [Helm specification](../../../reference/k-connector-helm-spec/#container). #### [](#deployment-strategy)Deployment strategy For smooth and uninterrupted updates, use the default `RollingUpdate` strategy. Additionally, set a budget to ensure a certain number of Pod replicas remain available during the update. ```yaml deployment: strategy: type: "RollingUpdate" updateStrategy: type: "RollingUpdate" budget: maxUnavailable: 1 ``` For all available settings, see the [Helm specification](../../../reference/k-connector-helm-spec/#deployment). #### [](#affinity-rules)Affinity rules Affinities control Pod placement in the cluster based on various conditions. Set these according to your high availability and infrastructure needs. ```yaml deployment: podAntiAffinity: topologyKey: kubernetes.io/hostname type: hard weight: 100 custom: requiredDuringSchedulingIgnoredDuringExecution: - labelSelector: matchExpressions: - key: "app" operator: "In" values: - "redpanda-connector" topologyKey: "kubernetes.io/hostname" preferredDuringSchedulingIgnoredDuringExecution: - weight: 100 podAffinityTerm: labelSelector: matchExpressions: - key: "app" operator: "In" values: - "redpanda-connector" topologyKey: "kubernetes.io/zone" ``` In this example: - The `requiredDuringSchedulingIgnoredDuringExecution` section ensures that the Kubernetes scheduler doesn’t place two Pods with the same `app: redpanda-connector` label on the same node due to the `topologyKey: kubernetes.io/hostname`. - The `preferredDuringSchedulingIgnoredDuringExecution` section is a soft rule that tries to ensure the Kubernetes scheduler doesn’t place two Pods with the same `app: redpanda-connector` label in the same zone. However, if it’s not possible, the scheduler can still place the Pods in the same zone. For all available settings, see the [Helm specification](../../../reference/k-connector-helm-spec/#deployment). #### [](#tolerations)Tolerations Tolerations and taints allow Pods to be scheduled onto nodes where they otherwise wouldn’t. If you have nodes dedicated to Kafka Connect with a taint `dedicated=redpanda-connectors:NoSchedule`, the following toleration allows the Pods to be scheduled on them. ```yaml tolerations: - key: "dedicated" operator: "Equal" value: "redpanda-connectors" effect: "NoSchedule" ``` For all available settings, see the [Helm specification](../../../reference/k-connector-helm-spec/#tolerations). #### [](#node-selection)Node selection Use node selectors to ensure connectors are scheduled on appropriate nodes and avoid scheduling on Redpanda broker nodes: ```yaml # Example: Schedule on nodes with specific labels nodeSelector: workload-type: "kafka-connect" # Or use node affinity for more complex selection deployment: nodeAffinity: requiredDuringSchedulingIgnoredDuringExecution: nodeSelectorTerms: - matchExpressions: - key: "kubernetes.io/hostname" operator: "NotIn" values: ["redpanda-node-1", "redpanda-node-2", "redpanda-node-3"] ``` For all available settings, see the [Helm specification](../../../reference/k-connector-helm-spec/#nodeselector). #### [](#graceful-shutdown)Graceful shutdown If your connectors require additional time for a graceful shutdown, modify the `terminationGracePeriodSeconds`. ```yaml deployment: terminationGracePeriodSeconds: 30 ``` For all available settings, see the [Helm specification](../../../reference/k-connector-helm-spec/#deployment). ### [](#monitoring-and-observability)Monitoring and observability This section covers monitoring, logging, and health check configuration. #### [](#monitoring)Monitoring If you have the [Prometheus Operator](https://prometheus-operator.dev/), enable monitoring to deploy a PodMonitor resource for Kafka Connect. ```yaml monitoring: enabled: true ``` For all available settings, see the [Helm specification](../../../reference/k-connector-helm-spec/#monitoring). See also: [Monitor Kafka Connect in Kubernetes](../../../manage/kubernetes/monitoring/k-monitor-connectors/) #### [](#logging)Logging Use the `info` logging level to avoid overwhelming the storage. For debugging purposes, temporarily change the logging level to `debug`. ```yaml logging: level: "info" ``` For all available settings, see the [Helm specification](../../../reference/k-connector-helm-spec/#logging). #### [](#probes)Probes Probes determine the health and readiness of your Pods. Configure them based on the startup behavior of your connectors. ```yaml deployment: livenessProbe: initialDelaySeconds: 60 periodSeconds: 10 readinessProbe: initialDelaySeconds: 30 periodSeconds: 10 ``` For all available settings, see the [Helm specification](../../../reference/k-connector-helm-spec/#deployment). ### [](#data-management)Data management This section covers configuration related to data handling and topic management. #### [](#topics)Topics Kafka Connect leverages internal topics to track processed data, enhancing its fault tolerance: - The offset topic logs the last processed position from the external data source. - In events like failures or restarts, the connector uses this logged position to resume operations, ensuring no data duplication or omission. ```yaml connectors: storage: topic: offset: _internal_connectors_offsets ``` Here, `_internal_connectors_offsets` is the dedicated Kafka topic where Kafka Connect persists the offsets of the source connector. For all available settings, see the [Helm specification](../../../reference/k-connector-helm-spec/#connectors). #### [](#producers)Producers When a source connector retrieves data from an external system for Redpanda, it assumes the role of a producer: - The source connector is responsible for transforming the external data into Kafka-compatible messages. - It then produces (writes) these messages to a specified Kafka topic. The `producerBatchSize` and `producerLingerMS` settings specify how Kafka Connect groups messages before producing them. ```yaml connectors: producerBatchSize: 131072 producerLingerMS: 1 ``` For all available settings, see the [Helm specification](../../../reference/k-connector-helm-spec/#connectors). ### [](#general-configuration)General configuration This section covers other important configuration settings. #### [](#name-overrides)Name overrides Deploying multiple instances of the same Helm chart in a Kubernetes cluster can lead to naming conflicts. Using `nameOverride` and `fullnameOverride` helps differentiate between them. If you have a production and staging environment, different names help to avoid confusion. - Use `nameOverride` to customize: - The default labels `app.kubernetes.io/component=` and `app.kubernetes.io/name=` - The suffix in the name of the resources `redpanda-` - Use `fullnameOverride` to customize the full name of the resources such as the Deployment and Services. ```yaml nameOverride: 'redpanda-connector-production' fullnameOverride: 'redpanda-connector-instance-prod' ``` For all available settings, see the [Helm specification](../../../reference/k-connector-helm-spec/#nameoverride). #### [](#labels)Labels Kubernetes labels help you to organize, query, and manage your resources. Use labels to categorize Kubernetes resources in different deployments by environment, purpose, or team. ```yaml commonLabels: env: 'production' ``` For all available settings, see the [Helm specification](../../../reference/k-connector-helm-spec/#commonlabels). #### [](#docker-image)Docker image You can specify the image tag to deploy a known version of the Docker image. Avoid using the `latest` tag, which can lead to unexpected changes. If you’re using a private repository, always ensure your nodes have the necessary credentials to pull the image. ```yaml image: repository: "redpandadata/connectors" tag: "1.2.3" ``` For all available settings, see the [Helm specification](../../../reference/k-connector-helm-spec/#image). #### [](#kafka-connect-configuration)Kafka Connect configuration You can configure Kafka Connect connection settings. Change the default REST API port only if it conflicts with an existing port. The `bootstrapServers` setting should point to the Kafka API endpoints on your Redpanda brokers. If you want to use Schema Registry, ensure the URL is set to the IP address or domain name of a Redpanda broker and that it includes the Schema Registry port. ```yaml connectors: restPort: 8082 bootstrapServers: "redpanda-broker-0:9092" schemaRegistryURL: "http://schema-registry.default.svc.cluster.local:8081" ``` For all available settings, see the [Helm specification](../../../reference/k-connector-helm-spec/#connectors). #### [](#deployment-history)Deployment history Keeping track of your deployment’s history is beneficial for rollback scenarios. Adjust the `revisionHistoryLimit` according to your storage considerations. ```yaml deployment: progressDeadlineSeconds: 600 revisionHistoryLimit: 10 ``` For all available settings, see the [Helm specification](../../../reference/k-connector-helm-spec/#deployment). ## [](#verify-the-deployment)Verify the deployment To verify that the deployment was successful, you can use the Kafka Connect REST API or check the deployment in Redpanda Console (if configured). ### [](#verify-with-the-kafka-connect-rest-api)Verify with the Kafka Connect REST API 1. Get the name of the Pod that’s running Kafka Connect: ```bash kubectl get pod -l app.kubernetes.io/name=connectors --namespace ``` Expected output should show pods in `Running` status: ```bash NAME READY STATUS RESTARTS AGE redpanda-connectors-6d64b948f6-dk484 1/1 Running 0 5m ``` 2. Check if the Kafka Connect service is accessible: ```bash kubectl get svc -l app.kubernetes.io/name=connectors --namespace ``` Expected output: ```bash NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE redpanda-connectors ClusterIP 10.96.123.45 8083/TCP 5m ``` 3. View the version of Kafka Connect: ```bash kubectl exec --namespace -- curl localhost:8083 | jq ``` Example output ```json { "version": "3.8.0", "commit": "771b9576b00ecf5b", "kafka_cluster_id": "redpanda.3e2649b0-f84c-4c03-b5e3-d6d1643f65b2" } ``` 4. View the list of available connectors: ```bash kubectl exec --namespace -- curl localhost:8083/connector-plugins | jq ``` Example output ```json [ { "class": "org.apache.kafka.connect.mirror.MirrorCheckpointConnector", "type": "source", "version": "3.8.0" }, { "class": "org.apache.kafka.connect.mirror.MirrorHeartbeatConnector", "type": "source", "version": "3.8.0" }, { "class": "org.apache.kafka.connect.mirror.MirrorSourceConnector", "type": "source", "version": "3.8.0" } ] ``` 5. Test connectivity to your Redpanda cluster: ```bash kubectl exec --namespace -- curl localhost:8083/connectors ``` This should return an empty array `[]` if no connectors are configured, indicating that Kafka Connect can communicate with your Redpanda cluster. ### [](#troubleshoot-common-issues)Troubleshoot common issues If the deployment isn’t working as expected, check these common issues: #### [](#pod-not-starting-or-crashing)Pod not starting or crashing 1. Check pod logs for error messages: ```bash kubectl logs -l app.kubernetes.io/name=connectors --namespace --tail=50 ``` 2. Check for resource constraints: ```bash kubectl describe pod -l app.kubernetes.io/name=connectors --namespace ``` Common issues and solutions: - **"You must set either bootstrap.servers or bootstrap.controllers"**: The `connectors.bootstrapServers` configuration is missing or incorrectly formatted. - **OutOfMemoryError**: Increase memory limits or reduce `javaMaxHeapSize`. - **Connection refused to Redpanda brokers**: Verify the bootstrap servers addresses and ensure Redpanda is running. #### [](#testing-network-connectivity)Testing network connectivity 1. Test if the connector can reach Redpanda brokers: ```bash kubectl exec --namespace -- nslookup ``` 2. Test port connectivity: ```bash kubectl exec --namespace -- nc -zv 9093 ``` #### [](#verify-with-redpanda-console)Verify with Redpanda Console If you have Redpanda Console configured to connect to Kafka Connect: 1. Access Redpanda Console through port-forward: ```bash kubectl port-forward svc/redpanda-console 8080:8080 --namespace ``` 2. Open [http://localhost:8080](http://localhost:8080) in your browser 3. Navigate to **Connect** If the Connectors page shows "No clusters configured" or connection errors, verify your Redpanda Console configuration includes the correct Kafka Connect service URL. ### [](#health-checks-and-monitoring)Health checks and monitoring The connectors chart includes built-in health checks that you can use to monitor the status: 1. **Liveness probe**: Checks if Kafka Connect is responsive ```bash kubectl exec --namespace -- curl -f localhost:8083/ ``` 2. **Readiness probe**: Checks if Kafka Connect is ready to accept requests ```bash kubectl exec --namespace -- curl -f localhost:8083/connectors ``` 3. **View connector worker information**: ```bash kubectl exec --namespace -- curl localhost:8083/admin/workers | jq ``` 4. **Check cluster information**: ```bash kubectl exec --namespace -- curl localhost:8083/admin/cluster | jq ``` These endpoints help you verify that Kafka Connect is not only running but also properly connected to your Redpanda cluster and ready to manage connectors. ## [](#install-a-new-connector)Install a new connector To install new connectors other than the ones included in the Redpanda Connectors Docker image, you must: 1. Prepare a JAR (Java archive) file for the connector. 2. Mount the JAR file into the plugin directory of the Redpanda Connectors Docker image. 3. Use that Docker image in the Helm chart. ### [](#prepare-a-jar-file)Prepare a JAR file Kafka Connect is written in Java. As such, connectors are also written in Java and packaged into JAR files. JAR files are used to distribute Java classes and associated metadata and resources in a single file. You can get JAR files for connectors in many ways, including: - **Build from source**: If you have the source code for a Java project, you can compile and package it into a JAR using build tools, such as: - Maven: Using the `mvn package` command. - Gradle: Using the `gradle jar` or `gradle build` command. - Java Development Kit (JDK): Using the `jar` command-line tool that comes with the JDK. - **Maven Central Repository**: If you’re looking for a specific Java library or framework, it may be available in the Maven Central Repository. From here, you can search for the library and download the JAR directly. - **Vendor websites**: If you are looking for commercial Java software or libraries, the vendor’s official website is a good place to check. > ⚠️ **CAUTION** > > To avoid security risks, always verify the source of the JAR files. Do not download JAR files from unknown websites. Malicious JAR files can present a security risk to your execution environment. ### [](#add-the-connector-to-the-docker-image)Add the connector to the Docker image The Redpanda Connectors Docker image is configured to find connectors in the `/opt/kafka/redpanda-plugins` directory. You must mount your connector’s JAR file to this directory in the Docker image. 1. Create a new Dockerfile: `Dockerfile` ```dockerfile FROM redpandadata/connectors: COPY /opt/kafka/connect-plugins// ``` Replace the following placeholders: - ``: The version of the Redpanda Connectors Docker image that you want to use. For all available versions, see [DockerHub](https://hub.docker.com/r/redpandadata/connectors/tags). - ``: The path to the JAR file on your local system. - ``: A unique directory name in which to mount your JAR files. - ``: The name of your JAR file, including the `.jar` file extension. 2. Change into the directory where you created the Dockerfile and run: ```bash docker build -t /connectors: . ``` - Replace `` with the name of your Docker repository and `` with your desired version or tag for the image. 3. Push the image to your Docker repository: ```bash docker push /connectors: ``` ### [](#deploy-the-helm-chart-with-your-custom-docker-image)Deploy the Helm chart with your custom Docker image 1. Modify your values file to use your new Docker image: ```yaml image: repository: /connectors tag: pullPolicy: IfNotPresent ``` Kafka Connect should discover the new connector automatically on startup. 2. Update your deployment: ```bash helm upgrade redpanda-connectors redpanda/connectors \ --namespace \ --values connectors-values.yaml ``` 3. Get the name of the Pod that’s running Kafka Connect: ```bash kubectl get pod -l app.kubernetes.io/name=connectors --namespace ``` 4. View all available connectors: ```bash kubectl exec --namespace -- curl localhost:8083/connector-plugins | jq ``` You should see your new connector in the list. ## [](#next-steps)Next steps - [Create and Manage Kafka Connect Connectors in Kubernetes](../../../manage/kubernetes/k-manage-connectors/) - [Monitor Kafka Connect in Kubernetes](../../../manage/kubernetes/monitoring/k-monitor-connectors/) ## Suggested labs - [Disaster Recovery with Envoy and Shadowing](/redpanda-labs/docker-compose/envoy-shadowing/) - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Stream Jira Issues to Redpanda for Real-Time Metrics](/redpanda-labs/docker-compose/jira-metrics-pipeline/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Set Up GitOps for the Redpanda Helm Chart](/redpanda-labs/kubernetes/gitops-helm/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) - [Set Up MySQL CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-mysql-json/) - [Set Up Postgres CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-postgres-json/) See more [Search all labs](/redpanda-labs) --- # Page 33: Deploy Redpanda **URL**: https://docs.redpanda.com/current/deploy/redpanda.md --- # Deploy Redpanda --- title: Deploy Redpanda latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: redpanda/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: redpanda/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/redpanda/index.adoc description: Overview of Redpanda deployment options and links to platform-specific guides. page-git-created-date: "2025-08-15" page-git-modified-date: "2025-08-15" support-status: supported --- Redpanda can be deployed on a variety of platforms to suit your infrastructure and operational needs. This section provides an overview of the available deployment methods and links to detailed, platform-specific instructions. - [Deploy on Kubernetes](kubernetes/) Learn about deployment options on Kubernetes. - [Deploy on Linux](manual/) Learn about deployment options on Linux, as well as considerations for high availability and sizing. --- # Page 34: Deploy on Kubernetes **URL**: https://docs.redpanda.com/current/deploy/redpanda/kubernetes.md --- # Deploy on Kubernetes --- title: Deploy on Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: redpanda/kubernetes/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: redpanda/kubernetes/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/redpanda/kubernetes/index.adoc description: Learn about deployment options on Kubernetes. page-git-created-date: "2025-08-15" page-git-modified-date: "2025-08-15" support-status: supported --- Kubernetes provides a standardized way of achieving high availability, disaster recovery, and scalability. - [Redpanda in Kubernetes](k-deployment-overview/) Learn about Redpanda in Kubernetes and the tools that are available. - [Get Started with Redpanda in Kubernetes](get-started-dev/) Find guides for setting up a three-broker Redpanda cluster in different Kubernetes platforms. - [Production Deployment Workflow for Kubernetes](k-production-workflow/) Learn how to deploy Redpanda in Kubernetes for production. - [Kubernetes Cluster Requirements and Recommendations](k-requirements/) A list of requirements and recommendations for provisioning Kubernetes clusters and worker nodes for running Redpanda in production. - [Tune Kubernetes Worker Nodes for Production](k-tune-workers/) To get the best performance from your hardware, set Redpanda to production mode and run the autotuner tool. The autotuner identifies your hardware configuration and tunes itself to give you the best performance. - [Deploy Redpanda for Production in Kubernetes](k-production-deployment/) Deploy a Redpanda cluster in Kubernetes. - [Production Readiness Checklist](k-production-readiness/) Comprehensive checklist for validating Redpanda deployments in Kubernetes against production readiness standards. - [High Availability in Kubernetes](k-high-availability/) Explore high availability configurations of Redpanda in Kubernetes. --- # Page 35: Deploy a Redpanda Cluster in Azure Kubernetes Service **URL**: https://docs.redpanda.com/current/deploy/redpanda/kubernetes/aks-guide.md --- # Deploy a Redpanda Cluster in Azure Kubernetes Service --- title: Deploy a Redpanda Cluster in Azure Kubernetes Service latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: redpanda/kubernetes/aks-guide page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: redpanda/kubernetes/aks-guide.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/redpanda/kubernetes/aks-guide.adoc description: Deploy a secure Redpanda cluster and Redpanda Console in Azure Kubernetes Service (AKS). page-git-created-date: "2025-08-15" page-git-modified-date: "2025-08-15" support-status: supported --- Deploy a secure Redpanda cluster and Redpanda Console in Azure Kubernetes Service (AKS). After you deploy, use `rpk` both as an internal client and an external client to interact with your Redpanda cluster from the command line. Your Redpanda cluster has the following security features: - SASL for authenticating users' connections. - TLS with self-signed certificates for secure communication between the cluster and clients. ## [](#prerequisites)Prerequisites - Satisfy the prerequisites listed in the [AKS quickstart](https://learn.microsoft.com/en-us/azure/aks/learn/quick-kubernetes-deploy-cli#prerequisites) to get access to the Azure CLI. - Install [`kubectl`](https://kubernetes.io/docs/tasks/tools/). Minimum required Kubernetes version: 1.27.0-0. ```bash kubectl version --client ``` - Install [Helm](https://helm.sh/docs/intro/install/). Minimum required Helm version: 3.10.0 ```bash helm version ``` ## [](#create-an-aks-cluster)Create an AKS cluster Your AKS cluster must have one worker node available for each Redpanda broker that you plan to deploy in your Redpanda cluster. You also need to run the worker nodes on a machine type that supports the [requirements and recommendations](../k-requirements/) for production deployments. In this step, you create an AKS cluster with three nodes on [Standard\_L8s\_v3 Azure Virtual Machines (Azure VMs)](https://learn.microsoft.com/en-us/azure/virtual-machines/lsv3-series). Deploying three nodes allows your AKS cluster to support a Redpanda cluster with three brokers. The Standard\_L8s\_v3 Azure VMs come with: - 2 cores per worker node, which is a requirement for production. - Local NVMe disks, which is recommended for best performance. 1. Create a resource group for Redpanda: ```bash az group create --name redpandaResourceGroup --location eastus ``` 2. Create an AKS cluster: ```bash az aks create -g redpandaResourceGroup -n \ --node-count 3 \ --generate-ssh-keys \ --enable-node-public-ip \ --node-vm-size Standard_L8s_v3 \ --disable-file-driver \ --node-os-upgrade-channel Unmanaged (1) ``` | 1 | Set the OS upgrade channel to Unmanaged to prevent AKS from automatically rebooting or upgrading nodes.For more details, see the requirements and recommendations for deploying Redpanda in Kubernetes. | | --- | --- | For all available options, see the [AKS documentation](https://learn.microsoft.com/en-us/cli/azure/aks?view=azure-cli-latest#az-aks-create). ### [](#create-sc)Create a StorageClass for your local NVMe disks When you provisioned the Kubernetes cluster, you selected an instance type that comes with local NVMe disks. However, these disks are not automatically mounted or formatted upon creation. To use these local NVMe disks, you must mount and format them, and you must create the necessary PersistentVolumes (PVs). To automate this process, you can use a Container Storage Interface (CSI) driver. In this step, you install the recommended [local volume manager (LVM) CSI driver](https://github.com/metal-stack/csi-driver-lvm). Then, you create a StorageClass that references the LVM CSI driver and specifies the recommended XFS file system. 1. Install the LVM CSI driver: ```yaml helm repo add metal-stack https://helm.metal-stack.io helm repo update helm install csi-driver-lvm metal-stack/csi-driver-lvm \ --version 0.6.0 \ --namespace csi-driver-lvm \ --create-namespace \ --set lvm.devicePattern='/dev/nvme[0-9]n[0-9]' ``` The `lvm.devicePattern` property specifies the pattern that the CSI driver uses to identify available NVMe volumes on your worker nodes. > 📝 **NOTE** > > Version 0.6.0 is required to avoid volume-mounting issues caused by recent `mkfs.xfs` updates. Newer versions enable the `-i nrext64=1` option, triggering the following error on default AKS kernels: > > XFS (dm-0): Superblock has unknown incompatible features (0x20) enabled. 2. Create the StorageClass: `csi-driver-lvm-striped-xfs.yaml` ```yaml apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: csi-driver-lvm-striped-xfs provisioner: lvm.csi.metal-stack.io reclaimPolicy: Retain volumeBindingMode: WaitForFirstConsumer allowVolumeExpansion: true parameters: type: "striped" csi.storage.k8s.io/fstype: xfs mkfsParams: "-i nrext64=0" ``` - `provisioner`: The LVM CSI driver responsible for provisioning the volume. - `reclaimPolicy`: The `Retain` policy ensures that the underlying volume is not deleted when the corresponding PVC is deleted. - `volumeBindingMode`: The `WaitForFirstConsumer` mode delays the binding and provisioning of a PersistentVolume until a Pod that uses the PVC is created. This mode is important for ensuring that the PV is created on the same node where the Pod will run because the PV will use the node’s local NVMe volumes. - `allowVolumeExpansion`: Allows the volume to be expanded after it has been provisioned. - `parameters.type`: Combines multiple physical volumes to create a single logical volume. In a striped setup, data is spread across the physical volumes in a way that distributes the I/O load evenly, improving performance by allowing parallel disk I/O operations. - `parameters.csi.storage.k8s.io/fstype`: Formats the volumes with the XFS file system. Redpanda Data recommends XFS for its enhanced performance with Redpanda workloads. - `parameters.mkfsParams`: Disables the nrext64 feature to ensure compatibility with older kernels. 3. Apply the StorageClass: ```bash kubectl apply -f csi-driver-lvm-striped-xfs.yaml ``` After applying this StorageClass, any PVC that references it will attempt to provision storage using the LVM CSI driver and the provided parameters. ### [](#configure-external-access)Configure external access In this step, you configure your AKS cluster to allow external access to the node ports on which the Redpanda deployment will be exposed. You use these node ports in later steps to configure external access to your Redpanda cluster. 1. Get your subscription ID: ```bash export SUBSCRIPTION_ID=$(az account show --query id --output tsv) ``` 2. Set up a connection to your AKS cluster: ```bash az account set --subscription $SUBSCRIPTION_ID az aks get-credentials --resource-group redpandaResourceGroup --name ``` 3. Open the [Azure Portal](https://portal.azure.com/), search for 'Network security groups', and click the name of the network security group in the **MC\_redpandaResourceGroup\_redpanda\_eastus** resource group. 4. Add an inbound security rule with the following values: - **Destination port ranges**: 31644,31092,30082,30081 - **Name** AllowRedpandaNodePorts ## [](#deploy-redpanda-and-redpanda-console)Deploy Redpanda and Redpanda Console In this step, you deploy Redpanda with SASL authentication and self-signed TLS certificates. Redpanda Console is included as a subchart in the Redpanda Helm chart. ### Operator 1. Make sure that you have permission to install custom resource definitions (CRDs): ```bash kubectl auth can-i create CustomResourceDefinition --all-namespaces ``` You should see `yes` in the output. You need these cluster-level permissions to install [cert-manager](https://cert-manager.io/docs/) and Redpanda Operator CRDs in the next steps. 2. Install [cert-manager](https://cert-manager.io/docs/installation/helm/) using Helm: ```bash helm repo add jetstack https://charts.jetstack.io helm repo update helm install cert-manager jetstack/cert-manager \ --set crds.enabled=true \ --namespace cert-manager \ --create-namespace ``` The Redpanda Helm chart uses cert-manager to enable TLS and manage TLS certificates by default. 3. Deploy the Redpanda Operator: 1. To deploy in cluster scope, use: ```bash helm repo add redpanda https://charts.redpanda.com helm repo update helm upgrade --install redpanda-controller redpanda/operator \ --namespace \ --create-namespace \ --version v26.1.2 \ (1) --set crds.enabled=true (2) ``` | 1 | This flag specifies the exact version of the Redpanda Operator Helm chart to use for deployment. By setting this value, you pin the chart to a specific version, which prevents automatic updates that might introduce breaking changes or new features that have not been tested in your environment. | | --- | --- | | 2 | This flag ensures that the CRDs are installed as part of the Redpanda Operator deployment.This command deploys the Redpanda Operator in cluster scope (default in v25.2+), allowing it to manage Redpanda clusters across multiple namespaces. | 2. To deploy in namespace scope (managing only resources within its deployment namespace), use: ```bash helm upgrade --install redpanda-controller redpanda/operator \ --namespace \ --create-namespace \ --version v26.1.2 \ --set crds.enabled=true \ --set 'additionalCmdFlags=["--namespace="]' (1) ``` | 1 | This flag restricts the Redpanda Operator to manage resources only within the specified namespace. | | --- | --- | 4. Ensure that the Deployment is successfully rolled out: ```bash kubectl --namespace rollout status --watch deployment/redpanda-controller-operator ``` deployment "redpanda-controller-operator" successfully rolled out 5. Install a [Redpanda custom resource](../../../../reference/k-crd/) in the same namespace as the Redpanda Operator: `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: clusterSpec: image: tag: v26.1.3 external: domain: customredpandadomain.local auth: sasl: enabled: true users: - name: superuser password: secretpassword storage: persistentVolume: enabled: true storageClass: csi-driver-lvm-striped-xfs ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` - `image.tag`: Deploys the latest version of Redpanda. - `external.domain`: The custom domain that each broker will advertise to clients externally. This domain is added to the internal and external TLS certificates so that you can connect to the cluster using this domain. - `auth.sasl.name`: Creates a superuser called `superuser` that can grant permissions to new users in your cluster using access control lists (ACLs). - `storage.persistentVolume.storageClass`: Points each PVC associated with the Redpanda brokers to the `csi-driver-lvm-striped-xfs` StorageClass. This StorageClass allows the LVM CSI driver to provision the appropriate local PersistentVolumes backed by NVMe disks for each Redpanda broker. 6. Wait for the Redpanda Operator to deploy Redpanda using the Helm chart: ```bash kubectl get redpanda --namespace --watch ``` NAME READY STATUS redpanda True Redpanda reconciliation succeeded This step may take a few minutes. You can watch for new Pods to make sure that the deployment is progressing: ```bash kubectl get pod --namespace ``` If it’s taking too long, see [Troubleshoot](#troubleshoot). ### Helm 1. Install cert-manager using Helm: ```bash helm repo add jetstack https://charts.jetstack.io helm repo update helm install cert-manager jetstack/cert-manager \ --set crds.enabled=true \ --namespace cert-manager \ --create-namespace ``` TLS is enabled by default. The Redpanda Helm chart uses cert-manager to manage TLS certificates by default. 2. Install Redpanda with SASL enabled: ```bash helm repo add redpanda https://charts.redpanda.com helm repo update helm install redpanda redpanda/redpanda \ --version 26.1.2 \ --namespace --create-namespace \ --set image.tag=v26.1.3 \ --set auth.sasl.enabled=true \ --set "auth.sasl.users[0].name=superuser" \ --set "auth.sasl.users[0].password=secretpassword" \ --set external.domain=customredpandadomain.local \ --set "storage.persistentVolume.storageClass=csi-driver-lvm-striped-xfs" \ --wait \ --timeout 1h ``` - `image.tag`: Deploys the latest version of Redpanda. - `external.domain`: The custom domain that each broker advertises to clients externally. This domain is added to the internal and external TLS certificates so that you can connect to the cluster using this domain. - `auth.sasl.name`: Creates a superuser called `superuser` that can grant permissions to new users in your cluster using access control lists (ACLs). - `storage.persistentVolume.storageClass`: Points each PVC associated with the Redpanda brokers to the `csi-driver-lvm-striped-xfs` StorageClass. This StorageClass allows the LVM CSI driver to provision the appropriate local PersistentVolumes backed by NVMe disks for each Redpanda broker. The installation displays some tips for getting started. If the installation is taking a long time, see [Troubleshoot](#troubleshoot). ## [](#verify-the-deployment)Verify the deployment When the Redpanda Helm chart is deployed, you should have: - Three Redpanda brokers. Each Redpanda broker runs inside a separate Pod and is scheduled on a separate worker node. - One PVC bound to a PV for each Redpanda broker. These PVs are what the Redpanda brokers use to store the Redpanda data directory with all your topics and metadata. 1. Verify that each Redpanda broker is scheduled on only one Kubernetes node: ```bash kubectl get pod --namespace \ -o=custom-columns=NODE:.spec.nodeName,POD_NAME:.metadata.name -l \ app.kubernetes.io/component=redpanda-statefulset ``` Example output: NODE POD\_NAME example-worker3 redpanda-0 example-worker2 redpanda-1 example-worker redpanda-2 2. Verify that each Redpanda broker has a bound PVC: ```bash kubectl get persistentvolumeclaim \ --namespace \ -o custom-columns=NAME:.metadata.name,STATUS:.status.phase,STORAGECLASS:.spec.storageClassName ``` Example output: NAME STATUS STORAGECLASS datadir-redpanda-0 Bound csi-driver-lvm-striped-xfs datadir-redpanda-1 Bound csi-driver-lvm-striped-xfs datadir-redpanda-2 Bound csi-driver-lvm-striped-xfs ## [](#create-a-user)Create a user In this step, you use `rpk` to create a new user. Then, you authenticate to Redpanda with the superuser to grant permissions to the new user. You’ll authenticate to Redpanda with this new user to create a topic in the next steps. > 💡 **TIP** > > As a security best practice, you should use the superuser only to grant permissions to new users through ACLs. Never delete the superuser. You need the superuser to grant permissions to new users. 1. Create a new user called `redpanda-twitch-account` with the password `changethispassword`: ```bash kubectl --namespace exec -ti redpanda-0 -c redpanda -- \ rpk security user create redpanda-twitch-account \ -p changethispassword ``` Example output: Created user "redpanda-twitch-account". 2. Use the superuser to grant the `redpanda-twitch-account` user permission to execute all operations only for a topic called `twitch-chat`. ```bash kubectl exec --namespace -c redpanda redpanda-0 -- \ rpk security acl create --allow-principal User:redpanda-twitch-account \ --operation all \ --topic twitch-chat \ -X user=superuser -X pass=secretpassword -X sasl.mechanism=SCRAM-SHA-512 ``` Example output: PRINCIPAL RESOURCE-TYPE RESOURCE-NAME OPERATION PERMISSION User:redpanda TOPIC twitch-chat ALL ALLOW ## [](#start-streaming)Start streaming In this step, you authenticate to Redpanda with the `redpanda-twitch-account` user to create a topic called `twitch-chat`. This topic is the only one that the `redpanda-twitch-account` user has permission to access. Then, you produce messages to the topic, and consume messages from it. 1. Create an alias to simplify the `rpk` commands: ```bash alias internal-rpk="kubectl --namespace exec -i -t redpanda-0 -c redpanda -- rpk -X user=redpanda-twitch-account -X pass=changethispassword -X sasl.mechanism=SCRAM-SHA-256" ``` 2. Create a topic called `twitch-chat`: ### Operator 1. Create a Secret in which to store your user’s password: ```bash kubectl create secret generic redpanda-secret --from-literal=password='changethispassword' --namespace ``` 2. Create a [Topic resource](../../../../manage/kubernetes/k-manage-topics/): `topic.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Topic metadata: name: twitch-chat spec: kafkaApiSpec: brokers: - "redpanda-0.redpanda..svc.cluster.local:9093" - "redpanda-1.redpanda..svc.cluster.local:9093" - "redpanda-2.redpanda..svc.cluster.local:9093" tls: caCertSecretRef: name: "redpanda-default-cert" key: "ca.crt" sasl: username: redpanda-twitch-account mechanism: SCRAM-SHA-256 passwordSecretRef: name: redpanda-secret key: password ``` 3. Apply the Topic resource in the same namespace as your Redpanda cluster: ```bash kubectl apply -f topic.yaml --namespace ``` 4. Check the logs of the Redpanda Operator to confirm that the topic was created: ```bash kubectl logs -l app.kubernetes.io/name=operator -c manager --namespace ``` You should see that the Redpanda Operator reconciled the Topic resource. For example: Example output ```json { "level":"info", "ts":"2023-09-25T16:20:09.538Z", "logger":"TopicReconciler.Reconcile", "msg":"Starting reconcile loop", "controller":"topic", "controllerGroup":"cluster.redpanda.com", "controllerKind":"Topic", "Topic": { "name":"twitch-chat", "namespace":"" }, "namespace":"", "name":"twitch-chat", "reconcileID":"c0cf9abc-a553-48b7-9b6e-2de3cdfb4432" } { "level":"info", "ts":"2023-09-25T16:20:09.581Z", "logger":"TopicReconciler.Reconcile", "msg":"reconciliation finished in 43.436125ms, next run in 3s", "controller":"topic", "controllerGroup":"cluster.redpanda.com", "controllerKind":"Topic", "Topic": { "name":"twitch-chat", "namespace":"" }, "namespace":"", "name":"twitch-chat", "reconcileID":"c0cf9abc-a553-48b7-9b6e-2de3cdfb4432", "result": { "Requeue":false, "RequeueAfter":3000000000 } } ``` ### Helm ```bash internal-rpk topic create twitch-chat ``` Example output: TOPIC STATUS twitch-chat OK 3. Describe the topic: ```bash internal-rpk topic describe twitch-chat ``` Expected output: ```none SUMMARY ======= NAME twitch-chat PARTITIONS 1 REPLICAS 1 CONFIGS ======= KEY VALUE SOURCE cleanup.policy delete DYNAMIC_TOPIC_CONFIG compression.type producer DEFAULT_CONFIG message.timestamp.type CreateTime DEFAULT_CONFIG partition_count 1 DYNAMIC_TOPIC_CONFIG redpanda.datapolicy function_name: script_name: DEFAULT_CONFIG redpanda.remote.read false DEFAULT_CONFIG redpanda.remote.write false DEFAULT_CONFIG replication_factor 1 DYNAMIC_TOPIC_CONFIG retention.bytes -1 DEFAULT_CONFIG retention.ms 604800000 DEFAULT_CONFIG segment.bytes 1073741824 DEFAULT_CONFIG ``` 4. Produce a message to the topic: ```bash internal-rpk topic produce twitch-chat ``` 5. Type a message, then press Enter: Pandas are fabulous! Example output: Produced to partition 0 at offset 0 with timestamp 1663282629789. 6. Press Ctrl+C to finish producing messages to the topic. 7. Consume one message from the topic: ```bash internal-rpk topic consume twitch-chat --num 1 ``` Expected output: ```none { "topic": "twitch-chat", "value": "Pandas are fabulous!", "timestamp": 1663282629789, "partition": 0, "offset": 0 } ``` ## [](#explore-your-topic-in-redpanda-console)Explore your topic in Redpanda Console Redpanda Console is a developer-friendly web UI for managing and debugging your Redpanda cluster and your applications. In this step, you use port-forwarding to access Redpanda Console on your local network. > 💡 **TIP** > > Because you’re using the Community Edition of Redpanda Console, you should not expose Redpanda Console outside your local network. The Community Edition of Redpanda Console does not provide authentication, and it connects to the Redpanda cluster as superuser. To use the Enterprise Edition, you need a license key. See [Redpanda Licensing](../../../../get-started/licensing/). 1. Expose Redpanda Console to your localhost: ```bash kubectl --namespace port-forward svc/redpanda-console 8080:8080 ``` The `kubectl port-forward` command actively runs in the command-line window. To execute other commands while the command is running, open another command-line window. 2. Open Redpanda Console on [http://localhost:8080](http://localhost:8080). All your Redpanda brokers are listed along with their IP addresses and IDs. 3. Go to **Topics** > **twitch-chat**. The message that you produced to the topic is displayed along with some other details about the topic. 4. Press Ctrl+C in the command-line to stop the port-forwarding process. ## [](#configure-external-access-to-redpanda)Configure external access to Redpanda If you want to connect to the Redpanda cluster with external clients, Redpanda brokers must advertise an externally accessible address that external clients can connect to. External clients are common in Internet of Things (IoT) environments, or if you use external services that do not implement VPC peering in your network. When you created the cluster, you set the `external.domain` configuration to `customredpandadomain.local`, which means that your Redpanda brokers are advertising the following addresses: - `redpanda-0.customredpandadomain.local` - `redpanda-1.customredpandadomain.local` - `redpanda-2.customredpandadomain.local` To access your Redpanda brokers externally, you can map your worker nodes' IP addresses to these domains. > ⚠️ **CAUTION** > > IP addresses can change. If the IP addresses of your worker nodes change, you must update your `/etc/hosts` file with the new mappings. > > In a production environment, it’s a best practice to use ExternalDNS to manage DNS records for your brokers. See [Use ExternalDNS for external access](../k-requirements/#use-externaldns-for-external-access). 1. Add mappings in your `/etc/hosts` file between your worker nodes' IP addresses and their custom domain names: ```bash sudo true && kubectl --namespace get endpoints,node -A -o go-template='{{ range $_ := .items }}{{ if and (eq .kind "Endpoints") (eq .metadata.name "redpanda-external") }}{{ range $_ := (index .subsets 0).addresses }}{{ $nodeName := .nodeName }}{{ $podName := .targetRef.name }}{{ range $node := $.items }}{{ if and (eq .kind "Node") (eq .metadata.name $nodeName) }}{{ range $_ := .status.addresses }}{{ if eq .type "ExternalIP" }}{{ .address }} {{ $podName }}.customredpandadomain.local{{ "\n" }}{{ end }}{{ end }}{{ end }}{{ end }}{{ end }}{{ end }}{{ end }}' | envsubst | sudo tee -a /etc/hosts ``` `/etc/hosts` 203.0.113.3 redpanda-0.customredpandadomain.local 203.0.113.5 redpanda-1.customredpandadomain.local 203.0.113.7 redpanda-2.customredpandadomain.local 2. Save the root certificate authority (CA) to your local file system outside Kubernetes: ```bash kubectl --namespace get secret redpanda-external-root-certificate -o go-template='{{ index .data "ca.crt" | base64decode }}' > ca.crt ``` 3. Install `rpk` on your local machine, not on a Pod: ### Linux > 💡 **TIP** > > You can use `rpk` on Windows only with [WSL](https://learn.microsoft.com/windows/wsl/install). However, commands that require Redpanda to be installed on your machine are not supported, such as [`rpk container`](../../../../reference/rpk/rpk-container/rpk-container/) commands, [`rpk iotune`](../../../../reference/rpk/rpk-iotune/), and [`rpk redpanda`](../../../../reference/rpk/rpk-redpanda/rpk-redpanda/) commands. #### amd64 ```bash curl -LO https://github.com/redpanda-data/redpanda/releases/latest/download/rpk-linux-amd64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-linux-amd64.zip -d ~/.local/bin/ ``` #### arm64 ```bash curl -LO https://github.com/redpanda-data/redpanda/releases/latest/download/rpk-linux-arm64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-linux-arm64.zip -d ~/.local/bin/ ``` ### macOS 1. If you don’t have Homebrew installed, [install it](https://brew.sh/). 2. To install or update `rpk`, run: ```bash brew install redpanda-data/tap/redpanda ``` 4. Configure `rpk` to connect to your cluster using the [pre-configured profile](../../../../manage/kubernetes/networking/k-connect-to-redpanda/#rpk-profile): ```bash rpk profile create --from-profile <(kubectl get configmap --namespace redpanda-rpk -o go-template='{{ .data.profile }}') ``` Replace `` with the name that you want to give this `rpk` profile. 5. Test the connection: ```bash rpk cluster info -X user=redpanda-twitch-account -X pass=changethispassword -X sasl.mechanism=SCRAM-SHA-256 ``` ## [](#explore-the-default-kubernetes-components)Explore the default Kubernetes components By default, the Redpanda Helm chart deploys the following Kubernetes components: - [A StatefulSet](#statefulset) with three Pods. - [One PersistentVolumeClaim](#persistentvolumeclaim) for each Pod, each with a capacity of 20Gi. - [A headless ClusterIP Service and a NodePort Service](#service) for each Kubernetes node that runs a Redpanda broker. - [Self-Signed TLS Certificates](#tls-certificates). ### [](#statefulset)StatefulSet Redpanda is a stateful application. Each Redpanda broker needs to store its own state (topic partitions) in its own storage volume. As a result, the Helm chart deploys a StatefulSet to manage the Pods in which the Redpanda brokers are running. ```bash kubectl get statefulset --namespace ``` Example output: NAME READY AGE redpanda 3/3 3m11s StatefulSets ensure that the state associated with a particular Pod replica is always the same, no matter how often the Pod is recreated. Each Pod is also given a unique ordinal number in its name such as `redpanda-0`. A Pod with a particular ordinal number is always associated with a PersistentVolumeClaim with the same number. When a Pod in the StatefulSet is deleted and recreated, it is given the same ordinal number and so it mounts the same storage volume as the deleted Pod that it replaced. ```bash kubectl get pod --namespace ``` Expected output: ```none NAME READY STATUS RESTARTS AGE redpanda-0 1/1 Running 0 6m9s redpanda-1 1/1 Running 0 6m9s redpanda-2 1/1 Running 0 6m9s redpanda-console-5ff45cdb9b-6z2vs 1/1 Running 0 5m redpanda-configuration-smqv7 0/1 Completed 0 6m9s ``` > 📝 **NOTE** > > The `redpanda-configuration` job updates the Redpanda runtime configuration. ### [](#persistentvolumeclaim)PersistentVolumeClaim Redpanda brokers must be able to store their data on disk. By default, the Helm chart uses the default StorageClass in the Kubernetes cluster to create a PersistentVolumeClaim for each Pod. The default StorageClass in your Kubernetes cluster depends on the Kubernetes platform that you are using. ```bash kubectl get persistentvolumeclaims --namespace ``` Expected output: ```none NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE datadir-redpanda-0 Bound pvc-3311ade3-de84-4027-80c6-3d8347302962 20Gi RWO standard 75s datadir-redpanda-1 Bound pvc-4ea8bc03-89a6-41e4-b985-99f074995f08 20Gi RWO standard 75s datadir-redpanda-2 Bound pvc-45c3555f-43bc-48c2-b209-c284c8091c45 20Gi RWO standard 75s ``` ### [](#service)Service The clients writing to or reading from a given partition have to connect directly to the leader broker that hosts the partition. As a result, clients need to be able to connect directly to each Pod. To allow internal and external clients to connect to each Pod that hosts a Redpanda broker, the Helm chart configures two Services: - Internal using the [Headless ClusterIP](#headless-clusterip-service) - External using the [NodePort](#nodeport-service) ```bash kubectl get service --namespace ``` Expected output: ```none NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE redpanda ClusterIP None 5m37s redpanda-console ClusterIP 10.0.251.204 8080 5m redpanda-external NodePort 10.96.137.220 9644:31644/TCP,9094:31092/TCP,8083:30082/TCP,8080:30081/TCP 5m37s ``` #### [](#headless-clusterip-service)Headless ClusterIP Service The headless Service associated with a StatefulSet gives the Pods their network identity in the form of a fully qualified domain name (FQDN). Both Redpanda brokers in the same Redpanda cluster and clients within the same Kubernetes cluster use this FQDN to communicate with each other. An important requirement of distributed applications such as Redpanda is peer discovery: The ability for each broker to find other brokers in the same cluster. When each Pod is rolled out, its `seed_servers` field is updated with the FQDN of each Pod in the cluster so that they can discover each other. ```bash kubectl --namespace exec redpanda-0 -c redpanda -- cat etc/redpanda/redpanda.yaml ``` ```yaml redpanda: data_directory: /var/lib/redpanda/data empty_seed_starts_cluster: false seed_servers: - host: address: redpanda-0.redpanda..svc.cluster.local. port: 33145 - host: address: redpanda-1.redpanda..svc.cluster.local. port: 33145 - host: address: redpanda-2.redpanda..svc.cluster.local. port: 33145 ``` #### [](#nodeport-service)NodePort Service External access is made available by a NodePort service that opens the following ports by default: | Listener | Node Port | Container Port | | --- | --- | --- | | Schema Registry | 30081 | 8081 | | HTTP Proxy | 30082 | 8083 | | Kafka API | 31092 | 9094 | | Admin API | 31644 | 9644 | To learn more, see [Networking and Connectivity in Kubernetes](../../../../manage/kubernetes/networking/k-networking-and-connectivity/). ### [](#tls-certificates)TLS Certificates By default, TLS is enabled in the Redpanda Helm chart. The Helm chart uses [cert-manager](https://cert-manager.io/docs/) to generate four Certificate resources that provide Redpanda with self-signed certificates for internal and external connections. Having separate certificates for internal and external connections provides security isolation. If an external certificate or its corresponding private key is compromised, it doesn’t affect the security of internal communications. ```bash kubectl get certificate --namespace ``` NAME READY redpanda-default-cert True redpanda-default-root-certificate True redpanda-external-cert True redpanda-external-root-certificate True - `redpanda-default-cert`: Self-signed certificate for internal communications. - `redpanda-default-root-certificate`: Root certificate authority for the internal certificate. - `redpanda-external-cert`: Self-signed certificate for external communications. - `redpanda-external-root-certificate`: Root certificate authority for the external certificate. By default, all listeners are configured with the same certificate. To configure separate TLS certificates for different listeners, see [TLS for Redpanda in Kubernetes](../../../../manage/kubernetes/security/tls/). > 📝 **NOTE** > > The Redpanda Helm chart provides self-signed certificates for convenience. In a production environment, it’s best to use certificates from a trusted Certificate Authority (CA) or integrate with your existing CA infrastructure. ## [](#uninstall-redpanda)Uninstall Redpanda When you finish testing Redpanda, you can uninstall it from your Kubernetes cluster. The steps depend on how you installed Redpanda: using the Redpanda Operator or the Redpanda Helm chart. ### Operator Follow the steps in **exact order** to avoid race conditions between the Redpanda Operator’s reconciliation loop and Kubernetes garbage collection. 1. Delete all Redpanda-related custom resources: ```bash kubectl delete users --namespace --all kubectl delete topics --namespace --all kubectl delete schemas --namespace --all kubectl delete redpanda --namespace --all ``` 2. Make sure requests for those resources return no results. For example, if you had a Redpanda cluster named `redpanda` in the namespace ``, run: ```bash kubectl get redpanda --namespace ``` 3. Uninstall the Redpanda Operator Helm release: ```bash helm uninstall redpanda-controller --namespace ``` Helm does not uninstall CRDs by default when using `helm uninstall` to avoid accidentally deleting existing custom resources. 4. Remove the CRDs. 1. List all Redpanda CRDs installed by the operator: ```bash kubectl api-resources --api-group='cluster.redpanda.com' ``` This command displays all CRDs defined by the Redpanda Operator. For example: ```bash NAME SHORTNAMES APIVERSION NAMESPACED KIND redpandas rp cluster.redpanda.com/v1alpha2 true Redpanda schemas sc cluster.redpanda.com/v1alpha2 true Schema topics cluster.redpanda.com/v1alpha2 true Topic users rpu cluster.redpanda.com/v1alpha2 true User ``` 2. Delete the CRDs: ```bash kubectl get crds -o name | grep cluster.redpanda.com | xargs kubectl delete ``` This command lists all CRDs with the `cluster.redpanda.com` domain suffix and deletes them, ensuring only Redpanda CRDs are removed. Helm does not delete CRDs automatically to prevent data loss, so you must run this step manually. 5. (Optional) Delete any leftover PVCs or Secrets in the namespace: > ⚠️ **CAUTION** > > The following command deletes all PVCs and Secrets in the namespace, which may remove unrelated resources if the namespace is shared with other applications. ```bash kubectl delete pvc,secret --all --namespace ``` ### Helm If you deployed Redpanda with the Redpanda Helm chart, follow these steps to uninstall it: 1. Uninstall the Helm release: ```bash helm uninstall redpanda --namespace ``` 2. (Optional) Delete any leftover PVCs or Secrets in the namespace: > ⚠️ **CAUTION** > > The following command deletes all PVCs and Secrets in the namespace, which may remove unrelated resources if the namespace is shared with other applications. ```bash kubectl delete pvc,secret --all --namespace ``` ## [](#delete-the-cluster)Delete the cluster To delete your Kubernetes cluster: ```bash az aks delete --name --resource-group redpandaResourceGroup ``` To remove the convenience alias created during the quickstart: ```bash unalias internal-rpk ``` ## [](#troubleshoot)Troubleshoot Before troubleshooting your cluster, make sure that you have all the [prerequisites](#prerequisites). ### [](#helm-v3-18-0-is-not-supported-json-number-error)Helm v3.18.0 is not supported (json.Number error) If you are using Helm v3.18.0, you may encounter errors such as: Error: INSTALLATION FAILED: execution error at (redpanda/templates/entry-point.yaml:17:4): invalid Quantity expected string or float64 got: json.Number (1) This is due to a bug in Helm v3.18.0. To avoid similar errors, upgrade to a later version. For more details, see the [Helm GitHub issue](https://github.com/helm/helm/issues/30880). === StatefulSet never rolls out If the StatefulSet Pods remain in a pending state, they are waiting for resources to become available. To identify the Pods that are pending, use the following command: ```bash kubectl get pod --namespace ``` The response includes a list of Pods in the StatefulSet and their status. To view logs for a specific Pod, use the following command. ```bash kubectl logs -f --namespace ``` You can use the output to debug your deployment. ### [](#didnt-match-pod-anti-affinity-rules)Didn’t match pod anti-affinity rules If you see this error, your cluster does not have enough nodes to satisfy the anti-affinity rules: Warning FailedScheduling 18m default-scheduler 0/1 nodes are available: 1 node(s) didn't match pod anti-affinity rules. preemption: 0/1 nodes are available: 1 No preemption victims found for incoming pod. The Helm chart configures default `podAntiAffinity` rules to make sure that only one Pod running a Redpanda broker is scheduled on each worker node. To learn why, see [Number of workers](../k-requirements/#number-of-workers). To resolve this issue, do one of the following: - Create additional worker nodes. - Modify the anti-affinity rules (for development purposes only). If adding nodes is not an option, you can modify the `podAntiAffinity` rules in your StatefulSet to be less strict. #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: statefulset: podAntiAffinity: type: soft ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `docker-repo.yaml` ```yaml statefulset: podAntiAffinity: type: soft ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values docker-repo.yaml ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set statefulset.podAntiAffinity.type=soft ``` ### [](#unable-to-mount-volume)Unable to mount volume If you see volume mounting errors in the Pod events or in the Redpanda logs, ensure that each of your Pods has a volume available in which to store data. - If you’re using StorageClasses with dynamic provisioners (default), ensure they exist: ```bash kubectl get storageclass ``` - If you’re using PersistentVolumes, ensure that you have one PersistentVolume available for each Redpanda broker, and that each one has the storage capacity that’s set in `storage.persistentVolume.size`: ```bash kubectl get persistentvolume --namespace ``` To learn how to configure different storage volumes, see [Configure Storage](../../../../manage/kubernetes/storage/k-configure-storage/). ### [](#failed-to-pull-image)Failed to pull image When deploying the Redpanda Helm chart, you may encounter Docker rate limit issues because the default registry URL is not recognized as a Docker Hub URL. The domain `docker.redpanda.com` is used for statistical purposes, such as tracking the number of downloads. It mirrors Docker Hub’s content while providing specific analytics for Redpanda. Failed to pull image "docker.redpanda.com/redpandadata/redpanda:v": rpc error: code = Unknown desc = failed to pull and unpack image "docker.redpanda.com/redpandadata/redpanda:v": failed to copy: httpReadSeeker: failed open: unexpected status code 429 Too Many Requests - Server message: toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit To fix this error, do one of the following: - Replace the `image.repository` value in the Helm chart with `docker.io/redpandadata/redpanda`. Switching to Docker Hub avoids the rate limit issues associated with `docker.redpanda.com`. #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: image: repository: docker.io/redpandadata/redpanda ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `docker-repo.yaml` ```yaml image: repository: docker.io/redpandadata/redpanda ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values docker-repo.yaml ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set image.repository=docker.io/redpandadata/redpanda ``` - Authenticate to Docker Hub by logging in with your Docker Hub credentials. The `docker.redpanda.com` site acts as a reflector for Docker Hub. As a result, when you log in with your Docker Hub credentials, you will bypass the rate limit issues. ### [](#dig-not-defined)Dig not defined This error means that you are using an unsupported version of [Helm](https://helm.sh/docs/intro/install/): Error: parse error at (redpanda/templates/statefulset.yaml:203): function "dig" not defined To fix this error, ensure that you are using the minimum required version: 3.10.0. ```bash helm version ``` ### [](#repository-name-already-exists)Repository name already exists If you see this error, remove the `redpanda` chart repository, then try installing it again. ```bash helm repo remove redpanda helm repo add redpanda https://charts.redpanda.com helm repo update ``` ### [](#fatal-error-during-checker-data-directory-is-writable-execution)Fatal error during checker "Data directory is writable" execution This error appears when Redpanda does not have write access to your configured storage volume under `storage` in the Helm chart. Error: fatal error during checker "Data directory is writable" execution: open /var/lib/redpanda/data/test\_file: permission denied To fix this error, set `statefulset.initContainers.setDataDirOwnership.enabled` to `true` so that the initContainer can set the correct permissions on the data directories. ### [](#cannot-patch-redpanda-with-kind-statefulset)Cannot patch "redpanda" with kind StatefulSet This error appears when you run `helm upgrade` with the `--values` flag but do not include all your previous overrides. Error: UPGRADE FAILED: cannot patch "redpanda" with kind StatefulSet: StatefulSet.apps "redpanda" is invalid: spec: Forbidden: updates to statefulset spec for fields other than 'replicas', 'template', 'updateStrategy', 'persistentVolumeClaimRetentionPolicy' and 'minReadySeconds' are forbidden To fix this error, include all the value overrides from the previous installation using either the `--set` or the `--values` flags. > ⚠️ **WARNING** > > Do not use the `--reuse-values` flag to upgrade from one version of the Helm chart to another. This flag stops Helm from using any new values in the upgraded chart. ### [](#cannot-patch-redpanda-console-with-kind-deployment)Cannot patch "redpanda-console" with kind Deployment This error appears if you try to upgrade your deployment and you already have `console.enabled` set to `true`. Error: UPGRADE FAILED: cannot patch "redpanda-console" with kind Deployment: Deployment.apps "redpanda-console" is invalid: spec.selector: Invalid value: v1.LabelSelector{MatchLabels:map\[string\]string{"app.kubernetes.io/instance":"redpanda", "app.kubernetes.io/name":"console"}, MatchExpressions:\[\]v1.LabelSelectorRequirement(nil)}: field is immutable To fix this error, set `console.enabled` to `false` so that Helm doesn’t try to deploy Redpanda Console again. ### [](#helm-is-in-a-pending-rollback-state)Helm is in a pending-rollback state An interrupted Helm upgrade process can leave your Helm release in a `pending-rollback` state. This state prevents further actions like upgrades, rollbacks, or deletions through standard Helm commands. To fix this: 1. Identify the Helm release that’s in a `pending-rollback` state: ```bash helm list --namespace --all ``` Look for releases with a status of `pending-rollback`. These are the ones that need intervention. 2. Verify the Secret’s status to avoid affecting the wrong resource: ```bash kubectl --namespace get secret --show-labels ``` Identify the Secret associated with your Helm release by its `pending-rollback` status in the labels. > ⚠️ **WARNING** > > Ensure you have correctly identified the Secret to avoid unintended consequences. Deleting the wrong Secret could impact other deployments or services. 3. Delete the Secret to clear the `pending-rollback` state: ```bash kubectl --namespace delete secret -l status=pending-rollback ``` After clearing the `pending-rollback` state: - **Retry the upgrade**: Restart the upgrade process. You should investigate the initial failure to avoid getting into the `pending-rollback` state again. - **Perform a rollback**: If you need to roll back to a previous release, use `helm rollback ` to revert to a specific, stable release version. ### [](#crash-loop-backoffs)Crash loop backoffs If a broker crashes after startup, or gets stuck in a crash loop, it can accumulate an increasing amount of stored state. This accumulated state not only consumes additional disk space but also prolongs the time required for each subsequent restart to process it. To prevent infinite crash loops, the Redpanda Helm chart sets the [`crash_loop_limit`](../../../../reference/properties/broker-properties/#crash_loop_limit) broker configuration property to `5`. The crash loop limit is the number of consecutive crashes that can happen within one hour of each other. By default, the broker terminates immediately after hitting the `crash_loop_limit`. The Pod running Redpanda remains in a `CrashLoopBackoff` state until its internal consecutive crash counter is reset to zero. To facilitate debugging in environments where a broker is stuck in a crash loop, you can also set the [`crash_loop_sleep_sec`](../../../../reference/properties/broker-properties/#crash_loop_sleep_sec) broker configuration property. This setting determines how long the broker sleeps before terminating the process after reaching the crash loop limit. By providing a window during which the Pod remains available, you can SSH into it and troubleshoot the issue. Example configuration: ```yaml config: node: crash_loop_limit: 5 crash_loop_sleep_sec: 60 ``` In this example, when the broker hits the `crash_loop_limit` of 5, it will sleep for 60 seconds before terminating the process. This delay allows administrators to access the Pod and troubleshoot. To troubleshoot a crash loop backoff: 1. Check the Redpanda logs from the most recent crashes: ```bash kubectl logs --namespace ``` > 📝 **NOTE** > > Kubernetes retains logs only for the current and the previous instance of a container. This limitation makes it difficult to access logs from earlier crashes, which may contain vital clues about the root cause of the issue. Given these log retention limitations, setting up a centralized logging system is crucial. Systems such as [Loki](https://grafana.com/docs/loki/latest/) or [Datadog](https://www.datadoghq.com/product/log-management/) can capture and store logs from all containers, ensuring you have access to historical data. 2. Resolve the issue that led to the crash loop backoff. 3. Reset the crash counter to zero to allow Redpanda to restart. You can do any of the following to reset the counter: - Make changes to any of the following sections in the Redpanda Helm chart to trigger an update: - `config.node` - `config.tunable` For example: ```yaml config: node: crash_loop_limit: ``` - Delete the `startup_log` file in the broker’s data directory. ```bash kubectl exec --namespace -- rm /var/lib/redpanda/data/startup_log ``` > 📝 **NOTE** > > It might be challenging to execute this command within a Pod that is in a `CrashLoopBackoff` state due to the limited time during which the Pod is available before it restarts. Wrapping the command in a loop might work. - Wait one hour since the last crash. The crash counter resets after one hour. To avoid future crash loop backoffs and manage the accumulation of small segments effectively: - [Monitor](../../../../manage/kubernetes/monitoring/k-monitor-redpanda/) the size and number of segments regularly. - Optimize your Redpanda configuration for segment management. - Consider implementing [Tiered Storage](../../../../manage/kubernetes/tiered-storage/k-tiered-storage/) to manage data more efficiently. ### [](#a-redpanda-enterprise-edition-license-is-required)A Redpanda Enterprise Edition license is required During a Redpanda upgrade, if enterprise features are enabled and a valid Enterprise Edition license is missing, Redpanda logs a warning and aborts the upgrade process on the first broker. This issue prevents a successful upgrade. A Redpanda Enterprise Edition license is required to use the currently enabled features. To apply your license, downgrade this broker to the pre-upgrade version and provide a valid license key via rpk using 'rpk cluster license set ', or via Redpanda Console. To request an enterprise license, please visit . To try Redpanda Enterprise for 30 days, visit . For more information, see . If you encounter this message, follow these steps to recover: 1. [Roll back the affected broker to the original version](../../../../upgrade/k-rolling-upgrade/#roll-back). 2. Do one of the following: - [Apply a valid Redpanda Enterprise Edition license](../../../../get-started/licensing/add-license-redpanda/) to the cluster. - Disable enterprise features. If you do not have a valid license and want to proceed without using enterprise features, you can disable the enterprise features in your Redpanda configuration. 3. Retry the upgrade. For more troubleshooting steps, see [Troubleshoot Redpanda in Kubernetes](../../../../troubleshoot/errors-solutions/k-resolve-errors/). ## [](#next-steps)Next steps - [Try an example in Redpanda Labs](../../../../../redpanda-labs/) - [Learn more about Redpanda Console](../../../../manage/console/) - [Learn more about rpk](../../../../get-started/rpk-install/) > 💡 **TIP** > > When you’re ready to use a registered domain, make sure to remove your entries from the `/etc/hosts` file, and see [Configure External Access through a NodePort Service](../../../../manage/kubernetes/networking/external/k-nodeport/#use-the-default-redpanda-subdomains). ## [](#suggested-reading)Suggested reading - [Networking and Connectivity in Kubernetes](../../../../manage/kubernetes/networking/k-networking-and-connectivity/) - [Configure TLS for Redpanda in Kubernetes](../../../../manage/kubernetes/security/tls/) - [Configure SASL for Redpanda in Kubernetes](../../../../manage/kubernetes/security/authentication/k-authentication/) - [Redpanda Helm Specification](../../../../reference/k-redpanda-helm-spec/) - [Redpanda CRD Reference](../../../../reference/k-crd/) - [Redpanda Console README](https://github.com/redpanda-data/console) on GitHub ## Suggested labs - [Disaster Recovery with Envoy and Shadowing](/redpanda-labs/docker-compose/envoy-shadowing/) - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Stream Jira Issues to Redpanda for Real-Time Metrics](/redpanda-labs/docker-compose/jira-metrics-pipeline/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Set Up GitOps for the Redpanda Helm Chart](/redpanda-labs/kubernetes/gitops-helm/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) - [Set Up MySQL CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-mysql-json/) - [Set Up Postgres CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-postgres-json/) See more [Search all labs](/redpanda-labs) --- # Page 36: Deploy a Redpanda Cluster in Amazon Elastic Kubernetes Service **URL**: https://docs.redpanda.com/current/deploy/redpanda/kubernetes/eks-guide.md --- # Deploy a Redpanda Cluster in Amazon Elastic Kubernetes Service --- title: Deploy a Redpanda Cluster in Amazon Elastic Kubernetes Service latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: redpanda/kubernetes/eks-guide page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: redpanda/kubernetes/eks-guide.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/redpanda/kubernetes/eks-guide.adoc description: Deploy a secure Redpanda cluster and Redpanda Console in Amazon Elastic Kubernetes Service (EKS). page-git-created-date: "2025-08-15" page-git-modified-date: "2025-08-29" support-status: supported --- Deploy a secure Redpanda cluster and Redpanda Console in Amazon Elastic Kubernetes Service (EKS). Then, use `rpk` both as an internal client and an external client to interact with your Redpanda cluster from the command line. Your Redpanda cluster has the following security features: - SASL for authenticating users' connections. - TLS with self-signed certificates for secure communication between the cluster and clients. ## [](#prerequisites)Prerequisites Before you begin, you must meet the following prerequisites. ### [](#iam-user)IAM user You need an IAM user with at least the following policies. See the AWS documentation for help [creating IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html) or for help [troubleshooting IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot.html). Policies Replace `` with your own [account ID](https://console.aws.amazon.com/iamv2/home). AmazonEC2FullAccess ```json { "Version": "2012-10-17", "Statement": [ { "Action": "ec2:*", "Effect": "Allow", "Resource": "*" }, { "Effect": "Allow", "Action": "elasticloadbalancing:*", "Resource": "*" }, { "Effect": "Allow", "Action": "cloudwatch:*", "Resource": "*" }, { "Effect": "Allow", "Action": "autoscaling:*", "Resource": "*" }, { "Effect": "Allow", "Action": "iam:CreateServiceLinkedRole", "Resource": "*", "Condition": { "StringEquals": { "iam:AWSServiceName": [ "autoscaling.amazonaws.com", "ec2scheduled.amazonaws.com", "elasticloadbalancing.amazonaws.com", "spot.amazonaws.com", "spotfleet.amazonaws.com", "transitgateway.amazonaws.com" ] } } } ] } ``` AWSCloudFormationFullAccess ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "cloudformation:*" ], "Resource": "*" } ] } ``` EksAllAccess ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "eks:*", "Resource": "*" }, { "Action": [ "ssm:GetParameter", "ssm:GetParameters" ], "Resource": [ "arn:aws:ssm:*::parameter/aws/*", "arn:aws:ssm:*::parameter/aws/*" ], "Effect": "Allow" }, { "Action": [ "kms:CreateGrant", "kms:DescribeKey" ], "Resource": "*", "Effect": "Allow" }, { "Action": [ "logs:PutRetentionPolicy" ], "Resource": "*", "Effect": "Allow" } ] } ``` IamLimitedAccess ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iam:CreateInstanceProfile", "iam:DeleteInstanceProfile", "iam:GetInstanceProfile", "iam:RemoveRoleFromInstanceProfile", "iam:GetRole", "iam:CreateRole", "iam:DeleteRole", "iam:AttachRolePolicy", "iam:PutRolePolicy", "iam:ListInstanceProfiles", "iam:AddRoleToInstanceProfile", "iam:ListInstanceProfilesForRole", "iam:PassRole", "iam:DetachRolePolicy", "iam:DeleteRolePolicy", "iam:GetRolePolicy", "iam:GetOpenIDConnectProvider", "iam:CreateOpenIDConnectProvider", "iam:DeleteOpenIDConnectProvider", "iam:TagOpenIDConnectProvider", "iam:ListAttachedRolePolicies", "iam:TagRole", "iam:GetPolicy", "iam:CreatePolicy", "iam:DeletePolicy", "iam:ListPolicyVersions" ], "Resource": [ "arn:aws:iam:::instance-profile/eksctl-*", "arn:aws:iam:::role/eksctl-*", "arn:aws:iam:::policy/eksctl-*", "arn:aws:iam:::oidc-provider/*", "arn:aws:iam:::role/aws-service-role/eks-nodegroup.amazonaws.com/AWSServiceRoleForAmazonEKSNodegroup", "arn:aws:iam:::role/eksctl-managed-*", "arn:aws:iam:::role/AmazonEKS_EBS_CSI_DriverRole" ] }, { "Effect": "Allow", "Action": [ "iam:GetRole" ], "Resource": [ "arn:aws:iam:::role/*" ] }, { "Effect": "Allow", "Action": [ "iam:CreateServiceLinkedRole" ], "Resource": "*", "Condition": { "StringEquals": { "iam:AWSServiceName": [ "eks.amazonaws.com", "eks-nodegroup.amazonaws.com", "eks-fargate.amazonaws.com" ] } } } ] } ``` ### [](#aws-cli)AWS CLI You need the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) to configure `kubeconfig` and get information about your EC2 instances. After you’ve installed the AWS CLI, make sure to [configure it](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) with credentials for your IAM user. > 📝 **NOTE** > > If your account uses an identity provider in the IAM Identity Center (previously AWS SSO, [authenticate with the IAM Identity Center](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html) (`aws sso login`). For troubleshooting, see the [AWS CLI documentation](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html#install-tshoot). ### [](#eksctl)eksctl You need [`eksctl`](https://docs.aws.amazon.com/eks/latest/userguide/eksctl.html) to create an EKS cluster from the command line. ### [](#jq)jq You need [jq](https://stedolan.github.io/jq/download/) to parse JSON results and store the value in environment variables. ### [](#kubectl)kubectl You must have [`kubectl`](https://docs.aws.amazon.com/eks/latest/userguide/install-kubectl.html) with the following minimum required Kubernetes version: 1.27.0-0 To check if you have `kubectl` installed: ```bash kubectl version --client ``` ### [](#helm)Helm You must have the following minimum required version of [Helm](https://helm.sh/docs/intro/install/): 3.10.0 To check if you have Helm installed: ```bash helm version ``` ## [](#create-an-eks-cluster)Create an EKS cluster Your EKS cluster must have one worker node available for each Redpanda broker that you plan to deploy in your Redpanda cluster. You also need to run the worker nodes on an EC2 instance type that supports the [requirements and recommendations](../k-requirements/) for production deployments. In this step, you create an EKS cluster with three nodes on [`c5d.2xlarge` instance types](https://aws.amazon.com/ec2/instance-types/c5/). Deploying three nodes allows your EKS cluster to support a Redpanda cluster with three brokers. The `c5d.2xlarge` instance type comes with: - Sufficient CPU: Redpanda requires at least 2 full CPU cores per broker. The c5d.2xlarge instance provides 8 vCPUs, which comfortably meets this requirement. - Local NVMe disks, which is recommended for best performance. 1. Create an EKS cluster and give it a unique name. If your account is configured with OIDC, add the `--with-oidc` flag to the `create cluster` command. ```bash eksctl create cluster \ --name \ --nodegroup-name nvme-workers \ --node-type c5d.2xlarge \ --nodes 3 \ --external-dns-access ``` > ❗ **IMPORTANT** > > Do not enable [auto mode](https://docs.aws.amazon.com/eks/latest/userguide/automode.html) (`--enable-auto-mode`) on Amazon EKS clusters running Redpanda. > > Auto mode can trigger automatic reboots or node upgrades that disrupt Redpanda brokers, risking data loss or cluster instability. Redpanda requires manual control over node lifecycle events. > > For more details, see the [requirements and recommendations](../k-requirements/#node-updates) for deploying Redpanda in Kubernetes. To see all options: ```bash eksctl create cluster --help ``` Or, for help creating an EKS cluster, see the [Creating and managing clusters](https://eksctl.io/usage/creating-and-managing-clusters/) in the `eksctl` documentation. 2. Make sure that your local `kubeconfig` file points to your EKS cluster: ```bash kubectl get service ``` You should see a ClusterIP Service called `kubernetes`. If the `kubectl` command cannot connect to your cluster, update your local `kubeconfig` file to point to your EKS cluster. Your default region is in the `~/.aws/credentials` file. ```bash aws eks update-kubeconfig --region --name ``` ### [](#create-sc)Create a StorageClass for your local NVMe disks When you provisioned the Kubernetes cluster, you selected an instance type that comes with local NVMe disks. However, these disks are not automatically mounted or formatted upon creation. To use these local NVMe disks, you must mount and format them, and you must create the necessary PersistentVolumes (PVs). To automate this process, you can use a Container Storage Interface (CSI) driver. In this step, you install the recommended [local volume manager (LVM) CSI driver](https://github.com/metal-stack/csi-driver-lvm). Then, you create a StorageClass that references the LVM CSI driver and specifies the recommended XFS file system. 1. Install the LVM CSI driver: ```yaml helm repo add metal-stack https://helm.metal-stack.io helm repo update helm install csi-driver-lvm metal-stack/csi-driver-lvm \ --version 0.6.0 \ --namespace csi-driver-lvm \ --create-namespace \ --set lvm.devicePattern='/dev/nvme[1-9]n[0-9]' ``` The `lvm.devicePattern` property specifies the pattern that the CSI driver uses to identify available NVMe volumes on your worker nodes. > 📝 **NOTE** > > Version 0.6.0 is required to avoid volume-mounting issues caused by recent `mkfs.xfs` updates. Newer versions enable the `-i nrext64=1` option, triggering the following error on default EKS kernels: > > XFS (dm-0): Superblock has unknown incompatible features (0x20) enabled. 2. Create the StorageClass: `csi-driver-lvm-striped-xfs.yaml` ```yaml apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: csi-driver-lvm-striped-xfs provisioner: lvm.csi.metal-stack.io reclaimPolicy: Retain volumeBindingMode: WaitForFirstConsumer allowVolumeExpansion: true parameters: type: "striped" csi.storage.k8s.io/fstype: xfs mkfsParams: "-i nrext64=0" ``` - `provisioner`: The LVM CSI driver responsible for provisioning the volume. - `reclaimPolicy`: The `Retain` policy ensures that the underlying volume is not deleted when the corresponding PVC is deleted. - `volumeBindingMode`: The `WaitForFirstConsumer` mode delays the binding and provisioning of a PersistentVolume until a Pod that uses the PVC is created. This mode is important for ensuring that the PV is created on the same node where the Pod will run because the PV will use the node’s local NVMe volumes. - `allowVolumeExpansion`: Allows the volume to be expanded after it has been provisioned. - `parameters.type`: Combines multiple physical volumes to create a single logical volume. In a striped setup, data is spread across the physical volumes in a way that distributes the I/O load evenly, improving performance by allowing parallel disk I/O operations. - `parameters.csi.storage.k8s.io/fstype`: Formats the volumes with the XFS file system. Redpanda Data recommends XFS for its enhanced performance with Redpanda workloads. - `parameters.mkfsParams`: Disables the nrext64 feature to ensure compatibility with older kernels. 3. Apply the StorageClass: ```bash kubectl apply -f csi-driver-lvm-striped-xfs.yaml ``` After applying this StorageClass, any PVC that references it will attempt to provision storage using the LVM CSI driver and the provided parameters. ### [](#configure-external-access)Configure external access In this step, you configure your EKS cluster to allow external access to the node ports on which the Redpanda deployment will be exposed. You use these node ports in later steps to configure external access to your Redpanda cluster. 1. Get the ID of the security group that’s associated with the nodes in your EKS cluster: ```bash AWS_SECURITY_GROUP_ID=`aws eks describe-cluster --name | jq -r '.cluster.resourcesVpcConfig.clusterSecurityGroupId'` ``` 2. Add inbound firewall rules to your EC2 instances so that external traffic can reach the node ports exposed on all Kubernetes worker nodes in the cluster: ```bash aws ec2 authorize-security-group-ingress \ --group-id ${AWS_SECURITY_GROUP_ID} \ --ip-permissions '[ { "IpProtocol": "tcp", "FromPort": 30081, "ToPort": 30081, "IpRanges": [{"CidrIp": "0.0.0.0/0"}] }, { "IpProtocol": "tcp", "FromPort": 30082, "ToPort": 30082, "IpRanges": [{"CidrIp": "0.0.0.0/0"}] }, { "IpProtocol": "tcp", "FromPort": 31644, "ToPort": 31644, "IpRanges": [{"CidrIp": "0.0.0.0/0"}] }, { "IpProtocol": "tcp", "FromPort": 31092, "ToPort": 31092, "IpRanges": [{"CidrIp": "0.0.0.0/0"}] } ]' ``` > ⚠️ **CAUTION** > > If you use `0.0.0.0/0`, you enable all IPv4 addresses to access your instances on those node ports. In production, you should authorize only a specific IP address or range of addresses to access your instances. For help creating firewall rules, see the [Amazon EC2 documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/authorizing-access-to-an-instance.html). ## [](#deploy-redpanda-and-redpanda-console)Deploy Redpanda and Redpanda Console In this step, you deploy Redpanda with SASL authentication and self-signed TLS certificates. Redpanda Console is included as a subchart in the Redpanda Helm chart. ### Operator 1. Make sure that you have permission to install custom resource definitions (CRDs): ```bash kubectl auth can-i create CustomResourceDefinition --all-namespaces ``` You should see `yes` in the output. You need these cluster-level permissions to install [cert-manager](https://cert-manager.io/docs/) and Redpanda Operator CRDs in the next steps. 2. Install [cert-manager](https://cert-manager.io/docs/installation/helm/) using Helm: ```bash helm repo add jetstack https://charts.jetstack.io helm repo update helm install cert-manager jetstack/cert-manager \ --set crds.enabled=true \ --namespace cert-manager \ --create-namespace ``` The Redpanda Helm chart uses cert-manager to enable TLS and manage TLS certificates by default. 3. Deploy the Redpanda Operator: 1. To deploy in cluster scope, use: ```bash helm repo add redpanda https://charts.redpanda.com helm repo update helm upgrade --install redpanda-controller redpanda/operator \ --namespace \ --create-namespace \ --version v26.1.2 \ (1) --set crds.enabled=true (2) ``` | 1 | This flag specifies the exact version of the Redpanda Operator Helm chart to use for deployment. By setting this value, you pin the chart to a specific version, which prevents automatic updates that might introduce breaking changes or new features that have not been tested in your environment. | | --- | --- | | 2 | This flag ensures that the CRDs are installed as part of the Redpanda Operator deployment.This command deploys the Redpanda Operator in cluster scope (default in v25.2+), allowing it to manage Redpanda clusters across multiple namespaces. | 2. To deploy in namespace scope (managing only resources within its deployment namespace), use: ```bash helm upgrade --install redpanda-controller redpanda/operator \ --namespace \ --create-namespace \ --version v26.1.2 \ --set crds.enabled=true \ --set 'additionalCmdFlags=["--namespace="]' (1) ``` | 1 | This flag restricts the Redpanda Operator to manage resources only within the specified namespace. | | --- | --- | 4. Ensure that the Deployment is successfully rolled out: ```bash kubectl --namespace rollout status --watch deployment/redpanda-controller-operator ``` deployment "redpanda-controller-operator" successfully rolled out 5. Install a [Redpanda custom resource](../../../../reference/k-crd/) in the same namespace as the Redpanda Operator: `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: clusterSpec: image: tag: v26.1.3 external: domain: customredpandadomain.local auth: sasl: enabled: true users: - name: superuser password: secretpassword storage: persistentVolume: enabled: true storageClass: csi-driver-lvm-striped-xfs ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` - `image.tag`: Deploys the latest version of Redpanda. - `external.domain`: The custom domain that each broker will advertise to clients externally. This domain is added to the internal and external TLS certificates so that you can connect to the cluster using this domain. - `auth.sasl.name`: Creates a superuser called `superuser` that can grant permissions to new users in your cluster using access control lists (ACLs). - `storage.persistentVolume.storageClass`: Points each PVC associated with the Redpanda brokers to the `csi-driver-lvm-striped-xfs` StorageClass. This StorageClass allows the LVM CSI driver to provision the appropriate local PersistentVolumes backed by NVMe disks for each Redpanda broker. 6. Wait for the Redpanda Operator to deploy Redpanda using the Helm chart: ```bash kubectl get redpanda --namespace --watch ``` NAME READY STATUS redpanda True Redpanda reconciliation succeeded This step may take a few minutes. You can watch for new Pods to make sure that the deployment is progressing: ```bash kubectl get pod --namespace ``` If it’s taking too long, see [Troubleshoot](#troubleshoot). ### Helm 1. Install cert-manager using Helm: ```bash helm repo add jetstack https://charts.jetstack.io helm repo update helm install cert-manager jetstack/cert-manager \ --set crds.enabled=true \ --namespace cert-manager \ --create-namespace ``` TLS is enabled by default. The Redpanda Helm chart uses cert-manager to manage TLS certificates by default. 2. Install Redpanda with SASL enabled: ```bash helm repo add redpanda https://charts.redpanda.com helm repo update helm install redpanda redpanda/redpanda \ --version 26.1.2 \ --namespace --create-namespace \ --set image.tag=v26.1.3 \ --set auth.sasl.enabled=true \ --set "auth.sasl.users[0].name=superuser" \ --set "auth.sasl.users[0].password=secretpassword" \ --set external.domain=customredpandadomain.local \ --set "storage.persistentVolume.storageClass=csi-driver-lvm-striped-xfs" \ --wait \ --timeout 1h ``` - `image.tag`: Deploys the latest version of Redpanda. - `external.domain`: The custom domain that each broker advertises to clients externally. This domain is added to the internal and external TLS certificates so that you can connect to the cluster using this domain. - `auth.sasl.name`: Creates a superuser called `superuser` that can grant permissions to new users in your cluster using access control lists (ACLs). - `storage.persistentVolume.storageClass`: Points each PVC associated with the Redpanda brokers to the `csi-driver-lvm-striped-xfs` StorageClass. This StorageClass allows the LVM CSI driver to provision the appropriate local PersistentVolumes backed by NVMe disks for each Redpanda broker. The installation displays some tips for getting started. If the installation is taking a long time, see [Troubleshoot](#troubleshoot). ## [](#verify-the-deployment)Verify the deployment When the Redpanda Helm chart is deployed, you should have: - Three Redpanda brokers. Each Redpanda broker runs inside a separate Pod and is scheduled on a separate worker node. - One PVC bound to a PV for each Redpanda broker. These PVs are what the Redpanda brokers use to store the Redpanda data directory with all your topics and metadata. 1. Verify that each Redpanda broker is scheduled on only one Kubernetes node: ```bash kubectl get pod --namespace \ -o=custom-columns=NODE:.spec.nodeName,POD_NAME:.metadata.name -l \ app.kubernetes.io/component=redpanda-statefulset ``` Example output: NODE POD\_NAME example-worker3 redpanda-0 example-worker2 redpanda-1 example-worker redpanda-2 2. Verify that each Redpanda broker has a bound PVC: ```bash kubectl get persistentvolumeclaim \ --namespace \ -o custom-columns=NAME:.metadata.name,STATUS:.status.phase,STORAGECLASS:.spec.storageClassName ``` Example output: NAME STATUS STORAGECLASS datadir-redpanda-0 Bound csi-driver-lvm-striped-xfs datadir-redpanda-1 Bound csi-driver-lvm-striped-xfs datadir-redpanda-2 Bound csi-driver-lvm-striped-xfs ## [](#create-a-user)Create a user In this step, you use `rpk` to create a new user. Then, you authenticate to Redpanda with the superuser to grant permissions to the new user. You’ll authenticate to Redpanda with this new user to create a topic in the next steps. > 💡 **TIP** > > As a security best practice, you should use the superuser only to grant permissions to new users through ACLs. Never delete the superuser. You need the superuser to grant permissions to new users. 1. Create a new user called `redpanda-twitch-account` with the password `changethispassword`: ```bash kubectl --namespace exec -ti redpanda-0 -c redpanda -- \ rpk security user create redpanda-twitch-account \ -p changethispassword ``` Example output: Created user "redpanda-twitch-account". 2. Use the superuser to grant the `redpanda-twitch-account` user permission to execute all operations only for a topic called `twitch-chat`. ```bash kubectl exec --namespace -c redpanda redpanda-0 -- \ rpk security acl create --allow-principal User:redpanda-twitch-account \ --operation all \ --topic twitch-chat \ -X user=superuser -X pass=secretpassword -X sasl.mechanism=SCRAM-SHA-512 ``` Example output: PRINCIPAL RESOURCE-TYPE RESOURCE-NAME OPERATION PERMISSION User:redpanda TOPIC twitch-chat ALL ALLOW ## [](#start-streaming)Start streaming In this step, you authenticate to Redpanda with the `redpanda-twitch-account` user to create a topic called `twitch-chat`. This topic is the only one that the `redpanda-twitch-account` user has permission to access. Then, you produce messages to the topic, and consume messages from it. 1. Create an alias to simplify the `rpk` commands: ```bash alias internal-rpk="kubectl --namespace exec -i -t redpanda-0 -c redpanda -- rpk -X user=redpanda-twitch-account -X pass=changethispassword -X sasl.mechanism=SCRAM-SHA-256" ``` 2. Create a topic called `twitch-chat`: ### Operator 1. Create a Secret in which to store your user’s password: ```bash kubectl create secret generic redpanda-secret --from-literal=password='changethispassword' --namespace ``` 2. Create a [Topic resource](../../../../manage/kubernetes/k-manage-topics/): `topic.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Topic metadata: name: twitch-chat spec: kafkaApiSpec: brokers: - "redpanda-0.redpanda..svc.cluster.local:9093" - "redpanda-1.redpanda..svc.cluster.local:9093" - "redpanda-2.redpanda..svc.cluster.local:9093" tls: caCertSecretRef: name: "redpanda-default-cert" key: "ca.crt" sasl: username: redpanda-twitch-account mechanism: SCRAM-SHA-256 passwordSecretRef: name: redpanda-secret key: password ``` 3. Apply the Topic resource in the same namespace as your Redpanda cluster: ```bash kubectl apply -f topic.yaml --namespace ``` 4. Check the logs of the Redpanda Operator to confirm that the topic was created: ```bash kubectl logs -l app.kubernetes.io/name=operator -c manager --namespace ``` You should see that the Redpanda Operator reconciled the Topic resource. For example: Example output ```json { "level":"info", "ts":"2023-09-25T16:20:09.538Z", "logger":"TopicReconciler.Reconcile", "msg":"Starting reconcile loop", "controller":"topic", "controllerGroup":"cluster.redpanda.com", "controllerKind":"Topic", "Topic": { "name":"twitch-chat", "namespace":"" }, "namespace":"", "name":"twitch-chat", "reconcileID":"c0cf9abc-a553-48b7-9b6e-2de3cdfb4432" } { "level":"info", "ts":"2023-09-25T16:20:09.581Z", "logger":"TopicReconciler.Reconcile", "msg":"reconciliation finished in 43.436125ms, next run in 3s", "controller":"topic", "controllerGroup":"cluster.redpanda.com", "controllerKind":"Topic", "Topic": { "name":"twitch-chat", "namespace":"" }, "namespace":"", "name":"twitch-chat", "reconcileID":"c0cf9abc-a553-48b7-9b6e-2de3cdfb4432", "result": { "Requeue":false, "RequeueAfter":3000000000 } } ``` ### Helm ```bash internal-rpk topic create twitch-chat ``` Example output: TOPIC STATUS twitch-chat OK 3. Describe the topic: ```bash internal-rpk topic describe twitch-chat ``` Expected output: ```none SUMMARY ======= NAME twitch-chat PARTITIONS 1 REPLICAS 1 CONFIGS ======= KEY VALUE SOURCE cleanup.policy delete DYNAMIC_TOPIC_CONFIG compression.type producer DEFAULT_CONFIG message.timestamp.type CreateTime DEFAULT_CONFIG partition_count 1 DYNAMIC_TOPIC_CONFIG redpanda.datapolicy function_name: script_name: DEFAULT_CONFIG redpanda.remote.read false DEFAULT_CONFIG redpanda.remote.write false DEFAULT_CONFIG replication_factor 1 DYNAMIC_TOPIC_CONFIG retention.bytes -1 DEFAULT_CONFIG retention.ms 604800000 DEFAULT_CONFIG segment.bytes 1073741824 DEFAULT_CONFIG ``` 4. Produce a message to the topic: ```bash internal-rpk topic produce twitch-chat ``` 5. Type a message, then press Enter: Pandas are fabulous! Example output: Produced to partition 0 at offset 0 with timestamp 1663282629789. 6. Press Ctrl+C to finish producing messages to the topic. 7. Consume one message from the topic: ```bash internal-rpk topic consume twitch-chat --num 1 ``` Expected output: ```none { "topic": "twitch-chat", "value": "Pandas are fabulous!", "timestamp": 1663282629789, "partition": 0, "offset": 0 } ``` ## [](#explore-your-topic-in-redpanda-console)Explore your topic in Redpanda Console Redpanda Console is a developer-friendly web UI for managing and debugging your Redpanda cluster and your applications. In this step, you use port-forwarding to access Redpanda Console on your local network. > 💡 **TIP** > > Because you’re using the Community Edition of Redpanda Console, you should not expose Redpanda Console outside your local network. The Community Edition of Redpanda Console does not provide authentication, and it connects to the Redpanda cluster as superuser. To use the Enterprise Edition, you need a license key. See [Redpanda Licensing](../../../../get-started/licensing/). 1. Expose Redpanda Console to your localhost: ```bash kubectl --namespace port-forward svc/redpanda-console 8080:8080 ``` The `kubectl port-forward` command actively runs in the command-line window. To execute other commands while the command is running, open another command-line window. 2. Open Redpanda Console on [http://localhost:8080](http://localhost:8080). All your Redpanda brokers are listed along with their IP addresses and IDs. 3. Go to **Topics** > **twitch-chat**. The message that you produced to the topic is displayed along with some other details about the topic. 4. Press Ctrl+C in the command-line to stop the port-forwarding process. ## [](#configure-external-access-to-redpanda)Configure external access to Redpanda If you want to connect to the Redpanda cluster with external clients, Redpanda brokers must advertise an externally accessible address that external clients can connect to. External clients are common in Internet of Things (IoT) environments, or if you use external services that do not implement VPC peering in your network. When you created the cluster, you set the `external.domain` configuration to `customredpandadomain.local`, which means that your Redpanda brokers are advertising the following addresses: - `redpanda-0.customredpandadomain.local` - `redpanda-1.customredpandadomain.local` - `redpanda-2.customredpandadomain.local` To access your Redpanda brokers externally, you can map your worker nodes' IP addresses to these domains. > ⚠️ **CAUTION** > > IP addresses can change. If the IP addresses of your worker nodes change, you must update your `/etc/hosts` file with the new mappings. > > In a production environment, it’s a best practice to use ExternalDNS to manage DNS records for your brokers. See [Use ExternalDNS for external access](../k-requirements/#use-externaldns-for-external-access). 1. Add mappings in your `/etc/hosts` file between your worker nodes' IP addresses and their custom domain names: ```bash sudo true && kubectl --namespace get endpoints,node -A -o go-template='{{ range $_ := .items }}{{ if and (eq .kind "Endpoints") (eq .metadata.name "redpanda-external") }}{{ range $_ := (index .subsets 0).addresses }}{{ $nodeName := .nodeName }}{{ $podName := .targetRef.name }}{{ range $node := $.items }}{{ if and (eq .kind "Node") (eq .metadata.name $nodeName) }}{{ range $_ := .status.addresses }}{{ if eq .type "ExternalIP" }}{{ .address }} {{ $podName }}.customredpandadomain.local{{ "\n" }}{{ end }}{{ end }}{{ end }}{{ end }}{{ end }}{{ end }}{{ end }}' | envsubst | sudo tee -a /etc/hosts ``` `/etc/hosts` 203.0.113.3 redpanda-0.customredpandadomain.local 203.0.113.5 redpanda-1.customredpandadomain.local 203.0.113.7 redpanda-2.customredpandadomain.local 2. Save the root certificate authority (CA) to your local file system outside Kubernetes: ```bash kubectl --namespace get secret redpanda-external-root-certificate -o go-template='{{ index .data "ca.crt" | base64decode }}' > ca.crt ``` 3. Install `rpk` on your local machine, not on a Pod: ### Linux > 💡 **TIP** > > You can use `rpk` on Windows only with [WSL](https://learn.microsoft.com/windows/wsl/install). However, commands that require Redpanda to be installed on your machine are not supported, such as [`rpk container`](../../../../reference/rpk/rpk-container/rpk-container/) commands, [`rpk iotune`](../../../../reference/rpk/rpk-iotune/), and [`rpk redpanda`](../../../../reference/rpk/rpk-redpanda/rpk-redpanda/) commands. #### amd64 ```bash curl -LO https://github.com/redpanda-data/redpanda/releases/latest/download/rpk-linux-amd64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-linux-amd64.zip -d ~/.local/bin/ ``` #### arm64 ```bash curl -LO https://github.com/redpanda-data/redpanda/releases/latest/download/rpk-linux-arm64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-linux-arm64.zip -d ~/.local/bin/ ``` ### macOS 1. If you don’t have Homebrew installed, [install it](https://brew.sh/). 2. To install or update `rpk`, run: ```bash brew install redpanda-data/tap/redpanda ``` 4. Configure `rpk` to connect to your cluster using the [pre-configured profile](../../../../manage/kubernetes/networking/k-connect-to-redpanda/#rpk-profile): ```bash rpk profile create --from-profile <(kubectl get configmap --namespace redpanda-rpk -o go-template='{{ .data.profile }}') ``` Replace `` with the name that you want to give this `rpk` profile. 5. Test the connection: ```bash rpk cluster info -X user=redpanda-twitch-account -X pass=changethispassword -X sasl.mechanism=SCRAM-SHA-256 ``` ## [](#explore-the-default-kubernetes-components)Explore the default Kubernetes components By default, the Redpanda Helm chart deploys the following Kubernetes components: - [A StatefulSet](#statefulset) with three Pods. - [One PersistentVolumeClaim](#persistentvolumeclaim) for each Pod, each with a capacity of 20Gi. - [A headless ClusterIP Service and a NodePort Service](#service) for each Kubernetes node that runs a Redpanda broker. - [Self-Signed TLS Certificates](#tls-certificates). ### [](#statefulset)StatefulSet Redpanda is a stateful application. Each Redpanda broker needs to store its own state (topic partitions) in its own storage volume. As a result, the Helm chart deploys a StatefulSet to manage the Pods in which the Redpanda brokers are running. ```bash kubectl get statefulset --namespace ``` Example output: NAME READY AGE redpanda 3/3 3m11s StatefulSets ensure that the state associated with a particular Pod replica is always the same, no matter how often the Pod is recreated. Each Pod is also given a unique ordinal number in its name such as `redpanda-0`. A Pod with a particular ordinal number is always associated with a PersistentVolumeClaim with the same number. When a Pod in the StatefulSet is deleted and recreated, it is given the same ordinal number and so it mounts the same storage volume as the deleted Pod that it replaced. ```bash kubectl get pod --namespace ``` Expected output: ```none NAME READY STATUS RESTARTS AGE redpanda-0 1/1 Running 0 6m9s redpanda-1 1/1 Running 0 6m9s redpanda-2 1/1 Running 0 6m9s redpanda-console-5ff45cdb9b-6z2vs 1/1 Running 0 5m redpanda-configuration-smqv7 0/1 Completed 0 6m9s ``` > 📝 **NOTE** > > The `redpanda-configuration` job updates the Redpanda runtime configuration. ### [](#persistentvolumeclaim)PersistentVolumeClaim Redpanda brokers must be able to store their data on disk. By default, the Helm chart uses the default StorageClass in the Kubernetes cluster to create a PersistentVolumeClaim for each Pod. The default StorageClass in your Kubernetes cluster depends on the Kubernetes platform that you are using. ```bash kubectl get persistentvolumeclaims --namespace ``` Expected output: ```none NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE datadir-redpanda-0 Bound pvc-3311ade3-de84-4027-80c6-3d8347302962 20Gi RWO standard 75s datadir-redpanda-1 Bound pvc-4ea8bc03-89a6-41e4-b985-99f074995f08 20Gi RWO standard 75s datadir-redpanda-2 Bound pvc-45c3555f-43bc-48c2-b209-c284c8091c45 20Gi RWO standard 75s ``` ### [](#service)Service The clients writing to or reading from a given partition have to connect directly to the leader broker that hosts the partition. As a result, clients need to be able to connect directly to each Pod. To allow internal and external clients to connect to each Pod that hosts a Redpanda broker, the Helm chart configures two Services: - Internal using the [Headless ClusterIP](#headless-clusterip-service) - External using the [NodePort](#nodeport-service) ```bash kubectl get service --namespace ``` Expected output: ```none NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE redpanda ClusterIP None 5m37s redpanda-console ClusterIP 10.0.251.204 8080 5m redpanda-external NodePort 10.96.137.220 9644:31644/TCP,9094:31092/TCP,8083:30082/TCP,8080:30081/TCP 5m37s ``` #### [](#headless-clusterip-service)Headless ClusterIP Service The headless Service associated with a StatefulSet gives the Pods their network identity in the form of a fully qualified domain name (FQDN). Both Redpanda brokers in the same Redpanda cluster and clients within the same Kubernetes cluster use this FQDN to communicate with each other. An important requirement of distributed applications such as Redpanda is peer discovery: The ability for each broker to find other brokers in the same cluster. When each Pod is rolled out, its `seed_servers` field is updated with the FQDN of each Pod in the cluster so that they can discover each other. ```bash kubectl --namespace exec redpanda-0 -c redpanda -- cat etc/redpanda/redpanda.yaml ``` ```yaml redpanda: data_directory: /var/lib/redpanda/data empty_seed_starts_cluster: false seed_servers: - host: address: redpanda-0.redpanda..svc.cluster.local. port: 33145 - host: address: redpanda-1.redpanda..svc.cluster.local. port: 33145 - host: address: redpanda-2.redpanda..svc.cluster.local. port: 33145 ``` #### [](#nodeport-service)NodePort Service External access is made available by a NodePort service that opens the following ports by default: | Listener | Node Port | Container Port | | --- | --- | --- | | Schema Registry | 30081 | 8081 | | HTTP Proxy | 30082 | 8083 | | Kafka API | 31092 | 9094 | | Admin API | 31644 | 9644 | To learn more, see [Networking and Connectivity in Kubernetes](../../../../manage/kubernetes/networking/k-networking-and-connectivity/). ### [](#tls-certificates)TLS Certificates By default, TLS is enabled in the Redpanda Helm chart. The Helm chart uses [cert-manager](https://cert-manager.io/docs/) to generate four Certificate resources that provide Redpanda with self-signed certificates for internal and external connections. Having separate certificates for internal and external connections provides security isolation. If an external certificate or its corresponding private key is compromised, it doesn’t affect the security of internal communications. ```bash kubectl get certificate --namespace ``` NAME READY redpanda-default-cert True redpanda-default-root-certificate True redpanda-external-cert True redpanda-external-root-certificate True - `redpanda-default-cert`: Self-signed certificate for internal communications. - `redpanda-default-root-certificate`: Root certificate authority for the internal certificate. - `redpanda-external-cert`: Self-signed certificate for external communications. - `redpanda-external-root-certificate`: Root certificate authority for the external certificate. By default, all listeners are configured with the same certificate. To configure separate TLS certificates for different listeners, see [TLS for Redpanda in Kubernetes](../../../../manage/kubernetes/security/tls/). > 📝 **NOTE** > > The Redpanda Helm chart provides self-signed certificates for convenience. In a production environment, it’s best to use certificates from a trusted Certificate Authority (CA) or integrate with your existing CA infrastructure. ## [](#uninstall-redpanda)Uninstall Redpanda When you finish testing Redpanda, you can uninstall it from your Kubernetes cluster. The steps depend on how you installed Redpanda: using the Redpanda Operator or the Redpanda Helm chart. ### Operator Follow the steps in **exact order** to avoid race conditions between the Redpanda Operator’s reconciliation loop and Kubernetes garbage collection. 1. Delete all Redpanda-related custom resources: ```bash kubectl delete users --namespace --all kubectl delete topics --namespace --all kubectl delete schemas --namespace --all kubectl delete redpanda --namespace --all ``` 2. Make sure requests for those resources return no results. For example, if you had a Redpanda cluster named `redpanda` in the namespace ``, run: ```bash kubectl get redpanda --namespace ``` 3. Uninstall the Redpanda Operator Helm release: ```bash helm uninstall redpanda-controller --namespace ``` Helm does not uninstall CRDs by default when using `helm uninstall` to avoid accidentally deleting existing custom resources. 4. Remove the CRDs. 1. List all Redpanda CRDs installed by the operator: ```bash kubectl api-resources --api-group='cluster.redpanda.com' ``` This command displays all CRDs defined by the Redpanda Operator. For example: ```bash NAME SHORTNAMES APIVERSION NAMESPACED KIND redpandas rp cluster.redpanda.com/v1alpha2 true Redpanda schemas sc cluster.redpanda.com/v1alpha2 true Schema topics cluster.redpanda.com/v1alpha2 true Topic users rpu cluster.redpanda.com/v1alpha2 true User ``` 2. Delete the CRDs: ```bash kubectl get crds -o name | grep cluster.redpanda.com | xargs kubectl delete ``` This command lists all CRDs with the `cluster.redpanda.com` domain suffix and deletes them, ensuring only Redpanda CRDs are removed. Helm does not delete CRDs automatically to prevent data loss, so you must run this step manually. 5. (Optional) Delete any leftover PVCs or Secrets in the namespace: > ⚠️ **CAUTION** > > The following command deletes all PVCs and Secrets in the namespace, which may remove unrelated resources if the namespace is shared with other applications. ```bash kubectl delete pvc,secret --all --namespace ``` ### Helm If you deployed Redpanda with the Redpanda Helm chart, follow these steps to uninstall it: 1. Uninstall the Helm release: ```bash helm uninstall redpanda --namespace ``` 2. (Optional) Delete any leftover PVCs or Secrets in the namespace: > ⚠️ **CAUTION** > > The following command deletes all PVCs and Secrets in the namespace, which may remove unrelated resources if the namespace is shared with other applications. ```bash kubectl delete pvc,secret --all --namespace ``` ## [](#delete-the-cluster)Delete the cluster To delete your Kubernetes cluster: ```bash eksctl delete cluster --name ``` To remove the convenience alias created during the quickstart: ```bash unalias internal-rpk ``` ## [](#troubleshoot)Troubleshoot Before troubleshooting your cluster, make sure that you have all the [prerequisites](#prerequisites). ### [](#helm-v3-18-0-is-not-supported-json-number-error)Helm v3.18.0 is not supported (json.Number error) If you are using Helm v3.18.0, you may encounter errors such as: Error: INSTALLATION FAILED: execution error at (redpanda/templates/entry-point.yaml:17:4): invalid Quantity expected string or float64 got: json.Number (1) This is due to a bug in Helm v3.18.0. To avoid similar errors, upgrade to a later version. For more details, see the [Helm GitHub issue](https://github.com/helm/helm/issues/30880). === StatefulSet never rolls out If the StatefulSet Pods remain in a pending state, they are waiting for resources to become available. To identify the Pods that are pending, use the following command: ```bash kubectl get pod --namespace ``` The response includes a list of Pods in the StatefulSet and their status. To view logs for a specific Pod, use the following command. ```bash kubectl logs -f --namespace ``` You can use the output to debug your deployment. ### [](#didnt-match-pod-anti-affinity-rules)Didn’t match pod anti-affinity rules If you see this error, your cluster does not have enough nodes to satisfy the anti-affinity rules: Warning FailedScheduling 18m default-scheduler 0/1 nodes are available: 1 node(s) didn't match pod anti-affinity rules. preemption: 0/1 nodes are available: 1 No preemption victims found for incoming pod. The Helm chart configures default `podAntiAffinity` rules to make sure that only one Pod running a Redpanda broker is scheduled on each worker node. To learn why, see [Number of workers](../k-requirements/#number-of-workers). To resolve this issue, do one of the following: - Create additional worker nodes. - Modify the anti-affinity rules (for development purposes only). If adding nodes is not an option, you can modify the `podAntiAffinity` rules in your StatefulSet to be less strict. #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: statefulset: podAntiAffinity: type: soft ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `docker-repo.yaml` ```yaml statefulset: podAntiAffinity: type: soft ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values docker-repo.yaml ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set statefulset.podAntiAffinity.type=soft ``` ### [](#unable-to-mount-volume)Unable to mount volume If you see volume mounting errors in the Pod events or in the Redpanda logs, ensure that each of your Pods has a volume available in which to store data. - If you’re using StorageClasses with dynamic provisioners (default), ensure they exist: ```bash kubectl get storageclass ``` - If you’re using PersistentVolumes, ensure that you have one PersistentVolume available for each Redpanda broker, and that each one has the storage capacity that’s set in `storage.persistentVolume.size`: ```bash kubectl get persistentvolume --namespace ``` To learn how to configure different storage volumes, see [Configure Storage](../../../../manage/kubernetes/storage/k-configure-storage/). ### [](#failed-to-pull-image)Failed to pull image When deploying the Redpanda Helm chart, you may encounter Docker rate limit issues because the default registry URL is not recognized as a Docker Hub URL. The domain `docker.redpanda.com` is used for statistical purposes, such as tracking the number of downloads. It mirrors Docker Hub’s content while providing specific analytics for Redpanda. Failed to pull image "docker.redpanda.com/redpandadata/redpanda:v": rpc error: code = Unknown desc = failed to pull and unpack image "docker.redpanda.com/redpandadata/redpanda:v": failed to copy: httpReadSeeker: failed open: unexpected status code 429 Too Many Requests - Server message: toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit To fix this error, do one of the following: - Replace the `image.repository` value in the Helm chart with `docker.io/redpandadata/redpanda`. Switching to Docker Hub avoids the rate limit issues associated with `docker.redpanda.com`. #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: image: repository: docker.io/redpandadata/redpanda ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `docker-repo.yaml` ```yaml image: repository: docker.io/redpandadata/redpanda ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values docker-repo.yaml ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set image.repository=docker.io/redpandadata/redpanda ``` - Authenticate to Docker Hub by logging in with your Docker Hub credentials. The `docker.redpanda.com` site acts as a reflector for Docker Hub. As a result, when you log in with your Docker Hub credentials, you will bypass the rate limit issues. ### [](#dig-not-defined)Dig not defined This error means that you are using an unsupported version of [Helm](https://helm.sh/docs/intro/install/): Error: parse error at (redpanda/templates/statefulset.yaml:203): function "dig" not defined To fix this error, ensure that you are using the minimum required version: 3.10.0. ```bash helm version ``` ### [](#repository-name-already-exists)Repository name already exists If you see this error, remove the `redpanda` chart repository, then try installing it again. ```bash helm repo remove redpanda helm repo add redpanda https://charts.redpanda.com helm repo update ``` ### [](#fatal-error-during-checker-data-directory-is-writable-execution)Fatal error during checker "Data directory is writable" execution This error appears when Redpanda does not have write access to your configured storage volume under `storage` in the Helm chart. Error: fatal error during checker "Data directory is writable" execution: open /var/lib/redpanda/data/test\_file: permission denied To fix this error, set `statefulset.initContainers.setDataDirOwnership.enabled` to `true` so that the initContainer can set the correct permissions on the data directories. ### [](#cannot-patch-redpanda-with-kind-statefulset)Cannot patch "redpanda" with kind StatefulSet This error appears when you run `helm upgrade` with the `--values` flag but do not include all your previous overrides. Error: UPGRADE FAILED: cannot patch "redpanda" with kind StatefulSet: StatefulSet.apps "redpanda" is invalid: spec: Forbidden: updates to statefulset spec for fields other than 'replicas', 'template', 'updateStrategy', 'persistentVolumeClaimRetentionPolicy' and 'minReadySeconds' are forbidden To fix this error, include all the value overrides from the previous installation using either the `--set` or the `--values` flags. > ⚠️ **WARNING** > > Do not use the `--reuse-values` flag to upgrade from one version of the Helm chart to another. This flag stops Helm from using any new values in the upgraded chart. ### [](#cannot-patch-redpanda-console-with-kind-deployment)Cannot patch "redpanda-console" with kind Deployment This error appears if you try to upgrade your deployment and you already have `console.enabled` set to `true`. Error: UPGRADE FAILED: cannot patch "redpanda-console" with kind Deployment: Deployment.apps "redpanda-console" is invalid: spec.selector: Invalid value: v1.LabelSelector{MatchLabels:map\[string\]string{"app.kubernetes.io/instance":"redpanda", "app.kubernetes.io/name":"console"}, MatchExpressions:\[\]v1.LabelSelectorRequirement(nil)}: field is immutable To fix this error, set `console.enabled` to `false` so that Helm doesn’t try to deploy Redpanda Console again. ### [](#helm-is-in-a-pending-rollback-state)Helm is in a pending-rollback state An interrupted Helm upgrade process can leave your Helm release in a `pending-rollback` state. This state prevents further actions like upgrades, rollbacks, or deletions through standard Helm commands. To fix this: 1. Identify the Helm release that’s in a `pending-rollback` state: ```bash helm list --namespace --all ``` Look for releases with a status of `pending-rollback`. These are the ones that need intervention. 2. Verify the Secret’s status to avoid affecting the wrong resource: ```bash kubectl --namespace get secret --show-labels ``` Identify the Secret associated with your Helm release by its `pending-rollback` status in the labels. > ⚠️ **WARNING** > > Ensure you have correctly identified the Secret to avoid unintended consequences. Deleting the wrong Secret could impact other deployments or services. 3. Delete the Secret to clear the `pending-rollback` state: ```bash kubectl --namespace delete secret -l status=pending-rollback ``` After clearing the `pending-rollback` state: - **Retry the upgrade**: Restart the upgrade process. You should investigate the initial failure to avoid getting into the `pending-rollback` state again. - **Perform a rollback**: If you need to roll back to a previous release, use `helm rollback ` to revert to a specific, stable release version. ### [](#crash-loop-backoffs)Crash loop backoffs If a broker crashes after startup, or gets stuck in a crash loop, it can accumulate an increasing amount of stored state. This accumulated state not only consumes additional disk space but also prolongs the time required for each subsequent restart to process it. To prevent infinite crash loops, the Redpanda Helm chart sets the [`crash_loop_limit`](../../../../reference/properties/broker-properties/#crash_loop_limit) broker configuration property to `5`. The crash loop limit is the number of consecutive crashes that can happen within one hour of each other. By default, the broker terminates immediately after hitting the `crash_loop_limit`. The Pod running Redpanda remains in a `CrashLoopBackoff` state until its internal consecutive crash counter is reset to zero. To facilitate debugging in environments where a broker is stuck in a crash loop, you can also set the [`crash_loop_sleep_sec`](../../../../reference/properties/broker-properties/#crash_loop_sleep_sec) broker configuration property. This setting determines how long the broker sleeps before terminating the process after reaching the crash loop limit. By providing a window during which the Pod remains available, you can SSH into it and troubleshoot the issue. Example configuration: ```yaml config: node: crash_loop_limit: 5 crash_loop_sleep_sec: 60 ``` In this example, when the broker hits the `crash_loop_limit` of 5, it will sleep for 60 seconds before terminating the process. This delay allows administrators to access the Pod and troubleshoot. To troubleshoot a crash loop backoff: 1. Check the Redpanda logs from the most recent crashes: ```bash kubectl logs --namespace ``` > 📝 **NOTE** > > Kubernetes retains logs only for the current and the previous instance of a container. This limitation makes it difficult to access logs from earlier crashes, which may contain vital clues about the root cause of the issue. Given these log retention limitations, setting up a centralized logging system is crucial. Systems such as [Loki](https://grafana.com/docs/loki/latest/) or [Datadog](https://www.datadoghq.com/product/log-management/) can capture and store logs from all containers, ensuring you have access to historical data. 2. Resolve the issue that led to the crash loop backoff. 3. Reset the crash counter to zero to allow Redpanda to restart. You can do any of the following to reset the counter: - Make changes to any of the following sections in the Redpanda Helm chart to trigger an update: - `config.node` - `config.tunable` For example: ```yaml config: node: crash_loop_limit: ``` - Delete the `startup_log` file in the broker’s data directory. ```bash kubectl exec --namespace -- rm /var/lib/redpanda/data/startup_log ``` > 📝 **NOTE** > > It might be challenging to execute this command within a Pod that is in a `CrashLoopBackoff` state due to the limited time during which the Pod is available before it restarts. Wrapping the command in a loop might work. - Wait one hour since the last crash. The crash counter resets after one hour. To avoid future crash loop backoffs and manage the accumulation of small segments effectively: - [Monitor](../../../../manage/kubernetes/monitoring/k-monitor-redpanda/) the size and number of segments regularly. - Optimize your Redpanda configuration for segment management. - Consider implementing [Tiered Storage](../../../../manage/kubernetes/tiered-storage/k-tiered-storage/) to manage data more efficiently. ### [](#a-redpanda-enterprise-edition-license-is-required)A Redpanda Enterprise Edition license is required During a Redpanda upgrade, if enterprise features are enabled and a valid Enterprise Edition license is missing, Redpanda logs a warning and aborts the upgrade process on the first broker. This issue prevents a successful upgrade. A Redpanda Enterprise Edition license is required to use the currently enabled features. To apply your license, downgrade this broker to the pre-upgrade version and provide a valid license key via rpk using 'rpk cluster license set ', or via Redpanda Console. To request an enterprise license, please visit . To try Redpanda Enterprise for 30 days, visit . For more information, see . If you encounter this message, follow these steps to recover: 1. [Roll back the affected broker to the original version](../../../../upgrade/k-rolling-upgrade/#roll-back). 2. Do one of the following: - [Apply a valid Redpanda Enterprise Edition license](../../../../get-started/licensing/add-license-redpanda/) to the cluster. - Disable enterprise features. If you do not have a valid license and want to proceed without using enterprise features, you can disable the enterprise features in your Redpanda configuration. 3. Retry the upgrade. For more troubleshooting steps, see [Troubleshoot Redpanda in Kubernetes](../../../../troubleshoot/errors-solutions/k-resolve-errors/). ## [](#next-steps)Next steps - [Try an example in Redpanda Labs](../../../../../redpanda-labs/) - [Learn more about Redpanda Console](../../../../manage/console/) - [Learn more about rpk](../../../../get-started/rpk-install/) > 💡 **TIP** > > When you’re ready to use a registered domain, make sure to remove your entries from the `/etc/hosts` file, and see [Configure External Access through a NodePort Service](../../../../manage/kubernetes/networking/external/k-nodeport/#use-the-default-redpanda-subdomains). ## [](#suggested-reading)Suggested reading - [Networking and Connectivity in Kubernetes](../../../../manage/kubernetes/networking/k-networking-and-connectivity/) - [Configure TLS for Redpanda in Kubernetes](../../../../manage/kubernetes/security/tls/) - [Configure SASL for Redpanda in Kubernetes](../../../../manage/kubernetes/security/authentication/k-authentication/) - [Redpanda Helm Specification](../../../../reference/k-redpanda-helm-spec/) - [Redpanda CRD Reference](../../../../reference/k-crd/) - [Redpanda Console README](https://github.com/redpanda-data/console) on GitHub ## Suggested labs - [Disaster Recovery with Envoy and Shadowing](/redpanda-labs/docker-compose/envoy-shadowing/) - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Stream Jira Issues to Redpanda for Real-Time Metrics](/redpanda-labs/docker-compose/jira-metrics-pipeline/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Set Up GitOps for the Redpanda Helm Chart](/redpanda-labs/kubernetes/gitops-helm/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) - [Set Up MySQL CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-mysql-json/) - [Set Up Postgres CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-postgres-json/) See more [Search all labs](/redpanda-labs) --- # Page 37: Get Started with Redpanda in Kubernetes **URL**: https://docs.redpanda.com/current/deploy/redpanda/kubernetes/get-started-dev.md --- # Get Started with Redpanda in Kubernetes --- title: Get Started with Redpanda in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: redpanda/kubernetes/get-started-dev page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: redpanda/kubernetes/get-started-dev.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/redpanda/kubernetes/get-started-dev.adoc description: Find guides for setting up a three-broker Redpanda cluster in different Kubernetes platforms. page-git-created-date: "2025-08-15" page-git-modified-date: "2025-08-15" support-status: supported --- For end-to-end guides on secure deployments of Redpanda on managed Kubernetes services, see: - [Azure Kubernetes Service](../aks-guide/) (AKS) - [Elastic Kubernetes Service](../eks-guide/) (EKS) - [Google Kubernetes Engine](../gke-guide/) (GKE) - [Local (kind or minikube)](../local-guide/) Or, if you’re ready to go into production, see the [production deployment workflow](../k-production-workflow/). ## [](#suggested-reading)Suggested reading - [Getting started with Redpanda in Kubernetes](https://redpanda.com/blog/manage-clusters-k8s-streaming-data) ## Suggested labs - [Set Up GitOps for the Redpanda Helm Chart](/redpanda-labs/kubernetes/gitops-helm/) [Search all labs](/redpanda-labs) --- # Page 38: Deploy a Redpanda Cluster in Google Kubernetes Engine **URL**: https://docs.redpanda.com/current/deploy/redpanda/kubernetes/gke-guide.md --- # Deploy a Redpanda Cluster in Google Kubernetes Engine --- title: Deploy a Redpanda Cluster in Google Kubernetes Engine latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: redpanda/kubernetes/gke-guide page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: redpanda/kubernetes/gke-guide.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/redpanda/kubernetes/gke-guide.adoc description: Deploy a secure Redpanda cluster and Redpanda Console in Google Kubernetes Engine (GKE). page-git-created-date: "2025-08-15" page-git-modified-date: "2025-08-15" support-status: supported --- Deploy a secure Redpanda cluster and Redpanda Console in Google Kubernetes Engine (GKE). Then, use `rpk` both as an internal client and an external client to interact with your Redpanda cluster from the command line. Your Redpanda cluster has the following security features: - SASL for authenticating users' connections. - TLS with self-signed certificates for secure communication between the cluster and clients. ## [](#prerequisites)Prerequisites - Complete the 'Before you begin' steps and the 'Launch Cloud Shell' steps of the [GKE quickstart](https://cloud.google.com/kubernetes-engine/docs/deploy-app-cluster#before-you-begin). Cloud Shell comes preinstalled with the Google Cloud CLI, the `kubectl` command-line tool, and the Helm package manager. - Ensure [`kubectl`](https://kubernetes.io/docs/tasks/tools/) is installed. Minimum required Kubernetes version: 1.27.0-0. ```bash kubectl version --client ``` - Ensure [Helm](https://helm.sh/docs/intro/install/) is installed. Minimum required Helm version: 3.10.0 ```bash helm version ``` ## [](#create-a-gke-cluster)Create a GKE cluster Your GKE cluster must have one worker node available for each Redpanda broker that you plan to deploy in your Redpanda cluster. You also need to run the worker nodes on a machine type that supports the [requirements and recommendations](../k-requirements/) for production deployments. In this step, you create a GKE cluster with three nodes on [`c2d-standard-8` machine types](https://cloud.google.com/compute/docs/compute-optimized-machines#c2d_series). Deploying three nodes allows your GKE cluster to support a Redpanda cluster with three brokers. The `c2d-standard-8` instance type comes with: - 2 cores per worker node, which is a requirement for production. - Local NVMe disks, which is recommended for best performance. Create a GKE cluster. Replace the `` placeholder with your own region. ```bash gcloud container clusters create \ --machine-type c2d-standard-8 \ --num-nodes=3 \ --local-nvme-ssd-block count=2 \ --region= ``` > ❗ **IMPORTANT** > > Do not enable [node auto-upgrades](https://cloud.google.com/kubernetes-engine/docs/how-to/node-auto-upgrades) (`--enable-autoupgrade`) on Google GKE clusters running Redpanda. > > Node auto-upgrades can trigger automatic reboots or node upgrades that disrupt Redpanda brokers, risking data loss or cluster instability. Redpanda requires manual control over node lifecycle events. > > For more details, see the [requirements and recommendations](../k-requirements/#node-updates) for deploying Redpanda in Kubernetes. To see all options that you can specify when creating a cluster, see the [Cloud SDK reference](https://cloud.google.com/sdk/gcloud/reference/container/clusters/create). Or, for help creating a GKE cluster, see the [GKE documentation](https://cloud.google.com/kubernetes-engine/docs/deploy-app-cluster#create_cluster). ### [](#create-sc)Create a StorageClass for your local NVMe disks When you provisioned the Kubernetes cluster, you selected an instance type that comes with local NVMe disks. However, these disks are not automatically mounted or formatted upon creation. To use these local NVMe disks, you must mount and format them, and you must create the necessary PersistentVolumes (PVs). To automate this process, you can use a Container Storage Interface (CSI) driver. In this step, you install the recommended [local volume manager (LVM) CSI driver](https://github.com/metal-stack/csi-driver-lvm). Then, you create a StorageClass that references the LVM CSI driver and specifies the recommended XFS file system. 1. Install the LVM CSI driver: ```yaml helm repo add metal-stack https://helm.metal-stack.io helm repo update helm install csi-driver-lvm metal-stack/csi-driver-lvm \ --version 0.6.0 \ --namespace csi-driver-lvm \ --create-namespace \ --set lvm.devicePattern='/dev/nvme[0-9]n[0-9]' ``` The `lvm.devicePattern` property specifies the pattern that the CSI driver uses to identify available NVMe volumes on your worker nodes. > 📝 **NOTE** > > Version 0.6.0 is required to avoid volume-mounting issues caused by recent `mkfs.xfs` updates. Newer versions enable the `-i nrext64=1` option, triggering the following error on default GKE kernels: > > XFS (dm-0): Superblock has unknown incompatible features (0x20) enabled. 2. Create the StorageClass: `csi-driver-lvm-striped-xfs.yaml` ```yaml apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: csi-driver-lvm-striped-xfs provisioner: lvm.csi.metal-stack.io reclaimPolicy: Retain volumeBindingMode: WaitForFirstConsumer allowVolumeExpansion: true parameters: type: "striped" csi.storage.k8s.io/fstype: xfs mkfsParams: "-i nrext64=0" ``` - `provisioner`: The LVM CSI driver responsible for provisioning the volume. - `reclaimPolicy`: The `Retain` policy ensures that the underlying volume is not deleted when the corresponding PVC is deleted. - `volumeBindingMode`: The `WaitForFirstConsumer` mode delays the binding and provisioning of a PersistentVolume until a Pod that uses the PVC is created. This mode is important for ensuring that the PV is created on the same node where the Pod will run because the PV will use the node’s local NVMe volumes. - `allowVolumeExpansion`: Allows the volume to be expanded after it has been provisioned. - `parameters.type`: Combines multiple physical volumes to create a single logical volume. In a striped setup, data is spread across the physical volumes in a way that distributes the I/O load evenly, improving performance by allowing parallel disk I/O operations. - `parameters.csi.storage.k8s.io/fstype`: Formats the volumes with the XFS file system. Redpanda Data recommends XFS for its enhanced performance with Redpanda workloads. - `parameters.mkfsParams`: Disables the nrext64 feature to ensure compatibility with older kernels. 3. Apply the StorageClass: ```bash kubectl apply -f csi-driver-lvm-striped-xfs.yaml ``` After applying this StorageClass, any PVC that references it will attempt to provision storage using the LVM CSI driver and the provided parameters. ### [](#configure-external-access)Configure external access Add inbound firewall rules to your instances so that external traffic can reach the following node ports on all Kubernetes worker nodes in the cluster: - 31644 - 31092 - 30082 - 30081 For help creating firewall rules, see the [Google VPC documentation](https://cloud.google.com/vpc/docs/using-firewalls). ## [](#deploy-redpanda-and-redpanda-console)Deploy Redpanda and Redpanda Console In this step, you deploy Redpanda with SASL authentication and self-signed TLS certificates. Redpanda Console is included as a subchart in the Redpanda Helm chart. ### Operator 1. Make sure that you have permission to install custom resource definitions (CRDs): ```bash kubectl auth can-i create CustomResourceDefinition --all-namespaces ``` You should see `yes` in the output. You need these cluster-level permissions to install [cert-manager](https://cert-manager.io/docs/) and Redpanda Operator CRDs in the next steps. 2. Install [cert-manager](https://cert-manager.io/docs/installation/helm/) using Helm: ```bash helm repo add jetstack https://charts.jetstack.io helm repo update helm install cert-manager jetstack/cert-manager \ --set crds.enabled=true \ --namespace cert-manager \ --create-namespace ``` The Redpanda Helm chart uses cert-manager to enable TLS and manage TLS certificates by default. 3. Deploy the Redpanda Operator: 1. To deploy in cluster scope, use: ```bash helm repo add redpanda https://charts.redpanda.com helm repo update helm upgrade --install redpanda-controller redpanda/operator \ --namespace \ --create-namespace \ --version v26.1.2 \ (1) --set crds.enabled=true (2) ``` | 1 | This flag specifies the exact version of the Redpanda Operator Helm chart to use for deployment. By setting this value, you pin the chart to a specific version, which prevents automatic updates that might introduce breaking changes or new features that have not been tested in your environment. | | --- | --- | | 2 | This flag ensures that the CRDs are installed as part of the Redpanda Operator deployment.This command deploys the Redpanda Operator in cluster scope (default in v25.2+), allowing it to manage Redpanda clusters across multiple namespaces. | 2. To deploy in namespace scope (managing only resources within its deployment namespace), use: ```bash helm upgrade --install redpanda-controller redpanda/operator \ --namespace \ --create-namespace \ --version v26.1.2 \ --set crds.enabled=true \ --set 'additionalCmdFlags=["--namespace="]' (1) ``` | 1 | This flag restricts the Redpanda Operator to manage resources only within the specified namespace. | | --- | --- | 4. Ensure that the Deployment is successfully rolled out: ```bash kubectl --namespace rollout status --watch deployment/redpanda-controller-operator ``` deployment "redpanda-controller-operator" successfully rolled out 5. Install a [Redpanda custom resource](../../../../reference/k-crd/) in the same namespace as the Redpanda Operator: `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: clusterSpec: image: tag: v26.1.3 external: domain: customredpandadomain.local auth: sasl: enabled: true users: - name: superuser password: secretpassword storage: persistentVolume: enabled: true storageClass: csi-driver-lvm-striped-xfs ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` - `image.tag`: Deploys the latest version of Redpanda. - `external.domain`: The custom domain that each broker will advertise to clients externally. This domain is added to the internal and external TLS certificates so that you can connect to the cluster using this domain. - `auth.sasl.name`: Creates a superuser called `superuser` that can grant permissions to new users in your cluster using access control lists (ACLs). - `storage.persistentVolume.storageClass`: Points each PVC associated with the Redpanda brokers to the `csi-driver-lvm-striped-xfs` StorageClass. This StorageClass allows the LVM CSI driver to provision the appropriate local PersistentVolumes backed by NVMe disks for each Redpanda broker. 6. Wait for the Redpanda Operator to deploy Redpanda using the Helm chart: ```bash kubectl get redpanda --namespace --watch ``` NAME READY STATUS redpanda True Redpanda reconciliation succeeded This step may take a few minutes. You can watch for new Pods to make sure that the deployment is progressing: ```bash kubectl get pod --namespace ``` If it’s taking too long, see [Troubleshoot](#troubleshoot). ### Helm 1. Install cert-manager using Helm: ```bash helm repo add jetstack https://charts.jetstack.io helm repo update helm install cert-manager jetstack/cert-manager \ --set crds.enabled=true \ --namespace cert-manager \ --create-namespace ``` TLS is enabled by default. The Redpanda Helm chart uses cert-manager to manage TLS certificates by default. 2. Install Redpanda with SASL enabled: ```bash helm repo add redpanda https://charts.redpanda.com helm repo update helm install redpanda redpanda/redpanda \ --version 26.1.2 \ --namespace --create-namespace \ --set image.tag=v26.1.3 \ --set auth.sasl.enabled=true \ --set "auth.sasl.users[0].name=superuser" \ --set "auth.sasl.users[0].password=secretpassword" \ --set external.domain=customredpandadomain.local \ --set "storage.persistentVolume.storageClass=csi-driver-lvm-striped-xfs" \ --wait \ --timeout 1h ``` - `image.tag`: Deploys the latest version of Redpanda. - `external.domain`: The custom domain that each broker advertises to clients externally. This domain is added to the internal and external TLS certificates so that you can connect to the cluster using this domain. - `auth.sasl.name`: Creates a superuser called `superuser` that can grant permissions to new users in your cluster using access control lists (ACLs). - `storage.persistentVolume.storageClass`: Points each PVC associated with the Redpanda brokers to the `csi-driver-lvm-striped-xfs` StorageClass. This StorageClass allows the LVM CSI driver to provision the appropriate local PersistentVolumes backed by NVMe disks for each Redpanda broker. The installation displays some tips for getting started. If the installation is taking a long time, see [Troubleshoot](#troubleshoot). ## [](#verify-the-deployment)Verify the deployment When the Redpanda Helm chart is deployed, you should have: - Three Redpanda brokers. Each Redpanda broker runs inside a separate Pod and is scheduled on a separate worker node. - One PVC bound to a PV for each Redpanda broker. These PVs are what the Redpanda brokers use to store the Redpanda data directory with all your topics and metadata. 1. Verify that each Redpanda broker is scheduled on only one Kubernetes node: ```bash kubectl get pod --namespace \ -o=custom-columns=NODE:.spec.nodeName,POD_NAME:.metadata.name -l \ app.kubernetes.io/component=redpanda-statefulset ``` Example output: NODE POD\_NAME example-worker3 redpanda-0 example-worker2 redpanda-1 example-worker redpanda-2 2. Verify that each Redpanda broker has a bound PVC: ```bash kubectl get persistentvolumeclaim \ --namespace \ -o custom-columns=NAME:.metadata.name,STATUS:.status.phase,STORAGECLASS:.spec.storageClassName ``` Example output: NAME STATUS STORAGECLASS datadir-redpanda-0 Bound csi-driver-lvm-striped-xfs datadir-redpanda-1 Bound csi-driver-lvm-striped-xfs datadir-redpanda-2 Bound csi-driver-lvm-striped-xfs ## [](#create-a-user)Create a user In this step, you use `rpk` to create a new user. Then, you authenticate to Redpanda with the superuser to grant permissions to the new user. You’ll authenticate to Redpanda with this new user to create a topic in the next steps. > 💡 **TIP** > > As a security best practice, you should use the superuser only to grant permissions to new users through ACLs. Never delete the superuser. You need the superuser to grant permissions to new users. 1. Create a new user called `redpanda-twitch-account` with the password `changethispassword`: ```bash kubectl --namespace exec -ti redpanda-0 -c redpanda -- \ rpk security user create redpanda-twitch-account \ -p changethispassword ``` Example output: Created user "redpanda-twitch-account". 2. Use the superuser to grant the `redpanda-twitch-account` user permission to execute all operations only for a topic called `twitch-chat`. ```bash kubectl exec --namespace -c redpanda redpanda-0 -- \ rpk security acl create --allow-principal User:redpanda-twitch-account \ --operation all \ --topic twitch-chat \ -X user=superuser -X pass=secretpassword -X sasl.mechanism=SCRAM-SHA-512 ``` Example output: PRINCIPAL RESOURCE-TYPE RESOURCE-NAME OPERATION PERMISSION User:redpanda TOPIC twitch-chat ALL ALLOW ## [](#start-streaming)Start streaming In this step, you authenticate to Redpanda with the `redpanda-twitch-account` user to create a topic called `twitch-chat`. This topic is the only one that the `redpanda-twitch-account` user has permission to access. Then, you produce messages to the topic, and consume messages from it. 1. Create an alias to simplify the `rpk` commands: ```bash alias internal-rpk="kubectl --namespace exec -i -t redpanda-0 -c redpanda -- rpk -X user=redpanda-twitch-account -X pass=changethispassword -X sasl.mechanism=SCRAM-SHA-256" ``` 2. Create a topic called `twitch-chat`: ### Operator 1. Create a Secret in which to store your user’s password: ```bash kubectl create secret generic redpanda-secret --from-literal=password='changethispassword' --namespace ``` 2. Create a [Topic resource](../../../../manage/kubernetes/k-manage-topics/): `topic.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Topic metadata: name: twitch-chat spec: kafkaApiSpec: brokers: - "redpanda-0.redpanda..svc.cluster.local:9093" - "redpanda-1.redpanda..svc.cluster.local:9093" - "redpanda-2.redpanda..svc.cluster.local:9093" tls: caCertSecretRef: name: "redpanda-default-cert" key: "ca.crt" sasl: username: redpanda-twitch-account mechanism: SCRAM-SHA-256 passwordSecretRef: name: redpanda-secret key: password ``` 3. Apply the Topic resource in the same namespace as your Redpanda cluster: ```bash kubectl apply -f topic.yaml --namespace ``` 4. Check the logs of the Redpanda Operator to confirm that the topic was created: ```bash kubectl logs -l app.kubernetes.io/name=operator -c manager --namespace ``` You should see that the Redpanda Operator reconciled the Topic resource. For example: Example output ```json { "level":"info", "ts":"2023-09-25T16:20:09.538Z", "logger":"TopicReconciler.Reconcile", "msg":"Starting reconcile loop", "controller":"topic", "controllerGroup":"cluster.redpanda.com", "controllerKind":"Topic", "Topic": { "name":"twitch-chat", "namespace":"" }, "namespace":"", "name":"twitch-chat", "reconcileID":"c0cf9abc-a553-48b7-9b6e-2de3cdfb4432" } { "level":"info", "ts":"2023-09-25T16:20:09.581Z", "logger":"TopicReconciler.Reconcile", "msg":"reconciliation finished in 43.436125ms, next run in 3s", "controller":"topic", "controllerGroup":"cluster.redpanda.com", "controllerKind":"Topic", "Topic": { "name":"twitch-chat", "namespace":"" }, "namespace":"", "name":"twitch-chat", "reconcileID":"c0cf9abc-a553-48b7-9b6e-2de3cdfb4432", "result": { "Requeue":false, "RequeueAfter":3000000000 } } ``` ### Helm ```bash internal-rpk topic create twitch-chat ``` Example output: TOPIC STATUS twitch-chat OK 3. Describe the topic: ```bash internal-rpk topic describe twitch-chat ``` Expected output: ```none SUMMARY ======= NAME twitch-chat PARTITIONS 1 REPLICAS 1 CONFIGS ======= KEY VALUE SOURCE cleanup.policy delete DYNAMIC_TOPIC_CONFIG compression.type producer DEFAULT_CONFIG message.timestamp.type CreateTime DEFAULT_CONFIG partition_count 1 DYNAMIC_TOPIC_CONFIG redpanda.datapolicy function_name: script_name: DEFAULT_CONFIG redpanda.remote.read false DEFAULT_CONFIG redpanda.remote.write false DEFAULT_CONFIG replication_factor 1 DYNAMIC_TOPIC_CONFIG retention.bytes -1 DEFAULT_CONFIG retention.ms 604800000 DEFAULT_CONFIG segment.bytes 1073741824 DEFAULT_CONFIG ``` 4. Produce a message to the topic: ```bash internal-rpk topic produce twitch-chat ``` 5. Type a message, then press Enter: Pandas are fabulous! Example output: Produced to partition 0 at offset 0 with timestamp 1663282629789. 6. Press Ctrl+C to finish producing messages to the topic. 7. Consume one message from the topic: ```bash internal-rpk topic consume twitch-chat --num 1 ``` Expected output: ```none { "topic": "twitch-chat", "value": "Pandas are fabulous!", "timestamp": 1663282629789, "partition": 0, "offset": 0 } ``` ## [](#explore-your-topic-in-redpanda-console)Explore your topic in Redpanda Console Redpanda Console is a developer-friendly web UI for managing and debugging your Redpanda cluster and your applications. In this step, you use port-forwarding to access Redpanda Console on your local network. > 💡 **TIP** > > Because you’re using the Community Edition of Redpanda Console, you should not expose Redpanda Console outside your local network. The Community Edition of Redpanda Console does not provide authentication, and it connects to the Redpanda cluster as superuser. To use the Enterprise Edition, you need a license key. See [Redpanda Licensing](../../../../get-started/licensing/). 1. Expose Redpanda Console to your localhost: ```bash kubectl --namespace port-forward svc/redpanda-console 8080:8080 ``` The `kubectl port-forward` command actively runs in the command-line window. To execute other commands while the command is running, open another command-line window. 2. Open Redpanda Console on [http://localhost:8080](http://localhost:8080). All your Redpanda brokers are listed along with their IP addresses and IDs. 3. Go to **Topics** > **twitch-chat**. The message that you produced to the topic is displayed along with some other details about the topic. 4. Press Ctrl+C in the command-line to stop the port-forwarding process. ## [](#configure-external-access-to-redpanda)Configure external access to Redpanda If you want to connect to the Redpanda cluster with external clients, Redpanda brokers must advertise an externally accessible address that external clients can connect to. External clients are common in Internet of Things (IoT) environments, or if you use external services that do not implement VPC peering in your network. When you created the cluster, you set the `external.domain` configuration to `customredpandadomain.local`, which means that your Redpanda brokers are advertising the following addresses: - `redpanda-0.customredpandadomain.local` - `redpanda-1.customredpandadomain.local` - `redpanda-2.customredpandadomain.local` To access your Redpanda brokers externally, you can map your worker nodes' IP addresses to these domains. > ⚠️ **CAUTION** > > IP addresses can change. If the IP addresses of your worker nodes change, you must update your `/etc/hosts` file with the new mappings. > > In a production environment, it’s a best practice to use ExternalDNS to manage DNS records for your brokers. See [Use ExternalDNS for external access](../k-requirements/#use-externaldns-for-external-access). 1. Add mappings in your `/etc/hosts` file between your worker nodes' IP addresses and their custom domain names: ```bash sudo true && kubectl --namespace get endpoints,node -A -o go-template='{{ range $_ := .items }}{{ if and (eq .kind "Endpoints") (eq .metadata.name "redpanda-external") }}{{ range $_ := (index .subsets 0).addresses }}{{ $nodeName := .nodeName }}{{ $podName := .targetRef.name }}{{ range $node := $.items }}{{ if and (eq .kind "Node") (eq .metadata.name $nodeName) }}{{ range $_ := .status.addresses }}{{ if eq .type "ExternalIP" }}{{ .address }} {{ $podName }}.customredpandadomain.local{{ "\n" }}{{ end }}{{ end }}{{ end }}{{ end }}{{ end }}{{ end }}{{ end }}' | envsubst | sudo tee -a /etc/hosts ``` `/etc/hosts` 203.0.113.3 redpanda-0.customredpandadomain.local 203.0.113.5 redpanda-1.customredpandadomain.local 203.0.113.7 redpanda-2.customredpandadomain.local 2. Save the root certificate authority (CA) to your local file system outside Kubernetes: ```bash kubectl --namespace get secret redpanda-external-root-certificate -o go-template='{{ index .data "ca.crt" | base64decode }}' > ca.crt ``` 3. Install `rpk` on your local machine, not on a Pod: ### Linux > 💡 **TIP** > > You can use `rpk` on Windows only with [WSL](https://learn.microsoft.com/windows/wsl/install). However, commands that require Redpanda to be installed on your machine are not supported, such as [`rpk container`](../../../../reference/rpk/rpk-container/rpk-container/) commands, [`rpk iotune`](../../../../reference/rpk/rpk-iotune/), and [`rpk redpanda`](../../../../reference/rpk/rpk-redpanda/rpk-redpanda/) commands. #### amd64 ```bash curl -LO https://github.com/redpanda-data/redpanda/releases/latest/download/rpk-linux-amd64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-linux-amd64.zip -d ~/.local/bin/ ``` #### arm64 ```bash curl -LO https://github.com/redpanda-data/redpanda/releases/latest/download/rpk-linux-arm64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-linux-arm64.zip -d ~/.local/bin/ ``` ### macOS 1. If you don’t have Homebrew installed, [install it](https://brew.sh/). 2. To install or update `rpk`, run: ```bash brew install redpanda-data/tap/redpanda ``` 4. Configure `rpk` to connect to your cluster using the [pre-configured profile](../../../../manage/kubernetes/networking/k-connect-to-redpanda/#rpk-profile): ```bash rpk profile create --from-profile <(kubectl get configmap --namespace redpanda-rpk -o go-template='{{ .data.profile }}') ``` Replace `` with the name that you want to give this `rpk` profile. 5. Test the connection: ```bash rpk cluster info -X user=redpanda-twitch-account -X pass=changethispassword -X sasl.mechanism=SCRAM-SHA-256 ``` ## [](#explore-the-default-kubernetes-components)Explore the default Kubernetes components By default, the Redpanda Helm chart deploys the following Kubernetes components: - [A StatefulSet](#statefulset) with three Pods. - [One PersistentVolumeClaim](#persistentvolumeclaim) for each Pod, each with a capacity of 20Gi. - [A headless ClusterIP Service and a NodePort Service](#service) for each Kubernetes node that runs a Redpanda broker. - [Self-Signed TLS Certificates](#tls-certificates). ### [](#statefulset)StatefulSet Redpanda is a stateful application. Each Redpanda broker needs to store its own state (topic partitions) in its own storage volume. As a result, the Helm chart deploys a StatefulSet to manage the Pods in which the Redpanda brokers are running. ```bash kubectl get statefulset --namespace ``` Example output: NAME READY AGE redpanda 3/3 3m11s StatefulSets ensure that the state associated with a particular Pod replica is always the same, no matter how often the Pod is recreated. Each Pod is also given a unique ordinal number in its name such as `redpanda-0`. A Pod with a particular ordinal number is always associated with a PersistentVolumeClaim with the same number. When a Pod in the StatefulSet is deleted and recreated, it is given the same ordinal number and so it mounts the same storage volume as the deleted Pod that it replaced. ```bash kubectl get pod --namespace ``` Expected output: ```none NAME READY STATUS RESTARTS AGE redpanda-0 1/1 Running 0 6m9s redpanda-1 1/1 Running 0 6m9s redpanda-2 1/1 Running 0 6m9s redpanda-console-5ff45cdb9b-6z2vs 1/1 Running 0 5m redpanda-configuration-smqv7 0/1 Completed 0 6m9s ``` > 📝 **NOTE** > > The `redpanda-configuration` job updates the Redpanda runtime configuration. ### [](#persistentvolumeclaim)PersistentVolumeClaim Redpanda brokers must be able to store their data on disk. By default, the Helm chart uses the default StorageClass in the Kubernetes cluster to create a PersistentVolumeClaim for each Pod. The default StorageClass in your Kubernetes cluster depends on the Kubernetes platform that you are using. ```bash kubectl get persistentvolumeclaims --namespace ``` Expected output: ```none NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE datadir-redpanda-0 Bound pvc-3311ade3-de84-4027-80c6-3d8347302962 20Gi RWO standard 75s datadir-redpanda-1 Bound pvc-4ea8bc03-89a6-41e4-b985-99f074995f08 20Gi RWO standard 75s datadir-redpanda-2 Bound pvc-45c3555f-43bc-48c2-b209-c284c8091c45 20Gi RWO standard 75s ``` ### [](#service)Service The clients writing to or reading from a given partition have to connect directly to the leader broker that hosts the partition. As a result, clients need to be able to connect directly to each Pod. To allow internal and external clients to connect to each Pod that hosts a Redpanda broker, the Helm chart configures two Services: - Internal using the [Headless ClusterIP](#headless-clusterip-service) - External using the [NodePort](#nodeport-service) ```bash kubectl get service --namespace ``` Expected output: ```none NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE redpanda ClusterIP None 5m37s redpanda-console ClusterIP 10.0.251.204 8080 5m redpanda-external NodePort 10.96.137.220 9644:31644/TCP,9094:31092/TCP,8083:30082/TCP,8080:30081/TCP 5m37s ``` #### [](#headless-clusterip-service)Headless ClusterIP Service The headless Service associated with a StatefulSet gives the Pods their network identity in the form of a fully qualified domain name (FQDN). Both Redpanda brokers in the same Redpanda cluster and clients within the same Kubernetes cluster use this FQDN to communicate with each other. An important requirement of distributed applications such as Redpanda is peer discovery: The ability for each broker to find other brokers in the same cluster. When each Pod is rolled out, its `seed_servers` field is updated with the FQDN of each Pod in the cluster so that they can discover each other. ```bash kubectl --namespace exec redpanda-0 -c redpanda -- cat etc/redpanda/redpanda.yaml ``` ```yaml redpanda: data_directory: /var/lib/redpanda/data empty_seed_starts_cluster: false seed_servers: - host: address: redpanda-0.redpanda..svc.cluster.local. port: 33145 - host: address: redpanda-1.redpanda..svc.cluster.local. port: 33145 - host: address: redpanda-2.redpanda..svc.cluster.local. port: 33145 ``` #### [](#nodeport-service)NodePort Service External access is made available by a NodePort service that opens the following ports by default: | Listener | Node Port | Container Port | | --- | --- | --- | | Schema Registry | 30081 | 8081 | | HTTP Proxy | 30082 | 8083 | | Kafka API | 31092 | 9094 | | Admin API | 31644 | 9644 | To learn more, see [Networking and Connectivity in Kubernetes](../../../../manage/kubernetes/networking/k-networking-and-connectivity/). ### [](#tls-certificates)TLS Certificates By default, TLS is enabled in the Redpanda Helm chart. The Helm chart uses [cert-manager](https://cert-manager.io/docs/) to generate four Certificate resources that provide Redpanda with self-signed certificates for internal and external connections. Having separate certificates for internal and external connections provides security isolation. If an external certificate or its corresponding private key is compromised, it doesn’t affect the security of internal communications. ```bash kubectl get certificate --namespace ``` NAME READY redpanda-default-cert True redpanda-default-root-certificate True redpanda-external-cert True redpanda-external-root-certificate True - `redpanda-default-cert`: Self-signed certificate for internal communications. - `redpanda-default-root-certificate`: Root certificate authority for the internal certificate. - `redpanda-external-cert`: Self-signed certificate for external communications. - `redpanda-external-root-certificate`: Root certificate authority for the external certificate. By default, all listeners are configured with the same certificate. To configure separate TLS certificates for different listeners, see [TLS for Redpanda in Kubernetes](../../../../manage/kubernetes/security/tls/). > 📝 **NOTE** > > The Redpanda Helm chart provides self-signed certificates for convenience. In a production environment, it’s best to use certificates from a trusted Certificate Authority (CA) or integrate with your existing CA infrastructure. ## [](#uninstall-redpanda)Uninstall Redpanda When you finish testing Redpanda, you can uninstall it from your Kubernetes cluster. The steps depend on how you installed Redpanda: using the Redpanda Operator or the Redpanda Helm chart. ### Operator Follow the steps in **exact order** to avoid race conditions between the Redpanda Operator’s reconciliation loop and Kubernetes garbage collection. 1. Delete all Redpanda-related custom resources: ```bash kubectl delete users --namespace --all kubectl delete topics --namespace --all kubectl delete schemas --namespace --all kubectl delete redpanda --namespace --all ``` 2. Make sure requests for those resources return no results. For example, if you had a Redpanda cluster named `redpanda` in the namespace ``, run: ```bash kubectl get redpanda --namespace ``` 3. Uninstall the Redpanda Operator Helm release: ```bash helm uninstall redpanda-controller --namespace ``` Helm does not uninstall CRDs by default when using `helm uninstall` to avoid accidentally deleting existing custom resources. 4. Remove the CRDs. 1. List all Redpanda CRDs installed by the operator: ```bash kubectl api-resources --api-group='cluster.redpanda.com' ``` This command displays all CRDs defined by the Redpanda Operator. For example: ```bash NAME SHORTNAMES APIVERSION NAMESPACED KIND redpandas rp cluster.redpanda.com/v1alpha2 true Redpanda schemas sc cluster.redpanda.com/v1alpha2 true Schema topics cluster.redpanda.com/v1alpha2 true Topic users rpu cluster.redpanda.com/v1alpha2 true User ``` 2. Delete the CRDs: ```bash kubectl get crds -o name | grep cluster.redpanda.com | xargs kubectl delete ``` This command lists all CRDs with the `cluster.redpanda.com` domain suffix and deletes them, ensuring only Redpanda CRDs are removed. Helm does not delete CRDs automatically to prevent data loss, so you must run this step manually. 5. (Optional) Delete any leftover PVCs or Secrets in the namespace: > ⚠️ **CAUTION** > > The following command deletes all PVCs and Secrets in the namespace, which may remove unrelated resources if the namespace is shared with other applications. ```bash kubectl delete pvc,secret --all --namespace ``` ### Helm If you deployed Redpanda with the Redpanda Helm chart, follow these steps to uninstall it: 1. Uninstall the Helm release: ```bash helm uninstall redpanda --namespace ``` 2. (Optional) Delete any leftover PVCs or Secrets in the namespace: > ⚠️ **CAUTION** > > The following command deletes all PVCs and Secrets in the namespace, which may remove unrelated resources if the namespace is shared with other applications. ```bash kubectl delete pvc,secret --all --namespace ``` ## [](#delete-the-cluster)Delete the cluster To delete your Kubernetes cluster: ```bash gcloud container clusters delete \ --region= ``` ## [](#troubleshoot)Troubleshoot Before troubleshooting your cluster, make sure that you have all the [prerequisites](#prerequisites). ### [](#helm-v3-18-0-is-not-supported-json-number-error)Helm v3.18.0 is not supported (json.Number error) If you are using Helm v3.18.0, you may encounter errors such as: Error: INSTALLATION FAILED: execution error at (redpanda/templates/entry-point.yaml:17:4): invalid Quantity expected string or float64 got: json.Number (1) This is due to a bug in Helm v3.18.0. To avoid similar errors, upgrade to a later version. For more details, see the [Helm GitHub issue](https://github.com/helm/helm/issues/30880). === StatefulSet never rolls out If the StatefulSet Pods remain in a pending state, they are waiting for resources to become available. To identify the Pods that are pending, use the following command: ```bash kubectl get pod --namespace ``` The response includes a list of Pods in the StatefulSet and their status. To view logs for a specific Pod, use the following command. ```bash kubectl logs -f --namespace ``` You can use the output to debug your deployment. ### [](#didnt-match-pod-anti-affinity-rules)Didn’t match pod anti-affinity rules If you see this error, your cluster does not have enough nodes to satisfy the anti-affinity rules: Warning FailedScheduling 18m default-scheduler 0/1 nodes are available: 1 node(s) didn't match pod anti-affinity rules. preemption: 0/1 nodes are available: 1 No preemption victims found for incoming pod. The Helm chart configures default `podAntiAffinity` rules to make sure that only one Pod running a Redpanda broker is scheduled on each worker node. To learn why, see [Number of workers](../k-requirements/#number-of-workers). To resolve this issue, do one of the following: - Create additional worker nodes. - Modify the anti-affinity rules (for development purposes only). If adding nodes is not an option, you can modify the `podAntiAffinity` rules in your StatefulSet to be less strict. #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: statefulset: podAntiAffinity: type: soft ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `docker-repo.yaml` ```yaml statefulset: podAntiAffinity: type: soft ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values docker-repo.yaml ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set statefulset.podAntiAffinity.type=soft ``` ### [](#unable-to-mount-volume)Unable to mount volume If you see volume mounting errors in the Pod events or in the Redpanda logs, ensure that each of your Pods has a volume available in which to store data. - If you’re using StorageClasses with dynamic provisioners (default), ensure they exist: ```bash kubectl get storageclass ``` - If you’re using PersistentVolumes, ensure that you have one PersistentVolume available for each Redpanda broker, and that each one has the storage capacity that’s set in `storage.persistentVolume.size`: ```bash kubectl get persistentvolume --namespace ``` To learn how to configure different storage volumes, see [Configure Storage](../../../../manage/kubernetes/storage/k-configure-storage/). ### [](#failed-to-pull-image)Failed to pull image When deploying the Redpanda Helm chart, you may encounter Docker rate limit issues because the default registry URL is not recognized as a Docker Hub URL. The domain `docker.redpanda.com` is used for statistical purposes, such as tracking the number of downloads. It mirrors Docker Hub’s content while providing specific analytics for Redpanda. Failed to pull image "docker.redpanda.com/redpandadata/redpanda:v": rpc error: code = Unknown desc = failed to pull and unpack image "docker.redpanda.com/redpandadata/redpanda:v": failed to copy: httpReadSeeker: failed open: unexpected status code 429 Too Many Requests - Server message: toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit To fix this error, do one of the following: - Replace the `image.repository` value in the Helm chart with `docker.io/redpandadata/redpanda`. Switching to Docker Hub avoids the rate limit issues associated with `docker.redpanda.com`. #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: image: repository: docker.io/redpandadata/redpanda ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `docker-repo.yaml` ```yaml image: repository: docker.io/redpandadata/redpanda ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values docker-repo.yaml ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set image.repository=docker.io/redpandadata/redpanda ``` - Authenticate to Docker Hub by logging in with your Docker Hub credentials. The `docker.redpanda.com` site acts as a reflector for Docker Hub. As a result, when you log in with your Docker Hub credentials, you will bypass the rate limit issues. ### [](#dig-not-defined)Dig not defined This error means that you are using an unsupported version of [Helm](https://helm.sh/docs/intro/install/): Error: parse error at (redpanda/templates/statefulset.yaml:203): function "dig" not defined To fix this error, ensure that you are using the minimum required version: 3.10.0. ```bash helm version ``` ### [](#repository-name-already-exists)Repository name already exists If you see this error, remove the `redpanda` chart repository, then try installing it again. ```bash helm repo remove redpanda helm repo add redpanda https://charts.redpanda.com helm repo update ``` ### [](#fatal-error-during-checker-data-directory-is-writable-execution)Fatal error during checker "Data directory is writable" execution This error appears when Redpanda does not have write access to your configured storage volume under `storage` in the Helm chart. Error: fatal error during checker "Data directory is writable" execution: open /var/lib/redpanda/data/test\_file: permission denied To fix this error, set `statefulset.initContainers.setDataDirOwnership.enabled` to `true` so that the initContainer can set the correct permissions on the data directories. ### [](#cannot-patch-redpanda-with-kind-statefulset)Cannot patch "redpanda" with kind StatefulSet This error appears when you run `helm upgrade` with the `--values` flag but do not include all your previous overrides. Error: UPGRADE FAILED: cannot patch "redpanda" with kind StatefulSet: StatefulSet.apps "redpanda" is invalid: spec: Forbidden: updates to statefulset spec for fields other than 'replicas', 'template', 'updateStrategy', 'persistentVolumeClaimRetentionPolicy' and 'minReadySeconds' are forbidden To fix this error, include all the value overrides from the previous installation using either the `--set` or the `--values` flags. > ⚠️ **WARNING** > > Do not use the `--reuse-values` flag to upgrade from one version of the Helm chart to another. This flag stops Helm from using any new values in the upgraded chart. ### [](#cannot-patch-redpanda-console-with-kind-deployment)Cannot patch "redpanda-console" with kind Deployment This error appears if you try to upgrade your deployment and you already have `console.enabled` set to `true`. Error: UPGRADE FAILED: cannot patch "redpanda-console" with kind Deployment: Deployment.apps "redpanda-console" is invalid: spec.selector: Invalid value: v1.LabelSelector{MatchLabels:map\[string\]string{"app.kubernetes.io/instance":"redpanda", "app.kubernetes.io/name":"console"}, MatchExpressions:\[\]v1.LabelSelectorRequirement(nil)}: field is immutable To fix this error, set `console.enabled` to `false` so that Helm doesn’t try to deploy Redpanda Console again. ### [](#helm-is-in-a-pending-rollback-state)Helm is in a pending-rollback state An interrupted Helm upgrade process can leave your Helm release in a `pending-rollback` state. This state prevents further actions like upgrades, rollbacks, or deletions through standard Helm commands. To fix this: 1. Identify the Helm release that’s in a `pending-rollback` state: ```bash helm list --namespace --all ``` Look for releases with a status of `pending-rollback`. These are the ones that need intervention. 2. Verify the Secret’s status to avoid affecting the wrong resource: ```bash kubectl --namespace get secret --show-labels ``` Identify the Secret associated with your Helm release by its `pending-rollback` status in the labels. > ⚠️ **WARNING** > > Ensure you have correctly identified the Secret to avoid unintended consequences. Deleting the wrong Secret could impact other deployments or services. 3. Delete the Secret to clear the `pending-rollback` state: ```bash kubectl --namespace delete secret -l status=pending-rollback ``` After clearing the `pending-rollback` state: - **Retry the upgrade**: Restart the upgrade process. You should investigate the initial failure to avoid getting into the `pending-rollback` state again. - **Perform a rollback**: If you need to roll back to a previous release, use `helm rollback ` to revert to a specific, stable release version. ### [](#crash-loop-backoffs)Crash loop backoffs If a broker crashes after startup, or gets stuck in a crash loop, it can accumulate an increasing amount of stored state. This accumulated state not only consumes additional disk space but also prolongs the time required for each subsequent restart to process it. To prevent infinite crash loops, the Redpanda Helm chart sets the [`crash_loop_limit`](../../../../reference/properties/broker-properties/#crash_loop_limit) broker configuration property to `5`. The crash loop limit is the number of consecutive crashes that can happen within one hour of each other. By default, the broker terminates immediately after hitting the `crash_loop_limit`. The Pod running Redpanda remains in a `CrashLoopBackoff` state until its internal consecutive crash counter is reset to zero. To facilitate debugging in environments where a broker is stuck in a crash loop, you can also set the [`crash_loop_sleep_sec`](../../../../reference/properties/broker-properties/#crash_loop_sleep_sec) broker configuration property. This setting determines how long the broker sleeps before terminating the process after reaching the crash loop limit. By providing a window during which the Pod remains available, you can SSH into it and troubleshoot the issue. Example configuration: ```yaml config: node: crash_loop_limit: 5 crash_loop_sleep_sec: 60 ``` In this example, when the broker hits the `crash_loop_limit` of 5, it will sleep for 60 seconds before terminating the process. This delay allows administrators to access the Pod and troubleshoot. To troubleshoot a crash loop backoff: 1. Check the Redpanda logs from the most recent crashes: ```bash kubectl logs --namespace ``` > 📝 **NOTE** > > Kubernetes retains logs only for the current and the previous instance of a container. This limitation makes it difficult to access logs from earlier crashes, which may contain vital clues about the root cause of the issue. Given these log retention limitations, setting up a centralized logging system is crucial. Systems such as [Loki](https://grafana.com/docs/loki/latest/) or [Datadog](https://www.datadoghq.com/product/log-management/) can capture and store logs from all containers, ensuring you have access to historical data. 2. Resolve the issue that led to the crash loop backoff. 3. Reset the crash counter to zero to allow Redpanda to restart. You can do any of the following to reset the counter: - Make changes to any of the following sections in the Redpanda Helm chart to trigger an update: - `config.node` - `config.tunable` For example: ```yaml config: node: crash_loop_limit: ``` - Delete the `startup_log` file in the broker’s data directory. ```bash kubectl exec --namespace -- rm /var/lib/redpanda/data/startup_log ``` > 📝 **NOTE** > > It might be challenging to execute this command within a Pod that is in a `CrashLoopBackoff` state due to the limited time during which the Pod is available before it restarts. Wrapping the command in a loop might work. - Wait one hour since the last crash. The crash counter resets after one hour. To avoid future crash loop backoffs and manage the accumulation of small segments effectively: - [Monitor](../../../../manage/kubernetes/monitoring/k-monitor-redpanda/) the size and number of segments regularly. - Optimize your Redpanda configuration for segment management. - Consider implementing [Tiered Storage](../../../../manage/kubernetes/tiered-storage/k-tiered-storage/) to manage data more efficiently. ### [](#a-redpanda-enterprise-edition-license-is-required)A Redpanda Enterprise Edition license is required During a Redpanda upgrade, if enterprise features are enabled and a valid Enterprise Edition license is missing, Redpanda logs a warning and aborts the upgrade process on the first broker. This issue prevents a successful upgrade. A Redpanda Enterprise Edition license is required to use the currently enabled features. To apply your license, downgrade this broker to the pre-upgrade version and provide a valid license key via rpk using 'rpk cluster license set ', or via Redpanda Console. To request an enterprise license, please visit . To try Redpanda Enterprise for 30 days, visit . For more information, see . If you encounter this message, follow these steps to recover: 1. [Roll back the affected broker to the original version](../../../../upgrade/k-rolling-upgrade/#roll-back). 2. Do one of the following: - [Apply a valid Redpanda Enterprise Edition license](../../../../get-started/licensing/add-license-redpanda/) to the cluster. - Disable enterprise features. If you do not have a valid license and want to proceed without using enterprise features, you can disable the enterprise features in your Redpanda configuration. 3. Retry the upgrade. For more troubleshooting steps, see [Troubleshoot Redpanda in Kubernetes](../../../../troubleshoot/errors-solutions/k-resolve-errors/). ## [](#next-steps)Next steps - [Try an example in Redpanda Labs](../../../../../redpanda-labs/) - [Learn more about Redpanda Console](../../../../manage/console/) - [Learn more about rpk](../../../../get-started/rpk-install/) > 💡 **TIP** > > When you’re ready to use a registered domain, make sure to remove your entries from the `/etc/hosts` file, and see [Configure External Access through a NodePort Service](../../../../manage/kubernetes/networking/external/k-nodeport/#use-the-default-redpanda-subdomains). ## [](#suggested-reading)Suggested reading - [Networking and Connectivity in Kubernetes](../../../../manage/kubernetes/networking/k-networking-and-connectivity/) - [Configure TLS for Redpanda in Kubernetes](../../../../manage/kubernetes/security/tls/) - [Configure SASL for Redpanda in Kubernetes](../../../../manage/kubernetes/security/authentication/k-authentication/) - [Redpanda Helm Specification](../../../../reference/k-redpanda-helm-spec/) - [Redpanda CRD Reference](../../../../reference/k-crd/) - [Redpanda Console README](https://github.com/redpanda-data/console) on GitHub ## Suggested labs - [Disaster Recovery with Envoy and Shadowing](/redpanda-labs/docker-compose/envoy-shadowing/) - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Stream Jira Issues to Redpanda for Real-Time Metrics](/redpanda-labs/docker-compose/jira-metrics-pipeline/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Set Up GitOps for the Redpanda Helm Chart](/redpanda-labs/kubernetes/gitops-helm/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) - [Set Up MySQL CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-mysql-json/) - [Set Up Postgres CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-postgres-json/) See more [Search all labs](/redpanda-labs) --- # Page 39: Redpanda in Kubernetes **URL**: https://docs.redpanda.com/current/deploy/redpanda/kubernetes/k-deployment-overview.md --- # Redpanda in Kubernetes --- title: Redpanda in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: redpanda/kubernetes/k-deployment-overview page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: redpanda/kubernetes/k-deployment-overview.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/redpanda/kubernetes/k-deployment-overview.adoc description: Learn about Redpanda in Kubernetes and the tools that are available. page-git-created-date: "2025-08-15" page-git-modified-date: "2025-12-04" support-status: supported --- Kubernetes is a container orchestration tool that helps you manage Redpanda deployments using declarative configuration files called _manifests_. Kubernetes provides a standardized way of achieving the following: - High availability - Disaster recovery - Scalability ## [](#deployment-tools)Deployment tools To deploy Redpanda in Kubernetes, you can choose between Helm for its simplicity or the Redpanda Operator for advanced lifecycle management. While Helm provides an easy way to install and upgrade Redpanda, it has limitations in managing complex, stateful workloads at scale. The Redpanda Operator is the recommended option for production deployments as it enables better upgrade management, dynamic configuration, and improved lifecycle automation. | Feature | Redpanda Operator | Helm | Description | | --- | --- | --- | --- | | Managed upgrade and rollback | ✅ | ⚠️ | Helm provides basic upgrades with rollback capabilities but requires manual intervention and increases operational risk. The Redpanda Operator automates safe, rolling upgrades with reconciliation, significantly reducing risk. | | Dynamic configuration | ✅ | ❌ | Helm configurations must be updated manually through Helm values and redeployment. The Redpanda Operator dynamically applies real-time configuration changes through custom resources (CRDs). | | Advanced health checks and metrics | ✅ | ⚠️ | Helm relies on standard Kubernetes-level health metrics, while the Redpanda Operator includes advanced, application-specific metrics and health checks. | | Lifecycle automation | ✅ | ⚠️ | Helm has limited automation and depends on manual management for scaling, failover, and cleanup. The Redpanda Operator automates scaling, failover, resource reconciliation, and cleanup tasks. | | Multi-tenancy management | ✅ | ⚠️ | Helm requires separate releases to manage multiple clusters, making management more complex. The Redpanda Operator simplifies multi-tenancy by managing clusters across different namespaces from a single operator instance. | > 💡 **TIP** > > If you are already using the Redpanda Helm chart and want to migrate to the latest Redpanda Operator for better lifecycle management, see [Migrate from the Redpanda Helm chart](../../../../migrate/kubernetes/helm-to-operator/). ### [](#helm-and-redpanda-operator)Redpanda Operator The Redpanda Operator is designed for production-grade Redpanda deployments, offering enhanced lifecycle management, automation, and GitOps compatibility. The Redpanda Operator defaults to cluster scope, enabling it to manage multiple Redpanda clusters across different namespaces from a single operator instance. The Redpanda Operator directly reconciles Redpanda resources, performing tasks such as installations, updates, and cleanup. ### [](#helm)Helm [Helm](https://helm.sh/docs) is a package manager for Kubernetes that simplifies defining, installing, and upgrading Kubernetes applications. Helm uses charts, a collection of files describing Kubernetes resources, to deploy applications in a Kubernetes cluster. The Redpanda Helm chart provides all the manifest files required to deploy Redpanda in Kubernetes, including: - A StatefulSet to manage Redpanda brokers - A Headless ClusterIP Service for internal communication with the Redpanda cluster - A NodePort Service for external communication with the Redpanda cluster ## [](#kubernetes-deployment-environments)Kubernetes deployment environments You can run Redpanda on managed Kubernetes services as well as in bare-metal environments. Managed Kubernetes services offer simpler deployment and maintenance, while bare-metal environments provide complete control and cost efficiencies. ### [](#managed-kubernetes)Managed Kubernetes Managed Kubernetes services, such as Google Kubernetes Engine (GKE) and Amazon Elastic Kubernetes Service (EKS), handle core components of a Kubernetes cluster, offering benefits such as: - **Ease of deployment**: Pre-configured instances join your Kubernetes cluster automatically. - **Control plane maintenance**: The provider maintains the control plane, ensuring security and reliability. - **Health monitoring and repairs**: The provider monitors master nodes and repairs them as needed. You remain responsible for deploying and maintaining Redpanda instances on worker nodes. > ❗ **IMPORTANT** > > Deploy Kubernetes clusters with **unmanaged (manual) node updates**. Managed (automatic) updates during cluster deployment can lead to service downtime, data loss, or quorum instability. Transitioning from managed updates to unmanaged updates after deployment may require downtime. To avoid these disruptions, plan for unmanaged node updates from the start. See [Kubernetes Cluster Requirements and Recommendations](../k-requirements/#node-updates). ### [](#bare-metal-kubernetes-environments)Bare-metal Kubernetes environments Bare-metal Kubernetes environments give you complete control over both the control plane and the worker nodes, which can be advantageous when you want the following: - **Complete control**: Bare-metal Kubernetes offers control over every aspect of deployment, suited for highly customized environments. - **Custom configurations**: You have granular control to fine-tune the Kubernetes setup. - **Cost efficiency**: Owning and operating your hardware may be more economical over time. ## [](#documentation-conventions)Documentation conventions This documentation follows conventions to help users easily identify Kubernetes resource types and Helm values: - **Resource names**: Kubernetes resource names, such as Service or PersistentVolume, are capitalized and in Pascal case to match the manifest files. - **Helm values**: Helm values, like `storage.persistentVolume.enabled`, are displayed in monospace font. ## [](#next-steps)Next steps - Get started - [Local Deployment Guide](../local-guide/) (kind and minikube) - [Azure Kubernetes Service Guide](../aks-guide/) (AKS) - [Elastic Kubernetes Service Guide](../eks-guide/) (EKS) - [Google Kubernetes Engine Guide](../gke-guide/) (GKE) - [Kubernetes Cluster Requirements and Recommendations](../k-requirements/) - [Production deployment workflow](../k-production-workflow/) ## [](#suggested-reading)Suggested reading - [Kubernetes operator documentation](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) - [Helm documentation](https://helm.sh/docs/intro/using_helm/) - [Redpanda Helm Specification](../../../../reference/k-redpanda-helm-spec/) - [Redpanda CRD Reference](../../../../reference/k-crd/) ## Suggested labs - [Set Up GitOps for the Redpanda Helm Chart](/redpanda-labs/kubernetes/gitops-helm/) [Search all labs](/redpanda-labs) --- # Page 40: High Availability in Kubernetes **URL**: https://docs.redpanda.com/current/deploy/redpanda/kubernetes/k-high-availability.md --- # High Availability in Kubernetes --- title: High Availability in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: redpanda/kubernetes/k-high-availability page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: redpanda/kubernetes/k-high-availability.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/redpanda/kubernetes/k-high-availability.adoc description: Explore high availability configurations of Redpanda in Kubernetes. page-git-created-date: "2025-08-15" page-git-modified-date: "2025-08-15" support-status: supported --- Redpanda is designed to ensure data integrity and high availability (HA), even at high-throughput levels. Kubernetes offers an ideal environment for managing and scaling Redpanda. By deploying Redpanda on Kubernetes, you can ensure HA through Kubernetes-native features, benefit from automated rollouts and rollbacks, and take advantage of the platform’s self-healing properties. ## [](#deployment-strategies)Deployment strategies Consider the following Redpanda deployment strategies for the most common types of failures. | Failure | Impact | Mitigation strategy | | --- | --- | --- | | Broker failure | Loss of function for an individual broker or for any virtual machine (VM) that hosts the broker | Multi-broker deployment | | Rack or switch failure | Loss of brokers/VMs hosted within that rack, or loss of connectivity to them | Multi-broker deployment spread across multiple racks or network failure domains | | Data center failure | Loss of brokers/VMs hosted within that data center, or loss of connectivity to them | Multi-AZ or replicated deployment | | Region failure | Loss of brokers/VMs hosted within that region, or loss of connectivity to them | Geo-stretch (latency dependent) or replicated deployment | | Global, systemic outage (DNS failures, routing failures) | Complete outage for all systems and services impacting customers and staff | Offline backups, replicas in 3rd-party domains | | Data loss or corruption (accidental or malicious) | Corrupt or unavailable data that also affects synchronous replicas | Offline backups | ## [](#ha-deployment-options)HA deployment options This section explains the trade-offs with different HA configurations. - [Multi-broker deployment](#multi-broker-deployment) - [Multi-AZ deployment](#multi-az-deployment) - [Multi-region deployment](#multi-region-deployment) - [Multi-cluster deployment](#multi-cluster-deployment) ### [](#multi-broker-deployment)Multi-broker deployment Redpanda is designed to be deployed in a cluster that consists of at least three brokers. Although clusters with a single broker are convenient for development and testing, they aren’t resilient to failure. Adding brokers to a cluster provides a way to handle individual broker failures. You can also use [\[rack awareness\]](#rack awareness) to assign brokers to different racks, which allows Redpanda to tolerate the loss of a rack or failure domain. By default, the Redpanda Helm chart deploys three Redpanda brokers in separate Pods that are all managed by a StatefulSet. If the Redpanda broker inside a Pod crashes, Kubernetes automatically restarts the Pod. The Redpanda Helm chart also uses `podAntiAffinity` rules to stop the Kubernetes scheduler from placing multiple Redpanda brokers on the same node. These rules offer two benefits: - To minimize the risk of data loss by ensuring that a node’s failure results in the loss of only one Redpanda broker. - To prevent resource contention between brokers by ensuring they are never co-located on the same node. ![Single-AZ deployment](../../../../shared/_images/single_az.png) See also: [Single-AZ deployments](#single-az-deployments) ### [](#multi-az-deployment)Multi-AZ deployment An availability zone (AZ) consists of one or more data centers served by high-bandwidth links with low latency (and typically within a close distance of one another). All AZs have discrete failure domains (power, cooling, fire, and network), but they also have common-cause failure domains, such as catastrophic events, that affect their geographical location. To safeguard against such possibilities, a cluster can be deployed across multiple AZs by configuring each AZ as a rack using rack awareness. Implementing Raft internally ensures that Redpanda can tolerate losing a minority of replicas for a given topic or for controller groups. For this to translate to a multi-AZ deployment, however, it’s necessary to deploy to at least three AZs (affording the loss of one zone). In a typical multi-AZ deployment, cluster performance is constrained by inter-AZ bandwidth and latency. See also: [Multi-AZ deployments](#multi-az-deployments) For greater resilience in Kubernetes: - Use [`nodeAffinity`](https://kubernetes.io/docs/tasks/configure-pod-container/assign-pods-nodes-using-node-affinity/) rules to control the placement of Pods based on node labels indicating zones or regions. Kubernetes provides a scheduling feature known as `nodeAffinity` that allows you to specify conditions on which a Pod can or cannot be scheduled based on the node labels. This is particularly useful for deploying workloads in a multi-zone or multi-region setup, ensuring high availability and resilience. - If you use the Redpanda Operator, deploy multiple instances of it across multiple AZs on multiple nodes. The Redpanda Operator has built-in leader election. When the leader (the active Redpanda Operator instance) fails or becomes unreachable, one of the other instances automatically takes over the leadership role, ensuring uninterrupted management of Redpanda instances. By distributing instances across multiple AZs, you protect against the failure of a whole availability zone. Even if one zone goes down, an instance from another zone can take over. ![Multi-AZ deployment](../../../../shared/_images/multi_az.png) See also: - [Redpanda Operator Helm chart](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values) - [Redpanda Helm chart](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values) ### [](#multi-region-deployment)Multi-region deployment A multi-region deployment is similar to a multi-AZ deployment, in that it needs at least three regions to counter the loss of a single region. Note that this deployment strategy increases latency due to the physical distance between regions. In addition to higher produce and end-to-end latency and increased costs, multi-region deployments require careful tuning. Redpanda recommends that you work closely with Redpanda’s Customer Success team when implementing a multi-region deployment. Also consider the following strategies to mitigate these challenges: - Configure [Leader Pinning](../../../../develop/produce-data/leader-pinning/) to ensure that topic partition leaders are geographically closer to clients. This can help lower network costs and latency by routing produce requests to brokers located in specific AZs. - If your produce latency exceeds your requirements, you can configure producers to have `acks=1` instead of `acks=all`. This reduces latency by only waiting for the leader to acknowledge, rather than waiting for all brokers to respond. However, using this configuration can decrease message durability. If the partition leader goes offline, you may lose any messages that are acknowledged but not yet replicated. ### [](#multi-cluster-deployment)Multi-cluster deployment In a multi-cluster deployment, each cluster is configured using one of the other HA deployments, along with standby clusters or [Remote Read Replica](../../../../manage/kubernetes/k-remote-read-replicas/) clusters in one or more remote locations. A standby cluster is a fully functional cluster that can handle producers and consumers. A remote read replica is a read-only cluster that can act as a backup for topics. To replicate data across clusters in a multi-cluster deployment, use one of the following options: - [MirrorMaker2 replication](../../../../migrate/data-migration/) - [Remote Read Replicas](../../../../manage/kubernetes/k-remote-read-replicas/) - [Redpanda Edge Agent](https://github.com/redpanda-data/redpanda-edge-agent) Alternatively, you could dual-feed clusters in multiple regions. Dual feeding is the process of having producers connect to your cluster across multiple regions. However, this introduces additional complexity onto the producing application. It also requires consumers that have sufficient deduplication logic built in to handle offsets, since they won’t be the same across each cluster. ## [](#ha-features-in-kubernetes)HA features in Kubernetes Kubernetes includes the following high-availability features: - **Automatic failovers**: Kubernetes has built-in controllers to detect Pod failures and recreate them, ensuring service continuity. - **Scaling**: Use Kubernetes Horizontal Pod Autoscaler (HPA) to scale Redpanda Pods based on metrics like CPU and memory usage. - **Network policies**: Use Kubernetes network policies to control the communication between Redpanda Pods, ensuring secure data transfer. ## [](#node-pools)Node pools If you use managed Kubernetes services such as Amazon EKS, consider creating dedicated node pools for your Redpanda deployment. These node pools can have machines optimized for the workload with high I/O capacity or more CPU and memory resources. Dedicated node pools ensure that Redpanda brokers do not compete for resources with other workloads in your Kubernetes cluster. This is particularly useful when you need to guarantee specific performance for your Redpanda deployment. Node pools are also beneficial during scaling operations. By having dedicated node pools, you can scale your Redpanda cluster without affecting other applications. ## [](#storage)Storage Data persistence and protection are crucial for high availability: - **Persistent Volume Claims (PVCs)**: By default, the Redpanda Helm chart uses the default StorageClass in your Kubernetes cluster to create one PVC for each Redpanda broker, ensuring data is stored persistently. These PVCs ensure that if a Pod is terminated or crashes, the data isn’t lost, and when a new Pod starts, it reattaches to the existing PVC. - **Storage Class**: The dynamic nature of Kubernetes deployments benefits from StorageClasses that automatically provision new PersistentVolumes (PVs) for each PVC. For Redpanda, choose a StorageClass that supports high I/O operations, especially if backed by high-performance NVMe storage. See also: - [Supported Volume Types for Data in Redpanda](../../../../manage/kubernetes/storage/k-volume-types/) - [Configure Storage for the Redpanda data directory in Kubernetes](../../../../manage/kubernetes/storage/k-configure-storage/) ## [](#ha-features-in-redpanda)HA features in Redpanda Redpanda includes the following high-availability features: - [Replica synchronization](#replica-synchronization) - [Rack awareness](#rack-awareness) - [Partition leadership](#partition-leadership) - [Producer acknowledgment](#producer-acknowledgment) - [Partition rebalancing](#partition-rebalancing) - [Tiered Storage and disaster recovery](#tiered-storage-and-disaster-recovery) ### [](#replica-synchronization)Replica synchronization A cluster’s availability is directly tied to replica synchronization. Brokers can be either leaders or replicas (followers) for a partition. A cluster’s replica brokers must be consistent with the leader to be available for consumers and producers. 1. The leader writes data to the disk. It then dispatches append entry requests to the followers in parallel with the disk flush. 2. The replicas receive messages written to the partition of the leader. They send acknowledgments to the leader after successfully replicating the message to their internal partition. 3. The leader sends an acknowledgment to the producer of the message, as determined by that producer’s `acks` value. Redpanda considers the group consistent after a majority has formed consensus; that is, a majority of participants acknowledged the write. While Apache Kafka® uses in-sync replicas, Redpanda uses a quorum-based majority with the Raft replication protocol. Kafka performance is negatively impacted when any "in-sync" replica is running slower than other replicas in the In-Sync Replica (ISR) set. Monitor the health of your cluster with the [`rpk cluster health`](../../../../reference/rpk/rpk-cluster/rpk-cluster-health/) command, which tells you if any brokers are down, and if you have any leaderless partitions. ### [](#rack-awareness)Rack awareness Rack awareness is one of the most important features for HA. It lets Redpanda spread partition replicas across available brokers in different failure zones. Rack awareness ensures that no more than a minority of replicas are placed on a single rack, even during cluster balancing. > 💡 **TIP** > > Make sure you assign separate rack IDs that actually correspond to a physical separation of brokers. See also: [Enable Rack Awareness](../../../../manage/kubernetes/k-rack-awareness/) ### [](#partition-leadership)Partition leadership Raft uses a heartbeat mechanism to maintain leadership authority and to trigger leader elections. The partition leader sends a periodic heartbeat to all followers to assert its leadership. If a follower does not receive a heartbeat over a period of time, then it triggers an election to choose a new partition leader. See also: [Partition leadership elections](../../../../get-started/architecture/#partition-leadership-elections) ### [](#producer-acknowledgment)Producer acknowledgment Producer acknowledgment defines how producer clients and broker leaders communicate their status while transferring data. The `acks` value determines producer and broker behavior when writing data to the event bus. See also: [Producer Acknowledgement Settings](../../../../develop/produce-data/configure-producers/) ### [](#partition-rebalancing)Partition rebalancing By default, Redpanda rebalances partition distribution when brokers are added or decommissioned. Continuous Data Balancing additionally rebalances partitions when brokers become unavailable or when disk space usage exceeds a threshold. See also: [Cluster Balancing](../../../../manage/cluster-maintenance/cluster-balancing/) ### [](#tiered-storage-and-disaster-recovery)Tiered Storage and disaster recovery In a disaster, your secondary cluster may still be available, but you need to quickly restore the original level of redundancy by bringing up a new primary cluster. In a containerized environment such as Kubernetes, all state is lost from pods that use only local storage. HA deployments with Tiered Storage address both these problems, since it offers long-term data retention and topic recovery. See also: [Tiered Storage](../../../../manage/kubernetes/tiered-storage/k-tiered-storage/) > ❗ **IMPORTANT** > > Tiered Storage operates as an asynchronous process and only applies to closed segments. Any open segments or segments existing only in local storage are not recoverable by your new primary cluster. ## [](#single-az-deployments)Single-AZ deployments When deploying a cluster for high availability into a single AZ or data center, you need to ensure that, within the AZ, single points of failure are minimized and that Redpanda is configured to be aware of any discrete failure domains within the AZ. This is achieved with Redpanda’s rack awareness, which deploys _n_ Redpanda brokers across three or more racks (or failure domains) within the AZ. Single-AZ deployments in the cloud have less network costs than multi-AZ deployments, and you can leverage resilient power supplies and networking infrastructure within the AZ to mitigate against all but total-AZ failure scenarios. You can balance the benefits of increased availability and fault tolerance against any increase in cost, performance, and complexity: - Cost: Redpanda operates the same Raft consensus algorithm whether it’s in HA mode or not. There may be infrastructure costs when deploying across multiple racks, but these are normally amortized across a wider datacenter operations program. - Performance: Spreading Redpanda replicas across racks and switches increases the number of network hops between Redpanda brokers; however, normal intra-data center network latency should be measured in microseconds rather than milliseconds. Ensure that there’s sufficient bandwidth between brokers to handle replication traffic. - Complexity: A benefit of Redpanda is the simplicity of deployment. Because Redpanda is deployed as a single binary with no external dependencies, it doesn’t need any infrastructure for ZooKeeper or for a Schema Registry. Redpanda also includes cluster balancing, so there’s no need to run Cruise Control. ### [](#single-az-infrastructure)Single-AZ infrastructure In a single-AZ deployment, ensure that brokers are spread across at least three failure domains. This generally means separate racks, under separate switches, ideally powered by separate electrical feeds or circuits. Also, ensure that there’s sufficient network bandwidth between brokers, particularly considering shared uplinks, which could be subject to high throughput intra-cluster replication traffic. In an on-premises network, this HA configuration refers to separate racks or data halls within a data center. Cloud providers support various HA configurations: - AWS [partition placement groups](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/placement-groups.html#placement-groups-partition) allow spreading hosts across multiple partitions (or failure domains) within an AZ. The default number of partitions is three, with a maximum of seven. This can be combined with Redpanda’s replication factor setting, so each topic partition replica is guaranteed to be isolated from the impact of hardware failure. - Microsoft Azure [flexible scale sets](https://learn.microsoft.com/en-us/azure/virtual-machine-scale-sets/virtual-machine-scale-sets-orchestration-modes#scale-sets-with-flexible-orchestration) let you assign VMs to specific fault domains. Each scale set can have up to five fault domains, depending on your region. Not all VM types support flexible orchestration; for example, Lsv2-series only supports uniform scale sets. - Google Cloud [instance placement policies](https://cloud.google.com/compute/docs/instances/define-instance-placement) let you specify how many availability domains you can have (up to eight) when using the Spread Instance Placement Policy. > 📝 **NOTE** > > Google Cloud doesn’t divulge which availability domain an instance has been placed into, so you must have an availability domain for each Redpanda broker. Essentially, this isn’t enabled with rack awareness, but it’s the only possibility for clusters with more than three brokers. You can automate this using Terraform or a similar infrastructure-as-code (IaC) tool. See [AWS](https://github.com/redpanda-data/deployment-automation/blob/main/aws/cluster.tf#L23-L24), [Azure](https://github.com/redpanda-data/deployment-automation/blob/main/azure/network.tf#L39-L50), and [GCP](https://github.com/redpanda-data/deployment-automation/blob/main/gcp/cluster.tf#L17-L19). ## [](#multi-az-deployments)Multi-AZ deployments In a multi-AZ (availability zone) deployment a single Redpanda cluster has brokers distributed over multiple availability zones. With rack awareness, Redpanda places replicas across brokers in different failure zones, resulting in a cluster that can survive a zone outage. > 📝 **NOTE** > > Adding a zone does not necessarily increase availability. The replication factor of a given partition is most important. If all of your partitions use a replication factor of three, then adding an additional broker in a fourth zone just means fewer partitions are affected by an outage (since the workload is more spread out). The primary reason to deploy across multiple availability zones is to achieve extremely high availability, even at the expense of other considerations. Before choosing this approach, carefully consider your system’s requirements. Some of the considerations of a multi-AZ approach include: - Cost: Maintaining presence across multiple availability zones may incur additional costs. You may require additional brokers to hit the minimum requirements for utilizing a multi-AZ deployment. Data sent between availability zones is often chargeable, resulting in additional cloud costs. - Performance: A multi-AZ approach introduces additional message latency. Your brokers are further apart in terms of network distance with additional routing hops in place. - Complexity: The Redpanda operational complexity is not appreciably increased, but the complexity of your overall cloud solution is. Maintaining presence across availability zones requires additional servers with corresponding maintenance, access control, and standard operational considerations. ### [](#multi-az-infrastructure-requirements)Multi-AZ infrastructure requirements Redpanda requires a minimum of three availability zones when using a multi-AZ approach. Deploying across only two availability zones is problematic. For example, given a cluster with three brokers spread across two availability zones, you either end up with all three brokers in one zone or a pair of brokers in one with a single broker in the other. Either way, it’s possible to lose a majority of your brokers with a single availability zone outage. You lose the ability to form consensus in affected partitions, negating the high availability state you desire. ### [](#multi-az-optimization)Multi-AZ optimization You can configure [follower fetching](../../../../develop/consume-data/follower-fetching/) to help ease the cross-AZ cost problems associated with a multi-AZ configuration. This is achieved by configuring consumers to advertise their preferred rack using the `client.rack` option within their consumer configuration. This allows consumers to read data from their closest replica rather than always reading from a (potentially non-local) partition leader. > 📝 **NOTE** > > With follower fetching enabled, a consumer chooses the closest replica rather than the leader. This reduces network transfer costs against the possibility of increased end-to-end latency. Make sure to monitor your system to determine if the cost savings are worth this latency risk. ### [](#multi-az-example)Multi-AZ example Redpanda provides an official [deployment automation](https://github.com/redpanda-data/deployment-automation) project using Ansible and Terraform to help self-managed users stand up multi-AZ deployments quickly and efficiently. #### [](#configure-terraform)Configure Terraform Configure the appropriate Terraform script for your cloud provider. Within the deployment-automation project, locate the file for your cloud provider and edit the `availability_zones` parameter. Include each availability zone you intend to use for your deployment. For example, under AWS, edit the `aws/main.tf` file: ```bash variable "availability_zone" { description = "The AWS AZ to deploy the infrastructure on" default = ["us-west-2a", "us-west-2b", "us-west-2c"] type = list(string) } ``` Alternatively, you can supply the configuration at the command line: ```bash $ terraform apply -var=availability_zone='["us-west-2a","us-west-2b","us-west-2c"]' ``` #### [](#deploy-using-terraform-and-ansible)Deploy using Terraform and Ansible After you configure Terraform for your cloud provider and choose availability zones, you can deploy your cluster. The following example deploys a multi-AZ cluster and validates the rack configuration. ```bash # Initialize a private key if you haven’t done so already ssh-keygen -f ~/.ssh/id_rsa # Clone the deployment-automation repository git clone https://github.com/redpanda-data/deployment-automation # Choose your cloud provider and initialize Terraform cd deployment-automation/aws # choose one: aws|azure|gcp terraform init # Deploy the infrastructure # (Note: This guidance is based on the assumption that you have cloud credentials available) terraform apply -var=availability_zone='["us-west-2a","us-west-2b","us-west-2c"]' # Verify you have correctly specified your racks in the host.ini file: cd .. export HOSTS=$(find . -name hosts.ini) head -4 $HOSTS [redpanda] 34.102.108.41 ansible_user=adminpanda ansible_become=True private_ip=10.168.0.41 rack=us-west2-a 35.236.32.47 ansible_user=adminpanda ansible_become=True private_ip=10.168.0.39 rack=us-west2-b 35.236.29.38 ansible_user=adminpanda ansible_become=True private_ip=10.168.0.40 rack=us-west2-c # Ensure the environment is ready export CLOUD_PROVIDER=aws # or azure or gcp accordingly export ANSIBLE_COLLECTIONS_PATH=${PWD}/artifacts/collections export ANSIBLE_ROLES_PATH=${PWD}/artifacts/roles export ANSIBLE_INVENTORY=${PWD}/${CLOUD_PROVIDER}/hosts.ini # Install Ansible Galaxy roles ansible-galaxy install -r ./requirements.yml # Provision the cluster with Ansible ansible-playbook ansible/provision-basic-cluster.yml -i $HOSTS ### Verify that rack awareness is enabled # SSH into a cluster node substituting the username and hostname from the values above ssh -i ~/.ssh/id_rsa @ # Check to confirm that rack awareness is enabled rpk cluster config get enable_rack_awareness true # Check to confirm that the brokers are assigned to distinct racks rpk cluster status | grep RACK -A3 ID HOST PORT RACK 0* 34.102.108.41 9092 us-west2-a 1 35.236.32.47 9092 us-west2-b 2 35.236.29.38 9092 us-west2-c ``` #### [](#use-follower-fetching)Use follower fetching Use [follower fetching](../../../../develop/consume-data/follower-fetching/) to reduce the latency and potential costs involved in a multi-AZ deployment. ```bash # SSH into a node using appropriate credentials ssh -i ~/.ssh/id_rsa @ # Create a topic with 1 partition and 3 replicas rpk topic create foo -p1 -r3 TOPIC STATUS foo OK # Determine which broker is the leader rpk topic describe foo -a | grep HIGH-WATERMARK -A1 PARTITION LEADER EPOCH REPLICAS LOG-START-OFFSET HIGH-WATERMARK 0 0 1 [0 1 2] 0 3 # Produce 1000 records using rpk for i in {1..1000}; do echo $(cat /dev/urandom | head -c50 | base64); done | rpk topic produce foo Produced to partition 0 at offset 0 with timestamp 1687508554559. Produced to partition 0 at offset 1 with timestamp 1687508554574. Produced to partition 0 at offset 2 with timestamp 1687508554593. ... 997 more lines ... # Consume for three seconds, writing debug logs and ignoring regular output timeout 3 rpk topic consume foo -v --rack us-west2-c 1>/dev/null 2>debug.log # Filter the debug log to only show lines of interest cat debug.log | grep -v ApiVersions | egrep 'opening|read' 08:25:14.974 DEBUG opening connection to broker {"addr": "10.168.0.41:9092", "broker": "seed 0"} 08:25:14.976 DEBUG read Metadata v7 {"broker": "seed 0", "bytes_read": 236, "read_wait": "36.312µs", "time_to_read": "534.898µs", "err": null} 08:25:14.977 DEBUG opening connection to broker {"addr": "34.102.108.41:9092", "broker": "0"} 08:25:14.980 DEBUG read ListOffsets v4 {"broker": "0", "bytes_read": 51, "read_wait": "16.19µs", "time_to_read": "1.090468ms", "err": null} 08:25:14.981 DEBUG opening connection to broker {"addr": "34.102.108.41:9092", "broker": "0"} 08:25:14.982 DEBUG read Fetch v11 {"broker": "0", "bytes_read": 73, "read_wait": "17.705µs", "time_to_read": "858.613µs", "err": null} 08:25:14.982 DEBUG opening connection to broker {"addr": "35.236.29.38:9092", "broker": "2"} 08:25:14.989 DEBUG read Fetch v11 {"broker": "2", "bytes_read": 130337, "read_wait": "54.712µs", "time_to_read": "4.466249ms", "err": null} 08:25:17.946 DEBUG read Fetch v11 {"broker": "2", "bytes_read": 0, "read_wait": "41.144µs", "time_to_read": "2.955927224s", "err": "context canceled"} 08:25:17.947 DEBUG read Fetch v11 {"broker": "0", "bytes_read": 22, "read_wait": "175.952µs", "time_to_read": "500.832µs", "err": null} ``` ## [](#suggested-reading)Suggested reading - [Production readiness checklist](../k-production-readiness/) - Validate your Kubernetes deployment against production standards - [Redpanda’s official Jepsen report](https://redpanda.com/blog/redpanda-official-jepsen-report-and-analysis?utm_assettype=report&utm_assetname=roi_report&utm_source=gated_content&utm_medium=content&utm_campaign=jepsen_blog) - [Simplifying Redpanda Raft implementation](https://redpanda.com/blog/simplifying-raft-replication-in-redpanda) - [An availability footprint of the Redpanda and Apache Kafka replication protocols](https://redpanda.com/blog/kafka-redpanda-availability) - [How we built Tiered Storage to supercharge storage and data streaming](https://www.redpanda.com/blog/tiered-storage-architecture-deep-dive) ## Suggested labs - [Disaster Recovery with Envoy and Shadowing](/redpanda-labs/docker-compose/envoy-shadowing/) - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) [Search all labs](/redpanda-labs) --- # Page 41: Deploy Redpanda for Production in Kubernetes **URL**: https://docs.redpanda.com/current/deploy/redpanda/kubernetes/k-production-deployment.md --- # Deploy Redpanda for Production in Kubernetes --- title: Deploy Redpanda for Production in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: redpanda/kubernetes/k-production-deployment page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: redpanda/kubernetes/k-production-deployment.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/redpanda/kubernetes/k-production-deployment.adoc description: Deploy a Redpanda cluster in Kubernetes. page-git-created-date: "2025-08-15" page-git-modified-date: "2026-02-06" support-status: supported --- This topic describes how to configure and deploy one or more Redpanda clusters and Redpanda Console in Kubernetes. ## [](#prerequisites)Prerequisites Make sure that your Kubernetes cluster meets the [requirements](../k-requirements/). You must already have a ConfigMap that stores your `io-config.yaml` file. See [Generate optimal I/O configuration settings](../k-tune-workers/#io). ## [](#deploy-a-redpanda-cluster)Deploy a Redpanda cluster To deploy Redpanda and Redpanda Console, you can use the following tools: - **Redpanda Operator**: The Redpanda Operator extends Kubernetes with custom resource definitions (CRDs), allowing you to define Redpanda clusters as native Kubernetes resources. The resource that the Redpanda Operator uses to represent a Redpanda cluster is the Redpanda resource. The Redpanda Operator can be deployed in either cluster scope (managing resources across all namespaces) or namespace scope (managing resources within a single namespace). - **Helm**: [Helm](https://helm.sh/docs) is a package manager for Kubernetes, which simplifies the process of defining, installing, and upgrading Kubernetes applications. Helm uses charts, a collection of files that describe a related set of Kubernetes resources, to deploy applications in a Kubernetes cluster. > 💡 **TIP** > > For more details about the differences between these two methods, see [Redpanda in Kubernetes](../k-deployment-overview/). ### Operator The Redpanda Operator can be deployed in two different scopes: - **Cluster scope** (recommended): The Redpanda Operator manages Redpanda resources across all namespaces in your Kubernetes cluster. This provides centralized management and is ideal for production environments. - **Namespace scope**: The Redpanda Operator manages Redpanda resources only within a specific namespace. This provides better isolation and is suitable when you need strict namespace boundaries. > ⚠️ **WARNING** > > Do not run multiple Redpanda Operators in different scopes (cluster and namespace scope) in the same cluster as this can cause resource conflicts. 1. Make sure that you have permission to install custom resource definitions (CRDs): ```bash kubectl auth can-i create CustomResourceDefinition --all-namespaces ``` You should see `yes` in the output. You need these cluster-level permissions to install [cert-manager](https://cert-manager.io/docs/) and Redpanda Operator CRDs in the next steps. 2. Install [cert-manager](https://cert-manager.io/docs/installation/helm/): ```bash helm repo add jetstack https://charts.jetstack.io helm repo update helm install cert-manager jetstack/cert-manager \ --set crds.enabled=true \ --namespace cert-manager \ --create-namespace ``` The Redpanda Helm chart enables TLS by default and uses cert-manager to manage TLS certificates. 3. Deploy the Redpanda Operator in your chosen scope: 1. To deploy in cluster scope, use: ```bash helm repo add redpanda https://charts.redpanda.com helm repo update helm upgrade --install redpanda-controller redpanda/operator \ --namespace \ --create-namespace \ --version v26.1.2 \ (1) --set crds.enabled=true (2) ``` | 1 | This flag specifies the exact version of the Redpanda Operator Helm chart to use for deployment. By setting this value, you pin the chart to a specific version, which prevents automatic updates that might introduce breaking changes or new features that have not been tested in your environment. | | --- | --- | | 2 | This flag ensures that the CRDs are installed as part of the Redpanda Operator deployment.This command deploys the Redpanda Operator in cluster scope (default in v25.2+), allowing it to manage Redpanda clusters across multiple namespaces. | 2. To deploy in namespace scope (managing only resources within its deployment namespace), use: ```bash helm upgrade --install redpanda-controller redpanda/operator \ --namespace \ --create-namespace \ --version v26.1.2 \ --set crds.enabled=true \ --set 'additionalCmdFlags=["--namespace="]' (1) ``` | 1 | This flag restricts the Redpanda Operator to manage resources only within the specified namespace. | | --- | --- | 4. Ensure that the Deployment is successfully rolled out: ```bash kubectl --namespace rollout status --watch deployment/redpanda-controller-operator ``` deployment "redpanda-controller-operator" successfully rolled out 5. Install a [Redpanda custom resource](../../../../reference/k-crd/) to deploy a Redpanda cluster and Redpanda Console. `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda namespace: spec: clusterSpec: #enterprise: #licenseSecretRef: #name: #key: image: tag: v26.1.3 statefulset: extraVolumes: |- - name: redpanda-io-config configMap: name: redpanda-io-config extraVolumeMounts: |- - name: redpanda-io-config mountPath: /etc/redpanda-io-config additionalRedpandaCmdFlags: - "--io-properties-file=/etc/redpanda-io-config/io-config.yaml" ``` - `metadata.name`: Name to assign the Redpanda cluster. - `metadata.namespace`: For cluster-scoped deployment, specify any namespace. For namespace-scoped deployment, must be the same namespace where the Redpanda Operator is deployed. - [`spec.clusterSpec`](../../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-api-redpanda-v1alpha2-redpandaclusterspec): This is where you can override default values in the Redpanda Helm chart. Here, you mount the [I/O configuration file](#prerequisites) to the Pods that run Redpanda. For other configuration details, see [Production considerations](#config). - `spec.clusterSpec.enterprise`: If you want to use enterprise features in Redpanda, uncomment this section and add the details of a Secret that stores your Enterprise Edition license key. For details, see [Redpanda Licensing](../../../../get-started/licensing/). - `spec.clusterSpec.image.tag`: Deploys the latest version of Redpanda. - `spec.clusterSpec.statefulset`: Here, you mount the [I/O configuration file](#prerequisites) to the Pods that run Redpanda. For other configuration details, see [Production considerations](#config). 6. Apply the Redpanda resource: ```bash kubectl apply -f redpanda-cluster.yaml ``` 7. Wait for the Redpanda Operator to deploy Redpanda using the Helm chart: ```bash kubectl get redpanda --namespace --watch ``` NAME READY STATUS redpanda True Redpanda reconciliation succeeded This step may take a few minutes. You can watch for new Pods to make sure that the deployment is progressing: ```bash kubectl get pod --namespace ``` If it’s taking too long, see [Troubleshooting](../../../../troubleshoot/errors-solutions/k-resolve-errors/). 8. Verify that each Redpanda broker is scheduled on only one Kubernetes node: ```bash kubectl get pod --namespace \ -o=custom-columns=NODE:.spec.nodeName,NAME:.metadata.name -l \ app.kubernetes.io/component=redpanda-statefulset ``` Expected output: example-worker3 redpanda-0 example-worker2 redpanda-1 example-worker redpanda-2 ### Helm 1. Install cert-manager using Helm: ```bash helm repo add jetstack https://charts.jetstack.io helm repo update helm install cert-manager jetstack/cert-manager \ --set crds.enabled=true \ --namespace cert-manager \ --create-namespace ``` The Redpanda Helm chart enables TLS by default and uses cert-manager to manage TLS certificates. 2. Override the default values to mount your [I/O configuration file](#prerequisites) onto each Pod that runs Redpanda. `redpanda-values.yaml` ```yaml image: tag: {latest-redpanda-tag} statefulset: extraVolumes: |- - name: redpanda-io-config configMap: name: redpanda-io-config extraVolumeMounts: |- - name: redpanda-io-config mountPath: /etc/redpanda-io-config additionalRedpandaCmdFlags: - "--io-properties-file=/etc/redpanda-io-config/io-config.yaml" ``` Redpanda reads from this file at startup to optimize itself for the given I/O parameters. If you want to use enterprise features in Redpanda, add the details of a Secret that stores your Enterprise Edition license key. `redpanda-values.yaml` ```yaml enterprise: licenseSecretRef: name: key: ``` For details, see [Add an Enterprise Edition License to Redpanda in Kubernetes](../../../../get-started/licensing/add-license-redpanda/kubernetes/). 3. Install the Redpanda Helm chart to deploy a Redpanda cluster and Redpanda Console. ```bash helm repo add redpanda https://charts.redpanda.com helm repo update helm install redpanda redpanda/redpanda \ --version 26.1.2 \ (1) --namespace \ (2) --create-namespace \ --values redpanda-values.yaml ``` | 1 | This flag specifies the exact version of the Redpanda Helm chart to use for deployment. By setting this value, you pin the chart to a specific version, which prevents automatic updates that might introduce breaking changes or new features that have not been tested in your environment. | | --- | --- | | 2 | Each deployment of the Redpanda Helm chart requires a separate namespace. Ensure you choose a unique namespace for each deployment. | 4. Wait for the Redpanda cluster to be ready: ```bash kubectl --namespace rollout status statefulset redpanda --watch ``` When the Redpanda cluster is ready, the output should look similar to the following: statefulset rolling update complete 3 pods at revision redpanda-8654f645b4... 5. Verify that each Redpanda broker is scheduled on only one Kubernetes node: ```bash kubectl get pod --namespace \ -o=custom-columns=NODE:.spec.nodeName,NAME:.metadata.name -l \ app.kubernetes.io/component=redpanda-statefulset ``` Expected output: example-worker3 redpanda-0 example-worker2 redpanda-1 example-worker redpanda-2 ## [](#deploy-multiple-redpanda-clusters)Deploy multiple Redpanda clusters You can deploy multiple Redpanda clusters in the same Kubernetes cluster. This is useful for creating separate environments (such as production, staging, and development) or for organizing clusters by application or team. ### Operator When using the Redpanda Operator, you can deploy multiple Redpanda clusters by creating separate Redpanda custom resources. **Requirements:** - Use a cluster-scoped Redpanda Operator deployment (recommended) or separate namespace-scoped operators in different namespaces - Each cluster must be deployed in a unique namespace - Configure unique external port numbers for each cluster to avoid conflicts 1. Create a second Redpanda cluster in a different namespace: `redpanda-cluster-two.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda-staging namespace: redpanda-staging spec: clusterSpec: image: tag: v26.1.3 listeners: kafka: external: default: advertisedPorts: [31093] (1) admin: external: default: advertisedPorts: [31645] (1) http: external: default: advertisedPorts: [30083] (1) rpc: port: 33146 (1) schemaRegistry: external: default: advertisedPorts: [30084] (1) statefulset: extraVolumes: |- - name: redpanda-io-config configMap: name: redpanda-io-config extraVolumeMounts: |- - name: redpanda-io-config mountPath: /etc/redpanda-io-config additionalRedpandaCmdFlags: - "--io-properties-file=/etc/redpanda-io-config/io-config.yaml" ``` | 1 | Configure unique port numbers for each cluster to avoid conflicts. Ensure these ports don’t conflict with your first cluster’s configuration. | | --- | --- | 2. Apply the second Redpanda resource: ```bash kubectl apply -f redpanda-cluster-two.yaml ``` 3. Wait for the second cluster to be ready: ```bash kubectl get redpanda --namespace redpanda-staging --watch ``` ### Helm When using Helm, deploy multiple Redpanda clusters by using separate namespaces and unique release names for each deployment. **Requirements:** - Each cluster must be deployed in a unique namespace - Use unique Helm release names for each deployment - Configure unique external port numbers for each cluster to avoid conflicts 1. Create configuration values for your second cluster: `redpanda-staging-values.yaml` ```yaml image: tag: v26.1.3 nameOverride: 'redpanda-staging' fullnameOverride: 'redpanda-staging' listeners: kafka: external: default: advertisedPorts: [31093] (1) admin: external: default: advertisedPorts: [31645] (1) http: external: default: advertisedPorts: [30083] (1) rpc: port: 33146 (1) schemaRegistry: external: default: advertisedPorts: [30084] (1) statefulset: extraVolumes: |- - name: redpanda-io-config configMap: name: redpanda-io-config extraVolumeMounts: |- - name: redpanda-io-config mountPath: /etc/redpanda-io-config additionalRedpandaCmdFlags: - "--io-properties-file=/etc/redpanda-io-config/io-config.yaml" ``` | 1 | Configure unique port numbers for each cluster to avoid conflicts. Ensure these ports don’t conflict with your first cluster’s configuration. | | --- | --- | 2. Install the second Redpanda cluster using a unique release name and namespace: ```bash helm install redpanda-staging redpanda/redpanda \ --version 26.1.2 \ --namespace redpanda-staging \ --create-namespace \ --values redpanda-staging-values.yaml ``` 3. Wait for the second cluster to be ready: ```bash kubectl --namespace redpanda-staging rollout status statefulset redpanda-staging --watch ``` > ❗ **IMPORTANT** > > When deploying multiple clusters, ensure that external listener ports are unique across all clusters to prevent conflicts. Also consider resource allocation and node capacity when planning multiple cluster deployments. ## [](#config)Production considerations This section provides advice for configuring the Redpanda in Kubernetes for production. If you’re using the Redpanda Operator, see: [cluster.redpanda.com/v1alpha2](../../../../reference/k-crd/) for all available settings. If you’re using the Redpanda Helm chart, see: [Redpanda Helm Chart Specification](../../../../reference/k-redpanda-helm-spec/) for all available settings. ### [](#version-pinning)Version pinning (Helm) If you use the Redpanda Helm chart to deploy Redpanda, it’s important to pin the version of the Helm chart to ensure that you have control over the version of Redpanda that you deploy. The Redpanda Helm chart version is independent of the Redpanda application version. The Redpanda application version can change even in patch releases of the Helm chart. This means that updates to the chart may roll out new versions of Redpanda. To avoid unexpected changes to your deployments, pin the version of the Helm chart. Pinning refers to the practice of specifying an exact version to use during deployment, rather than using the latest or unspecified version. When you pin the Helm chart version, you maintain consistent, predictable environments, especially in production. Using a specific version helps to: - **Ensure compatibility**: Guarantee that the deployed application behaves as tested, regardless of new chart versions being released. - **Avoid unexpected updates**: Prevent automatic updates that may introduce changes incompatible with the current deployment or operational practices. ```bash helm repo add redpanda https://charts.redpanda.com helm repo update helm install redpanda redpanda/redpanda \ --version 26.1.2 \ --namespace \ --create-namespace ``` [Review the release notes](../../../../reference/releases/) to understand any significant changes, bug fixes, or potential disruptions that could affect your existing deployment. ### [](#name-overrides-helm)Name overrides (Helm) Deploying multiple instances of the same Helm chart in a Kubernetes cluster can lead to naming conflicts. Using `nameOverride` and `fullnameOverride` helps differentiate between them. If you have a production and staging environment for Redpanda, different names help to avoid confusion. - Use `nameOverride` to customize the labels `app.kubernetes.io/component=-statefulset` and `app.kubernetes.io/name=`. - Use `fullnameOverride` to customize the name of the StatefulSet and Services. ```yaml nameOverride: 'redpanda-production' fullnameOverride: 'redpanda-instance-prod' ``` ### [](#labels)Labels Kubernetes labels help you to organize, query, and manage your resources. Use labels to categorize Kubernetes resources in different deployments by environment, purpose, or team. ```yaml commonLabels: env: 'production' ``` ### [](#tolerations)Tolerations Tolerations and taints allow Pods to be scheduled onto nodes where they otherwise wouldn’t. If you have nodes dedicated to Redpanda with a taint `dedicated=redpanda:NoSchedule`, the following toleration allows the Redpanda brokers to be scheduled on them. ```yaml tolerations: - key: "dedicated" operator: "Equal" value: "redpanda" effect: "NoSchedule" ``` ### [](#docker-image)Docker image You can specify the image tag to deploy a known version of the Redpanda Docker image. By default, the image tag is set in `Chart.appVersion`. Avoid using the `latest` tag, which can lead to unexpected changes. If you’re using a private repository, always ensure your nodes have the necessary credentials to pull the image. ```yaml image: repository: docker.redpanda.com/redpandadata/redpanda tag: "v26.1.3" imagePullSecrets: [] ``` ### [](#number-of-redpanda-brokers)Number of Redpanda brokers The number of Redpanda brokers you deploy depends on your use case and the level of redundancy you require. For production, deploy at least three Redpanda brokers. Always deploy an odd number of brokers to avoid split-brain scenarios. ```yaml statefulset: replicas: 3 ``` > 📝 **NOTE** > > You must provision one dedicated worker node for each Redpanda broker that you plan to deploy in your Redpanda cluster. The default [`podAntiAffinity` rules](#affinity-rules) make sure that each Redpanda broker runs on its own worker node. See also: - [High Availability in Kubernetes](../k-high-availability/) - [Kubernetes Cluster Requirements](../k-requirements/#number-of-worker-nodes) ### [](#tls)TLS By default, TLS (Transport Layer Security) is enabled for encrypted communication. Internal (`default`) and external (`external`) self-signed certificates are generated using cert-manager. See [TLS Certificates](#tls-certificates). ```yaml tls: enabled: true certs: # This key represents the name of the certificate. default: caEnabled: true # This key represents the name of the certificate. external: caEnabled: true ``` See also: [TLS for Redpanda in Kubernetes](../../../../manage/kubernetes/security/tls/) ### [](#authentication)Authentication If you want to authenticate clients connections to the Redpanda cluster, you can enable SASL authentication. ```yaml auth: sasl: enabled: true mechanism: "SCRAM-SHA-512" secretRef: "sasl-password-secret" users: [] ``` See also: [Configure Authentication for Redpanda in Kubernetes](../../../../manage/kubernetes/security/authentication/k-authentication/) ### [](#resources)Resources By default, the resources allocated to Redpanda are for a development environment. In a production cluster, the resources you allocate should be proportionate to your machine type. You should determine and set these values before deploying the cluster. ```yaml resources: cpu: cores: 4 memory: enable_memory_locking: true container: max: 10Gi ``` See also: - [Manage Pod Resources in Kubernetes](../../../../manage/kubernetes/k-manage-resources/) - [Kubernetes Cluster Requirements and Recommendations](../k-requirements/) ### [](#storage)Storage In production, it’s best to use local PersistentVolumes (PVs) that are backed by NVMe devices to store the Redpanda data directory. NVMe devices outperform traditional SSDs or HDDs. Redpanda Data recommends creating StorageClasses that use the [local volume manager (LVM) CSI driver](https://github.com/metal-stack/csi-driver-lvm) to automatically provision PVs. The LVM allows you to group physical storage devices into a logical volume group. Allocating logical volumes from a logical volume group provides greater flexibility in terms of storage expansion and management. The LVM supports features such as resizing, snapshots, and striping, which are not available with the other drivers such as the local volume static provisioner. ```yaml storage: persistentVolume: enabled: true size: 100Gi storageClass: csi-driver-lvm-striped-xfs ``` For an example of configuring local PersistentVolumes backed by NVMe disks, see one of the following guides: - [Azure Kubernetes Service](../aks-guide/#create-sc) (AKS) - [Elastic Kubernetes Service](../eks-guide/#create-sc) (EKS) - [Google Kubernetes Engine](../gke-guide/#create-sc) (GKE) See also: - [Supported Volume Types for Data in Redpanda](../../../../manage/kubernetes/storage/k-volume-types/) - [Kubernetes Cluster Requirements and Recommendations](../k-requirements/) - [Configure Storage for the Redpanda data directory in Kubernetes](../../../../manage/kubernetes/storage/k-configure-storage/) ### [](#external-access)External access To make the Redpanda cluster accessible from outside the Kubernetes cluster, you can use NodePort or LoadBalancer Services. The default NodePort Service provides the lowest latency of all the Kubernetes Services because it does not include any unnecessary routing or middleware. Client connections go to the Redpanda brokers in the most direct way possible, through the worker nodes. By default, the fully qualified domain names (FQDNs) that brokers advertise are their internal addresses within the Kubernetes cluster, which are not reachable from outside the cluster. To make the cluster accessible from outside, each broker must advertise a domain that can be reached from outside the cluster. ```yaml external: enabled: true type: NodePort ``` See also: - [About Networking and Connectivity in Kubernetes](../../../../manage/kubernetes/networking/k-networking-and-connectivity/) - [Configure Listeners in Kubernetes](../../../../manage/kubernetes/networking/k-configure-listeners/) ### [](#externaldns)ExternalDNS You should use ExternalDNS to manage DNS records for your Pods' domains. ExternalDNS synchronizes exposed Kubernetes Services with various DNS providers, rendering Kubernetes resources accessible through DNS servers. Benefits of ExternalDNS include: - **Automation**: ExternalDNS automatically configures public DNS records when you create, update, or delete Kubernetes Services or Ingresses. This eliminates the need for manual DNS configuration, which can be error-prone. - **Compatibility**: ExternalDNS is compatible with a wide range of DNS providers, including major cloud providers such as AWS, Google Cloud, and Azure, and DNS servers like CoreDNS and PowerDNS. - **Integration with other tools**: ExternalDNS can be used with other Kubernetes tools, such as ingress controllers or cert-manager for managing TLS certificates. ```yaml external: enabled: true type: LoadBalancer externalDns: enabled: true ``` See also: - [ExternalDNS with a NodePort Service](../../../../manage/kubernetes/networking/external/k-nodeport/#externaldns) - [ExternalDNS with LoadBalancer Services](../../../../manage/kubernetes/networking/external/k-loadbalancer/#externaldns) ### [](#logging)Logging By default, the log-level is set to `info`. In production, use the `info` logging level to avoid overwhelming the storage. For debugging purposes, temporarily change the logging level to `debug`. ```yaml logging: level: "info" ``` ### [](#monitoring)Monitoring By default, monitoring is disabled. If you have the [Prometheus Operator](https://prometheus-operator.dev/), enable monitoring to deploy a ServiceMonitor resource for Redpanda. Observability is essential in production environments. ```yaml monitoring: enabled: true ``` See also: [Monitor in Kubernetes](../../../../manage/kubernetes/monitoring/) ### [](#statefulset-update-strategy)StatefulSet update strategy For smooth and uninterrupted updates, use the default `RollingUpdate` strategy. Additionally, set a PodDisruptionBudget to ensure that at least one Pod is available during updates. ```yaml statefulset: updateStrategy: type: "RollingUpdate" budget: maxUnavailable: 1 ``` See also: [Upgrade Redpanda in Kubernetes](../../../../upgrade/k-rolling-upgrade/) ### [](#affinity-rules)Affinity rules By default, `podAntiAffinity` rules stop the Kubernetes scheduler from placing multiple Redpanda brokers on the same node. These rules offer two benefits: - Minimize the risk of data loss by ensuring that a node’s failure results in the loss of only one Redpanda broker. - Prevent resource contention between brokers by ensuring they are never co-located on the same node. Affinities control Pod placement in the cluster based on various conditions. Set these according to your high availability and infrastructure needs. For example, this is a soft rule that tries to ensure the Kubernetes scheduler doesn’t place two Pods with the same `app: redpanda` label in the same zone. However, if it’s not possible, the scheduler can still place the Pods in the same zone. ```yaml statefulset: podAntiAffinity: topologyKey: kubernetes.io/hostname type: hard weight: 100 custom: preferredDuringSchedulingIgnoredDuringExecution: - weight: 100 podAffinityTerm: labelSelector: matchExpressions: - key: "app" operator: "In" values: - "redpanda" topologyKey: "kubernetes.io/zone" ``` To completely disable `podAntiAffinity` rules (for example, in development environments where you want to run multiple brokers on the same node), you can override the default configuration: ```yaml statefulset: podTemplate: spec: affinity: podAntiAffinity: null ``` > ⚠️ **WARNING** > > Disabling `podAntiAffinity` rules is not recommended for production environments as it allows multiple brokers to be scheduled on the same node, increasing the risk of data loss if a node fails. See also: [High Availability in Kubernetes](../k-high-availability/) ### [](#graceful-shutdown)Graceful shutdown By default, Pods are given 90 seconds to shut down gracefully. If your brokers require additional time for a graceful shutdown, modify the `terminationGracePeriodSeconds`. ```yaml statefulset: terminationGracePeriodSeconds: 100 ``` See also: [Upgrade Redpanda in Kubernetes](../../../../upgrade/k-rolling-upgrade/) ### [](#service-account)Service account Restricting permissions is a best practice. Create a dedicated ServiceAccount for each Pod. To assign roles to this ServiceAccount, see [Role-based access control (RBAC)](#RBAC). ```yaml serviceAccount: create: true name: "redpanda-service-account" ``` ### [](#RBAC)Role-based access control (RBAC) RBAC is a method for providing permissions to ServiceAccounts based on roles. Some features such as rack awareness require both a ServiceAccount and RBAC to access resources using the Kubernetes API. ```yaml rbac: enabled: true annotations: {} ``` See also: [Enable Rack Awareness in Kubernetes](../../../../manage/kubernetes/k-rack-awareness/) ## [](#perform-a-self-test)Perform a self test To understand the performance capabilities of your Redpanda cluster, Redpanda offers built-in self-test features that evaluate the performance of both disk and network operations. For more information, see [Disk and network self-test benchmarks](../../../../troubleshoot/cluster-diagnostics/diagnose-issues/#self-test). When using the storage bandwidth test, ensure that your results show at least 16,000 IOPS (Input/Output Operations Per Second) for production environments. If your test results are below this threshold, your storage may not be suitable for production Redpanda workloads. ## [](#redpanda-console)Redpanda Console Redpanda Console is deployed by default when you deploy a Redpanda cluster using either the Redpanda Operator or the Redpanda Helm chart. This provides a web UI for managing and debugging your Redpanda cluster and applications. Both the Redpanda Operator and Helm chart automatically deploy Redpanda Console alongside your Redpanda cluster with sensible defaults. If you need to deploy Redpanda Console separately (for example, to connect to a Redpanda cluster running outside Kubernetes, or to have more granular control over the configuration), see [Deploy Redpanda Console on Kubernetes](../../../console/kubernetes/deploy/). The standalone deployment option provides the option to connect to Redpanda clusters running outside Kubernetes. For resource recommendations and scaling guidance for Redpanda Console on Kubernetes, see [Redpanda Console Kubernetes Requirements and Recommendations](../../../console/kubernetes/k-requirements/). ## [](#explore-the-default-kubernetes-components)Explore the default Kubernetes components By default, the Redpanda Helm chart deploys the following Kubernetes components: - [A StatefulSet](#statefulset) with three Pods. - [One PersistentVolumeClaim](#persistentvolumeclaim) for each Pod, each with a capacity of 20Gi. - [A headless ClusterIP Service and a NodePort Service](#service) for each Kubernetes node that runs a Redpanda broker. - [Self-Signed TLS Certificates](#tls-certificates). ### [](#statefulset)StatefulSet Redpanda is a stateful application. Each Redpanda broker needs to store its own state (topic partitions) in its own storage volume. As a result, the Helm chart deploys a StatefulSet to manage the Pods in which the Redpanda brokers are running. ```bash kubectl get statefulset --namespace ``` Example output: NAME READY AGE redpanda 3/3 3m11s StatefulSets ensure that the state associated with a particular Pod replica is always the same, no matter how often the Pod is recreated. Each Pod is also given a unique ordinal number in its name such as `redpanda-0`. A Pod with a particular ordinal number is always associated with a PersistentVolumeClaim with the same number. When a Pod in the StatefulSet is deleted and recreated, it is given the same ordinal number and so it mounts the same storage volume as the deleted Pod that it replaced. ```bash kubectl get pod --namespace ``` Expected output: ```none NAME READY STATUS RESTARTS AGE redpanda-0 1/1 Running 0 6m9s redpanda-1 1/1 Running 0 6m9s redpanda-2 1/1 Running 0 6m9s redpanda-console-5ff45cdb9b-6z2vs 1/1 Running 0 5m redpanda-configuration-smqv7 0/1 Completed 0 6m9s ``` > 📝 **NOTE** > > The `redpanda-configuration` job updates the Redpanda runtime configuration. ### [](#persistentvolumeclaim)PersistentVolumeClaim Redpanda brokers must be able to store their data on disk. By default, the Helm chart uses the default StorageClass in the Kubernetes cluster to create a PersistentVolumeClaim for each Pod. The default StorageClass in your Kubernetes cluster depends on the Kubernetes platform that you are using. ```bash kubectl get persistentvolumeclaims --namespace ``` Expected output: ```none NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE datadir-redpanda-0 Bound pvc-3311ade3-de84-4027-80c6-3d8347302962 20Gi RWO standard 75s datadir-redpanda-1 Bound pvc-4ea8bc03-89a6-41e4-b985-99f074995f08 20Gi RWO standard 75s datadir-redpanda-2 Bound pvc-45c3555f-43bc-48c2-b209-c284c8091c45 20Gi RWO standard 75s ``` ### [](#service)Service The clients writing to or reading from a given partition have to connect directly to the leader broker that hosts the partition. As a result, clients need to be able to connect directly to each Pod. To allow internal and external clients to connect to each Pod that hosts a Redpanda broker, the Helm chart configures two Services: - Internal using the [Headless ClusterIP](#headless-clusterip-service) - External using the [NodePort](#nodeport-service) ```bash kubectl get service --namespace ``` Expected output: ```none NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE redpanda ClusterIP None 5m37s redpanda-console ClusterIP 10.0.251.204 8080 5m redpanda-external NodePort 10.96.137.220 9644:31644/TCP,9094:31092/TCP,8083:30082/TCP,8080:30081/TCP 5m37s ``` #### [](#headless-clusterip-service)Headless ClusterIP Service The headless Service associated with a StatefulSet gives the Pods their network identity in the form of a fully qualified domain name (FQDN). Both Redpanda brokers in the same Redpanda cluster and clients within the same Kubernetes cluster use this FQDN to communicate with each other. An important requirement of distributed applications such as Redpanda is peer discovery: The ability for each broker to find other brokers in the same cluster. When each Pod is rolled out, its `seed_servers` field is updated with the FQDN of each Pod in the cluster so that they can discover each other. ```bash kubectl --namespace exec redpanda-0 -c redpanda -- cat etc/redpanda/redpanda.yaml ``` ```yaml redpanda: data_directory: /var/lib/redpanda/data empty_seed_starts_cluster: false seed_servers: - host: address: redpanda-0.redpanda..svc.cluster.local. port: 33145 - host: address: redpanda-1.redpanda..svc.cluster.local. port: 33145 - host: address: redpanda-2.redpanda..svc.cluster.local. port: 33145 ``` #### [](#nodeport-service)NodePort Service External access is made available by a NodePort service that opens the following ports by default: | Listener | Node Port | Container Port | | --- | --- | --- | | Schema Registry | 30081 | 8081 | | HTTP Proxy | 30082 | 8083 | | Kafka API | 31092 | 9094 | | Admin API | 31644 | 9644 | To learn more, see [Networking and Connectivity in Kubernetes](../../../../manage/kubernetes/networking/k-networking-and-connectivity/). ### [](#tls-certificates)TLS Certificates By default, TLS is enabled in the Redpanda Helm chart. The Helm chart uses [cert-manager](https://cert-manager.io/docs/) to generate four Certificate resources that provide Redpanda with self-signed certificates for internal and external connections. Having separate certificates for internal and external connections provides security isolation. If an external certificate or its corresponding private key is compromised, it doesn’t affect the security of internal communications. ```bash kubectl get certificate --namespace ``` NAME READY redpanda-default-cert True redpanda-default-root-certificate True redpanda-external-cert True redpanda-external-root-certificate True - `redpanda-default-cert`: Self-signed certificate for internal communications. - `redpanda-default-root-certificate`: Root certificate authority for the internal certificate. - `redpanda-external-cert`: Self-signed certificate for external communications. - `redpanda-external-root-certificate`: Root certificate authority for the external certificate. By default, all listeners are configured with the same certificate. To configure separate TLS certificates for different listeners, see [TLS for Redpanda in Kubernetes](../../../../manage/kubernetes/security/tls/). > 📝 **NOTE** > > The Redpanda Helm chart provides self-signed certificates for convenience. In a production environment, it’s best to use certificates from a trusted Certificate Authority (CA) or integrate with your existing CA infrastructure. ## [](#uninstall-redpanda)Uninstall Redpanda When you finish testing Redpanda, you can uninstall it from your Kubernetes cluster. The steps depend on how you installed Redpanda: using the Redpanda Operator or the Redpanda Helm chart. ### Operator Follow the steps in **exact order** to avoid race conditions between the Redpanda Operator’s reconciliation loop and Kubernetes garbage collection. 1. Delete all Redpanda-related custom resources: ```bash kubectl delete users --namespace --all kubectl delete topics --namespace --all kubectl delete schemas --namespace --all kubectl delete redpanda --namespace --all ``` 2. Make sure requests for those resources return no results. For example, if you had a Redpanda cluster named `redpanda` in the namespace ``, run: ```bash kubectl get redpanda --namespace ``` 3. Uninstall the Redpanda Operator Helm release: ```bash helm uninstall redpanda-controller --namespace ``` Helm does not uninstall CRDs by default when using `helm uninstall` to avoid accidentally deleting existing custom resources. 4. Remove the CRDs. 1. List all Redpanda CRDs installed by the operator: ```bash kubectl api-resources --api-group='cluster.redpanda.com' ``` This command displays all CRDs defined by the Redpanda Operator. For example: ```bash NAME SHORTNAMES APIVERSION NAMESPACED KIND redpandas rp cluster.redpanda.com/v1alpha2 true Redpanda schemas sc cluster.redpanda.com/v1alpha2 true Schema topics cluster.redpanda.com/v1alpha2 true Topic users rpu cluster.redpanda.com/v1alpha2 true User ``` 2. Delete the CRDs: ```bash kubectl get crds -o name | grep cluster.redpanda.com | xargs kubectl delete ``` This command lists all CRDs with the `cluster.redpanda.com` domain suffix and deletes them, ensuring only Redpanda CRDs are removed. Helm does not delete CRDs automatically to prevent data loss, so you must run this step manually. 5. (Optional) Delete any leftover PVCs or Secrets in the namespace: > ⚠️ **CAUTION** > > The following command deletes all PVCs and Secrets in the namespace, which may remove unrelated resources if the namespace is shared with other applications. ```bash kubectl delete pvc,secret --all --namespace ``` ### Helm If you deployed Redpanda with the Redpanda Helm chart, follow these steps to uninstall it: 1. Uninstall the Helm release: ```bash helm uninstall redpanda --namespace ``` 2. (Optional) Delete any leftover PVCs or Secrets in the namespace: > ⚠️ **CAUTION** > > The following command deletes all PVCs and Secrets in the namespace, which may remove unrelated resources if the namespace is shared with other applications. ```bash kubectl delete pvc,secret --all --namespace ``` ## [](#troubleshoot)Troubleshoot Before troubleshooting your cluster, make sure that you have all the [prerequisites](#prerequisites). ### [](#helm-v3-18-0-is-not-supported-json-number-error)Helm v3.18.0 is not supported (json.Number error) If you are using Helm v3.18.0, you may encounter errors such as: Error: INSTALLATION FAILED: execution error at (redpanda/templates/entry-point.yaml:17:4): invalid Quantity expected string or float64 got: json.Number (1) This is due to a bug in Helm v3.18.0. To avoid similar errors, upgrade to a later version. For more details, see the [Helm GitHub issue](https://github.com/helm/helm/issues/30880). === StatefulSet never rolls out If the StatefulSet Pods remain in a pending state, they are waiting for resources to become available. To identify the Pods that are pending, use the following command: ```bash kubectl get pod --namespace ``` The response includes a list of Pods in the StatefulSet and their status. To view logs for a specific Pod, use the following command. ```bash kubectl logs -f --namespace ``` You can use the output to debug your deployment. ### [](#didnt-match-pod-anti-affinity-rules)Didn’t match pod anti-affinity rules If you see this error, your cluster does not have enough nodes to satisfy the anti-affinity rules: Warning FailedScheduling 18m default-scheduler 0/1 nodes are available: 1 node(s) didn't match pod anti-affinity rules. preemption: 0/1 nodes are available: 1 No preemption victims found for incoming pod. The Helm chart configures default `podAntiAffinity` rules to make sure that only one Pod running a Redpanda broker is scheduled on each worker node. To learn why, see [Number of workers](../k-requirements/#number-of-workers). To resolve this issue, do one of the following: - Create additional worker nodes. - Modify the anti-affinity rules (for development purposes only). If adding nodes is not an option, you can modify the `podAntiAffinity` rules in your StatefulSet to be less strict. #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: statefulset: podAntiAffinity: type: soft ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `docker-repo.yaml` ```yaml statefulset: podAntiAffinity: type: soft ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values docker-repo.yaml ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set statefulset.podAntiAffinity.type=soft ``` ### [](#unable-to-mount-volume)Unable to mount volume If you see volume mounting errors in the Pod events or in the Redpanda logs, ensure that each of your Pods has a volume available in which to store data. - If you’re using StorageClasses with dynamic provisioners (default), ensure they exist: ```bash kubectl get storageclass ``` - If you’re using PersistentVolumes, ensure that you have one PersistentVolume available for each Redpanda broker, and that each one has the storage capacity that’s set in `storage.persistentVolume.size`: ```bash kubectl get persistentvolume --namespace ``` To learn how to configure different storage volumes, see [Configure Storage](../../../../manage/kubernetes/storage/k-configure-storage/). ### [](#failed-to-pull-image)Failed to pull image When deploying the Redpanda Helm chart, you may encounter Docker rate limit issues because the default registry URL is not recognized as a Docker Hub URL. The domain `docker.redpanda.com` is used for statistical purposes, such as tracking the number of downloads. It mirrors Docker Hub’s content while providing specific analytics for Redpanda. Failed to pull image "docker.redpanda.com/redpandadata/redpanda:v": rpc error: code = Unknown desc = failed to pull and unpack image "docker.redpanda.com/redpandadata/redpanda:v": failed to copy: httpReadSeeker: failed open: unexpected status code 429 Too Many Requests - Server message: toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit To fix this error, do one of the following: - Replace the `image.repository` value in the Helm chart with `docker.io/redpandadata/redpanda`. Switching to Docker Hub avoids the rate limit issues associated with `docker.redpanda.com`. #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: image: repository: docker.io/redpandadata/redpanda ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `docker-repo.yaml` ```yaml image: repository: docker.io/redpandadata/redpanda ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values docker-repo.yaml ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set image.repository=docker.io/redpandadata/redpanda ``` - Authenticate to Docker Hub by logging in with your Docker Hub credentials. The `docker.redpanda.com` site acts as a reflector for Docker Hub. As a result, when you log in with your Docker Hub credentials, you will bypass the rate limit issues. ### [](#dig-not-defined)Dig not defined This error means that you are using an unsupported version of [Helm](https://helm.sh/docs/intro/install/): Error: parse error at (redpanda/templates/statefulset.yaml:203): function "dig" not defined To fix this error, ensure that you are using the minimum required version: 3.10.0. ```bash helm version ``` ### [](#repository-name-already-exists)Repository name already exists If you see this error, remove the `redpanda` chart repository, then try installing it again. ```bash helm repo remove redpanda helm repo add redpanda https://charts.redpanda.com helm repo update ``` ### [](#fatal-error-during-checker-data-directory-is-writable-execution)Fatal error during checker "Data directory is writable" execution This error appears when Redpanda does not have write access to your configured storage volume under `storage` in the Helm chart. Error: fatal error during checker "Data directory is writable" execution: open /var/lib/redpanda/data/test\_file: permission denied To fix this error, set `statefulset.initContainers.setDataDirOwnership.enabled` to `true` so that the initContainer can set the correct permissions on the data directories. ### [](#cannot-patch-redpanda-with-kind-statefulset)Cannot patch "redpanda" with kind StatefulSet This error appears when you run `helm upgrade` with the `--values` flag but do not include all your previous overrides. Error: UPGRADE FAILED: cannot patch "redpanda" with kind StatefulSet: StatefulSet.apps "redpanda" is invalid: spec: Forbidden: updates to statefulset spec for fields other than 'replicas', 'template', 'updateStrategy', 'persistentVolumeClaimRetentionPolicy' and 'minReadySeconds' are forbidden To fix this error, include all the value overrides from the previous installation using either the `--set` or the `--values` flags. > ⚠️ **WARNING** > > Do not use the `--reuse-values` flag to upgrade from one version of the Helm chart to another. This flag stops Helm from using any new values in the upgraded chart. ### [](#cannot-patch-redpanda-console-with-kind-deployment)Cannot patch "redpanda-console" with kind Deployment This error appears if you try to upgrade your deployment and you already have `console.enabled` set to `true`. Error: UPGRADE FAILED: cannot patch "redpanda-console" with kind Deployment: Deployment.apps "redpanda-console" is invalid: spec.selector: Invalid value: v1.LabelSelector{MatchLabels:map\[string\]string{"app.kubernetes.io/instance":"redpanda", "app.kubernetes.io/name":"console"}, MatchExpressions:\[\]v1.LabelSelectorRequirement(nil)}: field is immutable To fix this error, set `console.enabled` to `false` so that Helm doesn’t try to deploy Redpanda Console again. ### [](#helm-is-in-a-pending-rollback-state)Helm is in a pending-rollback state An interrupted Helm upgrade process can leave your Helm release in a `pending-rollback` state. This state prevents further actions like upgrades, rollbacks, or deletions through standard Helm commands. To fix this: 1. Identify the Helm release that’s in a `pending-rollback` state: ```bash helm list --namespace --all ``` Look for releases with a status of `pending-rollback`. These are the ones that need intervention. 2. Verify the Secret’s status to avoid affecting the wrong resource: ```bash kubectl --namespace get secret --show-labels ``` Identify the Secret associated with your Helm release by its `pending-rollback` status in the labels. > ⚠️ **WARNING** > > Ensure you have correctly identified the Secret to avoid unintended consequences. Deleting the wrong Secret could impact other deployments or services. 3. Delete the Secret to clear the `pending-rollback` state: ```bash kubectl --namespace delete secret -l status=pending-rollback ``` After clearing the `pending-rollback` state: - **Retry the upgrade**: Restart the upgrade process. You should investigate the initial failure to avoid getting into the `pending-rollback` state again. - **Perform a rollback**: If you need to roll back to a previous release, use `helm rollback ` to revert to a specific, stable release version. ### [](#crash-loop-backoffs)Crash loop backoffs If a broker crashes after startup, or gets stuck in a crash loop, it can accumulate an increasing amount of stored state. This accumulated state not only consumes additional disk space but also prolongs the time required for each subsequent restart to process it. To prevent infinite crash loops, the Redpanda Helm chart sets the [`crash_loop_limit`](../../../../reference/properties/broker-properties/#crash_loop_limit) broker configuration property to `5`. The crash loop limit is the number of consecutive crashes that can happen within one hour of each other. By default, the broker terminates immediately after hitting the `crash_loop_limit`. The Pod running Redpanda remains in a `CrashLoopBackoff` state until its internal consecutive crash counter is reset to zero. To facilitate debugging in environments where a broker is stuck in a crash loop, you can also set the [`crash_loop_sleep_sec`](../../../../reference/properties/broker-properties/#crash_loop_sleep_sec) broker configuration property. This setting determines how long the broker sleeps before terminating the process after reaching the crash loop limit. By providing a window during which the Pod remains available, you can SSH into it and troubleshoot the issue. Example configuration: ```yaml config: node: crash_loop_limit: 5 crash_loop_sleep_sec: 60 ``` In this example, when the broker hits the `crash_loop_limit` of 5, it will sleep for 60 seconds before terminating the process. This delay allows administrators to access the Pod and troubleshoot. To troubleshoot a crash loop backoff: 1. Check the Redpanda logs from the most recent crashes: ```bash kubectl logs --namespace ``` > 📝 **NOTE** > > Kubernetes retains logs only for the current and the previous instance of a container. This limitation makes it difficult to access logs from earlier crashes, which may contain vital clues about the root cause of the issue. Given these log retention limitations, setting up a centralized logging system is crucial. Systems such as [Loki](https://grafana.com/docs/loki/latest/) or [Datadog](https://www.datadoghq.com/product/log-management/) can capture and store logs from all containers, ensuring you have access to historical data. 2. Resolve the issue that led to the crash loop backoff. 3. Reset the crash counter to zero to allow Redpanda to restart. You can do any of the following to reset the counter: - Make changes to any of the following sections in the Redpanda Helm chart to trigger an update: - `config.node` - `config.tunable` For example: ```yaml config: node: crash_loop_limit: ``` - Delete the `startup_log` file in the broker’s data directory. ```bash kubectl exec --namespace -- rm /var/lib/redpanda/data/startup_log ``` > 📝 **NOTE** > > It might be challenging to execute this command within a Pod that is in a `CrashLoopBackoff` state due to the limited time during which the Pod is available before it restarts. Wrapping the command in a loop might work. - Wait one hour since the last crash. The crash counter resets after one hour. To avoid future crash loop backoffs and manage the accumulation of small segments effectively: - [Monitor](../../../../manage/kubernetes/monitoring/k-monitor-redpanda/) the size and number of segments regularly. - Optimize your Redpanda configuration for segment management. - Consider implementing [Tiered Storage](../../../../manage/kubernetes/tiered-storage/k-tiered-storage/) to manage data more efficiently. ### [](#a-redpanda-enterprise-edition-license-is-required)A Redpanda Enterprise Edition license is required During a Redpanda upgrade, if enterprise features are enabled and a valid Enterprise Edition license is missing, Redpanda logs a warning and aborts the upgrade process on the first broker. This issue prevents a successful upgrade. A Redpanda Enterprise Edition license is required to use the currently enabled features. To apply your license, downgrade this broker to the pre-upgrade version and provide a valid license key via rpk using 'rpk cluster license set ', or via Redpanda Console. To request an enterprise license, please visit . To try Redpanda Enterprise for 30 days, visit . For more information, see . If you encounter this message, follow these steps to recover: 1. [Roll back the affected broker to the original version](../../../../upgrade/k-rolling-upgrade/#roll-back). 2. Do one of the following: - [Apply a valid Redpanda Enterprise Edition license](../../../../get-started/licensing/add-license-redpanda/) to the cluster. - Disable enterprise features. If you do not have a valid license and want to proceed without using enterprise features, you can disable the enterprise features in your Redpanda configuration. 3. Retry the upgrade. For more troubleshooting steps, see [Troubleshoot Redpanda in Kubernetes](../../../../troubleshoot/errors-solutions/k-resolve-errors/). ## [](#next-steps)Next steps After deploying Redpanda, validate your production readiness: - [Production readiness checklist](../k-production-readiness/) - Comprehensive validation of your deployment against production standards See the [Manage Kubernetes topics](../../../../manage/kubernetes/) to learn how to customize your deployment to meet your needs. ## [](#suggested-reading)Suggested reading - [High Availability in Kubernetes](../k-high-availability/) - [Redpanda Helm Specification](../../../../reference/k-redpanda-helm-spec/) - [Redpanda CRD Reference](../../../../reference/k-crd/) ## Suggested labs - [Set Up GitOps for the Redpanda Helm Chart](/redpanda-labs/kubernetes/gitops-helm/) [Search all labs](/redpanda-labs) --- # Page 42: Production Readiness Checklist **URL**: https://docs.redpanda.com/current/deploy/redpanda/kubernetes/k-production-readiness.md --- # Production Readiness Checklist --- title: Production Readiness Checklist latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: redpanda/kubernetes/k-production-readiness page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: redpanda/kubernetes/k-production-readiness.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/redpanda/kubernetes/k-production-readiness.adoc description: Comprehensive checklist for validating Redpanda deployments in Kubernetes against production readiness standards. learning-objective-1: Validate a Kubernetes-deployed Redpanda cluster against production readiness standards page-git-created-date: "2026-02-06" page-git-modified-date: "2026-04-08" support-status: supported --- Before running a production workload on Redpanda in Kubernetes, follow this readiness checklist. By completing this checklist, you will be able to: - Validate a Kubernetes-deployed Redpanda cluster against production readiness standards > 📝 **NOTE** > > For Linux deployments, see the [Production Readiness Checklist for Linux](../../manual/production/production-readiness/). ## [](#critical-requirements)Critical requirements The Critical requirements checklist helps ensure that: - You have specified all required defaults and configuration items. - You have the optimal hardware setup. - You have enabled security. - You are set up to run in production. ### [](#redpanda-license)Redpanda license If using Enterprise features, validate that you are using a valid Enterprise license: Input ```bash kubectl exec -n -c redpanda -- rpk cluster license info -X user= -X pass= -X sasl.mechanism= ``` Output ```bash LICENSE INFORMATION =================== Organization: Your Company Name Type: enterprise Expires: Dec 31 2026 ``` Production deployments using Enterprise features (such as Tiered Storage, Schema Registry, or Continuous Data Balancing) must have a valid Enterprise license with a sufficient expiration date. See also: [Redpanda Licensing](../../../../get-started/licensing/) > 📝 **NOTE: Input** > > **SASL authentication flags** > > The `rpk` commands throughout this checklist include SASL authentication flags (`-X user`, `-X pass`, `-X sasl.mechanism`). If your cluster does not use SASL authentication, you can omit these flags from all commands. For example: > > Input > > ```bash > # With SASL authentication > kubectl exec -n -c redpanda -- rpk cluster health -X user= -X pass= -X sasl.mechanism= > > # Without SASL authentication > kubectl exec -n -c redpanda -- rpk cluster health > ``` > > Common SASL mechanisms are `SCRAM-SHA-256` or `SCRAM-SHA-512`. Update these values as needed for your deployment. ### [](#cluster-health)Cluster health Check that all brokers are connected and running. Run [`rpk cluster health`](../../../../reference/rpk/rpk-cluster/rpk-cluster-health/) to check the health of the cluster. No nodes should be down, and there should be zero leaderless or under-replicated partitions. Input ```bash kubectl exec -n -c redpanda -- rpk cluster health -X user= -X pass= -X sasl.mechanism= ``` Output ```bash CLUSTER HEALTH OVERVIEW ======================= Healthy: true Unhealthy reasons: [] Controller ID: 0 All nodes: [0 1 2] Nodes down: [] Leaderless partitions (0): [] Under-replicated partitions (0): [] ``` ### [](#minimum-broker-count)Minimum broker count You must have at least three brokers running to ensure production-level fault tolerance. Production clusters should have an odd number of brokers (3, 5, 7, etc.) for optimal consensus behavior. Verify the running broker count: Input ```bash kubectl get pods -n -l app.kubernetes.io/component=redpanda-statefulset ``` Output ```bash NAME READY STATUS RESTARTS AGE redpanda-0 2/2 Running 0 10d redpanda-1 2/2 Running 0 10d redpanda-2 2/2 Running 0 10d ``` Verify the configured replica count in your deployment: #### Helm Input ```bash helm get values redpanda -n | grep -A 1 "statefulset:" ``` Output ```bash statefulset: replicas: 3 ``` #### Operator Input ```bash kubectl get redpanda redpanda -n -o jsonpath='{.spec.clusterSpec.statefulset.replicas}' ``` Output ```bash 3 ``` See also: [Default Topic Replication Factor](#default-topic-replication-factor) ### [](#active-broker-membership)Active broker membership Verify that all brokers are in active state and not being decommissioned. Decommissioning is used to permanently remove a broker from the cluster, such as during node pool migrations or cluster downsizing. Brokers in a decommissioned state should not be present in production clusters unless actively performing a planned migration. Input ```bash kubectl exec -n -c redpanda -- rpk redpanda admin brokers list -X user= -X pass= -X sasl.mechanism= ``` Output ```bash NODE-ID NUM-CORES MEMBERSHIP-STATUS IS-ALIVE BROKER-VERSION 0 4 active true v24.2.4 1 4 active true v24.2.4 2 4 active true v24.2.4 ``` All brokers must show `active` status. If any broker shows the status `draining` or `decommissioned`, investigate immediately. See also: [Decommission Brokers](../../../../manage/kubernetes/k-decommission-brokers/) ### [](#no-brokers-in-maintenance-mode)No brokers in maintenance mode Check that no brokers are in maintenance mode during normal operations. Maintenance mode is used when modifying brokers that will remain as members of the cluster, such as during rolling upgrades or hardware maintenance. While necessary during planned maintenance windows, brokers should not remain in maintenance mode during normal operations. Input ```bash kubectl exec -n -c redpanda -- rpk cluster maintenance status -X user= -X pass= -X sasl.mechanism= ``` Output ```bash NODE-ID ENABLED FINISHED ERRORS PARTITIONS ELIGIBLE TRANSFERRING FAILED 0 false - - - - - - 1 false - - - - - - 2 false - - - - - - ``` All brokers should show `ENABLED: false`. If any broker shows `ENABLED: true` outside of a planned maintenance window, investigate immediately. See also: [Maintenance Mode](../../../../manage/kubernetes/k-rolling-restart/) ### [](#consistent-redpanda-version)Consistent Redpanda version Check that Redpanda is running the [latest point release](https://github.com/redpanda-data/redpanda/releases) for the major version you’re on and that all brokers run the same version. **Verify Redpanda broker versions:** Input ```bash kubectl exec -n -c redpanda -- rpk redpanda admin brokers list -X user= -X pass= -X sasl.mechanism= ``` Output ```bash NODE-ID NUM-CORES MEMBERSHIP-STATUS IS-ALIVE BROKER-VERSION 0 4 active true v25.2.4 1 4 active true v25.2.4 2 4 active true v25.2.4 ``` All brokers must show the same `BROKER-VERSION`. Version mismatches between brokers can cause compatibility issues and must be resolved before advancing to production. **Verify Helm Chart or Operator version compatibility:** For Kubernetes deployments, you must also verify that your deployment tool (Helm Chart or Operator) version is compatible with your Redpanda version. The Helm Chart or Operator version must be within one minor version of the Redpanda version. For example, if running Redpanda v25.2.x, the Helm Chart or Operator version must be v25.1.x, v25.2.x, or v25.3.x. #### Helm Input ```bash helm list -n ``` Output ```bash NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION redpanda redpanda 1 2024-01-15 10:30:00.123456 -0800 PST deployed redpanda-5.2.4 v25.2.4 ``` The `CHART` column shows the Helm Chart version (for example, `redpanda-5.2.4`), which should be compatible with the `APP VERSION` (Redpanda version). #### Operator Input ```bash kubectl get deployment redpanda-controller-manager -n -o jsonpath='{.spec.template.spec.containers[0].image}' ``` Output ```bash docker.redpanda.com/redpandadata/redpanda-operator:v25.2.4 ``` The Operator version is shown in the image tag (for example, `v25.2.4`), which should be compatible with your Redpanda broker version. You can also check the Operator version using: Input ```bash kubectl get redpanda redpanda -n -o jsonpath='{.metadata.annotations.redpanda\.com/operator-version}' ``` **Version compatibility requirements:** - All Redpanda brokers must run the same version - The Helm Chart or Operator version must be within ±1 minor version of Redpanda version - Example: Redpanda v25.2.x requires Helm/Operator v25.1.x, v25.2.x, or v25.3.x - Running incompatible versions can lead to deployment failures or cluster instability. ### [](#version-pinning)Version pinning Verify that versions are explicitly pinned in your deployment configuration: #### Helm ```yaml image: tag: v24.2.4 # Pin specific Redpanda version console: enabled: true image: tag: v2.4.5 # Pin specific Console version connectors: enabled: true image: tag: v1.0.15 # Pin specific Connectors version ``` Verify pinned versions: Input ```bash helm get values redpanda -n ``` Output ```bash image: tag: v24.2.4 console: image: tag: v2.4.5 connectors: image: tag: v1.0.15 ``` #### Operator ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: clusterSpec: image: tag: v24.2.4 # Pin specific Redpanda version console: enabled: true image: tag: v2.4.5 # Pin specific Console version connectors: enabled: true image: tag: v1.0.15 # Pin specific Connectors version ``` Verify pinned versions: Input ```bash kubectl get redpanda redpanda -n -o yaml | grep -A 1 "tag:" ``` Pin specific versions for Redpanda and all related components (Console, Connectors). This ensures all environments (dev/staging/prod) run the same tested versions, allows controlled upgrade testing before production rollout, and provides rollback capability to known-good versions. Avoid using the latest tag, version ranges (for example, v24.2.x), or unspecified tags, as these can result in unexpected upgrades that introduce breaking changes or cause downtime. ### [](#default-topic-replication-factor)Default topic replication factor Check that the default replication factor (≥3) is set appropriately for production. Input ```bash kubectl exec -n -c redpanda -- rpk cluster config get default_topic_replications -X user= -X pass= -X sasl.mechanism= ``` Output ```bash 3 ``` Setting `default_topic_replications` to `3` or greater ensures new topics are created with adequate fault tolerance. See also: [Choose the Replication Factor](../../../../manage/kubernetes/k-manage-topics/#choose-the-replication-factor) ### [](#existing-topics-replication-factor)Existing topics replication factor Check that all existing topics have adequate replication (default is `3`). Input ```bash kubectl exec -n -c redpanda -- rpk topic list -X user= -X pass= -X sasl.mechanism= ``` Output ```bash NAME PARTITIONS REPLICAS _schemas 1 3 orders 12 3 payments 8 3 user-events 16 3 ``` All production topics should have `REPLICAS` of three or greater. Topics with single-digit replication are at risk of data loss if a broker fails. See also: [Change Topic Replication Factor](../../../../manage/cluster-maintenance/topic-property-configuration/#change-topic-replication-factor) ### [](#persistent-storage-configuration)Persistent storage configuration Verify that you have configured persistent storage (not hostPath or emptyDir) for data persistence. Input ```bash kubectl get pvc -n ``` Output ```bash NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE datadir-redpanda-0 Bound pvc-a1b2c3d4-e5f6-7890-abcd-ef1234567890 100Gi RWO fast-ssd 10d datadir-redpanda-1 Bound pvc-b2c3d4e5-f6g7-8901-bcde-fg2345678901 100Gi RWO fast-ssd 10d datadir-redpanda-2 Bound pvc-c3d4e5f6-g7h8-9012-cdef-gh3456789012 100Gi RWO fast-ssd 10d ``` Verify the StatefulSet uses PersistentVolumeClaims: Input ```bash kubectl describe statefulset -n redpanda | grep -A 5 "Volume Claims" ``` Output ```bash Volume Claims: Name: datadir StorageClass: fast-ssd Labels: Annotations: Capacity: 100Gi ``` HostPath and emptyDir storage are not suitable for production as they lack durability guarantees. See also: [Persistent Storage](../../../../manage/kubernetes/storage/k-persistent-storage/) ### [](#raidlvm-stripe-configuration-multiple-disks-only)RAID/LVM stripe configuration (multiple disks only) If using multiple physical disks, verify they are configured to stripe data across the disks as RAID-0 or LVM stripe (not linear/concat). Striping distributes data across multiple disks in parallel for improved I/O performance. Input ```bash # Check block device configuration on nodes kubectl debug node/ -it -- chroot /host /bin/bash lsblk -o NAME,TYPE,SIZE,MOUNTPOINT,FSTYPE lvs -o lv_name,stripes,stripe_size mdadm --detail /dev/md* # if using software RAID ``` Output ```bash # lsblk output NAME TYPE SIZE MOUNTPOINT FSTYPE nvme0n1 disk 1.8T nvme1n1 disk 1.8T vg0-data lvm 3.6T /var/lib/redpanda xfs # lvs output - note stripes > 1 indicates striping LV #Stripes StripeSize data 2 256.00k ``` Output ```bash # mdadm output /dev/md0: Raid Level : raid0 Array Size : 3515625472 (3.27 TiB) Raid Devices : 2 Number Major Minor RaidDevice State 0 259 0 0 active sync /dev/nvme0n1 1 259 1 1 active sync /dev/nvme1n1 ``` Using LVM linear/concat or JBOD instead of stripe/RAID-0 across multiple disks will severely degrade performance because data writes are serialized rather than parallelized. For optimal I/O throughput, configure multiple disks in a striped array that writes data across all disks simultaneously. Single disk configurations do not require striping. See also: [Storage](../k-production-deployment/#storage) ### [](#storage-performance-requirements)Storage performance requirements Ensure storage classes provide adequate IOPS and throughput for your workload by using the following specifications when selection a storage class: **Performance specifications:** - Use NVMe-based storage classes for production deployments - Specify a minimum 16,000 IOPS (Input/Output Operations Per Second) - Consider provisioned IOPS where available to meet or exceed the minimum - Enable [write caching](../../../../develop/manage-topics/config-topics/#configure-write-caching) to help Redpanda perform better in environments with disks that don’t meet the recommended IOPS - NFS (Network File System) is not supported - Test storage performance under load > ⚠️ **WARNING** > > Avoid cloud instance types that use multi-tenant or shared disks, as these can lead to unpredictable performance due to noisy neighbor effects. Examples of instances with shared/multi-tenant storage include AWS is4gen.xlarge and similar instance types across cloud providers. Instead, use instances with dedicated local NVMe storage or provisioned IOPS volumes that guarantee consistent performance. Multi-tenant disks can experience: - Unpredictable latency spikes from other tenants' workloads - Inconsistent throughput that varies based on neighbor activity - IOPS throttling that impacts Redpanda’s performance - Difficulty troubleshooting performance issues due to external factors See also: - [Storage requirements](../k-requirements/#storage) - [Cloud Instance Types](../k-requirements/#cloud-instance-types) ### [](#cpu-and-memory-resource-limits)CPU and memory resource limits Verify Pods have resource requests and limits configured. Input ```bash kubectl get pod -n -o jsonpath='{.spec.containers[?(@.name=="redpanda")].resources}' | jq ``` Output ```bash { "limits": { "cpu": "4", "memory": "8Gi" }, "requests": { "cpu": "4", "memory": "8Gi" } } ``` All Redpanda Pods **must have**: - Identical CPU requests and limits (`requests.cpu == limits.cpu`) - Identical memory requests and limits (`requests.memory == limits.memory`) Setting requests equal to limits ensures the Pod receives the `Guaranteed` QoS class, which prevents CPU throttling and reduces the risk of Pod eviction. See also: [Manage Pod Resources](../../../../manage/kubernetes/k-manage-resources/) ### [](#cpu-to-memory-ratio)CPU to memory ratio Ensure adequate memory allocation relative to CPU for optimal performance. Production deployments should provision at least 2 GiB of memory per CPU core. The ratio should be at least 1:2 (2 GiB per core). Verify the CPU to memory ratio in your configuration: #### Helm Input ```bash helm get values redpanda -n | grep -A 2 "resources:" ``` Output ```bash resources: cpu: cores: 4 memory: container: min: 8Gi max: 8Gi ``` #### Operator Input ```bash kubectl get redpanda redpanda -n -o jsonpath='{.spec.clusterSpec.resources}' | jq ``` Output ```bash { "cpu": { "cores": 4 }, "memory": { "container": { "min": "8Gi", "max": "8Gi" } } } ``` In the preceding examples, 4 CPU cores with 8 GiB memory provides a 1:2 ratio (2 GiB per core). See also: [Memory](../../../../manage/kubernetes/k-manage-resources/#memory) ### [](#no-fractional-cpu-requests)No fractional CPU requests Ensure CPU requests use whole numbers for consistent performance. Fractional CPUs can lead to performance variability in production. Use whole integer values (`4`, `8`, or `16` are acceptable, while `3.5` or `7.5` are not). Verify CPU configuration: Input ```bash kubectl get pod -n -o jsonpath='{.spec.containers[?(@.name=="redpanda")].resources.requests.cpu}' ``` Output ```bash 4 ``` ### [](#authorization-enabled)Authorization enabled Verify Kafka authorization is enabled for access control. Input ```bash kubectl exec -n -c redpanda -- rpk cluster config get kafka_enable_authorization -X user= -X pass= -X sasl.mechanism= ``` Output ```bash true ``` Without authorization enabled, any client can access Kafka APIs without authentication. See also: [Authorization](../../../../manage/security/authorization/) ### [](#production-mode-enabled)Production mode enabled Verify that developer mode and overprovisioned mode are disabled for production stability. Check developer mode: Input ```bash kubectl exec -n -c redpanda -- grep developer_mode /etc/redpanda/redpanda.yaml ``` Output ```bash developer_mode: false ``` Developer mode should never be enabled in production environments. Developer mode disables fsync and bypasses safety checks designed for production workloads. Check overprovisioned mode: Input ```bash kubectl exec -n -c redpanda -- grep overprovisioned /etc/redpanda/redpanda.yaml ``` Output ```bash overprovisioned: false ``` Overprovisioned mode bypasses critical resource checks and should never be enabled in production. This mode is intended only for development environments with constrained resources. Verify in Helm values that `resources.cpu.overprovisioned` is not explicitly set to `true` (it’s automatically calculated based on CPU allocation). ### [](#tls-enabled)TLS enabled Configure TLS encryption for all client and inter-broker communication. TLS prevents eavesdropping and man-in-the-middle attacks on network traffic. Verify TLS is enabled on all listeners: Input ```bash kubectl exec -n -c redpanda -- rpk cluster config export -X user= -X pass= -X sasl.mechanism= | grep -A 10 "kafka_api:" ``` Output ```bash redpanda: kafka_api: - address: 0.0.0.0 port: 9093 name: internal authentication_method: sasl kafka_api_tls: - name: internal enabled: true cert_file: /etc/tls/certs/tls.crt key_file: /etc/tls/certs/tls.key ``` Required TLS listeners include: - **kafka\_api** - Client connections to Kafka API - **admin\_api** - Administrative REST API access - **rpc\_server** - Inter-broker communication - **schema\_registry** - Schema Registry API (if used) Verify certificates are properly mounted: Input ```bash kubectl exec -n -c redpanda -- ls -la /etc/tls/certs/ ``` Output ```bash total 16 -rw-r--r-- 1 redpanda redpanda 1234 Dec 15 10:00 ca.crt -rw-r--r-- 1 redpanda redpanda 1675 Dec 15 10:00 tls.crt -rw------- 1 redpanda redpanda 1704 Dec 15 10:00 tls.key ``` See also: [TLS Encryption](../../../../manage/kubernetes/security/tls/) ### [](#authentication-enabled)Authentication enabled Configure appropriate authentication mechanisms to control access to Redpanda resources. Verify SASL users are configured: Input ```bash kubectl exec -n -c redpanda -- rpk acl user list -X user= -X pass= -X sasl.mechanism= ``` Output ```bash USERNAME admin app-producer app-consumer monitoring ``` Be sure to adhere to the following authentication requirements: - Set up SASL authentication for client connections - Configure TLS certificates for encryption (see preceding TLS configuration guidance) - Implement proper user management with principle of least privilege - Configure [ACLs (Access Control Lists)](../../../../manage/security/authorization/acl/) for resource authorization Verify ACLs are configured: Input ```bash kubectl exec -n -c redpanda -- rpk acl list -X user= -X pass= -X sasl.mechanism= ``` Output ```bash PRINCIPAL HOST RESOURCE-TYPE RESOURCE-NAME OPERATION PERMISSION User:app-producer * TOPIC orders.* WRITE ALLOW User:app-consumer * TOPIC orders.* READ ALLOW User:app-consumer * GROUP consumer-group-1 READ ALLOW ``` See also: - [Authentication](../../../../manage/kubernetes/security/authentication/k-authentication/) - [Authorization](../../../../manage/security/authorization/) ### [](#network-security)Network security Secure network access to the cluster using Kubernetes-native controls. Verify NetworkPolicies are configured: Input ```bash kubectl get networkpolicy -n ``` Output ```bash NAME POD-SELECTOR AGE redpanda-allow-internal app.kubernetes.io/name=redpanda 10d redpanda-allow-clients app.kubernetes.io/name=redpanda 10d redpanda-deny-all-ingress app.kubernetes.io/name=redpanda 10d ``` Check NetworkPolicy rules: Input ```bash kubectl describe networkpolicy -n ``` Be sure to satisfy the following network security requirements: - Configure NetworkPolicies to restrict pod-to-pod communication - Use TLS for all client connections (see TLS configuration) - Secure admin API endpoints with [authentication](../../../../manage/kubernetes/security/authentication/k-authentication/) and [authorization](../../../../manage/security/authorization/) - Limit ingress traffic to only necessary ports and sources - Use Kubernetes Services to control external access Verify services and exposed ports: Input ```bash kubectl get svc -n ``` Output ```bash NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) redpanda ClusterIP None 9093/TCP,9644/TCP,8082/TCP redpanda-external LoadBalancer 10.100.200.50 9093:30001/TCP ``` See also: [Listener Configuration](../../../../manage/kubernetes/networking/k-configure-listeners/) ### [](#pod-disruption-budget)Pod Disruption Budget Set up PDBs to control voluntary disruptions during maintenance. Input ```bash kubectl get pdb -n ``` Output ```bash NAME MIN AVAILABLE MAX UNAVAILABLE ALLOWED DISRUPTIONS AGE redpanda N/A 1 1 10d ``` Production deployments must have a PodDisruptionBudget with `maxUnavailable: 1` to prevent simultaneous broker disruptions during voluntary operations like node drains, upgrades, or autoscaler actions. See also: [Kubernetes Pod Disruption Budgets](https://kubernetes.io/docs/tasks/run-application/configure-pdb/) ### [](#rack-awareness-and-topology-spread)Rack awareness and topology spread Configure topology spread constraints to distribute brokers across availability zones. For configuration instructions, see [Multi-AZ deployment](../k-high-availability/#multi-az-deployment). Production deployments require each Redpanda broker to run in a different availability zone to ensure that a single zone failure does not cause loss of quorum. For a three-broker cluster, brokers must be distributed across three separate zones. To verify zone distribution, check your cluster configuration: - Verify `topologySpreadConstraints` are configured in your Helm values or Redpanda CR - Confirm nodes have zone labels (typically `topology.kubernetes.io/zone`) - Check that brokers are scheduled on nodes in different zones See also: [Rack Awareness](../../../../manage/kubernetes/k-rack-awareness/) ### [](#operator-crds-operator-deployments-only)Operator CRDs (Operator deployments only) > ⚠️ **WARNING** > > If your deployment uses the Redpanda Operator, all required Custom Resource Definitions (CRDs) must be installed with compatible versions. Without correct CRDs, the Operator cannot manage the cluster, leading to configuration drift, failed updates, and potential data loss. The required CRDs are below: - `clusters.cluster.redpanda.com` - Manages Redpanda cluster configuration - `topics.cluster.redpanda.com` - Manages topic lifecycle - `users.cluster.redpanda.com` - Manages SASL users - `schemas.cluster.redpanda.com` - Manages Schema Registry schemas If any CRDs are missing or incompatible with your Operator version, the Operator will fail to reconcile resources. Verify all required CRDs are installed: Input ```bash kubectl get crd | grep redpanda.com ``` Output ```bash clusters.cluster.redpanda.com topics.cluster.redpanda.com users.cluster.redpanda.com schemas.cluster.redpanda.com ``` ### [](#run-redpanda-tuners)Run Redpanda tuners Check that you have configured tuners for optimal performance. Tuners can significantly impact latency and throughput. In Kubernetes, tuners are configured through the Helm chart or may need to be run on worker nodes themselves. For details, see [Tune Kubernetes Worker Nodes for Production](../k-tune-workers/). ## [](#recommended-requirements)Recommended requirements The Recommended requirements checklist ensures that you can monitor and support your environment on a sustained basis. It includes the following checks: - You have adhered to day-2 operations best practices. - You can diagnose and recover from backup issues or failures. - You have configured monitoring, backup, and security scanning. ### [](#deployment-method)Deployment method Verify that the deployment method (Helm or Operator) is correctly identified for your cluster. Understanding your deployment method is important for troubleshooting, upgrades, and configuration management. #### Helm Input ```bash helm list -n ``` Output ```bash NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION redpanda redpanda 1 2024-01-15 10:30:00.123456 -0800 PST deployed redpanda-5.0.0 v24.1.1 ``` The presence of a Helm release (`CHART` displays `redpanda-5.0.0`) indicates a Helm-managed deployment. #### Operator Input ```bash kubectl get redpanda -n ``` Output ```bash NAME READY STATUS redpanda True Redpanda reconciliation succeeded ``` The presence of a Redpanda custom resource indicates an Operator-managed deployment. Knowing your deployment method helps determine which configuration approach to use (Helm values vs. Redpanda CR), how to perform upgrades and rollbacks, where to find deployment logs and troubleshooting information, and which documentation sections apply to your environment. See [Production Deployment Workflow](../k-production-workflow/) for the complete deployment process. ### [](#xfs-filesystem)XFS filesystem Verify that data directories use XFS filesystem for optimal performance. Input ```bash kubectl exec -n -c redpanda -- df -khT /var/lib/redpanda/data ``` Output ```bash Filesystem Type Size Used Avail Use% Mounted on /dev/nvme0n1 xfs 1.8T 14G 1.8T 1% /var/lib/redpanda/data ``` XFS provides better performance characteristics for Redpanda workloads compared to ext4. While ext4 is supported, XFS is strongly recommended for production deployments. See also: [Storage Requirements](../../manual/production/requirements/#storage) ### [](#pod-anti-affinity)Pod anti-affinity Configure Pod anti-affinity to spread brokers across nodes. Input ```bash kubectl get statefulset redpanda -n -o jsonpath='{.spec.template.spec.affinity}' | jq ``` Output ```bash { "podAntiAffinity": { "requiredDuringSchedulingIgnoredDuringExecution": [ { "labelSelector": { "matchLabels": { "app.kubernetes.io/name": "redpanda" } }, "topologyKey": "kubernetes.io/hostname" } ] } } ``` This prevents single node failures from affecting multiple brokers by ensuring each Redpanda Pod runs on a different node. See also: [Pod Anti-Affinity](../k-production-deployment/#affinity-rules) ### [](#node-isolation)Node isolation Configure taints/tolerations or nodeSelector for workload isolation. Input ```bash kubectl get statefulset redpanda -n -o jsonpath='{.spec.template.spec.nodeSelector}' | jq ``` Output ```bash { "workload-type": "redpanda" } ``` Isolating Redpanda workloads on dedicated nodes improves performance predictability by preventing resource contention with other applications. ### [](#partition-balancing)Partition balancing Configure automatic partition balancing across brokers and CPU cores. #### [](#continuous-data-balancing)Continuous Data Balancing [Continuous Data Balancing](../../../../manage/cluster-maintenance/continuous-data-balancing/) can help you manage production deployments by automatically rebalancing partition replicas across brokers based on disk usage and node changes. It also eliminates manual intervention and prevents performance degradation. > ❗ **IMPORTANT** > > You should enable Continuous Data Balancing for all licensed production clusters. Verify that Continuous Data Balancing is configured: Input ```bash kubectl exec -n -c redpanda -- rpk cluster config get partition_autobalancing_mode -X user= -X pass= -X sasl.mechanism= ``` Output ```bash continuous ``` The `continuous` setting enables automatic partition rebalancing based on: - Node additions or removals - High disk usage conditions - Broker availability changes Without Continuous Data Balancing, partition distribution becomes skewed over time, leading to hotspots and manual rebalancing operations. #### [](#core-balancing)Core Balancing [Intra-broker partition balancing](../../../../manage/cluster-maintenance/cluster-balancing/#intra-broker-partition-balancing) distributes partition replicas across CPU cores within individual brokers. Check core balancing for CPU core partition distribution: Input ```bash kubectl exec -n -c redpanda -- rpk cluster config get core_balancing_on_core_count_change -X user= -X pass= -X sasl.mechanism= ``` Output ```bash true ``` When enabled, Redpanda continuously rebalances partitions between CPU cores on a broker for optimal resource utilization, which is especially beneficial after broker restarts or configuration changes. ### [](#system-requirements)System requirements Run system checks to get more details regarding your system configuration. Input ```bash kubectl exec -n -c redpanda -- rpk redpanda check -X user= -X pass= -X sasl.mechanism= ``` Output ```bash CONDITION REQUIRED CURRENT SEVERITY PASSED Data directory is writable true true Fatal true Free memory per CPU [MB] >= 2048 8192 Warning true NTP Synced true true Warning true Swappiness 1 1 Warning true ``` Review any failed checks and remediate before proceeding to production. See [rpk redpanda check](../../../../reference/rpk/rpk-redpanda/rpk-redpanda-check/) for details on each validation. ### [](#debug-bundle)Debug bundle Verify that you can successfully generate and collect a debug bundle from your cluster. This proactive check ensures that if an issue occurs and you need to contact Redpanda support, you won’t face permission issues or silent collection failures that could delay troubleshooting. Generate a debug bundle: Input ```bash kubectl exec -n -c redpanda -- rpk debug bundle -o /tmp/bundle.zip ``` For additional options and arguments, see [rpk debug bundle](../../../../reference/rpk/rpk-debug/rpk-debug-bundle/). Output ```bash Creating bundle file... Collecting cluster info... Collecting logs... Collecting configuration... Debug bundle saved to '/tmp/bundle.zip' ``` Debug bundles collect critical diagnostic information including cluster configuration and metadata, Redpanda logs from all brokers, system resource usage and performance metrics, and Kubernetes resource definitions. When testing bundle generation, watch for permission errors preventing log collection, insufficient disk space for bundle creation, network policies blocking bundle transfer, or RBAC restrictions on accessing Pod logs or exec. Testing bundle generation early ensures this critical troubleshooting tool works when you need it most. Debug bundles are often required by Redpanda support to diagnose production issues efficiently. See also: [Diagnostics Bundles in Kubernetes](../../../../troubleshoot/debug-bundle/generate/kubernetes/) ### [](#tiered-storage)Tiered Storage Configure [Tiered Storage](../../../../manage/kubernetes/tiered-storage/k-tiered-storage/) for extended data retention using object storage. Tiered Storage automatically offloads older data to cloud storage (S3, GCS, Azure Blob), enabling extended retention without expanding local disk capacity. Verify Tiered Storage configuration: Input ```bash kubectl exec -n -c redpanda -- rpk cluster config get cloud_storage_enabled -X user= -X pass= -X sasl.mechanism= ``` Output ```bash true ``` #### [](#benefits-of-tiered-storage)Benefits of Tiered Storage - Reduced local storage costs from offloading cold data to cheaper object storage - Longer data retention periods without provisioning additional disk - Required for advanced features like Remote Read Replicas and Iceberg integration - Disaster recovery capabilities through cloud-backed data To verify your Tiered Storage configuration: Input ```bash # Check bucket configuration kubectl exec -n -c redpanda -- rpk cluster config get cloud_storage_bucket -X user= -X pass= -X sasl.mechanism= # Check region/endpoint kubectl exec -n -c redpanda -- rpk cluster config get cloud_storage_region -X user= -X pass= -X sasl.mechanism= ``` See also: [Tiered Storage](../../../../manage/kubernetes/tiered-storage/k-tiered-storage/) ### [](#security-scanning)Security scanning Regularly scan container images and configurations for vulnerabilities to maintain security. #### [](#container-image-scanning)Container image scanning Verify that container images are scanned before deployment: Input ```bash # Check current image in use kubectl get statefulset redpanda -n -o jsonpath='{.spec.template.spec.containers[?(@.name=="redpanda")].image}' ``` Output ```bash docker.redpanda.com/redpandadata/redpanda:v24.2.4 ``` #### [](#security-scanning-best-practices)Security scanning best practices Security scanning best practices include: - Scan images using tools like Trivy, Snyk, or cloud-native scanners before deployment - Set up automated scanning in CI/CD pipelines - Monitor for CVE announcements and security advisories - Keep Redpanda and related components up-to-date with security patches (see [Rolling Upgrades](../../../../upgrade/k-rolling-upgrade/)) - Review Kubernetes RBAC policies and ServiceAccount permissions (see [Role Controller](../../../../manage/kubernetes/security/authorization/k-role-controller/)) #### [](#configuration-scanning)Configuration scanning Input ```bash # Scan Kubernetes manifests kubectl get redpanda,statefulset,deployment -n -o yaml > cluster-config.yaml # Use kubesec, kube-bench, or similar tools to scan cluster-config.yaml ``` Establish a regular cadence for security scanning (for example, weekly or with each deployment). ### [](#backup-and-recovery)Backup and recovery Implement and test backup and recovery processes to ensure business continuity. #### [](#backup-strategy-with-tiered-storage)Backup strategy with Tiered Storage Tiered Storage provides built-in backup capabilities by storing data in object storage. Verify Tiered Storage is configured: Input ```bash kubectl exec -n -c redpanda -- rpk cluster config get cloud_storage_enabled -X user= -X pass= -X sasl.mechanism= ``` #### [](#recovery-testing)Recovery testing Regularly test recovery procedures to validate RTO/RPO targets: Input ```bash # Test topic restoration from Tiered Storage kubectl exec -n -c redpanda -- rpk topic describe -X user= -X pass= -X sasl.mechanism= ``` For mission-critical workloads requiring active disaster recovery, consider implementing [Shadowing](../../../../manage/kubernetes/shadowing/k-shadow-linking/) to asynchronously replicate data to a standby cluster. Shadowing provides offset-preserving replication that maintains consumer positions, enabling faster recovery with lower RTO compared to restoration from backups. This Enterprise feature (available in Redpanda v25.3 or later) supports cross-region or cross-cloud disaster recovery with automatic failover capabilities. Configure and validate Tiered Storage for automatic data backup to object storage. Document and regularly test recovery procedures for different failure scenarios in non-production environments. Establish clear Recovery Time Objective (RTO) and Recovery Point Objective (RPO) targets, and maintain runbooks for disaster recovery scenarios. For Shadowing deployments, use the [Shadowing Failover Runbook](../../../../manage/kubernetes/shadowing/k-failover-runbook/) as a starting point. Verify that IAM roles and permissions for object storage access are correctly configured and tested. See also: - [Whole Cluster Restore](../../../../manage/kubernetes/tiered-storage/k-whole-cluster-restore/) - [Configure Shadowing](../../../../manage/kubernetes/shadowing/k-shadow-linking/) - [Shadowing Failover Runbook](../../../../manage/kubernetes/shadowing/k-failover-runbook/) ### [](#audit-logging)Audit logging Enable and configure audit logging for compliance and security monitoring requirements. Verify your audit log configuration: Input ```bash kubectl exec -n -c redpanda -- rpk cluster config get audit_enabled -X user= -X pass= -X sasl.mechanism= ``` Output ```bash true ``` Check to ensure you know where audit logs are being written: Input ```bash # Check audit log topic kubectl exec -n -c redpanda -- rpk topic list -X user= -X pass= -X sasl.mechanism= | grep audit ``` Output ```bash _redpanda.audit_log 1 3 ``` The output values of `1` and `3` indicate the number of partitions and replicas, respectively, for the audit log topic. For production environments with compliance requirements (SOC 2, HIPAA, PCI DSS, GDPR), forward audit logs to your SIEM system and configure retention policies according to your regulatory obligations. Ensure the audit log topic has adequate replication and retention settings. See also: [Audit Logging](../../../../manage/kubernetes/security/k-audit-logging/) ### [](#monitoring)Monitoring Check that [monitoring](../../../../manage/kubernetes/monitoring/k-monitor-redpanda/) is configured with [Prometheus](../../../../manage/kubernetes/monitoring/k-monitor-redpanda/#configure-prometheus) and [Grafana](../../../../manage/kubernetes/monitoring/k-monitor-redpanda/#generate-grafana-dashboard) to scrape metrics from all Redpanda brokers. Verify ServiceMonitor is configured: Input ```bash kubectl get servicemonitor -n ``` ### [](#system-log-retention)System log retention Check that Redpanda logs are being captured and stored for an appropriate period of time (minimally, seven days). Configure log forwarding using tools like Fluentd or your cloud provider’s logging solution to send logs to a central location for troubleshooting and compliance purposes. See also: [Diagnostics Bundles in Kubernetes](../../../../troubleshoot/debug-bundle/generate/kubernetes/) ### [](#environment-configuration)Environment configuration Check that you have a development or test environment configured to evaluate upgrades and configuration changes before applying them to production. ### [](#upgrade-policy)Upgrade policy Check that you have an upgrade policy defined and implemented. Redpanda supports [rolling upgrades](../../../../upgrade/k-rolling-upgrade/), so upgrades do not require downtime. However, make sure that upgrades are scheduled on a regular basis, ideally using automation with [Helm](../../../../manage/kubernetes/k-configure-helm-chart/) or GitOps workflows. ## [](#advanced-requirements)Advanced requirements The Advanced requirements checklist ensures full enterprise readiness, indicates that your system is operating at the highest level of availability, and can prevent or recover from the most serious incidents. The Advanced requirements checklist confirms the following: - You are proactively monitoring mission-critical workloads. - You have business continuity solutions in place. - You have integrated into enterprise security and operational systems. - Your enterprise is ready to run mission-critical workloads. ### [](#configure-alerts)Configure alerts A standard set of alerts for [Grafana](../../../../manage/kubernetes/monitoring/k-monitor-redpanda/#generate-grafana-dashboard) or [Prometheus](../../../../manage/kubernetes/monitoring/k-monitor-redpanda/#configure-prometheus) is provided in the [GitHub Redpanda observability repo](https://github.com/redpanda-data/observability). Customize these alerts for your specific needs. See also: [Monitoring Metrics](../../../../reference/monitor-metrics/) ### [](#deployment-automation)Deployment automation Review your deployment automation. Ensure that cluster configuration is managed using [Helm](../../../../manage/kubernetes/k-configure-helm-chart/) or GitOps workflows, and that all configuration is saved in source control. ### [](#monitor-security-settings)Monitor security settings Regularly review your cluster’s security settings using the `/v1/security/report` [Admin API](/api/doc/admin/) endpoint. Investigate and address any issues identified in the alerts section. Input ```bash curl 'http://localhost:9644/v1/security/report' ``` View output ```bash { "interfaces": { "kafka": [ { "name": "test_kafka_listener", "host": "0.0.0.0", "port": 9092, "advertised_host": "0.0.0.0", "advertised_port": 9092, "tls_enabled": false, "mutual_tls_enabled": false, "authentication_method": "None", "authorization_enabled": false } ], "rpc": { "host": "0.0.0.0", "port": 33145, "advertised_host": "127.0.0.1", "advertised_port": 33145, "tls_enabled": false, "mutual_tls_enabled": false }, "admin": [ { "name": "test_admin_listener", "host": "0.0.0.0", "port": 9644, "tls_enabled": false, "mutual_tls_enabled": false, "authentication_methods": [], "authorization_enabled": false } ] }, "alerts": [ { "affected_interface": "kafka", "listener_name": "test_kafka_listener", "issue": "NO_TLS", "description": "\"kafka\" interface \"test_kafka_listener\" is not using TLS. This is insecure and not recommended." }, { "affected_interface": "kafka", "listener_name": "test_kafka_listener", "issue": "NO_AUTHN", "description": "\"kafka\" interface \"test_kafka_listener\" is not using authentication. This is insecure and not recommended." }, { "affected_interface": "kafka", "listener_name": "test_kafka_listener", "issue": "NO_AUTHZ", "description": "\"kafka\" interface \"test_kafka_listener\" is not using authorization. This is insecure and not recommended." }, { "affected_interface": "rpc", "issue": "NO_TLS", "description": "\"rpc\" interface is not using TLS. This is insecure and not recommended." }, { "affected_interface": "admin", "listener_name": "test_admin_listener", "issue": "NO_TLS", "description": "\"admin\" interface \"test_admin_listener\" is not using TLS. This is insecure and not recommended." }, { "affected_interface": "admin", "listener_name": "test_admin_listener", "issue": "NO_AUTHZ", "description": "\"admin\" interface \"test_admin_listener\" is not using authorization. This is insecure and not recommended." }, { "affected_interface": "admin", "listener_name": "test_admin_listener", "issue": "NO_AUTHN", "description": "\"admin\" interface \"test_admin_listener\" is not using authentication. This is insecure and not recommended." } ] } ``` ## [](#suggested-reading)Suggested reading - [Deploy for Production](../k-production-deployment/) - [Customize the Helm Chart](../../../../manage/kubernetes/k-configure-helm-chart/) ## Suggested labs - [Disaster Recovery with Envoy and Shadowing](/redpanda-labs/docker-compose/envoy-shadowing/) - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Stream Jira Issues to Redpanda for Real-Time Metrics](/redpanda-labs/docker-compose/jira-metrics-pipeline/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Set Up GitOps for the Redpanda Helm Chart](/redpanda-labs/kubernetes/gitops-helm/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) - [Set Up MySQL CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-mysql-json/) - [Set Up Postgres CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-postgres-json/) See more [Search all labs](/redpanda-labs) --- # Page 43: Production Deployment Workflow for Kubernetes **URL**: https://docs.redpanda.com/current/deploy/redpanda/kubernetes/k-production-workflow.md --- # Production Deployment Workflow for Kubernetes --- title: Production Deployment Workflow for Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: redpanda/kubernetes/k-production-workflow page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: redpanda/kubernetes/k-production-workflow.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/redpanda/kubernetes/k-production-workflow.adoc description: Learn how to deploy Redpanda in Kubernetes for production. page-git-created-date: "2025-08-15" page-git-modified-date: "2026-02-06" support-status: supported --- The production deployment tasks involve Kubernetes administrators (admins) as well as Kubernetes users. 1. All: [Review the requirements and recommendations](../k-requirements/) to align on prerequisites. 2. Admin: [Tune the worker nodes](../k-tune-workers/) for best performance. 3. User: [Deploy Redpanda](../k-production-deployment/) using either the Redpanda Operator or the Redpanda Helm chart. 4. All: [Validate production readiness](../k-production-readiness/) using the comprehensive checklist to ensure your deployment meets production standards. ## Suggested labs - [Disaster Recovery with Envoy and Shadowing](/redpanda-labs/docker-compose/envoy-shadowing/) - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Stream Jira Issues to Redpanda for Real-Time Metrics](/redpanda-labs/docker-compose/jira-metrics-pipeline/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Set Up GitOps for the Redpanda Helm Chart](/redpanda-labs/kubernetes/gitops-helm/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) - [Set Up MySQL CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-mysql-json/) - [Set Up Postgres CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-postgres-json/) See more [Search all labs](/redpanda-labs) --- # Page 44: Kubernetes Cluster Requirements and Recommendations **URL**: https://docs.redpanda.com/current/deploy/redpanda/kubernetes/k-requirements.md --- # Kubernetes Cluster Requirements and Recommendations --- title: Kubernetes Cluster Requirements and Recommendations latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: redpanda/kubernetes/k-requirements page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: redpanda/kubernetes/k-requirements.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/redpanda/kubernetes/k-requirements.adoc description: A list of requirements and recommendations for provisioning Kubernetes clusters and worker nodes for running Redpanda in production. page-git-created-date: "2025-08-15" page-git-modified-date: "2026-02-06" support-status: supported --- This topic provides the requirements and recommendations for provisioning Kubernetes clusters and worker nodes for running Redpanda in production. ## [](#operating-system)Operating system - Minimum version required of RHEL/CentOS: 8. **Recommended**: 9+ - Minimum version required of Ubuntu: 20.04 LTS. **Recommended**: 22.04+ **Recommendation**: Linux kernel 4.19 or later for better performance. ## [](#kubernetes-version)Kubernetes version Minimum required Kubernetes version: 1.27.0-0 Make sure to do the following: 1. [Install kubectl](https://kubernetes.io/docs/tasks/tools/). 2. [Configure the `kubeconfig` file for your cluster](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/). ## [](#helm-version)Helm version Minimum required Helm version: 3.10.0 [Install Helm](https://helm.sh/docs/intro/install/). > 📝 **NOTE** > > Helm v3.18.0 is not supported due to a bug that causes errors such as: > > Error: INSTALLATION FAILED: execution error at (redpanda/templates/entry-point.yaml:17:4): invalid Quantity expected string or float64 got: json.Number (1) > > To avoid similar errors, upgrade to a later version. For more details, see the [Helm GitHub issue](https://github.com/helm/helm/issues/30880). ## [](#number-of-workers)Number of nodes Provision one physical node or virtual machine (VM) for each Redpanda broker that you plan to deploy in your Redpanda cluster. Each Redpanda broker requires its own dedicated node for the following reasons: - **Resource isolation**: Redpanda brokers are designed to make full use of available system resources, including CPU and memory. By dedicating a node to each broker, you ensure that these resources aren’t shared with other applications or processes, avoiding potential performance bottlenecks or contention. - **External networking**: External clients should connect directly to the broker that owns the partition they’re interested in. This means that each broker must be individually addressable. As clients must connect to the specific broker that is the leader of the partition, they need a mechanism to directly address each broker in the cluster. Assigning each broker to its own dedicated node makes this direct addressing feasible, since each node will have a unique address. See [External networking](#external-networking). - **Fault tolerance**: Ensuring each broker operates on a separate node enhances fault tolerance. If one node experiences issues, it won’t directly impact the other brokers. > 📝 **NOTE** > > The Redpanda Helm chart configures [`podAntiAffinity` rules](../../../../reference/k-redpanda-helm-spec/#statefulset-podantiaffinity) to make sure that each Redpanda broker runs on its own node. **Recommendations**: Deploy at least three Pod replicas. ## [](#node-updates)Prevent automatic node upgrades Ensure that node and operating system (OS) upgrades are manually managed when running Redpanda in production. Manual control avoids unplanned reboots or replacements that disrupt Redpanda brokers, causing service downtime, data loss, or quorum instability. Common issues with automatic node upgrades include: - Hard timeouts for graceful shutdowns that do not allow Redpanda brokers enough time to complete decommissioning or leadership transitions. - Replacements or reboots without ensuring data has been safely migrated or replicated, risking data loss. - Parallel upgrades across multiple nodes, which can disrupt quorum or reduce cluster availability. **Requirements**: - Disable automatic node maintenance or upgrades. To prevent managed Kubernetes services from automatically rebooting or upgrading nodes: - **Azure AKS**: [Set the OS upgrade channel to `None`](https://learn.microsoft.com/en-us/azure/aks/auto-upgrade-node-os-image). - **Google GKE**: [Disable GKE auto-upgrades for node pools](https://cloud.google.com/kubernetes-engine/docs/how-to/node-auto-upgrades). - **Amazon EKS**: [Disable EKS node auto-upgrades](https://docs.aws.amazon.com/eks/latest/userguide/automode.html). See also: [How to manually manage node upgrades](../../../../upgrade/k-upgrade-kubernetes/). ## [](#cpu-and-memory)CPU and memory **Requirements**: - Each node must have at least two physical CPU cores. - x86\_64 (Westmere or newer) and AWS Graviton processors are supported. - Each Redpanda Pod requires at least 2 GiB of memory per core. - Request a minimum of 2.22 GiB per core to meet Redpanda’s memory allocation strategy. See [Manage Pod Resources in Kubernetes](../../../../manage/kubernetes/k-manage-resources/) for detailed guidance and examples. - Each Redpanda broker must have at least 2 GB of memory per core. - Each Redpanda broker must have at least 2 MB of memory for each topic partition replica. The total memory available for partition replicas is determined as a percentage of the cluster’s total memory, which is controlled by the [`topic_partitions_memory_allocation_percent`](../../../../reference/properties/cluster-properties/#topic_partitions_memory_allocation_percent) setting. Each partition replica consumes [`topic_memory_per_partition`](../../../../reference/properties/cluster-properties/#topic_memory_per_partition) bytes from this pool. If insufficient memory is available, topic operations will fail. You can adjust the allocation ratio using `topic_partitions_memory_allocation_percent`, but doing so is not recommended, as lowering it may lead to instability or degraded performance. **Recommendations**: - Four physical cores for each node are strongly recommended. ## [](#pod-resource-configuration)Pod resource configuration To ensure stable performance and predictable scheduling in Kubernetes, configure Redpanda Pods with appropriate CPU and memory requests and limits: - Set `resources.requests.memory` and `resources.limits.memory` to the same value. - Request at least 2.22 GiB of memory per core to meet Redpanda’s heap and overhead requirements. - Set `resources.cpu.cores` to an even integer (for example, `4`, `6`, or `8`) to align with the Kubernetes static CPU manager policy. - Match CPU and memory resource settings for all containers in the Pod, including init containers and sidecars, to receive the `Guaranteed` QoS class. - Enable memory locking with the `--lock-memory` flag to prevent paging and improve performance. This configuration: - Grants Redpanda exclusive access to CPU cores and memory - Reduces the risk of throttling, eviction, and OOM kills - Provides predictable and isolated runtime performance See [Manage Pod Resources in Kubernetes](../../../../manage/kubernetes/k-manage-resources/) for configuration examples using both Helm and the Redpanda Operator. ## [](#storage)Storage **Requirements**: - NVMe (Non-Volatile Memory Express) drives are required for production deployments. NVMe drives provide the high throughput and low latency needed for optimal Redpanda performance. - At least 16,000 IOPS (Input/Output Operations Per Second). See also: [Disk and network self-test benchmarks](../../../../troubleshoot/cluster-diagnostics/diagnose-issues/#self-test). - An XFS or ext4 file system. The Redpanda data directory (`/var/lib/redpanda/data`) and the Tiered Storage cache must be mounted on an XFS or ext4 file system. For information about supported volume types for different data in Redpanda, see [Supported Volume Types for Data in Redpanda](../../../../manage/kubernetes/storage/k-volume-types/). > ⚠️ **CAUTION** > > The Network File System (NFS) is unsupported for use as the storage mechanism for the Redpanda data directory or for the Tiered Storage cache. - A default StorageClass that can provision PersistentVolumes with at least 20Gi of storage. **Recommendations**: - Use an XFS file system for its enhanced performance with Redpanda workloads. - For setups with multiple disks, use a RAID-0 (striped) array. It boosts speed but lacks redundancy. A disk failure can lead to data loss. - Use local PersistentVolumes backed by NVMe disks. ## [](#security)Security **Recommendations**: - If you’re using a cloud platform, use [IAM roles](../../../../manage/security/iam-roles/) to restrict access to resources in your cluster. - Secure your Redpanda cluster with TLS encryption and SASL authentication. ## [](#external-networking)External networking - For external access, each node in your cluster must have a static, externally accessible IP address. - Minimum 10 GigE (10 Gigabit Ethernet) connection to ensure: - High data throughput - Reduced data transfer latency - Scalability for increased network traffic **Recommendations**: [Use a NodePort Service for external access](../k-production-deployment/#external-access). ## [](#tuning)Tuning Before deploying Redpanda to production, each node that runs Redpanda must be tuned to optimize the Linux kernel for Redpanda processes. As part of your system tuning, be aware that enabling SELinux (Security-Enhanced Linux) can introduce performance overhead. If SELinux is not required for your environment, Redpanda Data recommends disabling it for optimal performance. See [Tune Kubernetes Worker Nodes for Production](../k-tune-workers/). ## [](#object-storage-providers-for-tiered-storage)Object storage providers for Tiered Storage Redpanda supports the following storage providers for Tiered Storage: - Amazon Simple Storage Service (S3) - Google Cloud Storage (GCS), using the Google Cloud Platform S3 API - Azure Blob Storage (ABS) ## [](#cloud-instance-types)Cloud instance types **Recommendations**: - Use a cloud instance type that supports locally attached NVMe devices with an XFS file system. NVMe devices offer high I/O operations per second (IOPS) and minimal latency, while XFS offers enhanced performance with Redpanda workloads. ### [](#amazon)Amazon EKS defaults to the ext4 file system. Use XFS instead where possible. - General purpose: General-purpose instances provide a balance of compute, memory, and networking resources, and they can be used for a variety of diverse workloads. - [M5d](https://aws.amazon.com/ec2/instance-types/m5/) - [M5ad](https://aws.amazon.com/ec2/instance-types/m5/) - [M5dn](https://aws.amazon.com/ec2/instance-types/m5/) - [M6gd](https://aws.amazon.com/ec2/instance-types/m6g/) - [M7gd](https://aws.amazon.com/ec2/instance-types/m7g/) - Memory optimized: Memory-optimized instances are designed to deliver fast performance for workloads that process large data sets in memory. - [R5ad](https://aws.amazon.com/ec2/instance-types/r5/) - [R5d](https://aws.amazon.com/ec2/instance-types/r5/) - [R5dn](https://aws.amazon.com/ec2/instance-types/r5/) - [R6gd](https://aws.amazon.com/ec2/instance-types/r6g/) - [R6id](https://aws.amazon.com/ec2/instance-types/r6i/) - [R6idn](https://aws.amazon.com/ec2/instance-types/r6i/) - [R7gd](https://aws.amazon.com/ec2/instance-types/r7g/) - [X2gd](https://aws.amazon.com/ec2/instance-types/x2/) - [X2idn](https://aws.amazon.com/ec2/instance-types/x2i/) - [X2iedn](https://aws.amazon.com/ec2/instance-types/x2i/) - [z1d](https://aws.amazon.com/ec2/instance-types/z1d/) - Storage optimized: Storage-optimized instances are designed for workloads that require high, sequential read and write access to very large data sets on local storage. They are optimized to deliver tens of thousands of low-latency, random IOPS to applications. - [I4g, Is4gen, Im4gn](https://aws.amazon.com/ec2/instance-types/i4g/) - [I4i](https://aws.amazon.com/ec2/instance-types/i4i/) - [I3](https://aws.amazon.com/ec2/instance-types/i3/) - [I3en](https://aws.amazon.com/ec2/instance-types/i3en/) - Compute optimized: Compute-optimized instances deliver cost-effective high performance at a low price per compute ratio for running advanced compute-intensive workloads. - [C5d](https://aws.amazon.com/ec2/instance-types/c5/) - [C5ad](https://aws.amazon.com/ec2/instance-types/c5/) ### [](#azure)Azure AKS often defaults to the ext4 file system. Use XFS instead where possible. - General purpose: General purpose VM sizes provide balanced CPU-to-memory ratio. Ideal for testing and development, small to medium databases, and low to medium traffic web servers. - [Standard\_D2d\_v5](https://learn.microsoft.com/en-us/azure/virtual-machines/sizes/general-purpose/ddv5-series?tabs=sizebasic) - [Standard\_D4d\_v5](https://learn.microsoft.com/en-us/azure/virtual-machines/sizes/general-purpose/ddv5-series?tabs=sizebasic) - [Standard\_D32d\_v5](https://learn.microsoft.com/en-us/azure/virtual-machines/sizes/general-purpose/ddv5-series?tabs=sizebasic) ### [](#google)Google GKE often defaults to the ext4 file system. Use XFS instead where possible. - General purpose: The general-purpose machine family has the best price-performance with the most flexible vCPU to memory ratios, and provides features that target most standard and cloud-native workloads. - [C3 machine series with local SSD](https://cloud.google.com/compute/docs/general-purpose-machines#c3-with-local-ssd) - [N2 machine series](https://cloud.google.com/compute/docs/general-purpose-machines#n2_series) - [N2D machine series](https://cloud.google.com/compute/docs/general-purpose-machines#n2d_machines) - Memory optimized: The memory-optimized machine family provides the most compute and memory resources of any Compute Engine machine family offering. They are ideal for workloads that require higher memory-to-vCPU ratios than the high-memory machine types in the general-purpose N1 machine series. - [M3 machine series](https://cloud.google.com/compute/docs/memory-optimized-machines#m3_series) - Compute optimized: Compute-optimized VM instances are ideal for compute-intensive and high-performance computing (HPC) workloads. - [C2D machine series](https://cloud.google.com/compute/docs/compute-optimized-machines#c2d_series) - [C2 machine series](https://cloud.google.com/compute/docs/compute-optimized-machines#c2_machine_types) ## [](#next-steps)Next steps After meeting these requirements, proceed to: - [Deploy Redpanda for production](../k-production-deployment/) - [Validate production readiness](../k-production-readiness/) with the comprehensive checklist ## [](#suggested-reading)Suggested reading - [Redpanda Helm Specification](../../../../reference/k-redpanda-helm-spec/) - [Redpanda CRD Reference](../../../../reference/k-crd/) - [Sizing Guidelines](../../manual/sizing/) - Resources for Kubernetes managed services: ### GKE - [Local SSDs](https://cloud.google.com/compute/docs/disks/local-ssd) - [About local SSDs for GKE](https://cloud.google.com/kubernetes-engine/docs/concepts/local-ssd) - [Provision ephemeral storage with local SSDs](https://cloud.google.com/kubernetes-engine/docs/how-to/persistent-volumes/local-ssd) ### EKS - [Instance store volumes](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-store-volumes.html) - [Choosing an Amazon EC2 instance type](https://docs.aws.amazon.com/eks/latest/userguide/choosing-instance-type.html) - [EKS Persistent Volumes for Instance Store](https://aws.amazon.com/blogs/containers/eks-persistent-volumes-for-instance-store/) ### AKS - [AKS storage](https://docs.microsoft.com/en-us/azure/aks/concepts-storage) - [Using NVMe instances in Azure Kubernetes Service](https://medium.com/cooking-with-azure/using-nvm-e-instances-in-azure-kubernetes-service-40c587dbd67b) ## Suggested labs - [Disaster Recovery with Envoy and Shadowing](/redpanda-labs/docker-compose/envoy-shadowing/) - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Stream Jira Issues to Redpanda for Real-Time Metrics](/redpanda-labs/docker-compose/jira-metrics-pipeline/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Set Up GitOps for the Redpanda Helm Chart](/redpanda-labs/kubernetes/gitops-helm/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) - [Set Up MySQL CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-mysql-json/) - [Set Up Postgres CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-postgres-json/) See more [Search all labs](/redpanda-labs) --- # Page 45: Tune Kubernetes Worker Nodes for Production **URL**: https://docs.redpanda.com/current/deploy/redpanda/kubernetes/k-tune-workers.md --- # Tune Kubernetes Worker Nodes for Production --- title: Tune Kubernetes Worker Nodes for Production latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: redpanda/kubernetes/k-tune-workers page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: redpanda/kubernetes/k-tune-workers.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/redpanda/kubernetes/k-tune-workers.adoc description: To get the best performance from your hardware, set Redpanda to production mode and run the autotuner tool. The autotuner identifies your hardware configuration and tunes itself to give you the best performance. page-git-created-date: "2025-08-15" page-git-modified-date: "2025-08-15" support-status: supported --- To get the best performance from your hardware, set Redpanda to production mode on each worker node and run the [autotuner tool](../../../../reference/rpk/rpk-redpanda/rpk-redpanda-tune/). The autotuner identifies the hardware configuration of your worker node and optimizes the Linux kernel to give you the best performance. ## [](#prerequisites)Prerequisites Make sure that your current Linux user has root privileges. The autotuner requires privileged access to the Linux kernel settings. ## [](#install-redpanda)Install Redpanda To run the autotuner, you need to install the Redpanda binary on each worker node. ### Fedora/RedHat ```bash # Run the setup script to download and install the repo curl -1sLf 'https://dl.redpanda.com/nzc4ZYQK3WRGd9sy/redpanda/cfg/setup/bash.rpm.sh' | sudo -E bash && \ # Use yum to install redpanda sudo yum install redpanda -y ``` ### Debian/Ubuntu ```bash # Run the setup script to download and install the repo curl -1sLf 'https://dl.redpanda.com/nzc4ZYQK3WRGd9sy/redpanda/cfg/setup/bash.deb.sh' | sudo -E bash && \ # Use apt to install redpanda sudo apt install redpanda -y ``` ## [](#run-the-autotuner)Run the autotuner To tune the Linux kernel of your worker nodes, run the autotuner on each worker node that will host a Redpanda broker. 1. Set Redpanda to production mode: ```bash sudo rpk redpanda mode production ``` 2. Run the autotuner: ```bash sudo rpk redpanda tune all ``` Expected output: ```none TUNER APPLIED ENABLED SUPPORTED ERROR aio_events true true true ballast_file true true true clocksource true true true coredump false false true cpu true true true disk_irq true true true disk_nomerges true true true disk_scheduler true true true disk_write_cache false true false Disk write cache tuner is only supported in GCP fstrim false false true net true true true swappiness true true true transparent_hugepages false false true ``` Changes to the Linux kernel are not persisted. If a worker node restarts, make sure to run `sudo rpk redpanda tune all` on it again. > 💡 **TIP** > > You can use a privileged DaemonSet to schedule the autotuner on each worker node that runs a Redpanda broker. Apply taints to Nodes that successfully complete the autotuner command. Use tolerations on your Pods so that they are scheduled only on tuned worker nodes. For details about the autotuner, including how to enable or disable an individual tuner, see the [rpk redpanda tune](../../../../reference/rpk/rpk-redpanda/rpk-redpanda-tune/) command reference. ## [](#io)Generate optimal I/O configuration settings After tuning the Linux kernel, you can optimize Redpanda for the I/O capabilities of your worker node by using `rpk` to run benchmarks that capture its read/write IOPS and bandwidth capabilities. After running the benchmarks `rpk` saves the results to an I/O configuration file (`io-config.yaml`) that Redpanda can read upon startup to optimize itself for the worker node. > 📝 **NOTE** > > Unlike the autotuner, it isn’t necessary to run `rpk iotune` each time Redpanda is started, as its I/O output configuration file can be reused for each worker node that runs on the same type of hardware. 1. Run the I/O benchmark on your worker node: ```bash rpk iotune ``` Example output: `/etc/redpanda/io-config.yaml` ```yaml disks: - mountpoint: / read_iops: 40952 read_bandwidth: 5638210048 write_iops: 6685 write_bandwidth: 1491679488 ``` When this command is successful, the I/O configuration file is saved to `/etc/redpanda/io-config.yaml` by default. 2. Copy the file to your local machine. 3. Create a ConfigMap in the same namespace in which you will deploy Redpanda to store the I/O configuration file: ```bash kubectl create configmap redpanda-io-config --namespace --from-file= ``` You will mount this file onto the Pods that run Redpanda so that Redpanda can read it at startup. See [Deploy Redpanda for Production in Kubernetes](../k-production-deployment/). For more details about this procedure, see [Optimize I/O](../../../../manage/io-optimization/). ## [](#next-steps)Next steps [Deploy the Redpanda cluster](../k-production-deployment/). ## Suggested labs - [Disaster Recovery with Envoy and Shadowing](/redpanda-labs/docker-compose/envoy-shadowing/) - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Stream Jira Issues to Redpanda for Real-Time Metrics](/redpanda-labs/docker-compose/jira-metrics-pipeline/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Set Up GitOps for the Redpanda Helm Chart](/redpanda-labs/kubernetes/gitops-helm/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) - [Set Up MySQL CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-mysql-json/) - [Set Up Postgres CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-postgres-json/) See more [Search all labs](/redpanda-labs) --- # Page 46: Deploy a Local Development Cluster with kind or minikube **URL**: https://docs.redpanda.com/current/deploy/redpanda/kubernetes/local-guide.md --- # Deploy a Local Development Cluster with kind or minikube --- title: Deploy a Local Development Cluster with kind or minikube latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: redpanda/kubernetes/local-guide page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: redpanda/kubernetes/local-guide.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/redpanda/kubernetes/local-guide.adoc description: Deploy a local Redpanda cluster with Redpanda Console using the Helm chart. page-git-created-date: "2025-08-15" page-git-modified-date: "2025-08-15" support-status: supported --- Deploy a local Redpanda cluster with Redpanda Console using the Helm chart. Explore the essentials of how Redpanda works in Kubernetes and what components are deployed by default. Then, use `rpk` both as an internal client and an external client to interact with your Redpanda cluster from the command line. > ⚠️ **CAUTION: Only for development and testing** > > Only for development and testing > > Do not use kind or minikube for production workloads. Instead, try one of the following environments: > > - [Azure Kubernetes Service](../aks-guide/) (AKS) > > - [Elastic Kubernetes Service](../eks-guide/) (EKS) > > - [Google Kubernetes Engine](../gke-guide/) (GKE) ## [](#prerequisites)Prerequisites Before you begin, make sure that you have the correct software for your Kubernetes platform: ### kind - [Install `kubectl`](https://kubernetes.io/docs/tasks/tools/). Minimum required Kubernetes version: 1.27.0-0 ```bash kubectl version --client ``` - [Install Helm](https://helm.sh/docs/intro/install/). Minimum required Helm version: 3.10.0 ```bash helm version ``` - [Install kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) - [Install Docker](https://docs.docker.com/get-docker/) ### minikube - [Install `kubectl`](https://kubernetes.io/docs/tasks/tools/). Minimum required Kubernetes version: 1.27.0-0 ```bash kubectl version --client ``` - [Install Helm](https://helm.sh/docs/intro/install/). Minimum required Helm version: 3.10.0 ```bash helm version ``` - [Install minikube](https://minikube.sigs.k8s.io/docs/start/) ## [](#create-a-kubernetes-cluster)Create a Kubernetes cluster In this step, you create one master and three worker nodes (one worker node for each Redpanda broker). ### kind 1. Define a cluster in the `kind.yaml` configuration file: ```bash cat <kind.yaml --- apiVersion: kind.x-k8s.io/v1alpha4 kind: Cluster nodes: - role: control-plane - role: worker - role: worker - role: worker EOF ``` 2. Create the Kubernetes cluster from the configuration file: ```bash kind create cluster --config kind.yaml ``` ### minikube 1. Create the Kubernetes cluster: ```bash minikube start --nodes 4 ``` 2. Prevent applications from being scheduled on the Kubernetes control plane node: ```bash kubectl taint node \ -l node-role.kubernetes.io/control-plane="" \ node-role.kubernetes.io/control-plane=:NoSchedule ``` > 📝 **NOTE** > > The Helm chart configures default `podAntiAffinity` rules to make sure that only one Pod running a Redpanda broker is scheduled on each worker node. To learn why, see [Number of workers](../k-requirements/#number-of-workers). ## [](#deploy-redpanda-and-redpanda-console)Deploy Redpanda and Redpanda Console In this step, you deploy Redpanda with self-signed TLS certificates. Redpanda Console is included as a subchart in the Redpanda Helm chart. ### Operator 1. Make sure that you have permission to install custom resource definitions (CRDs): ```bash kubectl auth can-i create CustomResourceDefinition --all-namespaces ``` You should see `yes` in the output. You need these cluster-level permissions to install [cert-manager](https://cert-manager.io/docs/) and Redpanda Operator CRDs in the next steps. 2. Install [cert-manager](https://cert-manager.io/docs/installation/helm/) using Helm: ```bash helm repo add jetstack https://charts.jetstack.io helm repo update helm install cert-manager jetstack/cert-manager --set crds.enabled=true --namespace cert-manager --create-namespace ``` TLS is enabled by default. The Redpanda Helm chart uses cert-manager to manage TLS certificates by default. 3. Deploy the Redpanda Operator: 1. To deploy in cluster scope, use: ```bash helm repo add redpanda https://charts.redpanda.com helm repo update helm upgrade --install redpanda-controller redpanda/operator \ --namespace \ --create-namespace \ --version v26.1.2 \ (1) --set crds.enabled=true (2) ``` | 1 | This flag specifies the exact version of the Redpanda Operator Helm chart to use for deployment. By setting this value, you pin the chart to a specific version, which prevents automatic updates that might introduce breaking changes or new features that have not been tested in your environment. | | --- | --- | | 2 | This flag ensures that the CRDs are installed as part of the Redpanda Operator deployment.This command deploys the Redpanda Operator in cluster scope (default in v25.2+), allowing it to manage Redpanda clusters across multiple namespaces. | 2. To deploy in namespace scope (managing only resources within its deployment namespace), use: ```bash helm upgrade --install redpanda-controller redpanda/operator \ --namespace \ --create-namespace \ --version v26.1.2 \ --set crds.enabled=true \ --set 'additionalCmdFlags=["--namespace="]' (1) ``` | 1 | This flag restricts the Redpanda Operator to manage resources only within the specified namespace. | | --- | --- | 4. Ensure that the Deployment is successfully rolled out: ```bash kubectl --namespace rollout status --watch deployment/redpanda-controller-operator ``` deployment "redpanda-controller-operator" successfully rolled out 5. Install a [Redpanda custom resource](../../../../reference/k-crd/) in the same namespace as the Redpanda Operator: `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: clusterSpec: external: domain: customredpandadomain.local statefulset: initContainers: setDataDirOwnership: enabled: true ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` 6. Wait for the Redpanda Operator to deploy Redpanda using the Helm chart: ```bash kubectl get redpanda --namespace --watch ``` NAME READY STATUS redpanda True Redpanda reconciliation succeeded This step may take a few minutes. You can watch for new Pods to make sure that the deployment is progressing: ```bash kubectl get pod --namespace ``` If it’s taking too long, see [Troubleshoot](#troubleshoot). ### Helm 1. Add the Redpanda Helm chart repository and install cert-manager using Helm: ```bash helm repo add redpanda https://charts.redpanda.com helm repo add jetstack https://charts.jetstack.io helm repo update helm install cert-manager jetstack/cert-manager --set crds.enabled=true --namespace cert-manager --create-namespace ``` The Redpanda Helm chart uses cert-manager to manage TLS certificates. 2. Install Redpanda using Helm: ```bash helm repo add redpanda https://charts.redpanda.com/ helm repo update helm install redpanda redpanda/redpanda \ --version 26.1.2 \ --namespace \ --create-namespace \ --set external.domain=customredpandadomain.local \ --set statefulset.initContainers.setDataDirOwnership.enabled=true ``` The installation displays some tips for getting started. 3. Wait for the Redpanda cluster to be ready: ```bash kubectl --namespace rollout status statefulset redpanda --watch ``` When the Redpanda cluster is ready, the output should look similar to the following: ```plain statefulset rolling update complete 3 pods at revision redpanda-8654f645b4... ``` If your cluster remains in a pending state, see [Troubleshoot](#troubleshoot). ## [](#start-streaming)Start streaming Each Redpanda broker comes with `rpk`, which is a CLI tool for connecting to and interacting with Redpanda brokers. You can use `rpk` inside one of the Redpanda broker’s Docker containers to create a topic, produce messages to it, and consume messages from it. 1. Create an alias to simplify the `rpk` commands: ```bash alias internal-rpk="kubectl --namespace exec -i -t redpanda-0 -c redpanda -- rpk" ``` 2. Create a topic called `twitch-chat`: ### Operator 1. Create a [Topic resource](../../../../manage/kubernetes/k-manage-topics/): `topic.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Topic metadata: name: twitch-chat spec: kafkaApiSpec: brokers: - "redpanda-0.redpanda..svc.cluster.local:9093" - "redpanda-1.redpanda..svc.cluster.local:9093" - "redpanda-2.redpanda..svc.cluster.local:9093" tls: caCertSecretRef: name: "redpanda-default-cert" key: "ca.crt" ``` 2. Apply the Topic resource in the same namespace as your Redpanda cluster: ```bash kubectl apply -f topic.yaml --namespace ``` 3. Check the logs of the Redpanda Operator to confirm that the topic was created: ```bash kubectl logs -l app.kubernetes.io/name=operator -c manager --namespace ``` You should see that the Redpanda Operator reconciled the Topic resource. Example output ```json { "level":"info", "ts":"2023-09-25T16:20:09.538Z", "logger":"TopicReconciler.Reconcile", "msg":"Starting reconcile loop", "controller":"topic", "controllerGroup":"cluster.redpanda.com", "controllerKind":"Topic", "Topic": { "name":"twitch-chat", "namespace":"" }, "namespace":"", "name":"twitch-chat", "reconcileID":"c0cf9abc-a553-48b7-9b6e-2de3cdfb4432" } { "level":"info", "ts":"2023-09-25T16:20:09.581Z", "logger":"TopicReconciler.Reconcile", "msg":"reconciliation finished in 43.436125ms, next run in 3s", "controller":"topic", "controllerGroup":"cluster.redpanda.com", "controllerKind":"Topic", "Topic": { "name":"twitch-chat", "namespace":"" }, "namespace":"", "name":"twitch-chat", "reconcileID":"c0cf9abc-a553-48b7-9b6e-2de3cdfb4432", "result": { "Requeue":false, "RequeueAfter":3000000000 } } ``` ### Helm ```bash internal-rpk topic create twitch-chat ``` Example output: TOPIC STATUS twitch-chat OK 3. Describe the topic: ```bash internal-rpk topic describe twitch-chat ``` Expected output: ```none SUMMARY ======= NAME twitch-chat PARTITIONS 1 REPLICAS 1 CONFIGS ======= KEY VALUE SOURCE cleanup.policy delete DYNAMIC_TOPIC_CONFIG compression.type producer DEFAULT_CONFIG message.timestamp.type CreateTime DEFAULT_CONFIG partition_count 1 DYNAMIC_TOPIC_CONFIG redpanda.datapolicy function_name: script_name: DEFAULT_CONFIG redpanda.remote.read false DEFAULT_CONFIG redpanda.remote.write false DEFAULT_CONFIG replication_factor 1 DYNAMIC_TOPIC_CONFIG retention.bytes -1 DEFAULT_CONFIG retention.ms 604800000 DEFAULT_CONFIG segment.bytes 1073741824 DEFAULT_CONFIG ``` 4. Produce a message to the topic: ```bash internal-rpk topic produce twitch-chat ``` 5. Type a message, then press Enter: ```text Pandas are fabulous! ``` Example output: ```text Produced to partition 0 at offset 0 with timestamp 1663282629789. ``` 6. Press Ctrl+C to finish producing messages to the topic. 7. Consume one message from the topic: ```bash internal-rpk topic consume twitch-chat --num 1 ``` Expected output: Your message is displayed along with its metadata: ```json { "topic": "twitch-chat", "value": "Pandas are fabulous!", "timestamp": 1663282629789, "partition": 0, "offset": 0 } ``` ## [](#explore-your-topic-in-redpanda-console)Explore your topic in Redpanda Console Redpanda Console is a developer-friendly web UI for managing and debugging your Redpanda cluster and your applications. In this step, you use port-forwarding to access Redpanda Console on your local network. > 💡 **TIP** > > Because you’re using the Community Edition of Redpanda Console, you should not expose Redpanda Console outside your local network. The Community Edition of Redpanda Console does not provide authentication, and it connects to the Redpanda cluster as superuser. To use the Enterprise Edition, you need a license key. See [Redpanda Licensing](../../../../get-started/licensing/). 1. Expose Redpanda Console to your localhost: ```bash kubectl --namespace port-forward svc/redpanda-console 8080:8080 ``` The `kubectl port-forward` command actively runs in the command-line window. To execute other commands while the command is running, open another command-line window. 2. Open Redpanda Console on [http://localhost:8080](http://localhost:8080). All your Redpanda brokers are listed along with their IP addresses and IDs. 3. Go to **Topics** > **twitch-chat**. The message that you produced to the topic is displayed along with some other details about the topic. 4. Press Ctrl+C in the command-line to stop the port-forwarding process. ## [](#configure-external-access-to-redpanda)Configure external access to Redpanda If you want to connect to the Redpanda cluster with external clients, Redpanda brokers must advertise an externally accessible address that external clients can connect to. External clients are common in Internet of Things (IoT) environments, or if you use external services that do not implement VPC peering in your network. When you created the cluster, you set the `external.domain` configuration to `customredpandadomain.local`, which means that your Redpanda brokers are advertising the following addresses: - `redpanda-0.customredpandadomain.local` - `redpanda-1.customredpandadomain.local` - `redpanda-2.customredpandadomain.local` To access your Redpanda brokers externally, you can map your worker nodes' IP addresses to these domains. > ⚠️ **CAUTION** > > IP addresses can change. If the IP addresses of your worker nodes change, you must update your `/etc/hosts` file with the new mappings. > > In a production environment, it’s a best practice to use ExternalDNS to manage DNS records for your brokers. See [Use ExternalDNS for external access](../k-requirements/#use-externaldns-for-external-access). > 📝 **NOTE** > > These steps work only on Linux operating systems. 1. Add mappings in your `/etc/hosts` file between your worker nodes' IP addresses and their custom domain names: ```bash sudo true && kubectl --namespace get endpoints,node -A -o go-template='{{ range $_ := .items }}{{ if and (eq .kind "Endpoints") (eq .metadata.name "redpanda-external") }}{{ range $_ := (index .subsets 0).addresses }}{{ $nodeName := .nodeName }}{{ $podName := .targetRef.name }}{{ range $node := $.items }}{{ if and (eq .kind "Node") (eq .metadata.name $nodeName) }}{{ range $_ := .status.addresses }}{{ if eq .type "InternalIP" }}{{ .address }} {{ $podName }}.customredpandadomain.local{{ "\n" }}{{ end }}{{ end }}{{ end }}{{ end }}{{ end }}' | envsubst | sudo tee -a /etc/hosts ``` `/etc/hosts` 203.0.113.3 redpanda-0.customredpandadomain.local 203.0.113.5 redpanda-1.customredpandadomain.local 203.0.113.7 redpanda-2.customredpandadomain.local 2. Save the root certificate authority (CA) to your local file system outside Kubernetes: ```bash kubectl --namespace get secret redpanda-external-root-certificate -o go-template='{{ index .data "ca.crt" | base64decode }}' > ca.crt ``` 3. Install `rpk` on your local Linux machine, not on a Pod: ### amd64 ```bash curl -LO https://github.com/redpanda-data/redpanda/releases/latest/download/rpk-linux-amd64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-linux-amd64.zip -d ~/.local/bin/ ``` ### arm64 ```bash curl -LO https://github.com/redpanda-data/redpanda/releases/latest/download/rpk-linux-arm64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-linux-arm64.zip -d ~/.local/bin/ ``` > 💡 **TIP** > > You can use `rpk` on Windows only with [WSL](https://learn.microsoft.com/windows/wsl/install). However, commands that require Redpanda to be installed on your machine are not supported, such as [`rpk container`](../../../../reference/rpk/rpk-container/rpk-container/) commands, [`rpk iotune`](../../../../reference/rpk/rpk-iotune/), and [`rpk redpanda`](../../../../reference/rpk/rpk-redpanda/rpk-redpanda/) commands. 4. Configure `rpk` to connect to your cluster using the [pre-configured profile](../../../../manage/kubernetes/networking/k-connect-to-redpanda/#rpk-profile): ```bash rpk profile create --from-profile <(kubectl get configmap --namespace redpanda-rpk -o go-template='{{ .data.profile }}') ``` Replace `` with the name that you want to give this `rpk` profile. 5. Test the connection: ```bash rpk cluster info ``` ## [](#explore-the-default-kubernetes-components)Explore the default Kubernetes components By default, the Redpanda Helm chart deploys the following Kubernetes components: - [A StatefulSet](#statefulset) with three Pods. - [One PersistentVolumeClaim](#persistentvolumeclaim) for each Pod, each with a capacity of 20Gi. - [A headless ClusterIP Service and a NodePort Service](#service) for each Kubernetes node that runs a Redpanda broker. - [Self-Signed TLS Certificates](#tls-certificates). ### [](#statefulset)StatefulSet Redpanda is a stateful application. Each Redpanda broker needs to store its own state (topic partitions) in its own storage volume. As a result, the Helm chart deploys a StatefulSet to manage the Pods in which the Redpanda brokers are running. ```bash kubectl get statefulset --namespace ``` Example output: NAME READY AGE redpanda 3/3 3m11s StatefulSets ensure that the state associated with a particular Pod replica is always the same, no matter how often the Pod is recreated. Each Pod is also given a unique ordinal number in its name such as `redpanda-0`. A Pod with a particular ordinal number is always associated with a PersistentVolumeClaim with the same number. When a Pod in the StatefulSet is deleted and recreated, it is given the same ordinal number and so it mounts the same storage volume as the deleted Pod that it replaced. ```bash kubectl get pod --namespace ``` Expected output: ```none NAME READY STATUS RESTARTS AGE redpanda-0 1/1 Running 0 6m9s redpanda-1 1/1 Running 0 6m9s redpanda-2 1/1 Running 0 6m9s redpanda-console-5ff45cdb9b-6z2vs 1/1 Running 0 5m redpanda-configuration-smqv7 0/1 Completed 0 6m9s ``` > 📝 **NOTE** > > The `redpanda-configuration` job updates the Redpanda runtime configuration. ### [](#persistentvolumeclaim)PersistentVolumeClaim Redpanda brokers must be able to store their data on disk. By default, the Helm chart uses the default StorageClass in the Kubernetes cluster to create a PersistentVolumeClaim for each Pod. The default StorageClass in your Kubernetes cluster depends on the Kubernetes platform that you are using. ```bash kubectl get persistentvolumeclaims --namespace ``` Expected output: ```none NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE datadir-redpanda-0 Bound pvc-3311ade3-de84-4027-80c6-3d8347302962 20Gi RWO standard 75s datadir-redpanda-1 Bound pvc-4ea8bc03-89a6-41e4-b985-99f074995f08 20Gi RWO standard 75s datadir-redpanda-2 Bound pvc-45c3555f-43bc-48c2-b209-c284c8091c45 20Gi RWO standard 75s ``` ### [](#service)Service The clients writing to or reading from a given partition have to connect directly to the leader broker that hosts the partition. As a result, clients need to be able to connect directly to each Pod. To allow internal and external clients to connect to each Pod that hosts a Redpanda broker, the Helm chart configures two Services: - Internal using the [Headless ClusterIP](#headless-clusterip-service) - External using the [NodePort](#nodeport-service) ```bash kubectl get service --namespace ``` Expected output: ```none NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE redpanda ClusterIP None 5m37s redpanda-console ClusterIP 10.0.251.204 8080 5m redpanda-external NodePort 10.96.137.220 9644:31644/TCP,9094:31092/TCP,8083:30082/TCP,8080:30081/TCP 5m37s ``` #### [](#headless-clusterip-service)Headless ClusterIP Service The headless Service associated with a StatefulSet gives the Pods their network identity in the form of a fully qualified domain name (FQDN). Both Redpanda brokers in the same Redpanda cluster and clients within the same Kubernetes cluster use this FQDN to communicate with each other. An important requirement of distributed applications such as Redpanda is peer discovery: The ability for each broker to find other brokers in the same cluster. When each Pod is rolled out, its `seed_servers` field is updated with the FQDN of each Pod in the cluster so that they can discover each other. ```bash kubectl --namespace exec redpanda-0 -c redpanda -- cat etc/redpanda/redpanda.yaml ``` ```yaml redpanda: data_directory: /var/lib/redpanda/data empty_seed_starts_cluster: false seed_servers: - host: address: redpanda-0.redpanda..svc.cluster.local. port: 33145 - host: address: redpanda-1.redpanda..svc.cluster.local. port: 33145 - host: address: redpanda-2.redpanda..svc.cluster.local. port: 33145 ``` #### [](#nodeport-service)NodePort Service External access is made available by a NodePort service that opens the following ports by default: | Listener | Node Port | Container Port | | --- | --- | --- | | Schema Registry | 30081 | 8081 | | HTTP Proxy | 30082 | 8083 | | Kafka API | 31092 | 9094 | | Admin API | 31644 | 9644 | To learn more, see [Networking and Connectivity in Kubernetes](../../../../manage/kubernetes/networking/k-networking-and-connectivity/). ### [](#tls-certificates)TLS Certificates By default, TLS is enabled in the Redpanda Helm chart. The Helm chart uses [cert-manager](https://cert-manager.io/docs/) to generate four Certificate resources that provide Redpanda with self-signed certificates for internal and external connections. Having separate certificates for internal and external connections provides security isolation. If an external certificate or its corresponding private key is compromised, it doesn’t affect the security of internal communications. ```bash kubectl get certificate --namespace ``` NAME READY redpanda-default-cert True redpanda-default-root-certificate True redpanda-external-cert True redpanda-external-root-certificate True - `redpanda-default-cert`: Self-signed certificate for internal communications. - `redpanda-default-root-certificate`: Root certificate authority for the internal certificate. - `redpanda-external-cert`: Self-signed certificate for external communications. - `redpanda-external-root-certificate`: Root certificate authority for the external certificate. By default, all listeners are configured with the same certificate. To configure separate TLS certificates for different listeners, see [TLS for Redpanda in Kubernetes](../../../../manage/kubernetes/security/tls/). > 📝 **NOTE** > > The Redpanda Helm chart provides self-signed certificates for convenience. In a production environment, it’s best to use certificates from a trusted Certificate Authority (CA) or integrate with your existing CA infrastructure. ## [](#uninstall-redpanda)Uninstall Redpanda When you finish testing Redpanda, you can uninstall it from your Kubernetes cluster. The steps depend on how you installed Redpanda: using the Redpanda Operator or the Redpanda Helm chart. ### Operator Follow the steps in **exact order** to avoid race conditions between the Redpanda Operator’s reconciliation loop and Kubernetes garbage collection. 1. Delete all Redpanda-related custom resources: ```bash kubectl delete users --namespace --all kubectl delete topics --namespace --all kubectl delete schemas --namespace --all kubectl delete redpanda --namespace --all ``` 2. Make sure requests for those resources return no results. For example, if you had a Redpanda cluster named `redpanda` in the namespace ``, run: ```bash kubectl get redpanda --namespace ``` 3. Uninstall the Redpanda Operator Helm release: ```bash helm uninstall redpanda-controller --namespace ``` Helm does not uninstall CRDs by default when using `helm uninstall` to avoid accidentally deleting existing custom resources. 4. Remove the CRDs. 1. List all Redpanda CRDs installed by the operator: ```bash kubectl api-resources --api-group='cluster.redpanda.com' ``` This command displays all CRDs defined by the Redpanda Operator. For example: ```bash NAME SHORTNAMES APIVERSION NAMESPACED KIND redpandas rp cluster.redpanda.com/v1alpha2 true Redpanda schemas sc cluster.redpanda.com/v1alpha2 true Schema topics cluster.redpanda.com/v1alpha2 true Topic users rpu cluster.redpanda.com/v1alpha2 true User ``` 2. Delete the CRDs: ```bash kubectl get crds -o name | grep cluster.redpanda.com | xargs kubectl delete ``` This command lists all CRDs with the `cluster.redpanda.com` domain suffix and deletes them, ensuring only Redpanda CRDs are removed. Helm does not delete CRDs automatically to prevent data loss, so you must run this step manually. 5. (Optional) Delete any leftover PVCs or Secrets in the namespace: > ⚠️ **CAUTION** > > The following command deletes all PVCs and Secrets in the namespace, which may remove unrelated resources if the namespace is shared with other applications. ```bash kubectl delete pvc,secret --all --namespace ``` ### Helm If you deployed Redpanda with the Redpanda Helm chart, follow these steps to uninstall it: 1. Uninstall the Helm release: ```bash helm uninstall redpanda --namespace ``` 2. (Optional) Delete any leftover PVCs or Secrets in the namespace: > ⚠️ **CAUTION** > > The following command deletes all PVCs and Secrets in the namespace, which may remove unrelated resources if the namespace is shared with other applications. ```bash kubectl delete pvc,secret --all --namespace ``` ## [](#delete-the-cluster)Delete the cluster To delete your Kubernetes cluster: ### kind ```bash kind delete cluster ``` ### minikube ```bash minikube delete ``` To remove the convenience alias created during the quickstart: ```bash unalias internal-rpk ``` ## [](#troubleshoot)Troubleshoot Before troubleshooting your cluster, make sure that you have all the [prerequisites](#prerequisites). ### [](#helm-v3-18-0-is-not-supported-json-number-error)Helm v3.18.0 is not supported (json.Number error) If you are using Helm v3.18.0, you may encounter errors such as: Error: INSTALLATION FAILED: execution error at (redpanda/templates/entry-point.yaml:17:4): invalid Quantity expected string or float64 got: json.Number (1) This is due to a bug in Helm v3.18.0. To avoid similar errors, upgrade to a later version. For more details, see the [Helm GitHub issue](https://github.com/helm/helm/issues/30880). === StatefulSet never rolls out If the StatefulSet Pods remain in a pending state, they are waiting for resources to become available. To identify the Pods that are pending, use the following command: ```bash kubectl get pod --namespace ``` The response includes a list of Pods in the StatefulSet and their status. To view logs for a specific Pod, use the following command. ```bash kubectl logs -f --namespace ``` You can use the output to debug your deployment. ### [](#didnt-match-pod-anti-affinity-rules)Didn’t match pod anti-affinity rules If you see this error, your cluster does not have enough nodes to satisfy the anti-affinity rules: Warning FailedScheduling 18m default-scheduler 0/1 nodes are available: 1 node(s) didn't match pod anti-affinity rules. preemption: 0/1 nodes are available: 1 No preemption victims found for incoming pod. The Helm chart configures default `podAntiAffinity` rules to make sure that only one Pod running a Redpanda broker is scheduled on each worker node. To learn why, see [Number of workers](../k-requirements/#number-of-workers). To resolve this issue, do one of the following: - Create additional worker nodes. - Modify the anti-affinity rules (for development purposes only). If adding nodes is not an option, you can modify the `podAntiAffinity` rules in your StatefulSet to be less strict. #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: statefulset: podAntiAffinity: type: soft ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `docker-repo.yaml` ```yaml statefulset: podAntiAffinity: type: soft ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values docker-repo.yaml ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set statefulset.podAntiAffinity.type=soft ``` ### [](#unable-to-mount-volume)Unable to mount volume If you see volume mounting errors in the Pod events or in the Redpanda logs, ensure that each of your Pods has a volume available in which to store data. - If you’re using StorageClasses with dynamic provisioners (default), ensure they exist: ```bash kubectl get storageclass ``` - If you’re using PersistentVolumes, ensure that you have one PersistentVolume available for each Redpanda broker, and that each one has the storage capacity that’s set in `storage.persistentVolume.size`: ```bash kubectl get persistentvolume --namespace ``` To learn how to configure different storage volumes, see [Configure Storage](../../../../manage/kubernetes/storage/k-configure-storage/). ### [](#failed-to-pull-image)Failed to pull image When deploying the Redpanda Helm chart, you may encounter Docker rate limit issues because the default registry URL is not recognized as a Docker Hub URL. The domain `docker.redpanda.com` is used for statistical purposes, such as tracking the number of downloads. It mirrors Docker Hub’s content while providing specific analytics for Redpanda. Failed to pull image "docker.redpanda.com/redpandadata/redpanda:v": rpc error: code = Unknown desc = failed to pull and unpack image "docker.redpanda.com/redpandadata/redpanda:v": failed to copy: httpReadSeeker: failed open: unexpected status code 429 Too Many Requests - Server message: toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit To fix this error, do one of the following: - Replace the `image.repository` value in the Helm chart with `docker.io/redpandadata/redpanda`. Switching to Docker Hub avoids the rate limit issues associated with `docker.redpanda.com`. #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: image: repository: docker.io/redpandadata/redpanda ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `docker-repo.yaml` ```yaml image: repository: docker.io/redpandadata/redpanda ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values docker-repo.yaml ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set image.repository=docker.io/redpandadata/redpanda ``` - Authenticate to Docker Hub by logging in with your Docker Hub credentials. The `docker.redpanda.com` site acts as a reflector for Docker Hub. As a result, when you log in with your Docker Hub credentials, you will bypass the rate limit issues. ### [](#dig-not-defined)Dig not defined This error means that you are using an unsupported version of [Helm](https://helm.sh/docs/intro/install/): Error: parse error at (redpanda/templates/statefulset.yaml:203): function "dig" not defined To fix this error, ensure that you are using the minimum required version: 3.10.0. ```bash helm version ``` ### [](#repository-name-already-exists)Repository name already exists If you see this error, remove the `redpanda` chart repository, then try installing it again. ```bash helm repo remove redpanda helm repo add redpanda https://charts.redpanda.com helm repo update ``` ### [](#fatal-error-during-checker-data-directory-is-writable-execution)Fatal error during checker "Data directory is writable" execution This error appears when Redpanda does not have write access to your configured storage volume under `storage` in the Helm chart. Error: fatal error during checker "Data directory is writable" execution: open /var/lib/redpanda/data/test\_file: permission denied To fix this error, set `statefulset.initContainers.setDataDirOwnership.enabled` to `true` so that the initContainer can set the correct permissions on the data directories. ### [](#cannot-patch-redpanda-with-kind-statefulset)Cannot patch "redpanda" with kind StatefulSet This error appears when you run `helm upgrade` with the `--values` flag but do not include all your previous overrides. Error: UPGRADE FAILED: cannot patch "redpanda" with kind StatefulSet: StatefulSet.apps "redpanda" is invalid: spec: Forbidden: updates to statefulset spec for fields other than 'replicas', 'template', 'updateStrategy', 'persistentVolumeClaimRetentionPolicy' and 'minReadySeconds' are forbidden To fix this error, include all the value overrides from the previous installation using either the `--set` or the `--values` flags. > ⚠️ **WARNING** > > Do not use the `--reuse-values` flag to upgrade from one version of the Helm chart to another. This flag stops Helm from using any new values in the upgraded chart. ### [](#cannot-patch-redpanda-console-with-kind-deployment)Cannot patch "redpanda-console" with kind Deployment This error appears if you try to upgrade your deployment and you already have `console.enabled` set to `true`. Error: UPGRADE FAILED: cannot patch "redpanda-console" with kind Deployment: Deployment.apps "redpanda-console" is invalid: spec.selector: Invalid value: v1.LabelSelector{MatchLabels:map\[string\]string{"app.kubernetes.io/instance":"redpanda", "app.kubernetes.io/name":"console"}, MatchExpressions:\[\]v1.LabelSelectorRequirement(nil)}: field is immutable To fix this error, set `console.enabled` to `false` so that Helm doesn’t try to deploy Redpanda Console again. ### [](#helm-is-in-a-pending-rollback-state)Helm is in a pending-rollback state An interrupted Helm upgrade process can leave your Helm release in a `pending-rollback` state. This state prevents further actions like upgrades, rollbacks, or deletions through standard Helm commands. To fix this: 1. Identify the Helm release that’s in a `pending-rollback` state: ```bash helm list --namespace --all ``` Look for releases with a status of `pending-rollback`. These are the ones that need intervention. 2. Verify the Secret’s status to avoid affecting the wrong resource: ```bash kubectl --namespace get secret --show-labels ``` Identify the Secret associated with your Helm release by its `pending-rollback` status in the labels. > ⚠️ **WARNING** > > Ensure you have correctly identified the Secret to avoid unintended consequences. Deleting the wrong Secret could impact other deployments or services. 3. Delete the Secret to clear the `pending-rollback` state: ```bash kubectl --namespace delete secret -l status=pending-rollback ``` After clearing the `pending-rollback` state: - **Retry the upgrade**: Restart the upgrade process. You should investigate the initial failure to avoid getting into the `pending-rollback` state again. - **Perform a rollback**: If you need to roll back to a previous release, use `helm rollback ` to revert to a specific, stable release version. ### [](#crash-loop-backoffs)Crash loop backoffs If a broker crashes after startup, or gets stuck in a crash loop, it can accumulate an increasing amount of stored state. This accumulated state not only consumes additional disk space but also prolongs the time required for each subsequent restart to process it. To prevent infinite crash loops, the Redpanda Helm chart sets the [`crash_loop_limit`](../../../../reference/properties/broker-properties/#crash_loop_limit) broker configuration property to `5`. The crash loop limit is the number of consecutive crashes that can happen within one hour of each other. By default, the broker terminates immediately after hitting the `crash_loop_limit`. The Pod running Redpanda remains in a `CrashLoopBackoff` state until its internal consecutive crash counter is reset to zero. To facilitate debugging in environments where a broker is stuck in a crash loop, you can also set the [`crash_loop_sleep_sec`](../../../../reference/properties/broker-properties/#crash_loop_sleep_sec) broker configuration property. This setting determines how long the broker sleeps before terminating the process after reaching the crash loop limit. By providing a window during which the Pod remains available, you can SSH into it and troubleshoot the issue. Example configuration: ```yaml config: node: crash_loop_limit: 5 crash_loop_sleep_sec: 60 ``` In this example, when the broker hits the `crash_loop_limit` of 5, it will sleep for 60 seconds before terminating the process. This delay allows administrators to access the Pod and troubleshoot. To troubleshoot a crash loop backoff: 1. Check the Redpanda logs from the most recent crashes: ```bash kubectl logs --namespace ``` > 📝 **NOTE** > > Kubernetes retains logs only for the current and the previous instance of a container. This limitation makes it difficult to access logs from earlier crashes, which may contain vital clues about the root cause of the issue. Given these log retention limitations, setting up a centralized logging system is crucial. Systems such as [Loki](https://grafana.com/docs/loki/latest/) or [Datadog](https://www.datadoghq.com/product/log-management/) can capture and store logs from all containers, ensuring you have access to historical data. 2. Resolve the issue that led to the crash loop backoff. 3. Reset the crash counter to zero to allow Redpanda to restart. You can do any of the following to reset the counter: - Make changes to any of the following sections in the Redpanda Helm chart to trigger an update: - `config.node` - `config.tunable` For example: ```yaml config: node: crash_loop_limit: ``` - Delete the `startup_log` file in the broker’s data directory. ```bash kubectl exec --namespace -- rm /var/lib/redpanda/data/startup_log ``` > 📝 **NOTE** > > It might be challenging to execute this command within a Pod that is in a `CrashLoopBackoff` state due to the limited time during which the Pod is available before it restarts. Wrapping the command in a loop might work. - Wait one hour since the last crash. The crash counter resets after one hour. To avoid future crash loop backoffs and manage the accumulation of small segments effectively: - [Monitor](../../../../manage/kubernetes/monitoring/k-monitor-redpanda/) the size and number of segments regularly. - Optimize your Redpanda configuration for segment management. - Consider implementing [Tiered Storage](../../../../manage/kubernetes/tiered-storage/k-tiered-storage/) to manage data more efficiently. ### [](#a-redpanda-enterprise-edition-license-is-required)A Redpanda Enterprise Edition license is required During a Redpanda upgrade, if enterprise features are enabled and a valid Enterprise Edition license is missing, Redpanda logs a warning and aborts the upgrade process on the first broker. This issue prevents a successful upgrade. A Redpanda Enterprise Edition license is required to use the currently enabled features. To apply your license, downgrade this broker to the pre-upgrade version and provide a valid license key via rpk using 'rpk cluster license set ', or via Redpanda Console. To request an enterprise license, please visit . To try Redpanda Enterprise for 30 days, visit . For more information, see . If you encounter this message, follow these steps to recover: 1. [Roll back the affected broker to the original version](../../../../upgrade/k-rolling-upgrade/#roll-back). 2. Do one of the following: - [Apply a valid Redpanda Enterprise Edition license](../../../../get-started/licensing/add-license-redpanda/) to the cluster. - Disable enterprise features. If you do not have a valid license and want to proceed without using enterprise features, you can disable the enterprise features in your Redpanda configuration. 3. Retry the upgrade. For more troubleshooting steps, see [Troubleshoot Redpanda in Kubernetes](../../../../troubleshoot/errors-solutions/k-resolve-errors/). ## [](#next-steps)Next steps - [Try an example in Redpanda Labs](../../../../../redpanda-labs/) - [Learn more about Redpanda Console](../../../../manage/console/) - [Learn more about rpk](../../../../get-started/rpk-install/) > 💡 **TIP** > > When you’re ready to use a registered domain, make sure to remove your entries from the `/etc/hosts` file, and see [Configure External Access through a NodePort Service](../../../../manage/kubernetes/networking/external/k-nodeport/#use-the-default-redpanda-subdomains). ## [](#suggested-reading)Suggested reading - [Networking and Connectivity in Kubernetes](../../../../manage/kubernetes/networking/k-networking-and-connectivity/) - [Configure TLS for Redpanda in Kubernetes](../../../../manage/kubernetes/security/tls/) - [Configure SASL for Redpanda in Kubernetes](../../../../manage/kubernetes/security/authentication/k-authentication/) - [Redpanda Helm Specification](../../../../reference/k-redpanda-helm-spec/) - [Redpanda CRD Reference](../../../../reference/k-crd/) - [Redpanda Console README](https://github.com/redpanda-data/console) on GitHub ## Suggested labs - [Disaster Recovery with Envoy and Shadowing](/redpanda-labs/docker-compose/envoy-shadowing/) - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Stream Jira Issues to Redpanda for Real-Time Metrics](/redpanda-labs/docker-compose/jira-metrics-pipeline/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Set Up GitOps for the Redpanda Helm Chart](/redpanda-labs/kubernetes/gitops-helm/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) - [Set Up MySQL CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-mysql-json/) - [Set Up Postgres CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-postgres-json/) See more [Search all labs](/redpanda-labs) --- # Page 47: Deploy on Linux **URL**: https://docs.redpanda.com/current/deploy/redpanda/manual.md --- # Deploy on Linux --- title: Deploy on Linux latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: redpanda/manual/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: redpanda/manual/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/redpanda/manual/index.adoc description: Learn about deployment options on Linux, as well as considerations for high availability and sizing. page-git-created-date: "2025-08-15" page-git-modified-date: "2025-11-19" support-status: supported --- - [Requirements and Recommendations](production/requirements/) A list of requirements and recommendations for provisioning servers to run Redpanda in production. - [Linux Deployment Options](production/) Deploy Redpanda on Linux for development or for production. - [Sizing Use Cases](sizing-use-cases/) How to size Redpanda clusters for low, medium, and high throughput use cases in your data center or in object storage. - [Sizing Guidelines](sizing/) Learn about considerations to size your Redpanda cluster to handle the volume of data being produced, replicated, and consumed. - [Linux System Tuning](linux-system-tuning/) Learn how Redpanda applies automatic tuning to your Linux system. --- # Page 48: Linux System Tuning **URL**: https://docs.redpanda.com/current/deploy/redpanda/manual/linux-system-tuning.md --- # Linux System Tuning --- title: Linux System Tuning latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: redpanda/manual/linux-system-tuning page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: redpanda/manual/linux-system-tuning.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/redpanda/manual/linux-system-tuning.adoc description: Learn how Redpanda applies automatic tuning to your Linux system. page-git-created-date: "2025-08-15" page-git-modified-date: "2025-08-15" support-status: supported --- Redpanda includes several features to tune your Linux systems for optimal performance. You can trigger hardware-based optimizations through the `rpk redpanda tune` command, also called the autotuner. Software-based configurations are managed automatically through the `systemd` suite of tools. ## [](#user-triggered-hardware-tuning)User-triggered hardware tuning You can invoke the Redpanda autotuner using the `rpk redpanda tune` command to optimize native Linux nodes. It analyzes the hardware configuration of the worker node and sets appropriate kernel options. You can choose to set certain hardware parameters using `ulimit` or other system tools while using the autotuner to manage others. ### [](#using-the-autotuner)Using the autotuner The Redpanda autotuner has a large array of hardware tuners to choose from. You may choose to either execute all available tuners, or to apply only a subset of them. This is particularly important when you wish to maintain specific configurations and prevent Redpanda from altering these settings. Redpanda recommends running the autotuner as part of your production deployment workflows. This ensures any hardware configurations or updates to the autotuner itself are incorporated quickly and efficiently into your system. For the full list of available tuners, refer to [`rpk redpanda tune`](../../../../reference/rpk/rpk-redpanda/rpk-redpanda-tune/). When using Kubernetes, you should tune your system at the host node level. For more information on Kubernetes configuration and execution, refer to [Kubernetes worker node tuning](../../kubernetes/k-tune-workers/). ## [](#automated-software-configurations)Automated software configurations Redpanda makes use of systemd to manage operating system and software-based limits, such as memlocks, file handle limits, core limits, and certain distribution-specific configurations. These help ensure the system executes stably and efficiently. Some key examples of automated configurations include: - Detection of hung services and infinite looping scenarios. This helps ensure you don’t have blocking services or processes that may interfere with Redpanda’s stream processing. - Configuration of asynchronous input/output interfaces and scheduler affinity. This is particularly critical when you rely on real-time processing of data streams for your applications. - Use of systemd slices (see [this blog post](https://www.scylladb.com/2019/09/25/isolating-workloads-with-systemd-slices/) for more details), which allows Redpanda to efficiently use system resources while isolating tasks for scalability and performance reasons. ## [](#monitoring-configurations)Monitoring configurations While Redpanda provides numerous metrics, the configurations applied using the autotuner and systemd are not exposed internally. You should continue monitoring your system health through standard means. For example, the systemd configuration sets the file handle limit to 800,000 references. If you are concerned about approaching this limit, you should monitor it through standard system monitoring, such as the use of the `lsof` utility. --- # Page 49: Linux Deployment Options **URL**: https://docs.redpanda.com/current/deploy/redpanda/manual/production.md --- # Linux Deployment Options --- title: Linux Deployment Options latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: redpanda/manual/production/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: redpanda/manual/production/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/redpanda/manual/production/index.adoc description: Deploy Redpanda on Linux for development or for production. page-git-created-date: "2025-08-15" page-git-modified-date: "2025-08-15" support-status: supported --- - [Deploy for Development](dev-deployment/) Steps to deploy a Redpanda sandbox cluster. - [Deploy for Production: Automated](production-deployment-automation/) Deploy Redpanda using automation tools like Terraform and Ansible. - [Deploy for Production: Manual](production-deployment/) Steps to deploy a Redpanda production cluster. - [Production Readiness Checklist](production-readiness/) --- # Page 50: Deploy for Development **URL**: https://docs.redpanda.com/current/deploy/redpanda/manual/production/dev-deployment.md --- # Deploy for Development --- title: Deploy for Development latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: redpanda/manual/production/dev-deployment page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: redpanda/manual/production/dev-deployment.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/redpanda/manual/production/dev-deployment.adoc description: Steps to deploy a Redpanda sandbox cluster. page-git-created-date: "2025-08-15" page-git-modified-date: "2026-03-31" support-status: supported --- You can deploy Redpanda using well-known configuration properties optimized for a development or test environment. This configuration uses less system resources and simplifies setup, but it’s not suitable for a production deployment. For example, in [development mode](../../../../../reference/rpk/rpk-redpanda/rpk-redpanda-mode/#development-mode), the default `group_topic_partitions` is 3, and the default `storage_min_free_bytes` is 1 GiB. In production mode, the default `group_topic_partitions` is 16, and the default `storage_min_free_bytes` is 5 GiB. > 📝 **NOTE** > > - Development mode enables write caching by default. This is a relaxed mode of [`acks=all`](../../../../../develop/produce-data/configure-producers/#acksall) that acknowledges a message as soon as it is received and acknowledged on a majority of brokers, without waiting for it to fsync to disk. Write caching provides lower latency while still ensuring that a majority of brokers acknowledge the write. For more information, or to disable this, see [write caching](../../../../../develop/manage-topics/config-topics/#configure-write-caching). > > - Development mode also bypasses `fsync`, acknowledging messages before they’re stored to disk. This reduces the durability of messages, could cause potential data loss, and could give unrealistic performance characteristics for a production environment. To deploy for a production environment, see [Deploy for Production](../production-deployment/). Or to try out Redpanda in Docker, see [Redpanda Quickstart](../../../../../get-started/quick-start/). ## [](#prerequisites)Prerequisites Make sure you meet the [hardware and software requirements](../requirements/). ### [](#tcpip-ports)TCP/IP ports Redpanda uses the following default ports: | Port | Purpose | | --- | --- | | 9092 | Kafka API | | 8082 | HTTP Proxy | | 8081 | Schema Registry | | 9644 | Admin API and Prometheus | | 33145 | internal RPC | ## [](#install-redpanda)Install Redpanda Install Redpanda on each system you want to be part of your cluster. There are binaries available for Fedora/RedHat or Debian systems. Unless you intend to run Redpanda in FIPS-compliance mode, the following packages should accommodate your needs (for both Debian and Redhat based systems): `redpanda` - Contains the Redpanda application and all supporting libraries - Depends on `redpanda-tuner` and either `redpanda-rpk` or `redpanda-rpk-fips` `redpanda-rpk` - Contains the pure GoLang compiled `rpk` application - If you wish to use `rpk` only, then this is the only required install package `redpanda-tuner` - Contains the files used to run Redpanda tuners - Depends on `redpanda-rpk` or `redpanda-rpk-fips` ### Fedora/RedHat ```bash curl -1sLf 'https://dl.redpanda.com/nzc4ZYQK3WRGd9sy/redpanda/cfg/setup/bash.rpm.sh' | \ sudo -E bash && sudo yum install redpanda -y ``` > ❗ **IMPORTANT** > > To install a version of Redpanda that is older than the latest available version, you must also specify each dependency. For example, if installing `24.3.1~rc1-1` and you fail to specify each package and its version, you may encounter the following error: > > ```bash > yum install redpanda=24.3.1~rc1-1 > Reading package lists... Done > Building dependency tree... Done > Reading state information... Done > Some packages could not be installed. This may mean that you have > requested an impossible situation or if you are using the unstable > distribution that some required packages have not yet been created > or been moved out of Incoming. > The following information may help to resolve the situation: > > The following packages have unmet dependencies: > redpanda : Depends: redpanda-rpk (= 24.3.1~rc1-1) but it is not going to be installed or > redpanda-rpk-fips (= 24.3.1~rc1-1) but it is not going to be installed > Depends: redpanda-tuner (= 24.3.1~rc1-1) but it is not going to be installed > E: Unable to correct problems, you have held broken packages. > ``` > > To troubleshoot this error, specify the full list of versions for each package. In this case: > > ```bash > yum install \ > redpanda-tuner=24.3.1~rc1-1 \ > redpanda-rpk=24.3.1~rc1-1 \ > redpanda=24.3.1~rc1-1 > ``` ### Debian/Ubuntu ```bash curl -1sLf 'https://dl.redpanda.com/nzc4ZYQK3WRGd9sy/redpanda/cfg/setup/bash.deb.sh' | \ sudo -E bash && sudo apt install redpanda -y ``` > ❗ **IMPORTANT** > > To install a version of Redpanda that is older than the latest available version, you must also specify each dependency. For example, if installing `24.3.1~rc1-1` and you fail to specify each package and its version, you may encounter the following error: > > ```bash > apt install redpanda=24.3.1~rc1-1 > Reading package lists... Done > Building dependency tree... Done > Reading state information... Done > Some packages could not be installed. This may mean that you have > requested an impossible situation or if you are using the unstable > distribution that some required packages have not yet been created > or been moved out of Incoming. > The following information may help to resolve the situation: > > The following packages have unmet dependencies: > redpanda : Depends: redpanda-rpk (= 24.3.1~rc1-1) but it is not going to be installed or > redpanda-rpk-fips (= 24.3.1~rc1-1) but it is not going to be installed > Depends: redpanda-tuner (= 24.3.1~rc1-1) but it is not going to be installed > E: Unable to correct problems, you have held broken packages. > ``` > > To troubleshoot this error, specify the full list of versions for each package. In this case: > > ```bash > apt install \ > redpanda-tuner=24.3.1~rc1-1 \ > redpanda-rpk=24.3.1~rc1-1 \ > redpanda=24.3.1~rc1-1 > ``` ## [](#install-redpanda-for-fips-compliance)Install Redpanda for FIPS compliance > 📝 **NOTE** > > This feature requires an [enterprise license](../../../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../../../get-started/licensing/#self-managed) apply. To install Redpanda for FIPS compliance, install the packages `redpanda-fips` and `redpanda-rpk-fips`, which automatically pull in all required dependencies. `redpanda-fips` - Contains the OpenSSL FIPS-approved module and scripts required to set up and run Redpanda in FIPS-compliance mode. - Depends upon the successful installation of the `redpanda` package. - Includes the `fips.so` cryptographic provider (built from OpenSSL v3.0.9, which is the latest FIPS 140-2 approved module) and a copy of the OpenSSL application. - Executes `openssl fipsinstall` against the `fips.so` module, which generates a `fipsmodule.cnf` file that is used during the module’s POST (power-on-self-test) to validate the integrity of the module. `redpanda-rpk-fips` - Contains a version of `rpk` built with the [Microsoft GoLang compiler](https://github.com/microsoft/go) and [Microsoft’s Go Crypto OpenSSL package](https://github.com/microsoft/go-crypto-openssl) to which `rpk` is linked, and uses the FIPS-approved version of OpenSSL. ### RHEL To install Redpanda for FIPS compliance, run: ```bash curl -1sLf 'https://dl.redpanda.com/nzc4ZYQK3WRGd9sy/redpanda/cfg/setup/bash.rpm.sh' | \ sudo -E bash && sudo yum install redpanda -y ``` > 📝 **NOTE** > > Alternatively, you could run `sudo yum install -y redpanda-fips`, which also picks up and includes the `redpanda` install package. If you wish to only use `rpk` on a FIPS host, run: ```bash sudo yum install -y redpanda-fips redpanda-rpk-fips ``` ### Debian/Ubuntu To install Redpanda for FIPS compliance, run: ```bash sudo apt install redpanda-fips redpanda-rpk-fips ``` > 📝 **NOTE** > > Alternatively, you could run `sudo apt install redpanda-fips`, which also picks up and includes the `redpanda` install package. If you wish to only use `rpk` on a FIPS host, run: ```bash sudo apt install -y redpanda-rpk-fips ``` See also: [Configure Redpanda for FIPS](../../../../../manage/security/fips-compliance/) ## [](#install-redpanda-console)Install Redpanda Console For detailed instructions on installing and configuring Redpanda Console, see [Deploy Redpanda Console on Linux](../../../../console/linux/deploy/). ## [](#bootstrapping)Bootstrap broker configurations Each broker requires a set of broker configurations that determine how all brokers communicate with each other and with clients. Bootstrapping a cluster configures the [listeners](https://docs.redpanda.com/current/reference/glossary/#listener), [seed servers](https://docs.redpanda.com/current/reference/glossary/#seed-server), and [advertised listeners](https://docs.redpanda.com/current/reference/glossary/#advertised-listener), which ensure proper network connectivity and accessibility. Starting in version 23.3.8, `rpk` enhances the bootstrapping process with additional flags for configuring advertised listener addresses directly. Use the [`rpk redpanda config bootstrap`](../../../../../reference/rpk/rpk-redpanda/rpk-redpanda-config-bootstrap/) command to bootstrap Redpanda: ```bash sudo rpk redpanda config bootstrap --self --advertised-kafka --ips ,, && \ sudo rpk redpanda config set redpanda.empty_seed_starts_cluster false ``` Replace the following placeholders: - ``: The `--self` flag tells Redpanda the interfaces to bind to for the Kafka API, the RPC API, and the Admin API. These addresses determine on which network interface and port Redpanda listens for incoming connections. - Set the listener address to `0.0.0.0` to listen on all network interfaces available on the machine. - Set the listener address to a specific IP address to bind the listener to that address, restricting connections to that interface. - ``: The `--advertised-kafka` flag sets a different advertised Kafka address, which is useful for scenarios where the accessible address differs from the bind address. > ❗ **IMPORTANT** > > Redpanda does not allow advertised addresses set to `0.0.0.0`. If you set any advertised addresses to `0.0.0.0`, Redpanda will output startup validation errors. - ``: The `--ips` flag lists all the seed servers in the cluster, including the one being started. > 📝 **NOTE** > > The `--ips` flag must be set _identically_ (with nodes listed in identical order) on each node. Bootstrapping Redpanda updates your `/etc/redpanda/redpanda.yaml` configuration file: `/etc/redpanda/redpanda.yaml` ```yaml redpanda: data_directory: /var/lib/redpanda/data empty_seed_starts_cluster: false seed_servers: - host: address: port: 33145 - host: address: port: 33145 - host: address: port: 33145 rpc_server: address: port: 33145 kafka_api: - address: port: 9092 admin: - address: port: 9644 advertised_rpc_api: address: port: 33145 advertised_kafka_api: - address: port: 9092 ``` ### [](#recommendations)Recommendations - Redpanda Data strongly recommends at least three seed servers when forming a cluster. A larger number of seed servers increases the robustness of consensus and minimizes any chance that new clusters get spuriously formed after brokers are lost or restarted without any data. - It’s important to have one or more seed servers in each fault domain (for example, in each rack or cloud AZ). A higher number provides a stronger guarantee that clusters don’t fracture unintentionally. - It’s possible to change the seed servers for a short period of time after a cluster has been created. For example, you may want to designate one additional broker as a seed server to increase availability. To do this without cluster downtime, add the new broker to the [`seed_servers`](../../../../../reference/properties/broker-properties/) property and restart Redpanda to apply the change on a broker-by-broker basis. ### [](#listeners-for-mixed-environments)Listeners for mixed environments For clusters serving both internal and external clients, configure multiple listeners for the Kafka API to separate internal from external traffic. For more details, see [Configure Listeners](../../../../../manage/security/listener-configuration/). ## [](#start-redpanda)Start Redpanda To start Redpanda: ```bash sudo systemctl start redpanda-tuner redpanda ``` When a Redpanda cluster starts, it instantiates a controller Raft group with all the seed servers specified in the `--ips` flag. After all seed servers complete their startup procedure and become accessible, the cluster is then available. After that, non-seed servers start up and are added to the cluster. ## [](#start-redpanda-console)Start Redpanda Console For instructions on starting and managing Redpanda Console, see [Deploy Redpanda Console on Linux](../../../../console/linux/deploy/). ## [](#verify-the-installation)Verify the installation To verify that the Redpanda cluster is up and running, use `rpk` to get information about the cluster: ```bash rpk cluster info ``` You should see a list of advertised addresses. To create a topic: ```bash rpk topic create ``` If topics were initially created in a test environment with a replication factor of `1`, use `rpk topic alter-config` to change the topic replication factor: ```bash rpk topic alter-config --set replication.factor=3 ``` ## [](#perform-a-self-test)Perform a self test To understand the performance capabilities of your Redpanda cluster, Redpanda offers built-in self-test features that evaluate the performance of both disk and network operations. For more information, see [Disk and network self-test benchmarks](../../../../../troubleshoot/cluster-diagnostics/diagnose-issues/#self-test). When using the storage bandwidth test, ensure that your results show at least 16,000 IOPS (Input/Output Operations Per Second) for production environments. If your test results are below this threshold, your storage may not be suitable for production Redpanda workloads. ## [](#next-steps)Next steps - If clients connect from a different subnet, see [Configure Listeners](../../../../../manage/security/listener-configuration/). - Observability is essential. See [Monitor Redpanda](../../../../../manage/monitoring/). ## [](#suggested-reading)Suggested reading - [Configure Cluster Properties](../../../../../manage/cluster-maintenance/cluster-property-configuration/) - [Redpanda Console Configuration](../../../../../console/config/configure-console/) - [Work with Schema Registry](../../../../../manage/schema-reg/) - [Work with HTTP Proxy](../../../../../develop/http-proxy/) ## Suggested labs - [Disaster Recovery with Envoy and Shadowing](/redpanda-labs/docker-compose/envoy-shadowing/) - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Stream Jira Issues to Redpanda for Real-Time Metrics](/redpanda-labs/docker-compose/jira-metrics-pipeline/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Set Up GitOps for the Redpanda Helm Chart](/redpanda-labs/kubernetes/gitops-helm/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) - [Set Up MySQL CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-mysql-json/) - [Set Up Postgres CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-postgres-json/) See more [Search all labs](/redpanda-labs) --- # Page 51: Deploy for Production: Automated **URL**: https://docs.redpanda.com/current/deploy/redpanda/manual/production/production-deployment-automation.md --- # Deploy for Production: Automated --- title: "Deploy for Production: Automated" latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: redpanda/manual/production/production-deployment-automation page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: redpanda/manual/production/production-deployment-automation.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/redpanda/manual/production/production-deployment-automation.adoc description: Deploy Redpanda using automation tools like Terraform and Ansible. page-git-created-date: "2025-08-15" page-git-modified-date: "2025-08-15" support-status: supported --- If you use automation tools like Terraform and Ansible in your environment, you can use them to quickly provision a Redpanda cluster. Terraform can set up the infrastructure and output a properly-formatted `hosts.ini` file, and Ansible can use that `hosts.ini` file as input to install Redpanda. If you already have an infrastructure provisioning framework, you can supply your own hosts file (without using Terraform), and you can use Ansible to install Redpanda. This recommended automated deployment provides a production-usable way to deploy and maintain a cluster. For unique configurations, you can work directly with the Ansible and Terraform modules to integrate them into your environment. ## [](#prerequisites)Prerequisites 1. Install Terraform following the [Terraform documentation](https://learn.hashicorp.com/tutorials/terraform/install-cli). 2. Install Ansible following the [Ansible documentation](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html). Different operating systems may have specific Ansible dependencies. 3. Clone the [`deployment-automation` GitHub repository](https://github.com/redpanda-data/deployment-automation/): ```bash git clone https://github.com/redpanda-data/deployment-automation.git ``` 4. Change into the directory: ```bash cd deployment-automation ``` ## [](#use-terraform-to-set-up-infrastructure)Use Terraform to set up infrastructure ### AWS The recommended [Terraform module for Redpanda](https://registry.terraform.io/modules/redpanda-data/redpanda-cluster/aws/latest) deploys virtual machines on AWS EC2. To create an AWS Redpanda cluster, review the [default variables](https://github.com/redpanda-data/deployment-automation/blob/main/aws/main.tf) and make any edits necessary for your environment. 1. In the `deployment-automation` folder, change into the `aws` directory: ```bash cd aws ``` 2. Set AWS credentials. Terraform provides multiple ways to set the AWS secret and key. See the [Terraform documentation](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#environment-variables). 3. Initialize Terraform: ```bash terraform init ``` 4. Create the cluster with `terraform apply`: ```bash terraform apply -var='public_key_path=~/.ssh/id_rsa.pub' -var='subnet_id=' -var='vpc_id=' ``` - Terraform configures `public_key_path` on the brokers to remotely connect with SSH. If the public key path isn’t the default `~/.ssh/id_rsa.pub`, then you need to set it. - If you don’t have a default VPC defined, then you need to set `subnet_id` and `vpc_id`. For a complete and up-to-date list of configuration options, see the [Terraform module](https://registry.terraform.io/modules/redpanda-data/redpanda-cluster/aws/latest): > 📝 **NOTE** > > For acceptable `distro` names: > > ```bash > data "aws_ami" "ami" { > most_recent = true > > filter { > name = "name" > values = [ > "ubuntu/images/hvm-ssd/ubuntu-*-amd64-server-*", > "ubuntu/images/hvm-ssd/ubuntu-*-arm64-server-*", > "Fedora-Cloud-Base-*.x86_64-hvm-us-west-2-gp2-0", > "debian-*-amd64-*", > "debian-*-hvm-x86_64-gp2-*", > "amzn2-ami-hvm-2.0.*-x86_64-gp2", > "RHEL*HVM-*-x86_64*Hourly2-GP2", > "al2023-ami-2023.*-kernel-*-x86_64" > ] > } > > filter { > name = "architecture" > values = [var.machine_architecture] > } > > filter { > name = "name" > values = ["*${var.distro}*"] > } > > filter { > name = "virtualization-type" > values = ["hvm"] > } > > owners = ["099720109477", "125523088429", "136693071363", "137112412989", "309956199498"] > # Canonical, Fedora, Debian (new), Amazon, RedHat > } > ``` ### GCP 1. In the `deployment-automation` folder, change into the `gcp` directory: ```bash cd gcp ``` 2. Set GCP credentials. Terraform provides multiple ways to set the GCP secret and key. See the [Terraform documentation](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/getting_started). 3. This module generates a properly-configured GCP network within your GCP project by default. You can disable this functionality by commenting out that section of the main.tf and providing your own subnet to var.subnet. 4. You will need to either create a GCP project or provide a Project ID for an existing project. 5. Initialize Terraform: ```bash terraform init ``` 6. Create the cluster: ```bash terraform apply ``` The following example shows how to create a three-broker cluster: ```bash terraform apply --var="public_key_path=~/.ssh/id_rsa.pub" --var "ssh_user=ubuntu" --var="project_name=$GCP_PROJECT_ID" ``` For a full, up-to-date list of configuration options, see the [Terraform module](https://registry.terraform.io/modules/redpanda-data/redpanda-cluster/gcp/latest): ## [](#use-ansible-to-install-redpanda)Use Ansible to install Redpanda 1. From the [`deployment-automation`](https://github.com/redpanda-data/deployment-automation/) folder, set the required Ansible variables: ```bash export CLOUD_PROVIDER= export DEPLOYMENT_PREFIX= export ANSIBLE_COLLECTIONS_PATH=${PWD}/artifacts/collections export ANSIBLE_ROLES_PATH=${PWD}/artifacts/roles export ANSIBLE_INVENTORY=${PWD}/artifacts/hosts_${CLOUD_PROVIDER}_${DEPLOYMENT_PREFIX}.ini ``` 2. Install the roles required by Ansible: ```bash ansible-galaxy install -r requirements.yml ``` ### [](#configure-a-hosts-file)Configure a hosts file > 💡 **TIP** > > Redpanda Data recommends incorporating variables into your $ANSIBLE\_INVENTORY file for every host. Edits made to properties outside of the playbook may be overwritten. If you used Terraform to deploy the instances, the `hosts.ini` is configured automatically in the [`artifacts`](https://github.com/redpanda-data/deployment-automation/tree/main/artifacts) directory. If you didn’t use Terraform, then you must manually update the `[redpanda]` section. When you open the file, you see something like the following: ```ini [redpanda] ip ansible_user=ssh_user ansible_become=True private_ip=pip ip ansible_user=ssh_user ansible_become=True private_ip=pip ip ansible_user=ssh_user ansible_become=True private_ip=pip [monitor] ip ansible_user=ssh_user ansible_become=True private_ip=pip id=1 ``` Under the `[redpanda]` section, replace the following: | Property | Description | | --- | --- | | ip | The public IP address of the machine. | | ansible_user | The username for Ansible to use to SSH to the machine. | | private_ip | The private IP address of the machine. This could be the same as the public IP address. | You can add additional properties to configure features like rack awareness and Tiered Storage. The `[monitor]` section is only required if you want the playbook to install and configure a basic Prometheus and Grafana setup for observability. If you have a centralized monitoring setup or if you don’t require monitoring, then remove this section. ### [](#run-a-playbook)Run a playbook Use the [Ansible Collection for Redpanda](https://galaxy.ansible.com/redpanda/cluster) to build a Redpanda cluster. The recommended Redpanda playbook enables TLS encryption and Tiered Storage. If you prefer, you can download the modules and required roles and create your own playbook. For example, if you want to handle your own data directory, you can toggle that part off, and Redpanda ensures that the permissions are correct. If you want to generate your own security certificates, you can. To install and start a Redpanda cluster in one command with the Redpanda playbook, run: ```bash ansible-playbook --private-key -v ansible/provision-cluster.yml ``` > 📝 **NOTE** > > - The private key corresponds to the public key in the `distro_user` SSH configuration. > > - To use your own playbook, replace `provision-cluster.yml` with your playbook name. > > - When you use a playbook to create a cluster, you should also use the playbook for subsequent operations, like upgrades. The Ansible modules safely handle rolling upgrades, but you must comply with [Redpanda version path requirements](../../../../../upgrade/rolling-upgrade/). #### [](#custom-configuration)Custom configuration You can specify any available Redpanda configuration value, or set of values, by passing a JSON dictionary as an Ansible `extra-var`. These values are spliced with the calculated configuration and only override the values that you specify. Values must be unset manually with `rpk`. There are two sub-dictionaries you can specify: `redpanda.cluster` and `redpanda.node`. For more information, see [Cluster Configuration Properties](../../../../../reference/properties/cluster-properties/) and [Broker Configuration Properties](../../../../../reference/properties/broker-properties/). ```bash export JSONDATA='{"cluster":{"auto_create_topics_enabled":"true"},"node":{"developer_mode":"false"}}' ansible-playbook ansible/.yml --private-key artifacts/testkey -e redpanda="${JSONDATA}" ``` > 📝 **NOTE** > > Adding whitespace to the JSON breaks configuration merging. Use `rpk` and standard Kafka tools to produce and consume from the Redpanda cluster. #### [](#configure-prometheus-and-grafana)Configure Prometheus and Grafana Include a `[monitor]` section in your hosts file if you want the playbook to install and configure a basic Prometheus and Grafana setup for observability. Redpanda emits Prometheus metrics that can be scraped with a central collector. If you already have a centralized monitoring setup or if you don’t require monitoring, then this is unnecessary. To run the `deploy-monitor.yml` playbook: ```bash ansible-playbook ansible/deploy-monitor.yml \ --private-key '' ``` #### [](#configure-redpanda-console)Configure Redpanda Console To install Redpanda Console, add the `redpanda_broker` role to a group with `install_console: true`. The standard playbooks automatically install Redpanda Console on hosts in the `[client]` group. #### [](#build-the-cluster-with-tls-enabled)Build the cluster with TLS enabled Configure TLS with externally-provided and signed certificates. Then run the `provision-cluster-tls.yml` playbook, specifying the certificate locations on new hosts. You can either pass the variables in the command line or edit the file and pass them there. Consider whether you want public access to the Kafka API and Admin API endpoints. For example: ```bash ansible-playbook ansible/provision-cluster-tls.yml \ --private-key '' \ --extra-vars create_demo_certs=false \ --extra-vars advertise_public_ips=false \ --extra-vars handle_certs=false \ --extra-vars redpanda_truststore_file='' ``` It is important to use a signed certificate from a valid CA for production environments. The playbook uses locally-signed certificates that are not recommended for production use. Provide a valid certificate using these variables: ```bash redpanda_certs_dir: /etc/redpanda/certs redpanda_csr_file: "{{ redpanda_certs_dir }}/node.csr" redpanda_key_file: "{{ redpanda_certs_dir }}/node.key" redpanda_cert_file: "{{ redpanda_certs_dir }}/node.crt" redpanda_truststore_file: "{{ redpanda_certs_dir }}/truststore.pem" ``` For testing, you could deploy a local CA to generate private keys and signed certificates: ```bash ansible-playbook ansible/provision-cluster-tiered-storage.yml \ --private-key '' ``` #### [](#add-brokers-to-an-existing-cluster)Add brokers to an existing cluster To add brokers to a cluster, you must add them to the hosts file and run the relevant playbook again. You can add `skip_node=true` to the existing hosts to avoid the playbooks being rerun on them. #### [](#upgrade-a-cluster)Upgrade a cluster The playbook is designed to be idempotent, so it should be suitable for running as part of a CI/CD pipeline or through Ansible Tower. The playbook upgrades the packages and then performs a rolling upgrade, where one broker at a time is upgraded and safely restarted. For all upgrade requirements and recommendations, see [Upgrade Redpanda](../../../../../upgrade/rolling-upgrade/). It is important to test that your upgrade path is safe before using it in production. To upgrade a cluster, run the playbook with a specific target version: ```bash ansible-playbook --private-key ~/.ssh/id_rsa ansible/.yml -e redpanda_version=22.3.10-1 ``` By default, the playbook selects the latest version of the Redpanda packages, but an upgrade is only performed if the `redpanda_install_status` variable is set to `latest`: ```bash ansible-playbook --private-key ~/.ssh/id_rsa ansible/.yml -e redpanda_install_status=latest ``` To upgrade clusters with SASL authentication: ```bash export JSONDATA='{"cluster":{"auto_create_topics_enabled":"true"},"node":{"developer_mode":"false"}}' ansible-playbook ansible/.yml --private-key artifacts/testkey -e redpanda="${JSONDATA}" ``` Similarly, you can put the `redpanda_rpk_opts` into a YAML file protected with Ansible vault. ```bash ansible-playbook --private-key ~/.ssh/id_rsa ansible/.yml --extra-vars=redpanda_install_status=latest --extra-vars @vault-file.yml --ask-vault-pass ``` #### [](#redpanda-ansible-collection-values)Redpanda Ansible Collection values You can pass the following variables as `-e var=value` when running Ansible: | Property | Default value | Description | | --- | --- | --- | | redpanda_organization | redpanda-test | Set this to identify your organization in the asset management system. | | redpanda_cluster_id | redpanda | This helps identify the cluster. | | advertise_public_ips | false | Configure Redpanda to advertise the broker’s public IPs for client communication instead of private IPs. This enables using the cluster from outside its subnet.Note: This is not recommended for production deployments, because your brokers will be public. | | grafana_admin_pass | | Grafana admin user’s password. | | ephemeral_disk | false | Enable file system check for attached disk.This is useful when using attached disks in instances with ephemeral operating system disks like Azure L Series. This allows a file system repair at boot time and ensures that the drive is remounted automatically after a reboot. | | redpanda_mode | production | Enables hardware optimization. | | redpanda_admin_api_port | 9644 | | | redpanda_kafka_port | 9092 | | | redpanda_rpc_port | 33145 | | | redpanda_schema_registry_port | 8081 | | | is_using_unstable | false | Enables access to unstable builds. | | redpanda_version | latest | Version; for example, 22.2.2-1 or 22.3.1~rc1-1. If this value is set, then the package is upgraded if the installed version is lower than what has been specified. | | redpanda_rpk_opts | | Command line options to be passed to instances where rpk is used on the playbook. For example, superuser credentials can be specified as --user myuser --password mypassword. | | redpanda_install_status | present | If redpanda_version is set to latest, then changing redpanda_install_status to latest causes an upgrade; otherwise, the currently-installed version remains. | | redpanda_data_directory | /var/lib/redpanda/data | Path where Redpanda keeps its data. | | redpanda_key_file | /etc/redpanda/certs/node.key | TLS: Path to private key. | | redpanda_cert_file | /etc/redpanda/certs/node.crt | TLS: Path to signed certificate. | | redpanda_truststore_file | /etc/redpanda/certs/truststore.pem | TLS: Path to truststore. | | tls | false | Set to true to configure Redpanda to use TLS. This can be set on each broker, although this may lead to errors configuring rpk. | | skip_node | false | Broker configuration to prevent the redpanda_broker role being applied to this specific broker. Use carefully when adding new brokers to avoid existing brokers from being reconfigured. | | restart_node | false | Broker configuration to prevent Redpanda brokers from being restarted after updating. Use with care: This can cause rpk to be reconfigured but the broker is not restarted and therefore is in an inconsistent state. | | rack | undefined | Broker configuration to enable rack awareness. Rack awareness is enabled cluster-wide if at least one broker has this set. | | tiered_storage_bucket_name | | Set bucket name to enable Tiered Storage. | | schema_registry_replication_factor | 1 | The replication factor of Schema Registry’s internal storage topic. | | aws_region | | The region to be used if Tiered Storage is enabled. | ### [](#troubleshooting)Troubleshooting On macOS, Python may be [unable to fork workers](https://stackoverflow.com/questions/50168647/multiprocessing-causes-python-to-crash-and-gives-an-error-may-have-been-in-progr). You may see something like the following: ```bash ok: [34.209.26.177] => {“changed”: false, “stat”: {“exists”: false}} objc[57889]: +[__NSCFConstantString initialize] may have been in progress in another thread when fork() was called. objc[57889]: +[__NSCFConstantString initialize] may have been in progress in another thread when fork() was called. We cannot safely call it or ignore it in the fork() child process. Crashing instead. Set a breakpoint on objc_initializeAfterForkError to debug. ERROR! A worker was found in a dead state ``` Try setting an environment variable to resolve the error: ```bash export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES ``` ## [](#next-steps)Next steps - If clients connect from a different subnet, see [Configure Listeners](../../../../../manage/security/listener-configuration/). - Observability is essential in production environments. See [Monitor Redpanda](../../../../../manage/monitoring/). ## Suggested labs - [Disaster Recovery with Envoy and Shadowing](/redpanda-labs/docker-compose/envoy-shadowing/) - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Stream Jira Issues to Redpanda for Real-Time Metrics](/redpanda-labs/docker-compose/jira-metrics-pipeline/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Set Up GitOps for the Redpanda Helm Chart](/redpanda-labs/kubernetes/gitops-helm/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) - [Set Up MySQL CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-mysql-json/) - [Set Up Postgres CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-postgres-json/) See more [Search all labs](/redpanda-labs) --- # Page 52: Deploy for Production: Manual **URL**: https://docs.redpanda.com/current/deploy/redpanda/manual/production/production-deployment.md --- # Deploy for Production: Manual --- title: "Deploy for Production: Manual" latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: redpanda/manual/production/production-deployment page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: redpanda/manual/production/production-deployment.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/redpanda/manual/production/production-deployment.adoc description: Steps to deploy a Redpanda production cluster. page-git-created-date: "2025-08-15" page-git-modified-date: "2025-08-15" support-status: supported --- You can deploy Redpanda for production with a default deployment, which uses recommended deployment tools, or with a custom deployment, which uses unsupported deployment tools. > 📝 **NOTE** > > - See [Deploy for Production: Automated](../production-deployment-automation/) to use Terraform and Ansible to deploy Redpanda. > > - See [Redpanda Quickstart](../../../../../get-started/quick-start/) to try out Redpanda in Docker or [Deploy for Development](../dev-deployment/). ## [](#prerequisites)Prerequisites Make sure you meet the [hardware and software requirements](../requirements/). ### [](#tcpip-ports)TCP/IP ports Redpanda uses the following default ports: | Port | Purpose | | --- | --- | | 9092 | Kafka API | | 8082 | HTTP Proxy | | 8081 | Schema Registry | | 9644 | Admin API and Prometheus | | 33145 | internal RPC | ## [](#select-deployment-type)Select deployment type To start deploying Redpanda for production, choose your deployment type: - [Default deployment](#default-deployment): Use recommended deployment tools. - [Custom deployment](#custom-deployment): Use unsupported deployment tools. ## [](#default-deployment)Default deployment This section describes how to set up a production cluster of Redpanda. ### [](#install-redpanda)Install Redpanda Install Redpanda on each system you want to be part of your cluster. There are binaries available for Fedora/RedHat or Debian systems. Unless you intend to run Redpanda in FIPS-compliance mode, the following packages should accommodate your needs (for both Debian and Redhat based systems): `redpanda` - Contains the Redpanda application and all supporting libraries - Depends on `redpanda-tuner` and either `redpanda-rpk` or `redpanda-rpk-fips` `redpanda-rpk` - Contains the pure GoLang compiled `rpk` application - If you wish to use `rpk` only, then this is the only required install package `redpanda-tuner` - Contains the files used to run Redpanda tuners - Depends on `redpanda-rpk` or `redpanda-rpk-fips` #### Fedora/RedHat ```bash curl -1sLf 'https://dl.redpanda.com/nzc4ZYQK3WRGd9sy/redpanda/cfg/setup/bash.rpm.sh' | \ sudo -E bash && sudo yum install redpanda -y ``` > ❗ **IMPORTANT** > > To install a version of Redpanda that is older than the latest available version, you must also specify each dependency. For example, if installing `24.3.1~rc1-1` and you fail to specify each package and its version, you may encounter the following error: > > ```bash > yum install redpanda=24.3.1~rc1-1 > Reading package lists... Done > Building dependency tree... Done > Reading state information... Done > Some packages could not be installed. This may mean that you have > requested an impossible situation or if you are using the unstable > distribution that some required packages have not yet been created > or been moved out of Incoming. > The following information may help to resolve the situation: > > The following packages have unmet dependencies: > redpanda : Depends: redpanda-rpk (= 24.3.1~rc1-1) but it is not going to be installed or > redpanda-rpk-fips (= 24.3.1~rc1-1) but it is not going to be installed > Depends: redpanda-tuner (= 24.3.1~rc1-1) but it is not going to be installed > E: Unable to correct problems, you have held broken packages. > ``` > > To troubleshoot this error, specify the full list of versions for each package. In this case: > > ```bash > yum install \ > redpanda-tuner=24.3.1~rc1-1 \ > redpanda-rpk=24.3.1~rc1-1 \ > redpanda=24.3.1~rc1-1 > ``` #### Debian/Ubuntu ```bash curl -1sLf 'https://dl.redpanda.com/nzc4ZYQK3WRGd9sy/redpanda/cfg/setup/bash.deb.sh' | \ sudo -E bash && sudo apt install redpanda -y ``` > ❗ **IMPORTANT** > > To install a version of Redpanda that is older than the latest available version, you must also specify each dependency. For example, if installing `24.3.1~rc1-1` and you fail to specify each package and its version, you may encounter the following error: > > ```bash > apt install redpanda=24.3.1~rc1-1 > Reading package lists... Done > Building dependency tree... Done > Reading state information... Done > Some packages could not be installed. This may mean that you have > requested an impossible situation or if you are using the unstable > distribution that some required packages have not yet been created > or been moved out of Incoming. > The following information may help to resolve the situation: > > The following packages have unmet dependencies: > redpanda : Depends: redpanda-rpk (= 24.3.1~rc1-1) but it is not going to be installed or > redpanda-rpk-fips (= 24.3.1~rc1-1) but it is not going to be installed > Depends: redpanda-tuner (= 24.3.1~rc1-1) but it is not going to be installed > E: Unable to correct problems, you have held broken packages. > ``` > > To troubleshoot this error, specify the full list of versions for each package. In this case: > > ```bash > apt install \ > redpanda-tuner=24.3.1~rc1-1 \ > redpanda-rpk=24.3.1~rc1-1 \ > redpanda=24.3.1~rc1-1 > ``` ### [](#install-redpanda-for-fips-compliance)Install Redpanda for FIPS compliance > 📝 **NOTE** > > This feature requires an [enterprise license](../../../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../../../get-started/licensing/#self-managed) apply. To install Redpanda for FIPS compliance, install the packages `redpanda-fips` and `redpanda-rpk-fips`, which automatically pull in all required dependencies. `redpanda-fips` - Contains the OpenSSL FIPS-approved module and scripts required to set up and run Redpanda in FIPS-compliance mode. - Depends upon the successful installation of the `redpanda` package. - Includes the `fips.so` cryptographic provider (built from OpenSSL v3.0.9, which is the latest FIPS 140-2 approved module) and a copy of the OpenSSL application. - Executes `openssl fipsinstall` against the `fips.so` module, which generates a `fipsmodule.cnf` file that is used during the module’s POST (power-on-self-test) to validate the integrity of the module. `redpanda-rpk-fips` - Contains a version of `rpk` built with the [Microsoft GoLang compiler](https://github.com/microsoft/go) and [Microsoft’s Go Crypto OpenSSL package](https://github.com/microsoft/go-crypto-openssl) to which `rpk` is linked, and uses the FIPS-approved version of OpenSSL. #### RHEL To install Redpanda for FIPS compliance, run: ```bash curl -1sLf 'https://dl.redpanda.com/nzc4ZYQK3WRGd9sy/redpanda/cfg/setup/bash.rpm.sh' | \ sudo -E bash && sudo yum install redpanda -y ``` > 📝 **NOTE** > > Alternatively, you could run `sudo yum install -y redpanda-fips`, which also picks up and includes the `redpanda` install package. If you wish to only use `rpk` on a FIPS host, run: ```bash sudo yum install -y redpanda-fips redpanda-rpk-fips ``` #### Debian/Ubuntu To install Redpanda for FIPS compliance, run: ```bash sudo apt install redpanda-fips redpanda-rpk-fips ``` > 📝 **NOTE** > > Alternatively, you could run `sudo apt install redpanda-fips`, which also picks up and includes the `redpanda` install package. If you wish to only use `rpk` on a FIPS host, run: ```bash sudo apt install -y redpanda-rpk-fips ``` See also: [Configure Redpanda for FIPS](../../../../../manage/security/fips-compliance/) ### [](#install-redpanda-console)Install Redpanda Console For comprehensive installation and configuration instructions, see [Deploy Redpanda Console on Linux](../../../../console/linux/deploy/). ### [](#tune-the-linux-kernel-for-production)Tune the Linux kernel for production To get the best performance from your hardware, set Redpanda to production mode on each node and run the autotuner tool. The autotuner identifies the hardware configuration of your node and optimizes the Linux kernel to give you the best performance. By default, Redpanda is installed in development mode, which turns off hardware optimization. 1. Make sure that your current Linux user has root privileges. The autotuner requires privileged access to the Linux kernel settings. 2. Set Redpanda to run in [production mode](../../../../../reference/rpk/rpk-redpanda/rpk-redpanda-mode/#production-mode): ```bash sudo rpk redpanda mode production ``` 3. Tune the Linux kernel: ```bash sudo rpk redpanda tune all ``` Changes to the Linux kernel are not persisted. If a node restarts, make sure to run the autotuner again. To automatically tune the Linux kernel on a Redpanda broker after the node restarts, enable the `redpanda-tuner` service, which runs `rpk redpanda tune all`: - For RHEL, after installing the rpm package, run `systemctl` to both start and enable the `redpanda-tuner` service: ```bash sudo systemctl start redpanda-tuner sudo systemctl enable redpanda-tuner ``` - For Ubuntu, after installing the apt package, run `systemctl` to start the `redpanda-tuner` service (which is already enabled): ```bash sudo systemctl start redpanda-tuner ``` For more details, see the [autotuner reference](../../../../../reference/rpk/rpk-redpanda/rpk-redpanda-tune/). ### [](#generate-optimal-io-configuration-settings)Generate optimal I/O configuration settings After tuning the Linux kernel, you can optimize Redpanda for the I/O capabilities of your worker node by using `rpk` to run benchmarks that capture its read/write IOPS and bandwidth capabilities. After running the benchmarks `rpk` saves the results to an I/O configuration file (`io-config.yaml`) that Redpanda reads upon startup to optimize itself for the node. > 📝 **NOTE** > > Unlike the autotuner, it isn’t necessary to run `rpk iotune` each time Redpanda is started, as its I/O output configuration file can be reused for each node that runs on the same type of hardware. Run [rpk iotune](../../../../../reference/rpk/rpk-iotune/): ```bash sudo rpk iotune # takes 10mins ``` For reference, a local NVMe SSD should yield around 1 GB/s sustained writes. `rpk iotune` captures SSD wear and tear and gives accurate measurements of what your hardware is capable of delivering. Run this before benchmarking. If you’re on AWS, GCP, or Azure, creating a new instance and upgrading to an image with a recent Linux kernel version is often the easiest way to work around bad devices. ### [](#bootstrapping)Bootstrap broker configurations Each broker requires a set of broker configurations that determine how all brokers communicate with each other and with clients. Bootstrapping a cluster configures the [listeners](https://docs.redpanda.com/current/reference/glossary/#listener), [seed servers](https://docs.redpanda.com/current/reference/glossary/#seed-server), and [advertised listeners](https://docs.redpanda.com/current/reference/glossary/#advertised-listener), which ensure proper network connectivity and accessibility. Starting in version 23.3.8, `rpk` enhances the bootstrapping process with additional flags for configuring advertised listener addresses directly. Use the [`rpk redpanda config bootstrap`](../../../../../reference/rpk/rpk-redpanda/rpk-redpanda-config-bootstrap/) command to bootstrap Redpanda: ```bash sudo rpk redpanda config bootstrap --self --advertised-kafka --ips ,, && \ sudo rpk redpanda config set redpanda.empty_seed_starts_cluster false ``` Replace the following placeholders: - ``: The `--self` flag tells Redpanda the interfaces to bind to for the Kafka API, the RPC API, and the Admin API. These addresses determine on which network interface and port Redpanda listens for incoming connections. - Set the listener address to `0.0.0.0` to listen on all network interfaces available on the machine. - Set the listener address to a specific IP address to bind the listener to that address, restricting connections to that interface. - ``: The `--advertised-kafka` flag sets a different advertised Kafka address, which is useful for scenarios where the accessible address differs from the bind address. > ❗ **IMPORTANT** > > Redpanda does not allow advertised addresses set to `0.0.0.0`. If you set any advertised addresses to `0.0.0.0`, Redpanda will output startup validation errors. - ``: The `--ips` flag lists all the seed servers in the cluster, including the one being started. > 📝 **NOTE** > > The `--ips` flag must be set _identically_ (with nodes listed in identical order) on each node. Bootstrapping Redpanda updates your `/etc/redpanda/redpanda.yaml` configuration file: `/etc/redpanda/redpanda.yaml` ```yaml redpanda: data_directory: /var/lib/redpanda/data empty_seed_starts_cluster: false seed_servers: - host: address: port: 33145 - host: address: port: 33145 - host: address: port: 33145 rpc_server: address: port: 33145 kafka_api: - address: port: 9092 admin: - address: port: 9644 advertised_rpc_api: address: port: 33145 advertised_kafka_api: - address: port: 9092 ``` #### [](#recommendations)Recommendations - Redpanda Data strongly recommends at least three seed servers when forming a cluster. A larger number of seed servers increases the robustness of consensus and minimizes any chance that new clusters get spuriously formed after brokers are lost or restarted without any data. - It’s important to have one or more seed servers in each fault domain (for example, in each rack or cloud AZ). A higher number provides a stronger guarantee that clusters don’t fracture unintentionally. - It’s possible to change the seed servers for a short period of time after a cluster has been created. For example, you may want to designate one additional broker as a seed server to increase availability. To do this without cluster downtime, add the new broker to the [`seed_servers`](../../../../../reference/properties/broker-properties/) property and restart Redpanda to apply the change on a broker-by-broker basis. #### [](#listeners-for-mixed-environments)Listeners for mixed environments For clusters serving both internal and external clients, configure multiple listeners for the Kafka API to separate internal from external traffic. For more details, see [Configure Listeners](../../../../../manage/security/listener-configuration/). ### [](#start-redpanda)Start Redpanda To start Redpanda: ```bash sudo systemctl start redpanda-tuner redpanda ``` When a Redpanda cluster starts, it instantiates a controller Raft group with all the seed servers specified in the `--ips` flag. After all seed servers complete their startup procedure and become accessible, the cluster is then available. After that, non-seed servers start up and are added to the cluster. ### [](#start-redpanda-console)Start Redpanda Console For instructions on starting and managing Redpanda Console, see [Deploy Redpanda Console on Linux](../../../../console/linux/deploy/). ### [](#verify-the-installation)Verify the installation To verify that the Redpanda cluster is up and running, use `rpk` to get information about the cluster: ```bash rpk cluster info ``` You should see a list of advertised addresses. To create a topic: ```bash rpk topic create ``` If topics were initially created in a test environment with a replication factor of `1`, use `rpk topic alter-config` to change the topic replication factor: ```bash rpk topic alter-config --set replication.factor=3 ``` ### [](#enable-monitoring)Enable monitoring [Monitor Redpanda](../../../../../manage/monitoring/). Observability is essential in production environments. ## [](#custom-deployment)Custom deployment This section provides information for creating your own automation for deploying Redpanda clusters without using any of the tools that Redpanda supports for setting up a cluster, such as Ansible Playbook, Helm Chart, or Kubernetes Operator. > 💡 **TIP** > > Redpanda strongly recommends using one of these supported deployment tools. See [Automate Deploying for Production](../production-deployment-automation/). ### [](#configure-a-bootstrap-file)Configure a bootstrap file Redpanda cluster configuration is written with the Admin API and the `rpk cluster config` CLIs. In the special case where you want to provide configuration to Redpanda before it starts for the first time, you can write a `.bootstrap.yaml` file in the same directory as `redpanda.yaml`. This file is only read on the first startup of the cluster. Any subsequent changes to `.bootstrap.yaml` are ignored, so changes to cluster configuration must be done with the Admin API. The content format is a YAML dictionary of cluster configuration properties. For example, to initialize a cluster with Admin API authentication enabled and a single superuser, the `.bootstrap.yaml` file would contain the following: ```yaml admin_api_require_auth: true superusers: - alice ``` With this configuration, the Admin API is not accessible until you bootstrap a user account. ### [](#bootstrap-a-user-account)Bootstrap a user account When using username/password authentication, it’s helpful to be able to create one user before the cluster starts for the first time. Do this by setting the `RP_BOOTSTRAP_USER` environment variable when starting Redpanda for the first time. The value has the format `RP_BOOTSTRAP_USER=username:password[:mechanism]`. The only supported values for `mechanism` are `SCRAM-SHA-512` or `SCRAM-SHA-256`; if it is omitted, Redpanda defaults to `SCRAM-SHA-256`. For example: `RP_BOOTSTRAP_USER=alice:letmein:SCRAM-SHA-512`. > 📝 **NOTE** > > `RP_BOOTSTRAP_USER` only creates a user account. You must still set up authentication using cluster configuration. ### [](#secure-the-admin-api)Secure the Admin API The Admin API is used to create SASL user accounts and ACLs, so it’s important to think about how you secure it when creating a cluster. - No authentication, but listening only on 127.0.0.1: This may be appropriate if your Redpanda processes are running in an environment where only administrators can access the host. - mTLS authentication: You can generate client and server x509 certificates before starting Redpanda for the first time, refer to them in `redpanda.yaml`, and use the client certificate when accessing the Admin API. - Username/password authentication: Use the combination of `admin_api_require_auth`, `superusers`, and `RP_BOOTSTRAP_USER` to access the Admin API username/password authentication. You probably still want to enable TLS on the Admin API endpoint to protect credentials in flight. ### [](#configure-the-seed-servers)Configure the seed servers Seed servers help new brokers join a cluster by directing requests from newly-started brokers to an existing cluster. The [`seed_servers`](../../../../../reference/properties/broker-properties/#seed_servers) broker property controls how Redpanda finds its peers when initially forming a cluster. It is dependent on the [`empty_seed_starts_cluster`](../../../../../reference/properties/broker-properties/#empty_seed_starts_cluster) broker property. Starting with Redpanda version 22.3, you should explicitly set `empty_seed_starts_cluster` to `false` on every broker, and every broker in the cluster should have the same value set for `seed_servers`. With this set of configurations, Redpanda clusters form with these guidelines: - When a broker starts and it is a seed server (its address is in the `seed_servers` list), it waits for all other seed servers to start up, and it forms a cluster with all seed servers as members. - When a broker starts and it is not a seed server, it sends requests to the seed servers to join the cluster. It is essential that all seed servers have identical values for the `seed_servers` list. Redpanda strongly recommends at least three seed servers when forming a cluster. Each seed server decreases the likelihood of unintentionally forming a split brain cluster. To ensure brokers can always discover the cluster, at least one seed server should be available at all times. By default, for backward compatibility, `empty_seed_starts_cluster` is set to `true`, and Redpanda clusters form with the guidelines used prior to version 22.3: - When a broker starts with an empty `seed_servers` list, it creates a single broker cluster with itself as the only member. - When a broker starts with a non-empty `seed_servers` list, it sends requests to the brokers in that list to join the cluster. You should never have more than one broker with an empty `seed_servers` list, which would result in the creation of multiple clusters. > ❗ **IMPORTANT** > > Redpanda expects its storage to be persistent, and it’s an error to erase a broker’s drive and restart it. However, in some environments (like when migrating to a different Node pool on Kubernetes), truly persistent storage is unavailable, and brokers may find their data volumes erased. For such environments, Redpanda recommends setting `empty_seed_starts_cluster` to false and designating a set of seed servers such that they couldn’t lose their storage simultaneously. ### [](#do-not-configure-broker-ids)Do not configure broker IDs Redpanda automatically generates unique broker IDs for each new broker and assigns it to the [`node_id`](../../../../../reference/properties/broker-properties/) field in the broker configuration. This ensures safe and consistent cluster operations without requiring manual configuration. > ⚠️ **WARNING: Do not set node_id manually.** > > Do not set `node_id` manually. > > Redpanda assigns unique IDs automatically to prevent issues such as: > > - Brokers with empty disks rejoining the cluster. > > - Conflicts during recovery or scaling. > > > Manually setting or reusing `node_id` values, even for decommissioned brokers, can cause cluster inconsistencies and operational failures. ## [](#perform-a-self-test)Perform a self test To understand the performance capabilities of your Redpanda cluster, Redpanda offers built-in self-test features that evaluate the performance of both disk and network operations. For more information, see [Disk and network self-test benchmarks](../../../../../troubleshoot/cluster-diagnostics/diagnose-issues/#self-test). When using the storage bandwidth test, ensure that your results show at least 16,000 IOPS (Input/Output Operations Per Second) for production environments. If your test results are below this threshold, your storage may not be suitable for production Redpanda workloads. ### [](#upgrade-considerations)Upgrade considerations Deployment automation should place each broker into maintenance mode and wait for it to drain leadership before restarting it with a newer version of Redpanda. For more information, see [Upgrade](../../../../../upgrade/rolling-upgrade/). If upgrading multiple [feature release versions of Redpanda](../../../../../upgrade/k-rolling-upgrade/#find-a-new-version) in succession, make sure to verify that each version upgrades to completion before proceeding to the next version. You can verify by reading the `/v1/features` Admin API endpoint and checking that `cluster_version` has increased. Starting with Redpanda version 23.1, the `/v1/features` endpoint also includes a `node_latest_version` attribute, and installers can verify that the cluster has activated any new functionality from a previous upgrade by checking for `cluster_version` == `node_latest_version`. ## [](#next-steps)Next steps - If clients connect from a different subnet, see [Configure Listeners](../../../../../manage/security/listener-configuration/). - Observability is essential in production environments. See [Monitor Redpanda](../../../../../manage/monitoring/). ## [](#suggested-reading)Suggested reading - [Configure Cluster Properties](../../../../../manage/cluster-maintenance/cluster-property-configuration/) - [Redpanda Console Configuration](../../../../../console/config/configure-console/) ## Suggested labs - [Disaster Recovery with Envoy and Shadowing](/redpanda-labs/docker-compose/envoy-shadowing/) - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Stream Jira Issues to Redpanda for Real-Time Metrics](/redpanda-labs/docker-compose/jira-metrics-pipeline/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Set Up GitOps for the Redpanda Helm Chart](/redpanda-labs/kubernetes/gitops-helm/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) - [Set Up MySQL CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-mysql-json/) - [Set Up Postgres CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-postgres-json/) See more [Search all labs](/redpanda-labs) --- # Page 53: Production Readiness Checklist **URL**: https://docs.redpanda.com/current/deploy/redpanda/manual/production/production-readiness.md --- # Production Readiness Checklist --- title: Production Readiness Checklist latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: redpanda/manual/production/production-readiness page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: redpanda/manual/production/production-readiness.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/redpanda/manual/production/production-readiness.adoc page-git-created-date: "2025-08-15" page-git-modified-date: "2026-02-06" support-status: supported --- Before running a production workload on Redpanda, follow this readiness checklist. Redpanda Data recommends using the [automated deployment instructions](../production-deployment-automation/) with Ansible. If you cannot deploy with Ansible, use the [manual deployment instructions](../production-deployment/). > 📝 **NOTE** > > For Kubernetes deployments, see the [Production Readiness Checklist for Kubernetes](../../../kubernetes/k-production-readiness/). ## [](#critical-requirements)Critical requirements The Critical requirements checklist helps you to confirm that: - All required defaults and configuration items are specified. - You have the optimal hardware setup. - Security is enabled. - You are set up to run in production. ### [](#redpanda-license)Redpanda license Check that the [Redpanda License](../../../../../get-started/licensing/) has been loaded into the cluster configuration. This is required to enable [Enterprise](../../../../../get-started/licensing/#redpanda-enterprise-edition) features. Input ```bash rpk cluster license info ``` Output ```bash LICENSE INFORMATION =================== Organization: Redpanda Owlshop LLC Type: enterprise Expires: Mar 25 2025 ``` ### [](#cluster-health)Cluster health Check that all brokers are connected and running. Run [`rpk cluster info`](../../../../../reference/rpk/rpk-cluster/rpk-cluster-info/) to check the health of the cluster. No nodes should be down, and there should be zero leaderless or under-replicated partitions. Then run [`rpk cluster health`](../../../../../reference/rpk/rpk-cluster/rpk-cluster-health/). The cluster should be listed as healthy. Input ```bash rpk cluster info ``` Output ```bash CLUSTER ======= redpanda.be267958-279d-49cd-ae86-98fc7ed2de48 BROKERS ======= ID HOST PORT RACK 0* 54.70.51.189 9092 us-west-2a 1 35.93.178.18 9092 us-west-2b 2 35.91.121.126 9092 us-west-2c ``` Input ```bash rpk cluster health ``` Output ```bash CLUSTER HEALTH OVERVIEW ======================= Healthy: true Unhealthy reasons: [] Controller ID: 0 All nodes: [0 1 2] Nodes down: [] Leaderless partitions (0): [] Under-replicated partitions (0): [] ``` ### [](#production-mode)Production mode enabled Check that Redpanda is running in production mode. To check the status of a Redpanda broker, check its broker configuration in `/etc/redpanda/redpanda.yaml`. Both [`developer_mode`](../../../../../reference/properties/broker-properties/#developer_mode) and [`overprovisioned`](../../../../../reference/rpk/rpk-redpanda/rpk-redpanda-start/) should be `false` or should not be present in the file. If either configuration is set to `true` on any broker, then the cluster is not in full production mode and must be corrected. Input ```bash grep -E 'developer_mode|overprovisioned' /etc/redpanda/redpanda.yaml ``` Output ```bash developer_mode: false overprovisioned: false ``` ### [](#redpanda-reqs)System meets Redpanda requirements Run [`sudo rpk redpanda check`](../../../../../reference/rpk/rpk-redpanda/rpk-redpanda-check/) to ensure that your system meets Redpanda’s requirements. > 📝 **NOTE** > > This command requires sudo because it’s looking in `/proc` or `/sys`, which may be read restricted. Input ```bash sudo rpk redpanda check ``` Output ```bash System check results CONDITION REQUIRED CURRENT SEVERITY PASSED Ballast file present true true Warning true Clock Source tsc tsc Warning true Config file valid true true Fatal true Connections listen backlog size >= 4096 4096 Warning true Data directory filesystem type xfs xfs Warning true Data directory is writable true true Fatal true Data partition free space [GB] >= 10 1755.29 Warning true Dir '/var/lib/redpanda/data' IRQs affinity set true true Warning true Dir '/var/lib/redpanda/data' IRQs affinity static true true Warning true Dir '/var/lib/redpanda/data' nomerges tuned true true Warning true Dir '/var/lib/redpanda/data' scheduler tuned true true Warning true Free memory per CPU [MB] 2048 per CPU 7659 Warning true Fstrim systemd service and timer active true true Warning true I/O config file present true true Warning true Kernel Version 3.19 5.15.0-1056-aws Warning true Max AIO Events >= 1048576 1048576 Warning true Max syn backlog size >= 4096 4096 Warning true NIC IRQs affinity static true true Warning true NTP Synced true true Warning true RFS Table entries >= 32768 32768 Warning true Swap enabled true true Warning true Swappiness 1 1 Warning true Transparent huge pages active true true Warning true ``` ### [](#redpanda-lmr)Latest Redpanda version Check that Redpanda is running the [latest point release](https://github.com/redpanda-data/redpanda/releases) on every node for the major version you’re on. Input ```bash /usr/bin/redpanda --version ``` Output ```bash 26.1.3 - 65d85f6 ``` ### [](#cpu-memory)Correct CPUs and memory configured Check that you have the [correct number of CPUs and sufficient memory](../requirements/#cpu-and-memory) to run Redpanda. Input ```bash journalctl -u redpanda | grep "System resources" ``` Output ```bash Mar 25 12:16:18 ip-172-31-10-199 rpk[3957]: INFO 2024-03-25 12:16:18,105 [shard 0:main] main - application.cc:350 - System resources: { cpus: 8, available memory: 55.578GiB, reserved memory: 3.890GiB} ``` ### [](#mounted-disks)Disks correctly mounted Check that the correct disks are mounted, and if multiple devices are used, they are configured as RAID-0. Other RAID configurations can have significantly worse latencies. The file system should be type XFS. If XFS is unavailable, ext4 is an appropriate alternative. Input ```bash grep data_directory /etc/redpanda/redpanda.yaml data_directory: /var/lib/redpanda/data df -khT /var/lib/redpanda/data ``` Output for NVMe with XFS ```bash Filesystem Type Size Used Avail Use% Mounted on /dev/nvme0n1 xfs 1.8T 14G 1.8T 1% /mnt/vectorized ``` Output for mdadm RAID mount point ```bash Filesystem Type Size Used Avail Use% Mounted on /dev/md0 xfs 14T 99G 14T 1% /mnt/vectorized ``` Example for how to get more details about the RAID array: Input ```bash mdadm --detail /dev/md0 ``` Output ```bash /dev/md0: Version : 1.2 Creation Time : Thu Apr 18 11:03:46 2024 Raid Level : raid0 Array Size : 14648172544 (13969.59 GiB 14999.73 GB) Raid Devices : 2 Total Devices : 2 Persistence : Superblock is persistent Update Time : Thu Apr 18 11:03:46 2024 State : clean Active Devices : 2 Working Devices : 2 Failed Devices : 0 Spare Devices : 0 Layout : -unknown- Chunk Size : 512K Consistency Policy : none Name : ip-172-31-24-82:0 (local to host ip-172-31-24-82) UUID : e9574118:10d562bf:ed3ca2d9:68ccc3a6 Events : 0 Number Major Minor RaidDevice State 0 259 2 0 active sync /dev/nvme2n1 1 259 0 1 active sync /dev/nvme1n1 ``` Use these results to verify that the expected disks are present and the expected RAID level is set. (Typically, this would be `raid0` in a production system, as data resilience is provided by Raft across Redpanda brokers, rather than by RAID.) ### [](#auth-enable)Authentication enabled Check that [authentication](../../../../../manage/security/authentication/) is set up (or other mitigations are in place). Without SASL authentication enabled, anybody can potentially connect to the Redpanda brokers. Input ```bash rpk cluster config get kafka_enable_authorization ``` Output ```bash true ``` ### [](#super-users)Superusers configured Check that the [Admin API is secured](../production-deployment/#secure-the-admin-api), and any users defined in the superusers configuration are appropriately protected with strong credentials. See also: xref:manage:security/authentication.adoc#create-superusers ### [](#tls-enabled)TLS enabled Check that all public interfaces have [TLS enabled](../../../../../manage/security/encryption/). Input ```bash journalctl -u redpanda.service | grep tls ``` Output ```bash Jun 06 12:41:35 ip-172-31-31-199 rpk[9673]: INFO 2024-06-06 12:41:35,513 [shard 0:main] main - application.cc:772 - redpanda.cloud_storage_disable_tls:0 - Disable TLS for all S3 connections Jun 06 12:41:35 ip-172-31-31-199 rpk[9673]: INFO 2024-06-06 12:41:35,514 [shard 0:main] main - application.cc:772 - redpanda.kafka_mtls_principal_mapping_rules:{nullopt} - Principal Mapping Rules for mTLS Authentication on the Kafka API Jun 06 12:41:35 ip-172-31-31-199 rpk[9673]: INFO 2024-06-06 12:41:35,514 [shard 0:main] main - application.cc:772 - **redpanda.admin_api_tls:{{name: , tls_config: { enabled: 1** key/cert files: {{ key_file: /etc/redpanda/certs/node.key cert_file: /etc/redpanda/certs/node.crt }} ca file: {/etc/redpanda/certs/truststore.pem} client_auth_required: 0 }}} - TLS configuration for admin HTTP server Jun 06 12:41:35 ip-172-31-31-199 rpk[9673]: INFO 2024-06-06 12:41:35,515 [shard 0:main] main - application.cc:772 - **redpanda.kafka_api_tls:{{name: , tls_config: { enabled: 1** key/cert files: {{ key_file: /etc/redpanda/certs/node.key cert_file: /etc/redpanda/certs/node.crt }} ca file: {/etc/redpanda/certs/truststore.pem} client_auth_required: 0 }}} - TLS configuration for Kafka API endpoint Jun 06 12:41:35 ip-172-31-31-199 rpk[9673]: INFO 2024-06-06 12:41:35,515 [shard 0:main] main - application.cc:772 - **redpanda.rpc_server_tls:{ enabled: 1** key/cert files: {{ key_file: /etc/redpanda/certs/node.key cert_file: /etc/redpanda/certs/node.crt }} ca file: {/etc/redpanda/certs/truststore.pem} client_auth_required: 0 } - TLS configuration for RPC server Jun 06 12:41:35 ip-172-31-31-199 rpk[9673]: INFO 2024-06-06 12:41:35,515 [shard 0:main] main - application.cc:772 - pandaproxy.pandaproxy_api_tls:{} - TLS configuration for Pandaproxy api Jun 06 12:41:35 ip-172-31-31-199 rpk[9673]: INFO 2024-06-06 12:41:35,515 [shard 0:main] main - application.cc:772 - **pandaproxy_client.broker_tls:{ enabled: 1** key/cert files: {{ key_file: /etc/redpanda/certs/node.key cert_file: /etc/redpanda/certs/node.crt }} ca file: {/etc/redpanda/certs/truststore.pem} client_auth_required: 0 } - TLS configuration for the brokers Jun 06 12:41:35 ip-172-31-31-199 rpk[9673]: INFO 2024-06-06 12:41:35,515 [shard 0:main] main - application.cc:772 - **schema_registry.schema_registry_api_tls:{{name: , tls_config: { enabled: 1** key/cert files: {{ key_file: /etc/redpanda/certs/node.key cert_file: /etc/redpanda/certs/node.crt }} ca file: {/etc/redpanda/certs/truststore.pem} client_auth_required: 0 }}} - TLS configuration for Schema Registry API Jun 06 12:41:35 ip-172-31-31-199 rpk[9673]: INFO 2024-06-06 12:41:35,515 [shard 0:main] main - application.cc:772 - **schema_registry_client.broker_tls:{ enabled: 1** key/cert files: {{ key_file: /etc/redpanda/certs/node.key cert_file: /etc/redpanda/certs/node.crt }} ca file: {/etc/redpanda/certs/truststore.pem} client_auth_required: 0 } - TLS configuration for the brokers Jun 06 12:41:35 ip-172-31-31-199 rpk[9673]: INFO 2024-06-06 12:41:35,515 [shard 0:main] main - application.cc:772 - audit_log_client.broker_tls:{ enabled: 1 key/cert files: {{ key_file: /etc/redpanda/certs/node.key cert_file: /etc/redpanda/certs/node.crt }} ca file: {/etc/redpanda/certs/truststore.pem} client_auth_required: 0 } - TLS configuration for the brokers ``` Using the logs on each broker, check to verify that the following interfaces have TLS enabled: - Kafka API - Admin REST API - Internal RPC Server - Schema Registry - HTTP Proxy (Pandaproxy) In the logs, verify `enabled: 1`. See also: [Multiple listeners](../../../../../manage/security/listener-configuration/#multiple-listeners) > 📝 **NOTE** > > You can also use the [`/v1/security/report`](/api/doc/admin/operation/operation-get_security_report) Admin API endpoint to generate a security report for your cluster and verify TLS, authentication, and authorization settings: > > ```bash > curl 'http://localhost:9644/v1/security/report' > ``` ### [](#redpanda-tuners)Run Redpanda tuners Check that you have run tuners on all cluster hosts. This can have a significant impact on latency and throughput. [Redpanda tuners](../../../../../reference/rpk/rpk-redpanda/rpk-redpanda-tune/) ensure that the operating system is configured for optimal performance. In Kubernetes, you may need to run the tuners on the hosts themselves, rather than in containers. Input ```bash systemctl status redpanda-tuner ``` Output ```bash redpanda-tuner.service - Redpanda Tuner Loaded: loaded (/lib/systemd/system/redpanda-tuner.service; enabled; vendor preset: enabled) Active: active (exited) since Mon 2024-03-25 12:03:51 UTC; 48min ago Process: 3795 ExecStart=/usr/bin/rpk redpanda tune all $CPUSET (code=exited, status=0/SUCCESS) Main PID: 3795 (code=exited, status=0/SUCCESS) Mar 25 12:03:51 ip-172-31-10-199 rpk[3795]: cpu true true true Mar 25 12:03:51 ip-172-31-10-199 rpk[3795]: disk_irq true true true Mar 25 12:03:51 ip-172-31-10-199 rpk[3795]: disk_nomerges true true true Mar 25 12:03:51 ip-172-31-10-199 rpk[3795]: disk_scheduler true true true Mar 25 12:03:51 ip-172-31-10-199 rpk[3795]: disk_write_cache false true false Disk write cache tuner is only supported in GCP Mar 25 12:03:51 ip-172-31-10-199 rpk[3795]: fstrim false false true Mar 25 12:03:51 ip-172-31-10-199 rpk[3795]: net true true true Mar 25 12:03:51 ip-172-31-10-199 rpk[3795]: swappiness true true true Mar 25 12:03:51 ip-172-31-10-199 rpk[3795]: transparent_hugepages false false true Mar 25 12:03:51 ip-172-31-10-199 systemd[1]: Finished Redpanda Tuner. ``` Check that [`rpk iotune`](../../../../../reference/rpk/rpk-iotune/) has been run on all hosts. Ensure that the mountpoint listed in this configuration file matches the mountpoint for Redpanda’s data directory, usually `/var/lib/redpanda`. See [Generate optimal I/O configuration settings](../production-deployment/#generate-optimal-io-configuration-settings). See also: - [Tune the Linux kernel for production](../production-deployment/#tune-the-linux-kernel-for-production) - [Tune Kubernetes Worker Nodes for Production](../../../kubernetes/k-tune-workers/) Input ```bash cat /etc/redpanda/io-config.yaml disks: - mountpoint: /mnt/vectorized read_iops: 413115 read_bandwidth: 1882494592 write_iops: 182408 write_bandwidth: 788050688 ``` ### [](#disk-perf)Check disk performance Run [`rpk cluster self-test status`](../../../../../reference/rpk/rpk-cluster/rpk-cluster-self-test-status/) to ensure that disk performance is within an acceptable range. See also: [Cluster Diagnostics](../../../../../troubleshoot/cluster-diagnostics/diagnose-issues/) Input ```bash rpk cluster self-test status ``` Output ```bash NODE ID: 1 | STATUS: IDLE ========================= NAME 512KB sequential r/w throughput disk test INFO write run TYPE disk TEST ID e13b2c93-2417-458b-87be-fac409089513 TIMEOUTS 0 DURATION 30000ms IOPS 984 req/sec THROUGHPUT 492.1MiB/sec LATENCY P50 P90 P99 P999 MAX 4095us 4095us 4351us 4607us 5119us ``` ### [](#hostnames-interfaces)Advertised hostnames use correct interfaces Check that the advertised hostnames are operating on the correct network interfaces. For clusters with multiple interfaces (for example, a public and private IP address), set [`advertised_kafka_api`](../../../../../reference/properties/broker-properties/#advertised_kafka_api) to the public interface and set [`advertised_rpc_api`](../../../../../reference/properties/broker-properties/#advertised_rpc_api) to the private interface. These should be hostnames, not IP addresses. Example ```bash grep -A2 advertised /etc/redpanda/redpanda.yaml advertised_kafka_api: - address: myhostname.customdomain.com port: '9092' advertised_rpc_api: address: myinternalhostname.customdomain.com port: '33145' ``` ### [](#continuous-db)Confirm Continuous Data Balancing configuration Run [`rpk cluster config get partition_autobalancing_mode`](../../../../../reference/rpk/rpk-cluster/rpk-cluster-config-get/) to ensure that [Continuous Data Balancing](../../../../../manage/cluster-maintenance/continuous-data-balancing/) is configured and enabled. Input ```bash rpk cluster config get partition_autobalancing_mode ``` Output ```bash continuous ``` ### [](#debug-bundle)Generate debug bundle Check that you can generate a debug bundle from each host and upload it to [Redpanda support](https://support.redpanda.com/hc/en-us/requests/new). This is how you can collect data and export it to Redpanda support. Input ```bash sudo rpk debug bundle ``` Output ```bash Creating bundle file... Debug bundle saved to '1711372017-bundle.zip' ``` See also: - [rpk debug bundle](../../../../../reference/rpk/rpk-debug/rpk-debug-bundle/) - [Diagnostics Bundles in Kubernetes](../../../../../troubleshoot/debug-bundle/generate/kubernetes/) ### [](#topic-rf)Topic replication factor Check that all topics have a replication factor greater than one. Input ```bash rpk topic list ``` Output ```bash NAME PARTITIONS REPLICAS bad 1 1 good 1 3 ``` Redpanda Data recommends that you set `minimum_topic_replications` and `default_topic_replications` to at least 3. ```bash rpk cluster config set minimum_topic_replications=3 rpk cluster config set default_topic_replications=3 ``` See also: [Change topic replication factor](../../../../../migrate/data-migration/#change-topic-replication-factor) ### [](#maintenance-mode)No brokers in maintenance mode Check that no brokers are in maintenance mode. Input ```bash rpk cluster maintenance status ``` Output ```bash NODE-ID ENABLED FINISHED ERRORS PARTITIONS ELIGIBLE TRANSFERRING FAILED 1 false - - - - - - 2 false - - - - - - 3 false - - - - - - ``` See also: [Remove a broker from maintenance mode](../../../../../manage/node-management/#place-a-broker-in-maintenance-mode) ### [](#decom-state)No brokers in decommissioned state Check that no brokers are in a decommissioned state. Input ```bash rpk redpanda admin brokers list ``` Output ```bash NODE-ID NUM-CORES MEMBERSHIP-STATUS IS-ALIVE BROKER-VERSION 0 1 active true v24.1.6 - 5e880f6fd1a610d0991b00e32c012a03b14888ca 1 1 active true v24.1.6 - 5e880f6fd1a610d0991b00e32c012a03b14888ca 2 1 active true v24.1.6 - 5e880f6fd1a610d0991b00e32c012a03b14888ca ``` See also: [Decommission Brokers](../../../../../manage/cluster-maintenance/decommission-brokers/) ## [](#recommended-requirements)Recommended requirements The Recommended requirements checklist confirms that you can monitor and support your environment on a sustained basis. It includes the following checks: - You have adhered to day-2 operations best practices. - You can diagnose and recover from issues or failures. ### [](#environment-configuration)Environment configuration Check that you have a [development environment](../dev-deployment/) or test environment configured to evaluate upgrades and new versions before rolling them straight to production. ### [](#monitoring)Monitoring Check that [monitoring](../../../../../manage/monitoring/) is configured with [Prometheus](../../../../../manage/monitoring/#configure-prometheus), [Grafana](../../../../../manage/monitoring/#generate-grafana-dashboard), or [Datadog](https://www.datadoghq.com/product/log-management/) to scrape metrics from all Redpanda brokers at a regular interval. ### [](#system-log-retention)System log retention Check that system logs are being captured and stored for an appropriate period of time (minimally, 7 days). On bare metal, this may be journald. On Kubernetes you may need to have fluentd or an equivalent configured, with logs sent to a central location. See also: [rpk debug bundle](../../../../../reference/rpk/rpk-debug/rpk-debug-bundle/) ### [](#upgrade-policy)Upgrade policy Check that you have an upgrade policy defined and implemented. Redpanda Enterprise Edition supports [rolling upgrades](../../../../../upgrade/rolling-upgrade/#perform-a-rolling-upgrade), so upgrades do not require downtime. However, make sure that upgrades are scheduled on a regular basis, ideally using automation such as [Ansible](../production-deployment-automation/#use-ansible-to-install-redpanda) or [Helm](../../../../../manage/kubernetes/k-configure-helm-chart/). ### [](#high-availability)High availability If you have [high availability](../../../../../manage/high-availability/) requirements, check that the cluster is configured across multiple availability zones or fault domains. Input ```bash rpk cluster info ``` Output ```bash CLUSTER ======= redpanda.be267958-279d-49cd-ae86-98fc7ed2de48 BROKERS ======= ID HOST PORT RACK 0* 54.70.51.189 9092 us-west-2a 1 35.93.178.18 9092 us-west-2b 2 35.91.121.126 9092 us-west-2c ``` Check that [rack awareness](../../../../../manage/rack-awareness/#configure-rack-awareness) is configured correctly. Input ```bash rpk cluster config get enable_rack_awareness ``` Output ```bash true ``` See also: - [Multi-AZ deployments](../../../../../manage/high-availability/#multi-az-deployments) - [Configure rack awareness in Kubernetes](../../../../../manage/kubernetes/k-rack-awareness/#configure-rack-awareness) ## [](#advanced-requirements)Advanced requirements The Advanced requirements checklist ensures full enterprise readiness, indicates that your system is operating at the highest level of availability, and can prevent or recover from the most serious incidents. The advanced requirements confirm the following: - You are proactively monitoring mission-critical workloads, business continuity solutions, and integration into enterprise security systems. - Your enterprise is ready to run mission-critical workloads. ### [](#configure-alerts)Configure alerts A standard set of alerts for [Grafana](../../../../../manage/monitoring/#generate-grafana-dashboard) or [Prometheus](../../../../../manage/monitoring/#configure-prometheus) is provided in the [GitHub Redpanda observability repo](https://github.com/redpanda-data/observability). However, you should customize these alerts for your specific needs. See also: [Monitoring Metrics](../../../../../reference/monitor-metrics/) ### [](#backup-and-disaster-recovery-dr-solution)Backup and disaster recovery (DR) solution Check that you have a backup and disaster recovery (DR) solution in place. You can configure backup and restore using [Tiered Storage Whole Cluster Recovery](../../../../../manage/disaster-recovery/whole-cluster-restore/). Be sure to confirm that the backup and DR solution has been tested. For disaster recovery, confirm that a standby cluster is configured and running with replication (such as [MirrorMaker2](../../../../../migrate/data-migration/)). Also verify that your monitoring ensures that MirrorMaker2 is running and checks replication traffic. See [High-availability deployment of Redpanda: Patterns and considerations](https://redpanda.com/blog/high-availability-software-deployment-patterns-part-1) for more details about HA and DR options. ### [](#deployment-automation)Deployment automation Review your deployment automation. Specifically, if you need to reprovision a cluster, ensure that cluster installation is managed using automation such as [Terraform](../production-deployment-automation/#use-terraform-to-set-up-infrastructure), [Ansible](../production-deployment-automation/#use-ansible-to-install-redpanda), or [Helm](../../../../../manage/kubernetes/k-configure-helm-chart/), and that the configuration is saved in source control. ### [](#audit-logs)Audit logs Check that your [audit logs](../../../../../manage/audit-logging/#audit-log-flow) are forwarded to an enterprise security information and event management (SIEM) system. ### [](#monitor-security-settings)Monitor security settings Regularly review your cluster’s security settings using the [`/v1/security/report`](/api/doc/admin/operation/operation-get_security_report) Admin API endpoint. Investigate and address any issues identified in the alerts section. Input ```bash curl 'http://localhost:9644/v1/security/report' ``` View output ```bash { "interfaces": { "kafka": [ { "name": "test_kafka_listener", "host": "0.0.0.0", "port": 9092, "advertised_host": "0.0.0.0", "advertised_port": 9092, "tls_enabled": false, "mutual_tls_enabled": false, "authentication_method": "None", "authorization_enabled": false } ], "rpc": { "host": "0.0.0.0", "port": 33145, "advertised_host": "127.0.0.1", "advertised_port": 33145, "tls_enabled": false, "mutual_tls_enabled": false }, "admin": [ { "name": "test_admin_listener", "host": "0.0.0.0", "port": 9644, "tls_enabled": false, "mutual_tls_enabled": false, "authentication_methods": [], "authorization_enabled": false } ] }, "alerts": [ { "affected_interface": "kafka", "listener_name": "test_kafka_listener", "issue": "NO_TLS", "description": "\"kafka\" interface \"test_kafka_listener\" is not using TLS. This is insecure and not recommended." }, { "affected_interface": "kafka", "listener_name": "test_kafka_listener", "issue": "NO_AUTHN", "description": "\"kafka\" interface \"test_kafka_listener\" is not using authentication. This is insecure and not recommended." }, { "affected_interface": "kafka", "listener_name": "test_kafka_listener", "issue": "NO_AUTHZ", "description": "\"kafka\" interface \"test_kafka_listener\" is not using authorization. This is insecure and not recommended." }, { "affected_interface": "rpc", "issue": "NO_TLS", "description": "\"rpc\" interface is not using TLS. This is insecure and not recommended." }, { "affected_interface": "admin", "listener_name": "test_admin_listener", "issue": "NO_TLS", "description": "\"admin\" interface \"test_admin_listener\" is not using TLS. This is insecure and not recommended." }, { "affected_interface": "admin", "listener_name": "test_admin_listener", "issue": "NO_AUTHZ", "description": "\"admin\" interface \"test_admin_listener\" is not using authorization. This is insecure and not recommended." }, { "affected_interface": "admin", "listener_name": "test_admin_listener", "issue": "NO_AUTHN", "description": "\"admin\" interface \"test_admin_listener\" is not using authentication. This is insecure and not recommended." } ] } ``` ## [](#suggested-reading)Suggested reading - [Deploy for Production: Manual](../production-deployment/) - [Deploy for Production: Automated](../production-deployment-automation/) --- # Page 54: Requirements and Recommendations **URL**: https://docs.redpanda.com/current/deploy/redpanda/manual/production/requirements.md --- # Requirements and Recommendations --- title: Requirements and Recommendations latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: redpanda/manual/production/requirements page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: redpanda/manual/production/requirements.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/redpanda/manual/production/requirements.adoc description: A list of requirements and recommendations for provisioning servers to run Redpanda in production. page-git-created-date: "2025-08-15" page-git-modified-date: "2025-08-15" support-status: supported --- This topic provides the requirements and recommendations for provisioning servers to run Redpanda in production. ## [](#operating-system)Operating system - Minimum version required of RHEL/CentOS: 8. **Recommended**: 9+ - Minimum version required of Ubuntu: 20.04 LTS. **Recommended**: 22.04+ **Recommendation**: Linux kernel 4.19 or later for better performance. ## [](#number-of-workers)Number of nodes Provision one physical node or virtual machine (VM) for each Redpanda broker that you plan to deploy in your Redpanda cluster. Each Redpanda broker requires its own dedicated node for the following reasons: - **Resource isolation**: Redpanda brokers are designed to make full use of available system resources, including CPU and memory. By dedicating a node to each broker, you ensure that these resources aren’t shared with other applications or processes, avoiding potential performance bottlenecks or contention. - **External networking**: External clients should connect directly to the broker that owns the partition they’re interested in. This means that each broker must be individually addressable. As clients must connect to the specific broker that is the leader of the partition, they need a mechanism to directly address each broker in the cluster. Assigning each broker to its own dedicated node makes this direct addressing feasible, since each node will have a unique address. See [External networking](#external-networking). - **Fault tolerance**: Ensuring each broker operates on a separate node enhances fault tolerance. If one node experiences issues, it won’t directly impact the other brokers. **Recommendations**: Deploy at least three Redpanda brokers. ## [](#node-updates)Prevent automatic node upgrades Ensure that node and operating system (OS) upgrades are manually managed when running Redpanda in production. Manual control avoids unplanned reboots or replacements that disrupt Redpanda brokers, causing service downtime, data loss, or quorum instability. Common issues with automatic node upgrades include: - Hard timeouts for graceful shutdowns that do not allow Redpanda brokers enough time to complete decommissioning or leadership transitions. - Replacements or reboots without ensuring data has been safely migrated or replicated, risking data loss. - Parallel upgrades across multiple nodes, which can disrupt quorum or reduce cluster availability. **Requirements**: - Disable automatic node maintenance or upgrades. ## [](#cpu-and-memory)CPU and memory **Requirements**: - Each node must have at least two physical CPU cores. - x86\_64 (Westmere or newer) and AWS Graviton processors are supported. - Each Redpanda broker must have at least 2 GB of memory per core. - Each Redpanda broker must have at least 2 MB of memory for each topic partition replica. The total memory available for partition replicas is determined as a percentage of the cluster’s total memory, which is controlled by the [`topic_partitions_memory_allocation_percent`](../../../../../reference/properties/cluster-properties/#topic_partitions_memory_allocation_percent) setting. Each partition replica consumes [`topic_memory_per_partition`](../../../../../reference/properties/cluster-properties/#topic_memory_per_partition) bytes from this pool. If insufficient memory is available, topic operations will fail. You can adjust the allocation ratio using `topic_partitions_memory_allocation_percent`, but doing so is not recommended, as lowering it may lead to instability or degraded performance. **Recommendations**: - Four physical cores for each node are strongly recommended. ## [](#storage)Storage **Requirements**: - NVMe (Non-Volatile Memory Express) drives are required for production deployments. NVMe drives provide the high throughput and low latency needed for optimal Redpanda performance. - At least 16,000 IOPS (Input/Output Operations Per Second). See also: [Disk and network self-test benchmarks](../../../../../troubleshoot/cluster-diagnostics/diagnose-issues/#self-test). - An XFS or ext4 file system. The Redpanda data directory (`/var/lib/redpanda/data`) and the Tiered Storage cache must be mounted on an XFS or ext4 file system. > ⚠️ **CAUTION** > > The Network File System (NFS) is unsupported for use as the storage mechanism for the Redpanda data directory or for the Tiered Storage cache. **Recommendations**: - Use an XFS file system for its enhanced performance with Redpanda workloads. - For setups with multiple disks, use a RAID-0 (striped) array. It boosts speed but lacks redundancy. A disk failure can lead to data loss. ## [](#security)Security **Recommendations**: - If you’re using a cloud platform, use [IAM roles](../../../../../manage/security/iam-roles/) to restrict access to resources in your cluster. - Secure your Redpanda cluster with TLS encryption and SASL authentication. ## [](#external-networking)External networking - For external access, each node in your cluster must have a static, externally accessible IP address. - Minimum 10 GigE (10 Gigabit Ethernet) connection to ensure: - High data throughput - Reduced data transfer latency - Scalability for increased network traffic ## [](#tuning)Tuning Before deploying Redpanda to production, each node that runs Redpanda must be tuned to optimize the Linux kernel for Redpanda processes. As part of your system tuning, be aware that enabling SELinux (Security-Enhanced Linux) can introduce performance overhead. If SELinux is not required for your environment, Redpanda Data recommends disabling it for optimal performance. See [Deploy for Production: Manual](../production-deployment/). ## [](#object-storage-providers-for-tiered-storage)Object storage providers for Tiered Storage Redpanda supports the following storage providers for Tiered Storage: - Amazon Simple Storage Service (S3) - Google Cloud Storage (GCS), using the Google Cloud Platform S3 API - Azure Blob Storage (ABS) ## [](#cloud-instance-types)Cloud instance types **Recommendations**: - Use a cloud instance type that supports locally attached NVMe devices with an XFS file system. NVMe devices offer high I/O operations per second (IOPS) and minimal latency, while XFS offers enhanced performance with Redpanda workloads. ### [](#amazon)Amazon - General purpose: General-purpose instances provide a balance of compute, memory, and networking resources, and they can be used for a variety of diverse workloads. - [M5d](https://aws.amazon.com/ec2/instance-types/m5/) - [M5ad](https://aws.amazon.com/ec2/instance-types/m5/) - [M5dn](https://aws.amazon.com/ec2/instance-types/m5/) - [M6gd](https://aws.amazon.com/ec2/instance-types/m6g/) - [M7gd](https://aws.amazon.com/ec2/instance-types/m7g/) - Memory optimized: Memory-optimized instances are designed to deliver fast performance for workloads that process large data sets in memory. - [R5ad](https://aws.amazon.com/ec2/instance-types/r5/) - [R5d](https://aws.amazon.com/ec2/instance-types/r5/) - [R5dn](https://aws.amazon.com/ec2/instance-types/r5/) - [R6gd](https://aws.amazon.com/ec2/instance-types/r6g/) - [R6id](https://aws.amazon.com/ec2/instance-types/r6i/) - [R6idn](https://aws.amazon.com/ec2/instance-types/r6i/) - [R7gd](https://aws.amazon.com/ec2/instance-types/r7g/) - [X2gd](https://aws.amazon.com/ec2/instance-types/x2/) - [X2idn](https://aws.amazon.com/ec2/instance-types/x2i/) - [X2iedn](https://aws.amazon.com/ec2/instance-types/x2i/) - [z1d](https://aws.amazon.com/ec2/instance-types/z1d/) - Storage optimized: Storage-optimized instances are designed for workloads that require high, sequential read and write access to very large data sets on local storage. They are optimized to deliver tens of thousands of low-latency, random IOPS to applications. - [I4g, Is4gen, Im4gn](https://aws.amazon.com/ec2/instance-types/i4g/) - [I4i](https://aws.amazon.com/ec2/instance-types/i4i/) - [I3](https://aws.amazon.com/ec2/instance-types/i3/) - [I3en](https://aws.amazon.com/ec2/instance-types/i3en/) - Compute optimized: Compute-optimized instances deliver cost-effective high performance at a low price per compute ratio for running advanced compute-intensive workloads. - [C5d](https://aws.amazon.com/ec2/instance-types/c5/) - [C5ad](https://aws.amazon.com/ec2/instance-types/c5/) ### [](#azure)Azure - General purpose: General purpose VM sizes provide balanced CPU-to-memory ratio. Ideal for testing and development, small to medium databases, and low to medium traffic web servers. - [Standard\_D2d\_v5](https://learn.microsoft.com/en-us/azure/virtual-machines/sizes/general-purpose/ddv5-series?tabs=sizebasic) - [Standard\_D4d\_v5](https://learn.microsoft.com/en-us/azure/virtual-machines/sizes/general-purpose/ddv5-series?tabs=sizebasic) - [Standard\_D32d\_v5](https://learn.microsoft.com/en-us/azure/virtual-machines/sizes/general-purpose/ddv5-series?tabs=sizebasic) ### [](#google)Google - General purpose: The general-purpose machine family has the best price-performance with the most flexible vCPU to memory ratios, and provides features that target most standard and cloud-native workloads. - [C3 machine series with local SSD](https://cloud.google.com/compute/docs/general-purpose-machines#c3-with-local-ssd) - [N2 machine series](https://cloud.google.com/compute/docs/general-purpose-machines#n2_series) - [N2D machine series](https://cloud.google.com/compute/docs/general-purpose-machines#n2d_machines) - Memory optimized: The memory-optimized machine family provides the most compute and memory resources of any Compute Engine machine family offering. They are ideal for workloads that require higher memory-to-vCPU ratios than the high-memory machine types in the general-purpose N1 machine series. - [M3 machine series](https://cloud.google.com/compute/docs/memory-optimized-machines#m3_series) - Compute optimized: Compute-optimized VM instances are ideal for compute-intensive and high-performance computing (HPC) workloads. - [C2D machine series](https://cloud.google.com/compute/docs/compute-optimized-machines#c2d_series) - [C2 machine series](https://cloud.google.com/compute/docs/compute-optimized-machines#c2_machine_types) ## [](#next-steps)Next steps - [Linux Deployment Options](../) ## [](#suggested-reading)Suggested reading - [Sizing Guidelines](../../sizing/) - [Manage Disk Space](../../../../../manage/cluster-maintenance/disk-utilization/) ## Suggested labs - [Disaster Recovery with Envoy and Shadowing](/redpanda-labs/docker-compose/envoy-shadowing/) - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Stream Jira Issues to Redpanda for Real-Time Metrics](/redpanda-labs/docker-compose/jira-metrics-pipeline/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Set Up GitOps for the Redpanda Helm Chart](/redpanda-labs/kubernetes/gitops-helm/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) - [Set Up MySQL CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-mysql-json/) - [Set Up Postgres CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-postgres-json/) See more [Search all labs](/redpanda-labs) --- # Page 55: Sizing Use Cases **URL**: https://docs.redpanda.com/current/deploy/redpanda/manual/sizing-use-cases.md --- # Sizing Use Cases --- title: Sizing Use Cases latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: redpanda/manual/sizing-use-cases page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: redpanda/manual/sizing-use-cases.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/redpanda/manual/sizing-use-cases.adoc description: How to size Redpanda clusters for low, medium, and high throughput use cases in your data center or in object storage. page-git-created-date: "2025-08-15" page-git-modified-date: "2025-08-15" support-status: supported --- The following scenarios provide estimates and advice for sizing Redpanda clusters for different throughput and retention use cases in your data center and in object storage. For details about sizing considerations, see [Sizing Guidelines](../sizing/). > 📝 **NOTE** > > These use cases assume a happy path with known metrics and expected outputs, but many other factors can influence performance, such as batch size and other sources of network traffic. ## [](#low-throughput)Low throughput | Metric | Value | | --- | --- | | Producer throughput | 75 MB/sec (600 Mbps) | | Producer rate | 300 messages per second | | Consumer throughput | 75 MB/sec (600 Mbps) | | Consumer rate | 300 messages per second | | Data retention | 3 days | | Average message size | 250 KB | | Failure tolerance | 1 node | In this use case, despite the relatively low throughput of 150 MB/sec (producer plus consumer), it’s important to calculate the expected bandwidth utilization and to use a network testing tool like iPerf to verify that the bandwidth is available and sustainable. With a single topic with a replication factor of three, producing 75 MB/sec generates an additional 150 MB/sec of data transmitted over the network for replication, and it generates a further 75 MB/sec for the consumers. The 150 MB/sec of bandwidth for replication is full duplex (where each byte sent by a broker is received by some other broker). The 75 MB/sec producer and consumer flows, however, are half-duplex, because the client endpoint in each case is outside of the cluster. Therefore, the intra-cluster bandwidth is 225 MB for incoming and outgoing flows: - 150 MB/sec of intra-cluster full duplex bandwidth - 75 MB/sec of ingress from producers - 75 MB/sec of egress to consumers Three nodes satisfy Redpanda’s minimum deployment requirement (so Raft can form quorums) and also the single node failure tolerance. Divide the bandwidth total by the node count (3) to get the per-node bandwidth requirements. The throughput is not high enough to warrant any more than two cores and a single NVMe SSD disk. Be mindful of predicted growth of CPU and disk usage, and estimate when the cluster might need to scale up or scale out. With an average producer throughput of 75 MB/sec and a replication factor of three, each node writes 254 GB of data each hour and 6.4 TB of data each day. For three days of data retention, each node needs at least 20 TB of storage. > 📝 **NOTE** > > This assumes that each node could be a leader or a follower, and there are a sufficient number of partitions for good distribution. A typical node is the leader for 1/Nth of the partitions in a cluster with N nodes and a follower for 2/Nths of the partitions. However, the per node bandwidth could vary if distribution is uneven. You may have an inexact distribution of load during Redpanda partition balancing or when the client library doesn’t write to each partition evenly. The following machine specifications provide a minimum for a bare metal cluster or its cloud-based equivalent. | | Bare Metal | AWS | GCP | Azure | | --- | --- | --- | --- | --- | | Instance Type | - | m5.large | n2-standard-2 | F2s_v2 | | Nodes | 3 | 3 | 3 | 3 | | Cores | 2 | 2 | 2 | 2 | | Memory | 4 GB | 8 GB | 8 GB | 4 GB | | Instance Storage | 20 TB (NVMe) | - | - | 16 GB (SSD) | | Persistent Storage | - | 20 TB (gb3) | 20 TB (Zonal SSD PD) | 20 TB (Standard SSD) | | Network | 4 Gbps | Up to 10 Gbps | 10 Gbps | 5 Gbps | | Tiered Storage | False | False | False | False | ## [](#medium-throughput)Medium throughput | Metric | Value | | --- | --- | | Producer throughput | ~500 MB/sec (~4,000 Mbps) | | Producer rate | 2,000 messages per second | | Consumer throughput | ~1,000 MB/sec (~8,000 Mbps) | | Consumer rate | 4,000 messages per second | | Data retention | 24 hours | | Average message size | 250 KB | | Failure tolerance | 1 node | Producing an average of 500 MB/sec and consuming an average of 1,000 MB/sec equates to 2,500 MB/sec (20 Gbps) of network bandwidth for replication traffic. This is attainable but expensive with cloud providers, and these speeds are not as prevalent within a typical data center. With at least one partition for each core, the 500 MB/sec of data from producers is evenly distributed between the nodes. For example, with three nodes, each node receives approximately 167 MB/sec. However, that bandwidth value increases with data replication. | Producer MB/sec | Consumer MB/sec | Avg. Replication Factor | Nodes | Writes per node MB/sec | Reads per node MB/sec | | --- | --- | --- | --- | --- | --- | | 500 | 1,500 | 3 | 3 | 500/3 * 3 = 500 | 1500/3 = 500 | | 500 | 1,500 | 3 | 5 | 500/5 * 3 = 300 | 1500/5 = 300 | | 500 | 1,500 | 3 | 7 | 500/7 * 3 = 215 | 1500/7 = 215 | | 500 | 1,500 | 5 | 7 | 500/7 * 5 = 358 | 1500/7 = 215 | The additional 500 MB/sec for consumer throughput is for Tiered Storage and the bandwidth required to archive log segments to object storage. When Tiered Storage is enabled on a topic, it essentially adds another consumer’s worth of bandwidth on the network. To balance the available local disk, consider exactly how many reads can be serviced from local storage. Different instance types or locally attached NVMe SSD disks provide different amounts of local storage, and therefore different amounts of available data without going back to object storage. A topic with Tiered Storage enabled can write data to faster local storage managed by local retention settings, and at the same time, it can write data to object storage managed by different retention settings, or left to grow for a longer period. Consumers that generally keep up with producers stream from local storage, but at this velocity that window of opportunity is narrower. The object store enables a consumer to read from an older offset when necessary. | | Bare Metal | AWS | GCP | Azure | | --- | --- | --- | --- | --- | | Instance Type | - | i3en.6xlarge | n2-standard-32 | F48s_v2 | | Nodes | 3 | 3 | 3 | 3 | | Cores | 24 | 24 | 32 | 48 | | Memory | 192 GB | 192 GB | 128 GB | 96 GB | | Instance Storage | 30 TB (NVMe) | 15 TB (NVM3) | 9 TB (SSD) | 384 GiB (SSD) | | Persistent Storage | - | - | - | 20 TB (Standard SSD) | | Available Local Retention | 17 hrs | 8 hrs | 5 hrs | 9 days | | Network | 25 Gbps | 25 Gbps | 32 Gbps | 21 Gbps | | Tiered Storage | True | True | True | True | ## [](#high-throughput)High throughput | Metric | Value | | --- | --- | | Producer throughput | 1,000 MB/sec (8,000 Mbps) | | Producer rate | 4,000 messages per second | | Consumer throughput | 2,000 MB/sec (16,000 Mbps) | | Consumer rate | 8,000 messages per second | | Data retention | 24 hours | | Average message size | 250 KB | | Failure tolerance | 2 nodes | This use case has many topics, hundreds of partitions, and a high throughput. The combined producer and replication data equates to 8 Gbps of network traffic, plus 16 Gbps for the consumers and 8 Gbps for Tiered Storage. In total, that’s at least 32 Gbps of network bandwidth required to sustain this level of throughput. Writing at 1,000 MB/sec is near the upper limit of what a single NVMe disk can sustain. At this scale, you get significant performance gains by distributing the writes over many cores and disks to better leverage Redpanda’s thread-per-core model. For example, given five nodes with 24 cores each, start with at least one partition for each core (120 partitions in total) and scale up. Redpanda generates over 3 TB of writes each hour and over 80 TB each day. Local storage is going to fill up quickly, and the window of opportunity for consumers to read from local storage is going to be shorter than in the other scenarios. In this use case, [Tiered Storage](../../../../manage/tiered-storage/) is essential. | | Bare Metal | AWS | GCP | Azure | | --- | --- | --- | --- | --- | | Instance Type | - | i3en.12xlarge | n2-standard-48 | F48s_v2 | | Nodes | 5 | 5 | 5 | 5 | | Cores | 24 | 48 | 48 | 48 | | Memory | 192 GB | 384 GB | 192 GB | 96 GB | | Instance Storage | 30 TB (NVMe) | 30 TB (NVM3) | 9 TB (SSD) | 384 TB (SSD) | | Persistent Storage | - | - | - | 30 TB (Ultra SSD) | | Available Local Retention | 14 hrs | 7 hrs | 4 hrs | 7 days | | Network | 25 Gbps | 25 Gbps | 32 Gbps | 21 Gbps | | Tiered Storage | True | True | True | True | ## Suggested labs - [Disaster Recovery with Envoy and Shadowing](/redpanda-labs/docker-compose/envoy-shadowing/) - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Stream Jira Issues to Redpanda for Real-Time Metrics](/redpanda-labs/docker-compose/jira-metrics-pipeline/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Set Up GitOps for the Redpanda Helm Chart](/redpanda-labs/kubernetes/gitops-helm/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) - [Set Up MySQL CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-mysql-json/) - [Set Up Postgres CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-postgres-json/) See more [Search all labs](/redpanda-labs) --- # Page 56: Sizing Guidelines **URL**: https://docs.redpanda.com/current/deploy/redpanda/manual/sizing.md --- # Sizing Guidelines --- title: Sizing Guidelines latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: redpanda/manual/sizing page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: redpanda/manual/sizing.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/deploy/pages/redpanda/manual/sizing.adoc description: Learn about considerations to size your Redpanda cluster to handle the volume of data being produced, replicated, and consumed. page-git-created-date: "2025-08-15" page-git-modified-date: "2025-08-15" support-status: supported --- For best performance, size your Redpanda cluster to handle the volume of data being produced, replicated, and consumed. The following variables affect cluster sizing: - Throughput of data (after compression, if applied) - Topic replication factor - Number of producers and consumers Throughput and retention requirements can cause bottlenecks in the system. On an undersized cluster, clients could saturate the available network bandwidth, a disk could run out of IOPS and be unable to keep up with writes, or you could simply run out of disk space. On an oversized Redpanda cluster, you could overpay for unnecessary infrastructure. For sizing estimates and advice for various throughput and retention scenarios, see [Sizing Use Cases](../sizing-use-cases/). In general, choose the number of nodes based on the following criteria, and add nodes for fault tolerance. This ensures that the system can operate with full throughput in a degraded state. - **Network bandwidth**: Total bandwidth must account for maximum simultaneous writes and reads, multiplied by the replication factor. - **Memory per core**: Allocate a minimum of 2 GB memory for each CPU core. Additional memory could improve performance. - **Memory per partition**: Allocate a minimum of 2 MB of memory for each topic partition replica. For example: If you have 10,000 total partitions with a replication factor of 3, you need at least 60 GB of memory across all brokers: 10,000 partitions × 3 replicas × 2 MB = 60,000 MB (60 GB) If these partitions are evenly distributed across three brokers, each broker needs at least 20 GB of memory. - **Storage strategy**: Use Tiered Storage to unify historical and real-time data cost-effectively. - **Performance testing**: Run hardware and Redpanda benchmark tests to establish a performance baseline. Choose instance types that prioritize storage and network performance: - **AWS**: Test with i3en (NVMe SSD), i4i (NVMe), or is4gen (Intel-based NVMe) instances, or other NVMe-backed types - **Azure**: Test with Lsv2-series instances (high I/O performance) or other high-performance storage types - **GCP**: Test with n2-standard instances with local SSD or other high-performance local storage types ## [](#sizing-considerations)Sizing considerations ### [](#network)Network To understand the network usage of a basic Redpanda cluster, consider a cluster with three nodes, a topic with a single partition and a replication factor of three, and a single producer and consumer. For every 75 MB written to the partition’s leader, 150 MB is transmitted across the network to other nodes for replication, and 75 MB is transmitted to the consumer. ![3 node Redpanda cluster](../../../../shared/_images/3-node-rp-cluster-alt.png) The 150 MB/sec of bandwidth for replication is full duplex (where each byte sent by a broker is received by some other broker). The 75 MB/sec producer and consumer flows, however, are half-duplex, because the client endpoint in each case is outside of the cluster. In a well-balanced scenario, the intra-cluster bandwidth is 225 MB for incoming and outgoing flows: - 150 MB/sec of intra-cluster full duplex bandwidth - 75 MB/sec of ingress from producers half-duplex bandwidth - 75 MB/sec of egress to consumers half-duplex bandwidth Even with the same amount of data produced, increasing the replication factor or the number of consumers increases bandwidth utilization. It’s important to measure the network bandwidth between nodes, and between clients and nodes, to make sure that you’re getting the expected performance from the network. This is especially important for cloud deployments where network bandwidth is not always guaranteed. Short tests may give unrealistically good results because of burst bandwidth, where instances can use a network I/O credit mechanism to burst for a limited time beyond their baseline bandwidth. To get realistic results, soak test the network to understand how it behaves over longer periods of time. The following example uses [iPerf3](https://iperf.fr/) to test the network bandwidth between two Debian-based servers. To do a full network stress test, run iPerf3 for every combination of network routes. ```bash redpanda1:~ sudo apt -y update; sudo apt -y install iperf3 redpanda1:~ iperf3 -s ----------------------------------------------------------- Server listening on 5201 ----------------------------------------------------------- redpanda2:~ sudo apt update; sudo apt install iperf3 redpanda2:~ iperf3 -c redpanda1 -p 5201 -t 300 Connecting to host redpanda1, port 5201 [ ID] Interval Transfer Bitrate Retr Cwnd [ 5] 0.00-1.00 sec 1.11 GBytes 9.57 Gbits/sec 0 1.64 MBytes [ 5] 1.00-2.00 sec 1.11 GBytes 9.53 Gbits/sec 0 1.64 MBytes [ 5] 2.00-3.00 sec 1.11 GBytes 9.53 Gbits/sec 0 1.64 MBytes [ 5] 3.00-4.00 sec 1.11 GBytes 9.53 Gbits/sec 0 1.72 MBytes [ 5] 4.00-5.00 sec 1.11 GBytes 9.53 Gbits/sec 0 1.72 MBytes ... ``` ### [](#cpu-and-memory)CPU and memory Redpanda is designed to scale up to utilize all available hardware and scale out to distribute performance across multiple nodes. Topic partitions are the unit of parallelization in Redpanda. Adding partitions is how you scale to meet workload demands. Redpanda implements a thread-per-core programming model through its use of the [Seastar](https://seastar.io/) library. This allows Redpanda to pin each of its application threads to a CPU core to avoid context switching and blocking, significantly improving processing performance and efficiency. Redpanda can handle approximately one GB/sec of writes for each core, depending on the workload. Since NVMe disks can have a sustained write speed of over one GB/sec, it takes two cores to saturate a single NVMe disk. A general recommendation is to have 100 MB/sec for each core. Redpanda is basically a distributed transaction log with well-understood access patterns. It appends data to the end of log files and sequentially reads data from log files. Because Redpanda understands its own access patterns better than the operating system does, Redpanda chooses to bypass the Linux page cache and manages its own memory and disk I/O. This gives Redpanda complete control over the underlying hardware to optimize I/O performance, deliver predictable tail latencies, and minimize its memory footprint. A minimum of 2 GB of memory for each core is recommended, but more is better. ### [](#storage)Storage Your best storage solution for your workload depends on your performance and data retention requirements. If high throughput and low latency is most important, then use locally attached NVMe SSD disks. This is also a good option in the cloud. Just remember that in the cloud, local disks are ephemeral, so data is wiped when an instance is restarted. An alternative in the cloud is to use SSD-backed network-attached storage to persist data between instance restarts. Most cloud providers have options for guaranteeing throughput and provisioned IOPS performance of network-attached storage, although network-attached storage almost always exhibits slightly higher tail latencies than direct-attached storage. For example, AWS io2 volumes offer up to 64,000 IOPS and 1,000 MB/sec throughput with single-digit millisecond latency. This is an expensive option, so if you can trade performance for cost, then AWS gp3 volumes are a good alternative. GCP has comparable options with high-end Extreme persistent disks and the lesser SSD persistent disks. Likewise, Azure has Ultra, Premium, and Standard persistent disk options for choosing the right balance of performance versus cost. Whichever option you choose, benchmark Redpanda’s underlying storage for read and write performance, at least from an I/O perspective. Fio is a good tool for replicating Redpanda’s sequential write pattern and load. The following example shows how to run fio on a Debian-based server: > 📝 **NOTE** > > Ensure that the fio job runs against the chosen block device. By default, fio operates in the local directory. ```bash sudo apt -y update; sudo apt -y install fio cd /var/lib/redpanda/data sudo tee fio-seq-write.job >/dev/null << EOF [global] name=fio-seq-write filename=fio-seq-write rw=write bs=16K direct=1 numjobs=4 group_reporting time_based runtime=300 # 5 minute runtime [file1] size=10G ioengine=libaio iodepth=16 EOF sudo fio fio-seq-write.job ``` Key performance metrics: - IOPS = Input and output operations per second. IOPS represents how many sequential write operations per second the volume can handle. - BW = Average bandwidth measured in MB per second. Bandwidth divided by the write block size (for example, bs=16K) is the IOPS. - slat = Submission latency. The time in microseconds to submit the I/O to the kernel. - clat = Completion latency. The time in microseconds after slat until the device has completed the I/O. - lat = Overall latency in microseconds. - clat percentiles = Completion tail latency. Pay particular attention to p90 and above. This is a good indication of whether the volume can deliver predictable, consistent performance. ### [](#data-retention)Data retention Retention properties control how long messages are kept on disk before they’re deleted or compacted. You can configure data retention until message age or aggregate message size in the topic is exceeded. Setting retention properties (at the topic level or the cluster level) is the best way to prevent old messages from accumulating on disk to the point that the disk becomes full. See also: [Configure message retention](../../../../manage/cluster-maintenance/disk-utilization/#configure-message-retention) and [Set retention limits](../../../../manage/tiered-storage/#set-retention-limits) ### [](#tiered-storage)Tiered Storage Redpanda Tiered Storage enables multi-tiered object storage. It archives log segments to object storage in near real time while maintaining the ability for brokers to fetch and serve these archived segments to slow consumers transparently and without any client configuration. With only local storage, data retention is limited to the provisioned capacity: you must provision more nodes to increase capacity. Adding nodes is expensive, because you’re forced to overprovision infrastructure regardless of whether you need the additional compute power. In most cases, overprovisioning leads to underutilization and higher operational costs. Tiered Storage can be combined with local storage to provide long-term data retention and disaster recovery on a per-topic basis. Retention properties work the same for Tiered Storage topics and local storage topics. Data is retained in the cloud until it reaches the configured time or size limit. Ideally, a cluster should be sized such that the cluster’s local storage can service the majority of its consumers within a normal amount of lag, with Tiered Storage used to service any slow readers (for example, in the event of some downstream failure). When Tiered Storage is enabled on a topic, it copies closed log segments to the configured storage bucket or container. Log segments are closed when the value of [`log_segment_size`](../../../../reference/properties/cluster-properties/#log_segment_size) has been reached, so a topic’s object store lags behind the local copy. You can set an idle timeout to force Redpanda to periodically archive the contents of open log segments to object storage. This is useful if a topic’s write rate is low and log segments are kept open for long periods of time. Adjusting how much data the object store lags behind the local copy allows Redpanda to meet stricter recovery point-in-time objectives. This is encapsulated in the Kafka API, so clients can continue to produce and consume data from Redpanda in the same way. Consumers that keep up with producers continue to read from local storage and are subject to the local data retention policy. Consumers that want to read from older offsets do so with the same consumer API, and Redpanda handles fetching the necessary log segments from object storage. See also: [Tiered Storage](../../../../manage/tiered-storage/) ### [](#production-settings)Production settings Before running performance benchmark testing, set Redpanda into production mode and run the autotuner tool ([rpk redpanda tune all](../../../../reference/rpk/rpk-redpanda/rpk-redpanda-tune/)) on every node. This enables the necessary hardware optimizations and ensures that kernel parameters are set correctly. See also: [Set Redpanda production mode](../production/production-deployment/#set-redpanda-production-mode) and [autotuner reference](../../../../reference/rpk/rpk-redpanda/rpk-redpanda-tune/) ### [](#open-messaging-benchmark)Open Messaging Benchmark Performance benchmarking a distributed system like Redpanda requires careful orchestration, instrumentation, and measurement. Every cluster destined for production should be subject to performance benchmarking for validation and confidence in the setup. The [Open Messaging Benchmark](https://github.com/redpanda-data/openmessaging-benchmark) (OMB) framework simplifies the process. OMB contains extensible tests that replicate realworld stress on a streaming platform to measure throughput and latency over given time periods. OMB can verify that a Redpanda cluster, deployed in your own data center or in the cloud, is sized appropriately for your use case. See also: [Redpanda Benchmarks](https://github.com/redpanda-data/openmessaging-benchmark/blob/main/driver-redpanda/README.md) ## [](#assess-throughput)Assess throughput This section describes how to use the [`rpk topic analyze`](../../../../reference/rpk/rpk-topic/rpk-topic-analyze/) command to check how much work your Redpanda cluster is handling. It shows the number of messages the cluster is processing and the size of the data groups (batches). This information helps you decide if you need to add more servers or make changes to your setup. This command shows you the throughput of your Redpanda cluster: ```bash rpk topic analyze --regex '*' --print-all --time-range -1m:end ``` The arguments are: - `--regex '*'`: Analyzes all topics. - `--print-all`: Prints all the metrics. - `--time-range -1m:end`: Analyzes the last minute of data. Example output: ```bash SUMMARY ======= TOPICS 6 PARTITIONS 17 TOTAL THROUGHPUT (BYTES/S) 1361.9166666666667 TOTAL BATCH RATE (BATCHES/S) 2.9833333333333334 AVERAGE BATCH SIZE (BYTES) 456.50837988826817 TOPIC SUMMARY ============= TOPIC PARTITIONS BYTES-PER-SECOND BATCHES-PER-SECOND AVERAGE-BYTES-PER-BATCH _redpanda.audit_log 12 61 0.1 610 _redpanda.transform_logs 1 890.2666666666667 0.7833333333333333 1136.5106382978724 _schemas 1 0 0 0 edu-filtered-domains 1 14.283333333333333 0.1 142.83333333333334 logins 1 144.61666666666667 1 144.61666666666667 transactions 1 251.75 1 251.75 PARTITION BATCH RATE (BATCHES/S) ================================ TOPIC P25 P50 P75 P99 _redpanda.audit_log 0.016666666666666666 0.016666666666666666 0.03333333333333333 0.03333333333333333 _redpanda.transform_logs 0.7833333333333333 0.7833333333333333 0.7833333333333333 0.7833333333333333 _schemas 0 0 0 0 edu-filtered-domains 0.1 0.1 0.1 0.1 logins 1 1 1 1 transactions 1 1 1 1 PARTITION BATCH SIZE (BYTES) ============================ TOPIC P25 P50 P75 P99 _redpanda.audit_log 608 610 610 611 _redpanda.transform_logs 895 895 895 895 _schemas 0 0 0 0 edu-filtered-domains 141 141 141 141 logins 144 144 144 144 transactions 255 255 255 255 ``` - **Total throughput:** Indicates the total amount of data processed by the cluster every second. - **Total batch rate:** Shows the number of message batches processed per second. A higher rate suggests increased activity, which may require more CPU or I/O resources. - **Average batch size:** Reflects the average size of each message batch. Large or inconsistent batch sizes may indicate the need to adjust producer settings or verify storage capacity. - **Topic and partition summaries:** Provides details on resource usage by individual topics. For example, if a single topic (such as `_redpanda.transform_logs` in the example output) is responsible for most throughput, it may need optimization or additional resources. - **Percentiles (P25, P50, P75, P99):** Offers insights into workload distribution across partitions. Consistent values suggest balanced workloads, while significant variations may highlight areas that need rebalancing or capacity adjustments. ### [](#plan-for-capacity)Plan for capacity Compare the current throughput and batch rate with your cluster’s hardware limits, such as network bandwidth, disk IOPS, or CPU capacity. If usage is nearing these limits, consider scaling up (upgrading hardware) or scaling out (adding brokers). Monitor trends over time to anticipate when expansion is necessary. ### [](#address-bottlenecks)Address bottlenecks If specific topics or partitions consistently show higher loads, it may indicate uneven workload distribution. Redistribute partitions or adjust replication factors to balance the load more effectively. ## [](#suggested-reading)Suggested reading - [Four sizing principles for Redpanda production clusters](https://redpanda.com/blog/sizing-redpanda-cluster-best-practices) - [Free guide - Architecture and sizing guidelines for your Redpanda clusters](https://go.redpanda.com/redpanda-sizing-guidelines) - [Thread-per-core buffer management for a modern Kafka-API storage system](https://redpanda.com/blog/tpc-buffers?utm_medium=content&utm_assetname=sizing_guide&utm_assettype=report&utm_source=gated_content&utm_campaign=tpc_architecture_blog) - [A guide to benchmarking the performance of Redpanda](https://redpanda.com/blog/self-hosted-redpanda-benchmarking) ## Suggested labs - [Disaster Recovery with Envoy and Shadowing](/redpanda-labs/docker-compose/envoy-shadowing/) - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Stream Jira Issues to Redpanda for Real-Time Metrics](/redpanda-labs/docker-compose/jira-metrics-pipeline/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Set Up GitOps for the Redpanda Helm Chart](/redpanda-labs/kubernetes/gitops-helm/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) - [Set Up MySQL CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-mysql-json/) - [Set Up Postgres CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-postgres-json/) See more [Search all labs](/redpanda-labs) --- # Page 57: Develop **URL**: https://docs.redpanda.com/current/develop.md --- # Develop --- title: Develop latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/develop/pages/index.adoc description: Develop doc topics. page-git-created-date: "2023-05-30" page-git-modified-date: "2023-08-21" support-status: supported --- - [Kafka Compatibility](kafka-clients/) Kafka clients, version 0.11 or later, are compatible with Redpanda. Validations and exceptions are listed. - [Benchmark Redpanda](benchmark/) Learn how to measure the performance of a Redpanda cluster deployed on AWS EC2 instances with the OpenMessaging Benchmark. - [Use Redpanda with the HTTP Proxy API](http-proxy/) HTTP Proxy exposes a REST API to list topics, produce events, and subscribe to events from topics using consumer groups. - [Topics](manage-topics/) Learn how to manage topics in Redpanda, including creation, configuration, and advanced features. - [Edit Topic Configuration in Redpanda Console](../console/ui/edit-topic-configuration/) Learn how to use Redpanda Console to edit the configuration of existing topics in a cluster. - [Produce Data](produce-data/) Learn how to configure producers and idempotent producers. - [Consume Data](consume-data/) Learn about consumer offsets and follower fetching. - [Data Transforms](data-transforms/) Learn about WebAssembly data transforms within Redpanda. - [Transactions](transactions/) Learn how to use transactions; for example, you can fetch messages starting from the last consumed offset and transactionally process them one by one, updating the last consumed offset and producing events at the same time. --- # Page 58: Benchmark Redpanda **URL**: https://docs.redpanda.com/current/develop/benchmark.md --- # Benchmark Redpanda --- title: Benchmark Redpanda latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: benchmark page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: benchmark.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/develop/pages/benchmark.adoc description: Learn how to measure the performance of a Redpanda cluster deployed on AWS EC2 instances with the OpenMessaging Benchmark. page-git-created-date: "2023-07-24" page-git-modified-date: "2024-07-25" support-status: supported --- Learn how to measure the performance of a Redpanda cluster deployed on AWS EC2 instances with the Linux Foundation’s OpenMessaging Benchmark. Run the same tests and workloads that Redpanda uses to demonstrate significantly better performance than Apache Kafka. ## [](#about-openmessaging-benchmark)About OpenMessaging Benchmark The [Linux Foundation’s OpenMessaging Benchmark](https://openmessaging.cloud/docs/benchmarks/) (OMB) Framework is an open-source, cloud-based benchmark framework that supports several messaging systems, including Kafka, and is configurable for workloads representing real-world use cases. Redpanda Data provides a [fork of OMB on Github](https://github.com/redpanda-data/openmessaging-benchmark) with some updates: - Fixed coalescing of asynchronous consumer offset requests in the OMB Kafka driver. - Support for Kafka 3.2.0 clients. ### [](#omb-workloads)OMB workloads An OMB workload is a benchmark configuration that sets the producers, consumers, topics, and messages used by a test, as well as the production rate and duration of each test. An OMB workload is specified in a YAML configuration file. Example workload configuration file The content of an OMB workload configuration file, copied from Redpanda Data’s [fork of OMB](https://github.com/redpanda-data/openmessaging-benchmark/blob/main/workloads/1-topic-1-partition-1kb.yaml): ```none name: 1 topic / 1 partition / 1Kb topics: 1 partitionsPerTopic: 1 keyDistributor: "NO_KEY" messageSize: 1024 payloadFile: "payload/payload-1Kb.data" subscriptionsPerTopic: 1 consumerPerSubscription: 1 producersPerTopic: 1 producerRate: 50000 consumerBacklogSizeGB: 0 testDurationMinutes: 15 ``` The `keyDistributor` property configures how keys are distributed and assigned to messages. - `NO_KEY` sets `null` for all keys. - `KEY_ROUND_ROBIN` cycles through a finite set of keys in round-robin fashion. - `RANDOM_NANO` returns random keys based on `System.nanoTime()`. ## [](#set-up-benchmark)Set up benchmark Running OMB with Redpanda requires setting up your local environment to provision and start a Redpanda cluster in AWS. 1. Install CLI tools. - [Maven](https://maven.apache.org/install.html) - [Terraform](https://developer.hashicorp.com/terraform/downloads) with [terraform-inventory plugin](https://github.com/adammck/terraform-inventory) - [Ansible](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html) (v2.11 or higher) - Python 3 and pip - A window manager like [tmux](https://github.com/tmux/tmux/wiki) or [screen](https://linux.die.net/man/1/screen) that supports detachable screen sessions. > 💡 **TIP** > > Redpanda Data recommends running the benchmark executable with a window manager that supports detachable screen sessions, like tmux or screen, so the benchmark can continue to run in the background even after you disconnect. 2. Clone the Redpanda Data fork of OMB. ```bash git clone https://github.com/redpanda-data/openmessaging-benchmark ``` The repository contains a directory for the Redpanda driver, `openmessaging-benchmark/driver-redpanda`. Subsequent steps read and configure files in that directory. 3. Customize the `openmessaging-benchmark/driver-redpanda/pom.xml` file with your Kafka client version if necessary (currently 3.3.1): `pom.xml` ```xml ... org.apache.kafka kafka-clients 3.3.1 ... ``` 4. From the repository root directory, build the benchmark client. ```bash cd openmessaging-benchmark mvn clean install -Dlicense.skip=true ``` 5. From the Redpanda driver directory, install the Ansible roles required for deploying Redpanda. ```bash cd driver-redpanda/deploy ansible-galaxy install -r requirements.yaml ``` 6. Configure AWS credentials and SSH keys. 1. [Install](https://aws.amazon.com/cli/) and [configure](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) AWS CLI. 2. Generate SSH keys: ```bash ssh-keygen -f ~/.ssh/redpanda_aws ``` When prompted for a passphrase, set a blank passphrase by pressing Enter twice. 3. Verify the SSH key files were created. ```bash ls ~/.ssh/redpanda_aws* ``` 7. Provision a Redpanda cluster to deploy on AWS with Terraform. 1. Customize the `openmessaging-benchmark/deploy/terraform.tfvars` Terraform configuration file for your environment. Default Terraform configuration for Redpanda on AWS The default contents of `openmessaging-benchmark/driver-redpanda/deploy/terraform.tfvars`: ```none public_key_path = "~/.ssh/redpanda_aws.pub" region = "us-west-2" az = "us-west-2a" ami = "ami-0d31d7c9fc9503726" profile = "default" instance_types = { "redpanda" = "i3en.6xlarge" "client" = "m5n.8xlarge" "prometheus" = "c5.2xlarge" } num_instances = { "client" = 4 "redpanda" = 3 "prometheus" = 1 } ``` 2. From the Redpanda driver deployment directory, initialize the Terraform deployment of Redpanda on AWS. ```bash cd driver-redpanda/deploy terraform init terraform apply -auto-approve ``` > 📝 **NOTE** > > The `terraform apply` command prompts you for an owner name (`var.owner`) that is used to tag all the cloud resources that will be created. Once the installation is complete, you will see a confirmation message listing the resources that have been installed. 8. Run the Ansible playbook to install and start the Redpanda cluster. Redpanda can run with or without TLS and SASL enabled. - To run Redpanda **without TLS and SASL**: ```bash ansible-playbook deploy.yaml ``` - To run Redpanda **with TLS and SASL**: ```bash ansible-playbook deploy.yaml -e "tls_enabled=true sasl_enabled=true" ``` If the path to your SSH private key isn’t `~/.ssh/redpanda_aws`, add the `--private-key` flag to your Ansible command. ```bash ansible-playbook deploy.yaml --private-key= ``` > 📝 **NOTE** > > Beginning with Ansible 2.14, references to `args: warn` within Ansible tasks cause a fatal error and halt the execution of the playbook. You may find instances of this in the components installed by `ansible-galaxy`, particularly in the `cloudalchemy.grafana` task in `dashboards.yml`. To resolve this issue, removing the `warn` line in from the yml file. ## [](#run-benchmark)Run benchmark Connect to the benchmark’s client and run the benchmark with a custom workload. 1. Connect with SSH to the benchmark client, with its IP address retrieved from the `client_ssh_host` output of Terraform. ```bash ssh -i ~/.ssh/redpanda_aws ubuntu@$(terraform output --raw client_ssh_host) ``` 2. On the client, navigate to the `/opt/benchmark` directory. ```bash cd /opt/benchmark ``` 3. Create a workload configuration file. For example, create a `.yaml` file with one topic, 144 partitions, 500 MBps producer rate, four producers, and four consumers: ```bash cat > workloads/1-topic-144-partitions-500mb-4p-4c.yaml << EOF name: 500mb/sec rate; 4 producers 4 consumers; 1 topic with 144 partitions topics: 1 partitionsPerTopic: 144 messageSize: 1024 useRandomizedPayloads: true randomBytesRatio: 0.5 randomizedPayloadPoolSize: 1000 subscriptionsPerTopic: 1 consumerPerSubscription: 4 producersPerTopic: 4 producerRate: 500000 consumerBacklogSizeGB: 0 testDurationMinutes: 30 EOF ``` Alternatively, you can use an existing workload file from the Redpanda repo, in `openmessaging-benchmark/driver-redpanda/deploy/workloads/`. Workloads from Redpanda vs. Kafka comparison The workloads from the [Redpanda vs. Kafka benchmark comparison](https://redpanda.com/blog/redpanda-vs-kafka-performance-benchmark) can be gotten from the chart in the comparison: ![kafka vs redpanda performance 8](https://images.ctfassets.net/paqvtpyf8rwu/2lpkGM01nrl0s87xSBISno/6c25504b1f6e7c8015ef193433bd077e/kafka_vs_redpanda_performance_8.png) 4. Create or reuse a client configuration file. This file configures the Redpanda producer and consumer clients, as well as topics. The rest of the guide uses the `openmessaging-benchmark/driver-redpanda/redpanda-ack-all-group-linger-1ms.yaml` configuration file. Client configuration from Redpanda vs. Kafka comparison The client configuration from the [Redpanda vs. Kafka benchmark comparison](https://redpanda.com/blog/redpanda-vs-kafka-performance-benchmark) can be gotten from the code listing in the comparison: ```yaml topicConfig: | min.insync.replicas=2 flush.messages=1 flush.ms=0 producerConfig: | acks=all linger.ms=1 batch.size=131072 consumerConfig: | auto.offset.reset=earliest enable.auto.commit=false auto.commit.interval.ms=0 max.partition.fetch.bytes=131072 ``` > 💡 **TIP** > > Configure `reset=false` and manually delete the generated topic after the benchmark completes. Otherwise, when `reset=true`, the benchmark can fail due to it erroneously trying to delete the `_schemas` topic. 5. Run the benchmark with your workload and client configuration. ```bash sudo bin/benchmark -d \ driver-redpanda/redpanda-ack-all-group-linger-1ms.yaml \ workloads/1-topic-144-partitions-500mb-4p-4c.yaml ``` ## [](#view-benchmark-results)View benchmark results After a run completes, the benchmark generates results as `*.json` files in `/opt/benchmark`. Redpanda provides a Python script, `generate_charts.py`, to generate charts of benchmark results. To run the script: 1. Copy the results from the client to your local machine. ```bash exit; # back to your local machine mkdir ~/results scp -i ~/.ssh/redpanda_aws ubuntu@$(terraform output --raw client_ssh_host):/opt/benchmark/*.json ~/results/ ``` 2. From the root directory of the repository, install the prerequisite packages for the Python script. ```bash cd ../../bin # openmessaging-benchmark/bin python3 -m pip -r install requirements.txt ``` 3. To list all options, run the script with the `-h` flag. ```bash ./generate_charts.py -h ``` 4. To generate charts from your `~/results/` directory, first create an `~/output` directory, then run the script with `--results` and `--output` options set accordingly. ```bash mkdir ~/output ./generate_charts.py --results ~/results --output ~/output ``` 5. In `~/output`, verify the generated charts are in an HTML page with charts for throughput, publish latency, end-to-end latency, publish rate, and consume rate. ## [](#tear-down-benchmark)Tear down benchmark When done running the benchmark, tear down the Redpanda cluster. ```bash terraform destroy -auto-approve ``` ## [](#suggested-reading)Suggested reading - [Redpanda vs. Apache Kafka: A performance comparison (2022 update)](https://redpanda.com/blog/redpanda-vs-kafka-performance-benchmark) - [Performance update: Redpanda vs. Kafka with KRaft](https://redpanda.com/blog/kafka-kraft-vs-redpanda-performance-2023) - [Why `fsync()`: Losing unsynced data on a single node leads to global data loss](https://redpanda.com/blog/why-fsync-is-needed-for-data-safety-in-kafka-or-non-byzantine-protocols) --- # Page 59: Consume Data **URL**: https://docs.redpanda.com/current/develop/consume-data.md --- # Consume Data --- title: Consume Data latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: consume-data/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: consume-data/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/develop/pages/consume-data/index.adoc description: Learn about consumer offsets and follower fetching. page-git-created-date: "2023-05-30" page-git-modified-date: "2024-02-26" support-status: supported --- - [Consumer Offsets](consumer-offsets/) Redpanda uses an internal topic, `__consumer_offsets`, to store committed offsets from each Kafka consumer that is attached to Redpanda. - [Follower Fetching](follower-fetching/) Learn about follower fetching and how to configure a Redpanda consumer to fetch records from the closest replica. - [Filter Messages with JavaScript in Redpanda Console](../../console/ui/programmable-push-filters/) Learn how to filter Kafka records using custom JavaScript code within Redpanda Console. - [View Deserialized Messages in Redpanda Console](../../console/ui/record-deserialization/) Learn how Redpanda Console deserializes messages. --- # Page 60: Consumer Offsets **URL**: https://docs.redpanda.com/current/develop/consume-data/consumer-offsets.md --- # Consumer Offsets --- title: Consumer Offsets latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: consume-data/consumer-offsets page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: consume-data/consumer-offsets.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/develop/pages/consume-data/consumer-offsets.adoc description: Redpanda uses an internal topic, __consumer_offsets, to store committed offsets from each Kafka consumer that is attached to Redpanda. page-git-created-date: "2023-05-30" page-git-modified-date: "2025-05-07" support-status: supported --- In Redpanda, all messages are organized by [topic](https://docs.redpanda.com/current/reference/glossary/#topic) and distributed across multiple partitions, based on a [partition strategy](https://www.redpanda.com/guides/kafka-tutorial-kafka-partition-strategy). For example, when using the round robin strategy, a producer writing to a topic with five partitions would distribute approximately 20% of the messages to each [partition](https://docs.redpanda.com/current/reference/glossary/#partition). Within a partition, each message (once accepted and acknowledged by the partition leader) is permanently assigned a unique sequence number called an [offset](https://docs.redpanda.com/current/reference/glossary/#offset). Offsets enable consumers to resume processing from a specific point, such as after an application outage. If an outage prevents your application from receiving events, you can use the consumer offset to retrieve only the events that occurred during the downtime. By default, the first message in a partition is assigned offset 0, the next is offset 1, and so on. You can manually specify a specific start value for offsets if needed. Once assigned, offsets are immutable, ensuring that the order of messages within a partition is preserved. ## [](#how-consumers-use-offsets)How consumers use offsets As a consumer reads messages from Redpanda, it can save its progress by “committing the offset” (known as an [offset commit](https://docs.redpanda.com/current/reference/glossary/#offset-commit)), an action initiated by the consumer, not Redpanda. Kafka client libraries provide an API for committing offsets, which communicates with Redpanda using the [consumer group](https://docs.redpanda.com/current/reference/glossary/#consumer-group) API. Each committed offset is stored as a message in the `__consumer_offsets` topic, which is a private Redpanda topic that stores committed offsets from each Kafka consumer attached to Redpanda, allowing the consumer to resume processing from the last committed point. Redpanda exposes the `__consumer_offsets` key to enable the many tools in the Kafka ecosystem that rely on this value for their operation, providing greater ecosystem interoperability with environments and applications. When a consumer group works together to consume data from topics, the partitions are divided among the consumers in the group. For example, if a topic has 12 partitions, and there are two consumers, each consumer would be assigned six partitions to consume. If a new consumer starts later and joins this consumer group, a rebalance occurs, such that each consumer ends up with four partitions to consume. You specify a consumer group by setting the `group.id` property to a unique name for the group. Kafka tracks the maximum offset it has consumed in each partition and can commit offsets to ensure it can resume processing from the same point in the event of a restart. Kafka allows offsets for a consumer group to be stored on a designated broker, known as the group coordinator. All consumers in the group send their offset commits and fetch requests to this group coordinator. > 📝 **NOTE** > > More advanced consumers can read data from Redpanda without using a consumer group by requesting to read a specific topic, partition, and offset range. This pattern is often used by stream processing systems such as Apache Spark and Apache Flink, which have their own mechanisms for assigning work to consumers. When the group coordinator receives an OffsetCommitRequest, it appends the request to the [compacted](https://kafka.apache.org/documentation/#compaction) Kafka topic `__consumer_offsets`. The broker sends a successful offset commit response to the consumer only after all the replicas of the offsets topic receive the offsets. If the offsets fail to replicate within a configurable timeout, the offset commit fails and the consumer may retry the commit after backing off. The brokers periodically compact the `__consumer_offsets` topic, because it only needs to maintain the most recent offset commit for each partition. The coordinator also caches the offsets in an in-memory table to serve offset fetches quickly. ## [](#commit-strategies)Commit strategies There are several strategies for managing offset commits: ### [](#automatic-offset-commit)Automatic offset commit Auto commit is the default commit strategy, where the client automatically commits offsets at regular intervals. This is set with the `enable.auto.commit` property. The client then commits offsets every `auto.commit.interval.ms` milliseconds. The primary advantage of the auto commit approach is its simplicity. After it is configured, the consumer requires no additional effort. Commits are managed in the background. However, the consumer is unaware of what was committed or when. As a result, after an application restart, some messages may be reprocessed (since consumption resumes from the last committed offset, which may include already-processed messages). The strategy guarantees at-least-once delivery. > 📝 **NOTE** > > If your consume configuration is set up to consume and write to another data store, and the write to that datastore fails, the consumer might not recover when it is auto-committed. It may not only duplicate messages, but could also drop messages intended to be in another datastore. Make sure you understand the trade-off possibilities associated with this default behavior. ### [](#manual-offset-commit)Manual offset commit The manual offset commit strategy gives consumers greater control over when commits occur. This approach is typically used when a consumer needs to align commits with an external system, such as database transactions in an RDBMS. The main advantage of manual commits is that they allow you to decide exactly when a record is considered consumed. You can use two API calls for this: `commitSync` and `commitAsync`, which differ in their blocking behavior. #### [](#synchronous-commit)Synchronous commit The advantage of synchronous commits is that consumers can take appropriate action before continuing to consume messages, albeit at the expense of increased latency (while waiting for the commit to return). The commit (`commitSync`) will also retry automatically, until it either succeeds or receives an unrecoverable error. The following example shows a synchronous commit: ```java consumer.subscribe(Arrays.asList("foo", "bar")); while (true) { ConsumerRecords records = consumer.poll(100); for (ConsumerRecord record : records) { // process records here ... // ... and at the appropriate point, call commit (not after every message) consumer.commitSync(); } } ``` #### [](#asynchronous-commit)Asynchronous commit The advantage of asynchronous commits is lower latency, because the consumer does not pause to wait for the commit response. However, there is no automatic retry of the commit (`commitAsync`) if it fails. There is also increased coding complexity (due to the asynchronous callbacks). The following example shows an asynchronous commit in which the consumer will not block. Instead, the commit call registers a callback, which is executed once the commit returns: ```java void callback() { // executed when the commit returns } consumer.subscribe(Arrays.asList("foo", "bar")); while (true) { ConsumerRecords records = consumer.poll(100); for (ConsumerRecord record : records) { // process records here ... // ... and at the appropriate point, call commit consumer.commitAsync(callback); } } ``` ### [](#external-offset-management)External offset management The external offset management strategy allows consumers to manage offsets independently of Redpanda. In this approach: - Consumers bypass the consumer group API and directly assign partitions instead of subscribing to a topic. - Offsets are not committed to Redpanda, but are instead stored in an external storage system. To implement an external offset management strategy: 1. Set `enable.auto.commit` to `false`. 2. Use `assign(Collection)` to assign partitions. 3. Use the offset provided with each ConsumerRecord to save your position. 4. Upon restart, use `seek(TopicPartition, long)` to restore the position of the consumer. ### [](#hybrid-offset-management)Hybrid offset management The hybrid offset management strategy allows consumers to handle their own consumer rebalancing while still leveraging Redpanda’s offset commit functionality. In this approach: - Consumers bypass the consumer group API and directly assign partitions instead of subscribing to a topic. - Offsets are committed to Redpanda. ## [](#offset-commit-best-practices)Offset commit best practices Follow these best practices to optimize offset commits. ### [](#avoid-over-committing)Avoid over-committing The purpose of a commit is to save consumer progress. More frequent commits reduce the amount of data to re-read after an application restart, as the commit interval directly affects the recovery point objective (RPO). Because a lower RPO is desirable, application designers may believe that committing frequently is a good design choice. However, committing too frequently can result in adverse consequences. While individually small, each commit still results in a message being written to the `__consumer_offsets` topic, because the position of the consumer against every partition must be recorded. At high commit rates, this workload can become a bottleneck for both the client and the server. Additionally, many Kafka client implementations do not coalesce offset commits, meaning redundant commits in a backlog still need to be processed. In many Kafka client implementations, offset commits aren’t coalesced at the client; so if a backlog of commits forms (when using the asynchronous commit API), the earlier commits still need to be processed, even though they are effectively redundant. **Best practice**: Monitor commit latency to ensure commits are timely. If you notice performance issues, commit less frequently. ### [](#use-unique-consumer-groups)Use unique consumer groups Like many topics, the consumer group topic has multiple partitions to help with performance. When writing commit messages, Redpanda groups all of the commits for a consumer group into a specific partition to maintain ordering. Reusing a consumer group across multiple applications, even for different topics, forces all commits to use a single partition, negating the benefits of partitioning. **Best practice**: Assign a unique consumer group to each application to distribute the commit load across all partitions. ### [](#tune-the-consumer-group)Tune the consumer group In highly parallel applications, frequent consumer group heartbeats can create unnecessary overhead. For example, 3,200 consumers checking every 500 milliseconds generate 6,400 heartbeats per second. You can optimize this behavior by increasing the `heartbeat.interval.ms` (along with `session.timeout.ms`). **Best practice**: Adjust heartbeat and session timeout settings to reduce unnecessary overhead in large-scale applications. ## Suggested labs - [Stream Stock Market Data from a CSV file Using Node.js](/redpanda-labs/clients/stock-market-activity-nodejs/) - [Stream Stock Market Data from a CSV file Using Python](/redpanda-labs/clients/stock-market-activity-python/) - [Build a Chat Room Application with Redpanda and Java](/redpanda-labs/clients/docker-java/) - [Build a Chat Room Application with Redpanda and Golang](/redpanda-labs/clients/docker-go/) - [Build a Chat Room Application with Redpanda and Node.js](/redpanda-labs/clients/docker-nodejs/) - [Build a Chat Room Application with Redpanda and Python](/redpanda-labs/clients/docker-python/) - [Build a Chat Room Application with Redpanda and Rust](/redpanda-labs/clients/docker-rust/) See more [Search all labs](/redpanda-labs) --- # Page 61: Follower Fetching **URL**: https://docs.redpanda.com/current/develop/consume-data/follower-fetching.md --- # Follower Fetching --- title: Follower Fetching latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: consume-data/follower-fetching page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: consume-data/follower-fetching.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/develop/pages/consume-data/follower-fetching.adoc description: Learn about follower fetching and how to configure a Redpanda consumer to fetch records from the closest replica. page-git-created-date: "2023-08-03" page-git-modified-date: "2025-05-07" support-status: supported --- Learn about follower fetching and how to configure a Redpanda consumer to fetch records from the closest replica. ## [](#about-follower-fetching)About follower fetching **Follower fetching** enables a consumer to fetch records from the closest replica of a topic partition, regardless of whether it’s a leader or a follower. For a Redpanda cluster deployed across different data centers and availability zones (AZs), restricting a consumer to fetch only from the leader of a partition can incur greater costs and have higher latency than fetching from a follower that is geographically closer to the consumer. With follower fetching (proposed in [KIP-392](https://cwiki.apache.org/confluence/display/KAFKA/KIP-392%3A+Allow+consumers+to+fetch+from+closest+replica)), the fetch protocol is extended to support a consumer fetching from any replica. This includes [Remote Read Replicas](../../../manage/remote-read-replicas/). The first fetch from a consumer is processed by a Redpanda leader broker. The leader checks for a replica (itself or a follower) that has a rack ID that matches the consumer’s rack ID. If a replica with a matching rack ID is found, the fetch request returns records from that replica. Otherwise, the fetch is handled by the leader. ## [](#configure-follower-fetching)Configure follower fetching Redpanda decides which replica a consumer fetches from. If the consumer configures its `client.rack` property, Redpanda by default selects a replica from the same rack as the consumer, if available. To enable follower fetching in Redpanda, configure properties for the consumer and the Redpanda cluster and broker: - For a Redpanda cluster, set the [`enable_rack_awareness`](../../../reference/properties/cluster-properties/#enable_rack_awareness) property to `true`. - For each Redpanda broker, set the [`rack`](../../../reference/properties/broker-properties/#rack) property to a rack ID. - For each consumer, set the `client.rack` property to a rack ID. ## [](#suggested-videos)Suggested videos - [YouTube - Redpanda Office Hour: Follower Fetching (52 mins)](https://www.youtube.com/watch?v=wV6gH5_yVaw&ab_channel=RedpandaData) ## Suggested labs - [Stream Stock Market Data from a CSV file Using Node.js](/redpanda-labs/clients/stock-market-activity-nodejs/) - [Stream Stock Market Data from a CSV file Using Python](/redpanda-labs/clients/stock-market-activity-python/) - [Build a Chat Room Application with Redpanda and Java](/redpanda-labs/clients/docker-java/) - [Build a Chat Room Application with Redpanda and Golang](/redpanda-labs/clients/docker-go/) - [Build a Chat Room Application with Redpanda and Node.js](/redpanda-labs/clients/docker-nodejs/) - [Build a Chat Room Application with Redpanda and Python](/redpanda-labs/clients/docker-python/) - [Build a Chat Room Application with Redpanda and Rust](/redpanda-labs/clients/docker-rust/) See more [Search all labs](/redpanda-labs) --- # Page 62: Data Transforms **URL**: https://docs.redpanda.com/current/develop/data-transforms.md --- # Data Transforms --- title: Data Transforms latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: data-transforms/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: data-transforms/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/develop/pages/data-transforms/index.adoc description: Learn about WebAssembly data transforms within Redpanda. page-git-created-date: "2023-12-22" page-git-modified-date: "2024-04-30" support-status: supported --- - [How Data Transforms Work](how-transforms-work/) Learn how Redpanda data transforms work. - [Data Transforms Quickstarts](run-transforms-index/) Choose your deployment environment to get started with building and deploying your first transform function in Redpanda. - [Develop Data Transforms](build/) Learn how to initialize a data transforms project and write transform functions in your chosen language. - [Configure Data Transforms](configure/) Learn how to configure data transforms in Redpanda, including editing the `transform.yaml` file, environment variables, and memory settings. This topic covers both the configuration of transform functions and the WebAssembly (Wasm) engine's environment. - [Deploy Data Transforms](deploy/) Learn how to build, deploy, share, and troubleshoot data transforms in Redpanda. - [Write Integration Tests for Transform Functions](test/) Learn how to write integration tests for data transform functions in Redpanda, including setting up unit tests and using testcontainers for integration tests. - [Monitor Data Transforms](monitor/) This topic provides guidelines on how to monitor the health of your data transforms and view logs. - [Manage Data Transforms in Redpanda Console](../../console/ui/data-transforms/) Use Redpanda Console to monitor the status and performance metrics of your transform functions. You can also view detailed logs and delete transform functions when they are no longer needed. - [Upgrade the Data Transforms SDK](upgrade/) Upgrading the SDK version in your data transforms project ensures compatibility with the latest features and fixes. This guide provides step-by-step instructions to upgrade the SDK version for all supported SDK languages. - [Versioning and Compatibility for Data Transforms](versioning-compatibility/) The data transforms SDKs use semantic versioning to ensure compatibility and stability. Use this guide to learn the SDKs that are compatible with different versions of Redpanda, and what guarantees are provided regarding SDK and Redpanda compatibility. - [Prebuilt Data Transforms](labs/) Explore labs that include examples of transform functions and instructions on how to deploy and run them. --- # Page 63: Develop Data Transforms **URL**: https://docs.redpanda.com/current/develop/data-transforms/build.md --- # Develop Data Transforms --- title: Develop Data Transforms latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: data-transforms/build page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: data-transforms/build.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/develop/pages/data-transforms/build.adoc description: Learn how to initialize a data transforms project and write transform functions in your chosen language. page-topic-type: how-to personas: streaming_developer, application_developer learning-objective-1: Initialize a data transforms project using the rpk CLI learning-objective-2: Build transform functions that process records and write to output topics learning-objective-3: Implement multi-topic routing patterns with Schema Registry integration page-git-created-date: "2024-07-31" page-git-modified-date: "2026-03-12" support-status: supported --- Learn how to initialize a data transforms project and write transform functions in your chosen language. After reading this page, you will be able to: - Initialize a data transforms project using the rpk CLI - Build transform functions that process records and write to output topics - Implement multi-topic routing patterns with Schema Registry integration ## [](#prerequisites)Prerequisites You must have the following development tools installed on your host machine: - The [`rpk` command-line client](../../../get-started/rpk-install/) installed on your host machine and configured to connect to your Redpanda cluster. - For Golang projects, you must have at least version 1.20 of [Go](https://go.dev/doc/install). - For Rust projects, you must have the latest stable version of [Rust](https://rustup.rs/). - For JavaScript and TypeScript projects, you must have the [latest long-term-support release of Node.js](https://nodejs.org/en/download/package-manager). ## [](#init)Initialize a data transforms project To initialize a data transforms project, use the following command to set up the project files in your current directory. This command adds the latest version of the [SDK](../../../reference/data-transforms/sdks/) as a project dependency: ```bash rpk transform init --language= --name= ``` If you do not include the `--language` flag, the command prompts you for the language. Supported languages include: - `tinygo-no-goroutines` (does not include [Goroutines](https://golangdocs.com/goroutines-in-golang)) - `tinygo-with-goroutines` - `rust` - `javascript` - `typescript` For example, if you choose `tinygo-no-goroutines`, `rpk` creates the following project files: . ├── go.mod ├── go.sum ├── README.md ├── transform.go └── transform.yaml The `transform.go` file contains a boilerplate transform function. The `transform.yaml` file specifies the configuration settings for the transform function. See also: [Configure Data Transforms](../configure/) ## [](#build-transform-functions)Build transform functions You can develop your transform logic with one of the available SDKs that allow your transform code to interact with a Redpanda cluster. #### Go All transform functions must register a callback with the `OnRecordWritten()` method. You should run any initialization steps in the `main()` function because it’s only run once when the transform function is first deployed. You can also use the standard predefined [`init()` function](https://go.dev/doc/effective_go#init). ```go package main import ( "github.com/redpanda-data/redpanda/src/transform-sdk/go/transform" ) func main() { // Register your transform function. // This is a good place to perform other setup too. transform.OnRecordWritten(myTransform) } // myTransform is where you read the record that was written, and then you can // output new records that will be written to the destination topic func myTransform(event transform.WriteEvent, writer transform.RecordWriter) error { return writer.Write(event.Record()) } ``` #### Rust All transform functions must register a callback with the `on_record_written()` method. You should run any initialization steps in the `main()` function because it’s only run once when the transform function is first deployed. ```rust use redpanda_transform_sdk::*; fn main() { // Register your transform function. // This is a good place to perform other setup too. on_record_written(my_transform); } // my_transform is where you read the record that was written, and then you can // return new records that will be written to the output topic fn my_transform(event: WriteEvent, writer: &mut RecordWriter) -> Result<(), Box> { writer.write(event.record)?; Ok(()) } ``` #### JavaScript All transform functions must register a callback with the `onRecordWritten()` method. You should run any initialization steps outside of the callback so that they are only run once when the transform function is first deployed. ```js // src/index.js import { onRecordWritten } from "@redpanda-data/transform-sdk"; // This is a good place to perform setup steps. // Register your transform function. onRecordWritten((event, writer) => { // This is where you read the record that was written, and then you can // output new records that will be written to the destination topic writer.write(event.record); }); ``` If you need to use Node.js standard modules in your transform function, you must configure the [`polyfillNode` plugin](https://github.com/cyco130/esbuild-plugin-polyfill-node) for [esbuild](https://esbuild.github.io/). This plugin allows you to polyfill Node.js APIs that are not natively available in the Redpanda JavaScript runtime environment. `esbuild.js` ```js import * as esbuild from 'esbuild'; import { polyfillNode } from 'esbuild-plugin-polyfill-node'; await esbuild.build({ plugins: [ polyfillNode({ globals: { buffer: true, // Allow a global Buffer variable if referenced. process: false, // Don't inject the process global, the Redpanda JavaScript runtime does that. }, polyfills: { crypto: true, // Enable crypto polyfill // Add other polyfills as needed }, }), ], }); ``` ### [](#errors)Error handling By distinguishing between recoverable and critical errors, you can ensure that your transform functions are both resilient and robust. Handling recoverable errors internally helps maintain continuous operation, while allowing critical errors to escape ensures that the system can address severe issues effectively. Redpanda tracks the offsets of records that transform functions have processed. If an error escapes the Wasm virtual machine (VM), the VM will fail. When the Wasm engine detects this failure and starts a new VM, the transform function retries processing the input topics from the last processed offset, potentially leading to repeated failures if the underlying issue is not resolved. Handling errors internally by logging them and continuing to process subsequent records can help maintain continuous operation. However, this approach can result in silently discarding problematic records, which may lead to unnoticed data loss if the logs are not monitored closely. #### Go ```go package main import ( "log" "github.com/redpanda-data/redpanda/src/transform-sdk/go/transform" ) func main() { transform.OnRecordWritten(myTransform) } func myTransform(event transform.WriteEvent, writer transform.RecordWriter) error { record := event.Record() if record.Key == nil { // Handle the error internally by logging it log.Println("Error: Record key is nil") // Skip this record and continue to process other records return nil } // Allow errors with writes to escape return writer.Write(record) } ``` #### Rust ```rust use redpanda_transform_sdk::*; use log::error; fn main() { // Set up logging env_logger::init(); on_record_written(my_transform); } fn my_transform(event: WriteEvent, writer: &mut RecordWriter) -> anyhow::Result<()> { let record = event.record; if record.key().is_none() { // Handle the error internally by logging it error!("Error: Record key is nil"); // Skip this record and continue to process other records return Ok(()); } // Allow errors with writes to escape return writer.write(record) } ``` #### JavaScript ```js import { onRecordWritten } from "@redpanda-data/transform-sdk"; // Register your transform function. onRecordWritten((event, writer) => { const record = event.record; if (!record.key) { // Handle the error internally by logging it console.error("Error: Record key is nil"); // Skip this record and continue to process other records return; } // Allow errors with writes to escape writer.write(record); }); ``` When you deploy this transform function, and produce a message without a key, you’ll get the following in the logs: ```js { "body": { "stringValue": "2024/06/20 08:17:33 Error: Record key is nil\n" }, "timeUnixNano": 1718871455235337000, "severityNumber": 13, "attributes": [ { "key": "transform_name", "value": { "stringValue": "test" } }, { "key": "node", "value": { "intValue": 0 } } ] } ``` You can view logs for transform functions using the `rpk transform logs ` command. To ensure that you are notified of any errors or issues in your data transforms, Redpanda provides metrics that you can use to monitor the state of your data transforms. See also: - [View logs for transform functions](../monitor/#logs) - [Monitor data transforms](../monitor/) - [Configure transform logging](../configure/#log) - [`rpk transform logs` reference](../../../reference/rpk/rpk-transform/rpk-transform-logs/) ### [](#avoid-state-management)Avoid state management Relying on in-memory state across transform invocations can lead to inconsistencies and unpredictable behavior. Data transforms operate with at-least-once semantics, meaning a transform function might be executed more than once for a given record. Redpanda may also restart a transform function at any point, which causes its state to be lost. ### [](#env-vars)Access environment variables You can access both [built-in and custom environment variables](../configure/#environment-variables) in your transform function. In this example, environment variables are checked once during initialization: #### Go ```go package main import ( "fmt" "os" "github.com/redpanda-data/redpanda/src/transform-sdk/go/transform" ) func main() { // Check environment variables before registering the transform function. outputTopic1, ok := os.LookupEnv("REDPANDA_OUTPUT_TOPIC_1") if ok { fmt.Printf("Output topic 1: %s\n", outputTopic1) } else { fmt.Println("Only one output topic is set") } // Register your transform function. transform.OnRecordWritten(myTransform) } func myTransform(event transform.WriteEvent, writer transform.RecordWriter) error { return writer.Write(event.Record()) } ``` #### Rust ```rust use redpanda_transform_sdk::*; use std::env; use log::error; fn main() { // Set up logging env_logger::init(); // Check environment variables before registering the transform function. match env::var("REDPANDA_OUTPUT_TOPIC_1") { Ok(output_topic_1) => println!("Output topic 1: {}", output_topic_1), Err(_) => println!("Only one output topic is set"), } // Register your transform function. on_record_written(my_transform); } fn my_transform(_event: WriteEvent, _writer: &mut RecordWriter) -> anyhow::Result<()> { Ok(()) } ``` #### JavaScript ```js import { onRecordWritten } from "@redpanda-data/transform-sdk"; // Check environment variables before registering the transform function. const outputTopic1 = process.env.REDPANDA_OUTPUT_TOPIC_1; if (outputTopic1) { console.log(`Output topic 1: ${outputTopic1}`); } else { console.log("Only one output topic is set"); } // Register your transform function. onRecordWritten((event, writer) => { return writer.write(event.record); }); ``` ### [](#write-to-specific-output-topics)Write to specific output topics You can configure your transform function to write records to specific output topics based on message content, enabling powerful routing and fan-out patterns. This capability is useful for: - Filtering messages by criteria and routing to different topics - Fan-out patterns that distribute data from one input topic to multiple output topics - Event routing based on message type or schema - Data distribution for downstream consumers Wasm transforms provide a simpler alternative to external connectors like Kafka Connect for in-broker data routing, with lower latency and no additional infrastructure to manage. #### [](#basic-json-validation-example)Basic JSON validation example The following example shows a filter that outputs only valid JSON from the input topic into the output topic. The transform writes invalid JSON to a different output topic. ##### Go ```go import ( "encoding/json" "github.com/redpanda-data/redpanda/src/transform-sdk/go/transform" ) func main() { transform.OnRecordWritten(filterValidJson) } func filterValidJson(event transform.WriteEvent, writer transform.RecordWriter) error { if json.Valid(event.Record().Value) { return writer.Write(event.Record()) } // Send invalid records to separate topic return writer.Write(event.Record(), transform.ToTopic("invalid-json")) } ``` ##### Rust ```rust use anyhow::Result; use redpanda_transform_sdk::*; fn main() { on_record_written(filter_valid_json); } fn filter_valid_json(event: WriteEvent, writer: &mut RecordWriter) -> Result<()> { let value = event.record.value().unwrap_or_default(); if serde_json::from_slice::(value).is_ok() { writer.write(event.record)?; } else { // Send invalid records to separate topic writer.write_with_options(event.record, WriteOptions::to_topic("invalid-json"))?; } Ok(()) } ``` ##### JavaScript The JavaScript SDK does not support writing records to a specific output topic. #### [](#multi-topic-fanout)Multi-topic fan-out with Schema Registry This example shows how to route batched updates from a single input topic to multiple output topics based on a routing field in each message. Messages are encoded with the [Schema Registry wire format](../../../manage/schema-reg/schema-reg-overview/#wire-format) for validation against the output topic schema. Consider using this pattern with Iceberg-enabled topics to fan out data directly into lakehouse tables. Input message example ```json { "updates": [ {"table": "orders", "data": {"order_id": "123", "amount": 99.99}}, {"table": "inventory", "data": {"product_id": "P456", "quantity": 50}}, {"table": "customers", "data": {"customer_id": "C789", "name": "Jane"}} ] } ``` [Configure the transform](../configure/) with multiple output topics: ```yaml name: event-router input_topic: events output_topics: - orders - inventory - customers ``` The transform extracts each update and routes it to the appropriate topic based on the `table` field. Schemas are registered dynamically in the `main()` function using the Schema Registry client, which returns the schema IDs needed for encoding messages in the wire format. > 📝 **NOTE** > > In this example, it is assumed that you have created the output topics and have the schema definitions ready. The transform registers the schemas dynamically on startup using the `{topic-name}-value` naming convention for schema subjects (for example, `orders-value`, `inventory-value`). ##### Go `go.mod` ```go module fanout-example go 1.20 require github.com/redpanda-data/redpanda/src/transform-sdk/go/transform v1.1.0 // v1.1.0+ required ``` `transform.go`: ```go package main import ( "encoding/binary" "encoding/json" "log" "github.com/redpanda-data/redpanda/src/transform-sdk/go/transform" "github.com/redpanda-data/redpanda/src/transform-sdk/go/transform/sr" ) // Input message structure with array of updates type BatchMessage struct { Updates []TableUpdate `json:"updates"` } // Individual table update with routing field type TableUpdate struct { Table string `json:"table"` // Routing field - determines output topic Data json.RawMessage `json:"data"` // The actual data to write } // Schema IDs for each output topic, registered dynamically at startup var schemaIDs = make(map[string]int) func main() { // Create Schema Registry client client := sr.NewClient() // Define schemas for each output topic schemas := map[string]string{ "orders": `{"type":"record","name":"Order","fields":[{"name":"order_id","type":"string"},{"name":"amount","type":"double"}]}`, "inventory": `{"type":"record","name":"Inventory","fields":[{"name":"product_id","type":"string"},{"name":"quantity","type":"int"}]}`, "customers": `{"type":"record","name":"Customer","fields":[{"name":"customer_id","type":"string"},{"name":"name","type":"string"}]}`, } // Register schemas and store their IDs for topic, schemaStr := range schemas { subject := topic + "-value" schema := sr.Schema{ Schema: schemaStr, Type: sr.TypeAvro, } result, err := client.CreateSchema(subject, schema) if err != nil { log.Fatalf("Failed to register schema for %s: %v", topic, err) } schemaIDs[topic] = result.ID log.Printf("Registered schema for %s with ID %d", topic, result.ID) } log.Printf("Starting fanout transform with schema IDs: %v", schemaIDs) transform.OnRecordWritten(routeUpdates) } func routeUpdates(event transform.WriteEvent, writer transform.RecordWriter) error { var batch BatchMessage if err := json.Unmarshal(event.Record().Value, &batch); err != nil { log.Printf("Failed to parse batch message: %v", err) return nil // Skip invalid records } // Process each update in the batch for i, update := range batch.Updates { schemaID, exists := schemaIDs[update.Table] if !exists { log.Printf("Unknown table in update %d: %s", i, update.Table) continue } if err := writeUpdate(update, schemaID, writer, event); err != nil { log.Printf("Failed to write update %d to %s: %v", i, update.Table, err) } } return nil } func writeUpdate(update TableUpdate, schemaID int, writer transform.RecordWriter, event transform.WriteEvent) error { // Create Schema Registry wire format: [magic_byte, schema_id (4 bytes BE), data...] value := make([]byte, 5) value[0] = 0 // magic byte binary.BigEndian.PutUint32(value[1:5], uint32(schemaID)) value = append(value, update.Data...) record := transform.Record{ Key: event.Record().Key, Value: value, } return writer.Write(record, transform.ToTopic(update.Table)) } ``` ##### Rust `Cargo.toml` ```toml [package] name = "fanout-rust-example" version = "0.1.0" edition = "2021" [dependencies] redpanda-transform-sdk = "1.1.0" # v1.1.0+ required for WriteOptions API redpanda-transform-sdk-sr = "1.1.0" serde = { version = "1", features = ["derive"] } serde_json = "1" log = "0.4" env_logger = "0.11" [profile.release] opt-level = "z" lto = true strip = true ``` `src/main.rs`: ```rust use redpanda_transform_sdk::*; use redpanda_transform_sdk_sr::{SchemaRegistryClient, Schema, SchemaFormat}; use serde::Deserialize; use std::collections::HashMap; use std::error::Error; use std::sync::OnceLock; use log::{info, error}; #[derive(Deserialize)] struct BatchMessage { updates: Vec, } #[derive(Deserialize)] struct TableUpdate { table: String, data: serde_json::Value, } // Schema IDs for each output topic, registered dynamically at startup static SCHEMA_IDS: OnceLock> = OnceLock::new(); fn main() { // Initialize logging env_logger::init(); // Create Schema Registry client let mut client = SchemaRegistryClient::new(); // Define schemas for each output topic let schemas = [ ("orders", r#"{"type":"record","name":"Order","fields":[{"name":"order_id","type":"string"},{"name":"amount","type":"double"}]}"#), ("inventory", r#"{"type":"record","name":"Inventory","fields":[{"name":"product_id","type":"string"},{"name":"quantity","type":"int"}]}"#), ("customers", r#"{"type":"record","name":"Customer","fields":[{"name":"customer_id","type":"string"},{"name":"name","type":"string"}]}"#), ]; let mut schema_ids = HashMap::new(); // Register schemas and store their IDs for (topic, schema_str) in schemas { let subject = format!("{}-value", topic); let schema = Schema::new(schema_str.to_string(), SchemaFormat::Avro, vec![]); match client.create_schema(&subject, schema) { Ok(result) => { let id = result.id(); // SchemaId type schema_ids.insert(topic.to_string(), id.0); // Extract i32 from SchemaId wrapper info!("Registered schema for {} with ID {}", topic, id.0); } Err(e) => { error!("Failed to register schema for {}: {}", topic, e); panic!("Schema registration failed"); } } } let _ = SCHEMA_IDS.set(schema_ids); info!("Starting fanout transform with schema IDs"); on_record_written(route_updates); } fn write_update( update: &TableUpdate, schema_id: i32, writer: &mut RecordWriter, event: &WriteEvent, ) -> Result<(), Box> { // Create Schema Registry wire format: [magic_byte, schema_id (4 bytes BE), data...] let mut value = vec![0u8; 5]; value[0] = 0; // magic byte value[1..5].copy_from_slice(&schema_id.to_be_bytes()); let data_bytes = serde_json::to_vec(&update.data)?; value.extend_from_slice(&data_bytes); let key = event.record.key().map(|k| k.to_vec()); let record = BorrowedRecord::new(key.as_deref(), Some(&value)); writer.write_with_options(record, WriteOptions::to_topic(&update.table))?; Ok(()) } fn route_updates(event: WriteEvent, writer: &mut RecordWriter) -> Result<(), Box> { let batch: BatchMessage = serde_json::from_slice(event.record.value().unwrap_or_default())?; let schema_ids = SCHEMA_IDS.get().unwrap(); for update in batch.updates.iter() { if let Some(&schema_id) = schema_ids.get(&update.table) { write_update(update, schema_id, writer, &event)?; } } Ok(()) } ``` ##### JavaScript The JavaScript SDK does not support writing records to specific output topics. For multi-topic fan-out, use the Go or Rust SDK. ### [](#connect-to-the-schema-registry)Connect to the Schema Registry You can use the Schema Registry client library to read and write schemas as well as serialize and deserialize records. This client library is useful when working with schema-based topics in your data transforms. See also: - [Redpanda Schema Registry](../../../manage/schema-reg/schema-reg-overview/) - [Go Schema Registry client reference](../../../reference/data-transforms/golang-sdk/) - [Rust Schema Registry client reference](../../../reference/data-transforms/rust-sdk/) - [JavaScript Schema Registry client reference](../../../reference/data-transforms/js/js-sdk-sr/) ## [](#next-steps)Next steps [Configure Data Transforms](../configure/) ## [](#suggested-reading)Suggested reading - [How Data Transforms Work](../how-transforms-work/) - [Data Transforms SDKs](../../../reference/data-transforms/sdks/) - [`rpk transform` commands](../../../reference/rpk/rpk-transform/rpk-transform/) ## Suggested labs - [Flatten JSON Messages](/redpanda-labs/data-transforms/flatten-go/) - [Convert JSON Messages into Avro](/redpanda-labs/data-transforms/issdemo-go/) - [Convert Timestamps using Rust](/redpanda-labs/data-transforms/ts-converter-rust/) - [Filter Messages into a New Topic using a Regex](/redpanda-labs/data-transforms/regex-go/) - [Redact Information in JSON Messages](/redpanda-labs/data-transforms/redaction-go/) [Search all labs](/redpanda-labs) --- # Page 64: Configure Data Transforms **URL**: https://docs.redpanda.com/current/develop/data-transforms/configure.md --- # Configure Data Transforms --- title: Configure Data Transforms latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: data-transforms/configure page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: data-transforms/configure.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/develop/pages/data-transforms/configure.adoc description: Learn how to configure data transforms in Redpanda, including editing the transform.yaml file, environment variables, and memory settings. This topic covers both the configuration of transform functions and the WebAssembly (Wasm) engine's environment. page-git-created-date: "2024-07-31" page-git-modified-date: "2025-04-08" support-status: supported --- Learn how to configure data transforms in Redpanda, including editing the `transform.yaml` file, environment variables, and memory settings. This topic covers both the configuration of transform functions and the WebAssembly (Wasm) engine’s environment. ## [](#configure-transform-functions)Configure transform functions This section covers how to configure transform functions using the `transform.yaml` configuration file, command-line overrides, and environment variables. ### [](#config-file)Transform configuration file When you [initialize](../build/#init) a data transforms project, a `transform.yaml` file is generated in the provided directory. You can use this configuration file to configure the transform function with settings, including input and output topics, the language used for the data transform, and any environment variables. - `name`: The name of the transform function. - `description`: A description of what the transform function does. - `input-topic`: The topic from which data is read. - `output-topics`: A list of up to eight topics to which the transformed data is written. - `language`: The language used for the transform function. The language is set to the one you defined during [initialization](../build/#init). - `env`: A dictionary of custom environment variables that are passed to the transform function. Do not prefix keys with `REDPANDA_`. Check the list of all [limitations](../how-transforms-work/#limitations). Here is an example of a transform.yaml file: ```yaml name: redpanda-example description: | This transform function is an example to demonstrate how to configure data transforms in Redpanda. input-topic: example-input-topic output-topics: - example-output-topic-1 - example-output-topic-2 language: tinygo-no-goroutines env: DATA_TRANSFORMS_ARE_AWESOME: 'true' ``` ### [](#cl)Override configurations with command-line options You can set the name of the transform function, environment variables, and input and output topics on the command-line when you deploy the transform. These command-line settings take precedence over those specified in the `transform.yaml` file. See [Deploy Data Transforms](../deploy/) ### [](#built-in)Built-In environment variables As well as custom environment variables set in either the [command-line](#cl) or the [configuration file](#config-file), Redpanda makes some built-in environment variables available to your transform functions. These variables include: - `REDPANDA_INPUT_TOPIC`: The input topic specified. - `REDPANDA_OUTPUT_TOPIC_0..REDPANDA_OUTPUT_TOPIC_N`: The output topics in the order specified on the command line or in the configuration file. For example, `REDPANDA_OUTPUT_TOPIC_0` is the first variable, `REDPANDA_OUTPUT_TOPIC_1` is the second variable, and so on. Transform functions are isolated from the broker’s internal environment variables to maintain security and encapsulation. Each transform function only uses the environment variables explicitly provided to it. ## [](#configure-the-wasm-engine)Configure the Wasm engine This section covers how to configure the Wasm engine environment using Redpanda cluster configuration properties. ### [](#enable-transforms)Enable data transforms To use data transforms, you must enable it for a Redpanda cluster using the [`data_transforms_enabled`](../../../reference/properties/cluster-properties/#data_transforms_enabled) property. ### [](#configure-memory-resources-for-data-transforms)Configure memory resources for data transforms Redpanda reserves memory for each transform function within the broker. You need enough memory for your input record and output record to be in memory at the same time. Set the following based on the number of functions you have and the amount of memory you anticipate needing. - [`data_transforms_per_core_memory_reservation`](../../../reference/properties/cluster-properties/#data_transforms_per_core_memory_reservation): Increase this setting if you plan to deploy a large number of data transforms or if your transforms are memory-intensive. Reducing it may limit the number of concurrent transforms. - [`data_transforms_per_function_memory_limit`](../../../reference/properties/cluster-properties/#data_transforms_per_function_memory_limit): Adjust this setting if individual transform functions require more memory to process records efficiently. Reducing it may cause memory errors in complex transforms. The maximum number of functions that can be deployed to a cluster is equal to `data_transforms_per_core_memory_reservation` / `data_transforms_per_function_memory_limit`. When that limit is hit, Redpanda cannot allocate memory for the VM and the transforms stay in `errored` states. ### [](#binary-size)Configure maximum binary size You can set the maximum size for a deployable Wasm binary that the broker can store using the [`data_transforms_binary_max_size`](../../../reference/properties/cluster-properties/#data_transforms_binary_max_size) property. Increase this setting if your Wasm binaries are larger than the default limit. Setting it too low may prevent deployment of valid transform functions. ### [](#commit-interval)Configure commit interval You can set the interval at which data transforms commit their progress using the [`data_transforms_commit_interval_ms`](../../../reference/properties/cluster-properties/#data_transforms_commit_interval_ms) property. Adjust this setting to control how frequently the transform function’s progress is committed. Shorter intervals may provide more frequent progress updates but can increase load. Longer intervals reduce load but may delay progress updates. ### [](#log)Configure transform logging The following properties configure logging for data transforms: - [`data_transforms_logging_buffer_capacity_bytes`](../../../reference/properties/cluster-properties/#data_transforms_logging_buffer_capacity_bytes): Increase this value if your transform logs are large or if you need to buffer more log data before flushing. Reducing this value may cause more frequent log flushing. - [`data_transforms_logging_flush_interval_ms`](../../../reference/properties/cluster-properties/#data_transforms_logging_flush_interval_ms): Adjust this value to control how frequently logs are flushed to the `transform_logs` topic. Shorter intervals provide more frequent log updates but can increase load. Longer intervals reduce load but may delay log updates. - [`data_transforms_logging_line_max_bytes`](../../../reference/properties/cluster-properties/#data_transforms_logging_line_max_bytes): Increase this value if your log messages are frequently truncated. Setting this value too low may truncate important log information. ### [](#runtime-limit)Configure runtime limits You can set the maximum runtime for starting up a data transform and the time it takes for a single record to be transformed using the [`data_transforms_runtime_limit_ms`](../../../reference/properties/cluster-properties/#data_transforms_runtime_limit_ms) property. Adjust this value only if your transform functions need more time to process each record or to start up. ## [](#next-steps)Next steps [Deploy Data Transforms](../deploy/) ## Suggested labs - [Flatten JSON Messages](/redpanda-labs/data-transforms/flatten-go/) - [Convert JSON Messages into Avro](/redpanda-labs/data-transforms/issdemo-go/) - [Convert Timestamps using Rust](/redpanda-labs/data-transforms/ts-converter-rust/) - [Filter Messages into a New Topic using a Regex](/redpanda-labs/data-transforms/regex-go/) - [Redact Information in JSON Messages](/redpanda-labs/data-transforms/redaction-go/) [Search all labs](/redpanda-labs) --- # Page 65: Deploy Data Transforms **URL**: https://docs.redpanda.com/current/develop/data-transforms/deploy.md --- # Deploy Data Transforms --- title: Deploy Data Transforms latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: data-transforms/deploy page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: data-transforms/deploy.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/develop/pages/data-transforms/deploy.adoc description: Learn how to build, deploy, share, and troubleshoot data transforms in Redpanda. page-git-created-date: "2024-07-31" page-git-modified-date: "2025-04-08" support-status: supported --- Learn how to build, deploy, share, and troubleshoot data transforms in Redpanda. ## [](#prerequisites)Prerequisites Before you begin, ensure that you have the following: - [Data transforms enabled](../configure/#enable-transforms) in your Redpanda cluster. - The [`rpk` command-line client](../../../get-started/rpk-install/) installed on your host machine and configured to connect to your Redpanda cluster. - A [data transform](../build/) project. ## [](#build)Build the Wasm binary To build a Wasm binary: 1. Ensure your project directory contains a `transform.yaml` file. 2. Build the Wasm binary using the [`rpk transform build`](../../../reference/rpk/rpk-transform/rpk-transform-build/) command. ```bash rpk transform build ``` You should now have a Wasm binary named `.wasm`, where `` is the name specified in your `transform.yaml` file. This binary is your data transform function, ready to be deployed to a Redpanda cluster or hosted on a network for others to use. ## [](#deploy)Deploy the Wasm binary You can deploy your transform function using the [`rpk transform deploy`](../../../reference/rpk/rpk-transform/rpk-transform-deploy/) command. 1. Validate your setup against the pre-deployment checklist: - Do you meet the [Prerequisites](#prerequisites)? - Does your transform function access any environment variables? If so, make sure to set them in the `transform.yaml` file or in the command-line when you deploy the binary. - Do your configured input and output topics already exist? Input and output topics must exist in your Redpanda cluster before you deploy the Wasm binary. 2. Deploy the Wasm binary: ```bash rpk transform deploy ``` When the transform function reaches Redpanda, it starts processing new records that are written to the input topic. ### [](#reprocess)Reprocess records In some cases, you may need to reprocess records from an input topic that already contains data. Processing existing records can be useful, for example, to process historical data into a different format for a new consumer, to re-create lost data from a deleted topic, or to resolve issues with a previous version of a transform that processed data incorrectly. To reprocess records, you can specify the starting point from which the transform function should process records in each partition of the input topic. The starting point can be either a partition offset or a timestamp. > 📝 **NOTE** > > The `--from-offset` flag is only effective the first time you deploy a transform function. On subsequent deployments of the same function, Redpanda resumes processing from the last committed offset. To reprocess existing records using an existing function, [delete the function](#delete) and redeploy it with the `--from-offset` flag. To deploy a transform function and start processing records from a specific partition offset, use the following syntax: ```bash rpk transform deploy --from-offset +/- ``` In this example, the transform function will start processing records from the beginning of each partition of the input topic: ```bash rpk transform deploy --from-offset +0 ``` To deploy a transform function and start processing records from a specific timestamp, use the following syntax: ```bash rpk transform deploy --from-timestamp @ ``` In this example, the transform function will start processing from the first record in each partition of the input topic that was committed after the given timestamp: ```bash rpk transform deploy --from-timestamp @1617181723 ``` ### [](#share-wasm-binaries)Share Wasm binaries You can also deploy data transforms on a Redpanda cluster by providing an addressable path to the Wasm binary. This is useful for sharing transform functions across multiple clusters or teams within your organization. For example, if the Wasm binary is hosted at `https://my-site/my-transform.wasm`, use the following command to deploy it: ```bash rpk transform deploy --file=https://my-site/my-transform.wasm ``` ## [](#edit-existing-transform-functions)Edit existing transform functions To make changes to an existing transform function: 1. [Make your changes to the code](../build/). 2. [Rebuild](#build) the Wasm binary. 3. [Redeploy](#deploy) the Wasm binary to the same Redpanda cluster. When you redeploy a Wasm binary with the same name, it will resume processing from the last offset it had previously processed. If you need to [reprocess existing records](#reprocess), you must delete the transform function, and redeploy it with the `--from-offset` flag. Deploy-time configuration overrides must be provided each time you redeploy a Wasm binary. Otherwise, they will be overwritten by default values or the configuration file’s contents. ## [](#delete)Delete a transform function To delete a transform function, use the following command: ```bash rpk transform delete ``` For more details about this command, see [rpk transform delete](../../../reference/rpk/rpk-transform/rpk-transform-delete/). > 💡 **TIP** > > You can also [delete transform functions in Redpanda Console](../../../console/ui/data-transforms/#delete). ## [](#troubleshoot)Troubleshoot This section provides guidance on how to diagnose and troubleshoot issues with building or deploying data transforms. ### [](#invalid-transform-environment)Invalid transform environment This error means that one or more of your configured custom environment variables are invalid. Check your custom environment variables against the list of [limitations](../how-transforms-work/#limitations). ### [](#invalid-webassembly)Invalid WebAssembly This error indicates that the binary is missing a required callback function: Invalid WebAssembly - the binary is missing required transform functions. Check the broker support for the version of the data transforms SDK being used. All transform functions must register a callback with the `OnRecordWritten()` method. For more details, see [Develop Data Transforms](../build/). ## [](#next-steps)Next steps [Set up monitoring](../monitor/) for data transforms. ## Suggested labs - [Flatten JSON Messages](/redpanda-labs/data-transforms/flatten-go/) - [Convert JSON Messages into Avro](/redpanda-labs/data-transforms/issdemo-go/) - [Convert Timestamps using Rust](/redpanda-labs/data-transforms/ts-converter-rust/) - [Filter Messages into a New Topic using a Regex](/redpanda-labs/data-transforms/regex-go/) - [Redact Information in JSON Messages](/redpanda-labs/data-transforms/redaction-go/) [Search all labs](/redpanda-labs) --- # Page 66: How Data Transforms Work **URL**: https://docs.redpanda.com/current/develop/data-transforms/how-transforms-work.md --- # How Data Transforms Work --- title: How Data Transforms Work latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: data-transforms/how-transforms-work page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: data-transforms/how-transforms-work.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/develop/pages/data-transforms/how-transforms-work.adoc description: Learn how Redpanda data transforms work. page-git-created-date: "2023-12-22" page-git-modified-date: "2025-04-16" support-status: supported --- Redpanda provides the framework to build and deploy inline transformations (data transforms) on data written to Redpanda topics, delivering processed and validated data to consumers in the format they expect. Redpanda does this directly inside the broker, eliminating the need to manage a separate stream processing environment or use third-party tools. ![Data transforms in a broker](../../../shared/_images/wasm1.png) Data transforms let you run common data streaming tasks, like filtering, scrubbing, and transcoding, within Redpanda. For example, you may have consumers that require you to redact credit card numbers or convert JSON to Avro. Data transforms can also interact with the Redpanda Schema Registry to work with encoded data types. To learn how to build and deploy data transforms, see [Data Transforms in Linux Quickstart](../run-transforms/). ## [](#data-transforms-with-webassembly)Data transforms with WebAssembly Data transforms use [WebAssembly](https://webassembly.org/) (Wasm) engines inside a Redpanda broker, allowing Redpanda to control the entire transform lifecycle. For example, Redpanda can stop and start transforms when partitions are moved or to free up system resources for other tasks. Data transforms take data from an input topic and map it to one or more output topics. For each topic partition, a leader is responsible for handling the data. Redpanda runs a Wasm virtual machine (VM) on the same CPU core (shard) as these partition leaders to execute the transform function. Transform functions are the specific implementations of code that carry out the transformations. They read data from input topics, apply the necessary processing logic, and write the transformed data to output topics. To execute a transform function, Redpanda uses just-in-time (JIT) compilation to compile the bytecode in memory, write it to an executable space, then run the directly translated machine code. This JIT compilation ensures efficient execution of the machine code, as it is tailored to the specific hardware it runs on. When you deploy a data transform to a Redpanda broker, it stores the Wasm bytecode and associated metadata, such as input and output topics and environment variables. The broker then replicates this data across the cluster using internal Kafka topics. When the data is distributed, each shard runs its own instance of the transform function. This process includes several resource management features: - Each shard can run only one instance of the transform function at a time to ensure efficient resource utilization and prevent overload. - Memory for each function is reserved within the broker with the `data_transforms_per_core_memory_reservation` and `data_transforms_per_function_memory_limit` properties. See [Configure memory for data transforms](../configure/#resources). - CPU time is dynamically allocated to the Wasm runtime to ensure that the code does not run forever and cannot block the broker from handling traffic or doing other work, such as Tiered Storage uploads. ## [](#flow-of-data-transforms)Flow of data transforms When a shard becomes the leader of a given partition on the input topic of one or more active transforms, Redpanda does the following: 1. Spins up a Wasm VM using the JIT-compiled Wasm module. 2. Pushes records from the input partition into the Wasm VM. 3. Writes the output. The output partition may exist on the same broker or on another broker in the cluster. Within Redpanda, a single Raft controller manages cluster information, including data transforms. On every shard, Redpanda knows what data transforms exist in the cluster, as well as metadata about the transform function, such as input and output topics and environment variables. ![Wasm architecture in Redpanda](../../../shared/_images/wasm_architecture.png) Each transform function reads from a specified input topic and writes to a specified output topic. The transform function processes every record produced to an input topic and returns zero or more records that are then produced to the specified output topic. Data transforms are applied to all partitions on an input topic. A record is processed after it has been successfully written to disk on the input topic. Because the transform happens in the background after the write finishes, the transform doesn’t affect the original produced record, doesn’t block writes to the input topic, and doesn’t block produce and consume requests. A new transform function reads the input topic from the latest offset. That is, it only reads new data produced to the input topic: it does not read records produced to the input topic before the transform was deployed. If a partition leader moves from one broker to another, then the instance of the transform function assigned to that partition moves with it. When a partition replica [loses leadership](../../../get-started/architecture/#partition-leadership-elections), the broker hosting that partition replica stops the instance of the transform function running on the same shard. The broker that is now hosting the partition’s new leader starts the transform function on the same shard as that leader, and the transform function resumes from the last committed offset. If the previous instance of the transform function failed to commit its latest offsets before moving with the partition leader (for example, if the broker crashed), then it’s likely that the new instance will reprocess some events. For broker failures, transform functions have at-least-once semantics, because records are retried from the committed last offset, and offsets are committed periodically. For more information, see [Data Transforms in Linux Quickstart](../run-transforms/). ## [](#limitations)Limitations This section outlines the limitations of data transforms. These constraints are categorized into general limitations affecting the overall functionality and specific limitations related to giving data transforms access to custom environment variables. ### [](#general)General - **No external access**: Transform functions have no external access to disk or network resources. - **Single message transforms**: Only single record transforms are supported, but multiple output records from a single input record are supported. For aggregations, joins, or complex transformations, consider using [Redpanda Connect](../../../../redpanda-connect/get-started/about/) or [Apache Flink](https://flink.apache.org/). - **Output topic limit**: Up to eight output topics are supported. - **Delivery semantics**: Transform functions have at-least-once delivery. - **Transactions API**: When clients use the Kafka Transactions API on partitions of an input topic, transform functions process only committed records. ### [](#javascript)JavaScript - **No native extensions**: Native Node.js extensions are not supported. Packages that require compiling native code or interacting with low-level system features cannot be used. - **Limited Node.js standard modules**: Only modules that can be polyfilled by the [esbuild plugin](https://www.npmjs.com/package/esbuild-plugin-polyfill-node#implemented-polyfills) can be used. Even if a module can be polyfilled, certain functionalities, such as network connections, will not work because the necessary browser APIs are not exposed in the Redpanda JavaScript runtime environment. For example, while the plugin can provide stubs for some Node.js modules such as `http` and `process`, these stubs will not work in the Redpanda JavaScript runtime environment. - **No write options**: The JavaScript SDK does not support write options, such as specifying which output topic to write to. ### [](#environment-variables)Environment variables - **Maximum number of variables**: You can set up to 128 custom environment variables. - **Reserved prefix**: Variable keys must not start with `REDPANDA_`. This prefix is reserved for [built-in environment variables](../configure/#built-in). - **Key length**: Each key must be less than 128 bytes in length. - **Total value length**: The combined length of all values for the environment variables must be less than 2000 bytes. - **Encoding**: All keys and values must be encoded in UTF-8. - **Control characters**: Keys and values must not contain any control characters, such as null bytes. ## [](#suggested-reading)Suggested reading - [Golang SDK for Data Transforms](../../../reference/data-transforms/golang-sdk/) - [Rust SDK for Data Transforms](../../../reference/data-transforms/rust-sdk/) - [`rpk transform` commands](../../../reference/rpk/rpk-transform/rpk-transform/) ## Suggested labs - [Flatten JSON Messages](/redpanda-labs/data-transforms/flatten-go/) - [Convert JSON Messages into Avro](/redpanda-labs/data-transforms/issdemo-go/) - [Convert Timestamps using Rust](/redpanda-labs/data-transforms/ts-converter-rust/) - [Filter Messages into a New Topic using a Regex](/redpanda-labs/data-transforms/regex-go/) - [Redact Information in JSON Messages](/redpanda-labs/data-transforms/redaction-go/) [Search all labs](/redpanda-labs) --- # Page 67: Data Transforms in Kubernetes Quickstart **URL**: https://docs.redpanda.com/current/develop/data-transforms/k-run-transforms.md --- # Data Transforms in Kubernetes Quickstart --- title: Data Transforms in Kubernetes Quickstart latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: data-transforms/k-run-transforms page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: data-transforms/k-run-transforms.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/develop/pages/data-transforms/k-run-transforms.adoc description: Learn how to build and deploy your first transform function in Kubernetes deployments. page-git-created-date: "2023-12-22" page-git-modified-date: "2025-07-31" support-status: supported --- Data transforms let you run common data streaming tasks, like filtering, scrubbing, and transcoding, within Redpanda. For example, you may have consumers that require you to redact credit card numbers or convert JSON to Avro. Data transforms can also interact with the Redpanda Schema Registry to work with encoded data types. Data transforms use a WebAssembly (Wasm) engine inside a Redpanda broker. A Wasm function acts on a single record in an input topic. You can develop and manage data transforms with [`rpk transform`](../../../reference/rpk/rpk-transform/rpk-transform/) commands. > 📝 **NOTE** > > You should build and deploy transforms from a separate, non-production machine (host machine). Using a separate host machine avoids potential resource conflicts and stability issues on the nodes that run your brokers. See also: [How Data Transforms Work](../how-transforms-work/) ## [](#prerequisites)Prerequisites You must have the following: - [A Redpanda cluster](../../../deploy/redpanda/) running at least version 26.1. - External access to the Kafka API and the Admin API. Ensure that your Redpanda cluster has [external access](../../../manage/kubernetes/networking/external/) enabled and is accessible from your host machine using the advertised addresses. > 💡 **TIP** > > For a tutorial on setting up a Redpanda cluster with external access, see [Get Started with Redpanda in Kubernetes](../../../deploy/redpanda/kubernetes/get-started-dev/). - Development tools installed on your host machine: - For Golang, you must have at least version 1.20 of [Go](https://go.dev/doc/install). - For Rust, you must have the latest stable version of [Rust](https://rustup.rs/). - The [`rpk` command-line client](../../../get-started/rpk-install/) installed on your host machine and configured to connect to your Redpanda cluster. - For JavaScript and TypeScript projects, you must have the [latest long-term-support release of Node.js](https://nodejs.org/en/download/package-manager). You can use a [pre-configured `rpk` profile](../../../manage/kubernetes/networking/k-connect-to-redpanda/#rpk-profile): ```bash rpk profile create --from-profile <(kubectl get configmap --namespace redpanda-rpk -o go-template='{{ .data.profile }}') ``` Replace `` with the name that you want to give this `rpk` profile. ## [](#enable-data-transforms)Enable data transforms Data transforms is disabled on all clusters by default. Before you can deploy data transforms to a cluster, you must first enable the feature. 1. To enable data transforms, set the `data_transforms_enabled` cluster property to `true`: ### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: config: cluster: data_transforms_enabled: true ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ### Helm #### --values `write-caching.yaml` ```yaml config: cluster: data_transforms_enabled: true ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values write-caching.yaml --reuse-values ``` #### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set config.cluster.data_transforms_enabled=true ``` 2. Restart all brokers: ```bash kubectl rollout restart statefulset redpanda --namespace= ``` 3. Wait for all Pods to restart: ```bash kubectl rollout status statefulset redpanda --namespace= --watch ``` ## [](#create-a-data-transforms-project)Create a data transforms project The easiest way to create a new data transforms project is to use the [`rpk transform init` command](../../../reference/rpk/rpk-transform/rpk-transform-init/). This command generates template files and installs any dependencies for your chosen language. Create and initialize a data transforms project: ### Go ```bash rpk transform init --language=tinygo --name=data-transforms-tutorial ``` A successful command generates project files in your current directory: . ├── go.mod ├── go.sum ├── README.md ├── transform.go └── transform.yaml The `transform.go` file is the source file for your transform function. The `transform.yaml` file is the configuration for your transform function. The `transform.yaml` file already contains the name of your transform function and the language that you specified in the `rpk transform init` command. ### Rust ```bash rpk transform init --language=rust --name=data-transforms-tutorial ``` A successful command generates project files in your current directory: . ├── Cargo.lock ├── Cargo.toml ├── README.md ├── src │ └── main.rs └── transform.yaml The `src/main.rs` file is the source file for your transform function. The `transform.yaml` file is the configuration for your transform function. The `transform.yaml` file already contains the name of your transform function and the language that you specified in the `rpk transform init` command. ### JavaScript ```bash rpk transform init --language=javascript --name=data-transforms-tutorial ``` A successful command generates project files in your current directory: . ├── README.md ├── esbuild.js ├── node\_modules ├── package-lock.json ├── package.json ├── src │ └── index.js └── transform.yaml The `src/index.js` file is the source file for your transform function. The `transform.yaml` file is the configuration for your transform function. The `transform.yaml` file already contains the name of your transform function and the language that you specified in the `rpk transform init` command. The `esbuild.js` file is the build script for your project. This file configures the build process using esbuild, a fast JavaScript bundler. It ensures that your code is bundled correctly and includes any necessary polyfills for Node.js standard modules that are not natively available in the Redpanda JavaScript runtime environment. Now that you have a project set up, you can run some examples to learn how to work with data transforms. Make sure to copy the provided transform functions and paste them into your source file. For example, the `transform.go` file for Go projects, or the `src/main.rs` file for Rust. ## [](#run-examples)Run examples This section provides some examples of transform functions to teach you the basics of writing and deploying data transforms. It’s best to try each example in order, one after the other. ### [](#copy-records-from-one-topic-to-another)Copy records from one topic to another This transform function copies the same data from an input topic to an output topic. 1. Paste this transform function into your source file: #### Go ```go package main import ( "github.com/redpanda-data/redpanda/src/transform-sdk/go/transform" ) func main() { // Make sure to register your callback and perform other setup in main transform.OnRecordWritten(copyRecordsToOutput) } // This will be called for each record in the input topic. // The records returned will be written to the output topic. func copyRecordsToOutput(event transform.WriteEvent, writer transform.RecordWriter) error { return writer.Write(event.Record()) } ``` #### Rust ```rust use anyhow::Result; use redpanda_transform_sdk::*; fn main() { // Make sure to register your callback and perform other setup in main on_record_written(copy_records_to_output); } // This will be called for each record in the input topic. // The records returned will be written to the output topic. fn copy_records_to_output(event: WriteEvent, writer: &mut RecordWriter) -> Result<()> { writer.write(event.record)?; Ok(()) } ``` #### JavaScript ```js import { onRecordWritten } from "@redpanda-data/transform-sdk"; // Register your callback function in the entry point of your script. onRecordWritten(copyRecordsToOutput); // This function will be called for each record in the input topic. // The records returned will be written to the output topic. function copyRecordsToOutput(event, writer) { writer.write(event.record); } ``` 2. Build the transform into a Wasm binary: ```bash rpk transform build ``` 3. Create topics to apply the transform function to: ```bash rpk topic create input-topic output-topic ``` 4. Deploy the Wasm binary to your cluster: ```bash rpk transform deploy --input-topic=input-topic --output-topic=output-topic ``` 5. Produce two new records to the input topic. ```bash echo "hello\nworld" | rpk topic produce input-topic ``` 6. [Open Redpanda Console](http://localhost:8080/topics) and check the records in both the input topic and the output topic. They should be the same. You can also verify the content of the output topic in the command-line: ```bash rpk topic consume output-topic ``` ### [](#convert-csv-input-to-json-output)Convert CSV input to JSON output This example is a transform function that converts CSV inputs into JSON outputs. 1. Prepare the project files: #### Go Paste this transform function into your source file: ```go package main import ( "bytes" "encoding/csv" "encoding/json" "errors" "io" "strconv" "github.com/redpanda-data/redpanda/src/transform-sdk/go/transform" ) func main() { transform.OnRecordWritten(csvToJsonTransform) } type ItemQuantity struct { Item string `json:"item"` Quantity int `json:"quantity"` } func csvToJsonTransform(event transform.WriteEvent, writer transform.RecordWriter) error { // The input data is a CSV (without a header row) that is structured as: // key, item, quantity reader := csv.NewReader(bytes.NewReader(event.Record().Value)) // Improve performance by reusing the result slice. reader.ReuseRecord = true for { row, err := reader.Read() if err == io.EOF { break } else if err != nil { return err } if len(row) != 3 { return errors.New("unexpected number of rows") } // Convert the last column into an int quantity, err := strconv.Atoi(row[2]) if err != nil { return err } // Marshall the JSON value iq := ItemQuantity{ Item: row[1], Quantity: quantity, } v, err := json.Marshal(&iq) if err != nil { return err } // Add the output record using the first column as the key. r := transform.Record{ Key: []byte(row[0]), Value: v, } if err := writer.Write(r); err != nil { return err } } return nil } ``` #### Rust 1. Add the following dependencies to the `Cargo.toml` file: ```toml csv = "1.3.0" serde_json = "1.0.111" serde = { version = "1.0.195", features = ["derive"] } ``` 2. Run the following command to update your dependencies: ```bash cargo build ``` 3. Paste this transform function into your source file: ```rust use anyhow::Result; use redpanda_transform_sdk::*; use serde::{Deserialize, Serialize}; use csv::ReaderBuilder; use serde_json; #[derive(Serialize, Deserialize)] struct MarketStock { item: String, quantity: i32, } fn main() { on_record_written(csv_to_json_transform); } fn csv_to_json_transform(event: WriteEvent, writer: &mut RecordWriter) -> Result<()> { // The input data is a CSV (without a header row) that is defined as the MarketStock structure. let mut reader = ReaderBuilder::new().has_headers(false).from_reader(event.record.value().unwrap_or_default()); // For each record in our CSV for result in reader.deserialize() { let stock: MarketStock = match result { Ok(record) => record, Err(err) => { eprintln!("CSV deserialize error: {}", err); continue; // Skip the invalid record and continue processing } }; // Convert it to JSON let value = serde_json::to_vec(&stock)?; // Then output it with the same key. writer.write(BorrowedRecord::new(event.record.key(), Some(&value)))?; } Ok(()) } ``` #### JavaScript Paste this transform function into your source file: ```js import { onRecordWritten } from "@redpanda-data/transform-sdk"; onRecordWritten(csvToJsonTransform); function csvToJsonTransform(event, writer) { // The input data is a CSV (without a header row) that is structured as: // key, item, quantity const input = event.record.value.text(); const rows = input.split('\n'); for (const row of rows) { const columns = row.split(','); if (columns.length !== 2) { throw new Error('unexpected number of columns'); } const quantity = parseInt(columns[1], 10); if (isNaN(quantity)) { throw new Error('invalid quantity'); } const itemQuantity = { item: columns[0], quantity: quantity, }; event.record.value = JSON.stringify(itemQuantity); writer.write(event.record); } } ``` 2. Build the transform into a Wasm binary: ```bash rpk transform build ``` 3. Create topics to apply the transform function to: ```bash rpk topic create input-topic output-topic ``` 4. Deploy the Wasm binary to your cluster. If you have already deployed another example, this new transform function will replace it. ```bash rpk transform deploy --input-topic=input-topic --output-topic=output-topic ``` 5. Produce CSV records to the input topic. ```bash echo "apples,10\npears,11\noranges,5" | rpk topic produce input-topic -k market-stock ``` 6. [Open Redpanda Console](http://localhost:8080/topics) and check the records in both the input topic and the output topic. You should see the following values: ```json { "item": "oranges", "quantity": 5 } { "item": "apples", "quantity": 10 } { "item": "pears", "quantity": 11 } ``` You can also verify the content of the output topic in the command-line: ```bash rpk topic consume output-topic ``` ### [](#validate-json)Validate JSON This example is a filter that outputs only valid JSON from the input topic into the output topic. Invalid JSON is written to a different output topic. 1. Paste this transform function into your source file: #### Go ```go import ( "encoding/json" "github.com/redpanda-data/redpanda/src/transform-sdk/go/transform" ) func main() { transform.OnRecordWritten(filterValidJson) } func filterValidJson(event transform.WriteEvent, writer transform.RecordWriter) error { if json.Valid(event.Record().Value) { return w.Write(e.Record()) } // Send invalid records to separate topic return writer.Write(e.Record(), transform.ToTopic("invalid-json")) } ``` #### Rust ```rust use anyhow::Result; use redpanda_transform_sdk::*; fn main() { on_record_written(filter_valid_json); } fn filter_valid_json(event: WriteEvent, writer: &mut RecordWriter) -> Result<()> { let value = event.record.value().unwrap_or_default(); if serde_json::from_slice::(value).is_ok() { writer.write(event.record)?; } else { // Send invalid records to separate topic writer.write_with_options(event.record, WriteOptions::to_topic("invalid-json"))?; } Ok(()) } ``` #### JavaScript The JavaScript SDK does not support writing records to a specific output topic. As a result, this transform function writes only valid JSON messages to the output topic. Invalid messages are logged, instead of written to a separate output topic. ```js import { onRecordWritten } from "@redpanda-data/transform-sdk"; onRecordWritten(filterValidJson); function filterValidJson(event, writer) { const recordValue = event.record.value.text(); if (isValidJson(recordValue)) { writer.write(event.record); } else { console.log('Invalid JSON detected') } } function isValidJson(str) { try { JSON.parse(str); return true; } catch (e) { return false; } } ``` 2. Build the transform into a Wasm binary: ```bash rpk transform build ``` 3. Create topics to apply the transform function to: ```bash rpk topic create input-topic output-topic invalid-json ``` 4. Deploy the Wasm binary to your cluster. If you have already deployed another example, this new transform function will replace it. ```bash rpk transform deploy --input-topic=input-topic --output-topic=output-topic --output-topic=invalid-json ``` 5. Produce an invalid JSON record a one valid one to the input topic. ```bash echo '{"valid":"json"}' | rpk topic produce input-topic -k json echo 'invalid json' | rpk topic produce input-topic -k json ``` 6. Verify the content of the output topic in the command-line: ```bash rpk topic consume output-topic ``` You should see only the valid JSON from the input topic. Invalid JSON messages are written to the `invalid-json` topic. ## [](#clean-up)Clean up Your transform function will continue processing new records in the input topic until you delete it. To delete the transform function: ```bash rpk transform delete data-transforms-tutorial --no-confirm ``` ## [](#suggested-reading)Suggested reading - [How Data Transforms Work](../how-transforms-work/) - [Golang SDK for Data Transforms](../../../reference/data-transforms/golang-sdk/) - [Rust SDK for Data Transforms](../../../reference/data-transforms/rust-sdk/) - [`rpk transform` commands](../../../reference/rpk/rpk-transform/rpk-transform/) ## Suggested labs - [Flatten JSON Messages](/redpanda-labs/data-transforms/flatten-go/) - [Convert JSON Messages into Avro](/redpanda-labs/data-transforms/issdemo-go/) - [Convert Timestamps using Rust](/redpanda-labs/data-transforms/ts-converter-rust/) - [Filter Messages into a New Topic using a Regex](/redpanda-labs/data-transforms/regex-go/) - [Redact Information in JSON Messages](/redpanda-labs/data-transforms/redaction-go/) [Search all labs](/redpanda-labs) --- # Page 68: Prebuilt Data Transforms **URL**: https://docs.redpanda.com/current/develop/data-transforms/labs.md --- # Prebuilt Data Transforms --- title: Prebuilt Data Transforms latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: data-transforms/labs page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: data-transforms/labs.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/develop/pages/data-transforms/labs.adoc description: Explore labs that include examples of transform functions and instructions on how to deploy and run them. page-git-created-date: "2024-07-31" page-git-modified-date: "2024-08-01" support-status: supported --- Explore labs that include examples of transform functions and instructions on how to deploy and run them. - [Flatten JSON Messages](/redpanda-labs/data-transforms/flatten-go/): Flatten JSON messages in topics using data transforms. - [Convert JSON Messages into Avro](/redpanda-labs/data-transforms/issdemo-go/): Query live tracking data from the International Space Station and convert it from JSON to Avro using data transforms. - [Convert Timestamps using Rust](/redpanda-labs/data-transforms/ts-converter-rust/): Convert timestamps from various forms, such as epochs to strings. - [Filter Messages into a New Topic using a Regex](/redpanda-labs/data-transforms/regex-go/): Filter messages from one topic into another using regular expressions (regex) and data transforms. - [Redact Information in JSON Messages](/redpanda-labs/data-transforms/redaction-go/): Redact personally identifiable information (PII) in topics using data transforms. --- # Page 69: Monitor Data Transforms **URL**: https://docs.redpanda.com/current/develop/data-transforms/monitor.md --- # Monitor Data Transforms --- title: Monitor Data Transforms latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: data-transforms/monitor page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: data-transforms/monitor.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/develop/pages/data-transforms/monitor.adoc description: This topic provides guidelines on how to monitor the health of your data transforms and view logs. page-git-created-date: "2024-07-31" page-git-modified-date: "2025-04-08" support-status: supported --- This topic provides guidelines on how to monitor the health of your data transforms and view logs. ## [](#prerequisites)Prerequisites [Set up monitoring](../../../manage/monitoring/) for your cluster. ## [](#performance)Performance You can identify performance bottlenecks by monitoring latency and CPU usage: - [`redpanda_transform_execution_latency_sec`](../../../reference/public-metrics-reference/#redpanda_transform_execution_latency_sec) - [`redpanda_wasm_engine_cpu_seconds_total`](../../../reference/public-metrics-reference/#redpanda_wasm_engine_cpu_seconds_total) If latency is high, investigate the transform logic for inefficiencies or consider scaling the resources. High CPU usage might indicate the need for optimization in the code or an increase in [allocated CPU resources](../configure/). ## [](#reliability)Reliability Tracking execution errors and error states helps in maintaining the reliability of your data transforms: - [`redpanda_transform_execution_errors`](../../../reference/public-metrics-reference/#redpanda_transform_execution_errors) - [`redpanda_transform_failures`](../../../reference/public-metrics-reference/#redpanda_transform_failures) - [`redpanda_transform_state`](../../../reference/public-metrics-reference/#redpanda_transform_state) Make sure to [implement robust error handling and logging](../build/#errors) within your transform functions to help with troubleshooting. ## [](#resource-usage)Resource usage Monitoring memory usage metrics and total execution time ensures that the Wasm engine does not exceed allocated resources, helping in efficient resource management: - [`redpanda_wasm_engine_memory_usage`](../../../reference/public-metrics-reference/#redpanda_wasm_engine_memory_usage) - [`redpanda_wasm_engine_max_memory`](../../../reference/public-metrics-reference/#redpanda_wasm_engine_max_memory) - [`redpanda_wasm_binary_executable_memory_usage`](../../../reference/public-metrics-reference/#redpanda_wasm_binary_executable_memory_usage) If memory usage is consistently high or exceeds the maximum allocated memory: - Review and optimize your transform functions to reduce memory consumption. This step can involve optimizing data structures, reducing memory allocations, and ensuring efficient handling of records. - Consider increasing the allocated memory for the Wasm engine. Adjust the [`data_transforms_per_core_memory_reservation`](../configure/#resources) and [`data_transforms_per_function_memory_limit settings`](../configure/#resources) to provide more memory to each function and the overall Wasm engine. ## [](#throughput)Throughput Keeping track of read and write bytes and processor lag helps in understanding the data flow through your transforms, enabling better capacity planning and scaling: - [`redpanda_transform_read_bytes`](../../../reference/public-metrics-reference/#redpanda_transform_read_bytes) - [`redpanda_transform_write_bytes`](../../../reference/public-metrics-reference/#redpanda_transform_write_bytes) - [`redpanda_transform_processor_lag`](../../../reference/public-metrics-reference/#redpanda_transform_processor_lag) If there is a significant lag or low throughput, investigate potential bottlenecks in the data flow or consider scaling your infrastructure to handle higher throughput. ## [](#logs)View logs for data transforms Runtime logs for transform functions are written to an internal topic called `_redpanda.transform_logs`. You can read these logs by using the [`rpk transform logs`](../../../reference/rpk/rpk-transform/rpk-transform-logs/) command. ```bash rpk transform logs ``` Replace `` with the [configured name](../configure/) of the transform function. > 💡 **TIP** > > You can also [view logs in Redpanda Console](../../../console/ui/data-transforms/#logs). By default, Redpanda provides several settings to manage logging for data transforms, such as buffer capacity, flush interval, and maximum log line length. These settings ensure that logging operates efficiently without overwhelming the system. However, you may need to adjust these settings based on your specific requirements and workloads. For information on how to configure logging, see the [Configure transform logging](../configure/#log) section of the configuration guide. ## [](#suggested-reading)Suggested reading - [Data transforms metrics](../../../reference/public-metrics-reference/#data_transform_metrics) ## Suggested labs - [Flatten JSON Messages](/redpanda-labs/data-transforms/flatten-go/) - [Convert JSON Messages into Avro](/redpanda-labs/data-transforms/issdemo-go/) - [Convert Timestamps using Rust](/redpanda-labs/data-transforms/ts-converter-rust/) - [Filter Messages into a New Topic using a Regex](/redpanda-labs/data-transforms/regex-go/) - [Redact Information in JSON Messages](/redpanda-labs/data-transforms/redaction-go/) [Search all labs](/redpanda-labs) --- # Page 70: Data Transforms Quickstarts **URL**: https://docs.redpanda.com/current/develop/data-transforms/run-transforms-index.md --- # Data Transforms Quickstarts --- title: Data Transforms Quickstarts latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: data-transforms/run-transforms-index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: data-transforms/run-transforms-index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/develop/pages/data-transforms/run-transforms-index.adoc description: Choose your deployment environment to get started with building and deploying your first transform function in Redpanda. page-git-created-date: "2023-12-22" page-git-modified-date: "2025-04-16" support-status: supported --- - [Data Transforms in Linux Quickstart](../run-transforms/) Learn how to build and deploy your first transform function in Linux deployments. - [Data Transforms in Kubernetes Quickstart](../k-run-transforms/) Learn how to build and deploy your first transform function in Kubernetes deployments. --- # Page 71: Data Transforms in Linux Quickstart **URL**: https://docs.redpanda.com/current/develop/data-transforms/run-transforms.md --- # Data Transforms in Linux Quickstart --- title: Data Transforms in Linux Quickstart latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: data-transforms/run-transforms page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: data-transforms/run-transforms.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/develop/pages/data-transforms/run-transforms.adoc description: Learn how to build and deploy your first transform function in Linux deployments. page-git-created-date: "2023-12-22" page-git-modified-date: "2025-07-31" support-status: supported --- Data transforms let you run common data streaming tasks, like filtering, scrubbing, and transcoding, within Redpanda. For example, you may have consumers that require you to redact credit card numbers or convert JSON to Avro. Data transforms can also interact with the Redpanda Schema Registry to work with encoded data types. Data transforms use a WebAssembly (Wasm) engine inside a Redpanda broker. A Wasm function acts on a single record in an input topic. You can develop and manage data transforms with [`rpk transform`](../../../reference/rpk/rpk-transform/rpk-transform/) commands. > 📝 **NOTE** > > You should build and deploy transforms from a separate, non-production machine (host machine). Using a separate host machine avoids potential resource conflicts and stability issues on the nodes that run your brokers. See also: [How Data Transforms Work](../how-transforms-work/) ## [](#prerequisites)Prerequisites You must have the following: - [A Redpanda cluster](../../../deploy/redpanda/) running at least version 26.1. - External access to the Kafka API and the Admin API. - Development tools installed on your host machine: - For Golang, you must have at least version 1.20 of [Go](https://go.dev/doc/install). - For Rust, you must have the latest stable version of [Rust](https://rustup.rs/). - The [`rpk` command-line client](../../../get-started/rpk-install/) installed on your host machine and configured to connect to your Redpanda cluster. - For JavaScript and TypeScript projects, you must have the [latest long-term-support release of Node.js](https://nodejs.org/en/download/package-manager). ## [](#enable-data-transforms)Enable data transforms Data transforms is disabled on all clusters by default. Before you can deploy data transforms to a cluster, you must first enable the feature. 1. To enable data transforms, set the `data_transforms_enabled` cluster property to `true`: ```bash rpk cluster config set data_transforms_enabled true ``` 2. Restart all brokers: ```bash rpk redpanda stop rpk redpanda start ``` ## [](#create-a-data-transforms-project)Create a data transforms project The easiest way to create a new data transforms project is to use the [`rpk transform init` command](../../../reference/rpk/rpk-transform/rpk-transform-init/). This command generates template files and installs any dependencies for your chosen language. Create and initialize a data transforms project: ### Go ```bash rpk transform init --language=tinygo --name=data-transforms-tutorial ``` A successful command generates project files in your current directory: . ├── go.mod ├── go.sum ├── README.md ├── transform.go └── transform.yaml The `transform.go` file is the source file for your transform function. The `transform.yaml` file is the configuration for your transform function. The `transform.yaml` file already contains the name of your transform function and the language that you specified in the `rpk transform init` command. ### Rust ```bash rpk transform init --language=rust --name=data-transforms-tutorial ``` A successful command generates project files in your current directory: . ├── Cargo.lock ├── Cargo.toml ├── README.md ├── src │ └── main.rs └── transform.yaml The `src/main.rs` file is the source file for your transform function. The `transform.yaml` file is the configuration for your transform function. The `transform.yaml` file already contains the name of your transform function and the language that you specified in the `rpk transform init` command. ### JavaScript ```bash rpk transform init --language=javascript --name=data-transforms-tutorial ``` A successful command generates project files in your current directory: . ├── README.md ├── esbuild.js ├── node\_modules ├── package-lock.json ├── package.json ├── src │ └── index.js └── transform.yaml The `src/index.js` file is the source file for your transform function. The `transform.yaml` file is the configuration for your transform function. The `transform.yaml` file already contains the name of your transform function and the language that you specified in the `rpk transform init` command. The `esbuild.js` file is the build script for your project. This file configures the build process using esbuild, a fast JavaScript bundler. It ensures that your code is bundled correctly and includes any necessary polyfills for Node.js standard modules that are not natively available in the Redpanda JavaScript runtime environment. Now that you have a project set up, you can run some examples to learn how to work with data transforms. Make sure to copy the provided transform functions and paste them into your source file. For example, the `transform.go` file for Go projects, or the `src/main.rs` file for Rust. ## [](#run-examples)Run examples This section provides some examples of transform functions to teach you the basics of writing and deploying data transforms. It’s best to try each example in order, one after the other. ### [](#copy-records-from-one-topic-to-another)Copy records from one topic to another This transform function copies the same data from an input topic to an output topic. 1. Paste this transform function into your source file: #### Go ```go package main import ( "github.com/redpanda-data/redpanda/src/transform-sdk/go/transform" ) func main() { // Make sure to register your callback and perform other setup in main transform.OnRecordWritten(copyRecordsToOutput) } // This will be called for each record in the input topic. // The records returned will be written to the output topic. func copyRecordsToOutput(event transform.WriteEvent, writer transform.RecordWriter) error { return writer.Write(event.Record()) } ``` #### Rust ```rust use anyhow::Result; use redpanda_transform_sdk::*; fn main() { // Make sure to register your callback and perform other setup in main on_record_written(copy_records_to_output); } // This will be called for each record in the input topic. // The records returned will be written to the output topic. fn copy_records_to_output(event: WriteEvent, writer: &mut RecordWriter) -> Result<()> { writer.write(event.record)?; Ok(()) } ``` #### JavaScript ```js import { onRecordWritten } from "@redpanda-data/transform-sdk"; // Register your callback function in the entry point of your script. onRecordWritten(copyRecordsToOutput); // This function will be called for each record in the input topic. // The records returned will be written to the output topic. function copyRecordsToOutput(event, writer) { writer.write(event.record); } ``` 2. Build the transform into a Wasm binary: ```bash rpk transform build ``` 3. Create topics to apply the transform function to: ```bash rpk topic create input-topic output-topic ``` 4. Deploy the Wasm binary to your cluster: ```bash rpk transform deploy --input-topic=input-topic --output-topic=output-topic ``` 5. Produce two new records to the input topic. ```bash echo "hello\nworld" | rpk topic produce input-topic ``` 6. [Open Redpanda Console](http://localhost:8080/topics) and check the records in both the input topic and the output topic. They should be the same. You can also verify the content of the output topic in the command-line: ```bash rpk topic consume output-topic ``` ### [](#convert-csv-input-to-json-output)Convert CSV input to JSON output This example is a transform function that converts CSV inputs into JSON outputs. 1. Prepare the project files: #### Go Paste this transform function into your source file: ```go package main import ( "bytes" "encoding/csv" "encoding/json" "errors" "io" "strconv" "github.com/redpanda-data/redpanda/src/transform-sdk/go/transform" ) func main() { transform.OnRecordWritten(csvToJsonTransform) } type ItemQuantity struct { Item string `json:"item"` Quantity int `json:"quantity"` } func csvToJsonTransform(event transform.WriteEvent, writer transform.RecordWriter) error { // The input data is a CSV (without a header row) that is structured as: // key, item, quantity reader := csv.NewReader(bytes.NewReader(event.Record().Value)) // Improve performance by reusing the result slice. reader.ReuseRecord = true for { row, err := reader.Read() if err == io.EOF { break } else if err != nil { return err } if len(row) != 3 { return errors.New("unexpected number of rows") } // Convert the last column into an int quantity, err := strconv.Atoi(row[2]) if err != nil { return err } // Marshall the JSON value iq := ItemQuantity{ Item: row[1], Quantity: quantity, } v, err := json.Marshal(&iq) if err != nil { return err } // Add the output record using the first column as the key. r := transform.Record{ Key: []byte(row[0]), Value: v, } if err := writer.Write(r); err != nil { return err } } return nil } ``` #### Rust 1. Add the following dependencies to the `Cargo.toml` file: ```toml csv = "1.3.0" serde_json = "1.0.111" serde = { version = "1.0.195", features = ["derive"] } ``` 2. Run the following command to update your dependencies: ```bash cargo build ``` 3. Paste this transform function into your source file: ```rust use anyhow::Result; use redpanda_transform_sdk::*; use serde::{Deserialize, Serialize}; use csv::ReaderBuilder; use serde_json; #[derive(Serialize, Deserialize)] struct MarketStock { item: String, quantity: i32, } fn main() { on_record_written(csv_to_json_transform); } fn csv_to_json_transform(event: WriteEvent, writer: &mut RecordWriter) -> Result<()> { // The input data is a CSV (without a header row) that is defined as the MarketStock structure. let mut reader = ReaderBuilder::new().has_headers(false).from_reader(event.record.value().unwrap_or_default()); // For each record in our CSV for result in reader.deserialize() { let stock: MarketStock = match result { Ok(record) => record, Err(err) => { eprintln!("CSV deserialize error: {}", err); continue; // Skip the invalid record and continue processing } }; // Convert it to JSON let value = serde_json::to_vec(&stock)?; // Then output it with the same key. writer.write(BorrowedRecord::new(event.record.key(), Some(&value)))?; } Ok(()) } ``` #### JavaScript Paste this transform function into your source file: ```js import { onRecordWritten } from "@redpanda-data/transform-sdk"; onRecordWritten(csvToJsonTransform); function csvToJsonTransform(event, writer) { // The input data is a CSV (without a header row) that is structured as: // key, item, quantity const input = event.record.value.text(); const rows = input.split('\n'); for (const row of rows) { const columns = row.split(','); if (columns.length !== 2) { throw new Error('unexpected number of columns'); } const quantity = parseInt(columns[1], 10); if (isNaN(quantity)) { throw new Error('invalid quantity'); } const itemQuantity = { item: columns[0], quantity: quantity, }; event.record.value = JSON.stringify(itemQuantity); writer.write(event.record); } } ``` 2. Build the transform into a Wasm binary: ```bash rpk transform build ``` 3. Create topics to apply the transform function to: ```bash rpk topic create input-topic output-topic ``` 4. Deploy the Wasm binary to your cluster. If you have already deployed another example, this new transform function will replace it. ```bash rpk transform deploy --input-topic=input-topic --output-topic=output-topic ``` 5. Produce CSV records to the input topic. ```bash echo "apples,10\npears,11\noranges,5" | rpk topic produce input-topic -k market-stock ``` 6. [Open Redpanda Console](http://localhost:8080/topics) and check the records in both the input topic and the output topic. You should see the following values: ```json { "item": "oranges", "quantity": 5 } { "item": "apples", "quantity": 10 } { "item": "pears", "quantity": 11 } ``` You can also verify the content of the output topic in the command-line: ```bash rpk topic consume output-topic ``` ### [](#validate-json)Validate JSON This example is a filter that outputs only valid JSON from the input topic into the output topic. Invalid JSON is written to a different output topic. 1. Paste this transform function into your source file: #### Go ```go import ( "encoding/json" "github.com/redpanda-data/redpanda/src/transform-sdk/go/transform" ) func main() { transform.OnRecordWritten(filterValidJson) } func filterValidJson(event transform.WriteEvent, writer transform.RecordWriter) error { if json.Valid(event.Record().Value) { return w.Write(e.Record()) } // Send invalid records to separate topic return writer.Write(e.Record(), transform.ToTopic("invalid-json")) } ``` #### Rust ```rust use anyhow::Result; use redpanda_transform_sdk::*; fn main() { on_record_written(filter_valid_json); } fn filter_valid_json(event: WriteEvent, writer: &mut RecordWriter) -> Result<()> { let value = event.record.value().unwrap_or_default(); if serde_json::from_slice::(value).is_ok() { writer.write(event.record)?; } else { // Send invalid records to separate topic writer.write_with_options(event.record, WriteOptions::to_topic("invalid-json"))?; } Ok(()) } ``` #### JavaScript The JavaScript SDK does not support writing records to a specific output topic. As a result, this transform function writes only valid JSON messages to the output topic. Invalid messages are logged, instead of written to a separate output topic. ```js import { onRecordWritten } from "@redpanda-data/transform-sdk"; onRecordWritten(filterValidJson); function filterValidJson(event, writer) { const recordValue = event.record.value.text(); if (isValidJson(recordValue)) { writer.write(event.record); } else { console.log('Invalid JSON detected') } } function isValidJson(str) { try { JSON.parse(str); return true; } catch (e) { return false; } } ``` 2. Build the transform into a Wasm binary: ```bash rpk transform build ``` 3. Create topics to apply the transform function to: ```bash rpk topic create input-topic output-topic invalid-json ``` 4. Deploy the Wasm binary to your cluster. If you have already deployed another example, this new transform function will replace it. ```bash rpk transform deploy --input-topic=input-topic --output-topic=output-topic --output-topic=invalid-json ``` 5. Produce an invalid JSON record a one valid one to the input topic. ```bash echo '{"valid":"json"}' | rpk topic produce input-topic -k json echo 'invalid json' | rpk topic produce input-topic -k json ``` 6. Verify the content of the output topic in the command-line: ```bash rpk topic consume output-topic ``` You should see only the valid JSON from the input topic. Invalid JSON messages are written to the `invalid-json` topic. ## [](#clean-up)Clean up Your transform function will continue processing new records in the input topic until you delete it. To delete the transform function: ```bash rpk transform delete data-transforms-tutorial --no-confirm ``` ## [](#suggested-reading)Suggested reading - [How Data Transforms Work](../how-transforms-work/) - [Golang SDK for Data Transforms](../../../reference/data-transforms/golang-sdk/) - [Rust SDK for Data Transforms](../../../reference/data-transforms/rust-sdk/) - [`rpk transform` commands](../../../reference/rpk/rpk-transform/rpk-transform/) ## Suggested labs - [Flatten JSON Messages](/redpanda-labs/data-transforms/flatten-go/) - [Convert JSON Messages into Avro](/redpanda-labs/data-transforms/issdemo-go/) - [Convert Timestamps using Rust](/redpanda-labs/data-transforms/ts-converter-rust/) - [Filter Messages into a New Topic using a Regex](/redpanda-labs/data-transforms/regex-go/) - [Redact Information in JSON Messages](/redpanda-labs/data-transforms/redaction-go/) [Search all labs](/redpanda-labs) --- # Page 72: Write Integration Tests for Transform Functions **URL**: https://docs.redpanda.com/current/develop/data-transforms/test.md --- # Write Integration Tests for Transform Functions --- title: Write Integration Tests for Transform Functions latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: data-transforms/test page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: data-transforms/test.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/develop/pages/data-transforms/test.adoc description: Learn how to write integration tests for data transform functions in Redpanda, including setting up unit tests and using testcontainers for integration tests. page-git-created-date: "2024-07-31" page-git-modified-date: "2025-04-08" support-status: supported --- Learn how to write integration tests for data transform functions in Redpanda, including setting up unit tests and using testcontainers for integration tests. This guide covers how to write both unit tests and integration tests for your transform functions. While unit tests focus on testing individual components in isolation, integration tests verify that the components work together as expected in a real environment. ## [](#unit-tests)Unit tests You can create unit tests for transform functions by mocking the interfaces injected into the transform function and asserting that the input and output work correctly. This typically includes mocking the `WriteEvent` and `RecordWriter` interfaces. ```go package main import ( "testing" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/mock" "github.com/redpanda-data/redpanda/src/transform-sdk/go/transform" ) // MockWriteEvent is a mock implementation of the WriteEvent interface. type MockWriteEvent struct { mock.Mock } func (m *MockWriteEvent) Record() transform.Record { args := m.Called() return args.Get(0).(transform.Record) } // MockRecordWriter is a mock implementation of the RecordWriter interface. type MockRecordWriter struct { mock.Mock } func (m *MockRecordWriter) Write(record transform.Record) error { args := m.Called(record) return args.Error(0) } // copyRecord copies the record to the output topic. func copyRecord(event transform.WriteEvent, writer transform.RecordWriter) error { record := event.Record() return writer.Write(record) } // TestCopyRecord tests the copyRecord function. func TestCopyRecord(t *testing.T) { // Create mocks for the WriteEvent and RecordWriter event := new(MockWriteEvent) writer := new(MockRecordWriter) // Set up the expected behavior record := transform.Record{Value: []byte("test")} event.On("Record").Return(record) writer.On("Write", record).Return(nil) // Call the function under test err := copyRecord(event, writer) // Assert that no error occurred and that the expectations were met assert.NoError(t, err) event.AssertExpectations(t) writer.AssertExpectations(t) } ``` To run your unit tests, use the following command: ```bash go test ``` This will execute all tests in the current directory. ## [](#integration-tests)Integration tests Integration tests verify that your transform functions work correctly in a real Redpanda environment. You can use [testcontainers](https://github.com/testcontainers/testcontainers-go/tree/main) to set up and manage a Redpanda instance for testing. For more detailed examples and helper code for setting up integration tests, refer to the SDK integration tests on [GitHub](https://github.com/redpanda-data/redpanda/tree/dev/src/transform-sdk/tests). --- # Page 73: Upgrade the Data Transforms SDK **URL**: https://docs.redpanda.com/current/develop/data-transforms/upgrade.md --- # Upgrade the Data Transforms SDK --- title: Upgrade the Data Transforms SDK latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: data-transforms/upgrade page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: data-transforms/upgrade.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/develop/pages/data-transforms/upgrade.adoc description: Upgrading the SDK version in your data transforms project ensures compatibility with the latest features and fixes. This guide provides step-by-step instructions to upgrade the SDK version for all supported SDK languages. page-git-created-date: "2024-07-31" page-git-modified-date: "2024-08-01" support-status: supported --- Upgrading the SDK version in your data transforms project ensures compatibility with the latest features and fixes. This guide provides step-by-step instructions to upgrade the SDK version for all supported SDK languages. ## [](#prerequisites)Prerequisites Before upgrading, check the [compatibility matrix](../versioning-compatibility/) to ensure the new SDK version is compatible with your Redpanda version. ## [](#upgrade-your-local-sdk-version)Upgrade your local SDK version ### Go 1. Open your project’s root directory. 2. Run the following command to update the SDK: ```bash go get github.com/redpanda-data/redpanda/src/transform-sdk/go/transform@v ``` 3. Clean up the `go.mod` and `go.sum` files: ```bash go mod tidy ``` ### Rust 1. Open the `Cargo.toml` file in your project’s root directory. This file specifies the dependencies for your Rust project. 2. Locate the line that specifies the Redpanda SDK version. It will look something like this: ```toml [dependencies] redpanda-transform-sdk = "" ``` 3. Change the version to the one you want to upgrade to. 4. Run the following command to update the dependencies: ```bash cargo update -p redpanda-transform-sdk ``` ### JavaScript 1. Open the `package.json` file in your project’s root directory. 2. Locate the line that specifies the data transforms SDK version. It will look something like this: ```json { "dependencies": { "@redpanda-data/transform-sdk": "" }, } ``` 3. Run the following command to update the SDK: ```bash npm install --save @redpanda-data/transform-sdk@ ``` 4. Verify the update by checking the `package.json` file, the `package-lock.json` file, and the `node_modules/` directory. ## [](#next-steps)Next steps Run your [tests](../test/) to ensure everything works correctly with the new SDK version. --- # Page 74: Versioning and Compatibility for Data Transforms **URL**: https://docs.redpanda.com/current/develop/data-transforms/versioning-compatibility.md --- # Versioning and Compatibility for Data Transforms --- title: Versioning and Compatibility for Data Transforms latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: data-transforms/versioning-compatibility page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: data-transforms/versioning-compatibility.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/develop/pages/data-transforms/versioning-compatibility.adoc description: The data transforms SDKs use semantic versioning to ensure compatibility and stability. Use this guide to learn the SDKs that are compatible with different versions of Redpanda, and what guarantees are provided regarding SDK and Redpanda compatibility. page-git-created-date: "2024-07-31" page-git-modified-date: "2024-08-07" support-status: supported --- The data transforms SDKs use semantic versioning to ensure compatibility and stability. Use this guide to learn the SDKs that are compatible with different versions of Redpanda, and what guarantees are provided regarding SDK and Redpanda compatibility. ## [](#semantic-versioning)Semantic versioning The data transforms SDKs use semantic versioning, which is a versioning scheme with a three-part number: `major.minor.patch`. When a new version is released, one part of the version number is changed. The changed part of the version number signifies the level of change: - **Major**: Indicate breaking changes. - **Minor**: Indicate backward-compatible functionality. - **Patch**: Indicate backward-compatible bug fixes. For example, in the version number `1.2.3`, `1` is the major version, `2` is the minor version, and `3` is the patch version. ## [](#compatibility-matrix)Compatibility matrix This compatibility matrix provides detailed information on which versions of the SDK are supported with which versions of Redpanda. Always consult the compatibility matrix to ensure that you are using compatible versions. SDK versions are backwards-compatible and will continue to be supported in newer versions of Redpanda. However, newer SDK versions may not work with older versions of Redpanda. Always check this compatibility matrix when upgrading the SDK or Redpanda. ### [](#golang-sdk)Golang SDK | SDK version | Redpanda version | | --- | --- | | 1.1.x | 24.2.x | | 1.0.x | 24.2.x, 24.1.x, 23.3.x | ### [](#rust-sdk)Rust SDK | SDK version | Redpanda version | | --- | --- | | 1.1.x | 24.2.x | | 1.0.x | 24.2.x, 24.1.x, 23.3.x | ### [](#javascript-sdk)JavaScript SDK | SDK version | Redpanda version | | --- | --- | | 1.1.x | 24.2.x | | 1.0.x | 24.2.x, 24.1.x, 23.3.x | ## [](#best-practices)Best practices - **Stay updated**: Regularly check the [release notes](#rn) for updates to both the data transform SDK and Redpanda. Ensure that you are using compatible versions as specified in the [compatibility matrix](#matrix). - **Test upgrades**: Before upgrading either the SDK or Redpanda, test the upgrade in a staging environment. This helps ensure that your data transforms continue to work as expected. - **Monitor logs and metrics**: Watch the logs and metrics to catch any issues early. Ensure that you [set up monitoring and alerting](../monitor/) to notify you of any problems with your data transforms. ## [](#rn)Release notes Release notes for SDK versions are included in the Redpanda release notes. This ensures that all changes related to data transforms and SDKs are documented in one place. To view the release notes: 1. Visit the [Redpanda GitHub releases page](https://github.com/redpanda-data/redpanda/releases). 2. Search for the term `wasm` to filter the release notes for relevant updates to the data transform SDKs. ## [](#suggested-reading)Suggested reading - [Upgrade the Data Transforms SDK](../upgrade/) - [Golang SDK for Data Transforms](../../../reference/data-transforms/golang-sdk/) - [Rust SDK for Data Transforms](../../../reference/data-transforms/rust-sdk/) --- # Page 75: Use Redpanda with the HTTP Proxy API **URL**: https://docs.redpanda.com/current/develop/http-proxy.md --- # Use Redpanda with the HTTP Proxy API --- title: Use Redpanda with the HTTP Proxy API latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: http-proxy page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: http-proxy.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/develop/pages/http-proxy.adoc description: HTTP Proxy exposes a REST API to list topics, produce events, and subscribe to events from topics using consumer groups. page-git-created-date: "2023-05-30" page-git-modified-date: "2025-05-07" support-status: supported --- Redpanda HTTP Proxy (`pandaproxy`) allows access to your data through a REST API. For example, you can list topics or brokers, get events, produce events, subscribe to events from topics using consumer groups, and commit offsets for a consumer. See the [HTTP Proxy API reference](/api/doc/http-proxy/) for a full list of available endpoints. ## [](#prerequisites)Prerequisites ### [](#start-redpanda)Start Redpanda The first step is to start up Redpanda. HTTP Proxy is enabled by default on port 8082. To change the proxy port, edit `redpanda.yaml`: #### redpanda.yaml ```yaml ... pandaproxy: pandaproxy_api: - address: 0.0.0.0 port: 8082 ... ``` #### Kubernetes Cluster Resource ```yaml apiVersion: redpanda.vectorized.io/v1alpha1 kind: Cluster ... spec: ... resources: pandaproxyApi: - port: 8082 ... ``` > 📝 **NOTE** > > The remainder of this guide is based on the assumption that the HTTP Proxy port is 8082. ## [](#authenticate-with-http-proxy)Authenticate with HTTP Proxy HTTP Proxy supports authentication using SCRAM credentials or OIDC tokens. The authentication method depends on the [`authentication_method`](../../reference/properties/broker-properties/#http_proxy_auth_method) broker property and the cluster’s [`http_authentication`](../../reference/properties/cluster-properties/#http_authentication) settings. ### [](#scram-authentication)SCRAM Authentication If HTTP Proxy is configured to support SASL, you can provide the SCRAM username and password as part of the Basic Authentication header in your request. For example, to list topics as an authenticated user: #### curl ```bash curl -s -u ":" "http://:8082/topics" ``` #### NodeJS ```javascript let options = { auth: { username: "", password: "" }, }; axios .get("http://:8082/topics", options) .then(response => console.log(response.data)) .catch(error => console.error(error)); ``` #### Python ```python auth = ("", "") res = requests.get("http://:8082/topics", auth=auth).json() pretty(res) ``` ### [](#oidc-authentication)OIDC Authentication If HTTP Proxy is configured to support OIDC, you can provide an OIDC token in the Authorization header. For example: #### curl ```bash curl -s -H "Authorization: Bearer " "http://:8082/topics" ``` #### NodeJS ```javascript let options = { headers: { Authorization: `Bearer ` }, }; axios .get("http://:8082/topics", options) .then(response => console.log(response.data)) .catch(error => console.error(error)); ``` #### Python ```python headers = {"Authorization": "Bearer "} res = requests.get("http://:8082/topics", headers=headers).json() pretty(res) ``` For details about configuring OIDC authentication, see [OIDC Authentication](../../manage/security/authentication/#oidc-http). ## [](#set-up-libraries)Set up libraries You need an app that calls the HTTP Proxy endpoint. This app can be curl (or a similar CLI), or it could be your own custom app written in any language. Below are curl, JavaScript and Python examples. > 📝 **NOTE** > > In the examples, `` refers to your Redpanda cluster’s hostname or IP address. All following examples use a `base_uri` variable that combines the protocol, host, and port for consistency across curl, JavaScript, and Python examples. ### curl Curl is likely already installed on your system. If not, see [curl download instructions](https://curl.se/download.html). Set the base URI for your HTTP Proxy: ```bash base_uri="http://:8082" ``` ### NodeJS > 📝 **NOTE** > > This is based on the assumption that you’re in the root directory of an existing NodeJS project. See [Build a Chat Room Application with Redpanda and Node.js](../../../redpanda-labs/clients/docker-nodejs/) for an example of a NodeJS project. In a terminal window, run: ```bash npm install axios ``` Import the library into your code: ```javascript const axios = require('axios'); const base_uri = 'http://:8082'; ``` ### Python In a terminal window, run: ```bash pip install requests ``` Import the library into your code: ```python import requests import json def pretty(text): print(json.dumps(text, indent=2)) base_uri = "http://:8082" ``` ## [](#create-a-topic)Create a topic To create a test topic for this guide, use [`rpk`](../../get-started/rpk-install/). You can configure `rpk` for your Redpanda deployment, using [profiles](../../get-started/config-rpk-profile/), flags, or [environment variables](../../reference/rpk/rpk-x-options/#environment-variables). To create a topic named `test_topic` with three partitions, run: ```bash rpk topic create test_topic -p 3 ``` For more information, see the [rpk topic create](../../reference/rpk/rpk-topic/rpk-topic-create/) reference. ## [](#access-your-data)Access your data Here are some sample commands to produce and consume streams: ### [](#get-list-of-topics)Get list of topics #### curl ```bash curl -s "$base_uri/topics" ``` #### NodeJS ```javascript axios .get(`${base_uri}/topics`) .then(response => console.log(response.data)) .catch(error => console.error(error)); ``` Run the application. If your file name is `index.js` for example, you would run the following command: ```bash node index.js ``` #### Python ```python res = requests.get(f"{base_uri}/topics").json() pretty(res) ``` Expected output: ```bash ["test_topic"] ``` ### [](#send-events-to-a-topic)Send events to a topic Use POST to send events in the REST endpoint query. The header must include the following line: Content-Type:application/vnd.kafka.json.v2+json The following commands show how to send events to `test_topic`: #### curl ```bash curl -s \ -X POST \ "$base_uri/topics/test_topic" \ -H "Content-Type: application/vnd.kafka.json.v2+json" \ -d '{ "records":[ { "value":"Redpanda", "partition":0 }, { "value":"HTTP proxy", "partition":1 }, { "value":"Test event", "partition":2 } ] }' ``` #### NodeJS ```javascript let payload = { records: [ { "value":"Redpanda", "partition": 0 }, { "value":"HTTP proxy", "partition": 1 }, { "value":"Test event", "partition": 2 } ]}; let options = { headers: { "Content-Type" : "application/vnd.kafka.json.v2+json" }}; axios .post(`${base_uri}/topics/test_topic`, payload, options) .then(response => console.log(response.data)) .catch(error => console.error(error)); ``` Run the application: ```bash node index.js ``` #### Python ```python res = requests.post( url=f"{base_uri}/topics/test_topic", data=json.dumps( dict(records=[ dict(value="Redpanda", partition=0), dict(value="HTTP Proxy", partition=1), dict(value="Test Event", partition=2) ])), headers={"Content-Type": "application/vnd.kafka.json.v2+json"}).json() pretty(res) ``` Expected output (may be formatted differently depending on the chosen application): ```bash {"offsets":[{"partition":0,"offset":0},{"partition":2,"offset":0},{"partition":1,"offset":0}]} ``` ### [](#get-events-from-a-topic)Get events from a topic After events have been sent to the topic, you can retrieve these same events. #### curl ```bash curl -s \ "$base_uri/topics/test_topic/partitions/0/records?offset=0&timeout=1000&max_bytes=100000"\ -H "Accept: application/vnd.kafka.json.v2+json" ``` #### NodeJS ```javascript let options = { headers: { accept: "application/vnd.kafka.json.v2+json" }, params: { offset: 0, timeout: "1000", max_bytes: "100000", }, }; axios .get(`${base_uri}/topics/test_topic/partitions/0/records`, options) .then(response => console.log(response.data)) .catch(error => console.error(error)); ``` Run the application: ```bash node index.js ``` #### Python ```python res = requests.get( url=f"{base_uri}/topics/test_topic/partitions/0/records", params={"offset": 0, "timeout":1000,"max_bytes":100000}, headers={"Accept": "application/vnd.kafka.json.v2+json"}).json() pretty(res) ``` Expected output: ```bash [{"topic":"test_topic","key":null,"value":"Redpanda","partition":0,"offset":0}] ``` ### [](#get-list-of-brokers)Get list of brokers #### curl ```bash curl "$base_uri/brokers" ``` #### NodeJS ```javascript axios .get(`${base_uri}/brokers`) .then(response => console.log(response.data)) .catch(error => console.error(error)); ``` #### Python ```python res = requests.get(f"{base_uri}/brokers").json() pretty(res) ``` Expected output: ```bash {brokers: [0]} ``` ### [](#create-a-consumer)Create a consumer To retrieve events from a topic using consumers, you must create a consumer and a consumer group, and then subscribe the consumer instance to a topic. Each action involves a different endpoint and method. The first endpoint is: `/consumers/`. For this REST call, the payload is the group information. #### curl ```bash curl -s \ -X POST \ "$base_uri/consumers/test_group" \ -H "Content-Type: application/vnd.kafka.v2+json" \ -d '{ "format":"json", "name":"test_consumer", "auto.offset.reset":"earliest", "auto.commit.enable":"false", "fetch.min.bytes": "1", "consumer.request.timeout.ms": "10000" }' ``` #### NodeJS ```javascript let payload = { "name": "test_consumer", "format": "json", "auto.offset.reset": "earliest", "auto.commit.enable": "false", "fetch.min.bytes": "1", "consumer.request.timeout.ms": "10000" }; let options = { headers: { "Content-Type": "application/vnd.kafka.v2+json" }}; axios .post(`${base_uri}/consumers/test_group`, payload, options) .then(response => console.log(response.data)) .catch(error => console.error(error)); ``` Run the application: ```bash node index.js ``` #### Python ```python res = requests.post( url=f"{base_uri}/consumers/test_group", data=json.dumps({ "name": "test_consumer", "format": "json", "auto.offset.reset": "earliest", "auto.commit.enable": "false", "fetch.min.bytes": "1", "consumer.request.timeout.ms": "10000" }), headers={"Content-Type": "application/vnd.kafka.v2+json"}).json() pretty(res) ``` Expected output: ```bash {"instance_id":"test_consumer","base_uri":"http://127.0.0.1:8082/consumers/test_group/instances/test_consumer"} ``` > 📝 **NOTE** > > - Consumers expire after five minutes of inactivity. To prevent this from happening, try consuming events within a loop. If the consumer has expired, you can create a new one with the same name. > > - The output `base_uri` is the full URL path for this specific consumer instance and differs from the `base_uri` variable used in the code examples. ### [](#subscribe-to-the-topic)Subscribe to the topic After creating the consumer, subscribe to the topic that you created. #### curl ```bash curl -s -o /dev/null -w "%{http_code}" \ -X POST \ "$base_uri/consumers/test_group/instances/test_consumer/subscription"\ -H "Content-Type: application/vnd.kafka.v2+json" \ -d '{ "topics": [ "test_topic" ] }' ``` #### NodeJS ```javascript let payload = { topics: ["test_topic"]}; let options = { headers: { "Content-Type": "application/vnd.kafka.v2+json" }}; axios .post(`${base_uri}/consumers/test_group/instances/test_consumer/subscription`, payload, options) .then(response => console.log(response.data)) .catch(error => console.error(error)); ``` Run the application: ```bash node index.js ``` #### Python ```python res = requests.post( url=f"{base_uri}/consumers/test_group/instances/test_consumer/subscription", data=json.dumps({"topics": ["test_topic"]}), headers={"Content-Type": "application/vnd.kafka.v2+json"}) ``` Expected response is an HTTP 204, without a body. Now you can get the events from `test_topic`. ### [](#retrieve-events)Retrieve events Retrieve the events from the topic: #### curl ```bash curl -s \ "$base_uri/consumers/test_group/instances/test_consumer/records?timeout=1000&max_bytes=100000"\ -H "Accept: application/vnd.kafka.json.v2+json" ``` #### NodeJS ```javascript let options = { headers: { Accept: "application/vnd.kafka.json.v2+json" }, params: { timeout: "1000", max_bytes: "100000", }, }; axios .get(`${base_uri}/consumers/test_group/instances/test_consumer/records`, options) .then(response => console.log(response.data)) .catch(error => console.error(error)); ``` Run the application: ```bash node index.js ``` #### Python ```python res = requests.get( url=f"{base_uri}/consumers/test_group/instances/test_consumer/records", params={"timeout":1000,"max_bytes":100000}, headers={"Accept": "application/vnd.kafka.json.v2+json"}).json() pretty(res) ``` Expected output: ```bash [{"topic":"test_topic","key":null,"value":"Redpanda","partition":0,"offset":0},{"topic":"test_topic","key":null,"value":"HTTP proxy","partition":1,"offset":0},{"topic":"test_topic","key":null,"value":"Test event","partition":2,"offset":0}] ``` ### [](#get-offsets-from-consumer)Get offsets from consumer #### curl ```bash curl -s \ -X 'GET' \ curl -s -o /dev/null -w "%{http_code}" \ -X 'POST' \ "$base_uri/consumers/test_group/instances/test_consumer/offsets" \ -H 'accept: application/vnd.kafka.v2+json' \ -H 'accept: application/vnd.kafka.v2+json' \ -H 'Content-Type: application/vnd.kafka.v2+json' \ -d '{ "partitions": [ { "topic": "test_topic", "partition": 0 }, { "topic": "test_topic", "partition": 1 }, { "topic": "test_topic", "partition": 2 } ] }' ``` #### Python ```python res = requests.get( url=f"{base_uri}/consumers/test_group/instances/test_consumer/offsets", data=json.dumps( dict(partitions=[ dict(topic="test_topic", partition=p) for p in [0, 1, 2] ])), headers={"Content-Type": "application/vnd.kafka.v2+json"}).json() pretty(res) ``` Expected output: ```bash { "offsets": [{ "topic": "test_topic", "partition": 0, "offset": 0, "metadata": "" },{ "topic": "test_topic", "partition": 1, "offset": 0, "metadata": "" }, { "topic": "test_topic", "partition": 2, "offset": 0, "metadata": "" }] } ``` ### [](#commit-offsets-for-consumer)Commit offsets for consumer After events have been handled by a consumer, the offsets can be committed, so that the consumer group won’t retrieve them again. #### curl ```bash curl -s -o /dev/null -w "%{http_code}" \ -X 'POST' \ "$base_uri/consumers/test_group/instances/test_consumer/offsets" \ -H 'accept: application/vnd.kafka.v2+json' \ -H 'Content-Type: application/vnd.kafka.v2+json' \ -d '{ "partitions": [ { "topic": "test_topic", "partition": 0, "offset": 0 }, { "topic": "test_topic", "partition": 1, "offset": 0 }, { "topic": "test_topic", "partition": 2, "offset": 0 } ] }' ``` #### NodeJS ```javascript let options = { headers: { accept: "application/vnd.kafka.v2+json", "Content-Type": "application/vnd.kafka.v2+json", } }; let payload = { partitions: [ { topic: "test_topic", partition: 0, offset: 0 }, { topic: "test_topic", partition: 1, offset: 0 }, { topic: "test_topic", partition: 2, offset: 0 }, ]}; axios .post(`${base_uri}/consumers/test_group/instances/test_consumer/offsets`, payload, options) .then(response => console.log(response.data)) .catch(error => console.error(error)); ``` Run the application: ```bash node index.js ``` #### Python ```python res = requests.post( url=f"{base_uri}/consumers/test_group/instances/test_consumer/offsets", data=json.dumps( dict(partitions=[ dict(topic="test_topic", partition=p, offset=0) for p in [0, 1, 2] ])), headers={"Content-Type": "application/vnd.kafka.v2+json"}) ``` Expected output: none. ### [](#delete-a-consumer)Delete a consumer To remove a consumer from a group, send a DELETE request as shown below: #### curl ```bash curl -s -o /dev/null -w "%{http_code}" \ -X 'DELETE' \ "$base_uri/consumers/test_group/instances/test_consumer" \ -H 'Content-Type: application/vnd.kafka.v2+json' ``` #### NodeJS ```javascript let options = { headers: { "Content-Type": "application/vnd.kafka.v2+json" }}; axios .delete(`${base_uri}/consumers/test_group/instances/test_consumer`, options) .then(response => console.log(response.data)) .catch(error => console.error(error)); ``` #### Python ```python res = requests.delete( url=f"{base_uri}/consumers/test_group/instances/test_consumer", headers={"Content-Type": "application/vnd.kafka.v2+json"}) ``` ## [](#authenticate-with-http-proxy-2)Authenticate with HTTP Proxy HTTP Proxy supports authentication using SCRAM credentials or OIDC tokens. The authentication method depends on the [`authentication_method`](../../reference/properties/broker-properties/#http_proxy_auth_method) broker property and the cluster’s [`http_authentication`](../../reference/properties/cluster-properties/#http_authentication) settings. ### [](#scram-authentication-2)SCRAM Authentication If HTTP Proxy is configured to support SASL, you can provide the SCRAM username and password as part of the Basic Authentication header in your request. For example, to list topics as an authenticated user: #### curl ```bash curl -s -u ":" ":8082/topics" ``` #### NodeJS ```javascript let options = { auth: { username: "", password: "" }, }; axios .get(`${base_uri}/topics`, options) .then(response => console.log(response.data)) .catch(error => console.error(error)); ``` #### Python ```python auth = ("", "") res = requests.get(f"{base_uri}/topics", auth=auth).json() pretty(res) ``` ### [](#oidc-authentication-2)OIDC Authentication If HTTP Proxy is configured to support OIDC, you can provide an OIDC token in the Authorization header. For example: #### curl ```bash curl -s -H "Authorization: Bearer " ":8082/topics" ``` #### NodeJS ```javascript let options = { headers: { Authorization: `Bearer ` }, }; axios .get(`${base_uri}/topics`, options) .then(response => console.log(response.data)) .catch(error => console.error(error)); ``` #### Python ```python headers = {"Authorization": "Bearer "} res = requests.get(f"{base_uri}/topics", headers=headers).json() pretty(res) ``` For details about configuring OIDC authentication, see [OIDC Authentication](../../manage/security/authentication/#oidc-http). ## [](#generate-a-security-report-for-http-proxy)Generate a security report for HTTP Proxy Use the [`/v1/security/report`](/api/doc/admin/operation/operation-get_security_report) Admin API endpoint to generate a comprehensive security report for your cluster. This endpoint provides detailed information about TLS configuration, authentication methods, authorization status, and security alerts across all Redpanda interfaces, including HTTP Proxy. Input ```bash curl 'http://localhost:9644/v1/security/report' ``` View output ```bash { "interfaces": { "kafka": [ { "name": "test_kafka_listener", "host": "0.0.0.0", "port": 9092, "advertised_host": "0.0.0.0", "advertised_port": 9092, "tls_enabled": false, "mutual_tls_enabled": false, "authentication_method": "None", "authorization_enabled": false } ], "rpc": { "host": "0.0.0.0", "port": 33145, "advertised_host": "127.0.0.1", "advertised_port": 33145, "tls_enabled": false, "mutual_tls_enabled": false }, "admin": [ { "name": "test_admin_listener", "host": "0.0.0.0", "port": 9644, "tls_enabled": false, "mutual_tls_enabled": false, "authentication_methods": [], "authorization_enabled": false } ] }, "alerts": [ { "affected_interface": "kafka", "listener_name": "test_kafka_listener", "issue": "NO_TLS", "description": "\"kafka\" interface \"test_kafka_listener\" is not using TLS. This is insecure and not recommended." }, { "affected_interface": "kafka", "listener_name": "test_kafka_listener", "issue": "NO_AUTHN", "description": "\"kafka\" interface \"test_kafka_listener\" is not using authentication. This is insecure and not recommended." }, { "affected_interface": "kafka", "listener_name": "test_kafka_listener", "issue": "NO_AUTHZ", "description": "\"kafka\" interface \"test_kafka_listener\" is not using authorization. This is insecure and not recommended." }, { "affected_interface": "rpc", "issue": "NO_TLS", "description": "\"rpc\" interface is not using TLS. This is insecure and not recommended." }, { "affected_interface": "admin", "listener_name": "test_admin_listener", "issue": "NO_TLS", "description": "\"admin\" interface \"test_admin_listener\" is not using TLS. This is insecure and not recommended." }, { "affected_interface": "admin", "listener_name": "test_admin_listener", "issue": "NO_AUTHZ", "description": "\"admin\" interface \"test_admin_listener\" is not using authorization. This is insecure and not recommended." }, { "affected_interface": "admin", "listener_name": "test_admin_listener", "issue": "NO_AUTHN", "description": "\"admin\" interface \"test_admin_listener\" is not using authentication. This is insecure and not recommended." } ] } ``` ## [](#use-swagger-with-http-proxy)Use Swagger with HTTP Proxy You can use Swagger UI to test and interact with Redpanda HTTP Proxy endpoints. Use Docker to start Swagger UI: ```bash docker run -p 80:8080 -d swaggerapi/swagger-ui ``` Verify that the Swagger container is available: ```bash docker ps ``` Verify that the Docker container has been added and is running: `swaggerapi/swagger-ui` with `Up…` status In a browser, enter `` in the address bar to open the Swagger console. Change the URL to `[http://:8082/v1](http://:8082/v1)`, and click `Explore` to update the page with Redpanda HTTP Proxy endpoints. You can call the endpoints in any application and language that supports web interactions. ## Suggested labs - [Stream Stock Market Data from a CSV file Using Node.js](/redpanda-labs/clients/stock-market-activity-nodejs/) - [Stream Stock Market Data from a CSV file Using Python](/redpanda-labs/clients/stock-market-activity-python/) - [Build a Chat Room Application with Redpanda and Java](/redpanda-labs/clients/docker-java/) - [Build a Chat Room Application with Redpanda and Golang](/redpanda-labs/clients/docker-go/) - [Build a Chat Room Application with Redpanda and Node.js](/redpanda-labs/clients/docker-nodejs/) - [Build a Chat Room Application with Redpanda and Python](/redpanda-labs/clients/docker-python/) - [Build a Chat Room Application with Redpanda and Rust](/redpanda-labs/clients/docker-rust/) See more [Search all labs](/redpanda-labs) --- # Page 76: Kafka Compatibility **URL**: https://docs.redpanda.com/current/develop/kafka-clients.md --- # Kafka Compatibility --- title: Kafka Compatibility latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kafka-clients page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kafka-clients.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/develop/pages/kafka-clients.adoc description: Kafka clients, version 0.11 or later, are compatible with Redpanda. Validations and exceptions are listed. page-git-created-date: "2023-05-30" page-git-modified-date: "2026-03-31" support-status: supported --- Redpanda is compatible with Apache Kafka versions 0.11 and later, with specific exceptions noted on this page. ## [](#kafka-client-compatibility)Kafka client compatibility Clients developed for Kafka versions 0.11 or later are compatible with Redpanda. Modern clients auto-negotiate protocol versions or use an earlier protocol version accepted by Redpanda brokers. > 💡 **TIP** > > Redpanda Data recommends always using the latest supported version of a client. The following clients have been validated with Redpanda. | Language | Client | | --- | --- | | Java | Apache Kafka Java Client | | C/C++ | librdkafka | | Go | franz-go | | Python | kafka-python-ng | | Rust | kafka-rust | | Node.js | KafkaJSconfluent-kafka-javascript | Clients that have not been validated by Redpanda Data, but use the Kafka protocol, remain compatible with Redpanda subject to the limitations below (particularly those based on librdkafka, such as confluent-kafka-dotnet or confluent-python). If you find a client that is not supported, reach out to the Redpanda team in the community [Slack](https://redpanda.com/slack). ## [](#unsupported-kafka-features)Unsupported Kafka features Redpanda does not currently support the following Apache Kafka features: - Multiple SCRAM mechanisms simultaneously for SASL users; for example, a user having both a `SCRAM-SHA-256` and a `SCRAM-SHA-512` credential. Redpanda supports only one SASL/SCRAM mechanism per user, either `SCRAM-SHA-256` or `SCRAM-SHA-512`. See the [Configure Authentication](../../manage/security/authentication/#sasl) guide for details. - HTTP Proxy (pandaproxy): Unlike other REST proxy implementations in the Kafka ecosystem, Redpanda HTTP Proxy does not support topic and ACLs CRUD through the HTTP Proxy. HTTP Proxy is designed for clients producing and consuming data that do not perform administrative functions. - Quotas per user for bandwidth and API request rates. However, [quotas per client and per client group](../../manage/cluster-maintenance/manage-throughput/#client-throughput-limits) using AlterClientQuotas and DescribeClientQuotas APIs are supported. If you have any issues while working with a Kafka tool, you can [file an issue](https://github.com/redpanda-data/redpanda/issues/new). --- # Page 77: Topics **URL**: https://docs.redpanda.com/current/develop/manage-topics.md --- # Topics --- title: Topics latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: manage-topics/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: manage-topics/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/develop/pages/manage-topics/index.adoc description: Learn how to manage topics in Redpanda, including creation, configuration, and advanced features. page-git-created-date: "2026-03-31" page-git-modified-date: "2026-03-31" support-status: supported --- - [Manage Topics](config-topics/) Learn how to create topics, update topic configurations, and delete topics or records. - [Manage Cloud Topics](cloud-topics/) Cloud Topics are "diskless" Redpanda topics that enable you to store data directly to object storage to trade off latency for lower costs. --- # Page 78: Manage Cloud Topics **URL**: https://docs.redpanda.com/current/develop/manage-topics/cloud-topics.md --- # Manage Cloud Topics --- title: Manage Cloud Topics latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: manage-topics/cloud-topics page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: manage-topics/cloud-topics.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/develop/pages/manage-topics/cloud-topics.adoc description: Cloud Topics are "diskless" Redpanda topics that enable you to store data directly to object storage to trade off latency for lower costs. page-topic-type: how-to personas: streaming_developer, platform_admin learning-objective-1: Describe the latency and cost trade-offs of Cloud Topics compared to standard Redpanda topics learning-objective-2: Create a Cloud Topic using rpk after enabling Cloud Topics on your cluster learning-objective-3: Identify Cloud Topics limitations and configurations that reduce cross-AZ networking costs page-git-created-date: "2026-03-31" page-git-modified-date: "2026-03-31" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../get-started/licensing/#self-managed) apply. Starting in v26.1, Redpanda provides [Cloud Topics](https://docs.redpanda.com/current/reference/glossary/#cloud-topic) to support multi-modal streaming workloads in the most cost-effective way possible: as a per-topic configuration running mixed latency workloads. While standard Redpanda [topics](../config-topics/) that use local storage or Tiered Storage are ideal for latency-sensitive workloads (for example, for audit logs or analytics), Cloud Topics are optimized for latency-tolerant, high-throughput workloads where cross-AZ networking charges are a major consideration that can become the dominant cost driver at high throughput. These workloads can include observability streams, offline analytics, AI/ML model training data feeds, or development environments that have flexible latency requirements. Instead of replicating every byte across expensive network links, Cloud Topics leverage durable, inexpensive cloud storage (S3, ADLS, GCS, MinIO) as the primary mechanism to both replicate data and serve it to consumers. This eliminates over 90% of the cost of replicating data over network links in multi-AZ clusters. The end-to-end latency experienced when using Cloud Topics can range from 500 ms to as high as a few seconds with different object stores. Lower latencies may be achievable in certain environments, but Cloud Topics is optimized for throughput rather than low latency or tightly constrained tail latency. This latency profile is often acceptable for many streaming workloads, and can unlock new streaming use cases that previously were not cost effective. With Cloud Topics, data from the client is not acknowledged until it is uploaded to object storage. This maintains durability in the face of infrastructure failures, but results in an increase in both produce latency and end-to-end latency, driven by both batching of produced data and the inherent latency of the underlying object store. You should generally expect end-to-end latencies of 1-2 seconds with public cloud stores. ## [](#prerequisites)Prerequisites - [Install or Update rpk](../../../get-started/rpk-install/) v26.1 or later. - [Enable cloud storage](../../../manage/tiered-storage/#set-up-tiered-storage) on your Redpanda cluster. > 📝 **NOTE** > > If you plan to use Cloud Topics for all new topics in a Redpanda cluster, be sure to set the following cluster-level property: > > ```bash > default_redpanda_storage_mode=cloud > ``` > > This ensures that newly-created Redpanda topics are Cloud Topics by default. For details, see [Enable Tiered Storage for a cluster](../../../manage/tiered-storage/#enable-tiered-storage-for-a-cluster). - [Configure object storage](../../../manage/tiered-storage/#configure-object-storage). - Ensure that you have an Enterprise license. To check your license status, run: ```bash rpk cluster license info ``` ## [](#limitations)Limitations - Shadow links do not currently support Cloud Topics. - Once created, a Cloud Topic cannot be converted back to a standard Redpanda topic that uses local or Tiered Storage. Conversely, existing topics created as local or Tiered Storage topics cannot be converted to Cloud Topics. ## [](#enable-cloud-topics)Enable Cloud Topics To enable Cloud Topics for a cluster: ```bash rpk cluster config set cloud_topics_enabled=true ``` > 📝 **NOTE** > > This configuration update requires a restart to take effect. After enabling Cloud Topics, you can proceed to create new Cloud Topics: ```bash rpk topic create -c redpanda.storage.mode=cloud ``` ```console TOPIC STATUS audit.analytics.may2025 OK ``` You can make a topic a Cloud Topic only at topic creation time. In addition to replication, cross-AZ ingress (producer) and egress (consumer) traffic can also contribute substantially to cloud networking costs. When running multi-AZ clusters in general, Redpanda strongly recommends using [Follower Fetching](../../consume-data/follower-fetching/), which allows consumers to avoid crossing network zones. When possible, you can use [leader pinning](../../produce-data/leader-pinning/), which positions a topic’s partition leader close to the producers, providing a similar benefit for ingress traffic. These features can add additional savings to the replication cost savings of Cloud Topics. --- # Page 79: Manage Topics **URL**: https://docs.redpanda.com/current/develop/manage-topics/config-topics.md --- # Manage Topics --- title: Manage Topics latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: manage-topics/config-topics page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: manage-topics/config-topics.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/develop/pages/manage-topics/config-topics.adoc description: Learn how to create topics, update topic configurations, and delete topics or records. page-git-created-date: "2026-03-31" page-git-modified-date: "2026-04-08" support-status: supported --- Topics provide a way to organize events in a data streaming platform. When you create a topic, the default cluster-level topic configurations are applied using the cluster configuration file, unless you specify different configurations. The following table shows the default cluster-level properties and their equivalent topic-level properties: | Cluster property | Default | Topic property | | --- | --- | --- | | log_cleanup_policy | delete | cleanup.policy | | retention_bytes | null (no limit) | retention.bytes | | log_retention_ms | 604800000 ms (1 week) | retention.ms | | log_segment_ms | null (no limit) | segment.ms | | log_segment_size | 134217728 bytes (128 MiB) | segment.bytes | | log_compression_type | producer | compression.type | | log_message_timestamp_type | CreateTime | message.timestamp.type | | kafka_batch_max_bytes | 1048576 bytes (1 MiB) | max.message.bytes | | write_caching_default | false | write.caching | These default settings are best suited to a one-broker cluster in a development environment. To learn how to modify the default cluster-wide configurations, see [Configure Cluster Properties](../../../manage/cluster-maintenance/cluster-property-configuration/). Even if you set default values that work for most topics, you may still want to change some properties for a specific topic. > 📝 **NOTE** > > For details about topic properties, see [Topic Configuration Properties](../../../reference/properties/topic-properties/). ## [](#create-a-topic)Create a topic Creating a topic can be as simple as specifying a name for your topic on the command line. For example, to create a topic named `xyz`, run: ```bash rpk topic create xyz ``` This command creates a topic named `xyz` with one partition and one replica, because these are the default values set in the cluster configuration file. Replicas are copies of partitions that are distributed across different brokers, so if one broker goes down, other brokers still have a copy of the data. ### [](#choose-the-number-of-partitions)Choose the number of partitions A partition acts as a log file where topic data is written. Dividing topics into partitions allows producers to write messages in parallel and consumers to read messages in parallel. The higher the number of partitions, the greater the throughput. > 💡 **TIP** > > As a general rule, select a number of partitions that corresponds to the maximum number of consumers in any consumer group that will consume the data. For example, suppose you plan to create a consumer group with 10 consumers. To create topic `xyz` with 10 partitions, run: ```bash rpk topic create xyz -p 10 ``` ### [](#choose-the-replication-factor)Choose the replication factor The default replication factor in the cluster configuration is set to 1. By choosing a replication factor greater than 1, you ensure that each partition has a copy of its data on at least one other broker. One replica acts as the leader, and the other replicas are followers. To specify a replication factor of 3 for topic `xyz`, run: ```bash rpk topic create xyz -r 3 ``` > 📝 **NOTE** > > The replication factor must be an odd number. Redpanda Data recommends a replication factor of 3 for most use cases. Administrators may set a minimum required replication factor for any new topic in the cluster through the cluster-level [`minimum_topic_replications`](../../../reference/properties/cluster-properties/#minimum_topic_replications) property. > 💡 **TIP** > > If you enable [Tiered Storage](../../../manage/tiered-storage/) on a topic, you can then use [topic recovery](../../../manage/disaster-recovery/topic-recovery/) to restore data for a deleted topic. ### [](#choose-a-storage-mode)Choose a storage mode Starting in Redpanda v26.1, you can set the `redpanda.storage.mode` topic property to control how a topic stores data: | Value | Behavior | | --- | --- | | unset (default) | Legacy behavior. Tiered Storage is controlled by the redpanda.remote.read and redpanda.remote.write topic properties and their cluster-level defaults (cloud_storage_enable_remote_read and cloud_storage_enable_remote_write). | | local | Topic data is stored only on the broker’s local disk. Object storage upload is disabled for the topic, regardless of redpanda.remote.read and redpanda.remote.write values. | | tiered | Data is stored on local disk and uploaded to object storage. Enables Tiered Storage for the topic regardless of redpanda.remote.read and redpanda.remote.write values. | | cloud | Data is stored durably in object storage using the Cloud Topics architecture. Local storage is used only as a write buffer. See Manage Cloud Topics. | To set the storage mode at topic creation time: ```bash rpk topic create -c redpanda.storage.mode=tiered ``` When `redpanda.storage.mode` is set to `local`, `tiered`, or `cloud`, the `redpanda.remote.read` and `redpanda.remote.write` topic properties have no effect on the topic. To apply a default storage mode to all new topics in a cluster, set the `default_redpanda_storage_mode` cluster property: ```bash rpk cluster config set default_redpanda_storage_mode=tiered ``` To set `local` as the default storage mode for all new topics in a cluster: ```bash rpk cluster config set default_redpanda_storage_mode=local ``` If `default_redpanda_storage_mode` is not configured (the default), new topics use `unset` mode and Tiered Storage behavior is inherited from the cluster-level `cloud_storage_enable_remote_write` and `cloud_storage_enable_remote_read` properties. ## [](#update-topic-configurations)Update topic configurations After you create a topic, you can update the topic property settings for all new data written to it. For example, you can add partitions or change the cleanup policy. ### [](#add-partitions)Add partitions You can assign a certain number of partitions when you create a topic, and add partitions later. For example, suppose you add brokers to your cluster, and you want to take advantage of the additional processing power. To increase the number of partitions for existing topics, run: ```bash rpk topic add-partitions [TOPICS...] --num [#] ``` Note that `--num <#>` is the number of partitions to _add_, not the total number of partitions. > 📝 **NOTE** > > If a topic already has messages and you add partitions, the existing messages won’t be redistributed to the new partitions. If you require messages to be redistributed, then you must create a new topic with the new partition count, then stream the messages from the old topic to the new topic so they are appropriately distributed according to the new partition hashing. ### [](#change-the-replication-factor)Change the replication factor Suppose you create a topic with the default replication factor of 1 (which is specified in the cluster properties configuration file). Now you want to change the replication factor to 3, so you can have two backups of topic data in case a broker goes down. To set the replication factor to 3, run: ```bash rpk topic alter-config [TOPICS...] --set replication.factor=3 ``` > 📝 **NOTE** > > The replication factor can’t exceed the number of Redpanda brokers. If you try to set a replication factor greater than the number of brokers, the request is rejected. ### [](#change-the-storage-mode)Change the storage mode You can change a topic’s `redpanda.storage.mode` after creation, with the following restrictions: | From | To | Permitted | Notes | | --- | --- | --- | --- | | local | tiered | Yes | Enables Tiered Storage for the topic. Object storage must be configured. | | tiered | local | With caution | Disables object storage uploads. Redpanda strongly recommends against repeatedly toggling this setting, as it can result in data gaps in Tiered Storage. | | Any | cloud | No | Cloud Topics can only be set at topic creation time. | | cloud | Any | No | A Cloud Topic cannot be converted to a local or Tiered Storage topic. | For example, to transition an existing local topic to Tiered Storage: ```bash rpk topic alter-config --set redpanda.storage.mode=tiered ``` ### [](#change-the-cleanup-policy)Change the cleanup policy The cleanup policy determines how to clean up the partition log files when they reach a certain size: - `delete` deletes data based on age or log size. Topics retain all records until then. - `compact` compacts the data by only keeping the latest values for each KEY. - `compact,delete` combines both methods. Unlike compacted topics, which keep only the most recent message for a given key, topics configured with a `delete` cleanup policy provide a running history of all changes for those topics. > ⚠️ **WARNING** > > All topic properties take effect immediately after being set. Do not modify properties on internal Redpanda topics (such as `__consumer_offsets`, `_schemas`, or other system topics) as this can cause cluster instability. For example, to change a topic’s policy to `compact`, run: ```bash rpk topic alter-config [TOPICS…] —-set cleanup.policy=compact ``` For details on compaction in Redpanda, see [Compaction settings](../../../manage/cluster-maintenance/compaction-settings/). ### [](#configure-write-caching)Configure write caching Write caching is a relaxed mode of [`acks=all`](../../produce-data/configure-producers/#acksall) that provides better performance at the expense of durability. It acknowledges a message as soon as it is received and acknowledged on a majority of brokers, without waiting for it to be written to disk. This provides lower latency while still ensuring that a majority of brokers acknowledge the write. Write caching applies to user topics. It does not apply to transactions or consumer offsets: data written in the context of a transaction and consumer offset commits is always written to disk and fsynced before being acknowledged to the client. > 📝 **NOTE** > > For clusters in [development mode](../../../reference/rpk/rpk-redpanda/rpk-redpanda-mode/#development-mode), write caching is enabled by default. For clusters in production mode, it is disabled by default. Only enable write caching on workloads that can tolerate some data loss in the case of multiple, simultaneous broker failures. Leaving write caching disabled safeguards your data against complete data center or availability zone failures. #### [](#configure-at-cluster-level)Configure at cluster level To enable write caching by default in all user topics, set the cluster-level property [`write_caching_default`](../../../reference/properties/cluster-properties/#write_caching_default): `rpk cluster config set write_caching_default=true` With `write_caching_default` set to true at the cluster level, Redpanda fsyncs to disk according to [`raft_replica_max_pending_flush_bytes`](../../../reference/properties/cluster-properties/#raft_replica_max_pending_flush_bytes) and [`raft_replica_max_flush_delay_ms`](../../../reference/properties/cluster-properties/#raft_replica_max_flush_delay_ms), whichever is reached first. #### [](#configure-at-topic-level)Configure at topic level To override the cluster-level setting at the topic level, set the topic-level property `write.caching`: `rpk topic alter-config my_topic --set write.caching=true` With `write.caching` enabled at the topic level, Redpanda fsyncs to disk according to `flush.ms` and `flush.bytes`, whichever is reached first. ### [](#remove-a-configuration-setting)Remove a configuration setting You can remove a configuration that overrides the default setting, and the setting will use the default value again. For example, suppose you altered the cleanup policy to use `compact` instead of the default, `delete`. Now you want to return the policy setting to the default. To remove the configuration setting `cleanup.policy=compact`, run `rpk topic alter-config` with the `--delete` flag: ```bash rpk topic alter-config [TOPICS...] --delete cleanup.policy ``` ## [](#list-topic-configuration-settings)List topic configuration settings To display all the configuration settings for a topic, run: ```bash rpk topic describe -c ``` The `-c` flag limits the command output to just the topic configurations. This command is useful for checking the default configuration settings before you make any changes and for verifying changes after you make them. The following command output displays after running `rpk topic describe test-topic`, where `test-topic` was created with default settings: ```bash rpk topic describe test_topic SUMMARY ======= NAME test_topic PARTITIONS 1 REPLICAS 1 CONFIGS ======= KEY VALUE SOURCE cleanup.policy delete DYNAMIC_TOPIC_CONFIG compression.type producer DEFAULT_CONFIG max.message.bytes 1048576 DEFAULT_CONFIG message.timestamp.type CreateTime DEFAULT_CONFIG redpanda.datapolicy function_name: script_name: DEFAULT_CONFIG redpanda.remote.delete true DEFAULT_CONFIG redpanda.remote.read false DEFAULT_CONFIG redpanda.remote.write false DEFAULT_CONFIG redpanda.storage.mode unset DEFAULT_CONFIG retention.bytes -1 DEFAULT_CONFIG retention.local.target.bytes -1 DEFAULT_CONFIG retention.local.target.ms 86400000 DEFAULT_CONFIG retention.ms 604800000 DEFAULT_CONFIG segment.bytes 1073741824 DEFAULT_CONFIG ``` Suppose you add two partitions, and increase the number of replicas to 3. The new command output confirms the changes in the `SUMMARY` section: SUMMARY ======= NAME test\_topic PARTITIONS 3 REPLICAS 3 ## [](#delete-a-topic)Delete a topic To delete a topic, run: ```bash rpk topic delete ``` When a topic is deleted, its underlying data is deleted, too. To delete multiple topics at a time, provide a space-separated list. For example, to delete two topics named `topic1` and `topic2`, run: ```bash rpk topic delete topic1 topic2 ``` You can also use the `-r` flag to specify one or more regular expressions; then, any topic names that match the pattern you specify are deleted. For example, to delete topics with names that start with “f” and end with “r”, run: ```bash rpk topic delete -r '^f.*' '.*r$' ``` Note that the first regular expression must start with the `^` symbol, and the last expression must end with the `$` symbol. This requirement helps prevent accidental deletions. ## [](#delete-records-from-a-topic)Delete records from a topic Redpanda allows you to delete data from the beginning of a partition up to a specific offset (a monotonically increasing sequence number for records in a partition). Deleting records frees up disk space, which is especially helpful if your producers are pushing more data than anticipated in your retention plan. Delete records when you know that all consumers have read up to that given offset, and the data is no longer needed. There are different ways to delete records from a topic, including using the [`rpk topic trim-prefix`](../../../reference/rpk/rpk-topic/rpk-topic-trim-prefix/) command, using the `DeleteRecords` Kafka API with Kafka clients, or using Redpanda Console. > 📝 **NOTE** > > - To delete records, `cleanup.policy` must be set to `delete` or `compact,delete`. > > - Object storage is deleted asynchronously. After messages are deleted, the partition’s start offset will have advanced, but garbage collection of deleted segments may not be complete. > > - Similar to Kafka, after deleting records, local storage and object storage may still contain data for deleted offsets. (Redpanda does not truncate segments. Instead, it bumps the start offset, then it attempts to delete as many whole segments as possible.) Data before the new start offset is not visible to clients but could be read by someone with access to the local disk of a Redpanda node. > ⚠️ **WARNING** > > When you delete records from a topic with a timestamp, Redpanda advances the partition start offset to the first record whose timestamp is after the threshold. If record timestamps are not in order with respect to offsets, this may result in unintended deletion of data. Before using a timestamp, verify that timestamps increase in the same order as offsets in the topic to avoid accidental data loss. For example: > > ```bash > rpk topic consume -n 50 --format '%o %d{go[2006-01-02T15:04:05Z07:00]} %k %v' > ``` ## [](#next-steps)Next steps [Configure Producers](../../produce-data/configure-producers/) end::single-source\[\] ## Suggested labs - [Stream Stock Market Data from a CSV file Using Node.js](/redpanda-labs/clients/stock-market-activity-nodejs/) - [Stream Stock Market Data from a CSV file Using Python](/redpanda-labs/clients/stock-market-activity-python/) - [Build a Chat Room Application with Redpanda and Java](/redpanda-labs/clients/docker-java/) - [Build a Chat Room Application with Redpanda and Golang](/redpanda-labs/clients/docker-go/) - [Build a Chat Room Application with Redpanda and Node.js](/redpanda-labs/clients/docker-nodejs/) - [Build a Chat Room Application with Redpanda and Python](/redpanda-labs/clients/docker-python/) - [Build a Chat Room Application with Redpanda and Rust](/redpanda-labs/clients/docker-rust/) See more [Search all labs](/redpanda-labs) --- # Page 80: Produce Data **URL**: https://docs.redpanda.com/current/develop/produce-data.md --- # Produce Data --- title: Produce Data latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: produce-data/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: produce-data/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/develop/pages/produce-data/index.adoc description: Learn how to configure producers and idempotent producers. page-git-created-date: "2023-05-30" page-git-modified-date: "2024-07-24" support-status: supported --- - [Configure Producers](configure-producers/) Learn about configuration options for producers, including write caching and acknowledgment settings. - [Idempotent producers](idempotent-producers/) Idempotent producers assign a unique ID to every write request, guaranteeing that each message is recorded only once in the order in which it was sent. - [Configure Leader Pinning](leader-pinning/) Learn about Leader Pinning and how to configure a preferred partition leader location based on cloud availability zones or regions. --- # Page 81: Configure Producers **URL**: https://docs.redpanda.com/current/develop/produce-data/configure-producers.md --- # Configure Producers --- title: Configure Producers latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: produce-data/configure-producers page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: produce-data/configure-producers.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/develop/pages/produce-data/configure-producers.adoc description: Learn about configuration options for producers, including write caching and acknowledgment settings. page-git-created-date: "2023-05-30" page-git-modified-date: "2026-03-31" support-status: supported --- Producers are client applications that write data to Redpanda in the form of events. Producers communicate with Redpanda through the Kafka API. When a producer publishes a message to a Redpanda cluster, it sends it to a specific partition. Every event consists of a key and value. When selecting which partition to produce to, if the key is blank, then the producer publishes in a round-robin fashion between the topic’s partitions. If a key is provided, then the partition hashes the key using the murmur2 algorithm and modulates across the number of partitions. ## [](#producer-acknowledgment-settings)Producer acknowledgment settings The `acks` property sets the number of acknowledgments the producer requires the leader to have received before considering a request complete. This controls the durability of records that are sent. Redpanda guarantees data safety with fsync, which means flushing to disk. - With `acks=all`, every write is fsynced by default. - With other `acks` settings, or with `write_caching_default=true` at the cluster level, Redpanda fsyncs to disk according to `raft_replica_max_pending_flush_bytes` and `raft_replica_max_flush_delay_ms`, whichever is reached first. - With `write.caching` enabled at the topic level, Redpanda fsyncs to disk according to `flush.ms` and `flush.bytes`, whichever is reached first. ### [](#acks0)`acks=0` The producer doesn’t wait for acknowledgments from the leader and doesn’t retry sending messages. This increases throughput and lowers latency of the system at the expense of durability and data loss. This option allows a producer to immediately consider a message acknowledged when it is sent to the Redpanda broker. This means that a producer does not have to wait for any response from the Redpanda broker. This is the least safe option, because a leader-broker crash can cause data loss if the data has not yet replicated to the other brokers in the replica set. However, this setting is useful when you want to optimize for the highest throughput and are willing to risk some data loss. Because of the lack of guarantees, this setting is the most network bandwidth-efficient. This is helpful for use cases like IoT/sensor data collection, where updates are periodic or stateless and you can afford some degree of data loss, but you want to gather as much data as possible in a given time interval. ### [](#acks1)`acks=1` The producer waits for an acknowledgment from the leader, but it doesn’t wait for the leader to get acknowledgments from followers. This setting doesn’t prioritize throughput, latency, or durability. Instead, `acks=1` attempts to provide a balance between all of them. Replication is not guaranteed with this setting because it happens in the background, after the leader broker sends an acknowledgment to the producer. This setting could result in data loss if the leader broker crashes before any followers manage to replicate the message or if a majority of replicas go down at the same time before fsyncing the message to the disk. ### [](#acksall)`acks=all` The producer receives an acknowledgment after the majority of (implicitly, all) replicas acknowledge the message. Redpanda guarantees data safety by fsyncing every message to disk before acknowledgement back to clients. This increases durability at the expense of lower throughput and increased latency. Sometimes referred to as `acks = -1`, this option instructs the broker that replication is considered complete when the message has been replicated (and fsynced) to the majority of the brokers responsible for the partition in the cluster. As soon as the fsync call is complete, the message is considered acknowledged and is made visible to readers. > 📝 **NOTE** > > This property has an important distinction compared to Kafka’s behavior. In Kafka, a message is considered acknowledged without the requirement that it has been fsynced. Messages that have not been fsynced to disk may be lost in the event of a broker crash. So when using `acks=all`, the Redpanda default configuration is more resilient than Kafka’s. You can also consider using [write caching](../../manage-topics/config-topics/#configure-write-caching), which is a relaxed mode of `acks=all` that acknowledges a message as soon as it is received and acknowledged on a majority of brokers, without waiting for it to fsync to disk. This provides lower latency while still ensuring that a majority of brokers acknowledge the write. ### [](#retries)`retries` This property controls the number of times a message is re-sent to the broker if the broker fails to acknowledge it. This is essentially the same as if the client application resends the erroneous message after receiving an error response. The default value of `retries` in most client libraries is 0. This means that if the send fails, the message is not re-sent at all. If you increase this to a higher value, check the `max.in.flight.requests.per.connection` value as well, because leaving that property at its default value can potentially cause ordering issues in the target topic where the messages arrive. This occurs if two batches are sent to a single partition and the first fails and is retired, but the second succeeds so the records in the second batch may appear first. ### [](#max-in-flight-requests-per-connection)`max.in.flight.requests.per.connection` This property controls how many unacknowledged messages can be sent to the broker simultaneously at any given time. The default value is 5 in most client libraries. If you set this to 1, then the producer does not send any more messages until the previous one is either acknowledged or an error happens, which can prompt a retry. If you set this to a value higher than 1, then the producer sends more messages at the same time, which can help increase throughput but adds a risk of message reordering if retries are enabled. When you configure the producer to be [idempotent](../idempotent-producers/), up to five requests can be guaranteed to be in flight with the order preserved. ### [](#enable-idempotence)`enable.idempotence` To enable idempotence, set `enable.idempotence` to `true` (the default) in your Redpanda configuration. When idempotence is enabled, the producer ensures that exactly one copy of every message is written to the broker. When set to `false`, the producer retries sending a message for any reason (such as transient errors like brokers not being available or not enough replicas exception), and it can lead to duplicates. In most client libraries `enable.idempotence` is set to true by default. Internally, this is implemented using a special identifier that is assigned to every producer (the producer ID or PID). This ID, along with a sequence number, is included in every message sent to the broker. The broker checks if the PID/sequence number combination is larger than the previous one and, if not, it discards the message. To guarantee true idempotent behavior, you must also set `acks=all` to ensure that all brokers record messages in order, even in the event of node failures. In this configuration, both the producer and the broker prefer safety and durability over throughput. Idempotence is only guaranteed within a session. A session starts after the producer is instantiated and a connection is established between the client and the Redpanda broker. When the connection is closed, the session ends. If your application code retries a request, the producer client assigns a new ID to that request, which may lead to duplicate messages. ## [](#message-batching)Message batching Batching is an efficient way to save on both network bandwidth and disk size, because messages can be compressed easier. When a producer prepares to send messages to a broker, it first fills up a buffer. When this buffer is full, the producer compresses (if instructed to do so) and sends out this batch of messages to the broker. The number of batches that can be sent in a single request to the broker is limited by the `max.request.size` property. The number of requests that can simultaneously be in this sending state is controlled by the `max.in.flight.requests.per.connection` value, which defaults to 5 in most client libraries. Tune the batching configuration with the following properties: ### [](#buffer-memory)`buffer.memory` This property controls the total amount of memory available to the producer for buffering. If messages are sent faster than they can be delivered to the broker, the producer application may run out of memory, which causes it to either block subsequent send calls or throw an exception. The `max.block.ms` property controls the amount of time the producer blocks before throwing an exception if it cannot immediately send messages to the broker. ### [](#batch-size)`batch.size` This property controls the maximum size of coupled messages that can be batched together in one request. The producer automatically puts messages being sent to the same partition into one batch. This configuration property is given in bytes, as opposed to the number of messages. When the producer is gathering messages to assign to a batch, at some point it hits this byte-size limit, which triggers it to send the batch to the broker. However, the producer does not necessarily wait (for as much time as set using `linger.ms`) until the batch is full. Sometimes, it can even send single-message batches. This means that setting the batch size too large is not necessarily undesirable, because it won’t cause throttling when sending messages; rather, it only causes increased memory usage. Conversely, setting the batch size too small can cause the producer to send batches of messages faster, which can cause network overhead, meaning a reduced throughput. The default value is usually 16384, but you can set this as low as 0, which turns off batching entirely. ### [](#linger-ms)`linger.ms` This property controls the maximum amount of time the producer waits before sending out a batch of messages, if it is not already full. This means you can somewhat force the producer to make sure that batches are filled as efficiently as possible. If you’re willing to tolerate some latency, setting this value to a number larger than the default of `0` causes the producer to send fewer, more efficient batches of messages. If you set the value to `0`, there is still a high chance messages arrive around the same time to be batched together. ## [](#common-producer-configurations)Common producer configurations ### [](#compression-type)`compression.type` This property controls how the producer should compress a batch of messages before sending it to the broker. The default is `none`, which means the batch of messages is not compressed at all. Compression occurs on full batches, so you can improve batching throughput by setting this property to use one of the available compression algorithms (along with increasing batch size). The available options are: `zstd`, `lz4`, `gzip`, and `snappy`. ### [](#serializers)Serializers Serializers are responsible for converting a message to a byte array. You can influence the speed/memory efficiency of your streaming setup by choosing one of the built-in serializers or writing a custom one. The performance consequences of using serializers is not typically significant. For example, if you opt for the JSON serializer, you have more data to transport with each message because every record contains its schema in a verbose format, which impacts your compression speeds and network throughput. Alternatively, going with AVRO or Protobuf allows you to only define the schema in one place, while also enabling features like schema evolution. ## [](#broker-timestamps)Broker timestamps Redpanda employs a unique strategy to help ensure the accuracy of retention operations. In this strategy, closed segments are only eligible for deletion when the age of all messages in the segment exceeds a configured threshold. However, when a producer sends a message to a topic, the timestamp set by the producer may not accurately reflect the time the message reaches the broker. To address this time skew, each time a producer sends a message to a topic, Redpanda records the broker’s system date and time in the `broker_timestamp` property of the message. This property helps maintain accurate retention policies, even when the message’s creation timestamp deviates from the broker’s time. > 📝 **NOTE** > > Clock synchronization should be monitored by the server owner, as Redpanda does not monitor clock synchronization. While Redpanda does not rely on clocks for correctness, if you are using `LogAppendTime` (server timestamp set by Redpanda), server clocks may affect the time your application sees. See also: - [Set time-based retention](../../../manage/cluster-maintenance/disk-utilization/#set-time-based-retention) ### [](#configure-broker-timestamp-alerting)Configure broker timestamp alerting Each time a broker receives a message with a skewed timestamp that is outside a configured range, Redpanda increments the [`vectorized_kafka_rpc_produce_bad_create_time`](../../../reference/internal-metrics-reference/#vectorized_kafka_rpc_produce_bad_create_time) metric. Two cluster properties control this range. The minimum accepted value for both of these properties is five minutes. Any attempt to set a value lower than that is rejected by Redpanda. - `log_message_timestamp_alert_before_ms`: Defines the allowed skew before the broker’s time. This check is effectively disabled when the value is set to `null`. Minimum: `300000 ms` (5 minutes), Default: `null`. - `log_message_timestamp_alert_after_ms`: Defines the allowed skew after the broker’s time. There is no way to disable this check. Minimum: `300000 ms` (5 minutes), Default: `7200000 ms` (2 hours). ### [](#disable-broker-timestamp-retention)Disable broker timestamp retention While not advised for typical use, Redpanda lets you override the use of broker timestamps for retention policy with the Admin API. Use the [`activate feature`](/api/doc/admin/operation/operation-put_feature) API to disable the `broker_time_based_retention` property. If you disable this feature, make sure to specify your desired timestamp policy. This is stored in the [`log_message_timestamp_type`](../../../reference/properties/cluster-properties/#log_message_timestamp_type) cluster property. The timestamp policy defaults to `CreateTime` (client timestamp set by producer) but may be updated to `LogAppendTime` (server timestamp set by Redpanda). ## [](#producer-optimization-strategies)Producer optimization strategies You can optimize for speed (throughput and latency) or safety (durability and availability) by adjusting properties. Finding the optimal configuration depends on your use case. There are many configuration options within Redpanda. The configuration options mentioned here work best when combined with other broker and consumer configuration options. See also: - [Configure Broker Properties](../../../manage/cluster-maintenance/node-property-configuration/) - [Consumer Offsets](../../consume-data/consumer-offsets/) ### [](#optimize-for-speed)Optimize for speed To get data into Redpanda as quickly as possible, you can maximize latency and throughput in a variety of ways: - Experiment with [acks](#producer-acknowledgment-settings) settings. The quicker a producer receives a reply from the broker that the message has been committed, the sooner it can send the next message, which generally results in higher throughput. Hence, if you set `acks=1`, then the leader broker does not need to wait for replication to occur, and it can reply as soon as it finishes committing the message. This can result in less durability overall. - Enable [write caching](#Write caching), which acknowledges a message as soon as it is received and acknowledged on a majority of brokers, without waiting for it to fsync to disk. This provides lower latency while still ensuring that a majority of brokers acknowledge the write. - Experiment with other component’s properties, like the topic partition size. - Explore how the producer batches messages. Increasing the value of `batch.size` and `linger.ms` can increase throughput by making the producer add more messages into one batch before sending it to the broker and waiting until the batches can properly fill up. This approach negatively impacts latency though. By contrast, if you set `linger.ms` to `0` and `batch.size` to `1`, you can achieve lower latency, but sacrifice throughput. ### [](#optimize-for-safety)Optimize for safety For applications where you must guarantee that there are no lost messages, duplicates, or service downtime, you can use higher durability `acks` settings. If you set `acks=all`, then the producer waits for a majority of replicas to acknowledge the message before it can send the next message, resulting in lower latency, because there is more communication required between brokers. This approach can guarantee higher durability because the message is replicated to all brokers. You can also increase durability by increasing the number of retries the broker can make in case messages are not delivered successfully. The trade-off is that duplicates may enter the system and potentially alter the ordering of messages. ## Suggested labs - [Stream Stock Market Data from a CSV file Using Node.js](/redpanda-labs/clients/stock-market-activity-nodejs/) - [Stream Stock Market Data from a CSV file Using Python](/redpanda-labs/clients/stock-market-activity-python/) - [Build a Chat Room Application with Redpanda and Java](/redpanda-labs/clients/docker-java/) - [Build a Chat Room Application with Redpanda and Golang](/redpanda-labs/clients/docker-go/) - [Build a Chat Room Application with Redpanda and Node.js](/redpanda-labs/clients/docker-nodejs/) - [Build a Chat Room Application with Redpanda and Python](/redpanda-labs/clients/docker-python/) - [Build a Chat Room Application with Redpanda and Rust](/redpanda-labs/clients/docker-rust/) See more [Search all labs](/redpanda-labs) --- # Page 82: Idempotent producers **URL**: https://docs.redpanda.com/current/develop/produce-data/idempotent-producers.md --- # Idempotent producers --- title: Idempotent producers latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: produce-data/idempotent-producers page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: produce-data/idempotent-producers.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/develop/pages/produce-data/idempotent-producers.adoc description: Idempotent producers assign a unique ID to every write request, guaranteeing that each message is recorded only once in the order in which it was sent. page-git-created-date: "2023-05-30" page-git-modified-date: "2025-05-07" support-status: supported --- When a producer writes messages to a topic, each message should be recorded only once in the order in which it was sent. However, network issues such as a connection failure can result in a timeout, which prevents a write request from succeeding. In such cases, the client retries the write request until one of these events occurs: - The client receives an acknowledgment from the broker that the write was successful. - The retry limit is reached. - The message delivery timeout limit is reached. Since there is no way to tell if the initial write request succeeded before the disruption, a retry can result in a duplicate message. A retry can also cause subsequent messages to be written out of order. Idempotent producers prevent this problem by assigning a unique ID to every write request. The request ID consists of the producer ID and a sequence number. The sequence number identifies the order in which each write request was sent. If a retry results in a duplicate message, Redpanda detects and rejects the duplicate message and maintains the original order of the messages. If new write requests continue while a previous request is being retried, the new requests are stored in the client’s memory in the order in which they were sent. The client must also retry these requests once the previous request is successful. ## [](#enable-idempotence-for-producers)Enable idempotence for producers To make producers idempotent, the `enable.idempotence` property must be set to `true` in your producer configuration, as well as in the Redpanda cluster configuration, where it is set to `true` by default. Some Kafka clients have `enable.idempotence` set to `false` by default. In this case, set the property to `true` by following the instructions for your particular client. Idempotence is guaranteed within a session. A session starts once a producer is created and a connection is established between the client and the Kafka broker. > 📝 **NOTE** > > Idempotent producers retry unsuccessful write requests automatically. If you manually retry a write request, the client will assign a new ID to that request, which may lead to duplicate messages. To disable idempotence (and risk duplicate messages as a result of retries), set `enable_idempotence` to `false`. For instructions on how to edit any cluster property, see [Configure cluster properties](../../../manage/cluster-maintenance/cluster-property-configuration/). ## Suggested labs - [Stream Stock Market Data from a CSV file Using Node.js](/redpanda-labs/clients/stock-market-activity-nodejs/) - [Stream Stock Market Data from a CSV file Using Python](/redpanda-labs/clients/stock-market-activity-python/) - [Build a Chat Room Application with Redpanda and Java](/redpanda-labs/clients/docker-java/) - [Build a Chat Room Application with Redpanda and Golang](/redpanda-labs/clients/docker-go/) - [Build a Chat Room Application with Redpanda and Node.js](/redpanda-labs/clients/docker-nodejs/) - [Build a Chat Room Application with Redpanda and Python](/redpanda-labs/clients/docker-python/) - [Build a Chat Room Application with Redpanda and Rust](/redpanda-labs/clients/docker-rust/) See more [Search all labs](/redpanda-labs) --- # Page 83: Configure Leader Pinning **URL**: https://docs.redpanda.com/current/develop/produce-data/leader-pinning.md --- # Configure Leader Pinning --- title: Configure Leader Pinning latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: produce-data/leader-pinning page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: produce-data/leader-pinning.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/develop/pages/produce-data/leader-pinning.adoc description: Learn about Leader Pinning and how to configure a preferred partition leader location based on cloud availability zones or regions. page-topic-type: how-to personas: streaming_developer, platform_admin learning-objective-1: Configure preferred partition leader placement using rack labels learning-objective-2: Configure ordered rack preference for priority-based leader failover learning-objective-3: Identify conditions where Leader Pinning cannot place leaders in preferred racks page-git-created-date: "2024-12-03" page-git-modified-date: "2026-04-08" support-status: supported --- Produce requests that write data to Redpanda topics are routed through the topic partition leader, which syncs messages across its follower replicas. For a Redpanda cluster deployed across multiple availability zones (AZs), Leader Pinning ensures that a topic’s partition leaders are geographically closer to clients, which helps decrease networking costs and guarantees lower latency. If consumers are located in the same preferred region or AZ for Leader Pinning, and you have not set up [follower fetching](../../consume-data/follower-fetching/), Leader Pinning can also help reduce networking costs on consume requests. After reading this page, you will be able to: - Configure preferred partition leader placement using rack labels - Configure ordered rack preference for priority-based leader failover - Identify conditions where Leader Pinning cannot place leaders in preferred racks ## [](#prerequisites)Prerequisites > 📝 **NOTE** > > This feature requires an [enterprise license](../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../get-started/licensing/#self-managed) apply. Before you can enable Leader Pinning, you must [configure rack awareness](../../../manage/rack-awareness/#configure-rack-awareness) on the cluster. If the `[enable_rack_awareness](../../../reference/properties/cluster-properties/#enable_rack_awareness)` cluster configuration property is set to `false`, Leader Pinning is disabled across the cluster. ## [](#set-leader-rack-preferences)Set leader rack preferences You can configure Leader Pinning at the topic level, the cluster level, or both. Set the topic configuration property to configure individual topics, or set the cluster configuration property to apply a default for all topics. You can also combine both: apply a cluster-wide default, then override specific topics with the topic property. This configuration is based on the following scenario: you have Redpanda deployed in a multi-AZ or multi-region cluster, and you have configured each broker so that the `[rack](../../../reference/properties/broker-properties/#rack)` configuration property contains racks corresponding to the AZs: - Set the topic configuration property [`redpanda.leaders.preference`](../../../reference/properties/topic-properties/#redpanda-leaders-preference). This property accepts the following string values: - `none`: Disable Leader Pinning for the topic. - `racks:[,,…​]`: Specify the preferred location (rack) of all topic partition leaders. The list can contain one or more racks, and you can list the racks in any order. Spaces in the list are ignored, for example: `racks:rack1,rack2` and `racks: rack1, rack2` are equivalent. You cannot specify empty racks, for example: `racks: rack1,,rack2`. If you specify multiple racks, Redpanda tries to distribute the partition leader locations equally across brokers in these racks. - `ordered_racks:[,,…​]`: Supported in Redpanda v26.1 or later. Specify the preferred racks in priority order. Redpanda places leaders in the first listed rack when available, failing over to each subsequent rack when higher-priority racks are unavailable. If all listed racks are unavailable, leaders fall back to any other available brokers. Brokers with no rack assignment are treated as lowest priority. Use `ordered_racks` for multi-region deployments with a primary region for leaders and explicit failover to a disaster recovery site. The [`redpanda.leaders.preference`](../../../reference/properties/topic-properties/#redpanda-leaders-preference) property inherits the default value from the cluster property `default_leaders_preference`. To find the rack identifiers of all brokers, run: ```bash rpk cluster info ``` Expected output ```bash CLUSTER ======= redpanda.be267958-279d-49cd-ae86-98fc7ed2de48 BROKERS ======= ID HOST PORT RACK 0* 54.70.51.189 9092 us-west-2a 1 35.93.178.18 9092 us-west-2b 2 35.91.121.126 9092 us-west-2c ``` To set the topic property: ```bash rpk topic alter-config --set redpanda.leaders.preference=ordered_racks:, ``` - Set the cluster configuration property `[default_leaders_preference](../../../reference/properties/cluster-properties/#default_leaders_preference)`, which specifies the default Leader Pinning configuration for all topics that don’t have `redpanda.leaders.preference` explicitly set. It accepts values in the same format as `redpanda.leaders.preference`, where the default is `none`. This property also affects internal topics, such as `__consumer_offsets` and transaction coordinators. All offset tracking and transaction coordination requests get placed within the preferred regions or AZs for all clients, so you see end-to-end latency and networking cost benefits. To set the cluster property: ```bash rpk cluster config set default_leaders_preference ordered_racks:, ``` If there is more than one broker in the preferred AZ (or AZs), Leader Pinning distributes partition leaders uniformly across brokers in the AZ. ## [](#limitations)Limitations Leader Pinning controls which replica is elected as leader, and does not move replicas to different brokers. If all of a topic’s replicas are on brokers in non-preferred racks, no replica exists in the preferred racks to elect as leader, and Redpanda may elect a non-preferred leader indefinitely. For example, consider a cluster deployed across four racks (A, B, C, D) with Leader Pinning configured as `ordered_racks:A,B,C,D`. With a replication factor of 3, rack awareness can only place replicas in three of the four racks. If the highest-priority rack (A) does not receive a replica, no replica exists there to elect as leader, and Redpanda may elect a non-preferred leader indefinitely. To prevent this scenario: - Enable `[enable_rack_awareness](../../../reference/properties/cluster-properties/#enable_rack_awareness)` to distribute replicas across racks automatically. - Ensure the topic’s replication factor at least equals the total number of racks in the cluster, so every rack, including the highest-priority rack, receives a replica. ## [](#leader-pinning-failover-across-availability-zones)Leader Pinning failover across availability zones If there are three AZs: A, B, and C, and A becomes unavailable, the failover behavior with `racks` is as follows: - The topic with `A` as the preferred leader AZ will have its partition leaders uniformly distributed across B and C. - The topic with `A,B` as the preferred leader AZs will have its partition leaders in B. - The topic with `B` as the preferred leader AZ will have its partition leaders in B as well. ### [](#failover-with-ordered-rack-preference)Failover with ordered rack preference With `ordered_racks`, the failover order follows the configured priority list. Leaders move to the next available rack in the list when higher-priority racks become unavailable. For a topic configured with `ordered_racks:A,B,C`: - The topic with `A` as the first-priority rack will have its partition leaders in A. - If A becomes unavailable, leaders move to B. - If A and B become unavailable, leaders move to C. - If A, B, and C all become unavailable, leaders fall back to any available brokers. If a higher-priority rack recovers and the topic’s replication factor ensures that rack receives a replica, Redpanda automatically moves leaders back to the highest available preferred rack. ## [](#suggested-reading)Suggested reading - For latency-tolerant, high-throughput workloads where cross-AZ networking charges are a major cost driver, also consider [Cloud Topics](../../manage-topics/cloud-topics/) - [Follower Fetching](../../consume-data/follower-fetching/) --- # Page 84: Transactions **URL**: https://docs.redpanda.com/current/develop/transactions.md --- # Transactions --- title: Transactions latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: transactions page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: transactions.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/develop/pages/transactions.adoc description: Learn how to use transactions; for example, you can fetch messages starting from the last consumed offset and transactionally process them one by one, updating the last consumed offset and producing events at the same time. page-git-created-date: "2023-05-30" page-git-modified-date: "2026-02-21" support-status: supported --- Redpanda supports Apache Kafka®-compatible transaction semantics and APIs. For example, you can fetch messages starting from the last consumed offset and transactionally process them one by one, updating the last consumed offset and producing events at the same time. A transaction can span partitions from different topics, and a topic can be deleted while there are active transactions on one or more of its partitions. In-flight transactions can detect deletion events, remove the deleted partitions (and related messages) from the transaction scope, and commit changes to the remaining partitions. If a producer is sending multiple messages to the same or different partitions, and network connectivity or broker failure cause the transaction to fail, then it’s guaranteed that either all messages are written to the partitions or none. This is important for applications that require strict guarantees, like financial services transactions. Transactions guarantee both exactly-once semantics (EOS) and atomicity: - EOS helps developers avoid the anomalies of at-most-once processing (with potential lost events) and at-least-once processing (with potential duplicated events). Redpanda supports EOS when transactions are used in combination with [idempotent producers](../produce-data/idempotent-producers/). - Atomicity additionally commits a set of messages across partitions as a unit: either all messages are committed or none. Encapsulated data received or sent across multiple topics in a single operation can only succeed or fail globally. > 📝 **NOTE** > > Atomicity of transactions is not guaranteed when [remote recovery](../../manage/tiered-storage/#remote-recovery) is used. ## [](#use-transactions)Use transactions By default, the `[enable_transactions](../../reference/properties/cluster-properties/#enable_transactions)` cluster configuration property is set to true. However, in the following use cases, clients must explicitly use the Transactions API to perform operations within a transaction: - [Atomic (all or nothing) publishing of multiple messages](#atomic-publishing-of-multiple-messages) - [Exactly-once stream processing](#exactly-once-stream-processing) When you use transactions, you must set the [`transactional.id`](https://kafka.apache.org/documentation/#producerconfigs_transactional.id) property in the producer configuration. This property uniquely identifies the producer and enables reliable semantics across multiple producer sessions. It ensures that all transactions issued by a given producer are completed before any new transactions are started. ### [](#atomic-publishing-of-multiple-messages)Atomic publishing of multiple messages A banking IT system with an event-sourcing microservice architecture illustrates why transactions are necessary. In this system, each bank branch is implemented as an independent microservice that manages its own distinct set of accounts. Every branch maintains its own transaction history, stored as a Redpanda partition. When a branch starts, it replays the transaction history to reconstruct its current state. Financial transactions such as money transfers require the following guarantees: - A sender can’t withdraw more than the account withdrawal limit. - A recipient receives exactly the same amount sent. - A transaction is fast and is run at most once. - If a transaction fails, the system rolls back to the initial state. - Without withdrawals and deposits, the amount of money in the system remains constant with any history of money transfers. These requirements are easy to satisfy when the sender and the recipient of a financial transaction are hosted by the same branch. The operation doesn’t leave the consistency domain, and all checks and locks can be performed within a single service (ledger). Things get more complex with cross-branch financial transactions, because they involve several ledgers, and the operations should be performed atomically (all or nothing). The default approach (saga pattern) breaks a transaction into a sequence of reversible idempotent steps; however, this violates the isolation principle and adds complexity, making the application responsible for orchestrating the steps. Redpanda natively supports transactions, so it’s possible to atomically update several ledgers at the same time. For example: Show multi-ledger transaction example: ```java Properties props = new Properties(); props.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, "..."); props.put(ProducerConfig.ACKS_CONFIG, "all"); props.put(ProducerConfig.ENABLE_IDEMPOTENCE_CONFIG, true); props.put(ProducerConfig.TRANSACTIONAL_ID_CONFIG, "app-id"); Producer producer = null; while (true) { // waiting for somebody to initiate a financial transaction var sender_branch = ...; var sender_account = ...; var recipient_branch = ...; var recipient_account = ...; var amount = 42; if (producer == null) { try { producer = new KafkaProducer<>(props); producer.initTransactions(); } catch (Exception e1) { // TIP: log error for further analysis try { if (producer != null) { producer.close(); } } catch(Exception e2) { } producer = null; // TIP: notify the initiator of a transaction about the failure continue; } } producer.beginTransaction(); try { var f1 = producer.send(new ProducerRecord("ledger", sender_branch, sender_account, "" + (-amount))); var f2 = producer.send(new ProducerRecord("ledger", recipient_branch, recipient_account, "" + amount)); f1.get(); f2.get(); } catch (Exception e1) { // TIP: log error for further analysis try { producer.abortTransaction(); } catch (Exception e2) { // TIP: log error for further analysis try { producer.close(); } catch (Exception e3) { } producer = null; } // TIP: notify the initiator of a transaction about the failure continue; } try { producer.commitTransaction(); } catch (Exception e1) { try { producer.close(); } catch (Exception e3) {} producer = null; // TIP: notify the initiator of a transaction about the failure continue; } // TIP: notify the initiator of a transaction about the success } ``` When a transaction fails before a `commitTransaction` attempt completes, you can assume that it is not executed. When a transaction fails after a `commitTransaction` attempt completes, the true transaction status is unknown. Redpanda only guarantees that there isn’t a partial result: either the transaction is committed and complete, or it is fully rolled back. ### [](#exactly-once-stream-processing)Exactly-once stream processing Redpanda is commonly used as a pipe connecting different applications and storage systems. An application could use an OLTP database and then rely on change data capture to deliver the changes to a data warehouse. Redpanda transactions let you use streams as a smart pipe in your applications, building complex atomic operations that transform, aggregate, or otherwise process data transiting between external applications and storage systems. For example, here is the regular pipe flow: Postgresql -> topic -> warehouse Here is the smart pipe flow, with a transformation in `topic(1) -> topic(2)`: Postgresql -> topic(1) transform topic(2) -> warehouse The transformation reads a record from `topic(1)`, processes it, and writes it to `topic(2)`. Without transactions, an intermittent error can cause a message to be lost or processed several times. With transactions, Redpanda guarantees exactly-once semantics. For example: Show exactly-once processing example: ```java var source = "source-topic"; var target = "target-topic"; Properties pprops = new Properties(); pprops.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, "..."); pprops.put(ProducerConfig.ACKS_CONFIG, "all"); pprops.put(ProducerConfig.ENABLE_IDEMPOTENCE_CONFIG, true); pprops.put(ProducerConfig.TRANSACTIONAL_ID_CONFIG, UUID.randomUUID().toString()); Properties cprops = new Properties(); cprops.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, "..."); cprops.put(ConsumerConfig.ENABLE_AUTO_COMMIT_CONFIG, false); cprops.put(ConsumerConfig.GROUP_ID_CONFIG, "app-id"); cprops.put(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest"); cprops.put(ConsumerConfig.ISOLATION_LEVEL_CONFIG, "read_committed"); Consumer consumer = null; Producer producer = null; boolean should_reset = false; while (true) { if (should_reset) { should_reset = false; if (consumer != null) { try { consumer.close(); } catch(Exception e) {} consumer = null; } if (producer != null) { try { producer.close(); } catch (Exception e2) {} producer = null; } } try { if (consumer == null) { consumer = new KafkaConsumer<>(cprops); consumer.subscribe(Collections.singleton(source)); } } catch (Exception e1) { // TIP: log error for further analysis should_reset = true; continue; } try { if (producer == null) { producer = new KafkaProducer<>(pprops); producer.initTransactions(); } } catch (Exception e1) { // TIP: log error for further analysis should_reset = true; continue; } ConsumerRecords records = null; try { records = consumer.poll(Duration.ofMillis(10000)); } catch (Exception e1) { // TIP: log error for further analysis should_reset = true; continue; } var it = records.iterator(); while (it.hasNext()) { var record = it.next(); // transformation var old_value = record.value(); var new_value = old_value.toUpperCase(); try { producer.beginTransaction(); producer.send(new ProducerRecord(target, record.key(), new_value)); var offsets = new HashMap(); offsets.put(new TopicPartition(source, record.partition()), new OffsetAndMetadata(record.offset() + 1)); producer.sendOffsetsToTransaction(offsets, consumer.groupMetadata()); } catch (Exception e1) { // TIP: log error for further analysis try { producer.abortTransaction(); } catch (Exception e2) { } should_reset = true; break; } try { producer.commitTransaction(); } catch (Exception e1) { // TIP: log error for further analysis should_reset = true; break; } } } ``` #### [](#exactly-once-processing-configuration-requirements)Exactly-once processing configuration requirements Redpanda’s default configuration supports exactly-once processing. To preserve this capability, ensure the following settings are maintained: - `enable_idempotence = true` - `enable_transactions = true` - `transaction_coordinator_delete_retention_ms` is greater than or equal to `transactional_id_expiration_ms` ## [](#best-practices)Best practices To help avoid common pitfalls and optimize performance, consider the following when configuring transactional workloads in Redpanda: ### [](#tune-producer-id-limits)Tune producer ID limits For production environments with heavy producer usage, configure both [`max_concurrent_producer_ids`](../../reference/properties/cluster-properties/#max_concurrent_producer_ids) and [`transactional_id_expiration_ms`](../../reference/properties/cluster-properties/#transactional_id_expiration_ms) to prevent out-of-memory (OOM) crashes. Setting limits on producer IDs helps manage memory usage in high-throughput environments, particularly when using transactions or idempotent producers. If you have\`kafka\_connections\_max\` configured, you can determine an appropriate value for `max_concurrent_producer_ids` based on your connection patterns. - Lower bound: `kafka_connections_max` / `number_of_shards`, assuming each producer connects to only one shard. - Upper bound: `topic_partitions_per_shard` \* `kafka_connections_max`, assuming producers connect to all shards. If `kafka_connections_max` is not configured, estimate the value for `max_concurrent_producer_ids` based on your application patterns. A conservative approach is to start with 1000-5000 per shard, then monitor and adjust as needed. Applications with many partitions per producer typically require higher values, such as 10000 or more per shard. Tune `transactional_id_expiration_ms` based on your application’s transaction patterns. Calculate this value by taking your longest expected transaction time and adding a safety buffer. For example, if transactions typically run for 30 minutes, consider setting this to 2-4 hours. Short-lived transactions can use values between 1-4 hours, while batch processing applications should match their batch interval plus buffer time. Interactive applications may benefit from shorter values to free up memory faster. Client applications should minimize producer ID churn. Reuse producer instances when possible, instead of creating new ones for each operation. Avoid using random transactional IDs, as some Flink configurations do, because this creates excessive producer ID churn. Instead, use consistent transactional IDs that can be resumed across application restarts. Monitor the following metrics to determine if the limit is being reached: - [`vectorized_cluster_producer_state_manager_evicted_producers`](../../reference/internal-metrics-reference/#vectorized_cluster_producer_state_manager_evicted_producers): Number of evicted producers (should be 0 in steady state) - [`vectorized_cluster_producer_state_manager_producer_manager_total_active_producers`](../../reference/internal-metrics-reference/#vectorized_cluster_producer_state_manager_producer_manager_total_active_producers): Current number of active producers per shard If `vectorized_cluster_producer_state_manager_evicted_producers` > 0, the shard is exceeding the configured limit. For applications with long-running transactions, ensure [`transactional_id_expiration_ms`](../../reference/properties/cluster-properties/#transactional_id_expiration_ms) accommodates your typical transaction lifetime to avoid premature producer ID expiration. ### [](#configure-transaction-timeouts-and-limits)Configure transaction timeouts and limits - If a consumer is configured to use the read\_committed isolation level, it can only process successfully committed transactions. As a result, an ongoing transaction with a large timeout that becomes stuck could prevent the consumer from processing other committed transactions. To avoid this, don’t set the transaction timeout client setting (`transaction.timeout.ms` in the Kafka Java client implementation) to a value that is too high. The longer the timeout, the longer consumers may be blocked. - When running transactional workloads from clients, tune [`max_transactions_per_coordinator`](../../reference/properties/cluster-properties/#max_transactions_per_coordinator) to match the number of concurrent transactions your clients run (if your client transaction IDs are not reused). The total number of transactions allowed in the cluster at any time is determined by `max_transactions_per_coordinator * transaction_coordinator_partitions` (default is 50 partitions). When the limit is exceeded, Redpanda terminates old sessions. If an idle producer corresponding to a terminated session becomes active and tries to produces again, Redpanda rejects its batches with an `invalid producer epoch` or `invalid_producer_id_mapping` error, depending on where it is in the transaction execution phase. Be aware that if you keep the `transaction_coordinator_partitions` at the default of 50 and your clients create a new ID for every transaction, the total continues to accumulate, which bloats memory. - Transactional metadata is stored in the internal topic `kafka_internal/tx`. Over time, this topic can consume disk space. You can manage its disk usage by tuning the `transaction_coordinator_delete_retention_ms` and `transactional_id_expiration_ms` cluster properties. See also: [Manage Disk Space](../../manage/cluster-maintenance/disk-utilization/#manage-transaction-coordinator-disk-usage) - When upgrading a self-managed deployment, make sure to use maintenance mode with a [rolling upgrade](https://docs.redpanda.com/current/reference/glossary/#rolling-upgrade). ## [](#handle-transaction-failures)Handle transaction failures Different transactions require different approaches to handling failures within the application. Consider the approaches to failed or timed-out transactions in the provided use cases: - Publishing of multiple messages: The request came from outside the system, and it is the application’s responsibility to discover the true status of a timed-out transaction. (This example doesn’t use consumer groups to distribute partitions between consumers.) - Exactly-once streaming (consume-transform-loop): This is a closed system. Upon re-initialization of the consumer and producer, the system automatically discovers the moment it was interrupted and continues from that place. Additionally, this automatically scales by the number of partitions. Run another instance of the application, and it starts processing its share of partitions in the source topic. ## [](#transactions-with-compacted-segments)Transactions with compacted segments Transactions are supported on topics with compaction configured. The compaction process removes aborted transaction data from the log. The resulting compacted segment contains only committed data batches (and potentially harmless gaps in the offsets due to skipped batches). At a cluster-level, compaction is set when [`log_cleanup_policy`](../../reference/properties/cluster-properties/#log_cleanup_policy) or [`cleanup.policy`](../../reference/properties/topic-properties/#cleanuppolicy) are set to either `compact` or `compact,delete`. Optionally, you can enable removal of transactional control batches (commit and abort markers) during compaction by setting [`log_compaction_tx_batch_removal_enabled`](../../reference/properties/cluster-properties/#log_compaction_tx_batch_removal_enabled) to `true`. When enabled, the topic’s [`delete.retention.ms`](../../reference/properties/topic-properties/#delete-retention-ms) setting is applied to these markers. For topics with a `compact` only cleanup policy, you must explicitly set `delete.retention.ms` at the topic level. This feature is not applied when Tiered Storage is enabled. See [Transactional control batch removal](../../manage/cluster-maintenance/compaction-settings/#transactional-control-batch-removal). ## [](#suggested-reading)Suggested reading - [Kafka-compatible fast distributed transactions](https://redpanda.com/blog/fast-transactions) ## Suggested labs - [Stream Stock Market Data from a CSV file Using Node.js](/redpanda-labs/clients/stock-market-activity-nodejs/) - [Stream Stock Market Data from a CSV file Using Python](/redpanda-labs/clients/stock-market-activity-python/) - [Build a Chat Room Application with Redpanda and Java](/redpanda-labs/clients/docker-java/) - [Build a Chat Room Application with Redpanda and Golang](/redpanda-labs/clients/docker-go/) - [Build a Chat Room Application with Redpanda and Node.js](/redpanda-labs/clients/docker-nodejs/) - [Build a Chat Room Application with Redpanda and Python](/redpanda-labs/clients/docker-python/) - [Build a Chat Room Application with Redpanda and Rust](/redpanda-labs/clients/docker-rust/) See more [Search all labs](/redpanda-labs) --- # Page 85: Get Started **URL**: https://docs.redpanda.com/current/get-started.md --- # Get Started --- title: Get Started latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/get-started/pages/index.adoc description: Get Started index page. page-git-created-date: "2023-05-30" page-git-modified-date: "2023-08-21" support-status: supported --- - [What’s New](release-notes/) Summary of new features and updates. - [Introduction to Redpanda](intro-to-events/) Learn about Redpanda event streaming. - [How Redpanda Works](architecture/) Learn specifics about Redpanda architecture. - [Introduction to Redpanda Console](../console/) Learn about Redpanda Console: a web interface for managing and interacting with Redpanda clusters. - [Redpanda Quickstarts](quickstarts/) Get started with Redpanda using these hands-on tutorials. Explore features that demonstrate how Redpanda can power your streaming applications. - [Redpanda Licensing](licensing/) - [Redpanda CLI](rpk/) The `rpk` command line interface tool lets you manage your Redpanda cluster, without the need to run a separate script for each function, as with Apache Kafka. - [Partner Integrations](partner-integration/) Learn about Redpanda integrations built and supported by our partners. --- # Page 86: Specify Admin API Addresses for rpk **URL**: https://docs.redpanda.com/current/get-started/admin-addresses.md --- # Specify Admin API Addresses for rpk --- title: Specify Admin API Addresses for rpk latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: admin-addresses page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: admin-addresses.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/get-started/pages/admin-addresses.adoc description: Learn how and when to specify Redpanda admin addresses for rpk commands, so rpk knows where to run admin-related commands. page-git-created-date: "2024-07-24" page-git-modified-date: "2024-07-24" support-status: supported --- For `rpk` to know where to run admin-related commands, you must provide the admin server addresses for each broker of a Redpanda cluster. You can specify these addresses as IP addresses or as hostnames, using any of these methods: - Command line flag (`-X admin.hosts`) - Environment variable setting (`RPK_ADMIN_HOSTS`) - Configuration file setting in `redpanda.yaml` (`rpk.admin_api.addresses`) Command line flag settings take precedence over environment variable settings and configuration file settings. If the command line does not contain the `-X admin.hosts` settings, the environment variable settings are used. If the environment variables are not set, the values in the configuration file are used. ## [](#command-line-flags)Command line flags Admin API addresses are required for communicating with the Admin API. Provide these addresses with the `—-api-urls` flag for commands related to cluster or user tasks, such as [`rpk cluster health`](../../reference/rpk/rpk-cluster/rpk-cluster-health/) and [`rpk cluster maintenance enable `](../../reference/rpk/rpk-cluster/rpk-cluster-maintenance/). Note that `rpk cluster info` and `rpk cluster metadata` instead require the [`-X brokers` flag](../broker-admin/). The following table shows which `rpk` commands require the `-X admin.hosts` or `--hosts` flag. | Command | Address flag required | | --- | --- | | rpk security user | -X admin.hosts | | rpk cluster (all except rpk cluster info and rpk cluster metadata) | -X admin.hosts | | rpk redpanda admin | --hosts | ## [](#environment-variable-settings)Environment variable settings Environment variable settings last for the duration of the shell session, or until you set the variable to a different setting. Configure the environment variable `RPK_ADMIN_HOSTS`. For example, to configure the addresses to use when running Admin API commands on an external cluster with three brokers: ```bash export RPK_ADMIN_HOSTS="192.168.78.34:9644,192.168.78.35:9644,192.168.78.36:9644" ``` ## [](#configuration-file-settings)Configuration file settings As each Redpanda broker starts up, a `redpanda.yaml` configuration file is automatically generated for that broker. This file contains a section for `rpk` settings, which includes Admin API settings. The `admin_api` section contains the address and port for each admin server. The default address is `0.0.0.0`, and the default port is 9644. You can edit this line and replace it with the Admin API IP addresses. The following example shows the addresses and port numbers for two admin servers. ```yaml rpk: admin_api: - 192.168.72.34:9644 - 192.168.72.35:9644 ``` > 📝 **NOTE** > > If you do not update the default addresses in the `redpanda.yaml` file, you must provide the required addresses on the command line or by setting the corresponding environment variable. --- # Page 87: How Redpanda Works **URL**: https://docs.redpanda.com/current/get-started/architecture.md --- # How Redpanda Works --- title: How Redpanda Works latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: architecture page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: architecture.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/get-started/pages/architecture.adoc description: Learn specifics about Redpanda architecture. page-git-created-date: "2023-05-30" page-git-modified-date: "2025-08-15" support-status: supported --- At its core, Redpanda is a fault-tolerant transaction log for storing event streams. Producers and consumers interact with Redpanda using the Kafka API. To achieve high scalability, producers and consumers are fully decoupled. Redpanda provides strong guarantees to producers that events are stored durably within the system, and consumers can subscribe to Redpanda and read the events asynchronously. Redpanda achieves this decoupling by organizing events into topics. Topics represent a logical grouping of events that are written to the same log. A topic can have multiple producers writing events to it and multiple consumers reading events from it. This page provides details about how Redpanda works. For a high-level overview, see [Introduction to Redpanda](../intro-to-events/). ## [](#tiered-storage)Tiered Storage Redpanda Tiered Storage is a multi-tiered object storage solution that provides the ability to offload log segments to object storage in near real time. Tiered Storage can be combined with local storage to provide long-term data retention and disaster recovery on a per-topic basis. Consumers that read from more recent offsets continue to read from local storage, and consumers that read from historical offsets read from object storage, all with the same API. Consumers can read and reread events from any point within the maximum retention period, whether the events reside on local or object storage. As data in object storage grows, the metadata for it grows. To support efficient long-term data retention, Redpanda splits the metadata in object storage, maintaining metadata of only recently-updated segments in memory or local disk, while safely archiving the remaining metadata in object storage and caching it locally on disk. Archived metadata is then loaded only when historical data is accessed. This allows Tiered Storage to handle partitions of virtually any size or retention length. For more information, see [Tiered Storage](../../manage/tiered-storage/). ## [](#partitions)Partitions To scale topics, Redpanda shards them into one or more partitions that are distributed across the nodes in a cluster. This allows for concurrent writing and reading from multiple nodes. When producers write to a topic, they route events to one of the topic’s partitions. Events with the same key (like a stock ticker) are always routed to the same partition, and Redpanda guarantees the order of events at the partition level. Consumers read events from a partition in the order that they were written. If a key is not specified, then events are sent to all topic partitions in a round-robin fashion. ## [](#raft-consensus-algorithm)Raft consensus algorithm Redpanda provides strong guarantees for data safety and fault tolerance. Events written to a topic partition are appended to a log file on disk. They can be replicated to other nodes in the cluster and appended to their copies of the log file on disk to prevent data loss in the event of failure. The [Raft consensus algorithm](https://raft.github.io/) is used for data replication. Every topic partition forms a Raft group consisting of a single elected leader and zero or more followers (as specified by the topic’s replication factor). A Raft group can tolerate ƒ failures given 2ƒ+1 nodes. For example, in a cluster with five nodes and a topic with a replication factor of five, the topic remains fully operational if two nodes fail. Raft is a majority vote algorithm. For a leader to acknowledge that an event has been committed to a partition, a majority of its replicas must have written that event to their copy of the log. When a majority (quorum) of responses have been received, the leader can make the event available to consumers and acknowledge receipt of the event when `acks=all (-1)`. [Producer acknowledgement settings](../../develop/produce-data/configure-producers/#producer-acknowledgement-settings) define how producers and leaders communicate their status while transferring data. As long as the leader and a majority of the replicas are stable, Redpanda can tolerate disturbances in a minority of the replicas. If [gray failures](https://blog.acolyer.org/2017/06/15/gray-failure-the-achilles-heel-of-cloud-scale-systems/) cause a minority of replicas to respond slower than normal, then the leader does not have to wait for their responses to progress, and any additional latency is not passed on to the clients. The result is that Redpanda is less sensitive to faults and can deliver predictable performance. ## [](#partition-leadership-elections)Partition leadership elections [Raft](https://raft.github.io/) uses a heartbeat mechanism to maintain leader authority and to trigger leader elections. The partition leader sends a periodic heartbeat to all followers to assert its leadership in the current term (default = 150 milliseconds). A term is an arbitrary period of time that starts when a leader election is triggered. If a follower does not receive a heartbeat over a period of time (default = 1.5 seconds), then it triggers an election to choose a new partition leader. The follower increments its term and votes for itself to be the leader for that term. It then sends a vote request to the other nodes and waits for one of the following scenarios: - It receives a majority of votes and becomes the leader. Raft guarantees that at most one candidate can be elected the leader for a given term. - Another follower establishes itself as the leader. While waiting for votes, the candidate may receive communication from another node in the group claiming to be the leader. The candidate only accepts the claim if its term is greater than or equal to the candidate’s term; otherwise, the communication is rejected and the candidate continues to wait for votes. - No leader is elected over a period of time. If multiple followers timeout and become election candidates at the same time, it’s possible that no candidate gets a majority of votes. When this happens, each candidate increments its term and triggers a new election round. Raft uses a random timeout between 150-300 milliseconds to ensure that split votes are rare and resolved quickly. As long as there is a timing inequality between heartbeat time, election timeout, and mean time between node failures (MTBF), then Raft can elect and maintain a steady leader and make progress. A leader can maintain its position as long as one of the ten heartbeat messages it sends to all of its followers every 1.5 seconds is received; otherwise, a new leader is elected. If a follower triggers an election, but the incumbent leader subsequently springs back to life and starts sending data again, then it’s too late. As part of the election process, the follower (now an election candidate) incremented the term and rejects requests from the previous term, essentially forcing a leadership change. If a cluster is experiencing wider network infrastructure problems that result in latencies above the heartbeat timeout, then back-to-back election rounds can be triggered. During this period, unstable Raft groups may not be able to form a quorum. This results in partitions rejecting writes, but data previously written to disk is not lost. Redpanda has a Raft-priority implementation that allows the system to settle quickly after network outages. ## [](#controller-partition-and-snapshots)Controller partition and snapshots Redpanda stores metadata update commands (such as creating and deleting topics or users) in a system partition called the controller partition. A new snapshot is created after each controller command is added, or, with rapid updates, after a set period of time (default is 60 seconds). Controller snapshots save the current cluster metadata state to disk, so startup is fast. For example, with a partition that has moved several times, a snapshot can restore the latest state without replaying every move command. Each broker has a snapshot file stored in the controller log directory, such as `/var/lib/redpanda/data/redpanda/controller/0_0/snapshot`. The controller partition is replicated by a Raft group that includes all cluster brokers, and the controller snapshot is the Raft snapshot for this group. Snapshots are hydrated when a broker joins the cluster or restarts. Snapshots are enabled by default for all clusters, both new and upgraded. ## [](#optimized-platform-performance)Optimized platform performance Redpanda is designed to exploit advances in modern hardware, from the network down to the disks. Network bandwidth has increased considerably, especially in object storage, and spinning disks have been replaced by SSD devices that deliver better I/O performance. CPUs are faster too, but this is largely due to the increased core counts as opposed to the increase in single-core speeds. Redpanda has tuners that detect your hardware configuration to automatically optimize itself. Examples of platform and kernel features that Redpanda uses to optimize its performance: - Direct Memory Access (DMA) for disk I/O - Sparse file system support with XFS - Distribution of interrupt request (IRQ) processing between CPU cores - Isolated processes with control groups (cgroups) - Disabled CPU power-saving modes - Upfront memory allocation, partitioned and pinned to CPU cores ## [](#tpc)Thread-per-core model Redpanda implements a thread-per-core programming model through its use of the [Seastar](https://seastar.io/) library. This allows Redpanda to pin each of its application threads to a CPU core to avoid context switching and blocking. It combines this with structured message passing (SMP) to asynchronously communicate between the pinned threads. With this, Redpanda avoids the overhead of context switching and expensive locking operations to improve processing performance and efficiency. From a sizing perspective, Redpanda’s ability to efficiently use all available hardware enables it to scale up to get the most out of your infrastructure, before you’re forced to scale out to meet the demands of your workload. Redpanda delivers better performance with a smaller footprint, resulting in reduced operational costs and complexity. ## [](#next-steps)Next steps [Try out Redpanda](../quick-start/), or learn about [Redpanda Licensing](../licensing/). ## [](#suggested-reading)Suggested reading - [A developer’s guide to Redpanda](https://redpanda.com/blog/data-streaming-with-redpanda) - [How Redpanda’s cloud-first storage model reduces TCO](https://redpanda.com/blog/cloud-native-streaming-data-lower-cost) - [Thread-per-core buffer management for a modern Kafka-API storage system](https://redpanda.com/blog/tpc-buffers?utm_medium=content&utm_assetname=sizing_guide&utm_assettype=report&utm_source=gated_content&utm_campaign=tpc_architecture_blog) ## [](#suggested-videos)Suggested videos - [YouTube - Lightning Talk: Tiered Storage (11:39 mins)](https://www.youtube.com/watch?v=3_Tmdvrp5sU&ab_channel=RedpandaData) - [YouTube - Intro to Redpanda: Thread-per-core architecture in C++ (60 mins)](https://www.youtube.com/watch?v=guoaxRJG8p8&ab_channel=RedpandaData) - [YouTube - Differences between Apache Kafka and Redpanda: Thread per Core Architecture (4:30 mins)](https://www.youtube.com/watch?v=UxM1mn1gwoc&ab_channel=RedpandaData) - [YouTube - Common pitfalls for Redpanda beginners (44:35 mins)](https://www.youtube.com/watch?v=CEVxZznqTDo&ab_channel=RedpandaData) --- # Page 88: Specify Broker Addresses for rpk **URL**: https://docs.redpanda.com/current/get-started/broker-admin.md --- # Specify Broker Addresses for rpk --- title: Specify Broker Addresses for rpk latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: broker-admin page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: broker-admin.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/get-started/pages/broker-admin.adoc description: Learn how and when to specify Redpanda broker addresses for rpk commands, so rpk knows where to run Kafka-related commands. page-git-created-date: "2023-07-24" page-git-modified-date: "2025-05-07" support-status: supported --- For `rpk` to know where to run Kafka-related commands, you must provide the broker addresses for each broker of a Redpanda cluster. You can specify these addresses as IP addresses or as hostnames, using any of these methods: - Command line flag (`-X brokers`) - Environment variable setting (`RPK_BROKERS`) - Configuration file setting in `redpanda.yaml` (`rpk.kafka_api.brokers`) Command line flag settings take precedence over environment variable settings and configuration file settings. If the command line does not contain the `-X brokers` settings, the environment variable settings are used. If the environment variables are not set, the values in the configuration file are used. ## [](#command-line-flags)Command line flags Broker addresses are required for communicating with the Kafka API. Provide these addresses with the `-X brokers` flag for commands related to Kafka broker tasks, such as [`rpk topic create`](../../reference/rpk/rpk-topic/rpk-topic-create/), [`rpk topic produce`](../../reference/rpk/rpk-topic/rpk-topic-produce/), and [`rpk topic consume`](../../reference/rpk/rpk-topic/rpk-topic-consume/). The following table shows which `rpk` commands require the `-X brokers` flag. | Command | Address flag required | | --- | --- | | rpk cluster info | -X brokers | | rpk cluster metadata | -X brokers | | rpk group | -X brokers | | rpk security acl | -X brokers | | rpk topic | -X brokers | ## [](#environment-variable-settings)Environment variable settings Environment variable settings last for the duration of the shell session, or until you set the variable to a different setting. Configure the environment variable `RPK_BROKERS` for broker addresses, so you don’t have to include the `-X brokers` flag each time you run an `rpk` command. For example, to configure three brokers on a single machine running on localhost: ```bash export RPK_BROKERS="192.168.72.34:9092,192.168.72.35:9092,192.168.72.36.9092" ``` ## [](#configuration-file-settings)Configuration file settings As each Redpanda broker starts up, a `redpanda.yaml` configuration file is automatically generated for that broker. This file contains a section for `rpk` settings, which includes Kafka API settings. The `kafka_api` section contains the address and port for each broker. The default address is `0.0.0.0`, and the default port is 9092. You can edit this line and replace it with the IP addresses of your Redpanda brokers. The following example shows the addresses and port numbers for three brokers. ```yaml rpk: kafka_api: brokers: - 192.168.72.34:9092 - 192.168.72.35:9092 - 192.168.72.36.9092 ``` > 📝 **NOTE** > > If you do not update the default addresses in the `redpanda.yaml` file, you must provide the required addresses on the command line or by setting the corresponding environment variable. --- # Page 89: rpk Profiles **URL**: https://docs.redpanda.com/current/get-started/config-rpk-profile.md --- # rpk Profiles --- title: rpk Profiles latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: config-rpk-profile page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: config-rpk-profile.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/get-started/pages/config-rpk-profile.adoc description: Use rpk profile to simplify your development experience with multiple Redpanda clusters by saving and reusing configurations for different clusters. page-git-created-date: "2023-07-31" page-git-modified-date: "2025-08-22" support-status: supported --- Use rpk profiles to simplify your development experience using `rpk` with multiple Redpanda clusters by saving and reusing configurations for different clusters. > 💡 **TIP** > > **rpk profiles are the recommended way to configure rpk**. They provide persistent, reusable configurations that work across sessions and are easier to manage than environment variables or command-line flags. > ⚠️ **CAUTION** > > Profile files may contain sensitive information such as passwords or SASL credentials. Do not commit `rpk.yaml` files to version control systems like Git. ## [](#about-rpk-profiles)About rpk profiles An rpk profile contains a reusable configuration for a Redpanda cluster. When running `rpk`, you can create a profile, configure it for a cluster you’re working with, and use it repeatably when running an `rpk` command for the cluster. You can create different profiles for different Redpanda clusters. For example, your local cluster, development cluster, and production cluster can each have their own profile, with all of their information managed locally by rpk. You set a unique name for each profile. A profile saves rpk-specific command properties. For details, see [Specify command properties](../intro-to-rpk/#specify-configuration-properties). All `rpk` commands can read configuration values from a profile. You pass a profile to an `rpk` command by setting the `--profile` flag. For example, the command `rpk topic produce dev-topic --profile dev` gets its configuration from the profile named `dev`. ## [](#quickstart)Quickstart Create a profile with authentication and TLS to quickly set up cluster access instead of using environment variables or connection flags: ```bash rpk profile create \ --set brokers= \ --set admin.hosts= \ --set user= \ --set pass= \ --set sasl.mechanism= \ --set tls.enabled=true \ --description "" ``` Replace `` with your desired SASL mechanism (`SCRAM-SHA-256`, `SCRAM-SHA-512`, or `PLAIN`). When you create a profile, rpk automatically switches to use that profile so you don’t need to pass `--profile` flags every time. Check the active profile: ```bash rpk profile current ``` Now all `rpk` commands use this profile automatically: ```bash rpk topic list rpk topic create ``` You can change profiles by running: ```bash rpk profile use ``` For environment variables and other configuration methods, see [rpk -X options](../../reference/rpk/rpk-x-options/). ## [](#work-with-rpk-profiles)Work with rpk profiles The primary tasks for working with rpk profiles: - Create one or more profiles. - Choose the profile to use. - Edit or set default values across all profiles and values for a single profile. - Call an `rpk` command with a profile. - Delete unused profiles. ### [](#create-profile)Create profile To create a new profile, run [`rpk profile create`](../../reference/rpk/rpk-profile/rpk-profile-create/): ```bash rpk profile create [flags] ``` An rpk profile can be generated from different sources: - A `redpanda.yaml` file, using the `--from-redpanda` flag. - A different rpk profile, using the `--from-profile` flag. After the profile is created, rpk switches to the newly created profile. You can specify the configuration during creation with the `--set [key=value]` flag. To simplify configuration, the `--set` flag supports autocompletion of valid keys, suggesting key names based on their `-X` format. > 📝 **NOTE** > > You should always use and set the `--description` flag to describe your profiles. The description is printed in the output of [`rpk profile list`](../../reference/rpk/rpk-profile/rpk-profile-list/). Created profiles are stored in an `rpk.yaml` file in a default local OS directory (for example, `~/.config/rpk/` for Linux and `~/Library/Application Support/rpk/` for MacOS). All profiles created by a developer are stored in the same `rpk.yaml` file. ### [](#choose-profile-to-use)Choose profile to use With multiple created profiles, choose the profile to use with [`rpk profile use`](../../reference/rpk/rpk-profile/rpk-profile-use/): ```bash rpk profile use ``` ### [](#set-or-edit-configuration-values)Set or edit configuration values You can customize settings for a single profile. To set a profile’s configuration: - Use [`rpk profile set`](../../reference/rpk/rpk-profile/rpk-profile-set/) to set `key=value` pairs of configuration options to write to the profile’s section of `rpk.yaml`. - Use [`rpk profile edit`](../../reference/rpk/rpk-profile/rpk-profile-edit/) to edit the profile’s section of the `rpk.yaml` file in your default editor. You can configure settings that apply to all profiles. To set these `globals`: - Use [`rpk profile set-globals`](../../reference/rpk/rpk-profile/rpk-profile-set-globals/) to set `key=value` pairs to write to the globals section of `rpk.yaml`. - Use [`rpk profile edit-globals`](../../reference/rpk/rpk-profile/rpk-profile-edit-globals/) to edit the globals section of the `rpk.yaml` file in your default editor. > 💡 **TIP** > > For a list of all the available properties that can be set in your profile, see [`rpk -X options`](../../reference/rpk/rpk-x-options/). #### [](#customize-command-prompt-per-profile)Customize command prompt per profile A configurable field of an rpk profile is the `prompt` field. It enables the customization of the command prompt for a profile, so information about the in-use profile can be displayed within your command prompt. The format string is intended for a `PS1` prompt. For details on the prompt format string, see the [`rpk profile prompt`](../../reference/rpk/rpk-profile/rpk-profile-prompt/) reference. The `rpk profile prompt` command prints the ANSI-escaped text of the `prompt` field for the in-use profile. You can call `rpk profile prompt` in your shell’s (rc) configuration file to assign your `PS1`. For example, to customize your bash prompt for a `dev` rpk profile , first call `rpk profile edit dev` to set its `prompt` field: ```yaml name: dev prompt: hi-red, "[%n]" ``` - `hi-red` sets the text to high-intensity red - `%n` is a variable for the profile name Then in `.bashrc`, set `PS1` to include a call to `rpk profile prompt`: ```bash export PS1='\u@\h\n$(rpk profile prompt)% ' ``` > 📝 **NOTE** > > When setting your `PS1` variable, use single quotation marks and not double quotation marks, because double quotation marks aren’t reevaluated after every command. The resulting prompt looks like this: username@hostname\[dev\]% ### [](#use-profile-with-rpk-command)Use profile with `rpk` command An rpk command that can use a profile supports the `--profile ` flag. When the `--profile` flag is set for an rpk command, the configuration for the cluster that rpk is interfacing with will be read from the named profile. See the [rpk commands reference](../../reference/rpk/) for commands that support profiles. ### [](#delete-profile)Delete profile To delete a profile, run [`rpk profile delete`](../../reference/rpk/rpk-profile/rpk-profile-delete/). ## [](#related-topics)Related topics For details about all commands for rpk profiles, see the [`rpk profile`](../../reference/rpk/rpk-profile/rpk-profile/) reference page and its sub-pages. --- # Page 90: Docker Compose Labs **URL**: https://docs.redpanda.com/current/get-started/docker-compose-labs.md --- # Docker Compose Labs --- title: Docker Compose Labs latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: docker-compose-labs page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: docker-compose-labs.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/get-started/pages/docker-compose-labs.adoc description: Explore this collection of hands-on labs for deploying and testing Redpanda Self-Managed using Docker Compose. Whether you're a beginner looking to get started or an experienced user aiming to deepen your knowledge, these labs provide step-by-step instructions and practical examples to enhance your skills. page-git-created-date: "2024-12-12" page-git-modified-date: "2024-12-12" support-status: supported --- Explore this collection of hands-on labs for deploying and testing Redpanda Self-Managed using Docker Compose. Whether you’re a beginner looking to get started or an experienced user aiming to deepen your knowledge, these labs provide step-by-step instructions and practical examples to enhance your skills. - [Disaster Recovery with Envoy and Shadowing](../../../redpanda-labs/docker-compose/envoy-shadowing/) Combine Redpanda Shadowing for data replication with Envoy proxy for transparent client routing during disaster recovery. - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](../../../redpanda-labs/docker-compose/oidc/) Integrate Azure Entra ID with Redpanda and Redpanda Console for unified identity using OpenID Connect (OIDC). - [Migrate Data with Redpanda Migrator](../../../redpanda-labs/docker-compose/redpanda-migrator/) Migrate data, schemas, and consumer offsets from a source Kafka cluster to a target Redpanda cluster using Redpanda Migrator. - [Owl Shop Example Application in Docker](../../../redpanda-labs/docker-compose/owl-shop/) Manage and monitor applications in Redpanda Console using data from an example e-commerce application called owl shop. - [Redpanda Iceberg Docker Compose Example](../../../redpanda-labs/docker-compose/iceberg/) Pair Redpanda with MinIO for Tiered Storage and write data in the Iceberg format to enable seamless analytics workflows on data in Redpanda topics. - [Set Up MySQL CDC with Debezium and Redpanda](../../../redpanda-labs/docker-compose/cdc-mysql-json/) Use Debezium to capture the changes made to a MySQL database in real time and stream them to Redpanda. - [Set Up Postgres CDC with Debezium and Redpanda](../../../redpanda-labs/docker-compose/cdc-postgres-json/) Use Debezium to capture the changes made to a Postgres database in real time and stream them to Redpanda. - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](../../../redpanda-labs/docker-compose/three-brokers/) Start three Redpanda brokers and Redpanda Console to start developing your application on Redpanda locally. - [Start a Single Redpanda Broker with Redpanda Console in Docker](../../../redpanda-labs/docker-compose/single-broker/) Start a single Redpanda broker and Redpanda Console to start developing your application on Redpanda locally. - [Stream Jira Issues to Redpanda for Real-Time Metrics](../../../redpanda-labs/docker-compose/jira-metrics-pipeline/) Build a real-time Jira metrics pipeline using Redpanda Connect and Redpanda to track development performance, SLA compliance, and team productivity. --- # Page 91: Introduction to Redpanda **URL**: https://docs.redpanda.com/current/get-started/intro-to-events.md --- # Introduction to Redpanda --- title: Introduction to Redpanda latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: intro-to-events page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: intro-to-events.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/get-started/pages/intro-to-events.adoc description: Learn about Redpanda event streaming. page-git-created-date: "2023-05-30" page-git-modified-date: "2025-05-07" support-status: supported --- Distributed systems often require data and system updates to happen as quickly as possible. In software architecture, these updates can be handled with either messages or events. - With messages, updates are sent directly from one component to another to trigger an action. - With events, updates indicate that an action occurred at a specific time, and are not directed to a specific recipient. An event is simply a record of something changing state. For example, the event of a credit card transaction includes the product purchased, the payment, the delivery, and the time of the purchase. The event occurred in the purchasing component, but it also impacted the inventory, the payment processing, and the shipping components. In an event-driven architecture, all actions are defined and packaged as events to precisely identify individual actions and how they’re processed throughout the system. Instead of processing updates in consecutive order, event-driven architecture lets components process events at their own pace. This helps developers build fast and scalable systems. ## [](#what-is-redpanda)What is Redpanda? Redpanda is an event streaming platform: it provides the infrastructure for streaming real-time data. Producers are client applications that send data to Redpanda in the form of events. Redpanda safely stores these events in sequence and organizes them into topics, which represent a replayable log of changes in the system. Consumers are client applications that subscribe to Redpanda topics to asynchronously read events. Consumers can store, process, or react to the events. Redpanda decouples producers from consumers to allow for asynchronous event processing, event tracking, event manipulation, and event archiving. Producers and consumers interact with Redpanda using the Apache Kafka® API. ![Producers and consumers in a cluster](../../shared/_images/cluster.png) | Event-driven architecture (Redpanda) | Message-driven architecture | | --- | --- | | Producers send events to an event processing system (Redpanda) that acknowledges receipt of the write. This guarantees that the write is durable within the system and can be read by multiple consumers. | Producers send messages directly to each consumer. The producer must wait for acknowledgement that the consumer received the message before it can continue with its processes. | Event streaming lets you extract value out of each event by analyzing, mining, or transforming it for insights. You can: - Take one event and consume it in multiple ways. - Replay events from the past and route them to new processes in your application. - Run transformations on the data in real-time or historically. - Integrate with other event processing systems that use the Kafka API. ## [](#redpanda-differentiators)Redpanda differentiators Redpanda is less complex and less costly than any other commercial mission-critical event streaming platform. It’s fast, it’s easy, and it keeps your data safe. - Redpanda is designed for maximum performance on any data streaming workload. It can scale up to use all available resources on a single machine and scale out to distribute performance across multiple nodes. Built on C++, Redpanda delivers greater throughput and up to 10x lower p99 latencies than other platforms. This enables previously unimaginable use cases that require high throughput, low latency, and a minimal hardware footprint. - Redpanda is packaged as a single binary: it doesn’t rely on any external systems. It’s compatible with the Kafka API, so it works with the full ecosystem of tools and integrations built on Kafka. Redpanda can be deployed on bare metal, containers, or virtual machines in a data center or in the cloud. And Redpanda Console makes it easy to set up, manage, and monitor your clusters. Additionally, Tiered Storage lets you offload log segments to object storage in near real-time, providing long-term data retention and topic recovery. - Redpanda uses the [Raft consensus algorithm](https://raft.github.io/) throughout the platform to coordinate writing data to log files and replicating that data across multiple servers. Raft facilitates communication between the nodes in a Redpanda cluster to make sure that they agree on changes and remain in sync, even if a minority of them are in a failure state. This allows Redpanda to tolerate partial environmental failures and deliver predictable performance, even at high loads. - Redpanda provides data sovereignty. With the Bring Your Own Cloud (BYOC) offering, you deploy Redpanda in your own virtual private cloud, and all data is contained in your environment. Redpanda handles provisioning, monitoring, and upgrades, but you manage your streaming data without Redpanda’s control plane ever seeing it. ## [](#redpanda-self-managed-versions)Redpanda Self-Managed versions You can deploy Redpanda in a self-hosted environment (Redpanda Self-Managed) or as a fully managed cloud service (Redpanda Cloud). Redpanda Self-Managed version numbers follow the convention AB.C.D, where AB is the two-digit year, C is the feature release, and D is the patch release. For example, version 22.3.1 indicates the first patch release on the third feature release of the year 2022. Patch releases include bug fixes and minor improvements, with no change to user-facing behavior. New and enhanced features are documented with each feature release. Redpanda Cloud releases on a continuous basis and uptakes Redpanda Self-Managed versions. ## [](#next-steps)Next steps - To spin up a Redpanda cluster to try it out, see [Redpanda Quickstart](../quick-start/). - To learn more about Redpanda, see [How Redpanda Works](../architecture/). - For information about a Redpanda Self-Managed deployment, see [Redpanda Licensing](../licensing/overview/). - For information about a Redpanda Cloud deployment, see [Redpanda Cloud Overview](../../../redpanda-cloud/get-started/cloud-overview/). ## [](#suggested-reading)Suggested reading - [Upgrade your data streaming: a beginner’s guide to Redpanda](https://redpanda.com/blog/data-streaming-with-redpanda) - [Develop real-time apps faster and simpler with Redpanda](https://redpanda.com/blog/real-time-streaming-data-kafka-vs-redpanda?utm_assettype=blog&utm_assetname=redpanda_vs_kafka&utm_source=blog&utm_medium=content&utm_campaign=pillar_streaming_101) - [Free guide - Migrating from Kafka to Redpanda](https://go.redpanda.com/how-to-migrate-from-kafka-to-redpanda?utm_assettype=report&utm_assetname=migration_guide&utm_source=blog&utm_medium=content&utm_campaign=pillar_streaming_101) - [On-demand workshop - Get started with Redpanda](https://go.redpanda.com/virtual-workshop-april-2023?utm_assettype=workshop&utm_assetname=get_started_redpanda&utm_source=blog&utm_medium=content&utm_campaign=pillar_streaming_101) - [Redpanda University - A hands-on guide to Redpanda](https://university.redpanda.com/courses/hands-on-redpanda-getting-started) ## [](#suggested-videos)Suggested videos - [YouTube - Redpanda in a Nutshell (6:36 mins)](https://www.youtube.com/watch?v=FEVL8cLUFOc&ab_channel=RedpandaData) --- # Page 92: Introduction to rpk **URL**: https://docs.redpanda.com/current/get-started/intro-to-rpk.md --- # Introduction to rpk --- title: Introduction to rpk latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: intro-to-rpk page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: intro-to-rpk.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/get-started/pages/intro-to-rpk.adoc description: Learn about rpk and how to use it to interact with your Redpanda cluster. page-git-created-date: "2023-07-24" page-git-modified-date: "2025-08-21" support-status: supported --- The `rpk` command line interface tool is designed to manage your entire Redpanda cluster, without the need to run a separate script for each function, as with Apache Kafka. The `rpk` commands handle everything from configuring brokers to high-level general Redpanda tasks. For example, you can use `rpk` to monitor your cluster’s health, perform tuning, and implement access control lists (ACLs) and other security features. You can also use `rpk` to perform basic streaming tasks, such as creating topics, producing to topics, and consuming from topics. After you install `rpk`, you can use it to: - Manage Redpanda - Set up access control lists (ACLs) and other security features - Create topics, produce to topics, and consume from topics See also: - [Install or Update rpk](../rpk-install/) - [rpk Profiles](../config-rpk-profile/) - [Redpanda CLI Quickstart](../rpk-quickstart/) ## [](#specify-configuration-properties)Specify configuration properties You can specify `rpk` command properties in the following ways: - Create an [`rpk profile`](../config-rpk-profile/). - Specify the appropriate flag on the command line. - Define the corresponding [environment variables](#environment-variables). Environment variable settings only last for the duration of a shell session. Command line flag settings take precedence over the corresponding environment variables, and environment variables take precedence over configuration file settings. If a required flag is not specified on the command line, Redpanda searches the environment variable. If the environment variable is not set, the value in the `rpk.yaml` configuration file is used, if that file is available, otherwise the value in the `redpanda.yaml` configuration file is used. > 💡 **TIP** > > If you specify `rpk` command properties in the configuration files or as environment variables, you don’t need to specify them again on the command line. ### [](#common-configuration-properties)Common configuration properties Every `rpk` command supports a set of common configuration properties. You can set one or more options in an `rpk` command by using the `-X` flag: ```bash rpk -X -X ``` Get a list of available options with `-X list`: ```bash rpk -X list ``` Or, get a detailed description about each option with `-X help`: ```bash rpk -X help ``` Every `-X` option can be translated into an environment variable by prefixing it with `RPK_` and replacing periods (`.`) with underscores (`_`). For example, the flag `tls.enabled` has the equivalent environment variable `RPK_TLS_ENABLED`. Some of the common configuration properties apply across all `rpk` commands as defaults. These default properties have keys with names starting with `globals`, and they’re viewable in `rpk -X list` and `rpk -X help`. For more details, see [`rpk -X options`](../../reference/rpk/rpk-x-options/). ### [](#environment-variables)Environment variables `rpk` supports environment variables through `RPK_*` that correspond to `-X` options. For a comprehensive list and configuration examples, see: - [rpk profiles](../config-rpk-profile/) - Create and manage persistent configurations (recommended) - [rpk -X options](../../reference/rpk/rpk-x-options/) - Complete configuration reference including environment variables ## [](#next-steps)Next steps - [Install or Update rpk](../rpk-install/) - [rpk Command reference](../../reference/rpk/) --- # Page 93: Redpanda Licensing **URL**: https://docs.redpanda.com/current/get-started/licensing.md --- # Redpanda Licensing --- title: Redpanda Licensing latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: licensing/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: licensing/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/get-started/pages/licensing/index.adoc page-git-created-date: "2024-12-03" page-git-modified-date: "2024-12-03" support-status: supported --- - [Redpanda Licenses and Enterprise Features](overview/) Learn about Redpanda licensing for Redpanda, Redpanda Console, and Redpanda Connect, available in both Community and Enterprise editions. Understand licensing requirements and how to access enterprise features with a valid license key. - [Add an Enterprise Edition License to Redpanda](add-license-redpanda/) Learn how to add an Enterprise Edition license to Redpanda Self-Managed. - [Add an Enterprise Edition License to Redpanda Console](add-license-console/) Learn how to add a license to Redpanda Console using one of these provided options. - [Check the Status of Licenses](check-status/) Explore the options for checking and monitoring the status of your Redpanda Enterprise Edition license. - [Disable Enterprise Features in Redpanda](disable-enterprise-features/) Disable specific enterprise features in Redpanda to ensure your cluster operates within the scope of the Community Edition without enterprise features. --- # Page 94: Add an Enterprise Edition License to Redpanda Console **URL**: https://docs.redpanda.com/current/get-started/licensing/add-license-console.md --- # Add an Enterprise Edition License to Redpanda Console --- title: Add an Enterprise Edition License to Redpanda Console latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: licensing/add-license-console page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: licensing/add-license-console.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/get-started/pages/licensing/add-license-console.adoc description: Learn how to add a license to Redpanda Console using one of these provided options. page-git-created-date: "2025-02-06" page-git-modified-date: "2025-02-06" support-status: supported --- Redpanda Console supports a number of options for adding an Enterprise Edition license. Choose the option that best fits your deployment: | Option | Description | Requirements | | --- | --- | --- | | Upload a license through the UI | Uses the UI to upload a license to Redpanda and Redpanda Console. | Redpanda Console must be connected to a Redpanda cluster. | | Load from the Redpanda cluster at startup (Linux or Kubernetes) | Automatically loads the license from the connected Redpanda cluster during startup, allowing centralized license management. | Redpanda Console must be connected to a Redpanda cluster that has a valid license installed. | | Configure a standalone license for Redpanda Console | Configures Redpanda Console with its own license. This option is best for deployments that are not connected to a Redpanda cluster. | You must add the license key to the Redpanda Console configuration file or an environment variable. | --- # Page 95: Add an Enterprise Edition License to Redpanda **URL**: https://docs.redpanda.com/current/get-started/licensing/add-license-redpanda.md --- # Add an Enterprise Edition License to Redpanda --- title: Add an Enterprise Edition License to Redpanda latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: licensing/add-license-redpanda/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: licensing/add-license-redpanda/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/get-started/pages/licensing/add-license-redpanda/index.adoc description: Learn how to add an Enterprise Edition license to Redpanda Self-Managed. page-git-created-date: "2024-12-03" page-git-modified-date: "2024-12-03" support-status: supported --- - [Add an Enterprise Edition License to Redpanda in Linux](linux/) Learn how to add or update a Redpanda Enterprise Edition license in a Linux environment. - [Add an Enterprise Edition License to Redpanda in Kubernetes](kubernetes/) Learn how to add or update a Redpanda Enterprise Edition license in a Kubernetes environment. - [Manage Enterprise Edition Licenses through Redpanda Console](../../../console/ui/add-license/) Learn how to manage Enterprise Edition licenses in Redpanda Console. --- # Page 96: Add an Enterprise Edition License to Redpanda in Kubernetes **URL**: https://docs.redpanda.com/current/get-started/licensing/add-license-redpanda/kubernetes.md --- # Add an Enterprise Edition License to Redpanda in Kubernetes --- title: Add an Enterprise Edition License to Redpanda in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: licensing/add-license-redpanda/kubernetes page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: licensing/add-license-redpanda/kubernetes.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/get-started/pages/licensing/add-license-redpanda/kubernetes.adoc description: Learn how to add or update a Redpanda Enterprise Edition license in a Kubernetes environment. page-git-created-date: "2024-12-03" page-git-modified-date: "2026-03-11" support-status: supported --- To enable [enterprise features for Redpanda Self-Managed](../../overview/), you must have an Enterprise Edition license. This guide outlines how to apply or update an Enterprise Edition license for Redpanda Self-Managed in a Kubernetes environment. ## [](#prerequisites)Prerequisites You must have an Enterprise Edition license. To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). ## [](#add-a-new-license)Add a new license Redpanda supports the following ways to apply a new license: - [Use a Kubernetes Secret to store the license](#secret). - [Provide the license string inline in your Helm values or manifest file](#inline). - [Use Redpanda Console to upload the license to Redpanda](#console). ### [](#secret)Use a Kubernetes Secret You can store the license in a Kubernetes Secret and reference it in your Helm values or manifest file. 1. Download your license file (`redpanda.license`) and create a Kubernetes Secret: ```bash kubectl create secret generic redpanda-license \ --from-file=license=./redpanda.license \ --namespace ``` This command creates a Kubernetes Secret named `redpanda-license` in the specified namespace, containing the license file. 2. Reference the Secret: #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: enterprise: licenseSecretRef: name: redpanda-license key: license ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `redpanda-license.yaml` ```yaml enterprise: licenseSecretRef: name: redpanda-license key: license ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values redpanda-license.yaml --reuse-values ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda \ --namespace \ --create-namespace \ --set enterprise.licenseSecretRef.name=redpanda-license \ --set enterprise.licenseSecretRef.key=license ``` ### [](#inline)Provide the license inline If you prefer to provide the license string directly, you can do so as follows: #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: enterprise: license: ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `redpanda-license.yaml` ```yaml enterprise: license: ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values redpanda-license.yaml --reuse-values ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda \ --namespace \ --create-namespace \ --set enterprise.license= ``` ### [](#console)Use Redpanda Console You can upload a license directly through Redpanda Console. See [Manage Enterprise Edition Licenses through Redpanda Console](../../../../console/ui/add-license/). ## [](#verify-a-license)Verify a license After adding or updating a license, you can use `rpk` to verify that the license was set. ```bash kubectl exec --namespace -c redpanda -- \ rpk cluster license info ``` This command will display the current license details, including the expiration date and whether any enterprise features are active. For example: LICENSE INFORMATION =================== Organization: redpanda Type: enterprise Expires: Oct 24 2027 > 📝 **NOTE** > > Redpanda blocks upgrades to new feature releases if enterprise features are active without a valid license. Ensure compliance by obtaining a license to maintain access to the latest features and updates. ## [](#update-an-existing-license)Update an existing license The process for updating a license depends on how it was originally applied: - [Update the Kubernetes Secret](#secret-update). - [Update the license string inline in your Helm values or manifest file](#inline-update). - [Use Redpanda Console](../../../../console/ui/add-license/) When a new license is uploaded, enterprise features in Redpanda Self-Managed are unlocked immediately without requiring a cluster restart. However, to unlock enterprise features in Redpanda Console, you must restart the Redpanda Console instance. ### [](#secret-update)Update the Kubernetes Secret If the license is provided through a Kubernetes Secret, follow these steps to update it: 1. Download the updated license file and overwrite the existing `redpanda.license` file. 2. Delete the existing Secret: ```bash kubectl delete secret redpanda-license --namespace ``` 3. Create a new Secret with a **new name** that contains the contents of the updated license: ```bash kubectl create secret generic redpanda-license-updated \ --from-file=license=./redpanda.license \ --namespace ``` 4. Update the Redpanda CRD to use the new Secret. `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: enterprise: licenseSecretRef: name: redpanda-license-updated key: license ``` 5. Apply the changes to the Redpanda CRD: ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` The Redpanda Operator updates the license without restarting the Repanda broker. 6. Check the status of the new license to make sure it was successfully applied: ```bash rpk cluster license info ``` The output displays the following details: Organization: Organization the license was generated for. Type: Type of license. Expires: Expiration date of the license. Version: License schema version. 7. If you use Redpanda Console, delete the Redpanda Console Pods to force Redpanda Console to reload the updated license: ```bash kubectl delete pod $(kubectl get pod --namespace | grep redpanda-console | awk '{print $1}') --namespace ``` ### [](#inline-update)Update the license inline If you applied the license inline, follow these steps to update it: 1. Modify the `enterprise.license` value with the new license string: #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: enterprise: license: ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `redpanda-license.yaml` ```yaml enterprise: license: ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values redpanda-license.yaml --reuse-values ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda \ --namespace \ --create-namespace \ --set enterprise.license= ``` 2. Check the status of new license to make sure it was successfully applied: ```bash rpk cluster license info ``` The output displays the following details: Organization: Organization the license was generated for. Type: Type of license:. Expires: Expiration date of the license. Version: License schema version. 3. If you use Redpanda Console, delete the Redpanda Console Pods to force a reload of the updated license: ```bash kubectl delete pod $(kubectl get pod --namespace | grep redpanda-console | awk '{print $1}') --namespace ``` ## [](#next-steps)Next steps [Check the Status of Licenses](../../check-status/). --- # Page 97: Add an Enterprise Edition License to Redpanda in Linux **URL**: https://docs.redpanda.com/current/get-started/licensing/add-license-redpanda/linux.md --- # Add an Enterprise Edition License to Redpanda in Linux --- title: Add an Enterprise Edition License to Redpanda in Linux latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: licensing/add-license-redpanda/linux page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: licensing/add-license-redpanda/linux.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/get-started/pages/licensing/add-license-redpanda/linux.adoc description: Learn how to add or update a Redpanda Enterprise Edition license in a Linux environment. page-git-created-date: "2024-12-03" page-git-modified-date: "2024-12-03" support-status: supported --- To enable [enterprise features for Redpanda Self-Managed](../../overview/), you must have an Enterprise Edition license. This guide outlines how to apply or update an Enterprise Edition license for Redpanda Self-Managed in a Linux environment. ## [](#prerequisites)Prerequisites - You must have [`rpk` installed](../../../rpk-install/) and configured to connect to your Redpanda cluster. - You must have an Enterprise Edition license. To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). ## [](#add-a-new-license)Add a new license Redpanda supports the following ways to apply a new license: - [Provide the path to a file containing the license](#file). - [Pass the license string directly](#inline). - [Use Redpanda Console to upload the license to Redpanda](#console). ### [](#file)Apply the license using a license file If you have the license key stored in a file, you can apply it by specifying the file path: ```bash rpk cluster license set --path -X admin.hosts= ``` Replace the following placeholders: - `` with the path to your license file. - `` the Redpanda admin host and port ### [](#inline)Apply the license using an inline license string If you want to provide the license string directly, use the following command: ```bash rpk cluster license set ``` If neither the path nor the license string are provided, `rpk` looks for the license in `/etc/redpanda/redpanda.license`. ### [](#console)Use Redpanda Console You can upload a license directly through Redpanda Console. See [Manage Enterprise Edition Licenses through Redpanda Console](../../../../console/ui/add-license/). ## [](#verify-a-license)Verify a license After adding or updating a license, you can use `rpk` to verify that the license was set. ```bash rpk cluster license info ``` This command will display the current license details, including the expiration date and whether any enterprise features are active. For example: LICENSE INFORMATION =================== Organization: redpanda Type: enterprise Expires: Oct 24 2027 > 📝 **NOTE** > > Redpanda blocks upgrades to new feature releases if enterprise features are active without a valid license. Ensure compliance by obtaining a license to maintain access to the latest features and updates. ## [](#update-an-existing-license)Update an existing license To update an existing license, you can use one the following methods: - [rpk cluster license set](../../../../reference/rpk/rpk-cluster/rpk-cluster-license-set/) - [Redpanda Console](../../../../console/ui/add-license/) When a new license is uploaded, enterprise features in Redpanda Self-Managed are unlocked immediately without requiring a cluster restart. However, to unlock enterprise features in Redpanda Console, you must restart the Redpanda Console instance. ## [](#next-steps)Next steps [Check the Status of Licenses](../../check-status/). ## [](#suggested-reading)Suggested reading [rpk cluster license set](../../../../reference/rpk/rpk-cluster/rpk-cluster-license-set/) --- # Page 98: Check the Status of Licenses **URL**: https://docs.redpanda.com/current/get-started/licensing/check-status.md --- # Check the Status of Licenses --- title: Check the Status of Licenses latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: licensing/check-status/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: licensing/check-status/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/get-started/pages/licensing/check-status/index.adoc description: Explore the options for checking and monitoring the status of your Redpanda Enterprise Edition license. page-git-created-date: "2024-12-17" page-git-modified-date: "2024-12-17" support-status: supported --- To track license expiration and ensure compliance with [Redpanda licensing](../overview/), you can monitor the status of your Enterprise Edition license using a variety of tools, such as `rpk`, Redpanda Console, and observability tools such as Prometheus metrics. - [Check License Status and Feature Usage with `rpk`](rpk/) Learn how to monitor the status of an Enterprise Edition license and enterprise feature usage with `rpk`. - [Check License Status and Feature Usage with Redpanda Operator](redpanda-operator/) Learn how to monitor the status of an Enterprise Edition license and enterprise feature usage in Kubernetes using the Redpanda Operator. - [Check License Status in Redpanda Console](../../../console/ui/check-license/) Learn how to check the status of your Redpanda Enterprise Edition license using the Redpanda Console. This topic includes steps to check license details and understand license warnings. - [Monitor a License Using Metrics](metrics/) Learn how to monitor the expiration status of your Redpanda Enterprise license using the `redpanda_cluster_features_enterprise_license_expiry_sec` metric. Set up alerts and integrate dashboards to ensure proactive license management. --- # Page 99: Monitor a License Using Metrics **URL**: https://docs.redpanda.com/current/get-started/licensing/check-status/metrics.md --- # Monitor a License Using Metrics --- title: Monitor a License Using Metrics latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: licensing/check-status/metrics page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: licensing/check-status/metrics.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/get-started/pages/licensing/check-status/metrics.adoc description: Learn how to monitor the expiration status of your Redpanda Enterprise license using the redpanda_cluster_features_enterprise_license_expiry_sec metric. Set up alerts and integrate dashboards to ensure proactive license management. page-git-created-date: "2024-12-17" page-git-modified-date: "2024-12-17" support-status: supported --- Redpanda exposes the [`redpanda_cluster_features_enterprise_license_expiry_sec`](../../../../reference/public-metrics-reference/#redpanda_cluster_features_enterprise_license_expiry_sec) metric to help you track the time remaining before your license expires. Example metric output ```promql # HELP redpanda_cluster_features_enterprise_license_expiry_sec Seconds remaining until the enterprise license expires. # TYPE redpanda_cluster_features_enterprise_license_expiry_sec gauge redpanda_cluster_features_enterprise_license_expiry_sec 2592000 ``` In this example, the metric indicates 2,592,000 seconds (30 days) remaining until the license expires. ## [](#prerequisites)Prerequisites Redpanda exposes metrics in the [Prometheus exposition format](https://prometheus.io/docs/instrumenting/exposition_formats/) through an HTTP `/metrics` endpoint. For help setting up Prometheus monitoring, see [Monitor Redpanda](../../../../manage/monitoring/) or [Monitor Redpanda in Kubernetes](../../../../manage/kubernetes/monitoring/k-monitor-redpanda/). ## [](#set-up-alerts)Set up alerts To avoid violating the terms of the enterprise license, configure alerts when the expiration time falls below a certain threshold. For example, to set up alerts with Prometheus: ```yaml groups: - name: Redpanda License Alerts rules: - alert: RedpandaLicenseExpiringSoon expr: redpanda_cluster_features_enterprise_license_expiry_sec < 604800 for: 1h labels: severity: warning annotations: summary: "Redpanda license is expiring in less than 7 days" description: "The Redpanda Enterprise license will expire soon. Renew the license to avoid feature restrictions." ``` ## [](#integrate-with-dashboards)Integrate with dashboards Use visualization tools like Grafana to create a dashboard for Redpanda license monitoring: - Create a gauge to display the time remaining. - Add an alert panel for approaching expiration thresholds. ## [](#suggested-reading)Suggested reading - [Generate Grafana dashboard](../../../../manage/monitoring/#generate-grafana-dashboard). - [Generate Grafana dashboard in Kubernetes](../../../../manage/kubernetes/monitoring/k-monitor-redpanda/#generate-grafana-dashboard). --- # Page 100: Check License Status and Feature Usage with Redpanda Operator **URL**: https://docs.redpanda.com/current/get-started/licensing/check-status/redpanda-operator.md --- # Check License Status and Feature Usage with Redpanda Operator --- title: Check License Status and Feature Usage with Redpanda Operator latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: licensing/check-status/redpanda-operator page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: licensing/check-status/redpanda-operator.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/get-started/pages/licensing/check-status/redpanda-operator.adoc description: Learn how to monitor the status of an Enterprise Edition license and enterprise feature usage in Kubernetes using the Redpanda Operator. page-git-created-date: "2024-12-17" page-git-modified-date: "2024-12-17" support-status: supported --- If your Redpanda cluster is deployed in Kubernetes using the Redpanda Operator, you can monitor the license status from the Redpanda custom resource. The operator integrates license monitoring into the resource’s `status.conditions` and `status.license` fields, allowing you to get the license state with `kubectl`. These fields provide a detailed overview of your Redpanda license, including its status, expiration, and enterprise features currently in use. 1. Identify your Redpanda resources: ```bash kubectl get redpanda -A ``` Example output: NAMESPACE NAME LICENSE READY STATUS redpanda cluster Valid True Redpanda reconciliation succeeded The `License` field indicates whether the license is valid. Possible values include: - `Valid`: The license is valid. - `Expired`: The license has expired. - `Not Present`: No license is applied. 2. List detailed information about the license on a particular cluster: ```bash kubectl get redpanda -o jsonpath='{.status.license}' ``` Replace `` with the name of your Redpanda resource, such as `example-redpanda`. The output depends on the license status. It can include the following: > 📝 **NOTE** > > If the license is in violation, you must either obtain a valid license or disable the enterprise features in use to ensure compliance. For instructions, see [Disable Enterprise Features in Redpanda](../../disable-enterprise-features/). ## [](#examples)Examples This section provides examples of what the operator reports depending on the license status. Valid license: ```json { "license": { "status": "valid", "violation": false, "inUseFeatures": ["partition_auto_balancing_continuous"], "organization": "Devex", "type": "enterprise", "expiration": "2025-10-11T00:00:00Z" } } ``` Without a license: ```json { "license": { "status": "not_present", "violation": false, "inUseFeatures": ["partition_auto_balancing_continuous"] } } ``` Expired license: ```json { "license": { "status": "expired", "violation": true, "inUseFeatures": ["partition_auto_balancing_continuous"], } } ``` ## [](#trigger-license-checks)Trigger license checks The Redpanda Operator performs a license check during reconciliation, which is triggered in the following cases: - If changes are made to the Redpanda resource or its status. - If changes are made to resources managed by the operator, such as the StatefulSet resources for brokers or Deployment resources for Redpanda Console. - If no changes occur, the operator reconciles every 10 hours (default cache resync interval). - If you force reconciliation by making a no-op change, such as adding an annotation, to the Redpanda resource. ## [](#suggested-reading)Suggested reading - [Monitor a License Using Metrics](../metrics/) - [Check License Status and Feature Usage with `rpk`](../rpk/) --- # Page 101: Check License Status and Feature Usage with rpk **URL**: https://docs.redpanda.com/current/get-started/licensing/check-status/rpk.md --- # Check License Status and Feature Usage with `rpk` --- title: Check License Status and Feature Usage with rpk latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: licensing/check-status/rpk page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: licensing/check-status/rpk.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/get-started/pages/licensing/check-status/rpk.adoc description: Learn how to monitor the status of an Enterprise Edition license and enterprise feature usage with rpk. page-git-created-date: "2024-12-17" page-git-modified-date: "2024-12-17" support-status: supported --- To check the status of your license, use the `rpk cluster license info` command. Starting from version [24.2.8](https://github.com/redpanda-data/redpanda/releases/tag/v24.2.8), this command provides a detailed overview of your Redpanda license, including its status, expiration, and a list of currently used enterprise features. 1. Make sure that [`rpk` is installed](../../../rpk-install/) and configured to connect to your cluster’s Admin API endpoint. 2. Get the details about your cluster’s license: ```bash rpk cluster license info ``` The command displays the license information in a user-friendly format. The output depends on the license status. It can include the following: > 📝 **NOTE** > > If the license is in violation, you must either obtain a valid license or disable the enterprise features in use to ensure compliance. For instructions, see [Disable Enterprise Features in Redpanda](../../disable-enterprise-features/). If the license is within 30 days of expiration, a warning is logged. `rpk` displays warnings when you execute `rpk` commands that use the Admin API in the following scenarios: - **License violation**: When enterprise features are enabled without a valid license. - **Trial expiration**: When enterprise features are enabled and a trial license expires in less than 15 days. - **Enterprise expiration**: When enterprise features are enabled and an enterprise license is expired. ## [](#examples)Examples This section provides examples of what `rpk` reports depending on the license status. Valid license: LICENSE INFORMATION =================== License status: valid License violation: false Enterprise features in use: \[partition\_auto\_balancing\_continuous\] Organization: Devex Type: enterprise Expires: Oct 11 2025 Without a license: LICENSE INFORMATION =================== License status: not\_present License violation: false Enterprise features in use: \[partition\_auto\_balancing\_continuous\] Expired license: WARNING: The following enterprise features are being used in your Redpanda cluster: \[partition\_auto\_balancing\_continuous\]. These features require a license. LICENSE INFORMATION =================== License status: expired License violation: true Enterprise features in use: \[partition\_auto\_balancing\_continuous\] ## [](#change-the-output-format)Change the output format Different output formats can be useful depending on your scenario. For example, if you are writing scripts or automating license monitoring, you may prefer the JSON format, as it’s easily parsed by tools like `jq` or integrated into monitoring systems. To get the license information in another format, use the `--format` flag: ```bash rpk cluster license info --format ``` Replace `` with one of the available formats, such as `json` or `yaml`. For more formats, see [rpk cluster license info](../../../../reference/rpk/rpk-cluster/rpk-cluster-license-info/). ## [](#suggested-reading)Suggested reading - [Monitor a License Using Metrics](../metrics/) - [Check License Status and Feature Usage with Redpanda Operator](../redpanda-operator/) --- # Page 102: Disable Enterprise Features in Redpanda **URL**: https://docs.redpanda.com/current/get-started/licensing/disable-enterprise-features.md --- # Disable Enterprise Features in Redpanda --- title: Disable Enterprise Features in Redpanda latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: licensing/disable-enterprise-features page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: licensing/disable-enterprise-features.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/get-started/pages/licensing/disable-enterprise-features.adoc description: Disable specific enterprise features in Redpanda to ensure your cluster operates within the scope of the Community Edition without enterprise features. page-git-created-date: "2024-12-03" page-git-modified-date: "2024-12-03" support-status: supported --- Enterprise features in Redpanda are available only in the Enterprise Edition and require a valid license. If your cluster has enterprise features enabled without a valid license, it is essential to either upload a valid license or disable these features to maintain compliance with Redpanda licensing terms. ## [](#prerequisites)Prerequisites Before you begin, consider the following: - Take a backup of your current configuration to allow rollback if needed. - Disabling enterprise features may affect cluster performance, security, or functionality. Test these changes in a staging environment before applying them to production. - If you need enterprise features, consider purchasing a valid license to continue using them. To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). ## [](#check-for-enterprise-features-in-violation)Check for enterprise features in violation To check the status of your license, use the `rpk cluster license info` command. This command provides a detailed overview of your Redpanda license, including whether your cluster has enterprise features enabled without a valid license. > 📝 **NOTE** > > This command reports license violations only if enterprise features in Redpanda are enabled without a valid license. It does not report license violations for enterprise features in [Redpanda Connect](../overview/#connect) or [Redpanda Console](../overview/#console). 1. Ensure that [`rpk` is installed](../../rpk-install/) and configured to connect to your cluster’s Admin API endpoint. 2. Get the details about your cluster’s license: ```bash rpk cluster license info ``` If the `license violation` status is `true`, you must either obtain a valid license or disable the enterprise features in use to ensure compliance. ## [](#disable-enterprise-features)Disable enterprise features To disable specific enterprise features, refer to the following table: > 📝 **NOTE** > > These instructions apply to bare-metal deployments on Linux. If you are running Redpanda in a different environment, such as Kubernetes or Docker, the way you disable features may vary. | Feature | Action to Disable | | --- | --- | | Audit Logging | Set the cluster config audit_enabled to false:rpk cluster config set audit_enabled false | | Continuous Data Balancing | Set the cluster config partition_autobalancing_mode to node_add:rpk cluster config set partition_autobalancing_mode node_add | | Continuous Intra-Broker Partition Balancing (core_balancing_continuous) | Set the cluster config core_balancing_continuous to false:rpk cluster config set core_balancing_continuous false | | FIPS Compliance | Set the node config fips_mode to disabled:rpk node config set fips_mode disabled | | Kerberos authentication | Remove GSSAPI from the cluster config sasl_mechanisms:rpk cluster config set sasl_mechanisms | | Leader Pinning | Set default_leaders_preference to none:rpk cluster config set default_leaders_preference none | | OAUTHBEARER/OIDC authentication | Remove OIDC from the cluster config sasl_mechanisms and http_authentication:rpk cluster config set sasl_mechanisms rpk cluster config set http_authentication | | Remote Read Replicas | Set the cluster config cloud_storage_enable_remote_read to false:rpk cluster config set cloud_storage_enable_remote_read false | | Role-Based Access Control (RBAC) | Use rpk security role delete to delete all configured roles:rpk security role list rpk security role delete | | Server-Side Schema ID Validation | Set the cluster config enable_schema_id_validation to false:rpk cluster config set enable_schema_id_validation false | | Tiered Storage | Set the cluster config cloud_storage_enabled to false:rpk cluster config set cloud_storage_enabled false | ## [](#verify-the-license-status)Verify the license status When all required changes are made, confirm that the `license violation` status is now `false`. ```bash rpk cluster license info ``` ## [](#suggested-reading)Suggested reading For more information about licensing, see [Redpanda Licenses and Enterprise Features](../overview/). --- # Page 103: Redpanda Licenses and Enterprise Features **URL**: https://docs.redpanda.com/current/get-started/licensing/overview.md --- # Redpanda Licenses and Enterprise Features --- title: Redpanda Licenses and Enterprise Features latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: licensing/overview page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: licensing/overview.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/get-started/pages/licensing/overview.adoc description: Learn about Redpanda licensing for Redpanda, Redpanda Console, and Redpanda Connect, available in both Community and Enterprise editions. Understand licensing requirements and how to access enterprise features with a valid license key. page-git-created-date: "2024-12-03" page-git-modified-date: "2026-04-08" support-status: supported --- Redpanda, Redpanda Console, and Redpanda Connect are available in community and enterprise editions. Each product has a single binary that supports both editions. - Redpanda Community Edition is free and source-available on GitHub: - [Redpanda](https://github.com/redpanda-data/redpanda) - [Redpanda Console](https://github.com/redpanda-data/console) - [Redpanda Connect](https://github.com/redpanda-data/connect) - Redpanda Enterprise Edition requires a license key and includes additional features. > 💡 **TIP: Ready to try Redpanda Enterprise Edition?** > > Go to the Redpanda Self-Managed quickstart to set up a local Redpanda cluster and try the Enterprise Edition free for up to 60 days. > 📝 **NOTE** > > Redpanda Cloud is a managed deployment of Redpanda Enterprise Edition. To learn more about Redpanda Cloud, see the [Redpanda Cloud Overview](../../../../redpanda-cloud/get-started/cloud-overview/). ## [](#community-edition)Community Edition The Community Edition is licensed with the Redpanda [Business Source License](https://github.com/redpanda-data/redpanda/blob/dev/licenses/bsl.md) (BSL). These core features are free and source-available. ### [](#restrictions-and-licensing-terms)Restrictions and licensing terms - Users cannot provide Redpanda as a commercial streaming or queuing service to others. - The BSL code converts to Apache 2.0 licensing four years after each code merge. ## [](#enterprise-edition)Enterprise Edition The Enterprise Edition is licensed with the [Redpanda Community License](https://github.com/redpanda-data/redpanda/blob/dev/licenses/rcl.md) (RCL). It includes the free features licensed under the Redpanda BSL, as well as enterprise features. You can also generate a [Trial license](#trial-license) for the Enterprise Edition. ### [](#trial-license)Trial license All new Redpanda clusters automatically receive a trial license valid for 30 days. To extend this trial for 30 days, use the [`rpk generate license`](../../../reference/rpk/rpk-generate/rpk-generate-license/) command, or [request a new trial license key](https://redpanda.com/try-enterprise). This extended evaluation period begins after you apply the trial license to your cluster using the `--apply` flag. After this period expires, inactive enterprise features are disabled, and active features enter a restricted state. > ❗ **IMPORTANT** > > Only one trial license is permitted per email and business domain. Attempts to generate multiple trial licenses from the same email or business domain result in a license error. To get a permanent license, contact [Redpanda Sales](https://www.redpanda.com/contact). To generate and apply a 30-day trial license for Enterprise Edition: ```bash rpk generate license --apply First Name: Last Name: Company name: Business Email: ``` > 📝 **NOTE** > > To activate the trial license, you _must_ apply it to your cluster using the `--apply` flag. The trial license is saved in your working directory or the specified path, based on the `--path` flag. Example output: ```bash Successfully saved license to "/home//code/rp/redpanda/src/go/rpk/redpanda.license". Upload this license in Redpanda Console, or run: rpk cluster license set --path /home//rp/redpanda/src/go/rpk/redpanda.license This license expires on 2025-05-07. For more information, see: https://docs.redpanda.com/current/get-started/licensing/overview/#license-keys ``` ### [](#license-keys)License keys Enterprise features require an Enterprise Edition license key, sometimes called enterprise license, license key, or license. - **Redpanda**: Starting with version 24.3, new Redpanda clusters automatically receive a trial license that’s valid for 30 days, allowing unrestricted use of enterprise features. This evaluation period begins when the cluster is created for the first time. After this period expires, inactive enterprise features are disabled, and active features enter a restricted state. To extend your trial license see [Trial license](#trial-license), [request a new trial license key](https://redpanda.com/try-enterprise), or [upgrade to Redpanda Enterprise](https://redpanda.com/upgrade). Redpanda blocks upgrades to new feature releases if enterprise features are active without a valid license. Ensure compliance by obtaining a license to maintain access to the latest features and updates. > ❗ **IMPORTANT** > > To avoid startup issues with Redpanda Console when a trial or Enterprise license expires, use Redpanda Console v2.8.3 or later with clusters running Redpanda 24.3 or later. - **Redpanda Connect**: To evaluate enterprise features in Redpanda Connect, you must [apply a trial license key](../../../../redpanda-connect/get-started/licensing/#apply-a-license-key-to-redpanda-connect). After the 30-day evaluation period, you are blocked from using enterprise connectors unless you [upgrade to an Enterprise Edition license](https://www.redpanda.com/upgrade). ### [](#self-managed)Redpanda enterprise features The following table lists the enterprise features for Redpanda and how Redpanda behaves upon license expiration when each enterprise feature is enabled. - **Upon license expiration**: - The cluster continues to operate without data loss, but the further use of enterprise features is restricted (see the [table 1](#redpanda-enterprise-features)). - Configuration of enterprise features remains unchanged, allowing you to add a new license and continue using enterprise features as before expiration. For instructions, see [Add an Enterprise Edition License to Redpanda](../add-license-redpanda/) - **After license expiration**: You cannot enable enterprise features without a valid license. | Feature | Description | Behavior Upon Expiration | | --- | --- | --- | | Audit Logging | Records detailed logs of cluster activities for compliance and monitoring. | Read access to the audit log topic is denied, but logging continues. | | Continuous Data Balancing | Automatically balances partitions across a cluster to optimize resource use and performance.Continuous Data Balancing is enabled by default for all new clusters with valid licenses. | Continuous balancing is disabled, reverting to node_add setting that balances partitions only after a broker is added to the cluster. | | Continuous Intra-Broker Partition Balancing (core_balancing_continuous) | Balances partition replicas across CPU cores in an individual broker to optimize disk space usage.Continuous Intra-Broker Partition Balancing is enabled by default for all new clusters with a valid license. | Continuous Intra-Broker Partition Balancing is disabled. | | FIPS Compliance | Enables compliance with FIPS security standards for cryptography. | No change. | | Group-Based Access Control (GBAC) | Manages permissions using OIDC group memberships for ACLs and role assignments. | ACLs with Group: principals cannot be created. Existing group ACLs continue to be evaluated and can be deleted. | | Iceberg Topics | Enables Iceberg integration for Redpanda topics. | Topics cannot be created or modified with the redpanda.iceberg.mode property. | | Kerberos Authentication | Provides secure Kerberos-based authentication. | No change. | | Leader Pinning | Specifies the set of availability zones where the leaders of partitions of a given topic should be located. | Leader Pinning is disabled on all topics. | | OAUTHBEARER/OIDC Authentication | Allows for OAUTHBEARER and OpenID Connect (OIDC) authentication. | No change. | | Remote Read Replicas | Enables remote clusters to read data stored in object storage for disaster recovery. | Remote Read Replica topics cannot be created or modified. | | Role-Based Access Control (RBAC) | Manages user roles and permissions within the cluster. | Roles and ACLs associated with roles cannot be created or modified. Role deletion is allowed. | | Schema Registry Authorization | Manages ACLs for Redpanda Schema Registry resources within the cluster. | You can no longer enable schema_registry_enable_authorization, nor can you create or modify schema ACLs. | | Server-Side Schema ID Validation | Validates schema IDs server-side to ensure schema compatibility. With schema ID validation, records associated with unregistered schemas are detected and dropped by a broker rather than a consumer. | Topics with schema validation settings cannot be created or modified. | | Shadowing | Provides enterprise-grade disaster recovery through asynchronous, offset-preserving replication between distinct Redpanda clusters for cross-region data protection. | New shadow links cannot be created. Existing shadow links continue operating and can be updated. | | Topic Recovery | Allows restoring a single topic from Tiered Storage using remote recovery properties. | You cannot create topics with the redpanda.remote.recovery=true property or perform topic recovery operations. To proceed, add a valid license to the target cluster. Without a valid license, topic recovery is blocked. | | Tiered Storage | Enables data storage in cloud object storage for long-term retention and retrieval. | Topics cannot be created or modified to enable Tiered Storage features. Additional partitions cannot be added to topics with Tiered Storage properties enabled. | | Whole Cluster Restore (WCR) | Enables the recovery of cluster data from a source cluster’s snapshot. | If the license is expired, you cannot perform WCR. To proceed, add a valid license to the target cluster. If the source cluster has an expired license, the target cluster inherits the restriction until a valid license is applied. | ### [](#console)Redpanda Console enterprise features The following enterprise features for Redpanda Console are activated with a valid Enterprise Edition license key: | Feature | Description | Restrictions Without Valid License | | --- | --- | --- | | Authentication for Redpanda Console | Enables authentication for Redpanda Console, including secure login through OIDC and OAuth 2.0 SSO. | All pages are redirected to the license expiration landing page, and all other access is restricted. | | Authorization (RBAC) for Redpanda | Manages user roles and permissions for accessing features within Redpanda and Redpanda Console. | All pages are redirected to the license expiration landing page, and all other access is restricted. | | Debug bundle generation | Enables generating and downloading debug bundles in Redpanda Console for comprehensive cluster diagnostics. | All pages are redirected to the license expiration landing page, and all other access is restricted. | | Reassign Partitions | Enables the ability to move partitions between brokers. | All pages are redirected to the license expiration landing page, and all other access is restricted. | ### [](#connect)Redpanda Connect enterprise features The following enterprise features are available with a valid Enterprise Edition license. | Feature | Description | Restrictions Without Valid License | | --- | --- | --- | | Allow or deny lists | Limit the Redpanda Connect components that users can run within data pipelines on a Redpanda Connect instance. | No change. | | Enterprise connectors | Additional inputs, outputs, and processors available only to enterprise customers. | All enterprise connectors are blocked. | | FIPS compliance | Run Redpanda Connect using a FIPS-compliant version of rpk, the Redpanda command-line interface (CLI). | No change. | | Redpanda Connect configuration service | A configuration block that you can use to send logs and status events to a topic on a Redpanda cluster. | No change. | | Secrets management | Retrieve secrets values from a remote system, such as a secret management solution, without setting environment variables. | No change. | ## [](#manage-licenses-for-redpanda)Manage licenses for Redpanda Redpanda offers multiple ways to manage your license depending on your deployment method. Proper license management ensures access to advanced enterprise features and avoids restrictions when licenses are invalid or expired. See [Add an Enterprise Edition License to Redpanda](../add-license-redpanda/). ## [](#manage-licenses-for-redpanda-console)Manage licenses for Redpanda Console Redpanda Console offers two methods for applying or updating a license, depending on your setup: - If you use Redpanda Console without connecting it to a Redpanda cluster, you can [configure the license through the local configuration file or environment variables](../../../console/config/enterprise-license/). This method allows you to add a license for Redpanda Console independently of the Redpanda cluster. - If Redpanda Console is connected to a Redpanda cluster, you can [upload a license through the Redpanda Console UI](../../../console/ui/add-license/). This method allows you to manage and update licenses for both Redpanda Console and the connected Redpanda cluster. ## [](#manage-licenses-for-redpanda-connect)Manage licenses for Redpanda Connect Redpanda Connect offers multiple ways to apply or update your license. See [Apply a license key to Redpanda Connect](../../../../redpanda-connect/get-started/licensing/#apply-a-license-key-to-redpanda-connect). ## [](#next-steps)Next steps - [Add an Enterprise Edition License to Redpanda](../add-license-redpanda/) - [Check the Status of Licenses](../check-status/) --- # Page 104: Partner Integrations **URL**: https://docs.redpanda.com/current/get-started/partner-integration.md --- # Partner Integrations --- title: Partner Integrations latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: partner-integration page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: partner-integration.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/get-started/pages/partner-integration.adoc description: Learn about Redpanda integrations built and supported by our partners. page-git-created-date: "2024-05-21" page-git-modified-date: "2025-08-07" support-status: supported --- Learn about Redpanda integrations built and supported by our partners. | Partner | Description | More information | | --- | --- | --- | | Superstream | Superstream optimizes and improves Redpanda (and other Kafka platforms) for cost reduction, increased reliability, and improved visibility. | Superstream for Redpanda | | Aklivity Zilla | Zilla is a multi-protocol proxy that abstracts Redpanda for non-native clients, such as browsers and IoT devices, by exposing Redpanda topics using user-defined REST, Server-Sent Events (SSE), MQTT, or gRPC API entry points. | Modern Eventing with CQRS, Redpanda and Zilla | | Bytewax | Bytewax is an open source framework and distributed stream processing engine in Python. | Enriching streaming data with Bytewax and Redpanda | | ClickHouse | ClickHouse is a high-performance, column-oriented SQL database management system (DBMS) for online analytical processing (OLAP). | Building an OLAP database with ClickHouse and Redpanda | | Conduktor | Conduktor provides simple, flexible, and powerful tooling for Kafka developers and infrastructure. | Conduktor & Redpanda: Best of breed Kafka experience | | Decodable | Decodable is a real-time data processing platform powered by Apache Flink and Debezium. | Decodable + Redpanda | | ElastiFlow | ElastiFlow captures and analyzes flow and SNMP data to provide detailed insights into network performance and security. | Leveraging Redpanda for Enhanced Network Observability: ElastiFlow Integration | | Materialize | Materialize is a data warehouse purpose-built for operational workloads where an analytical data warehouse would be too slow, and a stream processor would be too complicated. | Ingesting data from Redpanda with Materialize | | PeerDB | PeerDB provides a fast, simple, and cost-effective way to replicate data from Postgres to data warehouses, queues and storage. | Quickstart guide | | Pinecone | Pinecone is a vector database for building accurate and performant AI applications at scale. The Pinecone connector for Redpanda Connect provides a production-ready integration from many existing data sources through simple YAML configuration. | Redpanda Connect integration | | RisingWave | RisingWave is a distributed SQL streaming database that enables simple, efficient, and reliable processing of streaming data. | Ingesting data from Redpanda with Risingwave | | Timeplus | Timeplus is a stream processor that provides powerful end-to-end capabilities, leveraging the open source streaming engine Proton. | Realizing low latency streaming analytics with Timeplus and Redpanda | | Tinybird | Tinybird is a data platform for data and engineering teams to solve complex real-time, operational, and user-facing analytics use cases at any scale. | Building a complete IoT backend with Redpanda and Tinybird | | Quix | Quix is a complete platform for building, deploying, and monitoring stream processing pipelines in Python. | Integrating Redpanda with Quix | | Yugabyte | YugabyteDB is an open-source, distributed SQL database that combines the capabilities of relational databases with the scalability of NoSQL systems. | How to Integrate Yugabyte CDC Connector with Redpanda | ## [](#how-to-contribute-to-this-page)How to contribute to this page To request a partner integration with Redpanda Data, reach out to ([partners@redpanda.com](mailto:partners@redpanda.com\)). Provide a link to your product documentation or a blogpost explaining how your product integrates with Redpanda. After meeting these requirements, you can [contribute to this page](https://github.com/redpanda-data/docs/edit/main/modules/get-started/pages/partner-integration.adoc). --- # Page 105: Redpanda Self-Managed Quickstart **URL**: https://docs.redpanda.com/current/get-started/quick-start.md --- # Redpanda Self-Managed Quickstart --- title: Redpanda Self-Managed Quickstart latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: quick-start page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: quick-start.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/get-started/pages/quick-start.adoc description: Learn how to quickly start working with a local Redpanda cluster that comes with a free 30-day license for Enterprise Edition. You can also extend the trial license for a further 30 days. page-git-created-date: "2023-05-30" page-git-modified-date: "2026-03-31" support-status: supported --- Learn how to quickly start working with a local Redpanda cluster that comes with a free 30-day license for Enterprise Edition. You can also extend the trial license for a further 30 days. Redpanda Self-Managed is a modern streaming platform, compatible with Kafka APIs, designed for speed, simplicity, and efficiency. In this quickstart, you: - Deploy a three-broker Redpanda cluster. - Explore streaming data in Redpanda Console. - Learn the basics of streaming with the Redpanda CLI (`rpk`). - Deploy a streaming pipeline with Redpanda Connect. - Learn how to extend your trial license for an additional 30 days. > 📝 **NOTE** > > This quickstart uses Docker to run Redpanda, which is only for development and testing purposes. For production deployments, see the [Linux deployment guides](../../deploy/redpanda/manual/production/) or the [Kubernetes deployment guides](../../deploy/redpanda/kubernetes/). To download the Redpanda binary, see [GitHub](https://github.com/redpanda-data/redpanda/releases/latest). > > **Looking for a managed solution?** You can also get started quickly with a hosted Redpanda cluster by signing up for [Redpanda Cloud](https://cloud.redpanda.com). ## [](#enterprise-features)Enterprise features The Enterprise Edition of Redpanda Self-Managed adds advanced capabilities to help scale, manage, optimize, and secure your cluster. All new Redpanda clusters include a built-in 30-day Enterprise Edition license, so you can evaluate enterprise features. Some features highlighted in this quickstart require an enterprise license: - **Redpanda Console Authentication**: Securely control login access to Redpanda Console. - **Audit Logging**: Track and monitor all user actions in a Redpanda topic. - **Continuous Data Balancing**: Automatically balance data across brokers to optimize performance. - **Tiered Storage**: Lower storage costs by offloading log segments to object storage. Your trial license also includes additional enterprise features. For more information, see [Redpanda Licenses and Enterprise Features](../licensing/overview/). > 💡 **TIP: Want a longer trial?** > > [Sign up for an extended trial license](https://cloud.redpanda.com/try-enterprise). ## [](#prerequisites)Prerequisites You need the following tools and settings before proceeding: - **tar (GNU tar)**: On most Linux distributions, GNU tar is preinstalled. On macOS, install GNU tar using Homebrew and ensure it’s used instead of the BSD version: ```bash brew install gnu-tar ``` - **Docker Compose**: For installation instructions, see the Docker Compose documentation: [Docker Compose documentation](https://docs.docker.com/compose/install/). To verify you have it installed, run: ```bash docker compose version ``` You should see the installed Docker Compose version. - **Docker Desktop (macOS/Windows)**: Ensure that Docker Desktop’s file sharing is enabled for the directory where you plan to run the quickstart. If your working directory isn’t shared, containers won’t be able to see your files. - **Available memory**: Make sure your machine has at least 4 GB of free memory before starting the containers. If your resource limits are too low, some containers may hang or fail to start. > 📝 **NOTE: Windows users** > > If you’re on **Windows**, use a compatible terminal that supports Unix-like commands (for example, PowerShell or Windows Terminal). Alternatively, you can use Windows Subsystem for Linux (WSL). For WSL installation instructions, see: [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install). ## [](#deploy-redpanda-self-managed)Deploy Redpanda Self-Managed To download, extract, and start Redpanda Self-Managed in Docker, run: ```bash mkdir redpanda-quickstart && cd redpanda-quickstart && \ (1) curl -sSL https://docs.redpanda.com/redpanda-quickstart.tar.gz | tar xzf - && \ (2) cd docker-compose && docker compose up -d (3) ``` | 1 | Create and navigate to the redpanda-quickstart directory. | | --- | --- | | 2 | Download and extract the archive. Explore the downloaded filesdocker-compose.ymlname: redpanda-quickstart-multi-broker networks: redpanda_network: driver: bridge volumes: redpanda-0: null redpanda-1: null redpanda-2: null minio: null services: ################## # Redpanda Brokers # ################## redpanda-0: command: - redpanda - start - --kafka-addr internal://0.0.0.0:9092,external://0.0.0.0:19092 # Address the broker advertises to clients that connect to the Kafka API. # Use the internal addresses to connect to the Redpanda brokers # from inside the same Docker network. # Use the external addresses to connect to the Redpanda brokers # from outside the Docker network. - --advertise-kafka-addr internal://redpanda-0:9092,external://localhost:19092 - --pandaproxy-addr internal://0.0.0.0:8082,external://0.0.0.0:18082 # Address the broker advertises to clients that connect to the HTTP Proxy. - --advertise-pandaproxy-addr internal://redpanda-0:8082,external://localhost:18082 - --schema-registry-addr internal://0.0.0.0:8081,external://0.0.0.0:18081 # Redpanda brokers use the RPC API to communicate with each other internally. - --rpc-addr redpanda-0:33145 - --advertise-rpc-addr redpanda-0:33145 # Mode dev-container uses well-known configuration properties for development in containers. - --mode dev-container # Tells Seastar (the framework Redpanda uses under the hood) to use 1 core on the system. - --smp 1 - --default-log-level=info image: docker.redpanda.com/redpandadata/redpanda:v26.1.3 container_name: redpanda-0 # Sets the username and password of the bootstrap SCRAM superuser # See https://docs.redpanda.com/current/deploy/deployment-option/self-hosted/manual/production/production-deployment/#bootstrap-a-user-account environment: RP_BOOTSTRAP_USER: "superuser:secretpassword" volumes: - redpanda-0:/var/lib/redpanda/data - ./bootstrap.yml:/etc/redpanda/.bootstrap.yaml networks: - redpanda_network ports: - 18081:18081 - 18082:18082 - 19092:19092 - 19644:9644 healthcheck: test: ["CMD", "rpk", "cluster", "info", "-X", "user=superuser", "-X", "pass=secretpassword"] interval: 10s timeout: 15s retries: 10 depends_on: minio: condition: service_healthy redpanda-1: command: - redpanda - start - --kafka-addr internal://0.0.0.0:9092,external://0.0.0.0:29092 - --advertise-kafka-addr internal://redpanda-1:9092,external://localhost:29092 - --pandaproxy-addr internal://0.0.0.0:8082,external://0.0.0.0:28082 - --advertise-pandaproxy-addr internal://redpanda-1:8082,external://localhost:28082 - --schema-registry-addr internal://0.0.0.0:8081,external://0.0.0.0:28081 - --rpc-addr redpanda-1:33145 - --advertise-rpc-addr redpanda-1:33145 - --mode dev-container - --smp 1 - --default-log-level=info - --seeds redpanda-0:33145 image: docker.redpanda.com/redpandadata/redpanda:v26.1.3 container_name: redpanda-1 environment: RP_BOOTSTRAP_USER: "superuser:secretpassword" volumes: - redpanda-1:/var/lib/redpanda/data - ./bootstrap.yml:/etc/redpanda/.bootstrap.yaml networks: - redpanda_network ports: - 28081:28081 - 28082:28082 - 29092:29092 - 29644:9644 healthcheck: test: ["CMD", "rpk", "cluster", "info", "-X", "user=superuser", "-X", "pass=secretpassword"] interval: 10s timeout: 15s retries: 10 depends_on: - redpanda-0 - minio redpanda-2: command: - redpanda - start - --kafka-addr internal://0.0.0.0:9092,external://0.0.0.0:39092 - --advertise-kafka-addr internal://redpanda-2:9092,external://localhost:39092 - --pandaproxy-addr internal://0.0.0.0:8082,external://0.0.0.0:38082 - --advertise-pandaproxy-addr internal://redpanda-2:8082,external://localhost:38082 - --schema-registry-addr internal://0.0.0.0:8081,external://0.0.0.0:38081 - --rpc-addr redpanda-2:33145 - --advertise-rpc-addr redpanda-2:33145 - --mode dev-container - --smp 1 - --default-log-level=info - --seeds redpanda-0:33145 image: docker.redpanda.com/redpandadata/redpanda:v26.1.3 container_name: redpanda-2 environment: RP_BOOTSTRAP_USER: "superuser:secretpassword" volumes: - redpanda-2:/var/lib/redpanda/data - ./bootstrap.yml:/etc/redpanda/.bootstrap.yaml networks: - redpanda_network ports: - 38081:38081 - 38082:38082 - 39092:39092 - 39644:9644 healthcheck: test: ["CMD", "rpk", "cluster", "info", "-X", "user=superuser", "-X", "pass=secretpassword"] interval: 10s timeout: 15s retries: 10 depends_on: - redpanda-0 - minio #################### # Redpanda Console # #################### console: container_name: redpanda-console image: docker.redpanda.com/redpandadata/console:v3.7.1 networks: - redpanda_network entrypoint: /bin/sh command: -c 'echo "$$CONSOLE_CONFIG_FILE" > /tmp/config.yml && /app/console' volumes: - ./config:/tmp/config/ environment: CONFIG_FILEPATH: ${CONFIG_FILEPATH:-/tmp/config.yml} CONSOLE_CONFIG_FILE: | # Configure a connection to the Redpanda cluster # See https://docs.redpanda.com/current/console/config/connect-to-redpanda/ kafka: brokers: ["redpanda-0:9092"] sasl: enabled: true impersonateUser: true schemaRegistry: enabled: true urls: ["http://redpanda-0:8081","http://redpanda-1:8081","http://redpanda-2:8081"] authentication: impersonateUser: true redpanda: adminApi: enabled: true urls: ["http://redpanda-0:9644","http://redpanda-1:9644","http://redpanda-2:9644"] authentication: basic: username: superuser password: secretpassword impersonateUser: false console: # Configures Redpanda Console to fetch topic documentation from GitHub and display it in the UI. # See https://docs.redpanda.com/current/console/config/topic-documentation/ topicDocumentation: enabled: true git: enabled: true repository: url: https://github.com/redpanda-data/docs branch: main baseDirectory: tests/docker-compose authentication: jwtSigningKey: vazxnT+ZHtxKslK6QlDGovcYnSjTk/lKMmZ+mHrBVE+YdVDkLgSuP6AszAKe9Gvq basic: enabled: true authorization: roleBindings: - roleName: admin users: - loginType: basic name: superuser ports: - 8080:8080 depends_on: redpanda-0: condition: service_healthy createtopic: condition: service_completed_successfully registerschema: condition: service_completed_successfully deploytransform: condition: service_completed_successfully #################### # Redpanda Connect # #################### connect: container_name: redpanda-connect image: docker.redpanda.com/redpandadata/connect networks: - redpanda_network entrypoint: /bin/sh depends_on: redpanda-0: condition: service_healthy command: -c 'echo "$$CONNECT_CFG_FILE" > /tmp/connect.yml; /redpanda-connect -c /tmp/connect.yml' environment: # This Redpanda Connect configuration creates fake data, # processes it, and writes the output to a set of topics. # # Input: # - Uses Redpanda Connect's generate input to generate fake data. # See https://docs.redpanda.com/redpanda-connect/components/inputs/generate/ # Pipeline: # - Bloblang mapping to batch each input and map 1 message to 'logins' # topic, and a random number (1-3) of messages to 'transaction' topic # - Unarchive processor to parse the JSON array and extract each # element into its own message. # See https://docs.redpanda.com/redpanda-connect/guides/bloblang/about/ # Output: # - kafka_franz output to write the messages to the Redpanda brokers. # See https://docs.redpanda.com/redpanda-connect/components/outputs/kafka_franz/ CONNECT_CFG_FILE: | input: generate: interval: 1s mapping: | let first_name = fake("first_name") let last_name = fake("last_name") root.user_id = counter() root.name = $$first_name + " " + $$last_name root.email = ($$first_name.slice(0,1) + $$last_name + "@" + fake("domain_name")).lowercase() root.ip = fake("ipv4") root.login_time = now() pipeline: processors: - mapping: | root = range(0, random_int(min:2, max:4)).map_each(cust -> this) - unarchive: format: "json_array" - mapping: | if batch_index() == 0 { meta topic = "logins" root = this } else { meta topic = "transactions" root.user_id = this.user_id root.email = this.email root.index = batch_index() - 1 root.product_url = fake("url") root.price = fake("amount_with_currency") root.timestamp = now() } output: kafka_franz: seed_brokers: [ "redpanda-0:9092" ] topic: $${! metadata("topic") } sasl: - mechanism: SCRAM-SHA-256 password: secretpassword username: superuser #################### # rpk container to create the edu-filtered-domains topic # # See https://docs.redpanda.com/current/reference/rpk/rpk-topic/rpk-topic-create/ #################### createtopic: command: - topic - create - edu-filtered-domains - -X user=superuser - -X pass=secretpassword - -X brokers=redpanda-0:9092 image: docker.redpanda.com/redpandadata/redpanda:v26.1.3 networks: - redpanda_network depends_on: redpanda-0: condition: service_healthy #################### # rpk container to register the schema # # See https://docs.redpanda.com/current/manage/schema-reg/schema-reg-api/ #################### registerschema: command: - registry - schema - create - transactions - --schema - /etc/redpanda/transactions-schema.json - -X user=superuser - -X pass=secretpassword - -X registry.hosts=redpanda-0:8081 image: docker.redpanda.com/redpandadata/redpanda:v26.1.3 # Mount the local directory that contains your schema to the container. volumes: - ./transactions-schema.json:/etc/redpanda/transactions-schema.json networks: - redpanda_network depends_on: redpanda-0: condition: service_healthy #################### # rpk container to deploy a consumer group # # See https://docs.redpanda.com/current/reference/rpk/rpk-topic/rpk-topic-consume/ #################### consumergroup: command: - topic - consume - transactions - --group - transactions-consumer - -X user=superuser - -X pass=secretpassword - -X brokers=redpanda-0:9092 image: docker.redpanda.com/redpandadata/redpanda:v26.1.3 networks: - redpanda_network depends_on: createtopic: condition: service_completed_successfully deploytransform: condition: service_completed_successfully #################### # rpk container to deploy the pre-built data transform # # See https://docs.redpanda.com/current/develop/data-transforms/deploy/ #################### deploytransform: command: - transform - deploy - --file=/etc/redpanda/regex.wasm - --name=regex - --input-topic=logins - --output-topic=edu-filtered-domains - --var=PATTERN="[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.edu" - --var=MATCH_VALUE=true - -X user=superuser - -X pass=secretpassword - -X admin.hosts=redpanda-0:9644 image: docker.redpanda.com/redpandadata/redpanda:v26.1.3 volumes: - ./transform/regex.wasm:/etc/redpanda/regex.wasm networks: - redpanda_network depends_on: createtopic: condition: service_completed_successfully #################### # MinIO for Tiered Storage # # See https://min.io/ # # NOTE: MinIO is included in this quickstart for development and evaluation purposes only. # It is not supported for production deployments of Redpanda. # # For production environments, use one of the supported object storage providers: # https://docs.redpanda.com/current/deploy/deployment-option/self-hosted/manual/production/requirements/#object-storage-providers-for-tiered-storage #################### minio: container_name: minio image: minio/minio:RELEASE.2025-05-24T17-08-30Z command: server --console-address ":9001" /data ports: - 9000:9000 - 9001:9001 environment: MINIO_ROOT_USER: minio MINIO_ROOT_PASSWORD: redpandaTieredStorage7 MINIO_SERVER_URL: "http://minio:9000" MINIO_REGION_NAME: local MINIO_DOMAIN: minio volumes: - minio:/data networks: redpanda_network: aliases: - redpanda.minio healthcheck: test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/ready"] interval: 10s timeout: 5s retries: 3 mc: depends_on: minio: condition: service_healthy image: minio/mc:RELEASE.2025-05-21T01-59-54Z container_name: mc networks: - redpanda_network environment: - AWS_ACCESS_KEY_ID=minio - AWS_SECRET_ACCESS_KEY=redpandaTieredStorage7 - AWS_REGION=local entrypoint: > /bin/sh -c " until (/usr/bin/mc alias set minio http://minio:9000 minio redpandaTieredStorage7) do echo '...waiting...' && sleep 1; done; /usr/bin/mc mb minio/redpanda; /usr/bin/mc policy set public minio/redpanda; tail -f /dev/null "rpk-profile.yaml# This file configures `rpk` to connect to a remote Redpanda cluster running in the same local network as `rpk`. # Configuration for connecting to the Kafka API of the Redpanda cluster. kafka_api: # SASL (Simple Authentication and Security Layer) settings for authentication. sasl: user: superuser # The username used for authentication password: secretpassword # The password associated with the username mechanism: scram-sha-256 # Authentication mechanism; SCRAM-SHA-256 provides secure password-based authentication # List of Kafka brokers in the Redpanda cluster. # These brokers ensure high availability and fault tolerance for Kafka-based communication. brokers: - 127.0.0.1:19092 # Broker 1: Accessible on localhost, port 19092 - 127.0.0.1:29092 # Broker 2: Accessible on localhost, port 29092 - 127.0.0.1:39092 # Broker 3: Accessible on localhost, port 39092 # Configuration for connecting to the Redpanda Admin API. # The Admin API allows you to perform administrative tasks such as managing configurations, monitoring, and scaling. admin_api: # List of Admin API endpoints for managing the cluster. addresses: - 127.0.0.1:19644 # Admin API for Broker 1: Accessible on localhost, port 19644 - 127.0.0.1:29644 # Admin API for Broker 2: Accessible on localhost, port 29644 - 127.0.0.1:39644 # Admin API for Broker 3: Accessible on localhost, port 39644 # Configuration for connecting to the Redpanda Schema Registry API. schema_registry: # List of Schema Registry API endpoints. addresses: - 127.0.0.1:18081 # Schema Registry API for Broker 1: Accessible on localhost, port 18081 - 127.0.0.1:28081 # Schema Registry API for Broker 2: Accessible on localhost, port 28081 - 127.0.0.1:38081 # Schema Registry API for Broker 3: Accessible on localhost, port 38081bootstrap.yml# ================================================================= # This file defines initial cluster properties for a Redpanda cluster. # Some of these settings are intended for quickstart development and evaluation # and are not suitable for production environments. # # For more information on bootstrap files, see: # https://docs.redpanda.com/current/deploy/deployment-option/self-hosted/manual/production/production-deployment/#configure-a-bootstrap-file # ================================================================= # # Enable SASL authentication for the Kafka and Admin APIs. # https://docs.redpanda.com/current/reference/properties/cluster-properties/#admin_api_require_auth admin_api_require_auth: true # At least one superuser is required to be able to create other SASL users # https://docs.redpanda.com/current/reference/properties/cluster-properties/#superusers superusers: - superuser # https://docs.redpanda.com/current/reference/properties/cluster-properties/#enable_sasl enable_sasl: true # Allow topics to be created on first access. # https://docs.redpanda.com/current/reference/properties/cluster-properties/#auto_create_topics_enabled auto_create_topics_enabled: true # Enable data transforms. # https://docs.redpanda.com/current/develop/data-transforms/how-transforms-work/ data_transforms_enabled: true # Enable audit logging (enterprise feature). # https://docs.redpanda.com/current/manage/audit-logging/ audit_enabled: true # Enable Tiered Storage (enterprise feature). # https://docs.redpanda.com/current/manage/tiered-storage/ cloud_storage_enabled: true cloud_storage_region: local cloud_storage_access_key: minio cloud_storage_secret_key: redpandaTieredStorage7 cloud_storage_api_endpoint: minio cloud_storage_api_endpoint_port: 9000 cloud_storage_disable_tls: true cloud_storage_bucket: redpanda # Forces segments to be uploaded to Tiered Storage faster for the purposes of the quickstart # https://docs.redpanda.com/current/reference/properties/object-storage-properties/#cloud_storage_segment_max_upload_interval_sec cloud_storage_segment_max_upload_interval_sec: 60 # Continuous Data Balancing (enterprise feature) continuously monitors your node and rack availability and disk usage. This enables self-healing clusters that dynamically balance partitions, ensuring smooth operations and optimal cluster performance. # https://docs.redpanda.com/current/manage/cluster-maintenance/continuous-data-balancing/ partition_autobalancing_mode: continuous # Enable Redpanda to collect consumer group metrics. # https://docs.redpanda.com/current/reference/properties/cluster-properties/#enable_consumer_group_metrics enable_consumer_group_metrics: - "group" - "partition" - "consumer_lag" # Lower the interval for the quickstart # https://docs.redpanda.com/current/reference/properties/cluster-properties/#consumer_group_lag_collection_interval_sec consumer_group_lag_collection_interval_sec: 60 # Enable Redpanda to collect host metrics. # https://docs.redpanda.com/current/reference/properties/cluster-properties/#enable_host_metrics enable_host_metrics: true | | 3 | Start Docker Compose. | When the containers are running, you have: - A Redpanda cluster with a 30-day free trial license. - A running data streaming pipeline generating data into the `logins` and `transactions` topics. - A Wasm data transform processing data from `logins` into `edu-filtered-domains`. - A secured instance of Redpanda Console with login authentication. ## [](#explore-redpanda-console)Explore Redpanda Console Redpanda Console is a developer-friendly web UI for managing and debugging your Redpanda cluster and your applications. This section provides practical examples and scenarios to help you understand how to leverage Redpanda Console for different use cases, including data observability, Redpanda management, access control, and connectivity. Redpanda Console was deployed as part of the `docker-compose.yml` file and is running locally on port 8080. ### [](#log-in-to-redpanda-console)Log in to Redpanda Console To start using Redpanda Console, you first need to log in with the credentials of a user. Redpanda is configured with a bootstrap SCRAM user called `superuser`, so you can log into Redpanda Console as that user (enterprise feature). This user has admin access to Redpanda and Redpanda Console. 1. Open your web browser and go to [http://localhost:8080/login](http://localhost:8080/login). 2. Enter the following credentials: - Username: ```none superuser ``` - Password: ```none secretpassword ``` Leave the SASL mechanism as **SCRAM-SHA-256**. You should now see an overview of your cluster’s status, health, and brokers. ![overview](../../console/_images/overview.png) To view details about a specific broker, click **View** at the end of the row in the **Broker Details** table. ![broker overview](../../console/_images/broker-overview.png) See also: [Authentication in Redpanda Console](../../console/config/security/authentication/). ### [](#view-topics-and-filter-messages)View topics and filter messages This quickstart deployment comes with two pre-configured topics, `logins` and `transactions`, actively receiving data from a Redpanda Connect pipeline. These topics simulate real-world data flows, enabling you to explore and interact with Redpanda Console features. You can filter messages in topics using several methods: - Text search: Search for specific text within the message. - Partition offset filters: Set the start and end offsets to narrow down the message range. - JavaScript filters: Use JavaScript function bodies to create complex filters that run server-side, allowing you to filter through topics with millions of records. Suppose you’re asked to find all transactions related to the `.edu` domain. You can use a JavaScript filter to display only messages that include email addresses in that domain. 1. In the menu, click **Topics**. 2. Click the **transactions** topic. When the topic’s page opens, the **Messages** tab is selected by default. 3. Click **Add filter** > **JavaScript Filter**. 4. Give your filter a name, such as "Find .edu domains". ![js filter](../../console/_images/js-filter.png) 5. Replace the default JavaScript code with the following: ```js return value.email.includes(".edu"); ``` 6. Click **Save** to apply the filter. You should see only messages that include the specific domain. By default, the filter runs on the newest 50 messages. You can run the filter on older messages by changing the start offset. For example, to start from the oldest messages, select **Beginning**. See also: [Filter Messages with JavaScript in Redpanda Console](../../console/ui/programmable-push-filters/). ### [](#explore-schema-registry)Explore Schema Registry On the **Schema Registry** page, you see an overview of your schemas. You can create, manage, and inspect your schemas without leaving Redpanda Console. ![schema reg](../../console/_images/schema-reg.png) See also: [Use Schema Registry in Redpanda Console](../../console/ui/schema-reg/). ### [](#configure-access-control-for-redpanda)Configure access control for Redpanda Managing access control lists (ACLs) can be complex, but Redpanda Console simplifies this with an intuitive interface. This quickstart deployment includes a bootstrapped superuser with full administrative privileges. The superuser has unrestricted access to all topics, consumer groups, transactions, and cluster-level operations. By default, the credentials for the superuser are: - Username: `superuser` - Password: `secretpassword` For improved security and role-based access control (RBAC), you should create additional users with restricted permissions as needed. On the **Security** page, you can: - Create, view, and edit ACLs for topics, consumer groups, transactions, and the entire cluster. - Quickly understand what each principal (user) is authorized to do. Suppose you’re onboarding a new team member who needs access to specific topics. You can use Redpanda Console to ensure users have the right permissions to perform their tasks. 1. In the menu, click **Security**. 2. On the **Users** tab, click **Create user**. 3. Enter "Sasha" in the username field. 4. Enter "sashapassword" in the password field. 5. Click **Create**. ![user](../../console/_images/user.png) Click **Done**, and you see a new user called Sasha. This user has no permissions yet. To set permissions on the `transactions` topic: 1. On the Access control page, open to the **Roles** tab. 2. Click **Create role**. 3. Enter "transaction-managers" as the role name. 4. In the topic selector dropdown, select **Literal** and enter "transactions" in the input field. 5. Under **Operations**, click the **All** dropdown and select **Allow**. 6. Scroll down to the bottom of the page and under **Principals** select **Sasha** from the dropdown. 7. Click **Create**. Now Sasha has full access only to the topic called transactions. To test these permissions, use `rpk` to connect to Redpanda as the user Sasha. 1. Try to access the `logins` topic as Sasha: ```bash docker exec -it redpanda-0 rpk topic describe logins \ -X user=Sasha \ -X pass=sashapassword \ -X sasl.mechanism=SCRAM-SHA-256 \ -X brokers=redpanda-0:9092 ``` You are not authorized to view the topic. SUMMARY ======= NAME logins PARTITIONS 0 ERROR TOPIC\_AUTHORIZATION\_FAILED: Not authorized to access topics: \[Topic authorization failed.\] CONFIGS ======= config response contained error: TOPIC\_AUTHORIZATION\_FAILED: Not authorized to access topics: \[Topic authorization failed.\] 2. Now try to access the `transactions` topic as Sasha: ```bash docker exec -it redpanda-0 rpk topic describe transactions \ -X user=Sasha \ -X pass=sashapassword \ -X sasl.mechanism=SCRAM-SHA-256 \ -X brokers=redpanda-0:9092 ``` You have access to this topic. Example output SUMMARY ======= NAME transactions PARTITIONS 1 REPLICAS 1 CONFIGS ======= KEY VALUE SOURCE cleanup.policy delete DEFAULT\_CONFIG compression.type producer DEFAULT\_CONFIG delete.retention.ms -1 DEFAULT\_CONFIG flush.bytes 262144 DEFAULT\_CONFIG flush.ms 100 DEFAULT\_CONFIG initial.retention.local.target.bytes -1 DEFAULT\_CONFIG initial.retention.local.target.ms -1 DEFAULT\_CONFIG max.message.bytes 1048576 DEFAULT\_CONFIG message.timestamp.type CreateTime DEFAULT\_CONFIG redpanda.iceberg.delete true DEFAULT\_CONFIG redpanda.iceberg.mode disabled DEFAULT\_CONFIG redpanda.leaders.preference none DEFAULT\_CONFIG redpanda.remote.delete true DEFAULT\_CONFIG redpanda.remote.read true DEFAULT\_CONFIG redpanda.remote.write true DEFAULT\_CONFIG retention.bytes -1 DEFAULT\_CONFIG retention.local.target.bytes -1 DEFAULT\_CONFIG retention.local.target.ms 86400000 DEFAULT\_CONFIG retention.ms 604800000 DEFAULT\_CONFIG segment.bytes 134217728 DEFAULT\_CONFIG segment.ms 1209600000 DEFAULT\_CONFIG write.caching true DEFAULT\_CONFIG ### [](#explore-data-transforms)Explore Data transforms Data transforms let you run common data streaming tasks on the Redpanda broker, like filtering, scrubbing, and transcoding. For example, you may have consumers that require you to redact credit card numbers or convert JSON to Avro. This quickstart deployment comes with one transform function called `regex` running in your cluster. Its job is to find records in the `logins` topic that contain email addresses with the `.edu` domain and add those to a new topic called `edu-filtered-domains`. In the menu, click **Transforms**. On the **Transforms** page, you see your transform. You can use Redpanda Console to manage and monitor your transforms. > 📝 **NOTE** > > The source code for the data transform function is in the [`docker-compose/transform/transform.go` file](https://github.com/redpanda-data/docs/tree/main/tests/docker-compose/transform/transform.go) that you downloaded. This file is commented to explain how it works. ![transforms](../../console/_images/transforms.png) See also: - [Manage Data Transforms in Redpanda Console](../../console/ui/data-transforms/) - [Data Transforms](../../develop/data-transforms/) ### [](#view-audit-logs)View audit logs Audit logs provide a record of all user actions. You can use these logs to track changes, troubleshoot issues, and maintain compliance with your organization’s security policies. 1. In the menu, click **Topics**. 2. Click the **Show internal topics** checkbox. 3. Click the **\_redpanda.audit\_log** topic in the table. ![audit logs](../../console/_images/audit-logs.png) See also: [Audit Logging](../../manage/audit-logging/). ## [](#start-streaming)Start streaming To start building a basic streaming application, you can use the Redpanda CLI (`rpk`) to create a topic, produce messages to it, and consume messages from it. Each Redpanda broker comes preinstalled with `rpk`, so you can use it inside one of the Redpanda broker’s Docker containers. For simplicity, this quickstart uses the bootstrapped superuser (`superuser`) to perform all operations. The superuser has full administrative privileges, making it convenient for setup and exploration. However, to enhance security in a production environment, Redpanda Data recommends creating users with restricted permissions for each task. To use `rpk` inside the Redpanda broker’s Docker container: 1. Get information about the cluster: ```bash docker exec -it redpanda-0 rpk cluster info -X user=superuser -X pass=secretpassword ``` 2. Create a topic called **chat-room**: ```bash docker exec -it redpanda-0 rpk topic create chat-room \ --replicas 3 \ (1) --topic-config redpanda.remote.read=true \ (2) --topic-config redpanda.remote.write=true \ (3) -X user=superuser \ -X pass=secretpassword ``` | 1 | Set a replication factor of 3 to replicate the topic across all 3 brokers. This replication factor provides high availability and data durability. For more details, see Choose the replication factor. | | --- | --- | | 2 | Enable remote reads for this topic to read offloaded records from object storage. | | 3 | Enable remote writes for this topic to offload older records to object storage. For more details, see Use Tiered Storage.Output:TOPIC STATUS chat-room OK | 3. Produce a message to the topic: ```bash docker exec -it redpanda-0 rpk topic produce chat-room -X user=superuser -X pass=secretpassword ``` 4. Enter a message, then press Enter: ```text Pandas are fabulous! ``` Example output: Produced to partition 0 at offset 0 with timestamp 1663282629789. 5. Press Ctrl+C to finish producing messages to the topic. 6. Consume one message from the topic: ```bash docker exec -it redpanda-0 rpk topic consume chat-room --num 1 -X user=superuser -X pass=secretpassword ``` Your message is displayed along with its metadata: ```json { "topic": "chat-room", "value": "Pandas are fabulous!", "timestamp": 1663282629789, "partition": 0, "offset": 0 } ``` ### [](#connect-to-the-cluster-externally)Connect to the cluster externally It’s often more practical to connect to a remote cluster from your local machine with `rpk`. The `docker-compose.yml` file configured the containers to expose ports on your localhost, so you can communicate with the cluster outside the Docker network. To do so, download `rpk` on your local machine and configure it to connect to your cluster on the exposed ports. 1. Install `rpk` on your local machine: #### Linux > 💡 **TIP** > > You can use `rpk` on Windows only with [WSL](https://learn.microsoft.com/windows/wsl/install). However, commands that require Redpanda to be installed on your machine are not supported, such as [`rpk container`](../../reference/rpk/rpk-container/rpk-container/) commands, [`rpk iotune`](../../reference/rpk/rpk-iotune/), and [`rpk redpanda`](../../reference/rpk/rpk-redpanda/rpk-redpanda/) commands. ##### amd64 ```bash curl -LO https://github.com/redpanda-data/redpanda/releases/latest/download/rpk-linux-amd64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-linux-amd64.zip -d ~/.local/bin/ ``` ##### arm64 ```bash curl -LO https://github.com/redpanda-data/redpanda/releases/latest/download/rpk-linux-arm64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-linux-arm64.zip -d ~/.local/bin/ ``` #### macOS 1. If you don’t have Homebrew installed, [install it](https://brew.sh/). 2. To install or update `rpk`, run: ```bash brew install redpanda-data/tap/redpanda ``` 2. Create a profile to configure `rpk` to connect to your cluster: ```bash rpk profile create quickstart --from-profile rpk-profile.yaml ``` > 📝 **NOTE** > > The profile is configured in the [`docker-compose/rpk-profile.yaml` file](https://github.com/redpanda-data/docs/tree/main/tests/docker-compose/rpk-profile.yaml) that you downloaded. This file is commented to explain how it works. 3. Get information about the cluster to test the connection: ```bash rpk cluster info ``` > 📝 **NOTE** > > The Redpanda broker returns a list of all broker addresses, so `rpk` can communicate with all brokers directly. Each broker returns its configured `advertise-*` address that matches the port to which the initial connection has been made. You can see examples of these addresses in the Docker Compose file that you downloaded. ### [](#view-offloaded-data-in-tiered-storage)View offloaded data in Tiered Storage Tiered Storage keeps local disk usage stable and performance consistent by offloading older data to object storage. You can also use Tiered Storage to recover clusters or topics, mount and unmount topics from a cluster, and more. > 📝 **NOTE** > > Redpanda supports Amazon S3, Azure ADLS, and Google GCS as object storage providers. For this quickstart, Redpanda uses MinIO as the object storage provider. **MinIO is not supported for production deployments**. 1. Check the size of remote and local disks for the `chat-room` topic you created earlier: ```bash rpk cluster logdirs describe --topics chat-room ``` BROKER DIR TOPIC PARTITION SIZE ERROR 0 /var/lib/redpanda/data chat-room 0 611 0 remote://redpanda chat-room 0 319 1 /var/lib/redpanda/data chat-room 0 611 1 remote://redpanda chat-room 0 319 2 /var/lib/redpanda/data chat-room 0 611 2 remote://redpanda chat-room 0 319 - Local storage: `/var/lib/redpanda/data` holds recent data. - Remote storage: `remote://redpanda` holds offloaded data. 2. Open MinIO at [http://localhost:9001/browser](http://localhost:9001/browser) to view your data stored in the S3-compatible object store. Login credentials: - Username: ```none minio ``` - Password: ```none redpandaTieredStorage7 ``` See also: [Use Tiered Storage](../../manage/tiered-storage/). ## [](#deploy-a-pipeline-with-redpanda-connect)Deploy a pipeline with Redpanda Connect Redpanda Connect is a powerful tool that allows you to build and manage data streaming pipelines. It supports hundreds of connectors for various systems, enabling seamless data ingestion, transformation, and routing between different sources and sinks. Using declarative YAML configuration files and the `rpk` CLI, you can quickly set up and deploy complex data pipelines in Redpanda. 1. Deploy the example pipeline: ```bash rpk connect run ../generate-profiles.yaml ``` This pipeline is configured to generate fake user profiles and produce them to the `profiles` topic in your Redpanda cluster. It’ll run until you stop it. > 📝 **NOTE** > > The pipeline configuration is in the [`docker-compose/generate-profiles.yaml` file](https://github.com/redpanda-data/docs/tree/main/tests/docker-compose/generate-profiles.yaml) that you downloaded. This file is commented to explain how it works. 2. After a few seconds, stop the pipeline by pressing Ctrl+C. 3. Consume 10 messages from the `profiles` topic to confirm that the pipeline produced data to that topic. ```bash rpk topic consume profiles --num 10 ``` ## [](#extend-your-30-day-trial)Extend your 30-day trial Your initial trial license is valid for 30 days. To extend it by another 30 days: 1. [Sign up for a new trial license](https://cloud.redpanda.com/try-enterprise). 2. Upload the new license to your running cluster using [`rpk cluster license set`](../../reference/rpk/rpk-cluster/rpk-cluster-license-set/): ```bash rpk cluster license set ``` Replace the `` placeholder with your license. This command applies the new license to your Redpanda cluster, extending your access to enterprise features for another 30 days. 3. Restart Redpanda Console so that it can fetch the new license from the Redpanda brokers: ```bash docker restart redpanda-console ``` > 📝 **NOTE** > > You can extend the trial license only once. > 💡 **TIP: Ready to go into production?** > > [Upgrade to Redpanda Enterprise](https://www.redpanda.com/upgrade). See also: [Redpanda Licensing](../licensing/). ## [](#clean-up)Clean up To reset your environment, shut down the running processes and delete the containers: ```bash docker compose down ``` To delete the volumes along with all your cluster data: ```bash docker compose down -v ``` ## [](#customize-the-docker-quickstart)Customize the Docker quickstart To customize this quickstart, you can configure Redpanda, Redpanda Console, or Redpanda Connect using the provided Docker Compose file. This allows you to tailor the services to fit your specific requirements. ### [](#redpanda-broker-properties)Redpanda broker properties To configure the Redpanda services with [broker configuration properties](../../reference/properties/broker-properties/), pass properties with the `--set` option in the `redpanda start` command in your Docker Compose file. **Example:** `docker-compose.yml` ```yaml redpanda-0: (1) command: (2) - redpanda - start - --set pandaproxy_client.retries=6 (3) ``` | 1 | The service name in Docker Compose. | | --- | --- | | 2 | Overrides the default command for the Redpanda container. | | 3 | Sets the pandaproxy_client.retries broker configuration property to 6. | ### [](#redpanda-cluster-properties)Redpanda cluster properties Cluster-level configurations are defined in the `bootstrap.yml` file. This file is included in your Docker Compose setup. It contains essential settings that apply to the entire Redpanda cluster. You can find all cluster properties in [Cluster Configuration Properties](../../reference/properties/cluster-properties/). **Example:** `docker-compose.yml` ```yaml redpanda: volumes: - ./bootstrap.yml:/etc/redpanda/.bootstrap.yaml (1) ``` | 1 | Mounts the bootstrap.yml file from your local parent directory to the container’s /etc/redpanda/ directory. | | --- | --- | ### [](#redpanda-console-configuration)Redpanda Console configuration Redpanda Console configuration is managed with the environment variable `CONSOLE_CONFIG_FILE`. You can specify the path to your configuration file in the Docker Compose file. **Example:** `docker-compose.yml` ```yaml console: environment: CONSOLE_CONFIG_FILE: | # Configure a connection to the Redpanda cluster # See https://docs.redpanda.com/current/console/config/connect-to-redpanda/ kafka: brokers: ["redpanda-0:9092"] ``` ### [](#redpanda-connect-configuration)Redpanda Connect configuration Existing data pipelines are configured using the `CONNECT_CFG_FILE` environment variable in the `connect` service. This environment variable contains YAML configuration settings for Redpanda Connect. **Example:** `docker-compose.yml` ```yaml connect: environment: CONNECT_CFG_FILE: | input: generate: interval: 1s mapping: | let first_name = fake("first_name") let last_name = fake("last_name") root.user_id = counter() root.name = $$first_name + " " + $$last_name root.email = ($$first_name.slice(0,1) + $$last_name + "@" + fake("domain_name")).lowercase() root.ip = fake("ipv4") root.login_time = now() pipeline: processors: - mapping: | root = range(0, random_int(min:2, max:4)).map_each(cust -> this) - unarchive: format: "json_array" - mapping: | if batch_index() == 0 { meta topic = "logins" root = this } else { meta topic = "transactions" root.user_id = this.user_id root.email = this.email root.index = batch_index() - 1 root.product_url = fake("url") root.price = fake("amount_with_currency") root.timestamp = now() } output: kafka_franz: seed_brokers: [ "redpanda-0:9092" ] topic: $${! metadata("topic") } sasl: - mechanism: SCRAM-SHA-256 password: secretpassword username: superuser ``` To create new data pipelines, run `rpk connect run`, specifying the path to your own YAML configuration file: ```bash rpk connect run ``` ## [](#next-steps)Next steps [Contact Redpanda](https://www.redpanda.com/contact) to discuss using Redpanda Enterprise Edition in production. - [Try more examples in Redpanda Labs](../../../redpanda-labs/) - [Learn more about enterprise features for Redpanda Self-Managed](../licensing/overview/) - [Deploy for development or production](../../deploy/redpanda/manual/production/) ## [](#suggested-reading)Suggested reading - [Redpanda Connect Documentation](../../../redpanda-connect/home/) - [rpk Commands](../../reference/rpk/) - [Introduction to Redpanda Console](../../console/) - Docker images - [Docker images for Redpanda Console](https://hub.docker.com/r/redpandadata/console/tags) - [Docker images for Redpanda](https://hub.docker.com/r/redpandadata/redpanda) --- # Page 106: Redpanda Quickstarts **URL**: https://docs.redpanda.com/current/get-started/quickstarts.md --- # Redpanda Quickstarts --- title: Redpanda Quickstarts latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: quickstarts page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: quickstarts.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/get-started/pages/quickstarts.adoc description: Get started with Redpanda using these hands-on tutorials. Explore features that demonstrate how Redpanda can power your streaming applications. page-git-created-date: "2024-12-03" page-git-modified-date: "2024-12-03" support-status: supported --- - [Redpanda Self-Managed Quickstart](../quick-start/) Learn how to quickly start working with a local Redpanda cluster that comes with a free 30-day license for Enterprise Edition. You can also extend the trial license for a further 30 days. - [Redpanda CLI Quickstart](../rpk-quickstart/) Quickly become familiar with `rpk` commands for basic Redpanda tasks, including creating, producing to, describing, and deleting topics, as well as consuming records and managing consumer groups. - [Docker Compose Labs](../docker-compose-labs/) Explore this collection of hands-on labs for deploying and testing Redpanda Self-Managed using Docker Compose. Whether you're a beginner looking to get started or an experienced user aiming to deepen your knowledge, these labs provide step-by-step instructions and practical examples to enhance your skills. --- # Page 107: What’s New **URL**: https://docs.redpanda.com/current/get-started/release-notes.md --- # What’s New --- title: What’s New latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: release-notes/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: release-notes/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/get-started/pages/release-notes/index.adoc description: Summary of new features and updates. page-git-created-date: "2025-04-07" page-git-modified-date: "2025-04-07" support-status: supported --- - [What’s New in Redpanda](redpanda/) Summary of new features and updates in this Redpanda release. - [What’s New in the Redpanda Operator](operator/) Summary of new features and updates in the Redpanda Operator. - [What’s New in the Helm Charts](helm-charts/) Summary of new features and updates in the Helm charts for Redpanda and Redpanda Console. --- # Page 108: What’s New in the Helm Charts **URL**: https://docs.redpanda.com/current/get-started/release-notes/helm-charts.md --- # What’s New in the Helm Charts --- title: What’s New in the Helm Charts latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: release-notes/helm-charts page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: release-notes/helm-charts.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/get-started/pages/release-notes/helm-charts.adoc description: Summary of new features and updates in the Helm charts for Redpanda and Redpanda Console. page-git-created-date: "2025-04-07" page-git-modified-date: "2026-03-31" support-status: supported --- This topic includes new content and significant changes in the Redpanda and Redpanda Console Helm charts. For a complete list of all updates, see: - [Changelog for the Redpanda chart](https://github.com/redpanda-data/redpanda-operator/blob/v26.1.2/charts/redpanda/CHANGELOG.md). - [Changelog for the Redpanda Console chart](https://github.com/redpanda-data/redpanda-operator/blob/v26.1.2/charts/console/CHANGELOG.md). See also: - [What’s New in Redpanda](../redpanda/) - [Kubernetes Compatibility](../../../upgrade/k-compatibility/) - [Upgrade Redpanda in Kubernetes](../../../upgrade/k-rolling-upgrade/) ## [](#console-chart-v26-1-x)Console chart v26.1.x [Changelog](https://github.com/redpanda-data/redpanda-operator/blob/release/v26.1.x/charts/console/CHANGELOG.md). ### [](#prometheus-servicemonitor)Prometheus ServiceMonitor The Console Helm chart now supports deploying a Prometheus `ServiceMonitor` using `monitoring.enabled`, `monitoring.scrapeInterval`, and `monitoring.labels`. See [Prometheus ServiceMonitor](../../../deploy/console/kubernetes/deploy/#prometheus-servicemonitor). ## [](#redpanda-chart-v26-1-x)Redpanda chart v26.1.x [Changelog](https://github.com/redpanda-data/redpanda-operator/blob/release/v26.1.x/charts/redpanda/CHANGELOG.md). ### [](#config-watcher-sidecar-resource-configuration)Config-watcher sidecar resource configuration You can now configure explicit CPU and memory resource requests and limits for the config-watcher sidecar using `statefulset.sideCars.configWatcher.resources`. This is required in namespaces that enforce LimitRange or ResourceQuota policies. See [Configure config-watcher sidecar resources](../../../manage/kubernetes/k-manage-resources/#config-watcher). --- # Page 109: What’s New in the Redpanda Operator **URL**: https://docs.redpanda.com/current/get-started/release-notes/operator.md --- # What’s New in the Redpanda Operator --- title: What’s New in the Redpanda Operator latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: release-notes/operator page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: release-notes/operator.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/get-started/pages/release-notes/operator.adoc description: Summary of new features and updates in the Redpanda Operator. page-git-created-date: "2025-04-07" page-git-modified-date: "2026-03-31" support-status: supported --- This topic includes new content and significant changes in the Redpanda Operator. For a complete list of all updates, see the [Redpanda Operator changelog](https://github.com/redpanda-data/redpanda-operator/blob/v26.1.2/operator/CHANGELOG.md). See also: - [What’s New in Redpanda](../redpanda/) - [Kubernetes Compatibility](../../../upgrade/k-compatibility/) - [Upgrade Redpanda in Kubernetes](../../../upgrade/k-rolling-upgrade/) ## [](#redpanda-operator-v26-1-x)Redpanda Operator v26.1.x [Changelog](https://github.com/redpanda-data/redpanda-operator/blob/release/v26.1.x/operator/CHANGELOG.md) ### [](#prometheus-servicemonitor-for-console)Prometheus ServiceMonitor for Console The Console custom resource supports a `monitoring` configuration that deploys a Prometheus `ServiceMonitor` to automatically discover and scrape Console metrics. See [Prometheus ServiceMonitor](../../../deploy/console/kubernetes/deploy/#prometheus-servicemonitor). ### [](#schema-registry-acls)Schema Registry ACLs The Redpanda custom resource supports configuring Schema Registry ACLs through the `schemaRegistry.authenticationMethod` field. This enables fine-grained access control for Schema Registry operations in clusters deployed with Kubernetes. When you enable Schema Registry authentication, you can control which users and service accounts can register, modify, and read schemas. See [Configure Authentication for Redpanda in Kubernetes](../../../manage/kubernetes/security/authentication/k-authentication/) for configuration details. ### [](#cloud-topics-for-kubernetes)Cloud Topics for Kubernetes The Redpanda custom resource supports Cloud Topics in Kubernetes deployments. You can configure topics to use cloud storage as the primary backing store by setting the appropriate storage mode properties. Cloud Topics in Kubernetes provide the same cost savings and architectural benefits as self-managed deployments. You configure them declaratively through the Redpanda custom resource. For setup instructions, see [Manage Cloud Topics](../../../develop/manage-topics/cloud-topics/). ### [](#group-based-access-control-gbac)Group-based access control (GBAC) The Redpanda Operator supports group-based access control (GBAC) for Kubernetes deployments with OIDC authentication. You can assign roles and ACLs to OIDC groups, and users automatically inherit permissions from their group memberships. GBAC simplifies permission management in Kubernetes environments by integrating with your identity provider’s group structure. See [Configure Group-Based Access Control](../../../manage/security/authorization/gbac/) for configuration and usage details. --- # Page 110: What’s New in Redpanda **URL**: https://docs.redpanda.com/current/get-started/release-notes/redpanda.md --- # What’s New in Redpanda --- title: What’s New in Redpanda latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: release-notes/redpanda page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: release-notes/redpanda.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/get-started/pages/release-notes/redpanda.adoc description: Summary of new features and updates in this Redpanda release. page-git-created-date: "2025-04-07" page-git-modified-date: "2026-03-31" support-status: supported --- This topic includes new content added in version 26.1. For a complete list of all product updates, see the [Redpanda release notes](https://github.com/redpanda-data/redpanda/releases/). See also: - [What’s New in Redpanda Cloud](../../../../redpanda-cloud/get-started/whats-new-cloud/) - [Redpanda Cloud vs Self-Managed feature compatibility](../../../../redpanda-cloud/get-started/cloud-overview/#redpanda-cloud-vs-self-managed-feature-compatibility) ## [](#cloud-topics)Cloud Topics [Cloud Topics](../../../develop/manage-topics/cloud-topics/) are now available, making it possible to use durable cloud storage (S3, ADLS, GCS) as the primary backing store instead of local disk, eliminating over 90% of cross-AZ replication costs. This makes them ideal for latency-tolerant, high-throughput workloads such as observability streams, analytics pipelines, and AI/ML training data feeds, where cross-AZ networking charges are the dominant cost driver. You can use Cloud Topics exclusively in Redpanda Streaming clusters, or in combination with traditional Tiered Storage and local storage topics on a shared cluster supporting low latency workloads. Cloud Topics require Tiered Storage and an Enterprise license. For setup instructions and limitations, see [Manage Cloud Topics](../../../develop/manage-topics/cloud-topics/). ## [](#group-based-access-control-gbac)Group-based access control (GBAC) Redpanda 26.1 introduces [group-based access control (GBAC)](../../../manage/security/authorization/gbac/), which extends OIDC authentication to support group-based permissions. In addition to assigning roles or ACLs to individual users, you can assign them to OIDC groups. Users inherit permissions from all groups reported by their identity provider (IdP) in the OIDC token claims. GBAC supports two authorization patterns: - Assign a group as a member of an RBAC role so that all users in the group inherit the role’s ACLs. - Create ACLs directly with a `Group:` principal. Group membership is managed entirely by your IdP. Redpanda reads group information from the OIDC token at authentication time and works across the Kafka API, Schema Registry, and HTTP Proxy. ## [](#fips-140-3-validation-and-fips-docker-image)FIPS 140-3 validation and FIPS Docker image Redpanda’s cryptographic module has been upgraded from FIPS 140-2 to [FIPS 140-3](https://csrc.nist.gov/pubs/fips/140-3/final) validation. Additionally, Redpanda now provides a FIPS-specific Docker image (`docker.redpanda.com/redpandadata/redpanda:-fips`) for `amd64` and `arm64` architectures, with the required OpenSSL FIPS module pre-configured. > 📝 **NOTE** > > If you are upgrading with FIPS mode enabled, ensure all SASL/SCRAM user passwords are at least 14 characters before upgrading. FIPS 140-3 enforces stricter HMAC key size requirements. See [Configure Redpanda for FIPS](../../../manage/security/fips-compliance/) for configuration details. ## [](#iceberg-expanded-json-schema-support)Iceberg: Expanded JSON Schema support Redpanda now supports additional JSON Schema patterns when translating to Iceberg tables: - `$ref` support: Internal references using `$ref` (for example, `"$ref": "#/definitions/myType"`) are resolved from schema resources declared in the same document. External references are not yet supported. - Map type from `additionalProperties`: `additionalProperties` objects that contain subschemas now translate to Iceberg `map`. - `oneOf` nullable pattern: The `oneOf` keyword is now supported for the standard nullable pattern if exactly one branch is `{"type":"null"}` and the other is a non-null schema. See [Specify Iceberg Schema](../../../manage/iceberg/specify-iceberg-schema/#how-iceberg-modes-translate-to-table-format) for JSON types mapping and updated requirements. ## [](#ordered-rack-preference-for-leader-pinning)Ordered rack preference for Leader Pinning [Leader Pinning](../../../develop/produce-data/leader-pinning/) now supports the `ordered_racks` configuration value, which lets you specify preferred racks in priority order. Unlike `racks`, which distributes leaders uniformly across all listed racks, `ordered_racks` places leaders in the highest-priority available rack and fails over to subsequent racks only when higher-priority racks become unavailable. ## [](#user-based-throughput-quotas)User-based throughput quotas Redpanda now supports throughput quotas based on authenticated user principals. Unlike client-based quotas (which rely on self-declared `client-id` values), user-based quotas enforce limits using verified identities from SASL, mTLS, or OIDC authentication. You can set quotas for individual users, default users, or fine-grained user/client combinations. See [About Client Throughput Quotas](../../../manage/cluster-maintenance/about-throughput-quotas/) for conceptual details, and [Set user-based quotas](../../../manage/cluster-maintenance/manage-throughput/#set-user-based-quotas) to get started. ## [](#cross-region-remote-read-replicas)Cross-region Remote Read Replicas Remote Read Replica topics on AWS can be deployed in a different region from the origin cluster’s S3 bucket. This enables cross-region disaster recovery and data locality scenarios while maintaining the read-only replication model. To create cross-region Remote Read Replica topics, configure dynamic upstreams that point to the origin cluster’s S3 bucket location. Redpanda manages the number of concurrent dynamic upstreams based on your `cloud_storage_url_style` setting (virtual\_host or path style). See [Remote Read Replicas](../../../manage/tiered-storage/#remote-read-replicas) for setup instructions and configuration details. ## [](#automatic-broker-decommissioning)Automatic broker decommissioning When continuous partition balancing is enabled, Redpanda can automatically decommission brokers that remain unavailable for a configured duration. The [`partition_autobalancing_node_autodecommission_timeout_sec`](../../../reference/properties/cluster-properties/#partition_autobalancing_node_autodecommission_timeout_sec) property triggers permanent broker removal, unlike [`partition_autobalancing_node_availability_timeout_sec`](../../../reference/properties/cluster-properties/#partition_autobalancing_node_availability_timeout_sec) which only moves partitions temporarily. Key characteristics: - Disabled by default - Requires `partition_autobalancing_mode` set to `continuous` - Permanently removes the node from the cluster (the node cannot rejoin automatically) - Processes one decommission at a time to maintain cluster stability - Manual intervention required if decommission stalls See [Configure Continuous Data Balancing](../../../manage/cluster-maintenance/continuous-data-balancing/) for configuration details. ## [](#new-configuration-properties)New configuration properties **Storage mode:** - [`default_redpanda_storage_mode`](../../../reference/properties/cluster-properties/#default_redpanda_storage_mode): Set the default storage mode for new topics (`local`, `tiered`, `cloud`, or `unset`) - [`redpanda.storage.mode`](../../../reference/properties/topic-properties/#redpandastoragemode): Set the storage mode for an individual topic, superseding the legacy `redpanda.remote.read` and `redpanda.remote.write` properties **Cloud Topics:** > 📝 **NOTE** > > Cloud Topics requires an Enterprise license. For more information, contact [Redpanda sales](https://redpanda.com/try-redpanda?section=enterprise). - [`cloud_topics_allow_materialization_failure`](../../../reference/properties/cluster-properties/#cloud_topics_allow_materialization_failure): Enable recovery from missing L0 extent objects - [`cloud_topics_compaction_interval_ms`](../../../reference/properties/cluster-properties/#cloud_topics_compaction_interval_ms): Interval for background compaction - [`cloud_topics_compaction_key_map_memory`](../../../reference/properties/cluster-properties/#cloud_topics_compaction_key_map_memory): Maximum memory per shard for compaction key-offset maps - [`cloud_topics_compaction_max_object_size`](../../../reference/properties/cluster-properties/#cloud_topics_compaction_max_object_size): Maximum size for L1 objects produced by compaction - [`cloud_topics_epoch_service_max_same_epoch_duration`](../../../reference/properties/cluster-properties/#cloud_topics_epoch_service_max_same_epoch_duration): Maximum duration a node can use the same epoch - [`cloud_topics_fetch_debounce_enabled`](../../../reference/properties/cluster-properties/#cloud_topics_fetch_debounce_enabled): Enable fetch debouncing - [`cloud_topics_gc_health_check_interval`](../../../reference/properties/cluster-properties/#cloud_topics_gc_health_check_interval): L0 garbage collector health check interval - [`cloud_topics_l1_indexing_interval`](../../../reference/properties/cluster-properties/#cloud_topics_l1_indexing_interval): Byte interval for index entries in long-term storage objects - [`cloud_topics_long_term_file_deletion_delay`](../../../reference/properties/cluster-properties/#cloud_topics_long_term_file_deletion_delay): Delay before deleting stale long-term files - [`cloud_topics_long_term_flush_interval`](../../../reference/properties/cluster-properties/#cloud_topics_long_term_flush_interval): Interval for flushing long-term storage metadata to object storage - [`cloud_topics_metastore_lsm_apply_timeout_ms`](../../../reference/properties/cluster-properties/#cloud_topics_metastore_lsm_apply_timeout_ms): Timeout for applying replicated writes to LSM database - [`cloud_topics_metastore_replication_timeout_ms`](../../../reference/properties/cluster-properties/#cloud_topics_metastore_replication_timeout_ms): Timeout for L1 metastore Raft replication - [`cloud_topics_num_metastore_partitions`](../../../reference/properties/cluster-properties/#cloud_topics_num_metastore_partitions): Number of partitions for the metastore topic - [`cloud_topics_parallel_fetch_enabled`](../../../reference/properties/cluster-properties/#cloud_topics_parallel_fetch_enabled): Enable parallel fetching - [`cloud_topics_preregistered_object_ttl`](../../../reference/properties/cluster-properties/#cloud_topics_preregistered_object_ttl): Time-to-live for pre-registered L1 objects - [`cloud_topics_produce_no_pid_concurrency`](../../../reference/properties/cluster-properties/#cloud_topics_produce_no_pid_concurrency): Concurrent Raft requests for producers without a producer ID - [`cloud_topics_produce_write_inflight_limit`](../../../reference/properties/cluster-properties/#cloud_topics_produce_write_inflight_limit): Maximum in-flight write requests per shard - [`cloud_topics_reconciliation_max_interval`](../../../reference/properties/cluster-properties/#cloud_topics_reconciliation_max_interval): Maximum reconciliation interval for adaptive scheduling - [`cloud_topics_reconciliation_max_object_size`](../../../reference/properties/cluster-properties/#cloud_topics_reconciliation_max_object_size): Maximum size for L1 objects produced by the reconciler - [`cloud_topics_reconciliation_min_interval`](../../../reference/properties/cluster-properties/#cloud_topics_reconciliation_min_interval): Minimum reconciliation interval for adaptive scheduling - [`cloud_topics_reconciliation_parallelism`](../../../reference/properties/cluster-properties/#cloud_topics_reconciliation_parallelism): Maximum concurrent objects built by reconciliation per shard - [`cloud_topics_reconciliation_slowdown_blend`](../../../reference/properties/cluster-properties/#cloud_topics_reconciliation_slowdown_blend): Blend factor for slowing down reconciliation - [`cloud_topics_reconciliation_speedup_blend`](../../../reference/properties/cluster-properties/#cloud_topics_reconciliation_speedup_blend): Blend factor for speeding up reconciliation - [`cloud_topics_reconciliation_target_fill_ratio`](../../../reference/properties/cluster-properties/#cloud_topics_reconciliation_target_fill_ratio): Target fill ratio for L1 objects - [`cloud_topics_upload_part_size`](../../../reference/properties/cluster-properties/#cloud_topics_upload_part_size): Part size for multipart uploads - [`cloud_topics_epoch_service_epoch_increment_interval`](../../../reference/properties/cluster-properties/#cloud_topics_epoch_service_epoch_increment_interval): Interval for cluster epoch incrementation - [`cloud_topics_epoch_service_local_epoch_cache_duration`](../../../reference/properties/cluster-properties/#cloud_topics_epoch_service_local_epoch_cache_duration): Cache duration for local epoch data - [`cloud_topics_long_term_garbage_collection_interval`](../../../reference/properties/cluster-properties/#cloud_topics_long_term_garbage_collection_interval): Interval for long-term storage garbage collection - [`cloud_topics_produce_batching_size_threshold`](../../../reference/properties/cluster-properties/#cloud_topics_produce_batching_size_threshold): Object size threshold that triggers upload - [`cloud_topics_produce_cardinality_threshold`](../../../reference/properties/cluster-properties/#cloud_topics_produce_cardinality_threshold): Partition cardinality threshold that triggers upload - [`cloud_topics_produce_upload_interval`](../../../reference/properties/cluster-properties/#cloud_topics_produce_upload_interval): Time interval that triggers upload - [`cloud_topics_reconciliation_interval`](../../../reference/properties/cluster-properties/#cloud_topics_reconciliation_interval): Interval for moving data from short-term to long-term storage - [`cloud_topics_short_term_gc_backoff_interval`](../../../reference/properties/cluster-properties/#cloud_topics_short_term_gc_backoff_interval): Backoff interval for short-term storage garbage collection - [`cloud_topics_short_term_gc_interval`](../../../reference/properties/cluster-properties/#cloud_topics_short_term_gc_interval): Interval for short-term storage garbage collection - [`cloud_topics_short_term_gc_minimum_object_age`](../../../reference/properties/cluster-properties/#cloud_topics_short_term_gc_minimum_object_age): Minimum age for objects to be eligible for short-term garbage collection **Object storage:** - [`cloud_storage_gc_max_segments_per_run`](../../../reference/properties/object-storage-properties/#cloud_storage_gc_max_segments_per_run): Maximum number of log segments to delete from object storage during each [housekeeping run](../../../manage/tiered-storage/#object-storage-housekeeping) - [`cloud_storage_prefetch_segments_max`](../../../reference/properties/object-storage-properties/#cloud_storage_prefetch_segments_max): Maximum number of small segments to prefetch during sequential reads **Authentication:** - [`nested_group_behavior`](../../../reference/properties/cluster-properties/#nested_group_behavior): Control how Redpanda handles nested groups extracted from authentication tokens - [`oidc_group_claim_path`](../../../reference/properties/cluster-properties/#oidc_group_claim_path): JSON path to extract groups from the JWT payload - [`schema_registry_enable_qualified_subjects`](../../../reference/properties/cluster-properties/#schema_registry_enable_qualified_subjects): Enable parsing of qualified subject syntax in Schema Registry **Other:** - [`delete_topic_enable`](../../../reference/properties/cluster-properties/#delete_topic_enable): Enable or disable topic deletion via the Kafka DeleteTopics API - [`internal_rpc_request_timeout_ms`](../../../reference/properties/cluster-properties/#internal_rpc_request_timeout_ms): Default timeout for internal RPC requests between nodes - [`log_compaction_max_priority_wait_ms`](../../../reference/properties/cluster-properties/#log_compaction_max_priority_wait_ms): Maximum time a priority partition (such as `__consumer_offsets`) waits before preempting regular compaction - [`partition_autobalancing_node_autodecommission_timeout_sec`](../../../reference/properties/cluster-properties/#partition_autobalancing_node_autodecommission_timeout_sec): Duration a node must be unavailable before Redpanda automatically decommissions it ### [](#changes-to-default-values)Changes to default values - [`log_compaction_tx_batch_removal_enabled`](../../../reference/properties/cluster-properties/#log_compaction_tx_batch_removal_enabled): Changed from `false` to `true`. - [`tls_v1_2_cipher_suites`](../../../reference/properties/cluster-properties/#tls_v1_2_cipher_suites): Changed from OpenSSL cipher names to IANA cipher names. ### [](#removed-properties)Removed properties The following deprecated configuration properties have been removed in v26.1.1. If you have any of these in your configuration files, update them according to the guidance below. **RPC timeout properties:** Replace with [`internal_rpc_request_timeout_ms`](../../../reference/properties/cluster-properties/#internal_rpc_request_timeout_ms). - `alter_topic_cfg_timeout_ms` - `create_topic_timeout_ms` - `metadata_status_wait_timeout_ms` - `node_management_operation_timeout_ms` - `recovery_append_timeout_ms` - `rm_sync_timeout_ms` - `tm_sync_timeout_ms` - `wait_for_leader_timeout_ms` **Client throughput quota properties:** Use [`rpk cluster quotas`](../../../reference/rpk/rpk-cluster/rpk-cluster-quotas/) to manage [client throughput limits](../../../manage/cluster-maintenance/manage-throughput/#client-throughput-limits). - `kafka_admin_topic_api_rate` - `kafka_client_group_byte_rate_quota` - `kafka_client_group_fetch_byte_rate_quota` - `target_fetch_quota_byte_rate` - `target_quota_byte_rate` **Quota balancer properties:** Use [broker-wide throughput limit properties](../../../manage/cluster-maintenance/manage-throughput/#broker-wide-throughput-limit-properties). - `kafka_quota_balancer_min_shard_throughput_bps` - `kafka_quota_balancer_min_shard_throughput_ratio` - `kafka_quota_balancer_node_period` - `kafka_quota_balancer_window` - `kafka_throughput_throttling_v2` **Timestamp alert properties:** - `log_message_timestamp_alert_after_ms`: Use [`log_message_timestamp_after_max_ms`](../../../reference/properties/cluster-properties/#log_message_timestamp_after_max_ms) - `log_message_timestamp_alert_before_ms`: Use [`log_message_timestamp_before_max_ms`](../../../reference/properties/cluster-properties/#log_message_timestamp_before_max_ms) **Other removed properties:** No replacement needed. These properties were deprecated placeholders that have been silently ignored and will continue to be ignored even after removal. - `cloud_storage_disable_metadata_consistency_checks` - `cloud_storage_reconciliation_ms` - `coproc_max_batch_size` - `coproc_max_inflight_bytes` - `coproc_max_ingest_bytes` - `coproc_offset_flush_interval_ms` - `datalake_disk_space_monitor_interval` - `enable_admin_api` - `enable_coproc` - `find_coordinator_timeout_ms` - `full_raft_configuration_recovery_pattern` - `id_allocator_replication` - `kafka_memory_batch_size_estimate_for_fetch` - `log_compaction_adjacent_merge_self_compaction_count` - `max_version` - `min_version` - `raft_max_concurrent_append_requests_per_follower` - `raft_recovery_default_read_size` - `rm_violation_recovery_policy` - `schema_registry_protobuf_renderer_v2` - `seed_server_meta_topic_partitions` - `seq_table_min_size` - `tm_violation_recovery_policy` - `transaction_coordinator_replication` - `tx_registry_log_capacity` - `tx_registry_sync_timeout_ms` - `use_scheduling_groups` --- # Page 111: Install or Update rpk **URL**: https://docs.redpanda.com/current/get-started/rpk-install.md --- # Install or Update rpk --- title: Install or Update rpk latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk-install page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk-install.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/get-started/pages/rpk-install.adoc description: Install or update rpk to interact with Redpanda from the command line. page-git-created-date: "2023-05-30" page-git-modified-date: "2025-05-07" support-status: supported --- The `rpk` tool is a single binary application that provides a way to interact with your Redpanda clusters from the command line. For example, you can use `rpk` to do the following: - Monitor your cluster’s health - Create, produce, and consume from topics - Set up access control lists (ACLs) and other security features For Redpanda Self-Managed deployments, the `rpk` binary is automatically installed on each Redpanda broker, so you can use the locally installed `rpk` binary to communicate with the local Redpanda cluster. You can also install `rpk` on your local machine as a standalone binary. With this setup, you can connect to a Redpanda cluster on your local machine and to an external one on a remote server. If you use `rpk` as a standalone binary to communicate with a Redpanda cluster, your installed version of `rpk` must match the version of Redpanda running in your cluster. ## [](#check-rpk-version)Check rpk version To check your current version of the rpk binary, run `rpk --version`. The following example lists the latest version of `rpk`. If your installed version is lower than this latest version, then update `rpk`. For a list of versions, see [Redpanda releases](https://github.com/redpanda-data/redpanda/releases/). ```bash rpk --version ``` ```bash rpk version 26.1.3 (rev 65d85f6) ``` ## [](#install-or-update-rpk-on-linux)Install or update rpk on Linux To install, or update to, the latest version of `rpk` for Linux, run: ### amd64 ```bash curl -LO https://github.com/redpanda-data/redpanda/releases/latest/download/rpk-linux-amd64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-linux-amd64.zip -d ~/.local/bin/ ``` ### arm64 ```bash curl -LO https://github.com/redpanda-data/redpanda/releases/latest/download/rpk-linux-arm64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-linux-arm64.zip -d ~/.local/bin/ ``` > 💡 **TIP** > > You can use `rpk` on Windows only with [WSL](https://learn.microsoft.com/windows/wsl/install). However, commands that require Redpanda to be installed on your machine are not supported, such as [`rpk container`](../../reference/rpk/rpk-container/rpk-container/) commands, [`rpk iotune`](../../reference/rpk/rpk-iotune/), and [`rpk redpanda`](../../reference/rpk/rpk-redpanda/rpk-redpanda/) commands. To install, or update to, a version other than the latest, run: ### amd64 ```bash curl -LO https://github.com/redpanda-data/redpanda/releases/download/v/rpk-linux-amd64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-linux-amd64.zip -d ~/.local/bin/ ``` ### arm64 ```bash curl -LO https://github.com/redpanda-data/redpanda/releases/download/v/rpk-linux-arm64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-linux-arm64.zip -d ~/.local/bin/ ``` ## [](#install-or-update-rpk-on-macos)Install or update rpk on macOS ### Homebrew 1. If you don’t have Homebrew installed, [install it](https://brew.sh/). 2. To install or update `rpk`, run: ```bash brew install redpanda-data/tap/redpanda ``` ### Manual Download To install or update `rpk` through a manual download, choose the option for your system architecture. For example, if you have an M1 or newer chip, select **Apple Silicon**. #### Intel macOS To install, or update to, the latest version of `rpk` for Intel macOS, run: ```bash curl -LO https://github.com/redpanda-data/redpanda/releases/latest/download/rpk-darwin-amd64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-darwin-amd64.zip -d ~/.local/bin/ ``` To install, or update to, a version other than the latest, run: ```bash curl -LO https://github.com/redpanda-data/redpanda/releases/download/v/rpk-darwin-amd64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-darwin-amd64.zip -d ~/.local/bin/ ``` #### Apple Silicon To install, or update to, the latest version of `rpk` for Apple Silicon, run: ```bash curl -LO https://github.com/redpanda-data/redpanda/releases/latest/download/rpk-darwin-arm64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-darwin-arm64.zip -d ~/.local/bin/ ``` To install, or update to, a version other than the latest, run: ```bash curl -LO https://github.com/redpanda-data/redpanda/releases/download/v/rpk-darwin-arm64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-darwin-arm64.zip -d ~/.local/bin/ ``` ## [](#next-steps)Next steps For the complete list of `rpk` commands and their syntax, see the [rpk reference](../../reference/rpk/). Explore `rpk` with the [Redpanda CLI Quickstart](../rpk-quickstart/). --- # Page 112: Redpanda CLI Quickstart **URL**: https://docs.redpanda.com/current/get-started/rpk-quickstart.md --- # Redpanda CLI Quickstart --- title: Redpanda CLI Quickstart latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk-quickstart page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk-quickstart.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/get-started/pages/rpk-quickstart.adoc description: Quickly become familiar with rpk commands for basic Redpanda tasks, including creating, producing to, describing, and deleting topics, as well as consuming records and managing consumer groups. page-git-created-date: "2025-01-28" page-git-modified-date: "2025-02-17" support-status: supported --- This guide shows how to run the Redpanda CLI, `rpk`, for basic Redpanda tasks, including creating, producing to, describing, and deleting topics, as well as consuming records and managing consumer groups. Follow these examples to quickly become familiar with `rpk` commands. Consider creating an `rpk` profile to simplify your development experience with multiple Redpanda clusters by saving and reusing configurations for different clusters. For more information, see [About rpk profiles](../config-rpk-profile/#about-rpk-profiles). ## [](#prerequisites)Prerequisites - A running Redpanda cluster. - The `rpk` CLI installed. See [Install or Update rpk](../rpk-install/). ## [](#create-a-topic)Create a topic To start streaming data, first create a topic as the destination for your records: ```bash rpk topic create tutorial ``` Output: ```bash TOPIC STATUS tutorial OK ``` See [rpk topic create](../../reference/rpk/rpk-topic/rpk-topic-create/). ## [](#produce-records-to-a-topic)Produce records to a topic Produce records to the topic. Downstream consumers will then be able to read these records. To exit the producer session, press `Ctrl+C`: ```bash rpk topic produce tutorial ``` Additional input: ```bash hello world ``` Output: ```bash Produced to partition 0 at offset 0 with timestamp 1734640650348. Produced to partition 0 at offset 1 with timestamp 1734640653558. ``` See [rpk topic produce](../../reference/rpk/rpk-topic/rpk-topic-produce/). ## [](#get-a-description-of-a-topic)Get a description of a topic Check the topic’s configuration and status to ensure that it’s ready for use: ```bash rpk topic describe tutorial ``` Output: ```bash SUMMARY ======= NAME tutorial PARTITIONS 1 REPLICAS 1 CONFIGS ======= KEY VALUE SOURCE cleanup.policy delete DEFAULT_CONFIG compression.type producer DEFAULT_CONFIG delete.retention.ms -1 DEFAULT_CONFIG flush.bytes 262144 DEFAULT_CONFIG flush.ms 100 DEFAULT_CONFIG initial.retention.local.target.bytes -1 DEFAULT_CONFIG initial.retention.local.target.ms -1 DEFAULT_CONFIG max.message.bytes 1048576 DEFAULT_CONFIG message.timestamp.type CreateTime DEFAULT_CONFIG redpanda.iceberg.delete true DEFAULT_CONFIG redpanda.iceberg.mode disabled DEFAULT_CONFIG redpanda.leaders.preference none DEFAULT_CONFIG redpanda.remote.delete true DEFAULT_CONFIG redpanda.remote.read false DEFAULT_CONFIG redpanda.remote.write false DEFAULT_CONFIG retention.bytes -1 DEFAULT_CONFIG retention.local.target.bytes -1 DEFAULT_CONFIG retention.local.target.ms 86400000 DEFAULT_CONFIG retention.ms 604800000 DEFAULT_CONFIG segment.bytes 134217728 DEFAULT_CONFIG segment.ms 1209600000 DEFAULT_CONFIG write.caching true DEFAULT_CONFIG ``` See [rpk topic describe](../../reference/rpk/rpk-topic/rpk-topic-describe/). ## [](#consume-records-from-a-topic)Consume records from a topic Consume records from the topic: ```bash rpk topic consume tutorial ``` Output: ```json { "topic": "tutorial", "value": "hello", "timestamp": 1678807229837, "partition": 0, "offset": 0 } { "topic": "tutorial", "value": "world", "timestamp": 1678807232413, "partition": 0, "offset": 1 } ``` Consume from an offset, where `2` is not inclusive: ```bash rpk topic consume tutorial --offset 0:2 ``` Output: ```json { "topic": "tutorial", "value": "hello", "timestamp": 1678807229837, "partition": 0, "offset": 0 } { "topic": "tutorial", "value": "world", "timestamp": 1678807232413, "partition": 0, "offset": 1 } ``` See [rpk topic consume](../../reference/rpk/rpk-topic/rpk-topic-consume/). ## [](#create-a-consumer-group-and-consume-topics)Create a consumer group and consume topics Organize consumers into groups to share workloads and balance consumption: ```bash rpk topic consume tutorial --group tutorial-group ``` > 📝 **NOTE** > > The consumer group is created when you start consuming from the topic. Output: ```json { "topic": "tutorial", "value": "hello", "timestamp": 1734640650348, "partition": 0, "offset": 0 } { "topic": "tutorial", "value": "world", "timestamp": 1734640653558, "partition": 0, "offset": 1 } ``` See [rpk topic consume](../../reference/rpk/rpk-topic/rpk-topic-consume/). ## [](#list-all-consumer-groups)List all consumer groups List available consumer groups in your cluster: ```bash rpk group list ``` Output: ```bash BROKER GROUP STATE 0 tutorial-group Empty ``` See [rpk group list](../../reference/rpk/rpk-group/rpk-group-list/). ## [](#get-a-description-of-a-consumer-group)Get a description of a consumer group View details about the consumer group’s state, coordinator, members, and offsets: ```bash rpk group describe tutorial-group ``` Output: ```bash GROUP tutorial-group COORDINATOR 0 STATE Empty BALANCER MEMBERS 0 TOTAL-LAG 0 TOPIC PARTITION CURRENT-OFFSET LOG-START-OFFSET LOG-END-OFFSET LAG MEMBER-ID CLIENT-ID HOST tutorial 0 2 0 2 0 ``` See [rpk group describe](../../reference/rpk/rpk-group/rpk-group-describe/). ## [](#delete-a-consumer-group)Delete a consumer group Clean up by removing the `tutorial-group` consumer group: ```bash rpk group delete tutorial-group ``` Output: ```bash GROUP STATUS tutorial-group OK ``` See [rpk group delete](../../reference/rpk/rpk-group/rpk-group-delete/). ## [](#delete-a-topic)Delete a topic Clean up by removing the `tutorial` topic: ```bash rpk topic delete tutorial ``` Output: ```bash TOPIC STATUS tutorial OK ``` See [rpk topic delete](../../reference/rpk/rpk-topic/rpk-topic-delete/). ## [](#next-steps)Next steps - To generate a profile to save and reuse configurations for different Redpanda clusters, see [About rpk profiles](../config-rpk-profile/#about-rpk-profiles). - For the complete list of `rpk` commands and their syntax, see the [rpk Command Reference](../../reference/rpk/). --- # Page 113: Redpanda CLI **URL**: https://docs.redpanda.com/current/get-started/rpk.md --- # Redpanda CLI --- title: Redpanda CLI latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/get-started/pages/rpk/index.adoc description: The rpk command line interface tool lets you manage your Redpanda cluster, without the need to run a separate script for each function, as with Apache Kafka. page-git-created-date: "2023-07-26" page-git-modified-date: "2024-02-26" support-status: supported --- - [Introduction to rpk](../intro-to-rpk/) Learn about `rpk` and how to use it to interact with your Redpanda cluster. - [Install or Update rpk](../rpk-install/) Install or update `rpk` to interact with Redpanda from the command line. - [rpk Profiles](../config-rpk-profile/) Use `rpk profile` to simplify your development experience with multiple Redpanda clusters by saving and reusing configurations for different clusters. - [Specify Broker Addresses for rpk](../broker-admin/) Learn how and when to specify Redpanda broker addresses for `rpk` commands, so `rpk` knows where to run Kafka-related commands. - [Specify Admin API Addresses for rpk](../admin-addresses/) Learn how and when to specify Redpanda admin addresses for `rpk` commands, so `rpk` knows where to run admin-related commands. --- # Page 114: Redpanda Self-Managed Documentation **URL**: https://docs.redpanda.com/current/home.md --- # Redpanda Self-Managed Documentation --- title: Redpanda Self-Managed Documentation latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/home/pages/index.adoc description: Home page for the Redpanda docs site. page-git-created-date: "2023-05-05" page-git-modified-date: "2024-09-04" support-status: supported --- ## Overview Redpanda is a Kafka-compatible event streaming platform built for data-intensive applications. Install Self-Managed Redpanda in your environment with the free Community Edition or with the Enterprise Edition for additional features like Tiered Storage, Continuous Data Balancing, and Audit Logging. [Learn more](../get-started/intro-to-events/) ## Deploy[](#home-primary-title) [ ### Docker quickstart Start using Redpanda in a self-managed environment. Get started ](../get-started/quick-start/) --- # Page 115: Manage **URL**: https://docs.redpanda.com/current/manage.md --- # Manage --- title: Manage latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/index.adoc description: Manage Redpanda. page-git-created-date: "2023-05-30" page-git-modified-date: "2024-02-26" support-status: supported --- - [Manage Redpanda in Kubernetes](kubernetes/) Learn how to manage Redpanda in Kubernetes. - [Cluster Maintenance](cluster-maintenance/) Learn about cluster balancing, rolling upgrades, disk space management, and cluster diagnostics. - [Security](security/) Learn how to configure authentication, authorization, encryption, listeners, and other security features. - [Tiered Storage](tiered-storage-linux/) Tiered Storage helps to lower storage costs by offloading log segments to object storage. - [Integrate Redpanda with Iceberg](iceberg/) Generate Iceberg tables for your Redpanda topics for data lakehouse access. - [Schema Registry](schema-reg/) Redpanda's Schema Registry provides the interface to store and manage event schemas. - [High Availability](high-availability/) Learn about the trade-offs with different high availability configurations. - [Disaster Recovery](disaster-recovery/) Learn about Shadowing with cross-region replication for disaster recovery. - [Remote Read Replicas](remote-read-replicas/) Learn how to create a Remote Read Replica topic, which is a read-only topic that mirrors a topic on a different cluster. - [Recovery Mode](recovery-mode/) Recovery mode starts Redpanda with limited functionality and disables partitions so you can repair a failed cluster. - [Enable Rack Awareness](rack-awareness/) Enable rack awareness to place partition replicas across different failure zones. - [Raft Group Reconfiguration](raft-group-reconfiguration/) Learn how the Redpanda Raft group protocol provides consistency and availability during reconfiguration. - [Optimize I/O](io-optimization/) Learn how to optimize I/O performance. - [Redpanda Console](console/) Learn how to manage Redpanda using Redpanda Console. - [Manage Redpanda using the Admin API](use-admin-api/) Manage components of a Redpanda cluster, such as individual brokers and partition leadership. The Redpanda Admin API also allows you to perform operations that are specific to Redpanda Self-Managed and cannot be done using the standard Kafka API. - [Monitor Redpanda](monitoring/) Metrics to monitor the health of your system to predict issues and optimize performance. --- # Page 116: Audit Logging **URL**: https://docs.redpanda.com/current/manage/audit-logging.md --- # Audit Logging --- title: Audit Logging latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: audit-logging page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: audit-logging.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/audit-logging.adoc description: Learn how to use Redpanda's audit logging capabilities. page-git-created-date: "2023-12-22" page-git-modified-date: "2025-07-31" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../get-started/licensing/#self-managed) apply. Many scenarios for streaming data include the need for fine-grained auditing of user activity related to the system. This is especially true for regulated industries such as finance, healthcare, and the public sector. Complying with [PCI DSS v4](https://www.pcisecuritystandards.org/document_library/?document=pci_dss) standards, for example, requires verbose and detailed activity auditing, alerting, and analysis capabilities. Redpanda’s auditing capabilities support recording both administrative and operational interactions with topics and with users. Redpanda complies with the Open Cybersecurity Schema Framework (OCSF), providing a predictable and extensible solution that works seamlessly with industry standard tools. With audit logging enabled, there should be no noticeable changes in performance other than slightly elevated CPU usage. > 📝 **NOTE** > > Audit logging is configured at the cluster level. Redpanda supports excluding specific topics or principals from auditing to help reduce noise in the log. Audit logging is disabled by default. ## [](#audit-log-flow)Audit log flow The Redpanda audit log mechanism functions similar to the Kafka flow. When a user interacts with another user or with a topic, Redpanda writes an event to a specialized audit topic. The audit topic is immutable. Only Redpanda can write to it. Users are prevented from writing to the audit topic directly and the Kafka API cannot create or delete it. ![Audit log flow](../../shared/_images/audit-logging-flow.png) By default, any management and authentication actions performed on the cluster yield messages written to the audit log topic that are retained for seven days. Interactions with all topics by all principals are audited. Actions performed using the Kafka API and Admin API are all audited, as are actions performed directly through `rpk`. Messages recorded to the audit log topic comply with the [open cybersecurity schema framework](https://schema.ocsf.io/). Any number of analytics frameworks, such as Splunk or Sumo Logic, can receive and process these messages. Using an open standard ensures Redpanda’s audit logs coexist with those produced by other IT assets, powering holistic monitoring and analysis of your assets. ## [](#audit-log-configuration-options)Audit log configuration options Redpanda’s audit logging mechanism supports several options to control the volume and availability of audit records. Configuration is applied at the cluster level. - [`audit_enabled`](../../reference/properties/cluster-properties/#audit_enabled): Boolean value to enable audit logging. When you set this to `true`, Redpanda checks for an existing topic named `_redpanda.audit_log`. If none is found, Redpanda automatically creates one for you. Default: `false`. - [`audit_log_num_partitions`](../../reference/properties/cluster-properties/#audit_log_num_partitions): Integer value defining the number of partitions used by a newly created audit topic. This configuration applies only to the audit log topic and may be different from the cluster or other topic configurations. This cannot be altered for an existing audit log topic. Default: `12`. - [`audit_log_replication_factor`](../../reference/properties/cluster-properties/#audit_log_replication_factor): Optional Integer value defining the replication factor for a newly created audit log topic. This configuration applies only to the audit log topic and may be different from the cluster or other topic configurations. This cannot be altered for existing audit log topics. If a value is not provided, Redpanda uses the `internal_topic_replication_factor` cluster property value. Default: `null`. - [`audit_client_max_buffer_size`](../../reference/properties/cluster-properties/#audit_client_max_buffer_size): Integer value defining the number of bytes allocated by the internal audit client for audit messages. When changing this, you must disable audit logging and then re-enable it for the change to take effect. Consider increasing this if your system generates a very large number of audit records in a short amount of time. Default: `16777216`. - [`audit_queue_max_buffer_size_per_shard`](../../reference/properties/cluster-properties/#audit_queue_max_buffer_size_per_shard): Integer value defining the maximum amount of memory in bytes used by the audit buffer in each shard. When this size is reached, requests to log additional audit messages return a non-retryable error. You must restart the cluster when changing this value. Default: `1048576`. - [`audit_enabled_event_types`](../../reference/properties/cluster-properties/#audit_enabled_event_types): List of strings in JSON style identifying the event types to include in the audit log. This may include any of the following: `management, produce, consume, describe, heartbeat, authenticate, schema_registry, admin`. Default: `'["management","authenticate","admin"]'`. - [`audit_excluded_topics`](../../reference/properties/cluster-properties/#audit_excluded_topics): List of strings in JSON style identifying the topics the audit logging system should ignore. This list cannot include the `_redpanda.audit_log` topic. Redpanda rejects the command if you do attempt to include that topic. Default: `null`. - [`audit_queue_drain_interval_ms`](../../reference/properties/cluster-properties/#audit_queue_drain_interval_ms): Internally, Redpanda batches audit log messages in memory and periodically writes them to the audit log topic. This defines the period in milliseconds between draining this queue to the audit log topic. Longer intervals may help prevent duplicate messages, especially in high throughput scenarios, but they also increase the risk of data loss during hard shutdowns where the queue is lost. Default: `500`. - [`audit_excluded_principals`](../../reference/properties/cluster-properties/#audit_excluded_principals): List of strings in JSON style identifying the principals the audit logging system should ignore. Principals can be listed as `User:name` or `name`, both are accepted. Default: `null`. Even though audited event messages are stored to a specialized immutable topic, standard topic settings still apply. For example, you can apply the same Tiered Storage, retention time, and replication settings available to normal topics. These particular options are important for controlling the amount of disk space utilized by your audit topics. > ❗ **IMPORTANT** > > You must configure certain audit logging properties before enabling audit logging because these settings impact the creation of the `_redpanda.audit_log` topic itself. These properties include: `audit_log_num_partitions` and `audit_log_replication_factor`. The Kafka API allows you to add partitions or alter the replication factor after enabling audit logging, but Redpanda prevents you from altering these two configuration values directly. ## [](#audit-logging-event-types)Audit logging event types Redpanda’s auditable events fall into one of eight different event types. The APIs associated with each event type are as follows. | Audit event type | Associated APIs | | --- | --- | | management | AlterPartitionReassignmentsCreateACLsCreatePartitionsCreateTopicsDeleteAclsDeleteGroupsDeleteRecordsDeleteTopicsIncrementalAlterconfigsOffsetDelete | | produce | AddPartitionsToTxnEndTxnInitProducerIdProduce | | consume | AddOffsetsToTxnFetchJoinGroupLeaveGroupListOffsetOffsetCommitSyncGroupTxOffsetCommit | | describe | DescribeAclsDescribeConfigsDescribeGroupsDescribeLogDirsFindCoordinatorListGroupsListPartitionReassignmentsMetadataOffsetForLeaderEpochDescribeProducersDescribeTransationsListTransactions | | heartbeat | Heartbeat | | authenticate | All authentication events | | schema_registry | All Schema Registry API calls | | admin | All Admin API calls | ### [](#logged-events)Logged events The following table identifies the data logging level for each audit event entry. > 📝 **NOTE** > > The Included column captures whether the event itself is included (for example, successful and failed access attempts), or whether a piece of data is included in the event itself (for example, Source IP address). | Data Logging Level | Audit Event | Included? | Details | | --- | --- | --- | --- | | System Level | Date and time stamp for each entry | Yes | time field on each event | | Successful and failed access attempts | Yes | The status_id field shows success/failure for all access attempts for which auditing is enabled | | User ID | Yes | user.name | | User group memberships | Yes | user.groups field with type idp_group. Included in authentication events for OIDC users and in authorization events when a group ACL matches. See Configure Group-Based Access Control. | | User connect and disconnect time | No | Connect and disconnect time may be inferred from the presence or absence of activity. | | Password change | Yes | For SCRAM users managed through Redpanda core, the Admin API call associated with the password change is logged. Note that this does not cover users synced from external IdPs, such as through OIDC. | | Changes of security settings | Yes | For example, ACL creation is logged (kafka create_acls), and cluster configuration changes are logged (Admin API events) | | Successful and failed attempts to add/remove users from the system | Yes | See Password change | | Failed attempts to access system data | Yes | Generally, access attempts are logged. For example, kafka produce and consume calls are audited. | | Failed attempts to access critical directories and files | No | Not applicable | | Date and time of system start-up and shut-down | Yes | An application lifecycle event is logged when the broker starts/stops | | Use of external/peripheral devices | No | Not applicable | | Application Level | Transaction date and time | Yes | time field on each event | | User ID | Yes | user.name | | Source IP address | Yes | src_endpoint.ip field | | Type of transaction | Yes | api.operation shows the relevant Kafka API accessed or HTTP method used (Admin/Schema Registry) | | Transaction data | Yes | resources[] for Kafka ops; http_request (headers, URL) for HTTP endpoints | | Transaction result (success/fail) and reason of failure | Partial | Auditing occurs at request time (start of event). Authentication failures are captured with status_id and status_detail fields. However, downstream operation outcomes (whether the actual Kafka/Admin API/Schema Registry operation succeeded or failed) are not included in audit logs. | | Transaction number | No | Redpanda auditing does not assign a unique number to each request | | Failed attempts to access system data | Yes | Access attempts are logged through various audit event types | | Failed attempts to access critical directories and files | No | Not applicable | | Use of external/peripheral devices | Yes | Device access events are captured when applicable | | Network Level | Source IP address (IPv4 or IPv6) | Yes | src_endpoint.ip field | | Destination IP address (IPv4 or IPv6) | Yes | dst_endpoint.ip field | | Protocol/Ports | Yes | service.name shows the service/protocol used (kafka/http). http_request.url.scheme shows http/https for http requests. dst_endpoint.port may be indicative of the protocol. | | Timestamp | Yes | time field | | Host name | Yes | url.hostname: HTTP endpoints (Admin API / Schema Registry) include the HTTP hostname. Not included for Kafka (only source/destination IP). | | VLAN ID | No | Not applicable | | MAC address | No | Not applicable | ## [](#enable-audit-logging)Enable audit logging All audit log settings are applied at the cluster level. Use `rpk cluster config` to configure audit logs. Some options require a cluster restart. You can verify this using `rpk cluster config status`. Some key tuning recommendations for your audit logging settings include: - To change the number of partitions or the replication factor for your audit log topic, set the `audit_log_num_partitions` and `audit_log_replication_factor` properties, respectively. - Choose the type of events needed by setting `audit_enabled_event_types` to the desired list of event categories. Keep this as restrictive as possible based on your compliance and security needs to avoid excessive noise in your audit logs. - Identify non-sensitive topics so that you can exclude them from auditing. Specify this list of topics in `audit_excluded_topics`. - Identify non-sensitive principals so that you can exclude them from auditing. Specify this list of principals in `audit_excluded_principals`. This command accepts names as `name` or `User:name`. - Set `audit_enabled` to `true`. - [Optimize costs for audit logging](#optimize-costs-for-audit-logging). The sequence of commands in `rpk` for this audit log configuration is: rpk cluster config set audit\_log\_num\_partitions 6 rpk cluster config set audit\_log\_replication\_factor 5 rpk cluster config set audit\_enabled\_event\_types '\["management","describe","authenticate"\]' rpk cluster config set audit\_excluded\_topics '\["topic1","topic2"\]' rpk cluster config set audit\_excluded\_principals '\["User:principal1", "principal2"\]' rpk cluster config set audit\_enabled true rpk topic alter-config \_redpanda.audit\_log --set retention.ms=259200000 ## [](#optimize-costs-for-audit-logging)Optimize costs for audit logging When enabled, audit logging can quickly generate a very large amount of data, especially if all event types are selected. Proper configuration of audit logging is critical to avoid filling your disk or using excess Tiered Storage. The configuration options available help ensure your audit logs contain only the volume of data necessary to meet your regulatory or legal requirements. With audit logging, the pattern of message generation may be very different from your typical sources of data. These messages reflect usage of your system as opposed to the operational data your topics typically process. As a result, your retention, replication, and Tiered Storage requirements may differ from your other topics. A typical scenario with audit logging is to route the messages to an analytics platform like Splunk. If your retention period is too long, you may find that you are storing excessive amounts of replicated messages in both Redpanda and in your analytics suite. Identifying the right balance of retention and replication settings minimizes this duplication while retaining your data in a system that provides actionable intelligence. Assess the retention needs for your audit logs. You may not need to keep the logs for the default seven days. This is controlled by setting [`retention.ms`](../../reference/properties/topic-properties/#retentionms) for the `_redpanda.audit_log` topic or by setting [`log_retention_ms`](../../reference/properties/cluster-properties/#log_retention_ms) at the cluster level. ## [](#next-steps)Next steps [See samples of audit log messages](audit-log-samples/) ## [](#suggested-reading)Suggested reading - [Topic Configuration Properties](../../reference/properties/topic-properties/) - [Manage Topics](../../develop/manage-topics/config-topics/) ## Suggested labs - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) [Search all labs](/redpanda-labs) --- # Page 117: Sample Audit Log Messages **URL**: https://docs.redpanda.com/current/manage/audit-logging/audit-log-samples.md --- # Sample Audit Log Messages --- title: Sample Audit Log Messages latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: audit-logging/audit-log-samples page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: audit-logging/audit-log-samples.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/audit-logging/audit-log-samples.adoc description: Sample Redpanda audit log messages. page-git-created-date: "2023-12-22" page-git-modified-date: "2026-04-07" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../get-started/licensing/#self-managed) apply. Redpanda’s audit logs comply with version 1.0.0 of the [Open Cybersecurity Schema Framework (OCSF)](https://github.com/ocsf). This provides a predictable and extensible solution that works seamlessly with industry standard tools. This page aggregates several sample log files covering a range of scenarios. ## [](#standard-ocsf-messages)Standard OCSF messages Redpanda produces the following standard OCSF class messages: - Authentication (3002) for all authentication events - Application Lifecycle (6002) for when the audit system is enabled or disabled or when Redpanda starts or stops (if auditing is enabled when Redpanda starts or stops) - API Activity (6003) for any access to the Kafka API, Admin API, or Schema Registry Refer to the [OCSF Schema Definition](https://schema.ocsf.io/) for the field definitions for each event class. ## [](#authentication-events)Authentication events These messages illustrate various scenarios around successful and unsuccessful authentication events. Authentication successful This scenario shows the message resulting from an admin using rpk with successful authentication. This is an authentication type event. ```json { "category_uid": 3, "class_uid": 3002, "metadata": { "product": { "name": "Redpanda", // This is the Node ID of the broker that produced this audit event "uid": "2", "vendor_name": "Redpanda Data, Inc.", "version": "v23.3.0-dev-2457-g76dc896f8c" }, "version": "1.0.0" }, "severity_id": 1, "time": 1700533469078, "type_uid": 300201, "activity_id": 1, "auth_protocol": "SASL-SCRAM", "auth_protocol_id": 99, // This is the IP address of the Kafka broker that received the authorization request "dst_endpoint": { "ip": "127.0.0.1", "port": 19092, // Name of the Redpanda kafka server "svc_name": "kafka rpc protocol" }, // Indicates that credentials were not encrypted using TLS "is_cleartext": true, "is_mfa": false, "service": { "name": "kafka rpc protocol" }, // This is the IP address of the client that generated the authorization request "src_endpoint": { "ip": "127.0.0.1", // This is the client ID of the kafka client "name": "rpk", "port": 42906 }, "status_id": 1, "user": { "name": "user", "type_id": 1 } } ``` Authentication successful (OIDC with group claims) This scenario shows a successful OIDC authentication event that includes the user’s IdP group memberships in the `user.groups` field. Group memberships are extracted from the OIDC token and included in all authentication events for OIDC users. ```json { "category_uid": 3, "class_uid": 3002, "metadata": { "product": { "name": "Redpanda", "uid": "0", "vendor_name": "Redpanda Data, Inc.", "version": "v26.1.1" }, "version": "1.0.0" }, "severity_id": 1, "time": 1700533469078, "type_uid": 300201, "activity_id": 1, "auth_protocol": "SASL-OAUTHBEARER", "auth_protocol_id": 99, "dst_endpoint": { "ip": "127.0.0.1", "port": 9092, "svc_name": "kafka rpc protocol" }, "is_cleartext": false, "is_mfa": false, "service": { "name": "kafka rpc protocol" }, "src_endpoint": { "ip": "10.0.1.50", "name": "kafka-client", "port": 48210 }, "status_id": 1, // IdP group memberships extracted from the OIDC token "user": { "name": "alice@example.com", "type_id": 1, "groups": [ {"type": "idp_group", "name": "engineering"}, {"type": "idp_group", "name": "analytics"} ] } } ``` Authentication failed This scenario illustrates a common failure where a user entered the wrong credentials. This is an authentication type event. ```json { "category_uid": 3, "class_uid": 3002, "metadata": { "product": { "name": "Redpanda", "uid": "1", "vendor_name": "Redpanda Data, Inc.", "version": "v23.3.0-dev-2457-g76dc896f8c" }, "version": "1.0.0" }, "severity_id": 1, "time": 1700534756350, "type_uid": 300201, "activity_id": 1, "auth_protocol": "SASL-SCRAM", "auth_protocol_id": 99, "dst_endpoint": { "ip": "127.0.0.1", "port": 19092, "svc_name": "kafka rpc protocol" }, "is_cleartext": true, "is_mfa": false, "service": { "name": "kafka rpc protocol" }, "src_endpoint": { "ip": "127.0.0.1", "name": "rpk", "port": 45236 }, "status_id": 2, "status_detail": "SASL authentication failed: security: Invalid credentials", "user": { "name": "admin", "type_id": 1 } } ``` ## [](#kafka-api-events)Kafka API events The Redpanda Kafka API offers a wide array of options for interacting with your Redpanda clusters. Following are examples of messages from common interactions with the API. Create ACL entry This example illustrates an ACL update that also requires a superuser authentication. It lists the edited ACL and the updated permissions. This is a management type event. ```json { "category_uid": 6, "class_uid": 6003, "metadata": { "product": { "name": "Redpanda", "vendor_name": "Redpanda Data, Inc.", "version": "v23.3.0-dev-2457-g76dc896f8c" }, "profiles": [ "cloud" ], "version": "1.0.0" }, "severity_id": 1, "time": 1700533393776, "type_uid": 600303, "activity_id": 3, "actor": { "authorizations": [ { "decision": "authorized", // This shows a superuser level authorization "policy": { "desc": "superuser", "name": "aclAuthorization" } } ], "user": { "name": "admin", "type_id": 2 } }, "api": { // The API operation performed "operation": "create_acls", "service": { "name": "kafka rpc protocol" } }, "cloud": { "provider": "" }, "dst_endpoint": { "ip": "127.0.0.1", "port": 19092, "svc_name": "kafka rpc protocol" }, // List of resources accessed "resources": [ // The created ACL { "name": "create acl", "type": "acl_binding", "data": { "resource_type": "topic", "resource_name": "*", "pattern_type": "literal", "acl_principal": "{type user name user}", "acl_host": "{{any_host}}", "acl_operation": "all", "acl_permission": "allow" } }, // Below indicates that the user had cluster level authorization { "name": "kafka-cluster", "type": "cluster" } ], "src_endpoint": { "ip": "127.0.0.1", "name": "rpk", "port": 50276 }, "status_id": 1, "unmapped": { // Provides a more parsable output of how the // authorization decision was made "authorization_metadata": { "acl_authorization": { "host": "", "op": "", "permission_type": "AUTHORIZED", "principal": "" }, "resource": { "name": "", "pattern": "", "type": "" } } } } ``` Authorization matched on a group ACL This example shows an API Activity (6003) where the authorization decision matched an ALLOW ACL on a `Group:` principal. The `actor.user.groups` field includes the matched group with type `idp_group`, and the `authorization_metadata` shows the group ACL that granted access. See [Group-Based Access Control](../../security/authorization/gbac/). ```json { "category_uid": 6, "class_uid": 6003, "metadata": { "product": { "name": "Redpanda", "uid": "0", "vendor_name": "Redpanda Data, Inc.", "version": "v26.1.0" }, "version": "1.0.0" }, "severity_id": 1, "time": 1774544504327, "type_uid": 600303, "activity_id": 3, "actor": { "authorizations": [ { "decision": "authorized", "policy": { "desc": "acl: {principal type {group} name {/sales} host {{any_host}} op all perm allow}, resource: type {topic} name {sales-topic} pattern {literal}", "name": "aclAuthorization" } } ], // The matched group appears in the user's groups field "user": { "name": "alice", "type_id": 1, "groups": [ { "type": "idp_group", "name": "/sales" } ] } }, "api": { "operation": "produce", "service": { "name": "kafka rpc protocol" } }, "dst_endpoint": { "ip": "127.0.1.1", "port": 9092, "svc_name": "kafka rpc protocol" }, "resources": [ { "name": "sales-topic", "type": "topic" } ], "src_endpoint": { "ip": "127.0.0.1", "name": "rdkafka", "port": 42728 }, "status_id": 1, "unmapped": { "authorization_metadata": { "acl_authorization": { "host": "{{any_host}}", "op": "all", "permission_type": "allow", "principal": "type {group} name {/sales}" }, "resource": { "name": "sales-topic", "pattern": "literal", "type": "topic" } } } } ``` Metadata request (with counts) This shows a message for a scenario where a user requests a set of metadata using rpk. It provides detailed information on the type of request and the information sent to the user. This is a describe type event. ```json { "category_uid": 6, "class_uid": 6003, // If present, indicates that >1 of the same authz check was performed // within the period of the audit log collecting entries // This provides start and end time (the time period these events were // observed) "count": 2, "end_time": 1700533480725, "metadata": { "product": { "name": "Redpanda", "uid": "0", "vendor_name": "Redpanda Data, Inc.", "version": "v23.3.0-dev-2457-g76dc896f8c" }, "profiles": [ "cloud" ], "version": "1.0.0" }, "severity_id": 1, "start_time": 1700533480724, "time": 1700533480724, "type_uid": 600303, "activity_id": 3, "actor": { "authorizations": [ { "decision": "authorized", // Represents a policy for a non-super user "policy": { "desc": "acl: {principal {type user name user} host {{any_host}} op all perm allow}, resource: type {topic} name {*} pattern {literal}", "name": "aclAuthorization" } } ], "user": { "name": "user", "type_id": 1 } }, "api": { "operation": "metadata", "service": { "name": "kafka rpc protocol" } }, "cloud": { "provider": "" }, "dst_endpoint": { "ip": "127.0.0.1", "port": 19092, "svc_name": "kafka rpc protocol" }, "resources": [ // The topics accessed { "name": "test", "type": "topic" } ], "src_endpoint": { "ip": "127.0.0.1", "name": "rpk", "port": 53602 }, "status_id": 1, "unmapped": { "authorization_metadata": { "acl_authorization": { "host": "{{any_host}}", "op": "all", "permission_type": "allow", "principal": "{type user name user}" }, "resource": { "name": "*", "pattern": "literal", "type": "topic" } } } } ``` ## [](#admin-api-events)Admin API events The following examples show audit messages related to use of the Redpanda Admin API. Requesting cluster configurations as a superuser This example shows the log message when you use the Admin API to retrieve the cluster configurations in a zipped archive. Note that a user must authenticate with the superuser role to perform this action. ```json { "category_uid": 6, "class_uid": 6003, "metadata": { "product": { "name": "Redpanda", "uid": "2", "vendor_name": "Redpanda Data, Inc.", "version": "v23.3.0-dev-2457-g76dc896f8c" }, "profiles": [ "cloud" ], "version": "1.0.0" }, "severity_id": 1, "time": 1700575714976, "type_uid": 600302, "activity_id": 2, "actor": { "authorizations": [ { "decision": "authorized", "policy": { "desc": "", "name": "Admin httpd authorizer" } } ], "user": { "name": "admin", "type_id": 2 } }, "api": { "operation": "GET", "service": { "name": "Redpanda Admin HTTP Server" } }, "cloud": { "provider": "" }, "dst_endpoint": { "ip": "127.0.0.1", "port": 9644, "svc_name": "Redpanda Admin HTTP Server" }, "http_request": { "http_headers": [ { "name": "Accept-Encoding", "value": "gzip" }, { "name": "Accept", "value": "application/json" }, { "name": "Content-Type", "value": "application/json" }, { "name": "User-Agent", "value": "Go-http-client/1.1" }, { "name": "Authorization", "value": "******" }, { "name": "Host", "value": "127.0.0.1:9644" } ], "http_method": "GET", "url": { "hostname": "127.0.0.1:9644", "path": "/v1/cluster_config?include_defaults=true", "port": 9644, "scheme": "http", "url_string": "http://127.0.0.1:9644/v1/cluster_config?include_defaults=true" }, "user_agent": "Go-http-client/1.1", "version": "1.1" }, "src_endpoint": { "ip": "127.0.0.1", "port": 44150 }, "status_id": 1, "unmapped": {} } ``` Unauthorized user requesting cluster configurations Similar to the previous example, this example illustrates a user requesting cluster configurations as a zip archive. Unlike the previous example, however, the user in this case is not authorized to retrieve this information. ```json { "category_uid": 6, "class_uid": 6003, "metadata": { "product": { "name": "Redpanda", "uid": "0", "vendor_name": "Redpanda Data, Inc.", "version": "v23.3.0-dev-2457-g76dc896f8c" }, "profiles": [ "cloud" ], "version": "1.0.0" }, "severity_id": 1, "time": 1700576203097, "type_uid": 600302, "activity_id": 2, "actor": { "authorizations": [ { "decision": "denied", "policy": { "desc": "Forbidden (superuser role required)", "name": "Admin httpd authorizer" } } ], "user": { "name": "user", "type_id": 1 } }, "api": { "operation": "GET", "service": { "name": "Redpanda Admin HTTP Server" } }, "cloud": { "provider": "" }, "dst_endpoint": { "ip": "127.0.0.1", "port": 9644, "svc_name": "Redpanda Admin HTTP Server" }, "http_request": { "http_headers": [ { "name": "Accept-Encoding", "value": "gzip" }, { "name": "Accept", "value": "application/json" }, { "name": "Content-Type", "value": "application/json" }, { "name": "User-Agent", "value": "Go-http-client/1.1" }, { "name": "Authorization", "value": "******" }, { "name": "Host", "value": "127.0.0.1:9644" } ], "http_method": "GET", "url": { "hostname": "127.0.0.1:9644", "path": "/v1/cluster_config?include_defaults=true", "port": 9644, "scheme": "http", "url_string": "http://127.0.0.1:9644/v1/cluster_config?include_defaults=true" }, "user_agent": "Go-http-client/1.1", "version": "1.1" }, "src_endpoint": { "ip": "127.0.0.1", "port": 53296 }, "status_id": 2, "unmapped": {} } ``` ## Suggested labs - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) [Search all labs](/redpanda-labs) --- # Page 118: Cluster Maintenance **URL**: https://docs.redpanda.com/current/manage/cluster-maintenance.md --- # Cluster Maintenance --- title: Cluster Maintenance latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: cluster-maintenance/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: cluster-maintenance/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/cluster-maintenance/index.adoc description: Learn about cluster balancing, rolling upgrades, disk space management, and cluster diagnostics. page-git-created-date: "2023-06-02" page-git-modified-date: "2024-02-26" support-status: supported --- - [Configure Cluster Properties](cluster-property-configuration/) Learn how to configure cluster properties. - [Configure Broker Properties](node-property-configuration/) Learn how to configure broker properties with the `redpanda.yaml` file. - [Configure Topic Properties](topic-property-configuration/) Learn how to configure topic properties to control Redpanda's behavior for individual topics, including retention, cleanup policies, and Tiered Storage settings. - [Cluster Balancing](cluster-balancing/) Learn about the different tools Redpanda provides for balanced clusters. - [Configure Continuous Data Balancing](continuous-data-balancing/) Continuous Data Balancing simplifies operations with self-healing clusters that dynamically balance partitions. - [Decommission Brokers](decommission-brokers/) Remove a broker so that it is no longer considered part of the cluster. - [Maintenance Mode](../node-management/) Enable maintenance mode to temporarily take a broker offline, for example during a rolling upgrade. - [Perform a Rolling Restart](rolling-restart/) Learn how to perform a rolling restart of your Redpanda cluster. - [Audit Logging](../audit-logging/) Learn how to use Redpanda's audit logging capabilities. - [Manage Disk Space](disk-utilization/) Redpanda provides several ways to manage disk space to ensure the stability of a cluster. - [About Client Throughput Quotas](about-throughput-quotas/) Understand how Redpanda's user-based and client ID-based throughput quotas work, including entity hierarchy, precedence rules, and quota tracking behavior. - [Manage Throughput](manage-throughput/) Configure broker-wide and client-specific throughput quotas to prevent resource exhaustion and noisy-neighbor issues. - [Compaction Settings](compaction-settings/) Redpanda's approach to compaction and options for configuring it. - [Configure Client Connections](configure-client-connections/) Learn about guidelines for configuring client connections in Redpanda clusters for optimal availability. - [Forced partition recovery](partition-recovery/) Recover a single partition using the Admin API. - [Node-wise Partition Recovery](nodewise-partition-recovery/) Feature to recover partitions that have lost a majority of replicas. --- # Page 119: About Client Throughput Quotas **URL**: https://docs.redpanda.com/current/manage/cluster-maintenance/about-throughput-quotas.md --- # About Client Throughput Quotas --- title: About Client Throughput Quotas latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: cluster-maintenance/about-throughput-quotas page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: cluster-maintenance/about-throughput-quotas.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/cluster-maintenance/about-throughput-quotas.adoc description: Understand how Redpanda's user-based and client ID-based throughput quotas work, including entity hierarchy, precedence rules, and quota tracking behavior. page-topic-type: concepts personas: platform_admin, developer learning-objective-1: Describe the difference between user-based and client ID-based quotas learning-objective-2: Determine which quota type to use for your use case learning-objective-3: Explain quota precedence rules and how Redpanda tracks quota usage page-git-created-date: "2026-03-31" page-git-modified-date: "2026-03-31" support-status: supported --- Redpanda uses throughput quotas to limit the rate of produce and consume requests from clients. Understanding how quotas work helps you prevent individual clients from disproportionately consuming resources and causing performance degradation for other clients (also known as the "noisy-neighbor" problem), and ensure fair resource sharing across users and applications. After reading this page, you will be able to: - Describe the difference between user-based and client ID-based quotas - Determine which quota type to use for your use case - Explain quota precedence rules and how Redpanda tracks quota usage To configure and manage throughput quotas, see [Manage Throughput](../manage-throughput/). ## [](#throughput-control-overview)Throughput control overview Redpanda provides two ways to control throughput: - Broker-wide limits: Configured using cluster properties. For details, see [Broker-wide throughput limits](../manage-throughput/#broker-wide-throughput-limits). - Client throughput quotas: Configured using the Kafka API. Client quotas enable per-user and per-client rate limiting with fine-grained control through entity hierarchy and precedence rules. This page focuses on client quotas. ## [](#supported-quota-types)Supported quota types Redpanda supports three Kafka API-based quota types: | Quota type | Description | | --- | --- | | producer_byte_rate | Limit throughput of produce requests (bytes per second) | | consumer_byte_rate | Limit throughput of fetch requests (bytes per second) | | controller_mutation_rate | Limit rate of topic mutation requests (partitions created or deleted per second) | All quota types can be applied to groups of client connections based on user principals, client IDs, or combinations of both. ## [](#quota-entities)Quota entities Redpanda uses two pieces of identifying information from each client connection to determine which quota applies: - Client ID: An ID that clients self-declare. Quotas can target an exact client ID (`client-id`) or a prefix (`client-id-prefix`). Multiple client connections that share a client ID or ID prefix are grouped into a single quota entity. - User [principal](https://docs.redpanda.com/current/reference/glossary/#principal): An authenticated identity verified through SASL, mTLS, or OIDC. Connections that share the same user are considered one entity. You can configure quotas that target either entity type, or combine both for fine-grained control. ### [](#client-id-based-quotas)Client ID-based quotas Client ID-based quotas apply to clients identified by their `client-id` field, which is set by the client application. The client ID is typically a configurable property when you create a client with Kafka libraries. When using client ID-based quotas, multiple clients using the same client ID share the same quota tracking. Client ID-based quotas rely on clients honestly reporting their identity and correctly setting the `client-id` property. This makes client ID-based quotas unsuitable for guaranteeing isolation between tenants. Use client ID-based quotas when: - Authentication is not enabled. - Grouping by application or service name is sufficient. - You operate a single-tenant environment where all clients are trusted. - You need simple rate limiting without user-level isolation. ### [](#user-based-quotas)User-based quotas > ❗ **IMPORTANT** > > User-based quotas require [authentication](../../security/authentication/) to be enabled on your cluster. User-based quotas apply to authenticated user principals. Each user has a separate quota, providing a way to limit the impact of individual users on the cluster. User-based quotas rely on Redpanda’s authentication system to verify user identity. The user principal is extracted from SASL credentials, mTLS certificates, or OIDC tokens and cannot be forged by clients. Use user-based quotas when: - You operate a multi-tenant environment, such as SaaS platforms or enterprises with departments. - You require isolation between users or tenants, to avoid noisy-neighbor issues. - You need per-user billing or metering. ### [](#combined-user-and-client-quotas)Combined user and client quotas You can combine user and client identities for fine-grained control over specific (user, client) combinations. Use combined quotas when: - You need fine-grained control, for example: user `alice` using a specific application. - Different rate limits apply to different apps used by the same user. For example, `alice`'s `payment-processor` gets 10 MB/s, but `alice`'s `analytics-consumer` gets 50 MB/s. See [Quota precedence and tracking](#quota-precedence-and-tracking) for examples. ## [](#quota-precedence-and-tracking)Quota precedence and tracking When a request arrives, Redpanda resolves which quota to apply by matching the request’s authenticated user principal and client ID against configured quotas. Redpanda applies the most specific match, using the precedence order in the following table (highest priority first). The precedence level that matches also determines how quota usage is tracked. Redpanda tracks quota usage using a tracker key that determines which connections share the same quota bucket. How connections are grouped into buckets depends on the type of entity the quota targets. To get independent quota tracking per user and client ID combination, configure quotas that include both dimensions, such as `/config/users//clients/` or `/config/users//clients/`. | Level | Match type | Config path | Tracker key | Isolation behavior | | --- | --- | --- | --- | --- | | 1 | Exact user + exact client | /config/users//clients/ | (user, client-id) | Each unique (user, client-id) pair tracked independently | | 2 | Exact user + client prefix | /config/users//client-id-prefix/ | (user, client-id-prefix) | Clients matching the prefix share tracking within that user | | 3 | Exact user + default client | /config/users//clients/ | (user, client-id) | Each unique (user, client-id) pair tracked independently | | 4 | Exact user only | /config/users/ | user | All clients for that user share a single tracking bucket | | 5 | Default user + exact client | /config/users//clients/ | (user, client-id) | Each unique (user, client-id) pair tracked independently | | 6 | Default user + client prefix | /config/users//client-id-prefix/ | (user, client-id-prefix) | Clients matching the prefix share tracking within each user | | 7 | Default user + default client | /config/users//clients/ | (user, client-id) | Each unique (user, client-id) pair tracked independently | | 8 | Default user only | /config/users/ | user | All clients for each user share a single tracking bucket (per user) | | 9 | Exact client only | /config/clients/ | client-id | All users with that client ID share a single tracking bucket | | 10 | Client prefix only | /config/client-id-prefix/ | client-id-prefix | All clients matching the prefix share a single bucket across all users | | 11 | Default client only | /config/clients/ | client-id | Each unique client ID tracked independently | | 12 | No quota configured | N/A | N/A | No tracking / unlimited throughput | > ❗ **IMPORTANT** > > The `` entity matches any user or client that doesn’t have a more specific quota configured. This is different from an empty/unauthenticated user (`user=""`), or undeclared client ID (`client-id=""`), which are treated as specific entities. ### [](#unauthenticated-connections)Unauthenticated connections Unauthenticated connections have an empty user principal (`user=""`) and are not treated as `user=`. Unauthenticated connections: - Fall back to client-only quotas. - Have unlimited throughput only if no client-only quota matches. ### [](#example-precedence-resolution)Example: Precedence resolution Given these configured quotas: ```bash rpk cluster quotas alter --add consumer_byte_rate=5000000 --name user=alice --name client-id=app-1 rpk cluster quotas alter --add consumer_byte_rate=10000000 --name user=alice rpk cluster quotas alter --add consumer_byte_rate=20000000 --name client-id=app-1 ``` | User + Client ID | Precedence match | | --- | --- | | user=alice, client-id=app-1 | Level 1: Exact user + exact client | | user=alice, client-id=app-2 | Level 4: Exact user only | | user=bob, client-id=app-1 | Level 9: Exact client only | | user=bob, client-id=app-2 | Level 12: No quota configured | When no quota matches (level 12), the connection is not throttled. ### [](#example-user-only-quota)Example: User-only quota If you configure a 10 MB/s produce quota for user `alice`: ```bash rpk cluster quotas alter --add producer_byte_rate=10000000 --name user=alice ``` Then `alice` connecting with client ID `app-1` and `alice` connecting with client ID `app-2` share the same 10 MB/s produce limit. To give each of `alice`'s clients an independent 10 MB/s limit, configure: ```bash rpk cluster quotas alter --add producer_byte_rate=10000000 --name user=alice --default client-id ``` ### [](#example-user-default-quota)Example: User default quota If you configure a default 10 MB/s produce quota for all users: ```bash rpk cluster quotas alter --add producer_byte_rate=10000000 --default user ``` This quota applies to all users who don’t have a more specific quota configured. Each user is tracked independently: `alice` gets her own 10 MB/s bucket, `bob` gets his own 10 MB/s bucket, and so on. Within each user, all client ID values share that user’s bucket. `alice` connecting with client ID `app-1` and `alice` connecting with client ID `app-2` share the same 10 MB/s produce limit, while `bob`'s connections have a separate 10 MB/s limit. ## [](#throttling-enforcement)Throughput throttling enforcement > 📝 **NOTE** > > As of v24.2, Redpanda enforces all throughput limits per broker, including client throughput. Redpanda enforces throughput limits by applying backpressure to clients. When a connection exceeds its throughput limit, Redpanda throttles the connection to bring the rate back within the allowed level: 1. Redpanda adds a `throttle_time_ms` field to responses, indicating how long the client should wait. 2. If the client doesn’t honor the throttle time, Redpanda inserts delays on the connection’s next read operation. The throttling delay may not exceed the limit set by the `max_kafka_throttle_delay_ms` tunable property. ## [](#default-behavior)Default behavior Quotas are opt-in restrictions and not enforced by default. When no quotas are configured, clients have unlimited throughput. ## [](#next-steps)Next steps - [Configure throughput quotas](../manage-throughput/) - [Enable authentication for user-based quotas](../../security/authentication/) --- # Page 120: Cluster Balancing **URL**: https://docs.redpanda.com/current/manage/cluster-maintenance/cluster-balancing.md --- # Cluster Balancing --- title: Cluster Balancing latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: cluster-maintenance/cluster-balancing page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: cluster-maintenance/cluster-balancing.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/cluster-maintenance/cluster-balancing.adoc description: Learn about the different tools Redpanda provides for balanced clusters. page-git-created-date: "2023-06-02" page-git-modified-date: "2025-08-15" support-status: supported --- Cluster balancing is crucial for optimal performance. Unbalanced clusters can saturate resources on one or more brokers, impacting throughput and latency. Furthermore, a cluster with replicas on a down broker risks availability loss if more brokers fail, and a cluster that keeps losing brokers without healing eventually risks data loss. Redpanda provides various topic-aware tools to balance clusters for best performance. | Topic-aware data balancer | Description | | --- | --- | | Partition leadership balancing | This balancer transfers the leadership of a broker’s partitions to other replicas to avoid topic leadership hotspots on one or a few specific brokers in your cluster.The partition leader regularly sends heartbeats to its followers. If a follower does not receive a heartbeat within a timeout, it triggers a new leader election. Redpanda also provides leadership balancing when brokers are added or decommissioned. | | Partition replica balancing | This balancer moves partition replicas to avoid topic replica hotspots on one or a few specific brokers in your cluster.Redpanda prioritizes balancing a topic’s partition replica count evenly across all brokers while it’s balancing the cluster’s overall partition count. Because different topics in a cluster can have vastly different load profiles, this better distributes the workload evenly across brokers.Redpanda provides partition replica balancing when brokers are added or decommissioned. | | Intra-broker partition balancing | This balancer moves partition replicas across CPU cores in an individual broker. Redpanda maintains balanced partition replica assignments between cores to avoid topic hotspots on one or a few specific cores within a broker.Continuous Intra-Broker Partition Balancing (core_balancing_continuous) requires an enterprise license. | | Continuous Data Balancing | This balancer monitors broker and rack availability, as well as disk usage, to avoid topic hotspots when moving data off brokers with fuller disks. Continuous Data Balancing enables self-healing clusters that dynamically balance partitions. It also ensures adherence to rack-aware replica placement policy and self-heals after rack (or availability zone) failure or replacement. This balancer does not keep the relative fullness of each broker within a defined range, it just prevents hitting the fullness threshold of each individual broker.Continuous Data Balancing requires an enterprise license. | > 📝 **NOTE** > > If a topic already has messages and you add partitions, the existing messages won’t be redistributed to the new partitions. If you require messages to be redistributed, then you must create a new topic with the new partition count, then stream the messages from the old topic to the new topic so they are appropriately distributed according to the new partition hashing. ## [](#partition-leadership-balancing)Partition leadership balancing Every Redpanda topic partition forms a Raft group with a single elected leader. This leader manages all writes for the partition. Raft uses a heartbeat mechanism to maintain leadership authority and to initiate leader elections. The partition leader regularly sends heartbeats ([`raft_heartbeat_interval_ms`](../../../reference/properties/cluster-properties/#raft_heartbeat_interval_ms)) to its followers. If a follower does not receive a heartbeat within a timeout ([`raft_heartbeat_timeout_ms`](../../../reference/properties/cluster-properties/#raft_heartbeat_timeout_ms)), it triggers a new leader election. For more information, see [Raft consensus algorithm](../../../get-started/architecture/#raft-consensus-algorithm) and [partition leadership elections](../../../get-started/architecture/#partition-leadership-elections). By default, Redpanda enables topic-aware leadership balancing with the [`enable_leader_balancer`](../../../reference/properties/cluster-properties/#enable_leader_balancer) property. Automatic partition leadership balancing improves cluster performance by transferring partition leadership from one broker to other replicas. This transfer changes where data is written to first, but leadership transfer does not involve any data transfer. > 📝 **NOTE** > > In addition to the periodic heartbeat, leadership balancing can also occur when a [broker restarts](../../../upgrade/rolling-upgrade/#impact-of-broker-restarts) or when the controller leader changes (such as when a controller partition changes leader). The _controller leader_ manages the entire cluster. For example, when decommissioning a broker, the controller leader creates a reallocation plan for all partition replicas allocated to that broker. The _partition leader_ then handles the reconfiguration for its Raft group. ### [](#manually-change-leadership)Manually change leadership Despite an even distribution of leaders, sometimes the write pattern is not even across topics, and a set of traffic-heavy partitions could land on one broker and cause a latency spike. For information about metrics to monitor, see [Partition health](../../monitoring/#partition-health). To manually change leadership, use the Admin API: ```bash curl -X POST http://:9644/v1/partitions/kafka///transfer_leadership?target= ``` For example, to change leadership to broker 2 for partition 0 on topic `test`: ```bash curl -X POST "http://localhost:9644/v1/partitions/kafka/test/0/transfer_leadership?target=2" ``` > 📝 **NOTE** > > In Kubernetes, run the `transfer_leadership` request on the Pod that is running the current partition leader. ## [](#partition-replica-balancing)Partition replica balancing While leadership balancing doesn’t move any data, partition balancing does move partition replicas to alleviate disk pressure and maintain the configured replication factor across brokers and the additional redundancy across failure domains (such as racks). Depending on the data volume, this process may take some time. Partition balancing is invoked periodically as determined by the [`partition_autobalancing_tick_interval_ms`](../../../reference/properties/cluster-properties/#partition_autobalancing_tick_interval_ms) property. For predictable and stable performance, Redpanda ensures an even distribution of a topic’s partition replicas across all brokers in a cluster. It allocates partitions to random healthy brokers to prevent topic hotspots, without waiting for a batch of moves to finish before scheduling the next batch. Different topics in a cluster can have vastly different load profiles, but partitions of a single topic are often similar. To distribute the workload of heavily-used topics, Redpanda prioritizes an equal count of a topic’s partition replicas on each broker while it aims for an equal overall partition count on each broker. For example, suppose you have a Redpanda cluster that has 3 brokers and 1 topic, `light`, with 100 partitions and replication factor=3. Partitions are balanced, so each broker hosts 100 replicas of partitions of topic `light`. You expand the cluster with 3 new brokers and, before partition balancing moves partitions to the new broker, you create another topic, `heavy`, which serves 10x more produce/consume requests than `light`. The `heavy` topic also has 100 partitions and replication factor=3. With topic-aware partition balancing, when creating `heavy`, Redpanda prioritizes an equal count of partitions of that topic: brokers 1, 2, and 3 host 100 replicas of `light` and 50 replicas of `heavy`, and brokers 4, 5, and 6 host 50 replicas of `heavy`. Partition balancing then kicks in and evens out the distribution of replicas of `light`, so that there are 50 replicas of `light` and 50 replicas of `heavy` on each broker. This topic-aware partition balancing is enabled by default with the [`partition_autobalancing_topic_aware`](../../../reference/properties/cluster-properties/#partition_autobalancing_topic_aware) property. Redpanda supports flexible use of network bandwidth for replicating under-replicated partitions. For example, if only one partition is moving, it can use the entire bandwidth for the broker. Redpanda detects which shards are idle, so other shards can essentially steal bandwidth from them. Total bandwidth is controlled by the [`raft_learner_recovery_rate`](../../../reference/properties/cluster-properties/#raft_learner_recovery_rate) property. Redpanda’s default partition balancing includes the following: - When a broker is added to the cluster, some replicas are moved from other brokers to the new broker to take advantage of the additional capacity. - When a broker is down for a configured timeout, existing online replicas are used to construct a replacement replica on a new broker. - When a broker’s free storage space drops below its low disk space threshold, some of the replicas from the broker with low disk space are moved to other brokers. Monitoring unavailable brokers lets Redpanda self-heal clusters by moving partitions from a failed broker to a healthy broker. Monitoring low disk space lets Redpanda distribute partitions across brokers with enough disk space. If free disk space reaches a critically low level, Redpanda blocks clients from producing. For information about the disk space threshold and alert, see [Handle full disks](../disk-utilization/#handle-full-disks). ### [](#partition-balancing-settings)Partition balancing settings Select your partition balancing setting with the [`partition_autobalancing_mode`](../../../reference/properties/cluster-properties/#partition_autobalancing_mode) property. | Setting | Description | | --- | --- | | node_add | Partition balancing happens when brokers (nodes) are added. To avoid hotspots, Redpanda allocates brokers to random healthy brokers.This is the default setting. | | continuous | Redpanda continuously monitors the cluster for broker failures and high disk usage and automatically redistributes partitions to maintain optimal performance and availability. It also monitors rack availability after failures, and for a given partition, it tries to move excess replicas from racks that have more than one replica to racks where there are none. See Configure Continuous Data Balancing.This requires an enterprise license. | | off | All partition balancing from Redpanda is turned off.This mode is not recommended for production clusters. Only set to off if you need to move partitions manually. | ## [](#intra-broker-partition-balancing)Intra-broker partition balancing In Redpanda, every partition replica is assigned to a CPU core on a broker. While Redpanda’s default [partition balancing](#partition-replica-balancing) monitors cluster-level events, such as the addition of new brokers or broker failure to balance partition assignments, it does not account for the distribution of partitions _within_ an individual broker. Topic-aware intra-broker partition balancing allows for dynamically reassigning partitions within a broker. Redpanda prioritizes an even distribution of a topic’s partition replicas across all cores in a broker. If a broker’s core count changes, when the broker starts back up, Redpanda can check partition assignments across the broker’s cores and reassign partitions, so that a balanced assignment is maintained across all cores. Redpanda can also check partition assignments when partitions are added to or removed from a broker, and rebalance the remaining partitions between cores. To determine when to use intra-broker partition balancing, use the public metrics for CPU usage described in the [Monitoring](../../monitoring/#cpu-usage) guide. Configure the following properties to trigger intra-broker partition balancing: | Cluster configuration property | Description | | --- | --- | | core_balancing_on_core_count_change | Set to true to rebalance partition assignments across cores after broker startup, if core count increases or decreases. Default value: true. | | core_balancing_continuous | Set to true to rebalance partition assignments across cores in runtime, for example when partitions are moved to or away from brokers. Default value: false.This requires an enterprise license. | You can also manually trigger intra-broker partition balancing with the Admin API: ```bash curl -X POST http://localhost:9644/v1/partitions/rebalance_cores ``` To check the new partition assignments, make a GET request to the `/v1/partitions` Admin API endpoint: ```bash curl http://localhost:9644/v1/partitions ``` ## [](#manually-move-partitions)Manually move partitions As an alternative to Redpanda partition balancing, you can change partition assignments explicitly with `rpk cluster partitions move`. To reassign partitions with `rpk`: 1. Set the `partition_autobalancing_mode` property to `off`. If Redpanda partition balancing is enabled, Redpanda may change partition assignments regardless of what you do with `rpk`. ```bash rpk cluster config set partition_autobalancing_mode off ``` 2. Show initial replica sets. For example, for topic `test`: ```bash rpk topic describe test -p PARTITION LEADER EPOCH REPLICAS LOG-START-OFFSET HIGH-WATERMARK 0 1 1 [1 2 3] 0 645 1 1 1 [0 1 2] 0 682 2 3 1 [0 1 3] 0 672 ``` 3. Change partition assignments. For example, to change the replica set of partition 1 from `[0 1 2]` to `[3 1 2]`, and to change the replica set of partition 2 from `[0 1 3]` to `[2 1 3]`, run: ```bash rpk cluster partitions move test -p 1:3,1,2 -p 2:2,1,3 NAMESPACE TOPIC PARTITION OLD-REPLICAS NEW-REPLICAS ERROR kafka test 1 [0-1, 1-1, 2-0] [1-1, 2-0, 3-0] kafka test 2 [0-0, 1-0, 3-1] [1-0, 2-0, 3-1] Successfully began 2 partition movement(s). Check the movement status with 'rpk cluster partitions move-status' or see new assignments with 'rpk topic describe -p TOPIC'. ``` or ```bash rpk cluster partitions move -p test/1:3,1,2 -p test/2:2,1,3 ``` 4. Verify that the reassignment is complete with `move-status`: ```bash rpk cluster partitions move-status ONGOING PARTITION MOVEMENTS =========================== NAMESPACE-TOPIC PARTITION MOVING-FROM MOVING-TO COMPLETION-% PARTITION-SIZE BYTES-MOVED BYTES-REMAINING kafka/test 1 [0 1 2] [1 2 3] 57 87369012 50426326 36942686 kafka/test 2 [0 1 3] [1 2 3] 52 83407045 43817575 39589470 ``` Alternatively, run `rpk topic describe` again to show your reassigned replica sets: ```bash rpk topic describe test -p PARTITION LEADER EPOCH REPLICAS LOG-START-OFFSET HIGH-WATERMARK 0 1 2 [1 2 3] 0 645 1 1 2 [1 2 3] 0 682 2 3 1 [1 2 3] 0 672 ``` To cancel all in-progress partition reassignments, run `move-cancel`: ```bash rpk cluster partitions move-cancel ``` To cancel specific movements to or from a given node, run: ```bash rpk cluster partitions move-cancel --node 2 ``` > 📝 **NOTE** > > If you prefer, Redpanda also supports the use of the `AlterPartitionAssignments` Kafka API and using standard kafka tools such as `kafka-reassign-partitions.sh`. ## [](#differences-in-partition-balancing-between-redpanda-and-kafka)Differences in partition balancing between Redpanda and Kafka - In a partition reassignment, you must provide the broker ID for each replica. Kafka validates the broker ID for any new replica that wasn’t in the previous replica set against the list of alive brokers. Redpanda validates all replicas against the list of alive brokers. - When there are two identical partition reassignment requests, Kafka cancels the first one without returning an error code, while Redpanda rejects the second one with `Partition configuration update in progress` or `update_in_progress`. - In Kafka, attempts to add partitions to a topic during in-progress reassignments result in a `reassignment_in_progress` error, while Redpanda successfully adds partitions to the topic. - Kafka doesn’t support shard-level (core) partition assignments, but Redpanda does. For help specifying a shard for partition assignments, see `rpk cluster partitions move --help`. ## [](#assign-partitions-at-topic-creation)Assign partitions at topic creation To manually assign partitions at topic creation, run: ```bash kafka-topics.sh --create --bootstrap-server 127.0.0.1:9092 --topic custom-assignment --replica-assignment 0:1:2,0:1:2,0:1:2 ``` ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Owl Shop Example Application in Docker](/redpanda-labs/docker-compose/owl-shop/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) See more [Search all labs](/redpanda-labs) --- # Page 121: Configure Cluster Properties **URL**: https://docs.redpanda.com/current/manage/cluster-maintenance/cluster-property-configuration.md --- # Configure Cluster Properties --- title: Configure Cluster Properties latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: cluster-maintenance/cluster-property-configuration page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: cluster-maintenance/cluster-property-configuration.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/cluster-maintenance/cluster-property-configuration.adoc description: Learn how to configure cluster properties. page-git-created-date: "2023-06-02" page-git-modified-date: "2025-08-15" support-status: supported --- When you install Redpanda software, cluster configuration properties are automatically set to the default values. Examples of cluster properties include Kafka front-end settings, authentication settings, and settings for enabling features, like Tiered Storage and rack awareness. Redpanda includes cluster properties, broker properties, and topic properties. Some properties can be configured at either the cluster level or the topic level, such as `retention_bytes` (cluster-level) and `retention.bytes` (topic-level). Topic-level properties override cluster-level properties. Most Redpanda configuration properties are cluster properties. | Cluster properties | Broker properties | | --- | --- | | Cluster properties are stored internally and automatically replicated across all nodes, which ensures that each broker is in sync. | Broker properties are stored in the redpanda.yaml file located in the /etc/redpanda directory for each broker. | See also: - [Cluster configuration properties](../../../reference/properties/cluster-properties/) - [Broker configuration properties](../../../reference/properties/broker-properties/) and [Configure broker properties](../node-property-configuration/) ## [](#edit-cluster-properties)Edit cluster properties > 📝 **NOTE** > > For Kubernetes deployments, see [Configure Cluster Properties in Kubernetes](../../kubernetes/k-configure-helm-chart/). To change any property settings, edit the configuration from the command line using your default text editor. As you make changes, the Redpanda Admin API verifies that the new value is valid. For example, if you change `fetch_max_bytes` from the default of `57671680` to `5o` (using the letter “o” by mistake), the system displays the following message: ```bash PROPERTY PRIOR NEW fetch_max_bytes 57671680 5o Validation errors: * fetch_max_bytes: expected type integer No changes were made. ``` After you save your configuration changes, the new values are automatically applied and a new version number is generated. Any subsequent edits start with the most recent version of the configuration. > 📝 **NOTE** > > Some properties require that you restart the cluster for a change to take effect. The default configuration includes this information in the descriptions for these properties. To assign new values to cluster properties: 1. Open a terminal window and log in to a broker on your cluster. 2. Run `rpk cluster config edit`. To edit tuning properties, run `rpk cluster config edit --all` instead. 3. Edit the configuration file and set values for the [properties](../../../reference/properties/cluster-properties/) you want to change. 4. Save the file and quit the editor. 5. Run `rpk cluster config status` to see whether the cluster requires a restart. If necessary, you see a message like this: ```bash $ rpk cluster config status NODE CONFIG-VERSION NEEDS-RESTART INVALID UNKNOWN 1 4 true [] [] ``` 6. If necessary, restart the cluster. When you finish your edits, the system updates the configuration and displays a message that lists which property settings were changed, along with their prior and new values. The message also includes the new version number of the configuration. For example: ```bash PROPERTY PRIOR NEW tx_timeout_delay_ms 1000 2000 Successfully updated configuration. New configuration version is 2. ``` > 📝 **NOTE** > > You can also change property values using the `rpk cluster config set` command, but this method does not display the current setting or the description. ## [](#view-current-value-of-a-property)View current value of a property To see the current value of a property, run `rpk cluster config get `. For example: ```bash $ rpk cluster config get log_compression_type producer ``` ## [](#copy-configurations-to-other-clusters)Copy configurations to other clusters Use the `export` option to save the current cluster configuration to a file. You can then copy this file to other clusters, so they can use the same configuration. 1. Export the current configuration settings to a YAML file by running `rpk cluster config export --filename .yaml`. To store the configuration file outside your current working directory, use the full pathname for `--filename`; otherwise, supply the filename to store the file in your current working directory. 2. Copy `.yaml` to the other cluster. 3. Log in to the other cluster, and import the file with the saved configuration by running `rpk cluster config import --filename .yaml`. This command applies the property settings in `.yaml` to all nodes in the cluster. > ⚠️ **CAUTION** > > Redpanda does not support importing cluster-specific identification (such as `cluster_id`) with this command. ## [](#remove-cluster-properties-from-redpanda-yaml)Remove cluster properties from redpanda.yaml If you have a `redpanda.yaml` file that contains both cluster properties and broker properties, the cluster properties are ignored. To remove cluster properties from the `redpanda.yaml` file, run: ```bash rpk cluster config lint ``` This avoids the issue of referring to a previous version or custom configuration. ## [](#suggested-reading)Suggested reading - [rpk cluster config](../../../reference/rpk/rpk-cluster/rpk-cluster-config/) - [Using Raft to centralize cluster configuration in Redpanda](https://redpanda.com/blog/raft-centralized-cluster-configuration-improvements/) ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Owl Shop Example Application in Docker](/redpanda-labs/docker-compose/owl-shop/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) See more [Search all labs](/redpanda-labs) --- # Page 122: Compaction Settings **URL**: https://docs.redpanda.com/current/manage/cluster-maintenance/compaction-settings.md --- # Compaction Settings --- title: Compaction Settings latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: cluster-maintenance/compaction-settings page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: cluster-maintenance/compaction-settings.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/cluster-maintenance/compaction-settings.adoc description: Redpanda's approach to compaction and options for configuring it. page-git-created-date: "2023-12-22" page-git-modified-date: "2026-03-31" support-status: supported --- Configure compaction for your cluster to optimize storage utilization. ## [](#redpanda-compaction-overview)Redpanda compaction overview Compaction is an optional mechanism intended to reduce the storage needs of Redpanda topics. You can enable compaction through configuration of a cluster or topic’s cleanup policy. When compaction is enabled as part of the cleanup policy, a background process executes on a pre-set interval to perform compaction operations. When triggered for a partition, the process purges older versions of records for a given key and only retains the most recent record in that partition. This is done by analyzing closed segments in the partition, copying the most recent records for each key into a new segment, then deleting the source segments. ![Example of topic compaction](../../../shared/_images/compaction-example.png) This diagram illustrates a compacted topic. Imagine a remote sensor network that uses image recognition to track appearances of red pandas in a geographic area. The sensor network employs special devices that send records to a topic when they detect one. You might enable compaction to reduce topic storage while still maintaining a record in the topic of the last time each device saw a red panda, perhaps to see if they stop frequenting a given area. The left side of the diagram shows all records sent across the topic. The right side illustrates the results of compaction; older records for certain keys are deleted from the log. > 📝 **NOTE** > > If your application requires consuming every record for a given key, consider using the `delete` [cleanup policy](../../../develop/manage-topics/config-topics/#change-the-cleanup-policy) instead. > ❗ **IMPORTANT** > > When using [Tiered Storage](../../tiered-storage/), compaction functions at the local storage level. As long as a segment remains in local storage, its records are eligible for compaction. Once a segment is uploaded to object storage and removed from local storage it is not retrieved for further compaction operations. A key may therefore appear in multiple segments between Tiered Storage and local storage. While compaction reduces storage needs, Redpanda’s compaction (just like Kafka’s) does not guarantee perfect de-duplication of a topic. It represents a best effort mechanism to reduce storage needs but duplicates of a key may still exist within a topic. Compaction is not a complete topic operation, either, since it operates on subsets of each partition within the topic. ## [](#configure-a-cleanup-policy)Configure a cleanup policy A compaction policy may be applied to a cluster or to an individual topic. If both are set, the topic-level policy overrides the cluster-level policy. The cluster-level [`log_cleanup_policy`](../../../reference/properties/cluster-properties/#log_cleanup_policy) and the topic-level [`cleanup.policy`](../../../reference/properties/topic-properties/#cleanuppolicy) support the following three options: - `delete`: Records are deleted from the topic once the specified retention period (time and/or size allocations) is exceeded. This is the default mechanism and is analogous to disabling compaction. - `compact`: This triggers only cleanup of records with multiple versions. A record that represents the only version for a given key is not deleted. - `compact,delete`: This combines both policies, deleting records exceeding the retention period while compacting multiple versions of records. > ⚠️ **WARNING** > > All topic properties take effect immediately after being set. Do not modify properties on internal Redpanda topics (such as `__consumer_offsets`, `_schemas`, or other system topics) as this can cause cluster instability. ## [](#tune-log-compaction-with-a-dirty-ratio-threshold)Tune log compaction with a dirty ratio threshold Use the dirty ratio to control when log compaction runs in compacted topics. The dirty ratio is the size of dirty segments divided by the total size of closed segments. Dirty segments are closed but un-compacted, meaning they may still contain duplicate keys that exist earlier in the log. ```none dirty_ratio = dirty_segment_bytes / total_closed_segment_bytes ``` Where: - **Dirty segments** are closed segments that may contain duplicate keys that haven’t yet been compacted. - **Closed segments** are all finalized segments in the log. ### [](#configuration-options)Configuration options | Property | Scope | Description | | --- | --- | --- | | min_cleanable_dirty_ratio | Cluster | The minimum ratio between the number of bytes in dirty segments and the total number of bytes in closed segments that must be reached before a partition’s log is eligible for compaction in a compact topic. | | min.cleanable.dirty.ratio | Topic | Topic-level override of the cluster-wide dirty ratio threshold. | | log_compaction_interval_ms | Cluster | Compaction frequency in milliseconds. | | max_compaction_lag_ms | Cluster | The maximum amount of time in milliseconds that a message remains ineligible for compaction. Use to guarantee the maximum delay between the time a message is written and the time the message becomes eligible for compaction. This setting is useful for ensuring that messages are compacted within a predictable timeframe. | | min_compaction_lag_ms | Cluster | The minimum time in milliseconds that a message remains uncompacted in the log. Use to guarantee the minimum length of time that must pass after a message is written before it could be compacted. For example, to provide a lower bound on how long each message will remain in the (uncompacted) head. | | max.compaction.lag.ms | Topic | The maximum amount of time in milliseconds that a message remains ineligible for compaction. Use to guarantee the maximum delay between the time a message is written and the time the message becomes eligible for compaction. | | min.compaction.lag.ms | Topic | The minimum time in milliseconds that a message remains uncompacted in the log. Use to guarantee the minimum length of time that must pass after a message is written before it could be compacted. For example, to provide a lower bound on how long each message will remain in the (uncompacted) head. | Redpanda runs a scan every `log_compaction_interval_ms`. During each scan: - Logs are evaluated for compaction eligibility using their dirty ratio. - Only logs with a dirty ratio greater than the configured threshold are compacted. - Logs are compacted in descending order of dirty ratio to maximize efficiency. ### [](#use-cases-for-dirty-ratio-based-compaction)Use cases for dirty ratio-based compaction | Use Case | Recommended Setting | | --- | --- | | High-throughput topics with frequent key overwrites | Lower min_cleanable_dirty_ratio to enable more aggressive compaction. | | Topics with large segment sizes or expensive I/O | Raise min_cleanable_dirty_ratio to defer compaction until it is more efficient. | | Topics requiring custom tuning | Use min.cleanable.dirty.ratio to override the cluster setting on specific topics. | ## [](#tombstone-record-removal)Tombstone record removal Compaction also enables deletion of existing records through tombstones. For example, as data is deleted from a source system, clients produce a tombstone record to the log. A tombstone contains a key and the value `null`. Tombstones signal to brokers and consumers that records with the same key prior to it in the log should be deleted. You can specify how long Redpanda keeps these tombstones for compacted topics using both a cluster configuration property `[tombstone_retention_ms](../../../reference/properties/cluster-properties/#tombstone_retention_ms)` and a topic configuration property [`delete.retention.ms`](../../../reference/properties/topic-properties/#deleteretentionms). If both are set, the topic-level tombstone retention policy overrides the cluster-level policy. > 📝 **NOTE** > > Redpanda does not currently remove tombstone records for compacted topics with Tiered Storage enabled. > > You cannot enable `tombstone_retention_ms` if you have enabled any of the Tiered Storage cluster properties `cloud_storage_enabled`, `cloud_storage_enable_remote_read`, and `cloud_storage_enable_remote_write`. > > On the topic level, you cannot enable `delete.retention.ms` at the same time as the Tiered Storage topic configuration properties `redpanda.remote.read` and `redpanda.remote.write`. To set the cluster-level tombstone retention policy, run the command: ```bash rpk cluster config set tombstone_retention_ms=100 ``` You can unset the tombstone retention policy for a topic so it inherits the cluster-wide default policy: ```bash rpk topic alter-config --delete delete.retention.ms ``` To override the cluster-wide default for a specific topic: ```bash rpk topic alter-config --set delete.retention.ms=5 ``` To disable tombstone removal for a specific topic: ```bash rpk topic alter-config --set delete.retention.ms=-1 ``` Redpanda removes tombstones as follows: - For topics with a `compact` only cleanup policy: Tombstones are removed when the topic exceeds the tombstone retention limit. The `delete.retention.ms` or `tombstone_retention_ms` values therefore also set the time bound that a consumer has in order to see a complete view of the log with tombstones present before they are removed. - For topics with a `compact,delete` cleanup policy: Both the tombstone retention policy and standard garbage collection can remove tombstone records. If obtaining a complete snapshot of the log, including tombstone records, is important to your consumers, set the tombstone retention value such that consumers have enough time for their reads to complete before tombstones are removed. Consumers may not see tombstones if their reads take longer than `delete.retention.ms` and `tombstone_retention_ms`. The trade-offs to ensuring tombstone visibility to consumers are increased disk usage and potentially slower compaction. On the other hand, if more frequent cleanup of tombstones is important for optimizing workloads and space management, consider setting a shorter tombstone retention, for example the typical default of 24 hours (86400000 ms). Compaction and tombstone removal are coordinated across replicas, preventing inconsistencies and ensuring that deleted records are properly recognized by all readers. As a result, tombstone removal on one replica may be delayed if another replica is stopped or lagging. ## [](#transactional-control-batch-removal)Transactional control batch removal Transactional workloads write control batches (commit and abort markers) to the log. By default, these markers are retained indefinitely. You can enable their removal during compaction by setting [`log_compaction_tx_batch_removal_enabled`](../../../reference/properties/cluster-properties/#log_compaction_tx_batch_removal_enabled) to `true`: ```bash rpk cluster config set log_compaction_tx_batch_removal_enabled=true ``` When enabled, the [`delete.retention.ms`](../../../reference/properties/topic-properties/#delete-retention-ms) setting is applied to transactional control batches, removing them after the retention period. This uses the same coordinated compaction mechanism as tombstone removal. > 📝 **NOTE** > > For topics with a `compact` only cleanup policy, you must explicitly set `delete.retention.ms` at the topic level to enable removal of transactional control batches. Consider enabling this feature if you have compacted topics with heavy transactional workloads and observe disk usage from accumulated transaction markers. ## [](#compaction-policy-settings)Compaction policy settings The various cleanup policy settings rely on proper tuning of a cluster’s compaction and retention policy options. The applicable settings are: - [`log_compaction_interval`](../../../reference/properties/cluster-properties/#log_compaction_interval_ms): Defines the compaction frequency in milliseconds. (default: 10,000ms) - [`min_cleanable_dirty_ratio`](../../../reference/properties/cluster-properties/#min_cleanable_dirty_ratio): Minimum dirty ratio a log must exceed to be eligible for compaction. - [`compaction_ctrl_backlog_size`](../../../reference/properties/cluster-properties/#compaction_ctrl_backlog_size): Defines the size for the compaction backlog of the backlog controller. (default: 10% of disk capacity) - [`compaction_ctrl_min_shares`](../../../reference/properties/cluster-properties/#compaction_ctrl_min_shares): Defines the minimum number of I/O and CPU shares the compaction process can use. (default: 10) - [`compaction_ctrl_max_shares`](../../../reference/properties/cluster-properties/#compaction_ctrl_max_shares): Defines the maximum number of I/O and CPU shares the compaction process can use. (default: 1,000) - [`storage_compaction_index_memory`](../../../reference/properties/cluster-properties/#storage_compaction_index_memory): Defines the amount of memory in bytes that each shard may use for creating the compaction index. This index optimizes execution during compaction operations. (default: 128 MiB) - `storage_compaction_key_map_memory`: Defines the amount of memory in bytes that each shard may use when creating the key map for a partition during compaction operations. The compaction process uses this key map to de-dupe keys within the compacted segments. (default: 128 MiB) - [`compacted_log_segment_size`](../../../reference/properties/cluster-properties/#compacted_log_segment_size): Defines the base size for a compacted log segment in bytes. (default: 268435456 \[256 MiB\]) - [`max_compacted_log_segment_size`](../../../reference/properties/cluster-properties/#max_compacted_log_segment_size): Defines the maximum size after consolidation for a compacted log segment in bytes. (default: 5368709120 \[5 GiB\]) > 📝 **NOTE** > > Additional [tunable properties](../../../reference/properties/cluster-properties/) are available but should only be used with direction from Redpanda support. These properties include [`compaction_ctrl_p_coeff`](../../../reference/properties/cluster-properties/#compaction_ctrl_p_coeff), [`compaction_ctrl_i_coeff`](../../../reference/properties/cluster-properties/#compaction_ctrl_i_coeff), [`compaction_ctrl_d_coeff`](../../../reference/properties/cluster-properties/#compaction_ctrl_d_coeff), and [`compaction_ctrl_update_interval_ms`](../../../reference/properties/cluster-properties/#compaction_ctrl_update_interval_ms). ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Owl Shop Example Application in Docker](/redpanda-labs/docker-compose/owl-shop/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) See more [Search all labs](/redpanda-labs) --- # Page 123: Configure Client Connections **URL**: https://docs.redpanda.com/current/manage/cluster-maintenance/configure-client-connections.md --- # Configure Client Connections --- title: Configure Client Connections latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: cluster-maintenance/configure-client-connections page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: cluster-maintenance/configure-client-connections.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/cluster-maintenance/configure-client-connections.adoc description: Learn about guidelines for configuring client connections in Redpanda clusters for optimal availability. page-git-created-date: "2025-11-19" page-git-modified-date: "2025-11-20" support-status: supported --- Optimize the availability of your clusters by configuring and tuning properties. > 💡 **TIP** > > Before you configure connection limits or reconnection settings, start by gathering detailed data about your client connections. > > - Internal metrics that follow the `vectorized_kafka_rpc_.*connect*` naming pattern provide details on Kafka client connection activity. For example, [`vectorized_kafka_rpc_active_connections`](../../../reference/internal-metrics-reference/#vectorized_kafka_rpc_active_connections) reports the current number of active connections. > > - For Redpanda v25.3 and later, use [`rpk cluster connections list`](../../../reference/rpk/rpk-cluster/rpk-cluster-connections-list/) or the Admin API ListKafkaConnections endpoint to identify: > > - Which clients and applications are connected > > - Long-lived connections and long-running requests > > - Connections with no activity > > - Whether any clients are causing excessive load > > > By reviewing connection details, you can make informed decisions about tuning connection limits and troubleshooting issues. > > > See also: [ListKafkaConnections reference](/api/doc/admin/v2/operation/operation-redpanda-core-admin-v2-clusterservice-listkafkaconnections), [Monitor Redpanda](../../monitoring/#throughput) ## [](#limit-client-connections)Limit client connections To mitigate the risk of a client creating too many connections and using too many system resources, you can configure a Redpanda cluster to impose limits on the number of client connections that can be created. The following Redpanda cluster properties limit the number of connections: - [`kafka_connections_max_per_ip`](../../../reference/properties/cluster-properties/#kafka_connections_max_per_ip): Similar to Kafka’s `max.connections.per.ip`, this sets the maximum number of connections accepted per IP address by a broker. - [`kafka_connections_max_overrides`](../../../reference/properties/cluster-properties/#kafka_connections_max_overrides): A list of IP addresses for which `kafka_connections_max_per_ip` is overridden and doesn’t apply. - [`kafka_connections_max`](../../../reference/properties/cluster-properties/#kafka_connections_max): Similar to Kafka’s `max.connections`, this sets the maximum number of connections per broker. Redpanda also provides properties to manage the rate of connection creation: - [`kafka_connection_rate_limit`](../../../reference/properties/cluster-properties/#kafka_connection_rate_limit): This property limits the maximum rate of connections created per second. It applies to each CPU core. - [`kafka_connection_rate_limit_overrides`](../../../reference/properties/cluster-properties/#kafka_connection_rate_limit_overrides): A list of IP addresses for which `kafka_connection_rate_limit` is overridden and doesn’t apply. > 📝 **NOTE** > > - These connection limit properties are disabled by default. You must manually enable them. > > - The total number of connections is not equal to the number of clients, because a client can open multiple connections. As a conservative estimate, for a cluster with N brokers, plan for N + 2 connections per client. ## [](#configure-client-reconnections)Configure client reconnections You can configure the Kafka client backoff and retry properties to change the default behavior of the clients to suit your failure requirements. Set the following Kafka client properties on your application’s producer or consumer to manage client reconnections: - `reconnect.backoff.ms`: Amount of time to wait before attempting to reconnect to the broker. The default is 50 milliseconds. - `reconnect.backoff.max.ms`: Maximum amount of time in milliseconds to wait when reconnecting to a broker. The backoff increases exponentially for each consecutive connection failure, up to this maximum. The default is 1000 milliseconds (1 second). Additionally, you can use Kafka properties to control message retry behavior. Delivery fails when either the delivery timeout or the number of retries is met. - `delivery.timeout.ms`: Amount of time for message delivery, so messages are not retried forever. The default is 120000 milliseconds (2 minutes). - `retries`: Number of times a producer can retry sending a message before marking it as failed. The default value is 2147483647 for Kafka >= 2.1, or 0 for Kafka <= 2.0. - `retry.backoff.ms`: Amount of time to wait before attempting to retry a failed request to a given topic partition. The default is 100 milliseconds. ## [](#see-also)See also - [Configure Producers](../../../develop/produce-data/configure-producers/) - [Manage Throughput](../manage-throughput/) --- # Page 124: Configure Continuous Data Balancing **URL**: https://docs.redpanda.com/current/manage/cluster-maintenance/continuous-data-balancing.md --- # Configure Continuous Data Balancing --- title: Configure Continuous Data Balancing latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: cluster-maintenance/continuous-data-balancing page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: cluster-maintenance/continuous-data-balancing.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/cluster-maintenance/continuous-data-balancing.adoc description: Continuous Data Balancing simplifies operations with self-healing clusters that dynamically balance partitions. page-topic-type: how-to personas: infrastructure_operator learning-objective-1: Enable Continuous Data Balancing on a Redpanda cluster learning-objective-2: Check data balancing status using rpk learning-objective-3: Cancel partition balancing moves for a specific node page-git-created-date: "2023-06-02" page-git-modified-date: "2026-03-31" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../get-started/licensing/#self-managed) apply. Continuous Data Balancing continuously monitors your node and rack availability and disk usage, dynamically balancing partitions to maintain smooth operations and optimal cluster performance. Continuous Data Balancing also maintains the configured replication level, even after infrastructure failure. Node availability has the highest priority in data balancing. After a rack (with all nodes belonging to it) becomes unavailable, Redpanda moves partition replicas to the remaining nodes. This violates the rack awareness constraint. After the rack (or a replacement rack) becomes available, Redpanda repairs the constraint by moving excess replicas from racks that have more than one replica to the newly-available rack. After reading this page, you will be able to: - Enable Continuous Data Balancing on a Redpanda cluster - Check data balancing status using rpk - Cancel partition balancing moves for a specific node ## [](#set-continuous-data-balancing-properties)Set Continuous Data Balancing properties To enable Continuous Data Balancing, set the `partition_autobalancing_mode` property to `continuous`. Customize the following properties to monitor node availability and disk usage. | Property | Description | | --- | --- | | partition_autobalancing_node_availability_timeout_sec | When a node is unreachable for the specified amount of time, Redpanda acts as if the node had been decommissioned: rebalancing begins, re-creating all of its replicas on other nodes in the cluster.The node remains part of the cluster and can rejoin when it comes back online. A node that was actually decommissioned is removed from the cluster.Default is 900 seconds (15 minutes). | | partition_autobalancing_node_autodecommission_timeout_sec | When a node is unavailable for this timeout duration, Redpanda automatically and permanently decommissions the node. This property only applies when partition_autobalancing_mode is set to continuous. Unlike partition_autobalancing_node_availability_timeout_sec, which moves partitions while keeping the node in the cluster, this property removes the node from the cluster entirely. A decommissioned node cannot rejoin the cluster.Only one node is decommissioned at a time. If a decommission is already in progress, automatic decommission does not trigger until it completes. If the decommission stalls (for example, because the node holds the only replica of a partition), manual intervention is required. See Node-wise Partition Recovery.By default, this property is null and automatic decommission is disabled. | | partition_autobalancing_max_disk_usage_percent | When a node fills up to this disk usage percentage, Redpanda starts moving replicas off the node to other nodes with disk utilization below the percentage.Default is 80%. | For the other `partition_autobalancing_mode` options, see [Cluster balancing](../cluster-balancing/). ## [](#use-data-balancing-commands)Use data balancing commands Use the following `rpk` commands to monitor and control data balancing. ### [](#check-data-balancing-status)Check data balancing status To see the status, run: ```bash rpk cluster partitions balancer-status ``` This shows the time since the last data balancing, the number of replica movements in progress, the nodes that are unavailable, and the nodes that are over the disk space threshold (default = 80%). It also returns a data balancing status: `off`, `ready`, `starting`, `in-progress`, or `stalled`. If the command reports a `stalled` status, verify: - Are there enough healthy nodes? For example, in a three node cluster, no movements are possible for partitions with three replicas. - Does the cluster have sufficient space? Partitions are not moved if all nodes in the cluster are utilizing more than their disk space threshold. - Do all partitions have quorum? Partitions are not moved if the majority of its replicas are down. - Are any nodes in maintenance mode? Partitions are not moved if a node is in maintenance mode. ### [](#cancel-data-balancing-moves)Cancel data balancing moves To cancel the current partition balancing moves, run: ```bash rpk cluster partitions movement-cancel ``` To cancel partition moves on a specific node, use the `--node` flag. For example: ```bash rpk cluster partitions movement-cancel --node 1 ``` > 📝 **NOTE** > > If continuous balancing is still enabled and the cluster remains unbalanced, Redpanda schedules another partition balancing round. To stop all balancing, first set `partition_autobalancing_mode` to `off`, then cancel the current data balancing moves. ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Owl Shop Example Application in Docker](/redpanda-labs/docker-compose/owl-shop/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) See more [Search all labs](/redpanda-labs) --- # Page 125: Decommission Brokers **URL**: https://docs.redpanda.com/current/manage/cluster-maintenance/decommission-brokers.md --- # Decommission Brokers --- title: Decommission Brokers latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: cluster-maintenance/decommission-brokers page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: cluster-maintenance/decommission-brokers.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/cluster-maintenance/decommission-brokers.adoc description: Remove a broker so that it is no longer considered part of the cluster. page-git-created-date: "2023-08-03" page-git-modified-date: "2026-03-31" support-status: supported --- When you decommission a broker, its partition replicas are reallocated across the remaining brokers and it is removed from the cluster. You may want to decommission a broker in the following circumstances: - The broker has lost its storage and you need a new broker with a new node ID (broker ID). - You are replacing a broker, for example to upgrade the Linux kernel or to replace the hardware. - You are removing a broker to decrease the size of the cluster. > ⚠️ **CAUTION** > > When a broker is decommissioned, it cannot rejoin the cluster. If a broker with the same ID tries to rejoin the cluster, it is rejected. ## [](#decommissioning-methods)Decommissioning methods There are two ways to decommission brokers in Redpanda: - Manual decommissioning (described in this guide): Use `rpk` commands to explicitly decommission a broker when you need full control over the timing and selection of brokers to remove. - Automatic decommissioning: When [Continuous Data Balancing](../continuous-data-balancing/) is enabled, you can configure the [partition\_autobalancing\_node\_autodecommission\_timeout\_sec](../continuous-data-balancing/#partition_autobalancing_node_autodecommission_timeout_sec) property to automatically decommission brokers that remain unavailable for a specified duration. Both methods permanently remove the broker from the cluster. Decommissioned brokers cannot rejoin. ## [](#what-happens-when-a-broker-is-decommissioned)What happens when a broker is decommissioned? When a broker is decommissioned, the controller leader creates a reallocation plan for all partition replicas that are allocated to that broker. By default, this reallocation is done in batches of 50 to avoid overwhelming the remaining brokers with Raft recovery. See [`partition_autobalancing_concurrent_moves`](../../../reference/properties/cluster-properties/#partition_autobalancing_concurrent_moves). The reallocation of each partition is translated into a Raft group reconfiguration and executed by the controller leader. The partition leader then handles the reconfiguration for its Raft group. After the reallocation for a partition is complete, it is recorded in the controller log and the status is updated in the topic tables of each broker. The decommissioning process is successful only when all partition reallocations have been completed successfully. The controller leader polls for the status of all the partition-level reallocations to ensure that everything completes as expected. During the decommissioning process, new partitions are not allocated to the broker that is being decommissioned. After all the reallocations have been completed successfully, the broker is removed from the cluster. > 📝 **NOTE** > > The decommissioning process is designed to tolerate controller leadership transfers. > 💡 **TIP** > > This guide uses `jq` to make parsing JSON output easier. For additional details, see [jq downloads](https://stedolan.github.io/jq/download/). ## [](#should-you-decommission-brokers)Should you decommission brokers? There are several considerations for determining your cluster’s minimum broker count, and whether or not to decommission any brokers. For the purposes of this section, the focus is on a cluster with seven brokers. In subsequent sections, the output from the given commands provides additional details to help you determine the minimum number of brokers. ### [](#availability)Availability You should have a sufficient number of brokers to properly span across each rack or availability zone. Run the following command to determine whether rack awareness is enabled in your cluster: ```bash rpk cluster config get enable_rack_awareness ``` true When enabled, you can view which rack each broker is assigned to by running the following command: ```bash rpk cluster info ``` Example output ```bash CLUSTER ======= redpanda.560e2403-3fd6-448c-b720-7b456d0aa78c BROKERS ======= ID HOST PORT RACK 0 redpanda-0.testcluster.local 32180 A 1 redpanda-1.testcluster.local 32180 A 4 redpanda-3.testcluster.local 32180 B 5* redpanda-2.testcluster.local 32180 B 6 redpanda-4.testcluster.local 32180 C 8 redpanda-6.testcluster.local 32180 C 9 redpanda-5.testcluster.local 32180 D ``` The output shows four racks (A/B/C/D), so you might want to have at least four brokers to make use of all racks. Rack awareness is just one aspect of availability. Check out [High Availability](../../high-availability/) for details on deploying Redpanda for high availability. ### [](#cost)Cost Infrastructure costs increase with each broker because each broker requires a dedicated node (instance), so adding a broker means an additional instance cost. For example, if the instance cost is $1925 per month in a cluster with seven brokers, the instance cost for each broker is $275. Reducing the number of brokers from seven to five would save $550 per month ($275 x 2), and reducing it to three brokers would save $1100 per month. You must also consider other costs, but they won’t be as impacted by changing the broker count. ### [](#data-retention)Data retention Local data retention is determined by the storage capability of each broker and how much data is being produced over a given period (that is, producer throughput). When decommissioning, storage capability must take into account both the free storage space and amount of space already used by existing partitions. Run the following command to determine how much storage is being used (in bytes) on each broker: ```bash rpk cluster logdirs describe --aggregate-into broker ``` Example output ```bash BROKER SIZE ERROR 0 263882790656 1 256177979648 2 257698037504 3 259934992896 4 254087316992 5 258369126144 6 255227998208 ``` The example output shows that each broker contains roughly 240GB of data, which means scaling down to five brokers would require each broker to have at least 337GB to hold current data. Throughput is the primary measurement required to calculate future data storage requirements. In the example cluster there is a throughput of 200MB/sec, which means it will generate 0.72TB/hour (or 17.28TB/day, or 120.96TB/wk). Divide this amount by the target number of brokers to get an estimate of how much storage is needed to retain that much data for various periods of time: | Retention | Disk size (on each of the 5 brokers) | | --- | --- | | 30mins | (200MB/sec * 30mins * 1.1) = 0.396TB / 5 brokers = 79.2GB | | 6hrs | (200MB/sec * 6hrs * 1.1) = = 4.752TB / 5 brokers = 950.4GB | | 1d | (200MB/sec * 1d * 1.1) = 19.008TB / 5 brokers = 3.8TB | | 3d | (200MB/sec * 3d * 1.1) = 57.024TB / 5 brokers = 11.4TB | In the example cluster, only 6 hours of data locally must be retained (any older data is moved to Tiered Storage with a retention of 1 year). So each broker should have available storage of around 1.2TB, taking into account both throughput and current data. Cost and use case requirements dictate how much to spend on local disk capacity. Tiered Storage can help to both decrease costs and expand data retention capabilities. For details, see [Tiered Storage](../../tiered-storage/). > 📝 **NOTE** > > At this point in the example, it remains unclear whether or not it makes sense to scale down to five brokers. Current calculations are based on five brokers. You can consider other broker counts later as needed. > > Additionally, assumptions have been made regarding a constant throughput and perfect data balancing. Throughput fluctuates across all partitions, which causes data imbalance. The calculations above attempt to accommodate for this by padding disk size by 1%. You can increase this buffer (for example, in the case of expected hot spot partitions). For details on sizing, see [Sizing Guidelines](../../../deploy/redpanda/manual/sizing/). ### [](#durability)Durability The brokers in a Redpanda cluster are part of a Raft group that requires sufficient brokers to form a quorum-based majority (minimally, three brokers). Each topic’s partitions are also Raft groups, so your cluster also needs to have at least as many brokers as the lowest replication factor across all topics. One way to find the max replication factor across all topics in a cluster is to run the following command: ```bash rpk topic list | tail -n +2 | awk '{print $3}' | sort -n | tail -1 ``` 5 In this example the highest replication factor is 5, which means at least 5 brokers are required in this cluster. Generally, a cluster can withstand a higher number of brokers going down if there are more brokers in the cluster. For details, see [Raft consensus algorithm](../../../get-started/architecture/#raft-consensus-algorithm). ### [](#partition-count)Partition count It is a best practice to make sure the total partition count does not exceed 1K per core. This max partition count depends on many other factors (such as memory per core, CPU performance, throughput, and latency requirements). Exceeding 1K partitions per core can lead to increased latency, increased number of partition leadership elections, and general reduced stability. Run the following command to get the total partition count: ```bash curl -sk http://:/v1/partitions/local_summary | jq .count ``` 3018 To determine the number of cores that are available across the remaining brokers: ```bash rpk redpanda admin brokers list ``` Example output ```bash ID HOST PORT RACK CORES MEMBERSHIP IS-ALIVE VERSION UUID 0 redpanda-0.testcluster.local 32180 A 8 active true 25.2.13 24c08934-94f6-478c-b57d-45239f452488 1 redpanda-1.testcluster.local 32180 B 8 active true 25.2.13 7f3c1c6e-2f4d-4c8a-9c6e-0a8a6d8b2b61 2 redpanda-2.testcluster.local 32180 C 8 active true 25.2.13 b2e8d4a9-91c1-4b55-9f6a-3f7a2d3c5e44 3 redpanda-3.testcluster.local 32180 A 8 active true 25.2.13 c9a6f7d2-5e3b-4f8c-8d1a-6e2b4a9f7c31 4 redpanda-4.testcluster.local 32180 B 8 active true 25.2.13 4e8b1c3a-9d7f-4a6e-b2c5-8f6d1a3e9b74 5 redpanda-5.testcluster.local 32180 C 8 active true 25.2.13 a1f9c6b4-3d2e-4a8f-9e5b-7c6d8a1b2f93 6 redpanda-6.testcluster.local 32180 A 8 active true 25.2.13 e6b4d2a8-5f1c-4e9b-8a3d-9c7f1b6a5e42 ``` In this example each broker has 8 cores available. If you plan to scale down to five brokers, then you would have 40 cores available, which means that your cluster is limited by core count to 40K partitions (well above the current 3018 partitions). > 📝 **NOTE** > > To best ensure the stability of the cluster, stay under 50K partitions per cluster. ### [](#decommission-assessment)Decommission assessment The considerations tested above yield the following: - At least four brokers are required based on availability. - Cost is not a limiting factor in this example, but lower cost (and lower broker count) is always best. - At least 1.2TB of data resides on each broker (if spread across five brokers). This falls within the 1.5TB of local storage available in this example. - At least five brokers are required based on the highest replication factor across all topics. - At 3018 partitions, the partition count is so low as to not be a determining factor in broker count (a single broker in this example environment could handle many more partitions). So the primary limitation consideration is the replication factor of five, meaning that you could scale down to five brokers at minimum. ## [](#decommission-a-broker)Decommission a broker 1. List your brokers and their associated broker IDs: ```bash rpk cluster info \ -X brokers=: ``` 2. Decommission the broker with your selected broker ID: ```bash rpk redpanda admin brokers decommission \ --hosts : \ --force ``` > 📝 **NOTE** > > The `--force` flag is required only if the broker is not running. If you see `Success, broker has been decommissioned!`, the broker is decommissioned. Otherwise, the decommissioning process is still in progress. You can monitor the decommissioning status to follow its progress. 3. Monitor the decommissioning status: ```bash rpk redpanda admin brokers decommission-status \ -X admin.hosts=: ``` The output uses cached cluster health data that is refreshed every 10 seconds. When the completion column for all rows is 100%, the broker is decommissioned. > ❗ **IMPORTANT** > > If you add a new broker, make sure to give it a unique ID. Do not reuse the ID of the decommissioned broker. ## [](#troubleshooting)Troubleshooting If the decommissioning process is not making progress, investigate the following potential issues: - **Absence of a controller leader or partition leader**: The controller leader serves as the orchestrator for decommissioning. Additionally, if one of the partitions undergoing reconfiguration does not have a leader, the reconfiguration process may stall. Make sure that an elected leader is present for all partitions. - **Bandwidth limitations for partition recovery**: Try increasing the value of [`raft_learner_recovery_rate`](../../../reference/properties/cluster-properties/#raft_learner_recovery_rate), and monitor the status using the [`redpanda_raft_recovery_partition_movement_available_bandwidth`](../../../reference/public-metrics-reference/#redpanda_raft_recovery_partition_movement_available_bandwidth) metric. If these steps do not allow the decommissioning process to complete, enable `TRACE` level logging on the controller leader to investigate any other issues. ## [](#suggested-reading)Suggested reading - [`rpk-redpanda-admin-brokers-decommission`](../../../reference/rpk/rpk-redpanda/rpk-redpanda-admin-brokers-decommission/) - [Engineering a more robust Raft group reconfiguration](https://redpanda.com/blog/raft-protocol-reconfiguration-solution) ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Owl Shop Example Application in Docker](/redpanda-labs/docker-compose/owl-shop/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) See more [Search all labs](/redpanda-labs) --- # Page 126: Manage Disk Space **URL**: https://docs.redpanda.com/current/manage/cluster-maintenance/disk-utilization.md --- # Manage Disk Space --- title: Manage Disk Space latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: cluster-maintenance/disk-utilization page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: cluster-maintenance/disk-utilization.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/cluster-maintenance/disk-utilization.adoc description: Redpanda provides several ways to manage disk space to ensure the stability of a cluster. page-git-created-date: "2023-06-02" page-git-modified-date: "2026-03-31" support-status: supported --- It is important to manage the local disk space in Redpanda to ensure the stability of a cluster. If a node’s disk space reaches a critically-low level, then Redpanda blocks clients from writing new data. If a node runs out of disk space, then the Redpanda process terminates. This has a significant impact on performance, as client connections and topic data concentrates on fewer nodes. Redpanda provides several ways to manage disk space, with varying degrees of flexibility and control over what data is removed from local disk and when. - Redpanda space management, when used with [Tiered Storage](../../tiered-storage/), treats local disks as a cache. - For more granularity, you can configure topic-level retention policies to manage log cleanup based on partition size or age. - You can configure storage thresholds to alert you when disk space is running low. - You can enable [Continuous Data Balancing](../continuous-data-balancing/) to ensure well-balanced disk usage across the cluster. - You can create a ballast file to allow fast recovery from a full disk. ## [](#configure-message-retention)Configure message retention By default, all topics on Redpanda Self-Managed clusters retain 24 hours of data on local disk, while Redpanda Cloud topics retain 6 hours of data. Redpanda makes use of dynamic [space management](#space_management) strategies to save on disk space. If data is written fast enough, however, it’s possible to exhaust local disk space even when using Tiered Storage. Proper configuration of message retention properties for your use case can prevent this from happening. Retention properties control the minimum length of time messages are kept on disk before they’re deleted or compacted. Setting message retention properties is the best way to prevent old messages from accumulating on disk to the point that the disk becomes full. You can configure retention properties to delete messages based on the following conditions: - Message age is exceeded. - Aggregate message size in the topic is exceeded. - A combination of message age and aggregate size, triggered when either is exceeded. You may set retention properties at the topic level or the cluster level. If a value isn’t specified for the topic, then the topic uses the value for the cluster. Note that cluster-level property names use snake-case, while topic-level properties use dots. > 📝 **NOTE** > > Although retention policy is set at a cluster or topic level, it applies to each partition in a topic independently. Within a partition, only closed segments are eligible for deletion or compaction. When a time-based policy is set, all messages within the segment must exceed the set limit. For example, assume the `retention.ms` for a topic is 300,000 ms (5 minutes). If the `segment.ms` is 1,800,000ms (30 minutes) then messages will remain for a minimum of 30 minutes while the segment containing them remains open. In this scenario, five minutes after a new segment begins, the retention policy would trigger deletion of the closed segment. | Retention property | Cluster level | Topic level(overrides cluster configuration) | | --- | --- | --- | | Time-based | log_retention_msDefault - 604800000 | retention.msNo default | | Size-based | retention_bytesNo default | retention.bytesNo default | | Time-based (with Tiered Storage enabled) | retention_local_target_ms_defaultDefault - 86400000 | retention.local.target.msNo default | | Size-based (with Tiered Storage enabled) | retention_local_target_bytes_defaultDefault - null | retention.local.target.bytesNo default | | Segment lifetime | log_segment_msNo default | segment.msNo default | | Segment size | log_segment_sizeDefault - 1073741824 | segment.bytesNo default | Data expires from object storage following both `retention.ms` and `retention.bytes`. For example, if `retention.bytes` is set to 10 GiB, then every partition in the topic has a limit of 10 GiB storage. When `retention.bytes` is exceeded by data in object storage, the data in object storage is trimmed, even if `retention.ms` is not yet exceeded. With Tiered Storage enabled, data expires from local storage following `retention.local.target.ms` or `retention.local.target.bytes`. ![Time-based segment rolling](../../../shared/_images/segment-rolling-size-and-time.png) Retention policy functions by deleting or compacting closed segments. The segment lifetime and segment size configurations help ensure new segments are created regularly within each partition. This illustration shows how Redpanda creates new segments based on size and time. After the limit for a segment is reached, whether it’s size- or time-based, Redpanda closes the segment and begins filling a new segment. If the limits are set too high, the segment may fill available disk space before closing and therefore never become eligible for deletion or compaction. If the values are set too low, your partitions will have a large number of segments that must be checked each time deletion or compaction processes execute, having a potential adverse impact on system resource utilization. > 📝 **NOTE** > > Both size-based and time-based retention policies are applied simultaneously. It’s possible for your size-based property to override your time-based property, or vice versa. For example, if your size-based property requires removing one segment, and your time-based property requires removing three segments, then three segments are removed. Size-based properties reclaim disk space as close as possible to the maximum size, without exceeding the limit. Redpanda runs a log cleanup process in the background to apply these policy settings. If you start to run out of disk space, adjusting your retention properties is an excellent way to reduce the amount of disk space used. See also: - [Manage local capacity for Tiered Storage topics](../../tiered-storage/#manage-local-capacity-for-tiered-storage-topics) - [Delete records from a topic](../../../develop/manage-topics/config-topics/#delete-records-from-a-topic) ### [](#set-time-based-retention)Set time-based retention Redpanda enforces time-based retention to manage log segment deletion according to record timestamps. Messages are eligible for deletion when their age exceeds the value specified in `log_retention_ms` (the cluster-level property) or `retention.ms` (the topic-level property). Only closed segments are eligible for deletion and all messages in a closed segment must exceed the age limit before Redpanda considers the segment for cleanup. If `retention.ms` is not set at the topic level, the topic inherits the `log_retention_ms` setting. Starting in v25.3, Redpanda validates timestamps using the properties `log_message_timestamp_before_max_ms` and `log_message_timestamp_after_max_ms`. These settings ensure that records are only accepted if their timestamps are within an allowed range, and prevent retention issues caused by records with timestamps that are too far in the past or future. By validating directly from record batches, Redpanda ensures: - Accurate, timestamp-based retention across clusters - Predictable and consistent data deletion behavior - Proper retention alignment for replicated and disaster recovery use cases Clusters running versions prior to v25.3 may continue to use the broker timestamp (`broker_timestamp`), which is populated when the broker first receives the record. You can also manually opt in clusters running versions prior to v25.3 to this new `max_timestamp` behavior using the Admin API: ```bash curl --request PUT http://localhost:9644/v1/features/validated_batch_timestamps -d '{"state":"active"}' ``` > ❗ **IMPORTANT** > > When manually opting in clusters running versions prior to v25.3, it is particularly important for users of MirrorMaker2 and Shadowing to enable this feature flag on their destination clusters. Without this feature flag, active clusters created by MirrorMaker2 that are running versions prior to v25.3 will have retention enforced from the date of cluster creation rather than the date of the data. You can see this if you compare the data present on the original cluster versus the newly-replicated cluster, as it will show a difference in retention enforcement. > 📝 **NOTE** > > Make sure that all of the produced data sent to `redpanda` pre-validation checks is correct with respect to having properly set `log_message_timestamp_before_max_ms` and `log_message_timestamp_after_max_ms` in each record batch. If these timestamps are missing or incorrect: > > - Data reclaimed earlier than you expect when using `broker_timestamp`\-based retention due to unset or low `max_timestamp` values > > - Retention could be blocked due to high `max_timestamp` at some point in the future. To set retention time for a single topic, use `retention.ms`, which overrides `log_retention_ms`. - `retention.ms` - Topic-level property that specifies how long a message stays on disk before it’s deleted. To minimize the likelihood of out-of-disk outages, set `retention.ms` to `86400000`, which is one day. There is no default. To set `retention.ms` on an individual topic: ```bash rpk topic alter-config --set retention.ms= ``` - `log_retention_ms` - Cluster-level property that specifies how long a message stays on disk before it’s deleted. To minimize the likelihood of out-of-disk outages, set `log_retention_ms` to `86400000`, which is one day. The default is `604800000`, which is one week. > ⚠️ **CAUTION** > > Do not set `log_retention_ms` to `-1` unless you’re using [remote write with Tiered Storage](../../tiered-storage/#remote-write) to upload segments to object storage. Setting it to `-1` configures indefinite retention, which can fill disk space. See also: - [Broker timestamps](../../../develop/produce-data/configure-producers/#broker-timestamps) ### [](#set-size-based-retention)Set size-based retention Messages are eligible for deletion after the storage size of the partition containing them exceeds the value specified in `retention_bytes` (the cluster-level property) or `retention.bytes` (the topic-level property). If `retention.bytes` is not set at the topic level, the topic inherits the `retention_bytes` setting. Segments are deleted in chronological order until the partition is back under the specified size limit. - `retention.bytes` - Topic-level property that specifies the maximum size of a partition. There is no default. To set `retention.bytes`: ```bash rpk topic alter-config --set retention.bytes= ``` - `retention_bytes` - Cluster-level property that specifies the maximum size of a partition. Set this to a value that is lower than the disk capacity, or a fraction of the disk capacity based on the number of partitions per topic. For example, if you have one partition, `retention_bytes` can be 80% of the disk size. If you have 10 partitions, it can be 80% of the disk size divided by 10. The default is `null`, which means that retention based on topic size is disabled. To set `retention_bytes`: ```bash rpk cluster config set retention_bytes ``` ## [](#configure-offset-retention)Configure offset retention Redpanda supports consumer group offset retention through both periodic offset expiration and the Kafka OffsetDelete API. For periodic offset expiration, set the retention duration of consumer group offsets and the check period. Redpanda identifies offsets that are expired and removes them to reclaim storage. For a consumer group, the retention timeout starts from when the group becomes empty as a consequence of losing all its consumers. For a standalone consumer, the retention timeout starts from the time of the last commit. Once elapsed, an offset is considered to be expired and is discarded. | Property | Description | | --- | --- | | group_offset_retention_check_ms | Period at which Redpanda checks for expired consumer group offsets. | | group_offset_retention_sec | Retention duration of consumer group offsets. | | legacy_group_offset_retention_enabled | Enable group offset retention for Redpanda clusters upgraded from versions prior to v23.1. | Redpanda supports group offset deletion with the Kafka OffsetDelete API through rpk with the [`rpk group offset-delete`](../../../reference/rpk/rpk-group/rpk-group-offset-delete/) command. The offset delete API provides finer control over culling consumer offsets. For example, it enables the manual removal of offsets that are tracked by Redpanda within the `__consumer_offsets` topic. The offsets requested to be removed will be removed only if either the group in question is in a dead state, or the partitions being deleted have no active subscriptions. ## [](#manage-transaction-coordinator-disk-usage)Manage transaction coordinator disk usage Redpanda uses the internal topic `kafka_internal/tx` to store transaction metadata for exactly-once and transactional producers. The log files contain all historical transactions, both committed and current open ones. Over time, this topic can consume excessive disk space in niche use cases that generate a large number of transactional sessions. You can manage the disk usage of `kafka_internal/tx` by tuning the following cluster properties: - `[transaction_coordinator_delete_retention_ms](../../../reference/properties/cluster-properties/#transaction_coordinator_delete_retention_ms)`. Default: `604800000` (7 days). - `[transactional_id_expiration_ms](../../../reference/properties/cluster-properties/#transactional_id_expiration_ms)`. Default: `604800000` (7 days). To mitigate unbounded growth of `kafka_internal/tx` disk usage and manage its storage consumption more effectively, [monitor your storage metrics](#monitor-disk-space) and lower the values of the relevant properties as needed. To adjust these properties, run: ```bash rpk cluster config set transaction_coordinator_delete_retention_ms= transactional_id_expiration_ms= ``` ## [](#configure-segment-size)Configure segment size The `log_segment_size` property specifies the size of each log segment within the partition. Redpanda closes segments after they exceed this size and messages begin filling a new segment. ![Cluster message retention hierarchy](../../../shared/_images/cluster-message-retention.png) To set `log_segment_size`: ```bash rpk cluster config set log_segment_size ``` If you know which topics will receive more data, it’s best to specify the size for each topic. To configure log segment size on a topic: ```bash rpk topic alter-config --set segment.bytes= ``` ### [](#segment-size-for-compacted-topics)Segment size for compacted topics Compaction, or key-based retention, saves space by retaining at least the most recent value for a message key within a topic partition’s log and discarding older values. Compaction runs periodically in the background in a best effort fashion, and it doesn’t guarantee that there are no duplicate values per key. When compaction is configured, topics take their size from `compacted_log_segment_size`. The `log_segment_size` property does not apply to compacted topics. When compaction executes, one or more segments are merged into one new compacted segment. The old segments are deleted. The size of the initial segments are controlled by `segment.bytes`. The `max_compacted_log_segment_size` property controls how many segments are merged together. For example, if you set `segment.bytes` to 128 MB, but leave `max_compacted_log_segment_size` at 5 GB, fresh segments are 128 MB but merged segments may grow up to 5 GB after compaction. Redpanda periodically performs compaction in the background. The compaction period is configured by the cluster property [log\_compaction\_interval\_ms](../../../reference/properties/cluster-properties/#log_compaction_interval_ms). Keep in mind that very large segments delay, or possibly prevent, compaction. A very large active segment cannot be cleaned up or compacted until it is closed, and very large closed segments require significant memory and CPU to process for compaction. Very small segments increase the frequency of processing for applying compaction and resource limits. To calculate an upper limit on segment size, divide the disk size by the number of partitions. For example, if you have a 128 GB disk and 1000 partitions, the upper limit of the segment size is `134217728`. Default is `1073741824`. For details about how to modify cluster configuration properties, see [Cluster configuration](../cluster-property-configuration/). For further information on how compaction works, see [Compaction tuning](../compaction-settings/). ### [](#log-rolling)Log rolling Writing data for a topic usually spans multiple log segments. An **active segment** of a topic is a log segment that is being written to. As data of a topic is written and an active segment becomes full (reaches `log_segment_size`), it’s closed and changed to read-only mode. A new segment is created and set to read-write mode, and it becomes the active segment. **Log rolling** is the rotation between segments to create a new active segment. Configurable timeouts can also trigger log rolling. This is useful when applying topic retention limits within a known fixed duration. A log rolling timeout starts from the first write to an active segment. When a timeout elapses before the segment is full, the segment is rolled. The timeouts are configured with cluster-level and topic-level properties: - [log\_segment\_ms](../../../reference/properties/cluster-properties/#log_segment_ms) (or `log.roll.ms`) is a cluster property that configures the default segment rolling timeout for all topics of a cluster. To set `log_segment_ms` for all topics of a cluster for a duration in milliseconds: ```bash rpk cluster config set log_segment_ms ``` - `segment.ms` is a topic-level property that configures the default segment rolling timeout for one topic. It’s not set by default. If set, it overrides `log_segment_ms`. To set `segment.ms` for a topic: ```bash rpk topic alter-config --set segment.ms= ``` - [log\_segment\_ms\_min](../../../reference/properties/cluster-properties/#log_segment_ms_min) and [log\_segment\_ms\_max](../../../reference/properties/cluster-properties/#log_segment_ms_max) are cluster-level properties that configure the lower and upper limits, respectively, of log rolling timeouts. ## [](#space_management)Space management > 📝 **NOTE** > > Space management only works when [Tiered Storage](../../tiered-storage/) is enabled on all topics. Space management and the housekeeping process only considers removing data that is safely stored in Tiered Storage. The goal of space management is to utilize the local disk space as a cache. It works alongside [Tiered Storage](../../tiered-storage/) to provide faster access to recent data, while making sure that local disk space is managed in accordance with retention policies and other processes, such as [Continuous Data Balancing](../continuous-data-balancing/) and [decommissioning](../decommission-brokers/). Space management divides the disk space into different areas that can be managed separately: - Reserved disk space (`disk_reservation_percent`) is the area of disk space that Redpanda does not use. - As the disk space used by the other areas grows to their target sizes, the reserved space provides buffer space to avoid free disk space alerts. - SSDs that run near capacity can experience performance degradation, so this buffer space prevents the disks from running at capacity. - Cache storage (the minimum of `cloud_storage_cache_size_percent` or `cloud_storage_cache_size`) is the maximum size of the [disk cache](../../tiered-storage/#caching) used by Tiered Storage. As the cache reaches its limit, new data added to the cache removes old data from the cache. - Log storage (the minimum of `retention_local_target_capacity_percent` or `retention_local_target_capacity_bytes`) is the area of disk space used for topic data. This is typically 70-80% of total disk space. ![Redpanda disk storage categories](../../../shared/_images/disk_storage.png) Log segment eviction occurs in each of the following phases. As soon as log storage usage falls below the target, the eviction process ends. > ❗ **IMPORTANT** > > Redpanda’s space management features are enabled with the [`space_management_enable`](../../../reference/properties/cluster-properties/#space_management_enable) parameter. As of Redpanda **v23.3.2**, all new clusters default this value to `true`. When upgrading from older versions, ensure this parameter is set to `true` if you wish to make use of space management as described here. Alternatively, if you wish to explicitly disable these features, set this property to `false`. See also: [Object storage housekeeping](../../tiered-storage/#object-storage-housekeeping) ### [](#phases-of-data-removal)Phases of data removal #### [](#phase-1-follow-retention-policy)Phase 1: Follow retention policy A housekeeping process in Redpanda periodically performs compaction and removes partition data that has expired according to your retention policy. This applies to both Tiered Storage and non-Tiered Storage topics. Space management attempts to apply retention to partitions in the order that removes the largest amount of data. - When `retention_local_strict` is false (default), the housekeeping process removes data above the configured log storage reservation. - When `retention_local_strict` is true, the housekeeping process uses local retention settings to select what data to remove. > 📝 **NOTE** > > The `retention_local_strict` property is set to true in clusters upgraded from release `23.1` and earlier. #### [](#phase-2-trim-to-local-retention)Phase 2: Trim to local retention This phase removes partition data that exceeds the effective local retention policy. This includes the explicit retention settings applied to a topic, as well as the cluster-level defaults, which are assigned to any topic that does not have explicit topic-level overrides. - When `retention_local_strict` is false (default), the retention policy was met in the previous phase, so no more data is removed. - When `retention_local_strict` is true, the housekeeping process removes data fairly across all topics until each topic reaches its local retention target. After this phase completes, all partitions are operating at a size that reflects their effective local retention target. The next phase starts to override the local retention settings to remove more data. #### [](#phase-3-trim-data-with-default-local-retention-settings)Phase 3: Trim data with default local retention settings For topics with the default local retention settings, this phase removes partition data to a _low-space_ level, which is a configured size of two log segments that provide minimal space for partition operation. The housekeeping process only considers removing data that is safely stored in Tiered Storage. #### [](#phase-4-trim-data-with-explicitly-configured-retention-settings)Phase 4: Trim data with explicitly-configured retention settings For topics with explicitly-configured retention settings, this phase removes data down to the _low-space_ level of two log segments. #### [](#phase-5-trim-to-active-latest-segment)Phase 5: Trim to active (latest) segment The final phase trims all topics down to their last active segment. Data in the active log segment cannot be removed, and it is not available for reclaim until it is rolled, which occurs when it reaches `segment.bytes` or when `segment.ms` time expires. ## [](#monitor-disk-space)Monitor disk space You can check your total disk size and free space by viewing the metrics: - `redpanda_storage_disk_total_bytes` - `redpanda_storage_disk_free_bytes` Redpanda monitors disk space and updates these metrics and the `storage_space_alert` status based on your full disk alert threshold. You can check the alert status with the `redpanda_storage_disk_free_space_alert` metric. The alert values are: - 0 = No alert - 1 = Low free space alert - 2 = Out of space (degraded, external writes are rejected) ## [](#set-free-disk-space-thresholds)Set free disk space thresholds You can set a soft limit for a minimum free disk space alert. This soft limit generates an error message and affects the value of the [`redpanda_storage_disk_free_space_alert`](../../../reference/public-metrics-reference/#redpanda_storage_disk_free_space_alert) metric. You can also set a hard limit for minimum disk space, after which Redpanda enters a degraded performance state. You set the thresholds for these values by configuring the following properties, which you can set on any data disk (one drive per node): | Property | Description | | --- | --- | | storage_space_alert_free_threshold_bytes | Minimum free disk space threshold, in bytes, for generating a low disk space alert. | | storage_space_alert_free_threshold_percent | Minimum free disk space allowed, in percentage of total available space for that drive, for generating a low disk space alert. | | storage_min_free_bytes | Disk space threshold beyond which a degraded performance state is entered. | > 📝 **NOTE** > > The alert threshold can be set in either bytes or percentage of total space. To disable one threshold in favor of the other, set it to zero. When a disk exceeds the configured alert threshold, Redpanda updates the [`redpanda_storage_disk_free_space_alert`](../../../reference/public-metrics-reference/#redpanda_storage_disk_free_space_alert) metric to `1`, indicating low free space, and writes an error level `storage space alert` message to the service log. The message looks like the following: ```bash ERROR 2023-12-08 15:07:45,716 [shard 0] cluster - storage space alert: free space at 25.574% on /var/lib/redpanda/data: 96.732GiB total, 24.739GiB free, min. free 0.000bytes. Be sure to adjust retention policies as needed to avoid running out of space. ``` If you continue to exhaust disk space and reach the `storage_min_free_bytes` value, the `redpanda_storage_disk_free_space_alert` metric changes to `2`, indicating Redpanda is in a degraded performance state. See [Handle full disks](#handle-full-disks) for more information on addressing this situation. Once disk space is freed, Redpanda updates the `redpanda_storage_disk_free_space_alert` metric accordingly. ## [](#handle-full-disks)Handle full disks If you exceed your low disk space threshold, Redpanda blocks clients from producing. In that state, Redpanda returns errors to external writers, but it still allows internal write traffic, such as replication and rebalancing. The [`storage_min_free_bytes`](../../../reference/properties/cluster-properties/#storage_min_free_bytes) tunable configuration property sets the low disk space threshold—​the hard limit—​for this write rejection. The default value is 5 GiB, which means that when any broker’s free space falls below 5 GiB, Redpanda rejects writes to all brokers. ## [](#create-a-ballast-file)Create a ballast file A ballast file is an empty file that takes up disk space. If Redpanda runs out of disk space and becomes unavailable, you can delete the ballast file as a last resort. This clears up some space and gives you time to delete topics or records and change your retention properties. To create a ballast file, set the following properties in the rpk section of the `redpanda.yaml` file: ```yaml rpk: tune_ballast_file: true ballast_file_path: "/var/lib/redpanda/data/ballast" ballast_file_size: "1GiB" ``` Run `rpk` to create the ballast file: ```bash rpk redpanda tune ballast_file ``` | Property | Description | | --- | --- | | tune_ballast_file | Set to true to enable ballast file creation. Default is false. | | ballast_file_path | You can change the location of the ballast file, but it must be on the same mount point as the Redpanda data directory. Default is /var/lib/redpanda/data/ballast. | | ballast_file_size | Increase the ballast file size if it is a very high-throughput cluster. Decrease the ballast file size if you have very little storage space. The ballast file should be large enough to give you time to delete data and reconfigure retention properties if Redpanda crashes, but small enough that you don’t waste disk space. In general, set this to approximately 10 times the size of the largest segment, to have enough space to compact that topic. Default is 1 GiB. | ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Owl Shop Example Application in Docker](/redpanda-labs/docker-compose/owl-shop/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) See more [Search all labs](/redpanda-labs) --- # Page 127: Manage Throughput **URL**: https://docs.redpanda.com/current/manage/cluster-maintenance/manage-throughput.md --- # Manage Throughput --- title: Manage Throughput latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: cluster-maintenance/manage-throughput page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: cluster-maintenance/manage-throughput.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/cluster-maintenance/manage-throughput.adoc description: Configure broker-wide and client-specific throughput quotas to prevent resource exhaustion and noisy-neighbor issues. page-topic-type: how-to personas: platform_admin, developer learning-objective-1: Set user-based throughput quotas learning-objective-2: Set client ID-based quotas learning-objective-3: Monitor quota usage and throttling behavior page-git-created-date: "2023-08-03" page-git-modified-date: "2026-03-31" support-status: supported --- Redpanda throttles throughput on ingress and egress independently, and you can configure limits at the broker and client levels. This prevents clients from causing unbounded network and disk usage on brokers. You can configure limits at two levels: - Broker limits: These apply to all clients connected to the broker and restrict total traffic on the broker. See [Broker-wide throughput limits](#broker-wide-throughput-limits). - Client limits: These apply to authenticated users or clients defined by their client ID. You can manage client quotas with [`rpk cluster quotas`](../../../reference/rpk/rpk-cluster/rpk-cluster-quotas/), with Redpanda Console, or with the Kafka API. When no quotas apply, the client has unlimited throughput. After reading this page, you will be able to: - Set user-based throughput quotas - Set client ID-based quotas - Monitor quota usage and throttling behavior ## [](#view-connected-client-details)View connected client details Before configuring throughput quotas, check the [current produce and consume throughput](../../monitoring/#throughput) of a client. Use the [`rpk cluster connections list`](../../../reference/rpk/rpk-cluster/rpk-cluster-connections-list/) command or the [ListKafkaConnections](/api/doc/admin/v2/operation/operation-redpanda-core-admin-v2-clusterservice-listkafkaconnections) Admin API endpoint to view detailed information about active Kafka client connections. For example, to view a cluster’s connected clients in order of highest current produce throughput, run: ### rpk ```bash rpk cluster connections list --order-by="recent_request_statistics.produce_bytes desc" ``` ```bash UID STATE USER CLIENT-ID IP:PORT NODE SHARD OPEN-TIME IDLE PROD-TPUT/SEC FETCH-TPUT/SEC REQS/MIN b20601a3-624c-4a8c-ab88-717643f01d56 OPEN UNAUTHENTICATED perf-producer-client 127.0.0.1:55012 0 0 9s 0s 78.9MB 0B 292 36338ca5-86b7-4478-ad23-32d49cfaef61 OPEN UNAUTHENTICATED rpk 127.0.0.1:49722 0 0 13s 13.694243104s 0B 0B 1 7e277ef6-0176-4007-b100-6581bfde570f OPEN UNAUTHENTICATED rpk 127.0.0.1:49736 0 0 13s 10.093957335s 0B 0B 2 567d9918-d3dc-4c74-ab5d-85f70cd3ee35 OPEN UNAUTHENTICATED rpk 127.0.0.1:49748 0 0 13s 0.591413542s 0B 0B 5 08616f21-08f9-46e7-8f06-964bd8240d9b OPEN UNAUTHENTICATED rpk 127.0.0.1:49764 0 0 13s 10.094602845s 0B 0B 2 e4d5b57e-5c76-4975-ada8-17a88d68a62d OPEN UNAUTHENTICATED rpk 127.0.0.1:54992 0 0 10s 0.302090085s 0B 14.5MB 27 b41584f3-2662-4185-a4b8-0d8510f5c780 OPEN UNAUTHENTICATED perf-producer-client 127.0.0.1:55002 0 0 8s 7.743592270s 0B 0B 1 62fde947-411d-4ea8-9461-3becc2631b46 CLOSED UNAUTHENTICATED rpk 127.0.0.1:48578 0 0 26s 0.000737836s 0B 0B 1 95387e2e-2ec4-4040-aa5e-4257a3efa1a2 CLOSED UNAUTHENTICATED rpk 127.0.0.1:48564 0 0 26s 0.208180826s 0B 0B 1 ``` ### curl ```bash curl -s -X POST \ --header "Content-Type: application/json" \ --data '{ "filter": "", "order_by": "recent_request_statistics.produce_bytes desc" }' \ "localhost:9644/redpanda.core.admin.v2.ClusterService/ListKafkaConnections" ``` Show example API response ```json { "connections": [ { "nodeId": 0, "shardId": 0, "uid": "b20601a3-624c-4a8c-ab88-717643f01d56", "state": "KAFKA_CONNECTION_STATE_OPEN", "openTime": "2025-10-15T14:15:15.755065000Z", "closeTime": "1970-01-01T00:00:00.000000000Z", "authenticationInfo": { "state": "AUTHENTICATION_STATE_UNAUTHENTICATED", "mechanism": "AUTHENTICATION_MECHANISM_UNSPECIFIED", "userPrincipal": "" }, "listenerName": "", "tlsInfo": { "enabled": false }, "source": { "ipAddress": "127.0.0.1", "port": 55012 }, "clientId": "perf-producer-client", "clientSoftwareName": "apache-kafka-java", "clientSoftwareVersion": "3.9.0", "transactionalId": "my-tx-id", "groupId": "", "groupInstanceId": "", "groupMemberId": "", "apiVersions": { "18": 4, "22": 3, "3": 12, "24": 3, "0": 7 }, "idleDuration": "0s", "inFlightRequests": { "sampledInFlightRequests": [ { "apiKey": 0, "inFlightDuration": "0.000406892s" } ], "hasMoreRequests": false }, "totalRequestStatistics": { "produceBytes": "78927173", "fetchBytes": "0", "requestCount": "4853", "produceBatchCount": "4849" }, "recentRequestStatistics": { "produceBytes": "78927173", "fetchBytes": "0", "requestCount": "4853", "produceBatchCount": "4849" } }, ... ] "totalSize": "9" } ``` To view connections for a specific client, you can use a filter expression: ### rpk ```bash rpk cluster connections list --client-id="perf-producer-client" ``` ```bash UID STATE USER CLIENT-ID IP:PORT NODE SHARD OPEN-TIME IDLE PROD-TPUT/SEC FETCH-TPUT/SEC REQS/MIN b41584f3-2662-4185-a4b8-0d8510f5c780 OPEN UNAUTHENTICATED perf-producer-client 127.0.0.1:55002 0 0 8s 7.743592270s 0B 0B 1 b20601a3-624c-4a8c-ab88-717643f01d56 OPEN UNAUTHENTICATED perf-producer-client 127.0.0.1:55012 0 0 9s 0s 78.9MB 0B 292 ``` The `USER` field in the connection list shows the authenticated principal. Unauthenticated connections show `UNAUTHENTICATED`, which corresponds to an empty user principal (`user=""`) in quota configurations, not `user=`. ### curl ```bash curl -s -X POST \ --header "Content-Type: application/json" \ --data '{ "filter": "client_id = \"perf-producer-client\"" }' \ "localhost:9644/redpanda.core.admin.v2.ClusterService/ListKafkaConnections" ``` Show example API response ```json { "connections": [ { "nodeId": 0, "shardId": 0, "uid": "b41584f3-2662-4185-a4b8-0d8510f5c780", "state": "KAFKA_CONNECTION_STATE_OPEN", "openTime": "2025-10-15T14:15:15.219538000Z", "closeTime": "1970-01-01T00:00:00.000000000Z", "authenticationInfo": { "state": "AUTHENTICATION_STATE_UNAUTHENTICATED", "mechanism": "AUTHENTICATION_MECHANISM_UNSPECIFIED", "userPrincipal": "" }, "listenerName": "", "tlsInfo": { "enabled": false }, "source": { "ipAddress": "127.0.0.1", "port": 55002 }, "clientId": "perf-producer-client", "clientSoftwareName": "apache-kafka-java", "clientSoftwareVersion": "3.9.0", "transactionalId": "", "groupId": "", "groupInstanceId": "", "groupMemberId": "", "apiVersions": { "18": 4, "3": 12, "10": 4 }, "idleDuration": "7.743592270s", "inFlightRequests": { "sampledInFlightRequests": [], "hasMoreRequests": false }, "totalRequestStatistics": { "produceBytes": "0", "fetchBytes": "0", "requestCount": "3", "produceBatchCount": "0" }, "recentRequestStatistics": { "produceBytes": "0", "fetchBytes": "0", "requestCount": "3", "produceBatchCount": "0" } }, ... ], "totalSize": "2" } ``` To view connections for a specific authenticated user: ```bash rpk cluster connections list --user alice ``` This shows all connections from user `alice`, useful for monitoring clients that are subject to user-based quotas. ## [](#broker-wide-throughput-limits)Broker-wide throughput limits Broker-wide throughput limits account for all Kafka API traffic going into or out of the broker, as data is produced to or consumed from a topic. The limit values represent the allowed rate of data in bytes per second passing through in each direction. Redpanda also provides administrators the ability to exclude clients from throughput throttling and to fine-tune which Kafka request types are subject to throttling limits. ### [](#broker-wide-throughput-limit-properties)Broker-wide throughput limit properties The properties for broker-wide throughput quota balancing are configured at the cluster level, for all brokers in a cluster: | Cluster configuration property | Description | | --- | --- | | kafka_throughput_limit_node_in_bps | A broker’s total throughput limit for ingress Kafka traffic. | | kafka_throughput_limit_node_out_bps | A broker’s total throughput limit for egress Kafka traffic. | | kafka_throughput_control | List of clients for whom broker-wide limits do not apply. | | kafka_throughput_controlled_api_keys | Kafka request types subject to broker-wide throughput limits; defaults to produce and fetch. | | max_kafka_throttle_delay_ms | Maximum delay inserted in the data path of Kafka API requests to throttle them down. Setting this lower than the Kafka client timeout helps ensure throttling alone does not cause client timeouts. | > 📝 **NOTE** > > By default, both `kafka_throughput_limit_node_in_bps` and `kafka_throughput_limit_node_out_bps` are disabled, and no throughput limits are applied. You must manually set them to enable throughput throttling. To set broker-wide throughput limits, use [`rpk cluster config set`](../../../reference/rpk/rpk-cluster/rpk-cluster-config-set/) to configure the cluster properties: ```bash # Set ingress limit to 100 MB/s per broker rpk cluster config set kafka_throughput_limit_node_in_bps 100000000 # Set egress limit to 200 MB/s per broker rpk cluster config set kafka_throughput_limit_node_out_bps 200000000 ``` ## [](#client-throughput-limits)Client throughput limits Redpanda provides configurable throughput quotas for individual clients or authenticated users. Quotas are managed through the Kafka-compatible AlterClientQuotas and DescribeClientQuotas APIs, accessible with `rpk`, Redpanda Console, or Kafka client libraries. Redpanda supports two types of client throughput quotas: - Client ID-based quotas: Limit throughput based on the self-declared `client-id` field. - User-based quotas: Limit throughput based on authenticated user [principal](https://docs.redpanda.com/current/reference/glossary/#principal). Requires [authentication](../../security/authentication/). You can also combine both types for fine-grained control (for example, limiting a specific user when using a specific client application). For conceptual information about quota types, entity hierarchy, precedence rules, and how Redpanda tracks and enforces quotas through throttling, see [About Client Throughput Quotas](../about-throughput-quotas/). ### [](#set-user-based-quotas)Set user-based quotas > ❗ **IMPORTANT** > > User-based quotas require authentication to be enabled. To set up authentication, see [Configure Authentication](../../security/authentication/). #### [](#quota-for-a-specific-user)Quota for a specific user To limit throughput for a specific authenticated user across all clients: ```bash rpk cluster quotas alter --add producer_byte_rate=2000000 --name user=alice ``` This limits user `alice` to 2 MB/s for produce requests regardless of the client ID used. To view quotas for a user: ```bash rpk cluster quotas describe --name user=alice ``` Expected output: ```bash user=alice producer_byte_rate=2000000 ``` #### [](#default-quota-for-all-users)Default quota for all users To set a fallback quota for any user without a more specific quota: ```bash rpk cluster quotas alter --add consumer_byte_rate=5000000 --default user ``` This applies a 5 MB/s fetch quota to all authenticated users who don’t have a more specific quota configured. ### [](#remove-a-user-quota)Remove a user quota To remove a quota for a specific user: ```bash rpk cluster quotas alter --delete consumer_byte_rate --name user=alice ``` To remove all quotas for a user: ```bash rpk cluster quotas delete --name user=alice ``` ### [](#set-client-id-based-quotas)Set client ID-based quotas Client ID-based quotas apply to all users using a specific client ID. These quotas do not require authentication. Because the client ID is self-declared, client ID-based quotas are not suitable for guaranteeing isolation between tenants. For multi-tenant environments, Redpanda recommends user-based quotas for per-tenant isolation. #### [](#individual-client-id-throughput-limit)Individual client ID throughput limit To view current throughput quotas set through the Kafka API, run [`rpk cluster quotas describe`](../../../reference/rpk/rpk-cluster/rpk-cluster-quotas-describe/). For example, to see the quotas for client ID `consumer-1`: ```bash rpk cluster quotas describe --name client-id=consumer-1 ``` ```bash client-id=consumer-1 producer_byte_rate=140000 ``` To set a throughput quota for a single client, use the [`rpk cluster quotas alter`](../../../reference/rpk/rpk-cluster/rpk-cluster-quotas-alter/) command. ```bash rpk cluster quotas alter --add consumer_byte_rate=200000 --name client-id=consumer-1 ``` ```bash ENTITY STATUS client-id=consumer-1 OK ``` #### [](#group-of-clients-throughput-limit)Group of clients throughput limit Alternatively, you can view or configure throughput quotas for a group of clients based on a match on client ID prefix. The following example sets the `consumer_byte_rate` quota to client IDs prefixed with `consumer-`: ```bash rpk cluster quotas alter --add consumer_byte_rate=200000 --name client-id-prefix=consumer- ``` > 📝 **NOTE** > > A `client-id-prefix` quota group is not related to Kafka consumer groups. The client ID is an application-defined identifier sent with every request. Client libraries typically default to their own name (such as `kgo`, `rdkafka`, `sarama`, or `perf-producer-client`), but applications can set it using the [`client.id`](https://kafka.apache.org/documentation/#consumerconfigs_client.id) configuration property. This makes prefix-based quotas useful for grouping related applications (for example, `inventory-service-` to match `inventory-service-1`, `inventory-service-2`, etc.). #### [](#default-client-throughput-limit)Default client throughput limit You can apply default throughput limits to clients. Redpanda applies the default limits if no quotas are configured for a specific client ID or prefix. To specify a produce quota of 1 GB/s through the Kafka API (applies across all produce requests to a single broker), run: ```bash rpk cluster quotas alter --default client-id --add producer_byte_rate=1000000000 ``` ### [](#set-combined-user-and-client-quotas)Set combined user and client quotas You can set quotas for specific (user, client ID) combinations for fine-grained control. #### [](#user-with-specific-client)User with specific client To limit a specific user when using a specific client: ```bash rpk cluster quotas alter --add consumer_byte_rate=1000000 --name user=alice --name client-id=consumer-1 ``` User `alice` using `client-id=consumer-1` is limited to a 1 MB/s fetch rate. The same user with a different client ID would use a different quota (or fall back to less specific matches). To view combined quotas: ```bash rpk cluster quotas describe --name user=alice --name client-id=consumer-1 ``` #### [](#user-with-client-prefix)User with client prefix To set a shared quota for a user across multiple clients matching a prefix: ```bash rpk cluster quotas alter --add producer_byte_rate=3000000 --name user=bob --name client-id-prefix=app- ``` All clients used by user `bob` with a client ID starting with `app-` share a combined 3 MB/s produce quota. #### [](#default-user-with-specific-client)Default user with specific client To set a quota for a specific client across all users: ```bash rpk cluster quotas alter --add producer_byte_rate=500000 --default user --name client-id=payment-processor ``` Any user using `client-id=payment-processor` is limited to a 500 KB/s produce rate, unless they have a more specific quota configured. ### [](#bulk-manage-client-throughput-limits)Bulk manage client throughput limits To more easily manage multiple quotas, you can use the `cluster quotas describe` and [`cluster quotas import`](../../../reference/rpk/rpk-cluster/rpk-cluster-quotas-import/) commands to do a bulk export and update. For example, to export all client quotas in JSON format: ```bash rpk cluster quotas describe --format json ``` `rpk cluster quotas import` accepts the output string from `rpk cluster quotas describe --format `: ```bash rpk cluster quotas import --from '{"quotas":[{"entity":[{"name":"analytics-consumer","type":"client-id"}],"values":[{"key":"consumer_byte_rate","values":"10000000"}]},{"entity":[{"name":"analytics-","type":"client-id-prefix"}],"values":[{"key":"producer_byte_rate","values":"10000000"},{"key":"consumer_byte_rate","values":"5000000"}]}]}' ``` You can also save the JSON or YAML output to a file and pass the file path in the `--from` flag. ### [](#view-throughput-limits-in-redpanda-console)View throughput limits in Redpanda Console You can also use Redpanda Console to view enforced limits. In the side menu, go to **Quotas**. ### [](#monitor-client-throughput)Monitor client throughput The following metrics provide insights into client throughput quota usage: - Client quota throughput per rule and quota type: - `/public_metrics` - [`redpanda_kafka_quotas_client_quota_throughput`](../../../reference/public-metrics-reference/#redpanda_kafka_quotas_client_quota_throughput) - `/metrics` - [`vectorized_kafka_quotas_client_quota_throughput`](../../../reference/internal-metrics-reference/#vectorized_kafka_quotas_client_quota_throughput) - Client quota throttling delay per rule and quota type, in seconds: - `/public_metrics` - [`redpanda_kafka_quotas_client_quota_throttle_time`](../../../reference/public-metrics-reference/#redpanda_kafka_quotas_client_quota_throttle_time) - `/metrics` - [`vectorized_kafka_quotas_client_quota_throttle_time`](../../../reference/internal-metrics-reference/#vectorized_kafka_quotas_client_quota_throttle_time) To identify which clients are actively connected and generating traffic, see [View connected client details](#view-connected-client-details). Quota metrics use the `redpanda_quota_rule` label to identify which quota was applied to a request. The label distinguishes between different entity types (user, client, or combinations). See the label values in [`redpanda_kafka_quotas_client_quota_throughput`](../../../reference/public-metrics-reference/#redpanda_kafka_quotas_client_quota_throughput). The `kafka_quotas` logger provides details at the trace level on client quota throttling: ```bash TRACE 2024-06-14 15:36:05,240 [shard 2:main] kafka_quotas - quota_manager.cc:361 - request: ctx:{quota_type: produce_quota, client_id: {rpk}}, key:k_client_id{rpk}, value:{limit: {1111}, rule: kafka_client_default}, bytes: 1316, delay:184518451ns, capped_delay:184518451ns TRACE 2024-06-14 15:36:05,240 [shard 2:main] kafka_quotas - connection_context.cc:605 - [127.0.0.1:51256] throttle request:{snc:0, client:184}, enforce:{snc:-365123762, client:-365123762}, key:0, request_size:1316 TRACE 2024-06-14 15:37:44,835 [shard 2:main] kafka_quotas - quota_manager.cc:361 - request: ctx:{quota_type: produce_quota, client_id: {rpk}}, key:k_client_id{rpk}, value:{limit: {1111}, rule: kafka_client_default}, bytes: 119, delay:0ns, capped_delay:0ns TRACE 2024-06-14 15:37:59,195 [shard 2:main] kafka_quotas - quota_manager.cc:361 - request: ctx:{quota_type: produce_quota, client_id: {rpk}}, key:k_client_id{rpk}, value:{limit: {1111}, rule: kafka_client_default}, bytes: 1316, delay:184518451ns, capped_delay:184518451ns TRACE 2024-06-14 15:37:59,195 [shard 2:main] kafka_quotas - connection_context.cc:605 - [127.0.0.1:58636] throttle request:{snc:0, client:184}, enforce:{snc:-14359, client:-14359}, key:0, request_size:1316 ``` ## [](#see-also)See also - [About Client Throughput Quotas](../about-throughput-quotas/) - [Configure Client Connections](../configure-client-connections/) - [Configure Authentication](../../security/authentication/) --- # Page 128: Configure Broker Properties **URL**: https://docs.redpanda.com/current/manage/cluster-maintenance/node-property-configuration.md --- # Configure Broker Properties --- title: Configure Broker Properties latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: cluster-maintenance/node-property-configuration page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: cluster-maintenance/node-property-configuration.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/cluster-maintenance/node-property-configuration.adoc description: Learn how to configure broker properties with the redpanda.yaml file. page-git-created-date: "2023-08-17" page-git-modified-date: "2025-08-15" support-status: supported --- When you install Redpanda, a `redpanda.yaml` file is installed on each broker in `/etc/redpanda`. This file contains broker configuration properties. A broker property is one that can be set differently from broker to broker, such as [`data_directory`](../../../reference/properties/broker-properties/#data_directory) or [`node_id`](../../../reference/properties/broker-properties/#node_id) (when specified). See [Broker Configuration Properties](../../../reference/properties/broker-properties/) for a list of broker properties, their descriptions, and their default values. The default `redpanda.yaml` file groups broker properties into categories: - `pandaproxy` - Properties for the Redpanda HTTP Proxy - `redpanda` - Runtime configuration properties, such as the cluster member IP addresses and the data directory - `rpk` - Properties that determine how `rpk` starts Redpanda - `schema registry` - Properties related to storage, retrieval, and compatibility of the schemas ## [](#set-broker-configuration-properties)Set broker configuration properties The `redpanda.yaml` file rarely needs to be edited after the system is installed, but you can choose to change broker configuration property values. > 📝 **NOTE** > > The broker configuration property [`node_id`](../../../reference/properties/broker-properties/) is immutable. To ensure safe operations, omit the `node_id` field from `redpanda.yaml` and allow Redpanda to assign it automatically. For more information, see [Do not configure broker IDs](../../../deploy/redpanda/manual/production/production-deployment/#do-not-configure-broker-ids). To change a broker property setting: 1. Open a terminal window and navigate to the broker where you want to change a property setting. 2. Go to the `/etc/redpanda` directory. 3. Open the `redpanda.yaml` file. 4. Change values for properties as needed. 5. Save the file and close the editor. 6. Restart the broker to apply the changes. When Redpanda starts up and reads the `redpanda.yaml` file, it checks that each property setting has a valid value. If the file contains an invalid property setting, Redpanda logs an error and refuses to start. ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Owl Shop Example Application in Docker](/redpanda-labs/docker-compose/owl-shop/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) See more [Search all labs](/redpanda-labs) --- # Page 129: Node-wise Partition Recovery **URL**: https://docs.redpanda.com/current/manage/cluster-maintenance/nodewise-partition-recovery.md --- # Node-wise Partition Recovery --- title: Node-wise Partition Recovery latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: cluster-maintenance/nodewise-partition-recovery page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: cluster-maintenance/nodewise-partition-recovery.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/cluster-maintenance/nodewise-partition-recovery.adoc description: Feature to recover partitions that have lost a majority of replicas. page-git-created-date: "2024-02-06" page-git-modified-date: "2024-12-03" support-status: supported --- Multi-broker or entire [AZ](https://docs.redpanda.com/current/reference/glossary/#availability-zone-az) failures (especially in cloud environments), along with some forms of human error, can result in ‘stuck’ partitions where there are fewer replicas than required to make a quorum. In such failure scenarios, some data loss may be unavoidable. Node-wise partition recovery provides a way to unsafely recover at least a portion of your data using remaining replicas, which are moved off of target brokers and allocated to healthy ones. In one step, this process repairs partitions while draining the target brokers of all partition replicas. This topic helps admins understand what they can or cannot recover using node-wise partition recovery. > ❗ **IMPORTANT** > > Only use this operation as a last-resort measure when all other recovery options have failed. In some cases, there may be no remaining replicas for the partitions on the dead brokers. This recovery method is intended for scenarios where you have already experienced data loss, with the goal being to stop the loss of additional data. ## [](#perform-the-recovery-operation)Perform the recovery operation To start node-wise partition recovery, run `rpk cluster partitions unsafe-recover`. For example: `rpk cluster partitions unsafe-recover --from-nodes 1,3,5` This command includes a prompt to confirm the generated recovery plan, as it is a destructive operation. When you run node-wise partition recovery, the partitions on the broker are rebuilt on a best-effort basis. When there are zero surviving partition replicas, such as a topic with a replication factor of 1 (`RF=1`), partition recovery rebuilds empty partitions with no data (although you may be able to recover the partition from Tiered Storage), allowing producers to continue writing to the partition even though no data can be recovered in such situations. The `--from-nodes` flag accepts a comma-separated list of the brokers' node IDs you wish to recover the data from. This example performs recovery operations on nodes 1, 3, and 5. Redpanda assesses these brokers to identify which partitions lack a majority. It then creates a plan to recover the impacted partitions and prompts you for confirmation. You must respond `yes` to continue with recovery. The `--dry` flag performs a dry run and allows you to view the recovery plan with no risk to your cluster. > 📝 **NOTE** > > When running node-wise partition recovery, it’s possible that there may be more recent data (a higher offset) available in Tiered Storage if: > > - Raft replication was stuck or slow before the node failure > > - Zero live replicas remain in the cluster (because the partition had a replication factor of one, `RF=1`) > > > For topics configured to use Tiered Storage, Redpanda also attempts to recover partition data from object storage, recovering the latest offset available for a partition in either storage tier (local or object storage). This allows for the maximum amount of data to be recovered in all cases, even for topics with a replication factor of 1, where no replicas remain in local storage. The recovery operation can take some time to complete, especially for a large amount of data. To monitor the status of the recovery operation in real-time, run: `rpk cluster partitions balancer-status` ## [](#example-recovery-operations)Example recovery operations The following example shows the node-wise partition recovery process in action: $ rpk cluster partitions unsafe-recover --from-nodes 1 NAMESPACE TOPIC PARTITION REPLICA-CORE DEAD-NODES kafka bar 0 \[1-1\] \[1\] ? Confirm recovery from these nodes? Yes Executing recovery plan... Successfully queued the recovery plan, you may check the status by running 'rpk cluster partitions balancer-status' $ rpk cluster partitions balancer-status Status: ready Seconds Since Last Tick: 26 Current Reassignment Count: 0 Partitions Pending Recovery (1): \[kafka/bar/0\] The following example shows the status of moved partitions: $ rpk cluster partitions move-status PARTITION MOVEMENTS =================== NAMESPACE-TOPIC PARTITION MOVING-FROM MOVING-TO COMPLETION-% PARTITION-SIZE BYTES-MOVED BYTES-REMAINING kafka/prod\_tests 4 \[045\] \[045\] 0 56204032205 0 56204032205 kafka/prod\_tests 7 \[045\] \[045\] 0 64607340009 0 64607340009 kafka/prod\_tests 12 \[014\] \[014\] 0 29074311639 0 29074311639 kafka/prod\_tests 20 \[014\] \[014\] 0 29673620476 0 29673620476 kafka/prod\_tests 22 \[045\] \[045\] 0 28471089141 0 28471089141 kafka/prod\_tests 23 \[045\] \[045\] 0 29692435312 0 29692435312 kafka/prod\_tests 31 \[014\] \[014\] 0 66982232299 0 66982232299 kafka/prod\_tests 33 \[014\] \[014\] 0 46329276747 0 46329276747 --- # Page 130: Forced partition recovery **URL**: https://docs.redpanda.com/current/manage/cluster-maintenance/partition-recovery.md --- # Forced partition recovery --- title: Forced partition recovery latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: cluster-maintenance/partition-recovery page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: cluster-maintenance/partition-recovery.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/cluster-maintenance/partition-recovery.adoc description: Recover a single partition using the Admin API. page-git-created-date: "2024-02-12" page-git-modified-date: "2025-08-20" support-status: supported --- You can use the Redpanda Admin API to recover a partition that is unavailable and has lost a majority of its replicas. This can occur when the partition replicas have lost [Raft](https://raft.github.io/) consensus, for instance if brokers in a Raft group fail, preventing the group from reaching a majority and electing a new leader. Redpanda performs forced partition recovery by promoting the best available replica to leader, making the partition available for produce and consume. Typically, Redpanda chooses the replica with the highest offset. > ⚠️ **CAUTION** > > Forced partition recovery allows some potential data loss on the partition if the best available replica is out of sync, ending up in an unclean leader election. Use this operation with caution, and only when brokers have failed beyond recovery to the point that the remaining replicas cannot form a majority. > 📝 **NOTE** > > If you want to instead force recover all partitions in bulk from a set of failed brokers, use [nodewise recovery](../nodewise-partition-recovery/). ## [](#use-the-admin-api-to-recover-a-partition)Use the Admin API to recover a partition The following examples assume that partition 0 in topic `test` is unavailable and its replicas cannot form a majority to elect a leader. 1. Call the [`/partitions/kafka/`](/api/doc/admin/operation/operation-get_topic_partitions) endpoint to determine the current broker and shard assignments of the partition replicas. ```bash curl http://localhost:9644/v1/partitions/kafka/test ``` ```bash [ { "ns": "kafka", "topic": "test", "partition_id": 0, "status": "done", "leader_id": 1, "raft_group_id": 1, "replicas": [ { "node_id": 1, "core": 1 }, { "node_id": 2, "core": 1 }, { "node_id": 3, "core": 1 } ] } ] ``` 2. In this scenario, brokers 2 and 3 have failed and you want to move the replicas from those brokers to brokers 4 and 5, which are healthy. Make a POST request to the `/debug/partitions/kafka///force_replicas` endpoint: ```bash curl -X POST http://localhost:9644/v1/debug/partitions/kafka/test/0/force_replicas \ -H 'Content-Type: application/json' -d '{ [ { "node_id": 1, "core": 1 }, { "node_id": 4, "core": 1 }, { "node_id": 5, "core": 0 } ] }' ``` The request body includes the broker ID and the CPU core (shard ID) for the replica on broker 1, to hydrate the new replicas assigned to brokers 4 and 5 on cores 1 and 0 respectively. If there are `n` CPU cores on the machine, the value of `core` can be within the range `[0, n-1]`. You may use a random value within the range, or the least loaded shard. See the [public metrics reference](../../../reference/public-metrics-reference/) for metrics regarding CPU usage, and [Redpanda Admin API](/api/doc/admin/operation/operation-force_update_partition_replicas) for additional detail. ## [](#suggested-reading)Suggested reading - [Partition leadership elections](../../../get-started/architecture/#partition-leadership-elections) --- # Page 131: Perform a Rolling Restart **URL**: https://docs.redpanda.com/current/manage/cluster-maintenance/rolling-restart.md --- # Perform a Rolling Restart --- title: Perform a Rolling Restart latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: cluster-maintenance/rolling-restart page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: cluster-maintenance/rolling-restart.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/cluster-maintenance/rolling-restart.adoc description: Learn how to perform a rolling restart of your Redpanda cluster. page-git-created-date: "2023-12-07" page-git-modified-date: "2025-07-31" support-status: supported --- A rolling restart involves restarting one broker at a time while the remaining brokers in your cluster continue running. This is to minimize downtime during a full cluster restart. You should perform a rolling restart during operations such as configuration updates that require a restart, version upgrades, or cluster maintenance. A rolling restart involves putting a broker into and out of [maintenance mode](../../node-management/), and then repeating the process on the next broker in the cluster. Placing brokers into maintenance mode ensures a smooth restart of your cluster while reducing the risk of interruption or degradation in service. When a broker is placed into maintenance mode, it reassigns its partition leadership to other brokers for all topics that have a replication factor greater than one. Reassigning partition leadership involves _draining_ leadership from the broker and _transferring_ that leadership to another broker. 1. Check for topics that have a replication factor greater than one. If you have topics with `replication.factor=1`, and if you have sufficient disk space, Redpanda Data recommends temporarily increasing the replication factor. This can help limit outages for these topics during the rolling restart. Do this before the restart to make sure there’s time for the data to replicate to other brokers. For more information, see [Change topic replication factor](../../../migrate/data-migration/#change-topic-replication-factor). 2. Ensure that all brokers are active before restarting: ```bash rpk redpanda admin brokers list ``` All brokers should show `active` for `MEMBERSHIP` and `true` for `IS-ALIVE`: Example output ```none ID HOST PORT RACK CORES MEMBERSHIP IS-ALIVE VERSION UUID 0 redpanda-0.testcluster.local 32180 A 8 active true 25.2.13 24c08934-94f6-478c-b57d-45239f452488 1 redpanda-1.testcluster.local 32180 B 8 active true 25.2.13 7f3c1c6e-2f4d-4c8a-9c6e-0a8a6d8b2b61 2 redpanda-2.testcluster.local 32180 C 8 active true 25.2.13 b2e8d4a9-91c1-4b55-9f6a-3f7a2d3c5e44 ``` ## [](#perform-a-rolling-restart)Perform a rolling restart ### [](#enable-maintenance-mode)Enable maintenance mode 1. Check that all brokers are healthy: ```bash rpk cluster health ``` Example output: ```bash CLUSTER HEALTH OVERVIEW ======================= Healthy: true (1) Controller ID: 0 All nodes: [0 1 2] (2) Nodes down: [] (3) Leaderless partitions: [] (3) Under-replicated partitions: [1] (3) ``` | 1 | The cluster is either healthy (true) or unhealthy (false). | | --- | --- | | 2 | The node IDs of all brokers in the cluster. | | 3 | If the cluster is unhealthy, these fields will contain data. | 2. Optional: You can use the Admin API (default port: 9644) to perform additional checks for potential risks with restarting a specific broker. ```bash curl -X GET "http://:/v1/broker/pre_restart_probe" | jq . ``` Example output: ```json // Returns tuples of partitions (in the format {namespace}/{topic_name}/{partition_id}) affected by the broker restart. { "risks": { "rf1_offline": [ "kafka/topic_a/0" ], "full_acks_produce_unavailable": [], "unavailable": [], "acks1_data_loss": [] } } ``` In this example, the restart probe indicates that there is an under-replicated partition `kafka/topic_a/0` (with a replication factor of 1) at risk of going offline if the broker is restarted. See the [Admin API reference](/api/doc/admin/operation/operation-pre_restart_probe) for more details on the restart probe endpoint. 3. Select a broker and place it into maintenance mode: ```bash rpk cluster maintenance enable --wait ``` The `--wait` option tells the command to wait until a given broker, 0 in this example, finishes draining all partitions it originally served. After the partition draining completes, the command completes. Expected output: Successfully enabled maintenance mode for node 0 Waiting for node to drain... 4. Verify that the broker is in maintenance mode: ```bash rpk cluster maintenance status ``` Expected output: NODE-ID DRAINING FINISHED ERRORS PARTITIONS ELIGIBLE TRANSFERRING FAILED 0 true true false 3 0 2 0 1 false false false 0 0 0 0 2 false false false 0 0 0 0 The `Finished` column should read `true` for the broker that you put into maintenance mode. 5. Validate the health of the cluster again: ```bash rpk cluster health --watch --exit-when-healthy ``` The combination of the `--watch` and `--exit-when-healthy` flags tell rpk to monitor the cluster health and exit only when the cluster is back in a healthy state. > 📝 **NOTE** > > You can also evaluate [metrics](../../monitoring/) to determine cluster health. If the cluster has any issues, take the broker out of maintenance mode by running the following command before proceeding with other operations, such as decommissioning or retrying the rolling restart: > > ```bash > rpk cluster maintenance disable > ``` ### [](#check-metrics)Check metrics Before continuing with the restart, check these important metrics to make sure the cluster is healthy and working as expected. | Metric Name | Description | Recommendations | | --- | --- | --- | | redpanda_kafka_under_replicated_replicas | Measures the number of under-replicated Kafka replicas. Non-zero: Replication lagging. Zero: All replicas replicated. | Pause restart if non-zero. | | redpanda_cluster_unavailable_partitions | Represents the number of partitions that are currently unavailable. Value of zero indicates all partitions are available. Non-zero indicates the respective count of unavailable partitions. | Ensure metric shows zero unavailable partitions before restart. | | redpanda_rpc_received_bytes and redpanda_rpc_sent_bytes | Total bytes processed for Kafka requests. | Ensure produce and consume rate for each broker recovers to its pre-restart value. | | redpanda_kafka_request_latency_seconds | Latency for processing Kafka requests. Indicates the delay between a Kafka request being initiated and completed. | Ensure the p99 histogram value recovers to its pre-restart level. | | redpanda_rpc_request_latency_seconds | Latency for processing RPC requests. Shows the delay between an RPC request initiation and completion. | Ensure the p99 histogram value recovers to its pre-restart level. | | redpanda_cpu_busy_seconds_total | CPU utilization for a given second. The value is a decimal between 0.0 and 1.0. A value of 1.0 means that the CPU was busy for the entire second, operating at 100% capacity. A value of 0.5 implies the CPU was busy for half the time (or 500 milliseconds) in the given second. A value of 0.0 indicates that the CPU was idle and not busy during the entire second. | If you’re seeing high values consistently, investigate the reasons. It could be due to high traffic or other system bottlenecks. | ### [](#restart-the-broker)Restart the broker To ensure proper ownership and permissions, restart the broker’s Redpanda service using `systemctl`: ```bash sudo systemctl restart redpanda ``` ### [](#disable-maintenance-mode)Disable maintenance mode 1. Take the broker out of maintenance mode: ```bash rpk cluster maintenance disable ``` Expected output: Successfully disabled maintenance mode for node 0 2. Ensure that the broker is no longer in maintenance mode: ```bash rpk cluster maintenance status ``` Expected output: ```none NODE-ID DRAINING FINISHED ERRORS PARTITIONS ELIGIBLE TRANSFERRING FAILED 0 false false false 0 0 0 0 1 false false false 0 0 0 0 2 false false false 0 0 0 0 ``` ### [](#post-restart-tasks)Post-restart tasks To verify that the cluster is running properly, run: ```bash rpk cluster health ``` To view additional information about your brokers, run: ```bash rpk redpanda admin brokers list ``` You can also use the [Admin API](/api/doc/admin/operation/operation-post_restart_probe) to check how much each broker has progressed in recovering its workloads: ```bash curl -X GET "http://:/v1/broker/post_restart_probe" ``` Example output: ```json // Returns the load already reclaimed by broker, as a percentage of in-sync replicas { "load_reclaimed_pc": 66 } ``` ## [](#impact-of-broker-restarts)Impact of broker restarts When brokers restart, clients may experience higher latency, nodes may experience CPU spikes when the broker becomes available again, and you may receive alerts about under-replicated partitions. Topics that weren’t using replication (that is, topics that had `replication.factor=1`) will be unavailable. ### [](#temporary-increase-in-latency-on-clients-producers-and-consumers)Temporary increase in latency on clients (producers and consumers) When you restart one or more brokers in a cluster, clients (consumers and producers) may experience higher latency due to partition leadership reassignment. Because clients must communicate with the leader of a partition, they may send a request to a broker whose leadership has been transferred, and receive `NOT_LEADER_FOR_PARTITION`. In this case, clients must request metadata from the cluster to find out the address of the new leader. Clients refresh their metadata periodically, or when the client receives some retryable errors that indicate that the metadata may be stale. For example: 1. Broker A shuts down. 2. Client sends a request to broker A, and receives `NOT_LEADER_FOR_PARTITION`. 3. Client requests metadata, and learns that the new leader is broker B. 4. Client sends the request to broker B. ### [](#cpu-spikes-upon-broker-restart)CPU spikes upon broker restart When a restarted broker becomes available again, you may see your nodes' CPU usage increase temporarily. This temporary increase in CPU usage is due to the cluster rebalancing the partition replicas. ### [](#under-replicated-partitions)Under-replicated partitions When a broker is in maintenance mode, Redpanda continues to replicate updates to that broker. When a broker is taken offline during a restart, partitions with replicas on the broker could become out of sync until it is brought back online. Once the broker is available again, data is copied to its under-replicated replicas until all affected partitions are in sync with the partition leader. ## [](#suggested-reading)Suggested reading - [Monitor Redpanda](../../monitoring/) ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Owl Shop Example Application in Docker](/redpanda-labs/docker-compose/owl-shop/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) See more [Search all labs](/redpanda-labs) --- # Page 132: Configure Topic Properties **URL**: https://docs.redpanda.com/current/manage/cluster-maintenance/topic-property-configuration.md --- # Configure Topic Properties --- title: Configure Topic Properties latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: cluster-maintenance/topic-property-configuration page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: cluster-maintenance/topic-property-configuration.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/cluster-maintenance/topic-property-configuration.adoc description: Learn how to configure topic properties to control Redpanda's behavior for individual topics, including retention, cleanup policies, and Tiered Storage settings. page-git-created-date: "2025-09-03" page-git-modified-date: "2026-03-31" support-status: supported --- Topic properties control Redpanda’s behavior for individual topics, including data retention, cleanup policies, compression settings, and Tiered Storage configurations. These properties let you customize how Redpanda stores, processes, and manages data for each topic, overriding cluster-wide defaults when needed. Redpanda stores topic properties as metadata associated with each topic and replicates them across the cluster to ensure consistency. Many topic properties correspond to [cluster properties](../cluster-property-configuration/) that establish default values for all topics. When you set a topic property, it overrides the corresponding cluster default for that specific topic. > ⚠️ **WARNING** > > All topic properties take effect immediately after being set. Do not modify properties on internal Redpanda topics (such as `__consumer_offsets`, `_schemas`, or other system topics) as this can cause cluster instability. For a complete reference of available topic properties and their corresponding cluster properties, see [Topic Configuration Properties](../../../reference/properties/topic-properties/). ## [](#configuration-methods)Configuration methods You can configure topic properties through multiple interfaces: - **rpk commands** - Use [`rpk topic create`](../../../reference/rpk/rpk-topic/rpk-topic-create/) with the `-c` flag to set properties during topic creation, or [`rpk topic alter-config`](../../../reference/rpk/rpk-topic/rpk-topic-alter-config/) to modify existing topics. - **Kafka Admin API** - Any Kafka-compatible client can use the standard Admin API to configure topic properties. - **Kubernetes Topic resources** - In Kubernetes deployments, configure topic properties using the `additionalConfig` field in Topic resources. See [Manage Topics in Kubernetes](../../kubernetes/k-manage-topics/). - **Redpanda Console** - Use the web interface to [edit topic configuration](../../../console/ui/edit-topic-configuration/) through a graphical interface. ## [](#verify-topic-property-configuration)Verify topic property configuration Use `rpk topic describe ` to view topic properties and their configuration sources: ```none rpk topic describe my-topic ``` The output shows two sections: ```none SUMMARY ======= NAME my-topic PARTITIONS 3 REPLICAS 3 CONFIGS ======= KEY VALUE SOURCE cleanup.policy delete DEFAULT_CONFIG compression.type producer DEFAULT_CONFIG retention.ms 604800000 DEFAULT_CONFIG write.caching true DYNAMIC_TOPIC_CONFIG ``` The `SOURCE` column indicates how each property is configured: - `DEFAULT_CONFIG` - Redpanda’s default value - `DYNAMIC_TOPIC_CONFIG` - User-configured value The replication factor appears as REPLICAS in the SUMMARY section, not as replication.factor in the CONFIGS list. However, you need to use the `replication.factor` key when modifying the value with `rpk topic alter-config`. For partition-level details, add the `-p` flag: ```none rpk topic describe my-topic -p ``` This shows a different output focused on partition information: ```none PARTITION LEADER EPOCH REPLICAS LOG-START-OFFSET HIGH-WATERMARK 0 1 2 [1 2 3] 0 6 1 2 4 [1 2 3] 0 10 2 3 1 [1 2 3] 0 8 ``` ## [](#examples)Examples The following examples show how to configure topic-level properties. Set a topic-level property for a topic to override the value of corresponding cluster property. ### [](#create-topic-with-topic-properties)Create topic with topic properties To set topic properties when creating a topic, use the [rpk topic create](../../../reference/rpk/rpk-topic/rpk-topic-create/) command with the `-c` option. For example, to create a topic with the `cleanup.policy` property set to `compact`: #### Local ```bash rpk topic create -c cleanup.policy=compact ``` #### Kubernetes ```bash kubectl exec -- rpk topic create -c cleanup.policy=compact ``` To configure multiple properties for a topic, use the `-c` option for each property. For example, to create a topic with all necessary properties for Tiered Storage: #### Local ```bash rpk topic create -c redpanda.remote.recovery=true -c redpanda.remote.write=true -c redpanda.remote.read=true ``` #### Kubernetes ```bash kubectl exec -- rpk topic create -c redpanda.remote.recovery=true -c redpanda.remote.write=true -c redpanda.remote.read=true ``` ### [](#modify-topic-properties)Modify topic properties To modify topic properties of an existing topic, use the [rpk topic alter-config](../../../reference/rpk/rpk-topic/rpk-topic-alter-config/) command. For example, to modify a topic’s `retention.ms` property: #### Local ```bash rpk topic alter-config --set retention.ms= ``` #### Kubernetes ```bash kubectl exec -- rpk topic alter-config --set retention.ms= ``` ### [](#configure-topic-properties-with-kubernetes)Configure topic properties with Kubernetes In Kubernetes deployments, configure topic properties using the `additionalConfig` field in Topic resources: ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Topic metadata: name: example-topic spec: partitions: 3 replicationFactor: 3 additionalConfig: cleanup.policy: "compact" retention.ms: "604800000" segment.ms: "86400000" ``` Apply the configuration: ```bash kubectl apply -f topic-config.yaml ``` ## [](#common-topic-property-categories)Common topic property categories The most commonly configured topic properties fall into these main categories: ### [](#disk-space-management)Disk space management Redpanda manages disk space through two main mechanisms: **compaction** (removing duplicate keys) and **retention** (removing old data). Choose your cleanup strategy with [`cleanup.policy`](../../../reference/properties/topic-properties/#cleanuppolicy): - `delete` - Remove old data based on time or size limits - `compact` - Keep only the latest value for each key - `compact,delete` - Combine both strategies ### [](#compaction)Compaction When using `cleanup.policy=compact` or `cleanup.policy=compact,delete`, configure: - [`min.cleanable.dirty.ratio`](../../../reference/properties/topic-properties/#mincleanabledirtyratio) - Control when compaction triggers based on dirty data ratio - [`max.compaction.lag.ms`](../../../reference/properties/topic-properties/#maxcompactionlagms) - Set maximum time before compaction is forced - [`min.compaction.lag.ms`](../../../reference/properties/topic-properties/#mincompactionlagms) - Set minimum time before compaction can occur ### [](#retention)Retention When using `cleanup.policy=delete` or `cleanup.policy=compact,delete`, configure: - [`retention.bytes`](../../../reference/properties/topic-properties/#retentionbytes) - Maximum size before cleanup (size-based retention) - [`retention.ms`](../../../reference/properties/topic-properties/#retentionms) - Maximum age before cleanup (time-based retention) - [`segment.bytes`](../../../reference/properties/topic-properties/#segmentbytes) - Control how frequently cleanup can occur by setting segment size ### [](#performance)Performance Essential performance tuning properties: - [`write.caching`](../../../reference/properties/topic-properties/#writecaching) - Cache writes for lower latency with `acks=all` - [`max.message.bytes`](../../../reference/properties/topic-properties/#maxmessagebytes) - Set maximum message size - [`replication.factor`](../../../reference/properties/topic-properties/#replicationfactor) - Number of replicas for durability vs. performance For complete details about all available topic properties, see [Topic Configuration Properties](../../../reference/properties/topic-properties/). ## [](#related-topics)Related topics - [Topic Configuration Properties](../../../reference/properties/topic-properties/) - Complete reference of all available topic properties - [Configure Cluster Properties](../cluster-property-configuration/) - Configure cluster-wide defaults - [Manage Topics](../../../develop/manage-topics/config-topics/) - Create and manage topics - [Manage Topics in Kubernetes](../../kubernetes/k-manage-topics/) - Topic management in Kubernetes deployments - [Edit Topic Configuration in Redpanda Console](../../../console/ui/edit-topic-configuration/) - Graphical topic configuration ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Owl Shop Example Application in Docker](/redpanda-labs/docker-compose/owl-shop/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) See more [Search all labs](/redpanda-labs) --- # Page 133: Redpanda Console **URL**: https://docs.redpanda.com/current/manage/console.md --- # Redpanda Console --- title: Redpanda Console latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: console/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: console/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/console/index.adoc description: Learn how to manage Redpanda using Redpanda Console. page-git-created-date: "2023-06-02" page-git-modified-date: "2025-05-23" support-status: supported --- - [Configure Redpanda Console](../../console/config/configure-console/) Learn how to configure Redpanda Console using environment variables, YAML files, or command-line arguments. - [Add a License Key to Redpanda Console](../../console/config/enterprise-license/) Learn how to apply or update a license key to Redpanda Console. - [Configure Redpanda Console to Connect to a Redpanda Cluster](../../console/config/connect-to-redpanda/) Learn how to configure Redpanda Console to connect to a Redpanda cluster and ensure communication with your Redpanda brokers. - [Redpanda Console Security](../../console/config/security/) Learn about security topics for Redpanda Console. - [HTTP Path Rewrites in Redpanda Console](../../console/config/http-path-rewrites/) Learn how to configure Redpanda Console to work with your URL path rewrites, particularly when hosted under a subpath. - [Configure Message Deserialization in Redpanda Console](../../console/config/deserialization/) Learn how to configure Redpanda Console to use Schema Registry, Protobuf files, and other deserialization methods to ensure your data is correctly interpreted and displayed. - [Enable Topic Documentation in Redpanda Console](../../console/config/topic-documentation/) Learn how to embed your Kafka topic documentation into the Redpanda Console UI by linking a Git repository that contains the topic documentation files. - [Redpanda Console Telemetry](../../console/config/analytics/) Learn what telemetry Redpanda Console collects by default, how it is handled, and how to disable it. - [Connect Redpanda Console to Kafka Connect Clusters](../../console/config/kafka-connect/) Learn how to connect one or more Kafka Connect clusters with Redpanda Console. --- # Page 134: Disaster Recovery **URL**: https://docs.redpanda.com/current/manage/disaster-recovery.md --- # Disaster Recovery --- title: Disaster Recovery latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: disaster-recovery/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: disaster-recovery/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/disaster-recovery/index.adoc description: Learn about Shadowing with cross-region replication for disaster recovery. page-git-created-date: "2025-11-19" page-git-modified-date: "2025-11-19" support-status: supported --- - [Shadowing](shadowing/) Set up disaster recovery for Redpanda clusters using Shadowing for cross-region replication. - [Whole Cluster Restore](whole-cluster-restore/) Restore a failed cluster, including its metadata. - [Topic Recovery](topic-recovery/) Restore a single topic from object storage. --- # Page 135: Shadowing **URL**: https://docs.redpanda.com/current/manage/disaster-recovery/shadowing.md --- # Shadowing --- title: Shadowing latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: disaster-recovery/shadowing/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: disaster-recovery/shadowing/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/disaster-recovery/shadowing/index.adoc description: Set up disaster recovery for Redpanda clusters using Shadowing for cross-region replication. page-git-created-date: "2025-11-19" page-git-modified-date: "2025-11-19" support-status: supported --- - [Shadowing Overview](overview/) Learn about disaster recovery using Shadowing for cross-region replication. - [Configure Shadowing](setup/) Set up Shadowing for disaster recovery, including cross-region replication, data filters, networking, and authentication. - [Monitor Shadowing](monitor/) Monitor Shadowing health with status commands, metrics, and best practices for tracking replication performance. - [Failover](failover/) Learn how failover can transform shadow topics into fully writable resources during disasters. - [Failover Runbook](failover-runbook/) Step-by-step emergency guide for failing over Redpanda shadow links during disasters. --- # Page 136: Failover Runbook **URL**: https://docs.redpanda.com/current/manage/disaster-recovery/shadowing/failover-runbook.md --- # Failover Runbook --- title: Failover Runbook latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: disaster-recovery/shadowing/failover-runbook page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: disaster-recovery/shadowing/failover-runbook.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/disaster-recovery/shadowing/failover-runbook.adoc description: Step-by-step emergency guide for failing over Redpanda shadow links during disasters. page-git-created-date: "2025-11-19" page-git-modified-date: "2025-12-16" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../../get-started/licensing/#self-managed) apply. This guide provides step-by-step procedures for emergency failover when your primary Redpanda cluster becomes unavailable. Follow these procedures only during active disasters when immediate failover is required. > 📝 **NOTE** > > If you’re running Redpanda in Kubernetes, see [Kubernetes Failover Runbook](../../../kubernetes/shadowing/k-failover-runbook/) for Kubernetes-specific emergency procedures. > ❗ **IMPORTANT** > > This is an emergency procedure. For planned failover testing or day-to-day shadow link management, see [Failover](../failover/). Ensure you have completed the [disaster readiness checklist](../overview/#disaster-readiness-checklist) before an emergency occurs. ## [](#emergency-failover-procedure)Emergency failover procedure Follow these steps during an active disaster: 1. [Assess the situation](#assess-situation) 2. [Verify shadow cluster status](#verify-shadow-status) 3. [Document current state](#document-state) 4. [Initiate failover](#initiate-failover) 5. [Monitor failover progress](#monitor-progress) 6. [Update application configuration](#update-applications) 7. [Verify application functionality](#verify-functionality) 8. [Clean up and stabilize](#cleanup-stabilize) ### [](#assess-situation)Assess the situation Confirm that failover is necessary: ```bash # Check if the primary cluster is responding rpk cluster info --brokers prod-cluster-1.example.com:9092,prod-cluster-2.example.com:9092 # If primary cluster is down, check shadow cluster health rpk cluster info --brokers shadow-cluster-1.example.com:9092,shadow-cluster-2.example.com:9092 ``` **Decision point**: If the primary cluster is responsive, consider whether failover is actually needed. Partial outages may not require full disaster recovery. **Examples that require full failover:** - Primary cluster is completely unreachable (network partition, regional outage) - Multiple broker failures preventing writes to critical topics - Data center failure affecting majority of brokers - Persistent authentication or authorization failures across the cluster **Examples that may NOT require failover:** - Single broker failure with sufficient replicas remaining - Temporary network connectivity issues affecting some clients - High latency or performance degradation (but cluster still functional) - Non-critical topic or partition unavailability ### [](#verify-shadow-status)Verify shadow cluster status Check the health of your shadow links: ```bash # List all shadow links rpk shadow list # Check the configuration of your shadow link rpk shadow describe # Check the status of your disaster recovery link rpk shadow status ``` For detailed command options, see [`rpk shadow list`](../../../../reference/rpk/rpk-shadow/rpk-shadow-list/), [`rpk shadow describe`](../../../../reference/rpk/rpk-shadow/rpk-shadow-describe/), and [`rpk shadow status`](../../../../reference/rpk/rpk-shadow/rpk-shadow-status/). Verify that the following conditions exist before proceeding with failover: - Shadow link state should be `ACTIVE`. - Topics should be in `ACTIVE` state (not `FAULTED`). - Replication lag should be reasonable for your RPO requirements. #### [](#understanding-replication-lag)Understanding replication lag Use [`rpk shadow status`](../../../../reference/rpk/rpk-shadow/rpk-shadow-status/) or the [Data Plane API](/api/doc/cloud-dataplane/operation/operation-shadowlinkservice_listshadowlinktopics) to check lag, which shows the message count difference between source and shadow partitions: - **Acceptable lag examples**: 0-1000 messages for low-throughput topics, 0-10000 messages for high-throughput topics - **Concerning lag examples**: Growing lag over 50,000 messages, or lag that continuously increases without recovering - **Critical lag examples**: Lag exceeding your data loss tolerance (for example, if you can only afford to lose 1 minute of data, lag should represent less than 1 minute of typical message volume) ### [](#document-state)Document current state Record the current lag and status before proceeding: ```bash # Capture current status for post-mortem analysis rpk shadow status > failover-status-$(date +%Y%m%d-%H%M%S).log ``` The partition information shows the following: | Field | Description | | --- | --- | | SRC_LSO | Source partition last stable offset | | SRC_HWM | Source partition high watermark | | DST_HWM | Shadow (destination) partition high watermark | | Lag | Message count difference between source and shadow partitions | > ❗ **IMPORTANT** > > Note the replication lag to estimate potential data loss during failover. The `Tasks` section shows the health of shadow link replication tasks. For details about what each task does, see [Shadow link tasks](../overview/#shadow-link-tasks). ### [](#initiate-failover)Initiate failover A complete cluster failover is appropriate If you observe that the source cluster is no longer reachable: ```bash # Fail over all topics in the shadow link rpk shadow failover --all ``` For detailed command options, see [`rpk shadow failover`](../../../../reference/rpk/rpk-shadow/rpk-shadow-failover/). For selective topic failover (when only specific services are affected): ```bash # Fail over individual topics rpk shadow failover --topic rpk shadow failover --topic ``` ### [](#monitor-progress)Monitor failover progress Track the failover process: ```bash # Monitor status until all topics show FAILED_OVER watch -n 5 "rpk shadow status " # Check detailed topic status and lag during emergency rpk shadow status --print-topic ``` Example output during successful failover: shadow link: Overview: NAME UID STATE ACTIVE Tasks: Name Broker\_ID State Reason 1 ACTIVE 2 ACTIVE Topics: Name: , State: FAILED\_OVER Name: , State: FAILED\_OVER Name: , State: FAILING\_OVER **Wait for**: All critical topics to reach `FAILED_OVER` state before proceeding. ### [](#update-applications)Update application configuration Redirect your applications to the shadow cluster by updating connection strings in your applications to point to shadow cluster brokers. If using DNS-based service discovery, update DNS records accordingly. Restart applications to pick up new connection settings and verify connectivity from application hosts to shadow cluster. ### [](#verify-functionality)Verify application functionality Test critical application workflows: ```bash # Verify applications can produce messages rpk topic produce --brokers :9092 # Verify applications can consume messages rpk topic consume --brokers :9092 --num 1 ``` Test message production and consumption, consumer group functionality, and critical business workflows to ensure everything is working properly. ### [](#cleanup-stabilize)Clean up and stabilize After all applications are running normally: ```bash # Optional: Delete the shadow link (no longer needed) rpk shadow delete ``` For detailed command options, see [`rpk shadow delete`](../../../../reference/rpk/rpk-shadow/rpk-shadow-delete/). > 📝 **NOTE** > > This operation [force deletes](#force-delete-warning) the shadow link. Document the time of failover initiation and completion, applications affected and recovery times, data loss estimates based on replication lag, and issues encountered during failover. ## [](#troubleshoot-common-issues)Troubleshoot common issues ### [](#topics-stuck-in-failing_over-state)Topics stuck in FAILING\_OVER state **Problem**: Topics remain in `FAILING_OVER` state for extended periods **Solution**: Check shadow cluster logs for specific error messages and ensure sufficient cluster resources (CPU, memory, disk space) are available on the shadow cluster. Verify network connectivity between shadow cluster nodes and confirm that all shadow topic partitions have elected leaders and the controller partition is properly replicated with an active leader. If topics remain stuck after addressing these cluster health issues and you need immediate failover, you can force delete the shadow link to failover all topics: ```bash # Force delete the shadow link to failover all topics rpk shadow delete --force ``` > ⚠️ **WARNING** > > Force deleting a shadow link immediately fails over all topics in the link. This action is irreversible and should only be used when topics are stuck and you need immediate access to all replicated data. ### [](#topics-in-faulted-state)Topics in FAULTED state **Problem**: Topics show `FAULTED` state and are not replicating **Solution**: Check for authentication issues, network connectivity problems, or source cluster unavailability. Verify that the shadow link service account still has the required permissions on the source cluster. Review shadow cluster logs for specific error messages about the faulted topics. ### [](#application-connection-failures)Application connection failures **Problem**: Applications cannot connect to shadow cluster after failover **Solution**: Verify shadow cluster broker endpoints are correct and check security group and firewall rules. Confirm authentication credentials are valid for the shadow cluster and test network connectivity from application hosts. ### [](#consumer-group-offset-issues)Consumer group offset issues **Problem**: Consumers start from beginning or wrong positions **Solution**: Verify consumer group offsets were replicated (check your filters) and use `rpk group describe ` to check offset positions. If necessary, manually reset offsets to appropriate positions. See [How to manage consumer group offsets in Redpanda](https://support.redpanda.com/hc/en-us/articles/23499121317399-How-to-manage-consumer-group-offsets-in-Redpanda) for detailed reset procedures. ## [](#next-steps)Next steps After successful failover, focus on recovery planning and process improvement. Begin by assessing the source cluster failure and determining whether to restore the original cluster or permanently promote the shadow cluster as your new primary. **Immediate recovery planning:** 1. **Assess source cluster**: Determine root cause of the outage 2. **Plan recovery**: Decide whether to restore source cluster or promote shadow cluster permanently 3. **Data synchronization**: Plan how to synchronize any data produced during failover 4. **Fail forward**: Create a new shadow link with the failed over shadow cluster as source to maintain a DR cluster **Process improvement:** 1. **Document the incident**: Record timeline, impact, and lessons learned 2. **Update runbooks**: Improve procedures based on what you learned 3. **Test regularly**: Schedule regular disaster recovery drills 4. **Review monitoring**: Ensure monitoring caught the issue appropriately --- # Page 137: Failover **URL**: https://docs.redpanda.com/current/manage/disaster-recovery/shadowing/failover.md --- # Failover --- title: Failover latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: disaster-recovery/shadowing/failover page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: disaster-recovery/shadowing/failover.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/disaster-recovery/shadowing/failover.adoc description: Learn how failover can transform shadow topics into fully writable resources during disasters. page-git-created-date: "2025-11-19" page-git-modified-date: "2025-12-16" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../../get-started/licensing/#self-managed) apply. Failover is the process of modifying shadow topics or an entire shadow cluster from read-only replicas to fully writable resources, and ceasing replication from the source cluster. You can fail over individual topics for selective workload migration or fail over the entire cluster for comprehensive disaster recovery. This critical operation transforms your shadow resources into operational production assets, allowing you to redirect application traffic when the source cluster becomes unavailable. You can failover a shadow link using Redpanda Console, `rpk`, or the Admin API. > 📝 **NOTE** > > If you are using Kubernetes, you can also use the Redpanda Operator’s `ShadowLink` resource to manage failover. See [Kubernetes Shadow Link Failover](../../../kubernetes/shadowing/k-failover-runbook/) for details. > ❗ **IMPORTANT: Experiencing an active disaster?** > > See [Failover Runbook](../failover-runbook/) for immediate step-by-step disaster procedures. ## [](#failover-behavior)Failover behavior When you initiate failover, Redpanda performs the following operations: 1. **Stops replication**: Halts all data fetching from the source cluster for the specified topics or entire shadow link 2. **Failover topics**: Converts read-only shadow topics into regular, writable topics 3. **Updates topic state**: Changes topic status from `ACTIVE` to `FAILING_OVER`, then `FAILED_OVER` Topic failover is irreversible. Once failed over, topics cannot return to shadow mode, and automatic fallback to the original source cluster is not supported. > 📝 **NOTE** > > To avoid a split-brain scenario after failover, ensure that all clients are reconfigured to point to the shadow cluster before resuming write activity. ## [](#failover-commands)Failover commands You can perform failover at different levels of granularity to match your disaster recovery needs: ### [](#individual-topic-failover)Individual topic failover To fail over a specific shadow topic while leaving other topics in the shadow link still replicating, run: ```bash rpk shadow failover --topic ``` For detailed command options, see [`rpk shadow failover`](../../../../reference/rpk/rpk-shadow/rpk-shadow-failover/). Use this approach when you need to selectively failover specific workloads or when testing failover procedures. ### [](#complete-shadow-link-failover-cluster-failover)Complete shadow link failover (cluster failover) To fail over all shadow topics associated with the shadow link simultaneously, run: ```bash rpk shadow failover --all ``` Use this approach during a complete regional disaster when you need to activate the entire shadow cluster as your new production environment. ### [](#force-delete-shadow-link-emergency-failover)Force delete shadow link (emergency failover) ```bash rpk shadow delete --force ``` > ⚠️ **WARNING** > > Force deleting a shadow link is irreversible and immediately fails over all topics in the link, bypassing the normal failover state transitions. This action should only be used as a last resort when topics are stuck in transitional states and you need immediate access to all replicated data. ## [](#failover-states)Failover states ### [](#shadow-link-states)Shadow link states The shadow link itself has a simple state model: - **`ACTIVE`**: Shadow link is operating normally, replicating data - **`PAUSED`**: Shadow link replication is temporarily halted by user action Shadow links do not have dedicated failover states. Instead, the link’s operational status is determined by the collective state of its shadow topics. ### [](#shadow-topic-states)Shadow topic states Individual shadow topics progress through specific states during failover: - **`ACTIVE`**: Normal replication state before failover - **`FAULTED`**: Shadow topic has encountered an error and is not replicating - **`FAILING_OVER`**: Failover initiated, replication stopping - **`FAILED_OVER`**: Failover completed successfully, topic fully writable - **`PAUSED`**: Replication temporarily halted by user action ## [](#monitor-failover-progress)Monitor failover progress To monitor failover progress using the status command, run: ```bash rpk shadow status ``` The output shows individual topic states and any issues encountered during the failover process. For detailed command options, see [`rpk shadow status`](../../../../reference/rpk/rpk-shadow/rpk-shadow-status/). Task states during monitoring: - **`ACTIVE`**: Task is operating normally and replicating data - **`FAULTED`**: Task encountered an error and requires attention - **`NOT_RUNNING`**: Task is not currently executing - **`LINK_UNAVAILABLE`**: Task cannot communicate with the source cluster For detailed information about shadow link tasks and their roles, see [Shadow link tasks](../overview/#shadow-link-tasks). ## [](#post-failover-cluster-behavior)Post-failover cluster behavior After successful failover, your shadow cluster exhibits the following characteristics: **Topic accessibility:** - Failed over topics become fully writable and readable. - Applications can produce and consume messages normally. - All Kafka APIs are available for failedover topics. - Original offsets and timestamps are preserved. **Shadow link status:** - The shadow link remains but stops replicating data. - Link status shows topics in `FAILED_OVER` state. - You can safely delete the shadow link after successful failover. **Operational limitations:** - No automatic fallback mechanism to the original source cluster. - Data transforms remain disabled until you manually re-enable them. - Audit log history from the source cluster is not available (new audit logs begin immediately). ## [](#failover-considerations-and-limitations)Failover considerations and limitations Before implementing failover procedures, understand these key considerations that affect your disaster recovery strategy and operational planning. **Data consistency:** - Some data loss may occur due to replication lag at the time of failover. - Consumer group offsets are preserved, allowing applications to resume from their last committed position. - In-flight transactions at the source cluster are not replicated and will be lost. **Recovery-point-objective (RPO):** The amount of potential data loss depends on replication lag when disaster occurs. Monitor lag metrics to understand your effective RPO. **Network partitions:** If the source cluster becomes accessible again after failover, do not attempt to write to both clusters simultaneously. This creates a scenario with potential data inconsistencies, since metadata starts to diverge. **Testing requirements:** Regularly test failover procedures in non-production environments to validate your disaster recovery processes and measure RTO. ## [](#next-steps)Next steps After completing failover: - Update your application connection strings to point to the shadow cluster - Verify that applications can produce and consume messages normally - Consider deleting the shadow link if failover was successful and permanent For emergency situations, see [Failover Runbook](../failover-runbook/). --- # Page 138: Monitor Shadowing **URL**: https://docs.redpanda.com/current/manage/disaster-recovery/shadowing/monitor.md --- # Monitor Shadowing --- title: Monitor Shadowing latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: disaster-recovery/shadowing/monitor page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: disaster-recovery/shadowing/monitor.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/disaster-recovery/shadowing/monitor.adoc description: Monitor Shadowing health with status commands, metrics, and best practices for tracking replication performance. page-git-created-date: "2025-11-19" page-git-modified-date: "2026-01-06" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../../get-started/licensing/#self-managed) apply. Monitor your [shadow links](../setup/) to ensure proper replication performance and understand your disaster recovery readiness. Use `rpk` commands, metrics, and status information to track shadow link health and troubleshoot issues. > 📝 **NOTE** > > If you’re running Redpanda in Kubernetes, see [Monitor Kubernetes Shadow Links](../../../kubernetes/shadowing/k-monitor-shadowing/). > ❗ **IMPORTANT: Experiencing an active disaster?** > > See [Failover Runbook](../failover-runbook/) for immediate step-by-step disaster procedures. ## [](#status-commands)Status commands To list existing shadow links: ```bash rpk shadow list ``` To view shadow link configuration details: ```bash rpk shadow describe ``` For detailed command options, see [`rpk shadow list`](../../../../reference/rpk/rpk-shadow/rpk-shadow-list/) and [`rpk shadow describe`](../../../../reference/rpk/rpk-shadow/rpk-shadow-describe/). This command shows the complete configuration of the shadow link, including connection settings, filters, and synchronization options. To check your shadow link status and ensure proper operation: ```bash rpk shadow status ``` - **Shadow link state**: Overall operational state (`ACTIVE`, `PAUSED`). - **Individual topic states**: Current state of each replicated topic (`ACTIVE`, `FAULTED`, `FAILING_OVER`, `FAILED_OVER`, `PAUSED`). - **Task status**: Health of replication tasks across brokers (`ACTIVE`, `FAULTED`, `NOT_RUNNING`, `LINK_UNAVAILABLE`). For details about shadow link tasks, see [Shadow link tasks](../overview/#shadow-link-tasks). - **Lag information**: Replication lag per partition showing source vs shadow high watermarks (HWM). ## [](#shadow-link-metrics)Metrics Shadowing provides comprehensive metrics to track replication performance and health with the [`public_metrics`](../../../../reference/public-metrics-reference/) endpoint. | Metric | Type | Description | | --- | --- | --- | | redpanda_shadow_link_shadow_lag | Gauge | The lag of the shadow partition against the source partition, calculated as source partition LSO (Last Stable Offset) minus shadow partition HWM (High Watermark). Monitor by shadow_link_name, topic, and partition to understand replication lag for each partition. | | redpanda_shadow_link_total_bytes_fetched | Count | The total number of bytes fetched by a sharded replicator (bytes received by the client). Labeled by shadow_link_name and shard to track data transfer volume from the source cluster. | | redpanda_shadow_link_total_bytes_written | Count | The total number of bytes written by a sharded replicator (bytes written to the write_at_offset_stm). Uses shadow_link_name and shard labels to monitor data written to the shadow cluster. | | redpanda_shadow_link_client_errors | Count | The number of errors seen by the client. Track by shadow_link_name and shard to identify connection or protocol issues between clusters. | | redpanda_shadow_link_shadow_topic_state | Gauge | Number of shadow topics in the respective states. Labeled by shadow_link_name and state to monitor topic state distribution across your shadow links. | | redpanda_shadow_link_total_records_fetched | Count | The total number of records fetched by the sharded replicator (records received by the client). Monitor by shadow_link_name and shard to track message throughput from the source. | | redpanda_shadow_link_total_records_written | Count | The total number of records written by a sharded replicator (records written to the write_at_offset_stm). Uses shadow_link_name and shard labels to monitor message throughput to the shadow cluster. | See also: [Public Metrics](../../../../reference/public-metrics-reference/) ## [](#monitoring-best-practices)Monitoring best practices ### [](#health-check-procedures)Health check procedures Establish regular monitoring workflows to ensure shadow link health: ```bash # Check all shadow links are active rpk shadow list | grep -v "ACTIVE" || echo "All shadow links healthy" # Monitor lag for critical topics rpk shadow status | grep -E "LAG|Lag" ``` ### [](#alert-conditions)Alert conditions Configure monitoring alerts for the following conditions, which indicate problems with Shadowing: - **High replication lag**: When `redpanda_shadow_link_shadow_lag` exceeds your RPO requirements - **Connection errors**: When `redpanda_shadow_link_client_errors` increases rapidly - **Topic state changes**: When topics move to `FAULTED` state - **Task failures**: When replication tasks enter `FAULTED` or `NOT_RUNNING` states - **Throughput drops**: When bytes/records fetched drops significantly - **Link unavailability**: When tasks show `LINK_UNAVAILABLE` indicating source cluster connectivity issues For more information about shadow link tasks and their states, see [Shadow link tasks](../overview/#shadow-link-tasks). --- # Page 139: Shadowing Overview **URL**: https://docs.redpanda.com/current/manage/disaster-recovery/shadowing/overview.md --- # Shadowing Overview --- title: Shadowing Overview latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: disaster-recovery/shadowing/overview page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: disaster-recovery/shadowing/overview.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/disaster-recovery/shadowing/overview.adoc description: Learn about disaster recovery using Shadowing for cross-region replication. page-git-created-date: "2025-11-19" page-git-modified-date: "2026-04-08" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../../get-started/licensing/#self-managed) apply. Shadowing is Redpanda’s enterprise-grade disaster recovery solution that establishes asynchronous, offset-preserving replication between two distinct Redpanda clusters. A cluster is able to create a dedicated client that continuously replicates source cluster data, including offsets, timestamps, and cluster metadata. This creates a read-only shadow cluster that you can quickly failover to handle production traffic during a disaster. Shadowing keeps data flowing, even during regional outages. > ❗ **IMPORTANT: Experiencing an active disaster?** > > See [Failover Runbook](../failover-runbook/) for immediate step-by-step disaster procedures. Unlike traditional replication tools that re-produce messages, Shadowing copies data at the byte level, ensuring shadow topics contain identical copies of source topics with preserved offsets and timestamps. Shadowing replicates: - **Topic data**: All records with preserved offsets and timestamps - **Topic configurations**: Partition counts, retention policies, and other topic properties - **Consumer group offsets**: Enables seamless consumer resumption after failover - **Access control lists (ACLs)**: User permissions and security policies - **Schema Registry data**: Schema definitions and compatibility settings ## [](#how-shadowing-fits-into-disaster-recovery)How Shadowing fits into disaster recovery Shadowing addresses enterprise disaster recovery requirements driven by regulatory compliance and business continuity needs. Organizations typically want to minimize both recovery time objective (RTO) and recovery point objective (RPO), and Shadowing asynchronous replication helps you achieve both goals by reducing data loss during regional outages and enabling rapid application recovery. The architecture follows an active-passive pattern. The source cluster processes all production traffic while the shadow cluster remains in read-only mode, continuously receiving updates. If a disaster occurs, you can failover the shadow topics, making them fully writable. At that point, you can redirect your applications to the shadow cluster, which becomes the new production cluster. > 📝 **NOTE** > > To avoid a split-brain scenario after failover, ensure that all clients are reconfigured to point to the shadow cluster before resuming write activity. Shadowing complements Redpanda’s existing availability and recovery capabilities. [High availability](../../../high-availability/) actively protects your day-to-day operations, handling reads and writes seamlessly during node or availability zone failures within a region. Shadowing is your safety net for catastrophic regional disasters. While [Whole Cluster Restore](../../whole-cluster-restore/) provides point-in-time recovery from [Tiered Storage](../../../tiered-storage/), Shadowing delivers near real-time, cross-region replication for mission-critical applications that require rapid failover with minimal data loss. ## [](#limitations)Limitations Shadowing for disaster recovery currently has the following limitations: - Shadowing is designed for active-passive disaster recovery scenarios. Each shadow cluster can maintain only one shadow link. - Shadowing operates exclusively in asynchronous mode and doesn’t support active-active configurations. This means there will always be some replication lag. - [Data transforms](../../../../develop/data-transforms/) are not supported on shadow clusters while Shadowing is active. Writing to shadow topics is blocked. - During a disaster, [audit log](../../../audit-logging/) history from the source cluster is lost, though the shadow cluster begins generating new audit logs immediately after the failover. - After you failover shadow topics, automatic fallback to the original source cluster is not supported. ## [](#shadow-link-tasks)Shadow link tasks Shadow linking operates through specialized tasks that handle different aspects of replication. If you use a `shadow-config.yaml` configuration file to create the shadow link, each task corresponds to a section in the file. Tasks run continuously to maintain synchronization with the source cluster. #### Source Topic Sync The **Source Topic Sync task** manages topic discovery and metadata synchronization. This task periodically queries the source cluster to discover available topics, applies your configured topic filters to determine which topics should become shadow topics, and synchronizes topic properties between clusters. The task is controlled by the `topic_metadata_sync_options` section in the configuration file. It includes: - **Auto-creation filters**: Determines which source topics automatically become shadow topics - **Property synchronization**: Controls which topic properties replicate from source to shadow - **Starting offset**: Sets where new shadow topics begin replication (earliest, latest, or timestamp-based) - **Sync interval**: How frequently to check for new topics and property changes When this task discovers a new topic that matches your filters, it creates the corresponding shadow topic and begins replication from your configured starting offset. #### Consumer Group Shadowing The **Consumer Group Shadowing task** replicates consumer group offsets and membership information from the source cluster. This ensures that consumer applications can resume processing from the correct position after failover. The task is controlled by the `consumer_offset_sync_options` section in the configuration file. It includes: - **Group filters**: Determines which consumer groups have their offsets replicated - **Sync interval**: How frequently to synchronize consumer group offsets - **Offset clamping**: Automatically adjusts replicated offsets to valid ranges on the shadow cluster This task runs on brokers that host the `__consumer_offsets` topic and continuously tracks consumer group coordinators to optimize offset synchronization. #### Security Migrator The **Security Migrator task** replicates security policies, primarily ACLs (access control lists), from the source cluster to maintain consistent authorization across both environments. The task is controlled by the `security_sync_options` section in the configuration file. It includes: - **ACL filters**: Determines which security policies replicate - **Sync interval**: How frequently to synchronize security settings By default, all ACLs replicate to ensure your shadow cluster maintains the same security posture as your source cluster. ### [](#task-status-and-monitoring)Task status and monitoring Each task reports its status through the shadow link status API. Task states include: - **`ACTIVE`**: Task is running normally and performing synchronization - **`PAUSED`**: Task has been manually paused through configuration - **`FAULTED`**: Task encountered an error and requires attention - **`NOT_RUNNING`**: Task is not currently executing - **`LINK_UNAVAILABLE`**: Task cannot communicate with the source cluster You can pause individual tasks by setting the `paused` field to `true` in the corresponding configuration section. This allows you to selectively disable parts of the replication process without affecting the entire shadow link. For monitoring task health and troubleshooting task issues, see [Monitor Shadowing](../monitor/). ## [](#what-gets-replicated)What gets replicated Shadowing replicates your topic data with complete fidelity, preserving all message records with their original offsets, timestamps, headers, and metadata. The partition structure remains identical between source and shadow clusters, ensuring applications can resume processing from the exact same position after failover. Consumer group data flows according to your group filters, replicating offsets and membership information for matched groups. ACLs replicate based on your security filters. Schema Registry data synchronizes schema definitions, versions, and compatibility settings. Partition count is always replicated to ensure the shadow topic matches the source topic’s partition structure. ### [](#topic-properties-replication)Topic properties replication The [Source Topic Sync task](#shadow-link-tasks) handles topic property replication. For topic properties, Redpanda follows these replication rules: **Never replicated** - `redpanda.remote.readreplica` - `redpanda.remote.recovery` - `redpanda.remote.allowgaps` - `redpanda.virtual.cluster.id` - `redpanda.leaders.preference` - `redpanda.cloud_topic.enabled` **Always replicated** - `max.message.bytes` - `cleanup.policy` - `message.timestamp.type` **Always replicated (unless `exclude_default` is `true`)** - `compression.type` - `retention.bytes` - `retention.ms` - `delete.retention.ms` - `replication.factor` - `min.compaction.lag.ms` - `max.compaction.lag.ms` To replicate additional topic properties, explicitly list them in `synced_shadow_topic_properties`. The filtering system you configure determines the precise scope of replication across all components, allowing you to balance comprehensive disaster recovery with operational efficiency. ## [](#best-practices)Best practices To ensure reliable disaster recovery with Shadowing: - **Avoid write caching on source topics**: Do not shadow source topics that have [write caching](../../../../develop/manage-topics/config-topics/#configure-write-caching) enabled. Write caching can result in data loss on the source cluster during broker resets, causing cluster divergence if shadow links replicate data before it’s lost on the source. - **Do not modify shadow topic properties**: Avoid modifying synced topic properties on shadow topics, as these properties automatically revert to source topic values. ## [](#implementation-overview)Implementation overview Choose your implementation approach: - **[Setup and Configuration](../setup/)**: Initial shadow configuration, authentication, and topic selection - **[Monitoring and Operations](../monitor/)**: Health checks, lag monitoring, and operational procedures - **[Planned Failover](../failover/)**: Controlled disaster recovery testing and migrations - **[Failover Runbook](../failover-runbook/)**: Rapid disaster response procedures > 💡 **TIP** > > You can create and manage shadow links with the [Redpanda Console](../../../../console/), the [Admin API v2](https://docs.redpanda.com/api/doc/admin/v2/), or [`rpk`](../../../../get-started/rpk/), giving you flexibility in how you interact with your disaster recovery infrastructure. ## [](#next-steps)Next steps After setting up Shadowing for your Redpanda clusters, consider these additional steps: - **Test your disaster recovery procedures**: Regularly practice failover scenarios in a non-production environment. See [Failover Runbook](../failover-runbook/) for step-by-step disaster procedures. - **Monitor shadow link health**: Set up alerting on the metrics described above to ensure early detection of replication issues. - **Implement automated failover**: Consider developing automation scripts that can detect outages and initiate failover based on predefined criteria. - **Review security policies**: Ensure your ACL filters replicate the appropriate security settings for your disaster recovery environment. - **Document your configuration**: Maintain up-to-date documentation of your shadow link configuration, including network settings, authentication details, and filter definitions. --- # Page 140: Configure Shadowing **URL**: https://docs.redpanda.com/current/manage/disaster-recovery/shadowing/setup.md --- # Configure Shadowing --- title: Configure Shadowing latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: disaster-recovery/shadowing/setup page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: disaster-recovery/shadowing/setup.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/disaster-recovery/shadowing/setup.adoc description: Set up Shadowing for disaster recovery, including cross-region replication, data filters, networking, and authentication. page-git-created-date: "2025-11-19" page-git-modified-date: "2026-01-14" support-status: supported --- You can create and manage shadow links with the [Redpanda Console](../../../../console/), the [Admin API v2](https://docs.redpanda.com/api/doc/admin/v2/), or [`rpk`](../../../../get-started/rpk/), giving you flexibility in how you interact with your disaster recovery infrastructure. > 💡 **TIP** > > Deploy clusters in different geographic regions to protect against regional disasters. If you’re using Kubernetes, see [Configure Shadowing in Kubernetes](../../../kubernetes/shadowing/k-shadow-linking/) for Kubernetes-specific shadow link configuration. ## [](#prerequisites)Prerequisites > 📝 **NOTE** > > This feature requires an [enterprise license](../../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../../get-started/licensing/#self-managed) apply. ### [](#license-and-cluster-requirements)License and cluster requirements - Both clusters must be running Redpanda v25.3 or later. - If you use Redpanda Console, ensure that it is running v3.30 or later. - You must have [Enterprise Edition](../../../../get-started/licensing/overview/) licenses on both clusters. ### [](#cluster-configuration)Cluster configuration The shadow cluster must have the [`enable_shadow_linking`](../../../../reference/properties/cluster-properties/#enable_shadow_linking) cluster property set to `true`. To enable this property, run: ```bash rpk cluster config set enable_shadow_linking true ``` > 📝 **NOTE** > > This cluster property must be configured using `rpk` or the Admin API v1 before you can create shadow links through any interface. To learn more about configuring cluster properties, see [Configure Cluster Properties](../../../cluster-maintenance/cluster-property-configuration/). ### [](#administrative-access)Administrative access Superuser access is required on both clusters through [`rpk`](../../../../get-started/rpk/), the Admin API, or [Redpanda Console](../../../../console/) to create and manage shadow links. ### [](#replication-service-permissions)Replication service permissions You must configure a service account on the source cluster with the following [ACL](../../../security/authorization/acl/) permissions for shadow link replication: - **Topics**: `read` permission on all topics you want to replicate - **Topic configurations**: `describe_configs` permission on topics for configuration synchronization - **Consumer groups**: `describe` and `read` permission on consumer groups for offset replication - **ACLs**: `describe` permission on ACL resources to replicate security policies - **Cluster**: `describe` permission on the cluster resource to access ACLs This service account authenticates from the shadow cluster to the source cluster and performs the actual data replication. The credentials for this account are provided when you set up the shadow link. ### [](#network-and-authentication)Network and authentication You must configure network connectivity between clusters with appropriate firewall rules to allow the shadow cluster to connect to the source cluster for data replication. Shadowing uses a pull-based architecture where the shadow cluster fetches data from the source cluster. For detailed networking configuration, see [Networking](#networking). If using [authentication](../../../security/authentication/) for the shadow link connection, configure the source cluster with your chosen authentication method (SASL/SCRAM, SASL/PLAIN, TLS, mTLS) and ensure the shadow cluster has the proper credentials to authenticate to the source cluster. ## [](#set-up-shadowing)Set up Shadowing To set up Shadowing, you need to create a shadow link and configure filters to select which topics, consumer groups, ACLs, and Schema Registry data to replicate. ### [](#create-a-shadow-link)Create a shadow link Any cluster can create a shadow link to a source cluster. > 💡 **TIP** > > You can use `rpk` to generate a sample configuration file with common filter patterns: > > ```bash > # Generate a sample configuration file with placeholder values > rpk shadow config generate -o shadow-config.yaml > > # Or generate a template with detailed field documentation > rpk shadow config generate --print-template -o shadow-config-template.yaml > ``` > > This creates a complete YAML configuration file that you can customize for your environment. The template includes all available fields with comments explaining their purpose. For detailed command options, see [`rpk shadow config generate`](../../../../reference/rpk/rpk-shadow/rpk-shadow-config-generate/). Explore the configuration file ```yaml # Sample ShadowLinkConfig YAML with all fields name: # Unique name for this shadow link, example: "production-dr" client_options: bootstrap_servers: # Source cluster brokers to connect to - : # Example: "prod-kafka-1.example.com:9092" - : # Example: "prod-kafka-2.example.com:9092" - : # Example: "prod-kafka-3.example.com:9092" source_cluster_id: # Optional: UUID assigned by Redpanda # Example: a882bc98-7aca-40f6-a657-36a0b4daf1fd # To get source_cluster_id, run `rpk cluster config get cluster_id`. # TLS settings using file paths tls_settings: enabled: true # Enable TLS tls_file_settings: ca_path: # Path to CA certificate, example: "/etc/ssl/certs/ca.crt" key_path: # Optional: Path to client private key, example: "/etc/ssl/private/client.key" cert_path: # Optional: Path to client certificate, example: "/etc/ssl/certs/client.crt" do_not_set_sni_hostname: false # Optional: Skip SNI hostname when using TLS (default: false) # Create SASL credentials in the source cluster. # Then, with this configuration, ensure the shadow cluster uses the credentials # to authenticate to the source cluster. authentication_configuration: # SASL/SCRAM authentication scram_configuration: username: # SASL/SCRAM username, example: "shadow-replication-user" password: # SASL/SCRAM password, example: "secure-password-123" scram_mechanism: SCRAM_SHA_256 # SCRAM mechanism: "SCRAM_SHA_256" or "SCRAM_SHA_512" # SASL/PLAIN authentication plain_configuration: username: # SASL/PLAIN username, example: "shadow-replication-user" password: # SASL/PLAIN password, example: "secure-password-123" # Connection tuning - adjust based on network characteristics metadata_max_age_ms: 10000 # How often to refresh cluster metadata (default: 10000ms) connection_timeout_ms: 1000 # Connection timeout (default: 1000ms, increase for high latency) retry_backoff_ms: 100 # Backoff between retries (default: 100ms) fetch_wait_max_ms: 500 # Max time to wait for fetch requests (default: 500ms) fetch_min_bytes: 5242880 # Min bytes per fetch (default: 5MB) fetch_max_bytes: 20971520 # Max bytes per fetch (default: 20MB) fetch_partition_max_bytes: 1048576 # Max bytes per partition fetch (default: 1MB) topic_metadata_sync_options: interval: 30s # How often to sync topic metadata (examples: "30s", "1m", "5m") auto_create_shadow_topic_filters: # Filters for automatic topic creation - pattern_type: LITERAL # Include all topics (wildcard) filter_type: INCLUDE name: '*' - pattern_type: PREFIX # Exclude topics with specific prefix filter_type: EXCLUDE name: # Examples: "temp-", "test-", "debug-" synced_shadow_topic_properties: # Additional topic properties to sync (beyond defaults) - retention.ms # Topic retention time - segment.ms # Segment roll time exclude_default: false # Include default properties (compression, retention, etc.) start_at_earliest: {} # Start from the beginning of source topics (default) paused: false # Enable topic metadata synchronization consumer_offset_sync_options: interval: 30s # How often to sync consumer group offsets paused: false # Enable consumer offset synchronization group_filters: # Filters for consumer groups to sync - pattern_type: LITERAL filter_type: INCLUDE name: '*' # Include all consumer groups security_sync_options: interval: 30s # How often to sync security settings paused: false # Enable security settings synchronization acl_filters: # Filters for ACLs to sync - resource_filter: resource_type: TOPIC # Resource type: "TOPIC", "GROUP", "CLUSTER" pattern_type: PREFIXED # Pattern type: "LITERAL", "PREFIXED" name: # Examples: "prod-", "app-data-" access_filter: principal: User: # Principal name, example: "User:app-service" operation: ANY # Operation: "READ", "WRITE", "CREATE", "DELETE", "ALTER", "DESCRIBE", "ANY" permission_type: ALLOW # Permission: "ALLOW" or "DENY" host: '*' # Host pattern, examples: "*", "10.0.0.0/8", "app-server.example.com" schema_registry_sync_options: # Schema Registry synchronization options shadow_schema_registry_topic: {} # Enable byte-for-byte _schemas topic replication ``` To create a shadow link with the source cluster using `rpk`, run the following command from the shadow cluster: ```bash # Use the generated configuration file to create the shadow link rpk shadow create --config-file shadow-config.yaml ``` For detailed command options, see [`rpk shadow create`](../../../../reference/rpk/rpk-shadow/rpk-shadow-create/). > 💡 **TIP** > > Use [`rpk profile`](../../../../get-started/config-rpk-profile/) to save your cluster connection details and credentials for both source and shadow clusters. This allows you to easily switch between the two configurations. ### [](#set-filters)Set filters Filters determine which resources Shadowing automatically creates when establishing your shadow link. Topic filters select which topics Shadowing automatically creates as shadow topics when they appear on the source cluster. After Shadowing creates a shadow topic, it continues replicating until you failover the topic, delete it, or delete the entire shadow link. Consumer group and ACL filters control which groups and security policies replicate to maintain application functionality. #### [](#filter-types-and-patterns)Filter types and patterns Each filter uses two key settings: - **Pattern type**: Determines how names are matched - `LITERAL`: Matches names exactly (including the special wildcard `*` to match all items) - `PREFIX`: Matches names that start with the specified string - **Filter type**: Specifies whether to INCLUDE or EXCLUDE matching items - `INCLUDE`: Replicate items that match the pattern - `EXCLUDE`: Skip items that match the pattern #### [](#filter-processing-rules)Filter processing rules Redpanda processes filters in the order you define them with EXCLUDE filters taking precedence. Design your filter lists carefully: 1. **Exclude filters win**: If any EXCLUDE filter matches a resource, it is excluded regardless of INCLUDE filters. 2. **Order matters for INCLUDE filters**: Among INCLUDE filters, the first match determines the result. 3. **Default behavior**: Items that don’t match any filter are excluded from replication. #### [](#common-filtering-patterns)Common filtering patterns Replicate all topics except test topics: ```yaml topic_metadata_sync_options: auto_create_shadow_topic_filters: - pattern_type: PREFIX filter_type: EXCLUDE name: test- # Exclude all test topics - pattern_type: LITERAL filter_type: INCLUDE name: '*' # Include all other topics ``` Replicate only production topics: ```yaml topic_metadata_sync_options: auto_create_shadow_topic_filters: - pattern_type: PREFIX filter_type: INCLUDE name: prod- # Include production topics - pattern_type: PREFIX filter_type: INCLUDE name: production- # Alternative production prefix ``` Replicate specific consumer groups: ```yaml consumer_offset_sync_options: group_filters: - pattern_type: LITERAL filter_type: INCLUDE name: critical-app-consumers # Include specific consumer group - pattern_type: PREFIX filter_type: INCLUDE name: prod-consumer- # Include production consumers ``` #### [](#schema-registry-synchronization)Schema Registry synchronization Shadowing can replicate Schema Registry data by shadowing the `_schemas` system topic. When enabled, this provides byte-for-byte replication of schema definitions, versions, and compatibility settings. To enable Schema Registry synchronization, add the following to your shadow link configuration: ```yaml schema_registry_sync_options: shadow_schema_registry_topic: {} ``` Requirements: - The `_schemas` topic must exist on the source cluster - The `_schemas` topic must not exist on the shadow cluster, or must be empty - Once enabled, the `_schemas` topic will be replicated completely Important: After the `_schemas` topic becomes a shadow topic, it cannot be stopped without either failing over the topic or deleting it entirely. #### [](#system-topic-filtering-rules)System topic filtering rules Redpanda system topics have the following specific filtering restrictions: - Literal filters for `__consumer_offsets` and `_redpanda.audit_log` are rejected. - Prefix filters for topics starting with `_redpanda` or `__redpanda` are rejected. - Wildcard `*` filters will not match topics that start with `_redpanda` or `__redpanda`. - To shadow specific system topics, you must provide explicit literal filters for those individual topics. #### [](#acl-filtering)ACL filtering ACLs are replicated by the [Security Migrator task](../overview/#shadow-link-tasks). This is recommended to ensure that your shadow cluster has the same permissions as your source cluster. To configure ACL filters: ```yaml security_sync_options: acl_filters: # Include read permissions for production topics - resource_filter: resource_type: TOPIC # Filter by topic resource pattern_type: PREFIXED # Match by prefix name: prod- # Production topic prefix access_filter: principal: User:app-user # Application service user operation: READ # Read operation permission_type: ALLOW # Allow permission host: '*' # Any host # Include consumer group permissions - resource_filter: resource_type: GROUP # Filter by consumer group pattern_type: LITERAL # Exact match name: '*' # All consumer groups access_filter: principal: User:app-user # Same application user operation: READ # Read operation permission_type: ALLOW # Allow permission host: '*' # Any host ``` #### [](#consumer-group-filtering-and-behavior)Consumer group filtering and behavior Consumer group filters determine which consumer groups have their offsets replicated to the shadow cluster by the [Consumer Group Shadowing task](../overview/#shadow-link-tasks). Offset replication operates selectively within each consumer group. Only committed offsets for active shadow topics are synchronized, even if the consumer group has offsets for additional topics that aren’t being shadowed. For example, if consumer group "app-consumers" has committed offsets for "orders", "payments", and "inventory" topics, but only "orders" is an active shadow topic, then only the "orders" offsets will be replicated to the shadow cluster. ```yaml consumer_offset_sync_options: interval: 30s # How often to sync consumer group offsets paused: false # Enable consumer offset synchronization group_filters: - pattern_type: PREFIX filter_type: INCLUDE name: prod-consumer- # Include production consumer groups - pattern_type: LITERAL filter_type: EXCLUDE name: test-consumer-group # Exclude specific test groups ``` ##### [](#important-consumer-group-considerations)Important consumer group considerations **Avoid name conflicts:** If you plan to consume data from the shadow cluster, do not use the same consumer group names as those used on the source cluster. While this won’t break shadow linking, it can impact your RPO/RTO because conflicting group names may interfere with offset replication and consumer resumption during disaster recovery. **Offset clamping:** When Redpanda replicates consumer group offsets from the source cluster, offsets are automatically "clamped" during the commit process on the shadow cluster. If a committed offset from the source cluster is above the high watermark (HWM) of the corresponding shadow partition, Redpanda clamps the offset to the shadow partition’s HWM before committing it to the shadow cluster. This ensures offsets remain valid and prevents consumers from seeking beyond available data on the shadow cluster. #### [](#starting-offset-for-new-shadow-topics)Starting offset for new shadow topics When the [Source Topic Sync task](../overview/#shadow-link-tasks) creates a shadow topic for the first time, you can control where replication begins on the source topic. This setting only applies to empty shadow partitions and is crucial for disaster recovery planning. Changing this configuration only affects new shadow topics, existing shadow topics continue replicating from their current position. ```yaml topic_metadata_sync_options: start_at_earliest: {} ``` Alternatively, to start from the most recent offset: ```yaml topic_metadata_sync_options: start_at_latest: {} ``` Or to start from a specific timestamp: ```yaml topic_metadata_sync_options: start_at_timestamp: 2024-01-01T00:00:00Z ``` Starting offset options: - **`earliest`** (default): This replicates all existing data from the source topic. Use this for complete disaster recovery where you need full data history. - **`latest`**: This starts replication from the current end of the source topic, skipping existing data. Use this when you only need new data for disaster recovery and want to minimize initial replication time. - **`timestamp`**: This starts replication from the first record with a timestamp at or after the specified time. Use this for point-in-time disaster recovery scenarios. > ❗ **IMPORTANT** > > The starting offset only affects **new shadow topics**. After a shadow topic exists and has data, changing this setting has no effect on that topic’s replication. #### [](#networking)Networking Configure network connectivity between your source and shadow clusters to enable shadow link replication. The shadow cluster initiates connections to the source cluster using a pull-based architecture. For additional details about networking, see [Network and authentication](#network-and-authentication). ##### [](#connection-requirements)Connection requirements - **Direction**: Shadow cluster connects to source cluster (outbound from shadow, inbound to source) - **Protocol**: Kafka protocol over TCP (default port 9092, or your configured listener ports) - **Persistence**: Connections remain active for continuous replication ##### [](#firewall-configuration)Firewall configuration You must configure firewall rules to allow the shadow cluster to reach the source cluster. **On the source cluster network:** - Allow inbound TCP connections on Kafka listener ports (typically 9092). - Allow connections from the shadow cluster’s IP addresses or subnets. **On the shadow cluster network:** - Allow outbound TCP connections to the source cluster’s Kafka listener ports. - Ensure DNS resolution works for source cluster hostnames. ##### [](#bootstrap-servers)Bootstrap servers Specify multiple bootstrap servers in your shadow link configuration for high availability: ```yaml client_options: bootstrap_servers: # Source cluster brokers to connect to - : # Example: "prod-kafka-1.example.com:9092" - : # Example: "prod-kafka-2.example.com:9092" - : # Example: "prod-kafka-3.example.com:9092" ``` The shadow cluster uses these addresses to discover all brokers in the source cluster. If one bootstrap server is unavailable, the shadow cluster tries the next one in the list. ##### [](#network-security)Network security For production deployments, secure the network connection between clusters: TLS encryption: ```yaml client_options: tls_settings: enabled: true # Enable TLS tls_file_settings: ca_path: # Path to CA certificate, example: "/etc/ssl/certs/ca.crt" key_path: # Optional: Path to client private key, example: "/etc/ssl/private/client.key" cert_path: # Optional: Path to client certificate, example: "/etc/ssl/certs/client.crt" do_not_set_sni_hostname: false # Optional: Skip SNI hostname when using TLS (default: false) ``` Authentication: ```yaml client_options: authentication_configuration: # SASL/SCRAM authentication. # Create SASL credentials in the source cluster. # Then, with this configuration, ensure the shadow cluster uses the credentials # to authenticate to the source cluster. scram_configuration: username: # SASL/SCRAM username, example: "shadow-replication-user" password: # SASL/SCRAM password, example: "secure-password-123" scram_mechanism: SCRAM_SHA_256 # SCRAM mechanism: "SCRAM_SHA_256" or "SCRAM_SHA_512" # SASL/PLAIN authentication plain_configuration: username: # SASL/PLAIN username, example: "shadow-replication-user" password: # SASL/PLAIN password ``` ##### [](#connection-tuning)Connection tuning Adjust connection parameters based on your network characteristics. For example: ```yaml client_options: # Connection and metadata settings connection_timeout_ms: 1000 # Default 1000ms, increase for high-latency networks retry_backoff_ms: 100 # Default 100ms, backoff between connection retries metadata_max_age_ms: 10000 # Default 10000ms, how often to refresh cluster metadata # Fetch request settings fetch_wait_max_ms: 500 # Default 500ms, max time to wait for fetch requests fetch_min_bytes: 5242880 # Default 5MB, minimum bytes to fetch per request fetch_max_bytes: 20971520 # Default 20MB, maximum bytes to fetch per request fetch_partition_max_bytes: 1048576 # Default 1MB, maximum bytes to fetch per partition ``` ## [](#update-an-existing-shadow-link)Update an existing shadow link To modify a shadow link configuration after creation, run: ```bash rpk shadow update ``` For detailed command options, see [`rpk shadow update`](../../../../reference/rpk/rpk-shadow/rpk-shadow-update/). This opens your default editor to modify the shadow link configuration. Only changed fields are updated on the server. The shadow link name cannot be changed - you must delete and recreate the link to rename it. See also: [Admin API v2 reference](/api/doc/admin/v2/) --- # Page 141: Topic Recovery **URL**: https://docs.redpanda.com/current/manage/disaster-recovery/topic-recovery.md --- # Topic Recovery --- title: Topic Recovery latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: disaster-recovery/topic-recovery page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: disaster-recovery/topic-recovery.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/disaster-recovery/topic-recovery.adoc description: Restore a single topic from object storage. page-git-created-date: "2025-11-19" page-git-modified-date: "2025-11-19" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../get-started/licensing/#self-managed) apply. When you create a topic, you can use remote recovery to download the topic data from object storage. This is useful when you need to restore a single topic in Tiered Storage that was accidentally deleted from a cluster. > ⚠️ **WARNING** > > While performing topic recovery, avoid adding additional load (such as produces, consumes, lists or additional recovery operations) to the target cluster. Doing so could destabilize the recovery process and result in either an unsuccessful or corrupted recovered topic. ## [](#prerequisites)Prerequisites You must have: - [Tiered Storage](../../tiered-storage/) enabled on your Redpanda cluster. - [Remote read](../../tiered-storage/#remote-read) (`redpanda.remote.read`) enabled on the topic you want to recover. ## [](#limitations)Limitations - Remote recovery is only safe when no other clusters are writing to the same bucket or container. - If you disable `redpanda.remote.read` after remote recovery, previously downloaded data will not be used to serve requests. ## [](#recover-a-topic)Recover a topic To create a new topic using remote recovery, in which the recovered topic can read and write in the cloud: ```bash rpk topic create -c redpanda.remote.recovery=true -c redpanda.remote.write=true -c redpanda.remote.read=true ``` To create a new topic using remote recovery, while also disabling the `redpanda.remote.write` property: ```bash rpk topic create -c redpanda.remote.recovery=true -c redpanda.remote.write=false -c redpanda.remote.read=true ``` --- # Page 142: Whole Cluster Restore **URL**: https://docs.redpanda.com/current/manage/disaster-recovery/whole-cluster-restore.md --- # Whole Cluster Restore --- title: Whole Cluster Restore latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: disaster-recovery/whole-cluster-restore page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: disaster-recovery/whole-cluster-restore.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/disaster-recovery/whole-cluster-restore.adoc description: Restore a failed cluster, including its metadata. page-git-created-date: "2025-11-19" page-git-modified-date: "2025-11-19" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../get-started/licensing/#self-managed) apply. With [Tiered Storage](../../tiered-storage/) enabled, you can use Whole Cluster Restore to restore data from a failed cluster (source cluster you are restoring from), including its metadata, onto a new cluster (target cluster you are restoring to). This is a simpler and cheaper alternative to active-active replication, for example with [MirrorMaker 2](../../../migrate/data-migration/). Use this recovery method to restore your application to the latest functional state as quickly as possible. > ⚠️ **CAUTION** > > Whole Cluster Restore is not a fully-functional disaster recovery solution. It does not provide snapshot-style consistency. Some partitions in some topics will be more up-to-date than others. Committed transactions are not guaranteed to be atomic. > 💡 **TIP** > > If you need to restore only a subset of topic data, consider using [topic recovery](../topic-recovery/) instead of a Whole Cluster Restore. The following metadata is included in a Whole Cluster Restore: - Topic definitions. If you have enabled Tiered Storage only for specific topics, topics without Tiered Storage enabled will be restored empty. - Users and access control lists (ACLs). - [Schemas](../../schema-reg/schema-reg-overview/). To ensure that your schemas are also archived and restored, you must also enable Tiered Storage for the `_schemas` topic. - The [consumer offsets topic](../../../develop/consume-data/consumer-offsets/). Some restored committed consumer offsets may be truncated to a lower value than in the original cluster, to keep offsets at or below the highest restored offset in the partition. - Transaction metadata, up to the highest committed transaction. In-flight transactions are treated as aborted and will not be included in the restore. - [Cluster configurations](../../../reference/properties/cluster-properties/), including your Redpanda license key, with the exception of the following properties: - `cloud_storage_cache_size` - `cluster_id` - `cloud_storage_access_key` - `cloud_storage_secret_key` - `cloud_storage_region` - `cloud_storage_bucket` - `cloud_storage_api_endpoint` - `cloud_storage_credentials_source` - `cloud_storage_trust_file` - `cloud_storage_backend` - `cloud_storage_credentials_host` - `cloud_storage_azure_storage_account` - `cloud_storage_azure_container` - `cloud_storage_azure_shared_key` - `cloud_storage_azure_adls_endpoint` - `cloud_storage_azure_adls_port` ## [](#manage-source-metadata-uploads)Manage source metadata uploads By default, Redpanda uploads cluster metadata to object storage periodically. You can manage metadata uploads for your source cluster, or disable them entirely, with the following cluster configuration properties: - [`enable_cluster_metadata_upload_loop`](../../../reference/properties/cluster-properties/#enable_cluster_metadata_upload_loop): Enable metadata uploads. This property is enabled by default and is required for Whole Cluster Restore. - [`cloud_storage_cluster_metadata_upload_interval_ms`](../../../reference/properties/object-storage-properties/#cloud_storage_cluster_metadata_upload_interval_ms): Set the time interval to wait between metadata uploads. - [`controller_snapshot_max_age_sec`](../../../reference/properties/cluster-properties/#controller_snapshot_max_age_sec): Maximum amount of time that can pass before Redpanda attempts to take a controller snapshot after a new controller command appears. This property affects how current the uploaded metadata can be. - [`cloud_storage_cluster_name`](../../../reference/properties/object-storage-properties/#cloud_storage_cluster_name): This is an internal-only configuration and should be enabled only after consulting with Redpanda support. Specify a custom name for cluster’s metadata in object storage. For use when multiple clusters share the same storage bucket (for example, for Whole Cluster Restore). > 📝 **NOTE** > > You can monitor the [redpanda\_cluster\_latest\_cluster\_metadata\_manifest\_age](../../../reference/public-metrics-reference/#redpanda_cluster_latest_cluster_metadata_manifest_age) metric to track the age of the most recent metadata upload. ## [](#restore-data-from-a-source-cluster)Restore data from a source cluster To restore data from a source cluster: 1. [Start a target cluster](#start-a-target-cluster) (new cluster). 2. [Restore data from a failed source cluster to the new cluster](#restore-to-target-cluster). ### [](#prerequisites)Prerequisites You must have the following: - Redpanda v23.3 or later on both source and target clusters. - [Tiered Storage](../../tiered-storage/) enabled on the source cluster. - Physical or virtual machines on which to deploy the target cluster. ### [](#limitations)Limitations - You cannot use Whole Cluster Restore if the target cluster is in [recovery mode](../../recovery-mode/). - Whole Cluster Restore supports only one source cluster. It is not possible to consolidate multiple clusters onto the target cluster. - If a duplicate cluster configuration is found in the target cluster, it will be overwritten by the restore. - The target cluster should not contain user-managed or application-managed topic data, schemas, users, ACLs, or ongoing transactions. ### [](#start-a-target-cluster)Start a target cluster Follow the steps to [deploy a new cluster](../../../deploy/redpanda/manual/production/). > 📝 **NOTE** > > Make sure to configure the target cluster with the same Tiered Storage settings as the source cluster. ### [](#restore-to-target-cluster)Restore to target cluster You can restore data from a source cluster to a target cluster using the [`rpk cluster storage restore`](../../../reference/rpk/rpk-cluster/rpk-cluster-storage-restore/) command. 1. Restore data from the source cluster: ```bash rpk cluster storage restore start -w ``` The wait flag (`-w`) tells the command to poll the status of the restore process and then exit when completed. 2. Check if a rolling restart is required: ```bash rpk cluster config status ``` Example output when a restart is required: ```bash NODE CONFIG-VERSION NEEDS-RESTART INVALID UNKNOWN 1 4 true [] [] ``` 3. If a restart is required, perform a [rolling restart](../../cluster-maintenance/rolling-restart/). When the cluster restore is successfully completed, you can redirect your application workload to the new cluster. Make sure to update your application code to use the new addresses of your brokers. ## [](#restore-data-from-multiple-clusters-sharing-the-same-bucket)Restore data from multiple clusters sharing the same bucket > ⚠️ **CAUTION** > > This is an advanced use case that should be performed only after consulting with Redpanda support. Typically, you will have a one-to-one mapping between a Redpanda cluster and its object storage bucket. However, it’s possible to run multiple clusters that share the same storage bucket. Sharing an object storage bucket allows you to move tenants between clusters without moving data. For example, you might wish to move topics (unmount on cluster A, mount on cluster B) to multiple clusters in the same bucket without having to move data. Running multiple clusters that share the same storage bucket presents unique challenges during Whole Cluster Restore operations. To manage these challenges, you must understand how Redpanda uses [UUIDs](#the-role-of-cluster-uuids-in-whole-cluster-restore) (universally unique identifiers) to identify clusters during a Whole Cluster Restore. This shared storage approach can create identification challenges during restore operations. ### [](#the-role-of-cluster-uuids-in-whole-cluster-restore)The role of cluster UUIDs in Whole Cluster Restore Each Redpanda cluster (single node or more) receives a unique UUID every time it starts. From that moment forward, all entities created by the cluster are identifiable using this cluster UUID. These entities include: - Topic data - Topic metadata - Whole Cluster Restore manifests - Controller log snapshots for Whole Cluster Restore - Consumer offsets for Whole Cluster Restore However, not all entities _managed_ by the cluster are identifiable using this cluster UUID. Each time a cluster uploads its metadata, the name of the object has two parts: the cluster UUID, which is unique each time you create a cluster (even after a restore it will have a new UUID), and a metadata (sequence) ID. When performing a restore, Redpanda scans the bucket to find the highest-sequenced ID uploaded by the cluster. It can be ambiguous what to restore when the highest sequential ID has been uploaded by another cluster, and result in a split-brain scenario, where you have two independent clusters that both believe they are the “rightful owner” of the same logical data. ### [](#configure-cluster-names-for-multiple-source-clusters)Configure cluster names for multiple source clusters To disambiguate cluster metadata from multiple clusters, use the [`cloud_storage_cluster_name`](../../../reference/properties/object-storage-properties/#cloud_storage_cluster_name) property (off by default), which allows you to assign a unique name to each cluster sharing the same object storage bucket. Redpanda uses this name to organize the cluster metadata within the shared object storage bucket. This ensures that each cluster’s data remains distinct and prevents conflicts during recovery operations.The name must be unique within the bucket, 1-64 characters, and use only letters, numbers, underscores, and hyphens. Do not change this value once set. After setting, your object storage bucket organization may look like the following: ```bash / +- cluster_metadata/ | + /manifests/ | | +- 0/cluster_manifest.json | | +- 1/cluster_manifest.json | | +- 2/cluster_manifest.json | + /manifests/ | +- 0/cluster_manifest.json | +- 1/cluster_manifest.json # lost cluster +- cluster_name/ +- rp-foo/uuid/ +- rp-qux/uuid/ ``` During a Whole Cluster Restore, Redpanda looks for the cluster name specified in `cloud_storage_cluster_name` and only consider manifests associated with that name. Because the cluster name specified here is `rp-qux`, Redpanda only considers manifests for the clusters `` and `` (another new cluster sharing the bucket), ignoring cluster `` entirely. In this case, your object storage bucket may look like the following: ```bash +- cluster_metadata/ | + /manifests/ | | +- 0/cluster_manifest.json | | +- 1/cluster_manifest.json | | +- 2/cluster_manifest.json | + /manifests/ | | +- 0/cluster_manifest.json | | +- 1/cluster_manifest.json # lost cluster | + /manifests/ | +- 3/cluster_manifest.json # new cluster | # ^- next highest sequence number globally +- cluster_name/ +- rp-foo/uuid/ +- rp-qux/uuid/ +- +- # reference to new cluster ``` ### [](#resolve-repeated-recovery-failures)Resolve repeated recovery failures If you experience repeated failures when a cluster is lost and recreated, the automated recovery algorithm may have selected the manifest with the highest sequence number, which might be the most recent one with no data, instead of the original one containing the data. In such a scenario, your object storage bucket might be organized like the following: ```bash / +- cluster_metadata/ + /manifests/ | +- 0/cluster_manifest.json | +- 1/cluster_manifest.json #lost cluster + /manifests/ +- 3/cluster_manifest.json # lost again (not recovered) + /manifests/ +- 7/cluster_manifest.json # new attempt to recover uuid-b # it does not have the data ``` In such cases, you can explicitly specify the cluster UUID: #### rpk The `--cluster-uuid-override` option is available in v25.3.3 and later: ```bash rpk cluster storage restore start --cluster-uuid-override ``` #### Admin API ```bash curl -XPOST \ --data '{"cluster_uuid_override": ""}' \ http://localhost:9644/v1/cloud_storage/automated_recovery ``` For details, see the [Admin API reference](../../use-admin-api/). --- # Page 143: Fast Commission and Decommission Brokers **URL**: https://docs.redpanda.com/current/manage/fast-commission-decommission.md --- # Fast Commission and Decommission Brokers --- title: Fast Commission and Decommission Brokers latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: fast-commission-decommission page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: fast-commission-decommission.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/fast-commission-decommission.adoc description: Configure fast partition movement during cluster resize for high availability. page-git-created-date: "2024-08-15" page-git-modified-date: "2025-07-31" support-status: supported --- Tiered Storage gives you the option to boost the speed and reduce the impact of broker operations, particularly when resizing a cluster. For instance, adding a new broker to increase capacity for an overburdened cluster could introduce additional stress as partition replicas are transferred to the new broker. For cloud deployments, commissioning or decommissioning a broker can be a slow and expensive process, especially across multiple availability zones (AZs). Tiered Storage can help make the cluster resize process faster and more cost-efficient by leveraging data that has already been uploaded to object storage. Instead of transferring all data from local storage to the reassigned replicas, the replicas can instead be initialized to rely more heavily on Tiered Storage for read requests. To accomplish this, Redpanda takes an on-demand snapshot at an offset that is already uploaded to object storage. This is a later offset compared to the default log start offset managed by [Raft](https://raft.github.io/). When an empty replica is initialized, the later offset uploaded to object storage can be used as the start offset source. Reads that access data before the uploaded offset can be executed as remote reads. Therefore, the only data that needs to be sent over the network to replicas is the data locally retained after the uploaded offset. This also results in less time taken overall to grow or shrink the cluster. ## [](#configure-fast-commission-and-decommission)Configure fast commission and decommission To activate fast commission and decommission when brokers enter and leave the cluster: 1. Make sure to [configure topics for Tiered Storage](../tiered-storage/#enable-tiered-storage). 2. Configure at least one of the following cluster configuration properties. These properties limit the size of data replicated across brokers to local storage using Raft: - `initial_retention_local_target_bytes_default`: Initial local retention size target for partitions of topics with Tiered Storage enabled. The default is null. - Use the `initial.retention.local.target.bytes` topic configuration property to override on the topic level. - `initial_retention_local_target_ms_default`: Initial local retention time target for partitions of topics with Tiered Storage enabled. The default is null. - Use the `initial.retention.local.target.ms` topic configuration property to override on the topic level. If no values are set for the cluster configuration properties, all locally-retained data is delivered by default to the new broker (learner) when joining a partition replica set. > ❗ **IMPORTANT** > > Because topics become more reliant on object storage to serve data, you may experience higher latency reads for data beyond the range of the configured local [retention target](../tiered-storage/#set-retention-limits). Carefully weigh the tradeoffs between faster broker commission/decommission and the increased read latency due to less data being available in local storage. ## [](#monitor-fast-commission-and-decommission)Monitor fast commission and decommission Use the following to monitor fast commission and decommission: - The `vectorized_cluster_partition_start_offset` metric on newly-joined brokers should be greater than on existing brokers. - Raft protocol logs taking an on-demand snapshot are logged. For example: ```bash INFO 2025-03-12 09:32:23,280 [shard 13:raft] raft - [follower: {id: 39, revision: 19481451}, term: 34] [group_id:116908, {kafka/foo/999}] - recovery_stm.cc:473 - creating on demand snapshot with last included offset: 316791, current leader start offset: 203732. Total partition size on leader 46.109MiB, expected to transfer to learner: 683.000 bytes ``` - Depending on retention settings, disk usage on a newly-joined broker should generally be much lower than on existing brokers. ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) [Search all labs](/redpanda-labs) --- # Page 144: High Availability **URL**: https://docs.redpanda.com/current/manage/high-availability.md --- # High Availability --- title: High Availability latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: high-availability page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: high-availability.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/high-availability.adoc description: Learn about the trade-offs with different high availability configurations. page-git-created-date: "2025-11-19" page-git-modified-date: "2025-11-19" support-status: supported --- Redpanda is designed to ensure data integrity and high availability (HA), even at high-throughput levels. ## [](#deployment-strategies)Deployment strategies Consider the following Redpanda deployment strategies for the most common types of failures. | Failure | Impact | Mitigation strategy | | --- | --- | --- | | Broker failure | Loss of function for an individual broker or for any virtual machine (VM) that hosts the broker | Multi-broker deployment | | Rack or switch failure | Loss of brokers/VMs hosted within that rack, or loss of connectivity to them | Multi-broker deployment spread across multiple racks or network failure domains | | Data center failure | Loss of brokers/VMs hosted within that data center, or loss of connectivity to them | Multi-AZ or replicated deployment | | Region failure | Loss of brokers/VMs hosted within that region, or loss of connectivity to them | Geo-stretch (latency dependent) or replicated deployment | | Global, systemic outage (DNS failures, routing failures) | Complete outage for all systems and services impacting customers and staff | Offline backups, replicas in 3rd-party domains | | Data loss or corruption (accidental or malicious) | Corrupt or unavailable data that also affects synchronous replicas | Offline backups | See also: [Deploy for Production](../../deploy/redpanda/manual/production/production-deployment/) ## [](#ha-deployment-options)HA deployment options This section explains the trade-offs with different HA configurations. - [Multi-broker deployment](#multi-broker-deployment) - [Multi-AZ deployment](#multi-az-deployment) - [Multi-region deployment](#multi-region-deployment) - [Multi-cluster deployment](#multi-cluster-deployment) ### [](#multi-broker-deployment)Multi-broker deployment Redpanda is designed to be deployed in a cluster that consists of at least three brokers. Although clusters with a single broker are convenient for development and testing, they aren’t resilient to failure. Adding brokers to a cluster provides a way to handle individual broker failures. You can also use [\[rack awareness\]](#rack awareness) to assign brokers to different racks, which allows Redpanda to tolerate the loss of a rack or failure domain. ![Single-AZ deployment](../../shared/_images/single_az.png) See also: [Single-AZ deployments](#single-az-deployments) ### [](#multi-az-deployment)Multi-AZ deployment An availability zone (AZ) consists of one or more data centers served by high-bandwidth links with low latency (and typically within a close distance of one another). All AZs have discrete failure domains (power, cooling, fire, and network), but they also have common-cause failure domains, such as catastrophic events, that affect their geographical location. To safeguard against such possibilities, a cluster can be deployed across multiple AZs by configuring each AZ as a rack using rack awareness. Implementing Raft internally ensures that Redpanda can tolerate losing a minority of replicas for a given topic or for controller groups. For this to translate to a multi-AZ deployment, however, it’s necessary to deploy to at least three AZs (affording the loss of one zone). In a typical multi-AZ deployment, cluster performance is constrained by inter-AZ bandwidth and latency. See also: [Multi-AZ deployments](#multi-az-deployments) ![Multi-AZ deployment](../../shared/_images/multi_az.png) ### [](#multi-region-deployment)Multi-region deployment A multi-region deployment is similar to a multi-AZ deployment, in that it needs at least three regions to counter the loss of a single region. Note that this deployment strategy increases latency due to the physical distance between regions. In addition to higher produce and end-to-end latency and increased costs, multi-region deployments require careful tuning. Redpanda recommends that you work closely with Redpanda’s Customer Success team when implementing a multi-region deployment. Also consider the following strategies to mitigate these challenges: - Configure [Leader Pinning](../../develop/produce-data/leader-pinning/) to ensure that topic partition leaders are geographically closer to clients. This can help lower network costs and latency by routing produce requests to brokers located in specific AZs. - If your produce latency exceeds your requirements, you can configure producers to have `acks=1` instead of `acks=all`. This reduces latency by only waiting for the leader to acknowledge, rather than waiting for all brokers to respond. However, using this configuration can decrease message durability. If the partition leader goes offline, you may lose any messages that are acknowledged but not yet replicated. ### [](#multi-cluster-deployment)Multi-cluster deployment In a multi-cluster deployment, each cluster is configured using one of the other HA deployments, along with standby clusters or [Remote Read Replica](../remote-read-replicas/) clusters in one or more remote locations. A standby cluster is a fully functional cluster that can handle producers and consumers. A remote read replica is a read-only cluster that can act as a backup for topics. To replicate data across clusters in a multi-cluster deployment, use one of the following options: - [MirrorMaker2 replication](../../migrate/data-migration/) - [Remote Read Replicas](../remote-read-replicas/) - [Redpanda Edge Agent](https://github.com/redpanda-data/redpanda-edge-agent) Alternatively, you could dual-feed clusters in multiple regions. Dual feeding is the process of having producers connect to your cluster across multiple regions. However, this introduces additional complexity onto the producing application. It also requires consumers that have sufficient deduplication logic built in to handle offsets, since they won’t be the same across each cluster. ## [](#ha-features-in-redpanda)HA features in Redpanda Redpanda includes the following high-availability features: - [Replica synchronization](#replica-synchronization) - [Rack awareness](#rack-awareness) - [Partition leadership](#partition-leadership) - [Producer acknowledgment](#producer-acknowledgment) - [Partition rebalancing](#partition-rebalancing) - [Tiered Storage and disaster recovery](#tiered-storage-and-disaster-recovery) ### [](#replica-synchronization)Replica synchronization A cluster’s availability is directly tied to replica synchronization. Brokers can be either leaders or replicas (followers) for a partition. A cluster’s replica brokers must be consistent with the leader to be available for consumers and producers. 1. The leader writes data to the disk. It then dispatches append entry requests to the followers in parallel with the disk flush. 2. The replicas receive messages written to the partition of the leader. They send acknowledgments to the leader after successfully replicating the message to their internal partition. 3. The leader sends an acknowledgment to the producer of the message, as determined by that producer’s `acks` value. Redpanda considers the group consistent after a majority has formed consensus; that is, a majority of participants acknowledged the write. While Apache Kafka® uses in-sync replicas, Redpanda uses a quorum-based majority with the Raft replication protocol. Kafka performance is negatively impacted when any "in-sync" replica is running slower than other replicas in the In-Sync Replica (ISR) set. Monitor the health of your cluster with the [`rpk cluster health`](../../reference/rpk/rpk-cluster/rpk-cluster-health/) command, which tells you if any brokers are down, and if you have any leaderless partitions. ### [](#rack-awareness)Rack awareness Rack awareness is one of the most important features for HA. It lets Redpanda spread partition replicas across available brokers in different failure zones. Rack awareness ensures that no more than a minority of replicas are placed on a single rack, even during cluster balancing. > 💡 **TIP** > > Make sure you assign separate rack IDs that actually correspond to a physical separation of brokers. See also: [Enable Rack Awareness](../rack-awareness/) ### [](#partition-leadership)Partition leadership Raft uses a heartbeat mechanism to maintain leadership authority and to trigger leader elections. The partition leader sends a periodic heartbeat to all followers to assert its leadership. If a follower does not receive a heartbeat over a period of time, then it triggers an election to choose a new partition leader. See also: [Partition leadership elections](../../get-started/architecture/#partition-leadership-elections) ### [](#producer-acknowledgment)Producer acknowledgment Producer acknowledgment defines how producer clients and broker leaders communicate their status while transferring data. The `acks` value determines producer and broker behavior when writing data to the event bus. See also: [Producer Acknowledgement Settings](../../develop/produce-data/configure-producers/) ### [](#partition-rebalancing)Partition rebalancing By default, Redpanda rebalances partition distribution when brokers are added or decommissioned. Continuous Data Balancing additionally rebalances partitions when brokers become unavailable or when disk space usage exceeds a threshold. See also: [Cluster Balancing](../cluster-maintenance/cluster-balancing/) ### [](#tiered-storage-and-disaster-recovery)Tiered Storage and disaster recovery In a disaster, your secondary cluster may still be available, but you need to quickly restore the original level of redundancy by bringing up a new primary cluster. In a containerized environment such as Kubernetes, all state is lost from pods that use only local storage. HA deployments with Tiered Storage address both these problems, since it offers long-term data retention and topic recovery. See also: [Tiered Storage](../tiered-storage/) > ❗ **IMPORTANT** > > Tiered Storage operates as an asynchronous process and only applies to closed segments. Any open segments or segments existing only in local storage are not recoverable by your new primary cluster. ## [](#single-az-deployments)Single-AZ deployments When deploying a cluster for high availability into a single AZ or data center, you need to ensure that, within the AZ, single points of failure are minimized and that Redpanda is configured to be aware of any discrete failure domains within the AZ. This is achieved with Redpanda’s rack awareness, which deploys _n_ Redpanda brokers across three or more racks (or failure domains) within the AZ. Single-AZ deployments in the cloud have less network costs than multi-AZ deployments, and you can leverage resilient power supplies and networking infrastructure within the AZ to mitigate against all but total-AZ failure scenarios. You can balance the benefits of increased availability and fault tolerance against any increase in cost, performance, and complexity: - Cost: Redpanda operates the same Raft consensus algorithm whether it’s in HA mode or not. There may be infrastructure costs when deploying across multiple racks, but these are normally amortized across a wider datacenter operations program. - Performance: Spreading Redpanda replicas across racks and switches increases the number of network hops between Redpanda brokers; however, normal intra-data center network latency should be measured in microseconds rather than milliseconds. Ensure that there’s sufficient bandwidth between brokers to handle replication traffic. - Complexity: A benefit of Redpanda is the simplicity of deployment. Because Redpanda is deployed as a single binary with no external dependencies, it doesn’t need any infrastructure for ZooKeeper or for a Schema Registry. Redpanda also includes cluster balancing, so there’s no need to run Cruise Control. ### [](#single-az-infrastructure)Single-AZ infrastructure In a single-AZ deployment, ensure that brokers are spread across at least three failure domains. This generally means separate racks, under separate switches, ideally powered by separate electrical feeds or circuits. Also, ensure that there’s sufficient network bandwidth between brokers, particularly considering shared uplinks, which could be subject to high throughput intra-cluster replication traffic. In an on-premises network, this HA configuration refers to separate racks or data halls within a data center. Cloud providers support various HA configurations: - AWS [partition placement groups](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/placement-groups.html#placement-groups-partition) allow spreading hosts across multiple partitions (or failure domains) within an AZ. The default number of partitions is three, with a maximum of seven. This can be combined with Redpanda’s replication factor setting, so each topic partition replica is guaranteed to be isolated from the impact of hardware failure. - Microsoft Azure [flexible scale sets](https://learn.microsoft.com/en-us/azure/virtual-machine-scale-sets/virtual-machine-scale-sets-orchestration-modes#scale-sets-with-flexible-orchestration) let you assign VMs to specific fault domains. Each scale set can have up to five fault domains, depending on your region. Not all VM types support flexible orchestration; for example, Lsv2-series only supports uniform scale sets. - Google Cloud [instance placement policies](https://cloud.google.com/compute/docs/instances/define-instance-placement) let you specify how many availability domains you can have (up to eight) when using the Spread Instance Placement Policy. > 📝 **NOTE** > > Google Cloud doesn’t divulge which availability domain an instance has been placed into, so you must have an availability domain for each Redpanda broker. Essentially, this isn’t enabled with rack awareness, but it’s the only possibility for clusters with more than three brokers. You can automate this using Terraform or a similar infrastructure-as-code (IaC) tool. See [AWS](https://github.com/redpanda-data/deployment-automation/blob/main/aws/cluster.tf#L23-L24), [Azure](https://github.com/redpanda-data/deployment-automation/blob/main/azure/network.tf#L39-L50), and [GCP](https://github.com/redpanda-data/deployment-automation/blob/main/gcp/cluster.tf#L17-L19). ### [](#single-az-rack-awareness)Single-AZ rack awareness To make Redpanda aware of the topology it’s running on, configure the cluster to [enable rack awareness](../rack-awareness/), then configure each broker with the identifier of the rack. Set the `enable_rack_awareness custer` property either in `/etc/redpanda/.bootstrap.yaml` or with `rpk`: ```bash rpk cluster config set enable_rack_awareness true ``` For each broker, set the rack ID in `/etc/redpanda/redpanda.yaml` file or with `rpk`: ```bash rpk redpanda config set redpanda.rack ``` The modified Ansible playbooks take a per-instance rack variable from the Terraform output and use that to set the relevant cluster and broker configuration. Redpanda deployment automation can provision public cloud infrastructure with discrete failure domains (`-var=ha=true`) and use the resulting inventory to provision rack-aware clusters using Ansible. See also: [Automated Deployment](../../deploy/redpanda/manual/production/production-deployment-automation/) ### [](#single-az-example)Single-AZ example The following example deploys an HA cluster into AWS, Azure, or GCP using Terraform and Ansible. 1. Install all prerequisites, including all Ansible requirements: ```bash ansible-galaxy install -r ansible/requirements.yml ``` 2. Initialize a private key, if you haven’t done so already: ```bash ssh-keygen -f ~/.ssh/id_rsa ``` 3. Clone the deployment-automation repository: ```bash git clone https://github.com/redpanda-data/deployment-automation ``` 4. Initialize Terraform for your cloud provider: ```bash cd deployment-automation/aws (or cd deployment-automation/azure, or cd deployment-automation/gcp) terraform init ``` 5. Deploy the infrastructure (this assumes you have cloud credentials available): ```bash terraform apply -var=ha=true ``` 6. Verify that the racks have been correctly specified in the `host.ini` file: ```bash cd .. cat hosts.ini ``` ```ini [redpanda] 35.166.210.85 ansible_user=ubuntu ansible_become=True private_ip=172.31.7.173 rack=1 18.237.173.220 ansible_user=ubuntu ansible_become=True private_ip=172.31.2.138 rack=2 54.218.103.91 ansible_user=ubuntu ansible_become=True private_ip=172.31.2.93 rack=3 ``` 7. Provision the cluster with Ansible: ```bash ansible-playbook --private-key `cat ~/.ssh/id_rsa.pub | awk '{print $2}'` ansible/playbooks/provision-node.yml -i hosts.ini ``` 8. Verify that rack awareness is enabled: 1. Get connection details for the first Redpanda broker from the `hosts.ini` file: ```bash grep -A1 '\[redpanda]' hosts.ini ``` Example output: 35.166.210.85 ansible\_user=ubuntu ansible\_become=True private\_ip=172.31.7.173 rack=1 2. SSH into a cluster host with the username and hostname of that Redpanda broker: ```bash ssh -i ~/.ssh/id_rsa @ ``` 3. Verify that rack awareness is enabled: ```bash rpk cluster config get enable_rack_awareness ``` Example output: true 4. Check the rack assigned to this specific broker: ```bash rpk cluster status ``` Expected output: ```none CLUSTER = = = = redpanda.807d59af-e033-466a-98c3-bb0be15c255d BROKERS = = = = ID HOST PORT RACK 0* 10.0.1.7 9092 1 1 10.0.1.4 9092 2 2 10.0.1.8 9092 3 ``` ## [](#multi-az-deployments)Multi-AZ deployments In a multi-AZ (availability zone) deployment a single Redpanda cluster has brokers distributed over multiple availability zones. With rack awareness, Redpanda places replicas across brokers in different failure zones, resulting in a cluster that can survive a zone outage. > 📝 **NOTE** > > Adding a zone does not necessarily increase availability. The replication factor of a given partition is most important. If all of your partitions use a replication factor of three, then adding an additional broker in a fourth zone just means fewer partitions are affected by an outage (since the workload is more spread out). The primary reason to deploy across multiple availability zones is to achieve extremely high availability, even at the expense of other considerations. Before choosing this approach, carefully consider your system’s requirements. Some of the considerations of a multi-AZ approach include: - Cost: Maintaining presence across multiple availability zones may incur additional costs. You may require additional brokers to hit the minimum requirements for utilizing a multi-AZ deployment. Data sent between availability zones is often chargeable, resulting in additional cloud costs. - Performance: A multi-AZ approach introduces additional message latency. Your brokers are further apart in terms of network distance with additional routing hops in place. - Complexity: The Redpanda operational complexity is not appreciably increased, but the complexity of your overall cloud solution is. Maintaining presence across availability zones requires additional servers with corresponding maintenance, access control, and standard operational considerations. ### [](#multi-az-infrastructure-requirements)Multi-AZ infrastructure requirements Redpanda requires a minimum of three availability zones when using a multi-AZ approach. Deploying across only two availability zones is problematic. For example, given a cluster with three brokers spread across two availability zones, you either end up with all three brokers in one zone or a pair of brokers in one with a single broker in the other. Either way, it’s possible to lose a majority of your brokers with a single availability zone outage. You lose the ability to form consensus in affected partitions, negating the high availability state you desire. ### [](#multi-az-optimization)Multi-AZ optimization You can configure [follower fetching](../../develop/consume-data/follower-fetching/) to help ease the cross-AZ cost problems associated with a multi-AZ configuration. This is achieved by configuring consumers to advertise their preferred rack using the `client.rack` option within their consumer configuration. This allows consumers to read data from their closest replica rather than always reading from a (potentially non-local) partition leader. > 📝 **NOTE** > > With follower fetching enabled, a consumer chooses the closest replica rather than the leader. This reduces network transfer costs against the possibility of increased end-to-end latency. Make sure to monitor your system to determine if the cost savings are worth this latency risk. ### [](#multi-az-example)Multi-AZ example Redpanda provides an official [deployment automation](https://github.com/redpanda-data/deployment-automation) project using Ansible and Terraform to help self-managed users stand up multi-AZ deployments quickly and efficiently. #### [](#configure-terraform)Configure Terraform Configure the appropriate Terraform script for your cloud provider. Within the deployment-automation project, locate the file for your cloud provider and edit the `availability_zones` parameter. Include each availability zone you intend to use for your deployment. For example, under AWS, edit the `aws/main.tf` file: ```bash variable "availability_zone" { description = "The AWS AZ to deploy the infrastructure on" default = ["us-west-2a", "us-west-2b", "us-west-2c"] type = list(string) } ``` Alternatively, you can supply the configuration at the command line: ```bash $ terraform apply -var=availability_zone='["us-west-2a","us-west-2b","us-west-2c"]' ``` #### [](#deploy-using-terraform-and-ansible)Deploy using Terraform and Ansible After you configure Terraform for your cloud provider and choose availability zones, you can deploy your cluster. The following example deploys a multi-AZ cluster and validates the rack configuration. ```bash # Initialize a private key if you haven’t done so already ssh-keygen -f ~/.ssh/id_rsa # Clone the deployment-automation repository git clone https://github.com/redpanda-data/deployment-automation # Choose your cloud provider and initialize Terraform cd deployment-automation/aws # choose one: aws|azure|gcp terraform init # Deploy the infrastructure # (Note: This guidance is based on the assumption that you have cloud credentials available) terraform apply -var=availability_zone='["us-west-2a","us-west-2b","us-west-2c"]' # Verify you have correctly specified your racks in the host.ini file: cd .. export HOSTS=$(find . -name hosts.ini) head -4 $HOSTS [redpanda] 34.102.108.41 ansible_user=adminpanda ansible_become=True private_ip=10.168.0.41 rack=us-west2-a 35.236.32.47 ansible_user=adminpanda ansible_become=True private_ip=10.168.0.39 rack=us-west2-b 35.236.29.38 ansible_user=adminpanda ansible_become=True private_ip=10.168.0.40 rack=us-west2-c # Ensure the environment is ready export CLOUD_PROVIDER=aws # or azure or gcp accordingly export ANSIBLE_COLLECTIONS_PATH=${PWD}/artifacts/collections export ANSIBLE_ROLES_PATH=${PWD}/artifacts/roles export ANSIBLE_INVENTORY=${PWD}/${CLOUD_PROVIDER}/hosts.ini # Install Ansible Galaxy roles ansible-galaxy install -r ./requirements.yml # Provision the cluster with Ansible ansible-playbook ansible/provision-basic-cluster.yml -i $HOSTS ### Verify that rack awareness is enabled # SSH into a cluster node substituting the username and hostname from the values above ssh -i ~/.ssh/id_rsa @ # Check to confirm that rack awareness is enabled rpk cluster config get enable_rack_awareness true # Check to confirm that the brokers are assigned to distinct racks rpk cluster status | grep RACK -A3 ID HOST PORT RACK 0* 34.102.108.41 9092 us-west2-a 1 35.236.32.47 9092 us-west2-b 2 35.236.29.38 9092 us-west2-c ``` #### [](#use-follower-fetching)Use follower fetching Use [follower fetching](../../develop/consume-data/follower-fetching/) to reduce the latency and potential costs involved in a multi-AZ deployment. ```bash # SSH into a node using appropriate credentials ssh -i ~/.ssh/id_rsa @ # Create a topic with 1 partition and 3 replicas rpk topic create foo -p1 -r3 TOPIC STATUS foo OK # Determine which broker is the leader rpk topic describe foo -a | grep HIGH-WATERMARK -A1 PARTITION LEADER EPOCH REPLICAS LOG-START-OFFSET HIGH-WATERMARK 0 0 1 [0 1 2] 0 3 # Produce 1000 records using rpk for i in {1..1000}; do echo $(cat /dev/urandom | head -c50 | base64); done | rpk topic produce foo Produced to partition 0 at offset 0 with timestamp 1687508554559. Produced to partition 0 at offset 1 with timestamp 1687508554574. Produced to partition 0 at offset 2 with timestamp 1687508554593. ... 997 more lines ... # Consume for three seconds, writing debug logs and ignoring regular output timeout 3 rpk topic consume foo -v --rack us-west2-c 1>/dev/null 2>debug.log # Filter the debug log to only show lines of interest cat debug.log | grep -v ApiVersions | egrep 'opening|read' 08:25:14.974 DEBUG opening connection to broker {"addr": "10.168.0.41:9092", "broker": "seed 0"} 08:25:14.976 DEBUG read Metadata v7 {"broker": "seed 0", "bytes_read": 236, "read_wait": "36.312µs", "time_to_read": "534.898µs", "err": null} 08:25:14.977 DEBUG opening connection to broker {"addr": "34.102.108.41:9092", "broker": "0"} 08:25:14.980 DEBUG read ListOffsets v4 {"broker": "0", "bytes_read": 51, "read_wait": "16.19µs", "time_to_read": "1.090468ms", "err": null} 08:25:14.981 DEBUG opening connection to broker {"addr": "34.102.108.41:9092", "broker": "0"} 08:25:14.982 DEBUG read Fetch v11 {"broker": "0", "bytes_read": 73, "read_wait": "17.705µs", "time_to_read": "858.613µs", "err": null} 08:25:14.982 DEBUG opening connection to broker {"addr": "35.236.29.38:9092", "broker": "2"} 08:25:14.989 DEBUG read Fetch v11 {"broker": "2", "bytes_read": 130337, "read_wait": "54.712µs", "time_to_read": "4.466249ms", "err": null} 08:25:17.946 DEBUG read Fetch v11 {"broker": "2", "bytes_read": 0, "read_wait": "41.144µs", "time_to_read": "2.955927224s", "err": "context canceled"} 08:25:17.947 DEBUG read Fetch v11 {"broker": "0", "bytes_read": 22, "read_wait": "175.952µs", "time_to_read": "500.832µs", "err": null} ``` ## [](#suggested-reading)Suggested reading - [Redpanda’s official Jepsen report](https://redpanda.com/blog/redpanda-official-jepsen-report-and-analysis?utm_assettype=report&utm_assetname=roi_report&utm_source=gated_content&utm_medium=content&utm_campaign=jepsen_blog) - [Simplifying Redpanda Raft implementation](https://redpanda.com/blog/simplifying-raft-replication-in-redpanda) - [An availability footprint of the Redpanda and Apache Kafka replication protocols](https://redpanda.com/blog/kafka-redpanda-availability) - [How we built Tiered Storage to supercharge storage and data streaming](https://www.redpanda.com/blog/tiered-storage-architecture-deep-dive) ## Suggested labs - [Disaster Recovery with Envoy and Shadowing](/redpanda-labs/docker-compose/envoy-shadowing/) - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Stream Jira Issues to Redpanda for Real-Time Metrics](/redpanda-labs/docker-compose/jira-metrics-pipeline/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Set Up GitOps for the Redpanda Helm Chart](/redpanda-labs/kubernetes/gitops-helm/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) - [Set Up MySQL CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-mysql-json/) - [Set Up Postgres CDC with Debezium and Redpanda](/redpanda-labs/docker-compose/cdc-postgres-json/) See more [Search all labs](/redpanda-labs) --- # Page 145: Integrate Redpanda with Iceberg **URL**: https://docs.redpanda.com/current/manage/iceberg.md --- # Integrate Redpanda with Iceberg --- title: Integrate Redpanda with Iceberg latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: iceberg/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: iceberg/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/iceberg/index.adoc description: Generate Iceberg tables for your Redpanda topics for data lakehouse access. page-git-created-date: "2025-02-07" page-git-modified-date: "2025-02-07" support-status: supported --- - [About Iceberg Topics](about-iceberg-topics/) Learn how Redpanda can integrate topics with Apache Iceberg. - [Specify Iceberg Schema](specify-iceberg-schema/) Learn about supported Iceberg modes and how you can integrate schemas with Iceberg topics. - [Use Iceberg Catalogs](use-iceberg-catalogs/) Learn how to access Redpanda topic data stored in Iceberg tables, using table metadata or a catalog integration. - [Integrate with REST Catalogs](rest-catalog/) Integrate Redpanda topics with managed Iceberg REST Catalogs. - [Query Iceberg Topics](query-iceberg-topics/) Query Redpanda topic data stored in Iceberg tables, based on the topic Iceberg mode and schema. - [Migrate to Iceberg Topics](migrate-to-iceberg-topics/) Migrate existing Iceberg integrations to Redpanda Iceberg topics. --- # Page 146: About Iceberg Topics **URL**: https://docs.redpanda.com/current/manage/iceberg/about-iceberg-topics.md --- # About Iceberg Topics --- title: About Iceberg Topics latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: iceberg/about-iceberg-topics page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: iceberg/about-iceberg-topics.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/iceberg/about-iceberg-topics.adoc description: Learn how Redpanda can integrate topics with Apache Iceberg. page-git-created-date: "2025-04-08" page-git-modified-date: "2026-04-08" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../get-started/licensing/#self-managed) apply. The Apache Iceberg integration for Redpanda allows you to store topic data in the cloud in the Iceberg open table format. This makes your streaming data immediately available in downstream analytical systems, including data warehouses like Snowflake, Databricks, ClickHouse, and Redshift, without setting up and maintaining additional ETL pipelines. You can also integrate your data directly into commonly-used big data processing frameworks, such as Apache Spark and Flink, standardizing and simplifying the consumption of streams as tables in a wide variety of data analytics pipelines. Redpanda supports [version 2](https://iceberg.apache.org/spec/#format-versioning) of the Iceberg table format. ## [](#iceberg-concepts)Iceberg concepts [Apache Iceberg](https://iceberg.apache.org) is an open source format specification for defining structured tables in a data lake. The table format lets you quickly and easily manage, query, and process huge amounts of structured and unstructured data. This is similar to the way you would manage and run SQL queries against relational data in a database or data warehouse. The open format lets you use many different languages, tools, and applications to process the same data in a consistent way, so you can avoid vendor lock-in. This data management system is also known as a _data lakehouse_. In the Iceberg specification, tables consist of the following layers: - **Data layer**: Stores the data in data files. The Iceberg integration currently supports the Parquet file format. Parquet files are column-based and suitable for analytical workloads at scale. They come with compression capabilities that optimize files for object storage. - **Metadata layer**: Stores table metadata separately from data files. The metadata layer allows multiple writers to stage metadata changes and apply updates atomically. It also supports database snapshots, and time travel queries that query the database at a previous point in time. - Manifest files: Track data files and contain metadata about these files, such as record count, partition membership, and file paths. - Manifest list: Tracks all the manifest files belonging to a table, including file paths and upper and lower bounds for partition fields. - Metadata file: Stores metadata about the table, including its schema, partition information, and snapshots. Whenever a change is made to the table, a new metadata file is created and becomes the latest version of the metadata in the catalog. For Iceberg-enabled topics, the manifest files are in JSON format. - **Catalog**: Contains the current metadata pointer for the table. Clients reading and writing data to the table see the same version of the current state of the table. The Iceberg integration supports two [catalog integration](../use-iceberg-catalogs/) types. You can configure Redpanda to catalog files stored in the same object storage bucket or container where the Iceberg data files are located, or you can configure Redpanda to use an [Iceberg REST catalog](https://iceberg.apache.org/terms/#decoupling-using-the-rest-catalog) endpoint to update an externally-managed catalog when there are changes to the Iceberg data and metadata. ![Redpanda’s Iceberg integration](../../../shared/_images/iceberg-integration-optimized.png) When you enable the Iceberg integration for a Redpanda topic, Redpanda brokers store streaming data in the Iceberg-compatible format in Parquet files in object storage, in addition to the log segments uploaded using Tiered Storage. Storing the streaming data in Iceberg tables in the cloud allows you to derive real-time insights through many compatible data lakehouse, data engineering, and business intelligence [tools](https://iceberg.apache.org/vendors/). ## [](#prerequisites)Prerequisites To enable Iceberg for Redpanda topics, you must have the following: - **rpk**: See [Install or Update rpk](../../../get-started/rpk-install/). - **Enterprise license**: To check if you already have a license key applied to your cluster: ```bash rpk cluster license info ``` - **Tiered Storage**: Enable [Tiered Storage](../../tiered-storage/#set-up-tiered-storage) for the topics for which you want to generate Iceberg tables. ## [](#limitations)Limitations - It is not possible to append topic data to an existing Iceberg table that is not created by Redpanda. - If you enable the Iceberg integration on an existing Redpanda topic, Redpanda does not backfill the generated Iceberg table with topic data. - JSON schemas are supported starting with Redpanda version 25.2. ## [](#enable-iceberg-integration)Enable Iceberg integration To create an Iceberg table for a Redpanda topic, you must set the cluster configuration property `[iceberg_enabled](../../../reference/properties/cluster-properties/#iceberg_enabled)` to `true`, and also configure the topic property [`redpanda.iceberg.mode`](../../../reference/properties/topic-properties/#redpanda-iceberg-mode). You can choose to provide a schema if you need the Iceberg table to be structured with defined columns. 1. Set the `iceberg_enabled` configuration option on your cluster to `true`. When multiple clusters write to the same catalog, each cluster must use a distinct namespace to avoid table name collisions. This is especially critical for REST catalog providers that offer a single global catalog per account (such as AWS Glue), where there is no other isolation mechanism. By default, Redpanda creates Iceberg tables in a namespace called `redpanda`. To use a unique namespace for your cluster’s REST catalog integration, also set `[iceberg_default_catalog_namespace](../../../reference/properties/cluster-properties/#iceberg_default_catalog_namespace)` when you set `iceberg_enabled`. This property cannot be changed after you enable Iceberg topics on the cluster. ```bash rpk cluster config set iceberg_enabled true # Optional: set a custom namespace (default is "redpanda") # rpk cluster config set iceberg_default_catalog_namespace '[""]' ``` ```bash Successfully updated configuration. New configuration version is 2. ``` You must restart your cluster if you change this configuration for a running cluster. 2. (Optional) Create a new topic. ```bash rpk topic create ``` ```bash TOPIC STATUS OK ``` 3. Configure `redpanda.iceberg.mode` for the topic. You can choose one of the following [Iceberg modes](../specify-iceberg-schema/): - `key_value`: Creates an Iceberg table using a simple schema, consisting of two columns, one for the record metadata including the key, and another binary column for the record’s value. - `value_schema_id_prefix`: Creates an Iceberg table whose structure matches the Redpanda schema for this topic, with columns corresponding to each field. You must register a schema in the Schema Registry (see next step), and producers must write to the topic using the Schema Registry wire format. - `value_schema_latest`: Creates an Iceberg table whose structure matches the latest schema registered for the subject in the Schema Registry. - `disabled` (default): Disables writing to an Iceberg table for this topic. ```bash rpk topic alter-config --set redpanda.iceberg.mode= ``` ```bash TOPIC STATUS OK ``` 4. Register a schema for the topic. This step is required for the `value_schema_id_prefix` and `value_schema_latest` modes. ```bash rpk registry schema create --schema --type ``` ```bash SUBJECT VERSION ID TYPE 1 1 PROTOBUF ``` As you produce records to the topic, the data also becomes available in object storage for Iceberg-compatible clients to consume. You can use the same analytical tools to [read the Iceberg topic data](../query-iceberg-topics/) in a data lake as you would for a relational database. See also: [Schema types translation](../specify-iceberg-schema/#schema-types-translation). ### [](#iceberg-data-retention)Iceberg data retention Data in an Iceberg-enabled topic is consumable from Kafka based on the configured [topic retention policy](../../cluster-maintenance/disk-utilization/). Conversely, data written to Iceberg remains queryable as Iceberg tables indefinitely. The Iceberg table persists unless you: - Delete the Redpanda topic associated with the Iceberg table. This is the default behavior set by the `[iceberg_delete](../../../reference/properties/cluster-properties/#iceberg_delete)` cluster property and the `redpanda.iceberg.delete` topic property. If you set this property to `false`, the Iceberg table remains even after you delete the topic. - Explicitly delete data from the Iceberg table using a query engine. - Disable the Iceberg integration for the topic and delete the Parquet files in object storage. The DLQ table (`~dlq`) follows the same persistence rules as the main Iceberg table. ## [](#schema-evolution)Schema evolution Redpanda supports schema evolution in accordance with the [Iceberg specification](https://iceberg.apache.org/spec/#schema-evolution). Permitted schema evolutions include reordering fields and promoting field types. When you update the schema in Schema Registry, Redpanda automatically updates the Iceberg table schema to match the new schema. For example, if you produce records to a topic `demo-topic` with the following Avro schema: schema\_1.avsc ```avro { "type": "record", "name": "ClickEvent", "fields": [ { "name": "user_id", "type": "int" }, { "name": "event_type", "type": "string" } ] } ``` ```bash rpk registry schema create demo-topic-value --schema schema_1.avsc echo '{"user_id":23, "event_type":"BUTTON_CLICK"}' | rpk topic produce demo-topic --format='%v\n' --schema-id=topic ``` Then, you update the schema to add a new field `ts`, and produce records with the updated schema: schema\_2.avsc ```avro { "type": "record", "name": "ClickEvent", "fields": [ { "name": "user_id", "type": "int" }, { "name": "event_type", "type": "string" }, { "name": "ts", "type": [ "null", { "type": "long", "logicalType": "timestamp-millis" } ], "default": null # Default value for the new field } ] } ``` The `ts` field can be either null or a long representing epoch milliseconds. The default value is null. ```bash rpk registry schema create demo-topic-value --schema schema_2.avsc echo '{"user_id":858, "event_type":"BUTTON_CLICK", "ts":1737998723230}' | rpk topic produce demo-topic --format='%v\n' --schema-id=topic ``` Querying the Iceberg table for `demo-topic` includes the new column `ts`: ```bash +---------+--------------+--------------------------+ | user_id | event_type | ts | +---------+--------------+--------------------------+ | 858 | BUTTON_CLICK | 2025-02-26T20:05:23.230Z | | 23 | BUTTON_CLICK | NULL | +---------+--------------+--------------------------+ ``` ## [](#troubleshoot-errors)Troubleshoot errors If Redpanda encounters an error while writing a record to the Iceberg table, Redpanda by default writes the record to a separate dead-letter queue (DLQ) Iceberg table named `~dlq`. The following can cause errors to occur when translating records in the `value_schema_id_prefix` and `value_schema_latest` modes to the Iceberg table format: - Redpanda cannot find the embedded schema ID in the Schema Registry. - Redpanda fails to translate one or more schema data types to an Iceberg type. - In `value_schema_id_prefix` mode, you do not use the Schema Registry wire format with the magic byte. The DLQ table itself uses the `key_value` schema, consisting of two columns: the record metadata including the key, and a binary column for the record’s value. > 📝 **NOTE** > > Topic property misconfiguration, such as [overriding the default behavior of `value_schema_latest` mode](../specify-iceberg-schema/#override-value-schema-latest-default) but not specifying the fully qualified Protobuf message name, does not cause records to be written to the DLQ table. Instead, Redpanda pauses the topic data translation to the Iceberg table until you fix the misconfiguration. ### [](#inspect-dlq-table)Inspect DLQ table You can inspect the DLQ table for records that failed to write to the Iceberg table, and you can take further action on these records, such as transforming and reprocessing them, or debugging issues that occurred upstream. The following example produces a record to a topic named `ClickEvent` and does not use the Schema Registry wire format that includes the magic byte and schema ID: ```bash echo '"key1" {"user_id":2324,"event_type":"BUTTON_CLICK","ts":"2024-11-25T20:23:59.380Z"}' | rpk topic produce ClickEvent --format='%k %v\n' ``` Querying the DLQ table returns the record that was not translated: ```sql SELECT value FROM ."ClickEvent~dlq"; -- Fully qualified table name ``` ```bash +-------------------------------------------------+ | value | +-------------------------------------------------+ | 7b 22 75 73 65 72 5f 69 64 22 3a 32 33 32 34 2c | | 22 65 76 65 6e 74 5f 74 79 70 65 22 3a 22 42 55 | | 54 54 4f 4e 5f 43 4c 49 43 4b 22 2c 22 74 73 22 | | 3a 22 32 30 32 34 2d 31 31 2d 32 35 54 32 30 3a | | 32 33 3a 35 39 2e 33 38 30 5a 22 7d | +-------------------------------------------------+ ``` The data is in binary format, and the first byte is not `0x00`, indicating that it was not produced with a schema. ### [](#reprocess-dlq-records)Reprocess DLQ records You can apply a transformation and reprocess the record in your data lakehouse to the original Iceberg table. In this case, you have a JSON value represented as a UTF-8 binary. Depending on your query engine, you might need to decode the binary value first before extracting the JSON fields. Some engines may automatically decode the binary value for you: ClickHouse SQL example to reprocess DLQ record ```sql SELECT CAST(jsonExtractString(json, 'user_id') AS Int32) AS user_id, jsonExtractString(json, 'event_type') AS event_type, jsonExtractString(json, 'ts') AS ts FROM ( SELECT CAST(value AS String) AS json FROM .`ClickEvent~dlq` -- Ensure that the table name is properly parsed ); ``` ```bash +---------+--------------+--------------------------+ | user_id | event_type | ts | +---------+--------------+--------------------------+ | 2324 | BUTTON_CLICK | 2024-11-25T20:23:59.380Z | +---------+--------------+--------------------------+ ``` You can now insert the transformed record back into the main Iceberg table. Redpanda recommends employing a strategy for exactly-once processing to avoid duplicates when reprocessing records. ### [](#drop-invalid-records)Drop invalid records To disable the default behavior and drop an invalid record, set the [`redpanda.iceberg.invalid.record.action`](../../../reference/properties/topic-properties/#redpanda-iceberg-invalid-record-action) topic property to `drop`. You can also configure the default cluster-wide behavior for invalid records by setting the `iceberg_invalid_record_action` property. ## [](#performance-considerations)Performance considerations When you enable Iceberg for any substantial workload and start translating topic data to the Iceberg format, you may see most of your cluster’s CPU utilization increase. If this additional workload overwhelms the brokers and causes the Iceberg table lag to exceed the configured target lag, Redpanda automatically applies backpressure to producers to prevent Iceberg tables from lagging further. This ensures that Iceberg tables keep up with the volume of incoming data, but sacrifices ingress throughput of the cluster. You may need to increase the size of your Redpanda cluster to accommodate the additional workload. To ensure that your cluster is sized appropriately, contact the Redpanda Customer Success team. ### [](#use-custom-partitioning)Use custom partitioning To improve query performance, consider implementing custom [partitioning](https://iceberg.apache.org/docs/nightly/partitioning/) for the Iceberg topic. Use the [`redpanda.iceberg.partition.spec`](../../../reference/properties/topic-properties/#redpanda-iceberg-partition-spec) topic property to define the partitioning scheme: ```bash # Create new topic with five topic partitions, replication factor 3, and custom table partitioning for Iceberg rpk topic create -p5 -r3 -c redpanda.iceberg.mode=value_schema_id_prefix -c "redpanda.iceberg.partition.spec=(, , ...)" ``` Valid `` values include a source column name or a transformation of a column. The columns referenced can be Redpanda-defined (such as `redpanda.timestamp`) or user-defined based on a schema that you register for the topic. The Iceberg table stores records that share different partition key values in separate files based on this specification. For example: - To partition the table by a single key, such as a column `col1`, use: `redpanda.iceberg.partition.spec=(col1)`. - To partition by multiple columns, use a comma-separated list: `redpanda.iceberg.partition.spec=(col1, col2)`. - To partition by the year of a timestamp column `ts1`, and a string column `col1`, use: `redpanda.iceberg.partition.spec=(year(ts1), col1)`. To learn more about how partitioning schemes can affect query performance, and for details on the partitioning specification such as allowed transforms, see the [Apache Iceberg documentation](https://iceberg.apache.org/spec/#partitioning). > 💡 **TIP** > > - Partition by columns that you frequently use in queries. Columns with relatively few unique values, also known as low cardinality, are also good candidates for partitioning. > > - If you must partition based on columns with high cardinality, for example timestamps, use Iceberg’s available transforms such as extracting the year, month, or day to avoid creating too many partitions. Too many partitions can be detrimental to performance because more files need to be scanned and managed. ### [](#avoid-high-column-count)Avoid high column count A high column count or schema field count results in more overhead when translating topics to the Iceberg table format. Small message sizes can also increase CPU utilization. To minimize the performance impact on your cluster, keep to a low column count and large message size for Iceberg topics. ## [](#next-steps)Next steps - [Use Iceberg Catalogs](../use-iceberg-catalogs/) - [Migrate existing Iceberg integrations to Iceberg Topics](../migrate-to-iceberg-topics/) ## [](#suggested-reading)Suggested reading - [Server-Side Schema ID Validation](../../schema-reg/schema-id-validation/) - [Understanding Apache Kafka Schema Registry](https://www.redpanda.com/blog/schema-registry-kafka-streaming#how-does-serialization-work-with-schema-registry-in-kafka) ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) [Search all labs](/redpanda-labs) --- # Page 147: Query Iceberg Topics using AWS Glue **URL**: https://docs.redpanda.com/current/manage/iceberg/iceberg-topics-aws-glue.md --- # Query Iceberg Topics using AWS Glue --- title: Query Iceberg Topics using AWS Glue page-beta-text: This is a beta feature. Beta features are available for testing and feedback. They are not supported by Redpanda and should not be used in production environments. latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: iceberg/iceberg-topics-aws-glue page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: iceberg/iceberg-topics-aws-glue.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/iceberg/iceberg-topics-aws-glue.adoc description: Add Redpanda topics as Iceberg tables that you can query from AWS Glue Data Catalog. # Beta release status page-beta: "true" page-git-created-date: "2025-07-30" page-git-modified-date: "2026-04-08" support-status: supported release-status: beta - This is a beta feature. Beta features are available for testing and feedback. They are not supported by Redpanda and should not be used in production environments. --- beta > 📝 **NOTE** > > This feature requires an [enterprise license](../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../get-started/licensing/#self-managed) apply. This guide walks you through querying Redpanda topics as Iceberg tables stored in AWS S3, using a catalog integration with [AWS Glue](https://docs.aws.amazon.com/glue/latest/dg/components-overview.html#data-catalog-intro). For general information about Iceberg catalog integrations in Redpanda, see [Use Iceberg Catalogs](../use-iceberg-catalogs/). ## [](#prerequisites)Prerequisites - An AWS account with access to [AWS Glue Data Catalog](https://docs.aws.amazon.com/glue/latest/dg/what-is-glue.html). - Redpanda version 25.1.7 or later. - [`rpk`](../../../get-started/rpk-install/) installed or updated to the latest version. - [Object storage configured](../../tiered-storage/#configure-object-storage) for your cluster and [Tiered Storage enabled](../../tiered-storage/#enable-tiered-storage) for the topics for which you want to generate Iceberg tables. You also use the S3 bucket URI to set the base location for AWS Glue Data Catalog. - Admin permissions to create IAM policies and roles in AWS. ## [](#limitations)Limitations ### [](#lowercase-field-names-required)Lowercase field names required Use only lowercase field names. AWS Glue converts all table column names to lowercase, and Redpanda requires exact column name matches to manage schemas. Using uppercase letters prevents Redpanda from finding matching columns, which breaks schema management. ### [](#nested-partition-spec-support)Nested partition spec support AWS Glue does not support partitioning on nested fields. If Redpanda detects that the default partitioning `(hour(redpanda.timestamp))` based on the record metadata is in use, it will instead apply an empty partition spec `()`, which means the table will not be partitioned. To use partitioning, you must implement custom partitioning using your own partition columns (that is, columns that are not nested). > 📝 **NOTE** > > In Redpanda versions 25.2.1 and earlier, an empty partition spec `()` can cause a known issue that prevents certain engines like Amazon Redshift from successfully querying the table. To resolve this issue, specify custom partitioning, or upgrade Redpanda to versions 25.2.2 or later. ### [](#manual-deletion-of-iceberg-tables)Manual deletion of Iceberg tables The AWS Glue catalog integration does not support automatic deletion of Iceberg tables from Redpanda. To manually delete Iceberg tables in AWS Glue, you must either: - Set the cluster property `[iceberg_delete](../../../reference/properties/cluster-properties/#iceberg_delete)` to `false` when you configure the catalog integration. - Override the cluster property `iceberg_delete` by setting the topic property [`redpanda.iceberg.delete`](../../../reference/properties/topic-properties/#redpanda-iceberg-delete) to `false` for the topic you want to delete. When `iceberg_delete` or the topic override `redpanda.iceberg.delete` is set to `false`, you can delete the Redpanda topic, and then delete the table in AWS Glue and the Iceberg data and metadata files in the S3 bucket. If you plan to re-create the topic after deleting it, you must delete the table data entirely before re-creating the topic. ## [](#authorize-access-to-aws-glue)Authorize access to AWS Glue You must allow Redpanda access to AWS Glue services in your AWS account. You can use the same access credentials that you configured for S3 (IAM role, access keys, and KMS key), as long as you have also added read and write access to AWS Glue Data Catalog. For example, you could create a separate IAM policy that manages access to AWS Glue and attach it to the IAM role that Redpanda also uses to access S3. Add all AWS Glue API actions in the policy (`"glue:*"`) on the following resources: - Root catalog (`catalog`) - All databases (`database/*`) - All tables (`table/*/*`) Your IAM policy should include a statement similar to the following: ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "glue:*" ], "Resource": [ "arn:aws:glue:::catalog", "arn:aws:glue:::database/*", "arn:aws:glue:::table/*/*" ] } ] } ``` For more information on configuring IAM permissions, see the [AWS Glue documentation](https://docs.aws.amazon.com/glue/latest/dg/configure-iam-for-glue.html). ## [](#configure-authentication-and-credentials)Configure authentication and credentials You must configure credentials for the AWS Glue Data Catalog integration in either of the following ways: - Allow Redpanda to use the same `cloud_storage_*` credential properties configured for S3. This is the recommended approach. - If you want to configure authentication to AWS Glue separately from authentication to S3, there are equivalent credential configuration properties named `iceberg_rest_catalog_aws_*` that override the object storage credentials. These properties only apply to REST catalog authentication, and never to S3 authentication: - `[iceberg_rest_catalog_credentials_source](../../../reference/properties/cluster-properties/#iceberg_rest_catalog_credentials_source)` overrides `[cloud_storage_credentials_source](../../../reference/properties/cluster-properties/#cloud_storage_credentials_source)` - `[iceberg_rest_catalog_aws_access_key](../../../reference/properties/cluster-properties/#iceberg_rest_catalog_aws_access_key)` overrides `[cloud_storage_access_key](../../../reference/properties/cluster-properties/#cloud_storage_access_key)` - `[iceberg_rest_catalog_aws_secret_key](../../../reference/properties/cluster-properties/#iceberg_rest_catalog_aws_secret_key)` overrides `[cloud_storage_secret_key](../../../reference/properties/cluster-properties/#cloud_storage_secret_key)` - `[iceberg_rest_catalog_aws_region](../../../reference/properties/cluster-properties/#iceberg_rest_catalog_aws_region)` overrides `[cloud_storage_region](../../../reference/properties/cluster-properties/#cloud_storage_region)` ## [](#update-cluster-configuration)Update cluster configuration To configure your Redpanda cluster to enable Iceberg on a topic and integrate with the AWS Glue Data Catalog: 1. Edit your cluster configuration to set the `iceberg_enabled` property to `true`, and set the catalog integration properties listed in the example below. By default, Redpanda creates Iceberg tables in a namespace called `redpanda`. Because AWS Glue provides a single catalog per account, each Redpanda cluster that writes to the same Glue catalog must use a distinct namespace to avoid table name collisions. To set a unique namespace, also set `[iceberg_default_catalog_namespace](../../../reference/properties/cluster-properties/#iceberg_default_catalog_namespace)` when you set `iceberg_enabled`. This property cannot be changed after Iceberg is enabled. Run `rpk cluster config edit` to update these properties: ```bash iceberg_enabled: true # Set a custom namespace instead of the default "redpanda" iceberg_default_catalog_namespace: [""] # Glue requires Redpanda Iceberg tables to be manually deleted iceberg_delete: false iceberg_catalog_type: rest iceberg_rest_catalog_endpoint: https://glue..amazonaws.com/iceberg iceberg_rest_catalog_authentication_mode: aws_sigv4 # Because Redpanda does not support the use of distinct buckets for Iceberg, # always place iceberg_rest_catalog_base_location in the same S3 bucket as cloud_storage_bucket iceberg_rest_catalog_base_location: s3:/// # Use the iceberg_rest_catalog_aws_* properties if you want to # use separate AWS credentials for the catalog, or omit these lines to reuse S3 # (cloud_storage_*) credentials. # For access using access keys only, use iceberg_rest_catalog_aws_access_key # and iceberg_rest_catalog_aws_secret_key. For access with an IAM role, use # iceberg_rest_catalog_credentials_source only. # iceberg_rest_catalog_aws_region: # iceberg_rest_catalog_aws_access_key: # iceberg_rest_catalog_aws_secret_key: # iceberg_rest_catalog_credentials_source: ``` Use your own values for the following placeholders: - ``: The AWS region where your Data Catalog is located. The region in the AWS Glue endpoint must match the region specified in either your `[cloud_storage_region](../../../reference/properties/cluster-properties/#cloud_storage_region)` or `[iceberg_rest_catalog_aws_region](../../../reference/properties/cluster-properties/#iceberg_rest_catalog_aws_region)` property. - `` and ``: AWS Glue requires you to specify the base location where Redpanda stores Iceberg data and metadata files. You must use an S3 URI; for example, `s3:///iceberg`. This must be the same bucket used for object storage (your `cloud_storage_bucket`). You cannot specify a different bucket for Iceberg data. `` is a name you choose (such as `iceberg`) as the logical name for the warehouse represented by all Redpanda Iceberg topic data in the cluster. As a security best practice, do not use the bucket root for the base location. Always specify a subfolder to avoid interfering with your cluster’s data in object storage. ```bash Successfully updated configuration. New configuration version is 2. ``` 2. If you change the configuration for a running cluster, you must restart that cluster now. 3. Enable the integration for a topic by configuring the topic property `redpanda.iceberg.mode`. The following examples show how to use [`rpk`](../../../get-started/rpk-install/) to either create a new topic or alter the configuration for an existing topic and set the Iceberg mode to `key_value`. The `key_value` mode creates a two-column Iceberg table for the topic, with one column for the record metadata including the key, and another binary column for the record’s value. See [Specify Iceberg Schema](../specify-iceberg-schema/) for more details on Iceberg modes. Create a new topic and set `redpanda.iceberg.mode`: ```bash rpk topic create --topic-config=redpanda.iceberg.mode=key_value ``` Set `redpanda.iceberg.mode` for an existing topic: ```bash rpk topic alter-config --set redpanda.iceberg.mode=key_value ``` 4. Produce to the topic. For example, ```bash echo "hello world\nfoo bar\nbaz qux" | rpk topic produce --format='%k %v\n' ``` You should see the topic as a table with data in AWS Glue Data Catalog. The data may take some time to become visible, depending on your `[iceberg_target_lag_ms](../../../reference/properties/cluster-properties/#iceberg_target_lag_ms)` setting. 1. In AWS Glue Studio, go to Databases. 2. Select the `redpanda` database. The `redpanda` database and the table within are automatically added for you. The table name is the same as the topic name. ## [](#query-iceberg-table)Query Iceberg table You can query the Iceberg table using different engines, such as Amazon Athena, PyIceberg, or Apache Spark. To query the table or view the table data in AWS Glue, ensure that your account has the necessary permissions to access the catalog, database, and table. To query the table in Amazon Athena: 1. On the list of tables in AWS Glue Studio, click "Table data" under the **View data** column. 2. Click "Proceed" to be redirected to the Athena query editor. 3. In the query editor, select AwsDataCatalog as the data source, and select the `redpanda` database. If you set a custom namespace for your cluster, select that database instead of `redpanda`. 4. The SQL query editor should be pre-populated with a query that selects 10 rows from the Iceberg table. Run the query to see a preview of the table data. ```sql SELECT * FROM "AwsDataCatalog"."redpanda"."" limit 10; ``` Your query results should look like the following: ```sql +-----------------------------------------------------+----------------+ | redpanda | value | +-----------------------------------------------------+----------------+ | {partition=0, offset=0, timestamp=2025-07-21 | 77 6f 72 6c 64 | | 18:11:25.070000, headers=null, key=[B@1900af31} | | +-----------------------------------------------------+----------------+ ``` ## [](#suggested-reading)Suggested reading - [Query Iceberg Topics](../query-iceberg-topics/) ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) [Search all labs](/redpanda-labs) --- # Page 148: Query Iceberg Topics using Databricks and Unity Catalog **URL**: https://docs.redpanda.com/current/manage/iceberg/iceberg-topics-databricks-unity.md --- # Query Iceberg Topics using Databricks and Unity Catalog --- title: Query Iceberg Topics using Databricks and Unity Catalog latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: iceberg/iceberg-topics-databricks-unity page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: iceberg/iceberg-topics-databricks-unity.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/iceberg/iceberg-topics-databricks-unity.adoc description: Add Redpanda topics as Iceberg tables that you can query in Databricks managed by Unity Catalog. page-git-created-date: "2025-06-12" page-git-modified-date: "2026-04-06" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../get-started/licensing/#self-managed) apply. This guide walks you through querying Redpanda topics as managed Iceberg tables in Databricks, with AWS S3 as object storage and a catalog integration using [Unity Catalog](https://docs.databricks.com/aws/en/data-governance/unity-catalog). For general information about Iceberg catalog integrations in Redpanda, see [Use Iceberg Catalogs](../use-iceberg-catalogs/). ## [](#prerequisites)Prerequisites - [Object storage configured](../../tiered-storage/#configure-object-storage) for your cluster and [Tiered Storage enabled](../../tiered-storage/#enable-tiered-storage) for the topics for which you want to generate Iceberg tables. You need the AWS S3 bucket URI, so you can configure it as an external location in Unity Catalog. - A Databricks workspace in the same region as your S3 bucket. See the [list of supported AWS regions](https://docs.databricks.com/aws/en/resources/supported-regions#supported-regions-list). - Unity Catalog enabled in your Databricks workspace. See the [Databricks documentation](https://docs.databricks.com/aws/en/data-governance/unity-catalog/get-started) to set up Unity Catalog for your workspace. - [Predictive optimization](https://docs.databricks.com/aws/en/optimizations/predictive-optimization#enable-predictive-optimization) enabled for Unity Catalog. > 📝 **NOTE** > > When you enable predictive optimization, you must also set the following configurations in your Databricks workspace. These configurations allow predictive optimization to automatically generate column statistics and carry out background compaction for Iceberg tables: > > ```sql > SET spark.databricks.delta.liquid.lazyClustering.backfillStats=true; > SET spark.databricks.delta.computeStats.autoConflictResolution=true; > > /* > After setting these configurations, you can optionally run OPTIMIZE to > immediately trigger compaction and liquid clustering, or let predictive > optimization handle it automatically later. > */ > OPTIMIZE ``.redpanda.``; > ``` - [External data access](https://docs.databricks.com/aws/en/external-access/admin) enabled in your metastore. - Workspace admin privileges to complete the steps to create a Unity Catalog storage credential and external location that connects your cluster’s Tiered Storage bucket to Databricks. ## [](#limitations)Limitations The following data types are not currently supported for managed Iceberg tables: | Iceberg type | Equivalent Avro type | | --- | --- | | uuid | uuid | | fixed(L) | fixed | | time | time-millis, time-micros | There are no limitations for Protobuf types. ## [](#create-a-unity-catalog-storage-credential)Create a Unity Catalog storage credential A storage credential is a Databricks object that controls access to external object storage, in this case S3. You associate a storage credential with an AWS IAM role that defines what actions Unity Catalog can perform in the S3 bucket. Follow the steps in the [Databricks documentation](https://docs.databricks.com/aws/en/connect/unity-catalog/cloud-storage/storage-credentials) to create an AWS IAM role that has the required permissions for the bucket. When you have completed these steps, you should have the following configured in AWS and Databricks: - A self-assuming IAM role, meaning you’ve defined the role trust policy so the role trusts itself. - Two IAM policies attached to the IAM role. The first policy grants Unity Catalog read and write access to the bucket. The second policy allows Unity Catalog to configure file events. - A storage credential in Databricks associated with the IAM role, using the role’s ARN. You also use the storage credential’s external ID in the role’s trust relationship policy to make the role self-assuming. ## [](#create-a-unity-catalog-external-location)Create a Unity Catalog external location The external location stores the Unity Catalog-managed Iceberg metadata, and the Iceberg data written by Redpanda. You must use the same bucket configured for [Tiered Storage](https://docs.redpanda.com/current/reference/glossary/#tiered-storage) for your Redpanda cluster. Follow the steps in the [Databricks documentation](https://docs.databricks.com/aws/en/connect/unity-catalog/cloud-storage/external-locations) to **manually** create an external location. You can create the external location in the Catalog Explorer or with SQL. You must create the external location manually because the location needs to be associated with the existing Tiered Storage bucket URL, `s3://`. ## [](#create-a-new-catalog)Create a new catalog Follow the steps in the Databricks documentation to [create a standard catalog](https://docs.databricks.com/aws/en/catalogs/create-catalog). When you create the catalog, specify the external location you created in the previous step as the storage location. You use the catalog name when you set the Iceberg cluster configuration properties in Redpanda in a later step. ## [](#authorize-access-to-unity-catalog)Authorize access to Unity Catalog Redpanda recommends using OAuth for service principals to grant Redpanda access to Unity Catalog. 1. Follow the steps in the [Databricks documentation](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-m2m) to create a service principal, and then generate an OAuth secret. You use the client ID and secret to set Iceberg cluster configuration properties in Redpanda in the next step. 2. Open your catalog in the Catalog Explorer, then click **Permissions**. 3. Click **Grant** to grant the service principal the following permissions on the catalog: - `ALL PRIVILEGES` - `EXTERNAL USE SCHEMA` The Iceberg integration for Redpanda also supports using bearer tokens. ## [](#update-cluster-configuration)Update cluster configuration To configure your Redpanda cluster to enable Iceberg on a topic and integrate with Unity Catalog: 1. Edit your cluster configuration to set the `iceberg_enabled` property to `true`, and set the catalog integration properties listed in the example below. Run `rpk cluster config edit` to update these properties: ```bash iceberg_enabled: true iceberg_catalog_type: rest iceberg_rest_catalog_endpoint: https:///api/2.1/unity-catalog/iceberg-rest iceberg_rest_catalog_authentication_mode: oauth2 iceberg_rest_catalog_oauth2_server_uri: https:///oidc/v1/token iceberg_rest_catalog_oauth2_scope: all-apis iceberg_rest_catalog_client_id: iceberg_rest_catalog_client_secret: iceberg_rest_catalog_warehouse: iceberg_disable_snapshot_tagging: true ``` Use your own values for the following placeholders: - ``: The URL of your [Databricks workspace instance](https://docs.databricks.com/aws/en/workspace/workspace-details#workspace-instance-names-urls-and-ids); for example, `cust-success.cloud.databricks.com`. - ``: The client ID of the service principal you created in an earlier step. - ``: The client secret of the service principal you created in an earlier step. - ``: The name of your catalog in Unity Catalog. ```bash Successfully updated configuration. New configuration version is 2. ``` 2. You must restart your cluster if you change the configuration for a running cluster. 3. Enable the integration for a topic by configuring the topic property `redpanda.iceberg.mode`. The following examples show how to use [`rpk`](../../../get-started/rpk-install/) to either create a new topic or alter the configuration for an existing topic and set the Iceberg mode to `key_value`. The `key_value` mode creates an Iceberg table for the topic consisting of two columns, one for the record metadata including the key, and another binary column for the record’s value. See [Specify Iceberg Schema](../specify-iceberg-schema/) for more details on Iceberg modes. Create a new topic and set `redpanda.iceberg.mode`: ```bash rpk topic create --topic-config=redpanda.iceberg.mode=key_value ``` Set `redpanda.iceberg.mode` for an existing topic: ```bash rpk topic alter-config --set redpanda.iceberg.mode=key_value ``` 4. Produce to the topic. For example, ```bash echo "hello world\nfoo bar\nbaz qux" | rpk topic produce --format='%k %v\n' ``` You should see the topic as a table with data in Unity Catalog. The data may take some time to become visible, depending on your `[iceberg_target_lag_ms](../../../reference/properties/cluster-properties/#iceberg_target_lag_ms)` setting. 1. In Catalog Explorer, open your catalog. You should see a `redpanda` schema (or the namespace you configured with `[iceberg_default_catalog_namespace](../../../reference/properties/cluster-properties/#iceberg_default_catalog_namespace)`), in addition to `default` and `information_schema`. 2. The schema and the table residing within it are automatically added for you. The table name is the same as the topic name. ## [](#query-iceberg-table-using-databricks-sql)Query Iceberg table using Databricks SQL You can query the Iceberg table using different engines, such as Databricks SQL, PyIceberg, or Apache Spark. To query the table or view the table data in Catalog Explorer, ensure that your account has the necessary permissions to read the table. Review the Databricks documentation on [granting permissions to objects](https://docs.databricks.com/aws/en/data-governance/unity-catalog/manage-privileges/?language=SQL#grant-permissions-on-objects-in-a-unity-catalog-metastore) and [Unity Catalog privileges](https://docs.databricks.com/aws/en/data-governance/unity-catalog/manage-privileges/privileges) for details. The following example shows how to query the Iceberg table using SQL in Databricks SQL. 1. In the Databricks console, open **SQL Editor**. 2. In the query editor, run: ```sql -- Ensure that the catalog and table name are correctly parsed in case they contain special characters SELECT * FROM ``.redpanda.`` LIMIT 10; ``` Your query results should look like the following: ```sql -- Example for redpanda.iceberg.mode=key_value with 1 record produced to topic +----------------------------------------------------------------------+------------+ | redpanda | value | +----------------------------------------------------------------------+------------+ | {"partition":0,"offset":"0","timestamp":"2025-04-02T18:57:11.127Z", | 776f726c64 | | "headers":null,"key":"68656c6c6f"} | | +----------------------------------------------------------------------+------------+ ``` ## [](#suggested-reading)Suggested reading - [Query Iceberg Topics](../query-iceberg-topics/) ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) [Search all labs](/redpanda-labs) --- # Page 149: Use Iceberg Topics with GCP BigLake **URL**: https://docs.redpanda.com/current/manage/iceberg/iceberg-topics-gcp-biglake.md --- # Use Iceberg Topics with GCP BigLake --- title: Use Iceberg Topics with GCP BigLake latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: iceberg/iceberg-topics-gcp-biglake page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: iceberg/iceberg-topics-gcp-biglake.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/iceberg/iceberg-topics-gcp-biglake.adoc description: Add Redpanda topics as Iceberg tables to your Google BigLake data lakehouse that you can query from Google BigQuery. page-git-created-date: "2025-11-19" page-git-modified-date: "2025-11-27" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../get-started/licensing/#self-managed) apply. > 💡 **TIP** > > This guide is for integrating Iceberg topics with a managed REST catalog. Integrating with a REST catalog is recommended for production deployments. If it is not possible to use a REST catalog, you can use the [filesystem-based catalog](../use-iceberg-catalogs/#object-storage). For an example of using the filesystem-based catalog to access Iceberg topics, see the [Getting Started with Iceberg Topics on Redpanda BYOC](https://www.redpanda.com/blog/iceberg-topics-redpanda-cloud-byoc-setup) blog post. > > The blog post uses a Redpanda Cloud cluster, but you follow the same steps for a Self-Managed cluster. This guide walks you through querying Redpanda topics as Iceberg tables stored in Google Cloud Storage, using a REST catalog integration with [Google BigLake](https://cloud.google.com/biglake/docs/introduction). In this guide, you do the following: - Create Google Cloud resources such as a storage bucket and service account - Grant permissions to the service account to access Iceberg data in the bucket - Create a catalog in BigLake - Configure the BigLake integration for your Redpanda cluster - Query the Iceberg data in Google BigQuery This guide also includes optional steps to deploy a Redpanda quickstart cluster on a GCP VM instance using Docker Compose, which you can use to quickly test the BigLake Iceberg integration. For general information about Iceberg catalog integrations in Redpanda, see [Use Iceberg Catalogs](../use-iceberg-catalogs/). > 📝 **NOTE** > > Check the [BigLake product page](https://cloud.google.com/biglake) for the latest status and availability of the REST Catalog API. ## [](#prerequisites)Prerequisites - A Google Cloud Platform (GCP) project. If you do not have permissions to manage GCP resources such as VMs, storage buckets, and service accounts in your project, ask your project owner to create or update them for you. - The [`gcloud` CLI](https://docs.cloud.google.com/sdk/docs/install) installed and configured for your GCP project. - [BigLake API](https://cloud.google.com/biglake/docs/enable-biglake-api) enabled for your GCP project. - Redpanda v26.1.3 or later. Your Redpanda cluster must be deployed on GCP VMs. - `rpk` [installed or updated](../../../get-started/rpk-install/) to the latest version. - [Object storage configured](../../tiered-storage/#configure-object-storage) for your cluster and [Tiered Storage enabled](../../tiered-storage/#enable-tiered-storage) for the topics for which you want to generate Iceberg tables. You also use the GCS bucket URI to set the warehouse location for the BigLake catalog. ## [](#limitations)Limitations ### [](#multi-region-bucket-support)Multi-region bucket support BigLake metastore does not support multi-region buckets. Use single-region buckets to store your Iceberg topics. ### [](#catalog-deletion)Catalog deletion Currently, it is not possible to delete non-empty BigLake Iceberg catalogs through the BigLake interface. If you need to reconfigure your setup, create a new bucket or use the REST API to remove the existing catalog. ### [](#topic-names)Topic names BigLake does not support Iceberg table names that contain dots (`.`). When creating Iceberg topics in Redpanda that you plan to access through BigLake, either: - Use the `iceberg_topic_name_dot_replacement` cluster property to set a replacement string for dots in topic names. Ensure that the replacement value does not cause table name collisions. For example, `current.orders` and `current_orders` would both map to the same table name if you set the replacement to an underscore (`_`). - Ensure that the new topic names do not include dots. You must also set the `iceberg_dlq_table_suffix` property to a value that does not include dots or tildes (`~`). See [Configure Redpanda for Iceberg](#configure-redpanda-for-iceberg) for the list of cluster properties to set when enabling the BigLake REST catalog integration. ## [](#set-up-google-cloud-resources)Set up Google Cloud resources ### [](#create-a-service-account-for-redpanda)Create a service account for Redpanda If you don’t already have a Google Cloud service account to use, create a new service account that will be used by the VMs running Redpanda. Redpanda uses this account for writing data to Tiered Storage, Iceberg data and metadata, and for interacting with the BigLake catalog: ```bash gcloud iam service-accounts create --display-name "" ``` Replace the placeholder values: - ``: You can use a [name](https://docs.cloud.google.com/iam/docs/service-accounts-create) that contains lowercase alphanumeric characters and dashes. - ``: Enter a display name for the service account. ### [](#grant-required-permissions)Grant required permissions Grant the necessary permissions to your service account. To run the following commands, replace the placeholder values: - ``: The name of your service account. - ``: The name of your storage bucket. 1. Grant the service account the [Storage Object Admin role](https://docs.cloud.google.com/storage/docs/access-control/iam-roles) to access the bucket: ```bash gcloud storage buckets add-iam-policy-binding gs:// \ --member="serviceAccount:@$(gcloud config get-value project).iam.gserviceaccount.com" \ --role="roles/storage.objectAdmin" ``` 2. Grant [Service Usage Consumer](https://docs.cloud.google.com/iam/docs/roles-permissions/serviceusage) and [BigLake Editor](https://docs.cloud.google.com/iam/docs/roles-permissions/biglake#biglake.editor) roles for using the Iceberg REST catalog: ```bash gcloud projects add-iam-policy-binding $(gcloud config get-value project) \ --member="serviceAccount:@$(gcloud config get-value project).iam.gserviceaccount.com" \ --role="roles/serviceusage.serviceUsageConsumer" gcloud projects add-iam-policy-binding $(gcloud config get-value project) \ --member="serviceAccount:@$(gcloud config get-value project).iam.gserviceaccount.com" \ --role="roles/biglake.editor" ``` ### [](#create-a-biglake-catalog)Create a BigLake catalog Create a BigLake Iceberg REST catalog using the `gcloud` CLI: > 📝 **NOTE** > > This command is currently pre-GA and may change. Check the [gcloud reference](https://docs.cloud.google.com/sdk/gcloud/reference/alpha/biglake/iceberg/catalogs/create) for the latest information. ```bash gcloud alpha biglake iceberg catalogs create --catalog-type=gcs-bucket --project= ``` Replace the placeholder values: - ``: Use the name of your storage bucket as the catalog ID. - ``: Your GCP project ID. ## [](#optional-deploy-redpanda-quickstart-on-gcp)Optional: Deploy Redpanda quickstart on GCP If you want to quickly test Iceberg topics in BigLake, you can deploy a test environment using the Redpanda Self-Managed quickstart. In this section, you create a new storage bucket for Tiered Storage and Iceberg data. You configure a Redpanda cluster for the BigLake catalog integration and deploy the cluster on a GCP Linux VM instance using Docker Compose. > 📝 **NOTE** > > If you already have a Redpanda cluster deployed on GCP, skip to [Configure Redpanda for Iceberg](#configure-redpanda-for-iceberg). ### [](#create-a-storage-bucket)Create a storage bucket Create a new Google Cloud Storage bucket to store Iceberg data: ```bash gcloud storage buckets create gs:// --location= ``` Replace the placeholder values: - ``: A globally unique name for your bucket. - ``: The region where you want to create the bucket, for example, `europe-west2`. > 📝 **NOTE** > > Ensure that the service account you created earlier has the [required permissions](#grant-required-permissions) to access this bucket. ### [](#create-vm-instances)Create VM instances Create a VM instance to run Redpanda: ```bash gcloud compute instances create \ --zone= \ --machine-type=e2-medium \ --service-account=@$(gcloud config get-value project).iam.gserviceaccount.com \ --scopes=https://www.googleapis.com/auth/cloud-platform \ --create-disk=auto-delete=yes,boot=yes,device-name=,image=projects/debian-cloud/global/images/debian-12-bookworm-v20251014,mode=rw,size=20,type=pd-standard ``` Replace the placeholder values: - ``: A name for your VM instance. - ``: The name of the service account you created earlier. - ``: The fully-qualified zone name, for example, `europe-west2-a`. ### [](#install-and-configure-redpanda)Install and configure Redpanda 1. Connect to your VM instance. It may take a few moments for the instance to be ready to accept SSH connections: ```bash gcloud compute ssh --zone ``` 2. Install Docker and Docker Compose following the [Docker installation guide](https://docs.docker.com/engine/install/debian/) for Debian. ```bash # Add Docker's official GPG key: sudo apt-get update sudo apt-get install ca-certificates curl sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc sudo chmod a+r /etc/apt/keyrings/docker.asc # Add the repository to Apt sources: echo \ "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \ $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \ sudo tee /etc/apt/sources.list.d/docker.list > /dev/null sudo apt-get update # Install Docker Engine, CLI, and Compose sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin ``` 3. Download the Redpanda Self-Managed quickstart files: ```bash mkdir redpanda-quickstart && cd redpanda-quickstart && \ (1) curl -sSL https://docs.redpanda.com/redpanda-quickstart.tar.gz | tar xzf - && \ (2) cd docker-compose (3) ``` | 1 | Create and navigate to the redpanda-quickstart directory. | | --- | --- | | 2 | Download and extract the archive. | | 3 | Navigate to the Docker Compose configuration directory. | 4. Edit the `bootstrap.yaml` file to enable Tiered Storage and Iceberg features. Add or modify these sections: ```yaml # Enable Tiered Storage cloud_storage_enabled: true cloud_storage_region: n/a # GCP does not require region to be set cloud_storage_api_endpoint: storage.googleapis.com cloud_storage_api_endpoint_port: 443 cloud_storage_disable_tls: false cloud_storage_bucket: cloud_storage_credentials_source: gcp_instance_metadata # Configure Iceberg REST catalog integration with BigLake iceberg_enabled: true iceberg_catalog_type: rest iceberg_rest_catalog_endpoint: https://biglake.googleapis.com/iceberg/v1/restcatalog iceberg_rest_catalog_oauth2_server_uri: https://oauth2.googleapis.com/token iceberg_rest_catalog_authentication_mode: gcp iceberg_rest_catalog_warehouse: gs:/// iceberg_rest_catalog_gcp_user_project: iceberg_dlq_table_suffix: _dlq ``` - Replace `` with your bucket name and `` with your Google Cloud project ID. - You must set the `iceberg_dlq_table_suffix` property to a value that does not include dots or tildes (`~`). The example above uses `_dlq` as the suffix for the [dead-letter queue (DLQ) table](../about-iceberg-topics/#troubleshoot-errors). > 📝 **NOTE** > > If you edit `bootstrap.yml`, you can skip the cluster configuration step in [Configure Redpanda for Iceberg](#configure-redpanda-for-iceberg) and proceed to the next step in that section to enable Iceberg for a topic. 5. Start Redpanda: ```bash docker compose up -d ``` 6. Install and configure `rpk`: ```bash sudo apt-get install unzip curl -LO https://github.com/redpanda-data/redpanda/releases/latest/download/rpk-linux-amd64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-linux-amd64.zip -d ~/.local/bin/ rpk profile create quickstart --from-profile rpk-profile.yaml ``` ## [](#configure-redpanda-for-iceberg)Configure Redpanda for Iceberg 1. Edit your cluster configuration to set the `iceberg_enabled` property to `true`, and set the catalog integration properties listed in the example below. Run `rpk cluster config edit` to update these properties: ```yaml iceberg_enabled: true iceberg_catalog_type: rest iceberg_rest_catalog_endpoint: https://biglake.googleapis.com/iceberg/v1/restcatalog iceberg_rest_catalog_oauth2_server_uri: https://oauth2.googleapis.com/token iceberg_rest_catalog_authentication_mode: gcp iceberg_rest_catalog_warehouse: gs:/// iceberg_rest_catalog_gcp_user_project: iceberg_dlq_table_suffix: _dlq ``` - Replace `` with your bucket name and `` with your Google Cloud project ID. - You must set the `iceberg_dlq_table_suffix` property to a value that does not include dots or tildes (`~`). The example above uses `_dlq` as the suffix for the [dead-letter queue (DLQ) table](../about-iceberg-topics/#troubleshoot-errors). 2. If you change the configuration for a running cluster, you must restart that cluster now. 3. Enable the REST catalog integration for a topic by configuring the topic property `redpanda.iceberg.mode`. The following examples show how to use [`rpk`](../../../get-started/rpk-install/) to either create a new topic or alter the configuration for an existing topic and set the Iceberg mode to `key_value`. The `key_value` mode creates a two-column Iceberg table for the topic, with one column for the record metadata including the key, and another binary column for the record’s value. See [Specify Iceberg Schema](../specify-iceberg-schema/) for more details on Iceberg modes. Create a new topic and set `redpanda.iceberg.mode`: ```bash rpk topic create --topic-config=redpanda.iceberg.mode=key_value ``` Set `redpanda.iceberg.mode` for an existing topic: ```bash rpk topic alter-config --set redpanda.iceberg.mode=key_value ``` > 📝 **NOTE** > > If you’re using the Self-managed quickstart for testing, your Redpanda cluster includes a `transactions` topic with data in it, and a sample schema in the Schema Registry. To enable Iceberg for the `transactions` topic, run: > > ```bash > rpk topic alter-config transactions --set redpanda.iceberg.mode=value_schema_latest:subject=transactions > ``` It may take a few moments for the Iceberg data to become available in BigLake. ## [](#query-iceberg-topics-in-bigquery)Query Iceberg topics in BigQuery 1. Navigate to the [BigQuery console](https://console.cloud.google.com/bigquery). 2. Query your Iceberg topic using SQL. For example, to query the `transactions` topic in the quickstart cluster: ```sql SELECT * FROM `>redpanda`.transactions ORDER BY redpanda.timestamp DESC LIMIT 10 ``` Replace `` with your bucket name. Your Redpanda topic is now available as Iceberg tables in BigLake, allowing you to run analytics queries directly on your streaming data. ## [](#optional-clean-up-resources)Optional: Clean up resources When you’re finished with the quickstart example, you can clean up the resources you created: ```bash # Delete VM instances gcloud compute instances delete --zone= # Delete the storage bucket gcloud storage buckets delete gs:// # Delete the service account gcloud iam service-accounts delete @$(gcloud config get-value project).iam.gserviceaccount.com ``` > 📝 **NOTE** > > Manually delete the BigLake catalog using the [REST API](https://docs.cloud.google.com/bigquery/docs/reference/biglake/rest/v1/projects.locations.catalogs/delete). ## [](#suggested-reading)Suggested reading - [Use Iceberg Catalogs](../use-iceberg-catalogs/) - [Query Iceberg Topics](../query-iceberg-topics/) - [Google BigLake documentation](https://cloud.google.com/biglake/docs/introduction) ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) [Search all labs](/redpanda-labs) --- # Page 150: Migrate to Iceberg Topics **URL**: https://docs.redpanda.com/current/manage/iceberg/migrate-to-iceberg-topics.md --- # Migrate to Iceberg Topics --- title: Migrate to Iceberg Topics latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: iceberg/migrate-to-iceberg-topics page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: iceberg/migrate-to-iceberg-topics.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/iceberg/migrate-to-iceberg-topics.adoc description: Migrate existing Iceberg integrations to Redpanda Iceberg topics. page-topic-type: how-to learning-objective-1: Compare external Iceberg integrations with Iceberg Topics architectures learning-objective-2: Implement data merge strategies using SQL patterns learning-objective-3: Execute validation checks and perform cutover procedures page-git-created-date: "2026-02-28" page-git-modified-date: "2026-02-28" support-status: supported --- Migrate existing Iceberg pipelines to Redpanda Iceberg topics to simplify your architecture and reduce operational overhead. After reading this page, you will be able to: - Compare external Iceberg integrations with Iceberg Topics architectures - Implement data merge strategies using SQL patterns - Execute validation checks and perform cutover procedures ## [](#why-migrate-to-iceberg-topics)Why migrate to Iceberg Topics Redpanda’s built-in Iceberg-enabled topics offer a simpler alternative to external Iceberg integrations for writing streaming data to Iceberg tables. > 📝 **NOTE** > > This page focuses on migrating from Kafka Connect Iceberg Sink. The migration patterns and SQL examples can be adapted for other Iceberg sources such as Apache Flink or Spark. ### [](#kafka-connect-iceberg-sink-comparison)Kafka Connect Iceberg Sink comparison The following table compares Kafka Connect Iceberg Sink with Redpanda Iceberg Topics: | Aspect | Kafka Connect Iceberg Sink | Iceberg Topics | | --- | --- | --- | | Infrastructure | Requires external Kafka Connect cluster | Built into Redpanda brokers | | Dependencies | Separate service to manage | No external dependencies | | Setup time | Medium (deploy connector) | Fast (enable topic property and post schema) | ## [](#prerequisites)Prerequisites To migrate from an existing Iceberg integration to Iceberg Topics, you must have: - [Tiered Storage](../../tiered-storage/) enabled. - [Iceberg Topics](../about-iceberg-topics/) enabled on your Redpanda cluster. - Understanding of your current schema format (Avro, Protobuf, or JSON Schema). - For Kafka Connect migrations, knowledge of your Kafka Connect configuration, especially if using `iceberg.tables.route-field` for multi-table routing. - If migrating multi-table fan-out patterns, [data transforms](../../../develop/data-transforms/how-transforms-work/) enabled on your cluster. - Access to both source and target (Iceberg Topics) tables in your query engine. - Query engine access (Snowflake, Databricks, ClickHouse, or Spark) for data merging. ## [](#migration-steps)Migration steps Redpanda recommends following a phased approach to ensure data consistency and minimize risk: 1. Enable Iceberg on target topics and verify new data flows. 2. Run both systems concurrently during transition. 3. Choose a strategy to combine historical and new data. 4. Verify data completeness and accuracy. 5. Disable the external Iceberg integration. > ❗ **IMPORTANT** > > Iceberg Topics cannot append to existing Iceberg tables that are not created by Redpanda. You must create new Iceberg tables and merge historical data separately. ### [](#enable-iceberg-topics)Enable Iceberg Topics For simple migrations (one topic mapping to one Iceberg table), enable the Iceberg integration for your Redpanda topics. 1. Set the `iceberg_enabled` configuration property on your cluster to `true`: ```bash rpk cluster config set iceberg_enabled true ``` If you change this configuration for a running cluster, restart the cluster. 2. Configure the `redpanda.iceberg.mode` property for the topic: ```bash rpk topic alter-config --set redpanda.iceberg.mode= ``` Choose the mode based on your message format and schema configuration. For Kafka Connect migrations, use this mapping: | Kafka Connect Converter | Recommended Iceberg Mode | | --- | --- | | io.confluent.connect.avro.AvroConverter | value_schema_id_prefix (messages already use Schema Registry wire format) | | io.confluent.connect.protobuf.ProtobufConverter | value_schema_id_prefix (messages already use Schema Registry wire format) | | org.apache.kafka.connect.json.JsonConverter with schemas | value_schema_latest (Schema Registry resolves schema automatically) | | org.apache.kafka.connect.json.JsonConverter with embedded schemas | key_value (schema included with each message) | See [Specify Iceberg Schema](../specify-iceberg-schema/) to learn more about the different Iceberg modes. 3. If using `value_schema_id_prefix` or `value_schema_latest` modes, register a schema for the topic: ```bash rpk registry schema create -value --schema --type ``` > ❗ **IMPORTANT** > > If using the `value_schema_id_prefix` mode, schema subjects must use the `-value` [naming convention](../../schema-reg/schema-id-validation/#set-subject-name-strategy-per-topic) (TopicNameStrategy). Note the schema ID returned, in case you need it for troubleshooting. 4. Verify that new records are being written to the Iceberg table: - Check that data appears in your query engine. - Validate that the schema translation is correct. - Confirm record counts are increasing. #### [](#multi-table-fan-out-pattern)Multi-table fan-out pattern If your existing integration routes records to multiple Iceberg tables based on a field value (for example, Kafka Connect’s `iceberg.tables.route-field` property), you need to implement equivalent routing logic. You create separate Iceberg-enabled topics for each target table, and Redpanda automatically creates corresponding Iceberg tables. Use either of the following approaches to route records to the correct topic: ##### [](#option-1-data-transforms-with-separate-topics-recommended)Option 1: Data transforms with separate topics (recommended) Use a data transform to read the routing field from each message and write records to separate Iceberg-enabled topics. This approach keeps routing logic within Redpanda and avoids external dependencies. When using Iceberg modes that require schema validation, the transform can register schemas dynamically and encode messages with the appropriate format. 1. Enable data transforms on your cluster: ```bash rpk cluster config set data_transforms_enabled true ``` 2. Create output topics and enable Iceberg with Schema Registry validation: ```bash rpk topic create rpk topic alter-config --set redpanda.iceberg.mode=value_schema_id_prefix rpk topic alter-config --set redpanda.iceberg.mode=value_schema_id_prefix rpk topic alter-config --set redpanda.iceberg.mode=value_schema_id_prefix ``` 3. Implement a transform function that: 1. Reads the routing field from each input message. 2. If using Schema Registry validation, registers schemas dynamically and encodes messages with the appropriate format. 3. Writes to a specific output topic based on the routing field. 4. Deploy the transform, specifying multiple output topics: ```bash rpk transform deploy \ --file transform.wasm \ --name \ --input-topic \ --output-topic \ --output-topic \ --output-topic ``` 5. Validate the fanout by checking that each output topic receives the correct records. For a complete implementation example with dynamic schema registration, see [Multi-topic fan-out with Schema Registry](../../../develop/data-transforms/build/#multi-topic-fanout). The example demonstrates Schema Registry wire format encoding for use with `value_schema_id_prefix` mode. ##### [](#option-2-external-stream-processor)Option 2: External stream processor Use an external stream processor for complex routing logic: 1. Use a stream processor ([Redpanda Connect](../../../../redpanda-connect/home/) or Flink) to split records. 2. Write to separate Iceberg-enabled topics. This approach is more complex but offers more flexibility for advanced routing requirements not supported by data transforms. ### [](#validate-schema-registry-integration)Validate Schema Registry integration If using [`value_schema_id_prefix`](../specify-iceberg-schema/#value_schema_id_prefix) mode, verify that messages use the Schema Registry [wire format](../../schema-reg/schema-reg-overview/#wire-format). ```bash rpk topic consume --num=1 --format='%v\n' | xxd | head -n 1 ``` If the first byte is not `00` (magic byte), you must configure your producer to use the wire format. The `value_schema_id_prefix` mode also requires that schema subjects follow the TopicNameStrategy: `-value`. Verify your schemas use the correct naming: ```bash rpk registry schema list ``` #### [](#verify-no-records-in-dlq)Verify no records in DLQ Check that no records failed validation and were written to the dead-letter queue. If records are present, see [Records in DLQ table](#records-in-dlq-table) for resolution steps. ```sql SELECT COUNT(*) FROM ."~dlq"; ``` ### [](#run-systems-in-parallel)Run systems in parallel Keep your existing Iceberg integration running while Iceberg Topics is enabled. This provides a safety net during the transition period: - New data flows to both the source tables and new Iceberg Topics tables. - You can validate data consistency between both systems. - You have a fallback option if issues arise. Run a query to compare record counts between systems: ```sql -- Source table SELECT COUNT(*) AS source_count FROM .; -- Iceberg Topics table SELECT COUNT(*) AS iceberg_topics_count FROM .; ``` Record counts should increase at similar rates, accounting for the time Iceberg Topics was enabled. Check for DLQ records (see [Records in DLQ table](#records-in-dlq-table)). Monitor Iceberg topic metrics to validate that data is flowing at expected rates: - `redpanda_iceberg_translation_parquet_rows_added`: Track rows written to Iceberg tables (compare with source write rate) - `redpanda_iceberg_translation_translations_finished`: Number of completed translation executions - `redpanda_iceberg_translation_invalid_records`: Records that failed validation - `redpanda_iceberg_translation_dlq_files_created`: Dead-letter queue activity - `redpanda_iceberg_rest_client_num_commit_table_update_requests_failed`: Failed table commits to catalog If using data transforms for multi-table fanout, also monitor: - `redpanda_transform_processor_lag`: Records pending processing in transform input topic For a complete list of Iceberg metrics, see the [Iceberg metrics reference](../../../reference/public-metrics-reference/#iceberg-metrics). > 💡 **TIP** > > Run both systems for at least 24-48 hours to ensure stability before proceeding with data merge. ### [](#merge-historical-data)Merge historical data Choose a strategy to combine your historical data with new Iceberg Topics data. #### [](#option-1-insert-into-pattern-recommended)Option 1: INSERT INTO pattern (recommended) Use this approach to create a unified table with all data, taking into consideration the following: - You want a single table for queries. - You can afford the one-time data copy cost. - You need optimal query performance. This SQL pattern uses partition and offset metadata to identify and copy only records not yet in the target table: ```sql -- Step 1: Find the latest offset per partition in the target (Iceberg Topics) table WITH latest_offsets AS ( SELECT partition, MAX(offset) AS max_offset FROM target_iceberg_topics_table GROUP BY partition ) -- Step 2: Insert records from source table that don't exist in target INSERT INTO target_iceberg_topics_table SELECT s.* FROM source_table AS s LEFT JOIN latest_offsets AS t ON s.partition = t.partition WHERE t.max_offset IS NULL -- Partition not seen before in target OR s.offset > t.max_offset; -- Record is newer than target's latest offset ``` - The `latest_offsets` CTE finds the highest offset in the target table for each partition. - The `LEFT JOIN` ensures you include partitions never seen before in the target (`t.max_offset IS NULL`). - The `WHERE` clause filters to only records with offsets greater than the target’s latest. - This avoids duplicates by using Kafka partition and offset as the deduplication key. This approach may take significant time for large datasets. Consider executing this process during low-query periods. You can also execute on an incremental basis to ease the load on your query engine, for example, by date or partition ranges. #### [](#option-2-view-based-query-federation)Option 2: View-based query federation Use this approach to query both tables without copying data if: - You cannot afford data copy time or cost. - You need immediate access to a unified view. - Query complexity and performance are acceptable with federated queries. - You may consolidate data later. Create a view that queries both tables and deduplicates on the fly: ```sql CREATE VIEW unified_iceberg_view AS WITH latest_offsets AS ( SELECT partition, MAX(offset) AS max_offset FROM target_iceberg_topics_table GROUP BY partition ), historical_data AS ( SELECT s.* FROM source_table AS s LEFT JOIN latest_offsets AS t ON s.partition = t.partition WHERE t.max_offset IS NULL OR s.offset <= t.max_offset -- Only historical records not in target ), new_data AS ( SELECT * FROM target_iceberg_topics_table ) SELECT * FROM historical_data UNION ALL SELECT * FROM new_data; ``` Most Iceberg-compatible query engines support views, including Snowflake, Databricks, ClickHouse, and Spark. ### [](#validate-the-migration)Validate the migration After completing the data merge, verify the migration before cutting over: - Record counts match between source and target: ```sql -- Compare record counts SELECT 'Source' AS table_name, COUNT(*) AS record_count FROM . UNION ALL SELECT 'Target', COUNT(*) FROM .; ``` - All partitions are represented in the target: ```sql -- Check for missing partitions SELECT DISTINCT partition FROM . EXCEPT SELECT DISTINCT partition FROM .; -- Should return no rows ``` - Date ranges cover the full historical period. Compare `MIN(timestamp)` and `MAX(timestamp)` between source and target tables to ensure the target covers the same time range. - No gaps in offset sequences: ```sql -- Check for offset gaps (may indicate missing data) WITH offset_check AS ( SELECT partition, offset, LAG(offset) OVER (PARTITION BY partition ORDER BY offset) AS prev_offset FROM . ) SELECT * FROM offset_check WHERE offset - prev_offset > 1; -- Should return no rows ``` - Sample queries return expected results. Spot check specific records by ID to verify data accuracy. - Schema translation is correct. Run `DESCRIBE` on both tables and verify all fields are present with correct data types. - New records are flowing to Iceberg Topics. Check record count for a recent time window (for example, the last hour). - Query performance is acceptable. - Monitoring and alerts are configured. - No records in DLQ (see [Records in DLQ table](#records-in-dlq-table)). ### [](#troubleshoot-common-migration-issues)Troubleshoot common migration issues #### [](#records-in-dlq-table)Records in DLQ table Iceberg Topics write records that fail validation to a dead-letter queue (DLQ) table. Records may appear in the DLQ due to: - Schema Registry issues. For example, using the wrong schema subject name, or Redpanda cannot find the embedded schema ID in Schema Registry. - When using `value_schema_id_prefix` mode: messages not encoded with Schema Registry wire format. - Incompatible schema changes. For example, changing field types or removing required fields. - Data type translation failures. To check for DLQ records during migration: ```sql SELECT COUNT(*) FROM ."~dlq"; ``` If the count is greater than zero, inspect the failed records. See [Troubleshoot errors](../about-iceberg-topics/#troubleshoot-errors) for steps to inspect and reprocess DLQ records. #### [](#multi-table-fan-out-transform-issues)Multi-table fan-out transform issues If the transform does not process messages, check if: - The specified output topics don’t exist or aren’t enabled with Iceberg. - The routing logic in the transform is incorrect, or the routing field is missing from input messages. - (When using Schema Registry validation) The schema registration failed during initialization, preventing the transform from starting. To check the transform status: ```bash rpk transform list ``` To view logs and check for errors: ```bash rpk transform logs ``` To check for routing errors: ```bash rpk transform logs | grep -i "unknown\|error" ``` If using Schema Registry validation, verify schema registration: ```bash # Check transform logs for schema registration messages rpk transform logs | grep -i "schema" # List registered schemas rpk registry schema list ``` ### [](#plan-for-rollback)Plan for rollback Before cutting over, ensure you have a rollback strategy. See the [Pre-cutover checklist](#pre-cutover-checklist) in the cutover section to verify you’re ready. #### [](#rollback-during-parallel-operation)Rollback during parallel operation If you discover issues while both systems are running: 1. Keep producing to both systems. 2. Point consumers back to source tables. 3. Investigate Iceberg Topics issues using troubleshooting section. 4. Fix issues and re-validate. 5. Attempt cutover again when ready. #### [](#rollback-after-external-integration-disabled)Rollback after external integration disabled > ⚠️ **WARNING** > > Rollback after stopping your external Iceberg integration may result in data loss or gaps. If you must rollback after disabling the external integration: 1. Restart your external Iceberg integration immediately. 2. Identify data written only to Iceberg Topics during the gap. 3. Export that data from Iceberg Topics tables: ```sql SELECT * FROM iceberg_topics_table WHERE timestamp > ''; ``` 4. Write exported data back to the source system (for example, Kafka Connect input topics or directly to source tables). 5. Verify data completeness across both systems. 6. Resume operations on the external integration. Redpanda recommends maintaining the ability to rollback for at least seven days after cutover to allow for issue discovery. ### [](#cut-over-to-iceberg-topics)Cut over to Iceberg Topics #### [](#pre-cutover-checklist)Pre-cutover checklist Before disabling your external Iceberg integration, ensure you have completed all validation steps: - All historical data is successfully merged (see [Merge historical data](#merge-historical-data)). - Parallel operation is complete and stable for at least 24-48 hours. - All validation queries pass (see [Validate the migration](#validate-the-migration)). - No records in DLQ tables, or all DLQ records are investigated and resolved. - Query performance meets requirements. - Downstream consumers are successfully tested with Iceberg Topics tables. - Monitoring and alerts are configured. - Rollback plan is verified and documented. #### [](#cutover-procedure)Cutover procedure 1. Set an appropriate maintenance window, ideally during low-traffic periods. 2. Stop your external Iceberg integration. 3. Monitor Iceberg Topics to ensure data continues flowing. 4. Verify that no new records are being written to source tables: ```sql SELECT MAX(timestamp) FROM .; -- Should not change after integration is stopped ``` 5. Run validation queries from [Validate the migration](#validate-the-migration) after 1-2 hours of operation. 6. Wait for a short period, such as 24-48 hours, to monitor and validate stability. 7. If migrating to a unified table of historical plus new data, optionally delete old source tables after an extended validation period (for example, at least seven days): > 📝 **NOTE** > > Ensure you have backups before deleting historical data. Some organizations keep old tables for compliance or audit purposes. ```sql DROP TABLE .; ``` 8. Decommission external Iceberg infrastructure after an extended safety period (30+ days, for example). If any issues arise during cutover, see [Plan for rollback](#plan-for-rollback). ## [](#next-steps)Next steps - [Query Iceberg Topics](../query-iceberg-topics/) - [About Iceberg Topics](../about-iceberg-topics/) --- # Page 151: Query Iceberg Topics **URL**: https://docs.redpanda.com/current/manage/iceberg/query-iceberg-topics.md --- # Query Iceberg Topics --- title: Query Iceberg Topics latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: iceberg/query-iceberg-topics page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: iceberg/query-iceberg-topics.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/iceberg/query-iceberg-topics.adoc description: Query Redpanda topic data stored in Iceberg tables, based on the topic Iceberg mode and schema. page-git-created-date: "2025-04-07" page-git-modified-date: "2026-04-06" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../get-started/licensing/#self-managed) apply. When you access Iceberg topics from a data lakehouse or other Iceberg-compatible tools, how you consume the data depends on the topic [Iceberg mode](../specify-iceberg-schema/) and whether you’ve registered a schema for the topic in the [Redpanda Schema Registry](../../schema-reg/schema-reg-overview/). You do not need to rely on complex ETL jobs or pipelines to access real-time data from Redpanda. ## [](#access-iceberg-tables)Access Iceberg tables > ❗ **IMPORTANT** > > Redpanda v25.3 introduces breaking schema changes for Iceberg topics. If you are using Iceberg topics and want to retain the data in the corresponding Iceberg tables, review [Schema Changes and Migration Guide for Iceberg Topics in Redpanda v25.3](../../../upgrade/iceberg-schema-changes-and-migration-guide/) before upgrading your cluster, and follow the required migration steps to avoid sending new records to a dead-letter queue table. Redpanda generates an Iceberg table with the same name as the topic. Depending on the processing engine and your Iceberg [catalog implementation](../use-iceberg-catalogs/), you may also need to define the table (for example using `CREATE TABLE`) to point the data lakehouse to its location in the catalog. For an example, see [Query Iceberg Topics using Snowflake and Open Catalog](../redpanda-topics-iceberg-snowflake-catalog/). Some query engines may require you to manually refresh the Iceberg table snapshot (for example, by running a command like `ALTER TABLE REFRESH;`) to see the latest data. If your engine needs the full JSON metadata path, use the following: ```none redpanda-iceberg-catalog/redpanda//metadata/v.metadata.json ``` This provides read access to all snapshots written as of the specified table version (denoted by `version-number`). > 📝 **NOTE** > > Redpanda automatically removes expired snapshots on a periodic basis. Snapshot expiry helps maintain a smaller metadata size and reduces the window available for [time travel](#time-travel-queries). ## [](#query-examples)Query examples To follow along with the examples on this page, suppose you produce the same stream of events to a topic `ClickEvent`, which uses a schema, and another topic `ClickEvent_key_value`, which uses the key-value mode. The topics have [Tiered Storage](https://docs.redpanda.com/current/reference/glossary/#tiered-storage) configured to an AWS S3 bucket. A sample record contains the following data: ```bash {"user_id": 2324, "event_type": "BUTTON_CLICK", "ts": "2024-11-25T20:23:59.380Z"} ``` > 📝 **NOTE** > > The query examples on this page use `redpanda` as the Iceberg namespace, which is the default. If you configured a different namespace using `[iceberg_default_catalog_namespace](../../../reference/properties/cluster-properties/#iceberg_default_catalog_namespace)`, replace `redpanda` with your configured namespace. ### [](#topic-with-schema-value_schema_id_prefix-mode)Topic with schema (`value_schema_id_prefix` mode) > 📝 **NOTE** > > The steps in this section also apply to the `value_schema_latest` mode, except the produce step. The `value_schema_latest` mode is not compatible with the Schema Registry wire format. The [`rpk topic produce`](#reference:rpk/rpk-topic/rpk-topic-produce) command embeds the wire format header, so you must use your own producer code with `value_schema_latest`. Assume that you have created the `ClickEvent` topic, set `redpanda.iceberg.mode` to `value_schema_id_prefix`, and are connecting to a REST-based Iceberg catalog. The following is an Avro schema for `ClickEvent`: `schema.avsc` ```avro { "type" : "record", "namespace" : "com.redpanda.examples.avro", "name" : "ClickEvent", "fields" : [ { "name": "user_id", "type" : "int" }, { "name": "event_type", "type" : "string" }, { "name": "ts", "type": "string" } ] } ``` 1. Register the schema under the `ClickEvent-value` subject: ```bash rpk registry schema create ClickEvent-value --schema path/to/schema.avsc --type avro ``` 2. Produce to the `ClickEvent` topic using the following format: ```bash echo '"key1" {"user_id":2324,"event_type":"BUTTON_CLICK","ts":"2024-11-25T20:23:59.380Z"}' | rpk topic produce ClickEvent --format='%k %v\n' --schema-id=topic ``` The `value_schema_id_prefix` mode requires that you produce to a topic using the [Schema Registry wire format](../../schema-reg/schema-reg-overview/#wire-format), which includes the magic byte and schema ID in the prefix of the message payload. This allows Redpanda to identify the correct schema version in the Schema Registry for a record. 3. The following Spark SQL query returns values from columns in the `ClickEvent` table, with the table structure derived from the schema, and column names matching the schema fields. If you’ve integrated a catalog, query engines such as Spark SQL provide Iceberg integrations that allow easy discovery and access to existing Iceberg tables in object storage. ```sql SELECT * FROM ``.redpanda.ClickEvent; ``` ```bash +-----------------------------------+---------+--------------+--------------------------+ | redpanda | user_id | event_type | ts | +-----------------------------------+---------+--------------+--------------------------+ | {"partition":0,"offset":0,"timestamp":2025-03-05 15:09:20.436,"headers":null,"key":null} | 2324 | BUTTON_CLICK | 2024-11-25T20:23:59.380Z | +-----------------------------------+---------+--------------+--------------------------+ ``` ### [](#topic-in-key-value-mode)Topic in key-value mode In `key_value` mode, you do not associate the topic with a schema in the Schema Registry, which means using semi-structured data in Iceberg. The record keys and values can have an arbitrary structure, so Redpanda stores them in [binary format](https://apache.github.io/iceberg/spec/?h=spec#primitive-types) in Iceberg. In this example, assume that you have created the `ClickEvent_key_value` topic, and set `redpanda.iceberg.mode` to `key_value`. 1. Produce to the `ClickEvent_key_value` topic using the following format: ```bash echo '"key1" {"user_id":2324,"event_type":"BUTTON_CLICK","ts":"2024-11-25T20:23:59.380Z"}' | rpk topic produce ClickEvent_key_value --format='%k %v\n' ``` 2. The following Spark SQL query returns the semi-structured data in the `ClickEvent_key_value` table. The table consists of two columns: one named `redpanda`, containing the record key and other metadata, and another binary column named `value` for the record’s value: ```sql SELECT * FROM ``.redpanda.ClickEvent_key_value; ``` ```bash +-----------------------------------+------------------------------------------------------------------------------+ | redpanda | value | +-----------------------------------+------------------------------------------------------------------------------+ | {"partition":0,"offset":0,"timestamp":2025-03-05 15:14:30.931,"headers":null,"key":key1} | {"user_id":2324,"event_type":"BUTTON_CLICK","ts":"2024-11-25T20:23:59.380Z"} | +-----------------------------------+------------------------------------------------------------------------------+ ``` Depending on your query engine, you might need to first decode the binary value to display the record key and value using a SQL helper function. For example, see the [`decode` and `unhex`](https://spark.apache.org/docs/latest/api/sql/index.html#unhex) Spark SQL functions, or the [HEX\_DECODE\_STRING](https://docs.snowflake.com/en/sql-reference/functions/hex_decode_string) Snowflake function. Some engines may also automatically decode the binary value for you. ### [](#time-travel-queries)Time travel queries Some query engines, such as Spark, support time travel with Iceberg, allowing you to query the table as it existed at a specific point in the past. You can run a time travel query by specifying a timestamp or version number. Redpanda automatically removes expired snapshots on a periodic basis, which also reduces the window available for time travel queries. By default, Redpanda retains snapshots for five days, so you can query Iceberg tables as of up to five days ago. The following example queries a `ClickEvent` table at a specific timestamp in Spark: ```sql SELECT * FROM ``.redpanda.ClickEvent TIMESTAMP AS OF '2025-03-02 10:00:00'; ``` ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) [Search all labs](/redpanda-labs) --- # Page 152: Query Iceberg Topics using Snowflake and Open Catalog **URL**: https://docs.redpanda.com/current/manage/iceberg/redpanda-topics-iceberg-snowflake-catalog.md --- # Query Iceberg Topics using Snowflake and Open Catalog --- title: Query Iceberg Topics using Snowflake and Open Catalog latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: iceberg/redpanda-topics-iceberg-snowflake-catalog page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: iceberg/redpanda-topics-iceberg-snowflake-catalog.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/iceberg/redpanda-topics-iceberg-snowflake-catalog.adoc description: Add Redpanda topics as Iceberg tables that you can query in Snowflake using an Open Catalog integration. page-git-created-date: "2025-02-07" page-git-modified-date: "2026-03-31" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../get-started/licensing/#self-managed) apply. This guide walks you through querying Redpanda topics as Iceberg tables in [Snowflake](https://docs.snowflake.com/en/user-guide/tables-iceberg), with AWS S3 as object storage and a catalog integration using [Open Catalog](https://other-docs.snowflake.com/en/opencatalog/overview). ## [](#prerequisites)Prerequisites - [Object storage configured](../../tiered-storage/#configure-object-storage) for your cluster and [Tiered Storage enabled](../../tiered-storage/#enable-tiered-storage) for the topics for which you want to generate Iceberg tables. You need the S3 bucket URI to configure it as external storage for Open Catalog. - A Snowflake account. - An Open Catalog account. To [create an Open Catalog account](https://other-docs.snowflake.com/en/opencatalog/create-open-catalog-account), you require ORGADMIN access in Snowflake. - An internal catalog created in Open Catalog with your Tiered Storage AWS S3 bucket configured as external storage. Follow this guide to [create a catalog](https://other-docs.snowflake.com/en/opencatalog/create-catalog#create-a-catalog-using-amazon-simple-storage-service-amazon-s3) with the S3 bucket configured as external storage. You require admin permissions to carry out these steps in AWS: 1. If you don’t already have one, create an IAM policy that gives Open Catalog read and write access to your S3 bucket. 2. Create an IAM role and attach the IAM policy to the role. 3. After creating a new catalog in Open Catalog, grant the catalog’s AWS IAM user access to the S3 bucket. - A Snowflake [external volume](https://docs.snowflake.com/en/user-guide/tables-iceberg-configure-external-volume) set up using the Tiered Storage bucket. Follow this guide to [configure the external volume with S3](https://docs.snowflake.com/en/user-guide/tables-iceberg-configure-external-volume-s3). You can use the same IAM policy as the catalog for the external volume’s IAM role and user. ## [](#set-up-catalog-integration-using-open-catalog)Set up catalog integration using Open Catalog ### [](#create-a-new-open-catalog-service-connection-for-redpanda)Create a new Open Catalog service connection for Redpanda To create a new service connection to integrate the Iceberg-enabled topics into Open Catalog: 1. In Open Catalog, select **Connections**, then **\+ Connection**. 2. In **Configure Service Connection**, provide a name. Open Catalog creates a new principal with this name. 3. Make sure **Create new principal role** is selected. 4. Enter a name for the principal role. Then, click **Create**. After you create the connection, get the client ID and client secret. Save these credentials to add to your cluster configuration in a later step. ### [](#create-a-catalog-role)Create a catalog role Grant privileges to the principal created in the previous step: 1. In Open Catalog, select **Catalogs**, and select your catalog. 2. On the **Roles** tab of your catalog, click **\+ Catalog Role**. 3. Give the catalog role a name. 4. Under **Privileges**, select `CATALOG_MANAGE_CONTENT`. This provides full management [privileges](https://other-docs.snowflake.com/en/opencatalog/access-control#catalog-privileges) for the catalog. Then, click **Create**. 5. On the **Roles** tab of the catalog, click **Grant to Principal Role**. 6. Select the catalog role you just created. 7. Select the principal role you created earlier. Click **Grant**. ### [](#update-cluster-configuration)Update cluster configuration To configure your Redpanda cluster to enable Iceberg on a topic and integrate with Open Catalog: 1. Edit your cluster configuration to set the `iceberg_enabled` property to `true`, and set the catalog integration properties listed in the example below. You must restart your cluster if you change this configuration for a running cluster. You can run `rpk cluster config edit` to update these properties: ```bash iceberg_enabled: true iceberg_catalog_type: rest iceberg_rest_catalog_endpoint: https://-.snowflakecomputing.com/polaris/api/catalog iceberg_rest_catalog_authentication_mode: oauth2 iceberg_rest_catalog_client_id: iceberg_rest_catalog_client_secret: iceberg_rest_catalog_warehouse: # Optional iceberg_translation_interval_ms_default: 1000 iceberg_catalog_commit_interval_ms: 1000 ``` Use your own values for the following placeholders: - `` and ``: Your [Open Catalog account URI](https://docs.snowflake.com/en/sql-reference/sql/create-catalog-integration-open-catalog#required-parameters) is composed of these values. > 💡 **TIP** > > In Snowflake, navigate to **Admin**, then **Accounts**. Click the ellipsis near your Open Catalog account name, and select **Manage URLs**. The **Current URL** contains `` and ``. - ``: The client ID of the service connection you created in an earlier step. - ``: The client secret of the service connection you created in an earlier step. - ``: The name of your catalog in Open Catalog. ```bash Successfully updated configuration. New configuration version is 2. ``` 2. You must restart your cluster so that the configuration changes take effect. 3. Enable the integration for a topic by configuring the topic property `redpanda.iceberg.mode`. This mode creates an Iceberg table for the topic consisting of two columns: one for the record metadata including the key, and another binary column for the record’s value. See [Enable Iceberg integration](../about-iceberg-topics/#enable-iceberg-integration) for more details on Iceberg modes. The following examples show how to use `rpk` to create a new topic or alter the configuration for an existing topic, setting the Iceberg mode to `key_value`. Create a new topic and set `redpanda.iceberg.mode`: ```bash rpk topic create --topic-config=redpanda.iceberg.mode=key_value ``` Set `redpanda.iceberg.mode` for an existing topic: ```bash rpk topic alter-config --set redpanda.iceberg.mode=key_value ``` 4. Produce to the topic. For example, ```bash echo "hello world\nfoo bar\nbaz qux" | rpk topic produce --format='%k %v\n' ``` You should see the topic as a table in Open Catalog. 1. In Open Catalog, select **Catalogs**, then open your catalog. 2. Under your catalog, you should see the `redpanda` namespace (or the namespace you configured with `[iceberg_default_catalog_namespace](../../../reference/properties/cluster-properties/#iceberg_default_catalog_namespace)`), and a table with the name of your topic. The namespace and the table are automatically added for you. ## [](#query-iceberg-table-in-snowflake)Query Iceberg table in Snowflake To query the topic in Snowflake, you must create a [catalog integration](https://docs.snowflake.com/en/user-guide/tables-iceberg#catalog-integration) so that Snowflake has access to the table data and metadata. ### [](#configure-catalog-integration-with-snowflake)Configure catalog integration with Snowflake 1. Run the [`CREATE CATALOG INTEGRATION`](https://docs.snowflake.com/sql-reference/sql/create-catalog-integration-open-catalog) command in Snowflake: ```sql CREATE CATALOG INTEGRATION CATALOG_SOURCE = POLARIS TABLE_FORMAT = ICEBERG CATALOG_NAMESPACE = 'redpanda' REST_CONFIG = ( CATALOG_URI = '' WAREHOUSE = '' ) REST_AUTHENTICATION = ( TYPE = OAUTH OAUTH_CLIENT_ID = '' OAUTH_CLIENT_SECRET = '' OAUTH_ALLOWED_SCOPES = ('PRINCIPAL_ROLE:ALL') ) REFRESH_INTERVAL_SECONDS = 30 ENABLED = TRUE; ``` Use your own values for the following placeholders: - ``: Provide a name for your Iceberg catalog integration in Snowflake. - ``: Your [Open Catalog account URI](https://docs.snowflake.com/en/sql-reference/sql/create-catalog-integration-open-catalog#required-parameters) (`[https://-.snowflakecomputing.com/polaris/api/catalog](https://-.snowflakecomputing.com/polaris/api/catalog)`). - ``: The name of your catalog in Open Catalog. - ``: The client ID of the service connection you created in an earlier step. - ``: The client secret of the service connection you created in an earlier step. 2. Run the following command to verify that the catalog is integrated correctly: ```sql SELECT SYSTEM$LIST_ICEBERG_TABLES_FROM_CATALOG(''); ``` ```bash # Example result for redpanda.iceberg.mode=key_value +-----------------------------------------------------------------------+ | SYSTEM$LIST_ICEBERG_TABLES_FROM_CATALOG('') | +-----------------------------------------------------------------------+ | [{"namespace":"redpanda","name":""}] | +-----------------------------------------------------------------------+ ``` ### [](#create-iceberg-table-in-snowflake)Create Iceberg table in Snowflake After creating the catalog integration, you must create an externally-managed table in Snowflake. You must run your Snowflake queries against this table. In your Snowflake database, run the [CREATE ICEBERG TABLE](https://docs.snowflake.com/en/sql-reference/sql/create-iceberg-table-rest) command. The following example also specifies that the table should automatically refresh metadata: ```sql CREATE ICEBERG TABLE CATALOG = '' EXTERNAL_VOLUME = '' CATALOG_TABLE_NAME = '' AUTO_REFRESH = TRUE ``` Use your own values for the following placeholders: - ``: Provide a name for your table in Snowflake. - ``: The name of the catalog integration you configured in an earlier step. - ``: The name of the external volume you configured using the Tiered Storage bucket. - ``: The name of the table in your catalog, which is the same as your Redpanda topic name. ### [](#query-table)Query table To verify that Snowflake has successfully created the table containing the topic data, run the following: ```sql SELECT * FROM ; ``` Your query results should look like the following: ```bash # Example for redpanda.iceberg.mode=key_value with 3 records produced to topic +--------------------------------------------------------------------------------------------------------------+------------+ | REDPANDA | VALUE | +--------------------------------------------------------------------------------------------------------------+------------+ | { "partition": 0, "offset": 0, "timestamp": "2025-02-07 16:29:50.122", "headers": null, "key": "68656C6C6F"} | 776F726C64 | | { "partition": 0, "offset": 1, "timestamp": "2025-02-07 16:29:50.122", "headers": null, "key": "666F6F"} | 626172 | | { "partition": 0, "offset": 2, "timestamp": "2025-02-07 16:29:50.122", "headers": null, "key": "62617A" } | 717578 | +--------------------------------------------------------------------------------------------------------------+------------+ ``` ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) [Search all labs](/redpanda-labs) --- # Page 153: Integrate with REST Catalogs **URL**: https://docs.redpanda.com/current/manage/iceberg/rest-catalog.md --- # Integrate with REST Catalogs --- title: Integrate with REST Catalogs latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: iceberg/rest-catalog/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: iceberg/rest-catalog/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/iceberg/rest-catalog/index.adoc description: Integrate Redpanda topics with managed Iceberg REST Catalogs. page-git-created-date: "2025-07-30" page-git-modified-date: "2025-11-27" support-status: supported --- > 💡 **TIP** > > These guides are for integrating Iceberg topics with managed REST catalogs. Integrating with a REST catalog is recommended for production deployments. If it is not possible to use a REST catalog, you can use the [filesystem-based catalog](../use-iceberg-catalogs/#object-storage). For an example of using the filesystem-based catalog to access Iceberg topics, see the [Getting Started with Iceberg Topics on Redpanda BYOC](https://www.redpanda.com/blog/iceberg-topics-redpanda-cloud-byoc-setup) blog post. The blog post uses a Redpanda Cloud cluster, but you follow the same steps for a Self-Managed cluster. - [Query Iceberg Topics using AWS Glue](../iceberg-topics-aws-glue/) Add Redpanda topics as Iceberg tables that you can query from AWS Glue Data Catalog. - [Query Iceberg Topics using Databricks and Unity Catalog](../iceberg-topics-databricks-unity/) Add Redpanda topics as Iceberg tables that you can query in Databricks managed by Unity Catalog. - [Use Iceberg Topics with GCP BigLake](../iceberg-topics-gcp-biglake/) Add Redpanda topics as Iceberg tables to your Google BigLake data lakehouse that you can query from Google BigQuery. - [Query Iceberg Topics using Snowflake and Open Catalog](../redpanda-topics-iceberg-snowflake-catalog/) Add Redpanda topics as Iceberg tables that you can query in Snowflake using an Open Catalog integration. --- # Page 154: Specify Iceberg Schema **URL**: https://docs.redpanda.com/current/manage/iceberg/specify-iceberg-schema.md --- # Specify Iceberg Schema --- title: Specify Iceberg Schema latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: iceberg/specify-iceberg-schema page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: iceberg/specify-iceberg-schema.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/iceberg/specify-iceberg-schema.adoc description: Learn about supported Iceberg modes and how you can integrate schemas with Iceberg topics. page-git-created-date: "2025-07-30" page-git-modified-date: "2026-03-31" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../get-started/licensing/#self-managed) apply. In [Iceberg-enabled clusters](../about-iceberg-topics/#enable-iceberg-integration), the `redpanda.iceberg.mode` topic property determines how Redpanda maps topic data to the Iceberg table structure. You can have the generated Iceberg table match the structure of a schema in the Schema Registry, or you can use the `key_value` mode where Redpanda stores the record values as-is in the table. ## [](#supported-iceberg-modes)Supported Iceberg modes Redpanda supports the following [modes](../../../reference/properties/topic-properties/#redpanda-iceberg-mode) for Iceberg topics: ### [](#key_value)key\_value Creates an Iceberg table using a simple schema, consisting of two columns, one for the record metadata including the key, and another binary column for the record’s value. ### [](#value_schema_id_prefix)value\_schema\_id\_prefix Creates an Iceberg table whose structure matches the Redpanda schema for the topic, with columns corresponding to each field. You must register a schema in the [Schema Registry](../../schema-reg/schema-reg-overview/) and producers must write to the topic using the Schema Registry wire format. In the [Schema Registry wire format](../../schema-reg/schema-reg-overview/#wire-format), a "magic byte" and schema ID are embedded in the message payload header. Producers to the topic must use the wire format in the serialization process so Redpanda can determine the schema used for each record, use the schema to define the Iceberg table, and store the topic values in the corresponding table columns. ### [](#value_schema_latest)value\_schema\_latest Creates an Iceberg table whose structure matches the latest schema registered for the subject in the Schema Registry. You must register a schema in the Schema Registry. Producers cannot use the wire format in `value_schema_latest` mode. Redpanda expects the serialized message as-is without the magic byte or schema ID prefix in the record value. > 📝 **NOTE** > > The `value_schema_latest` mode is not compatible with the [`rpk topic produce`](#reference:rpk/rpk-topic/rpk-topic-produce) command which embeds the wire format header. You must use your own producer code to produce to topics in `value_schema_latest` mode. The latest schema is cached periodically. The cache period is defined by the cluster property `iceberg_latest_schema_cache_ttl_ms` (default: 5 minutes). ### [](#disabled)disabled Default for `redpanda.iceberg.mode`. Disables writing to an Iceberg table for the topic. > 📝 **NOTE** > > The following modes are compatible with producing to an Iceberg topic using Redpanda Console: > > - `key_value` > > - Starting in version 25.2, `value_schema_latest` with a JSON schema > > > Otherwise, records may fail to write to the Iceberg table and instead write to the [dead-letter queue](../about-iceberg-topics/#manage-dead-letter-queue). ## [](#configure-iceberg-mode-for-a-topic)Configure Iceberg mode for a topic You can set the Iceberg mode for a topic when you create the topic, or you can update the mode for an existing topic. Option 1. Create a new topic and set `redpanda.iceberg.mode`: ```bash rpk topic create --topic-config=redpanda.iceberg.mode= ``` Option 2. Set `redpanda.iceberg.mode` for an existing topic: ```bash rpk topic alter-config --set redpanda.iceberg.mode= ``` ### [](#override-value-schema-latest-default)Override `value_schema_latest` default In `value_schema_latest` mode, you only need to set the property value to the string `value_schema_latest`. This enables the default behavior of `value_schema_latest` mode, which determines the subject for the topic using the [TopicNameStrategy](../../schema-reg/schema-id-validation/#set-subject-name-strategy-per-topic). For example, if your topic is named `sensor` the schema is looked up in the `sensor-value` subject. For Protobuf data, the default behavior also deserializes records using the first message defined in the corresponding Protobuf schema stored in the Schema Registry. If you use a different strategy other than the topic name to derive the subject name, you can override the default behavior of `value_schema_latest` mode and explicitly set the subject name. To override the default behavior, use the following optional syntax: ```bash value_schema_latest:subject=,protobuf_name= ``` - For both Avro and Protobuf, specify a different subject name by using the key-value pair `subject=`, for example `value_schema_latest:subject=sensor-data`. - For Protobuf only: - Specify a different message definition by using a key-value pair `protobuf_name=`. You must use the fully qualified name, which includes the package name, for example, `value_schema_latest:protobuf_name=com.example.manufacturing.SensorData`. - To specify both a different subject and message definition, separate the key-value pairs with a comma, for example: `value_schema_latest:subject=my_protobuf_schema,protobuf_name=com.example.manufacturing.SensorData`. > 📝 **NOTE** > > If you don’t specify the fully qualified Protobuf message name, Redpanda pauses the data translation to the Iceberg table until you fix the topic misconfiguration. ## [](#how-iceberg-modes-translate-to-table-format)How Iceberg modes translate to table format > ❗ **IMPORTANT** > > Redpanda v25.3 introduces breaking schema changes for Iceberg topics. If you are using Iceberg topics and want to retain the data in the corresponding Iceberg tables, review [Schema Changes and Migration Guide for Iceberg Topics in Redpanda v25.3](../../../upgrade/iceberg-schema-changes-and-migration-guide/) before upgrading your cluster, and follow the required migration steps to avoid sending new records to a dead-letter queue table. Redpanda generates an Iceberg table with the same name as the topic. In each mode, Redpanda writes to a `redpanda` table column that stores a single Iceberg [struct](https://iceberg.apache.org/spec/#nested-types) per record, containing nested columns of the metadata from each record, including the record key, headers, timestamp, the partition it belongs to, and its offset. For example, if you produce to a topic `ClickEvent` according to the following Avro schema: ```avro { "type": "record", "name": "ClickEvent", "fields": [ { "name": "user_id", "type": "int" }, { "name": "event_type", "type": "string" }, { "name": "ts", "type": "string" } ] } ``` The `key_value` mode writes to the following table format: ```sql CREATE TABLE ClickEvent ( redpanda struct< partition: integer, timestamp: timestamptz, offset: long, headers: array>, key: binary, timestamp_type: integer >, value binary ) ``` Use `key_value` mode if you want to use the Iceberg data in its semi-structured format. The `value_schema_id_prefix` and `value_schema_latest` modes can use the schema to translate to the following table format: ```sql CREATE TABLE ClickEvent ( redpanda struct< partition: integer, timestamp: timestamptz, offset: long, headers: array>, key: binary, timestamp_type: integer >, user_id integer NOT NULL, event_type string, ts string ) ``` As you produce records to the topic, the data also becomes available in object storage for Iceberg-compatible clients to consume. You can use the same analytical tools to [read the Iceberg topic data](../query-iceberg-topics/) in a data lake as you would for a relational database. If Redpanda fails to translate the record to the columnar format as defined by the schema, it writes the record to a dead-letter queue (DLQ) table. See [Troubleshoot errors](../about-iceberg-topics/#troubleshoot-errors) for more information. > 📝 **NOTE** > > You cannot use schemas to parse or decode record keys for Iceberg. The record keys are always stored in binary format in the `redpanda.key` column. ### [](#schema-types-translation)Schema types translation Redpanda supports direct translations of the following types to Iceberg value domains: #### Avro | Avro type | Iceberg type | | --- | --- | | boolean | boolean | | int | int | | long | long | | float | float | | double | double | | bytes | binary | | string | string | | record | struct | | array | list | | map | map | | fixed | fixed* | | decimal | decimal | | uuid | uuid* | | date | date | | time | time* | | timestamp | timestamp | \*These types are not currently supported in Unity Catalog managed Iceberg tables. There are some cases where the Avro type does not map directly to an Iceberg type and Redpanda applies the following transformations: - Enums are translated into the Iceberg `string` type. - Different flavors of time (such as `time-millis`) and timestamp (such as `timestamp-millis`) types are translated to the same Iceberg `time` and `timestamp` types, respectively. - Avro unions are flattened to Iceberg structs with optional fields. For example: - The union `["int", "long", "float"]` is represented as an Iceberg struct `struct<0 INT NULLABLE, 1 LONG NULLABLE, 2 FLOAT NULLABLE>`. - The union `["int", null, "float"]` is represented as an Iceberg struct `struct<0 INT NULLABLE, 1 FLOAT NULLABLE>`. - Two-field unions that contain `null` are represented as a single optional field only (no struct). For example, the union `["null", "long"]` is represented as `long`. Some Avro types are not supported: - The Avro `duration` logical type is ignored. - The Avro `null` type is ignored and not represented in the Iceberg schema. - Recursive types are not supported. #### Protobuf | Protobuf type | Iceberg type | | --- | --- | | bool | boolean | | double | double | | float | float | | int32 | int | | sint32 | int | | int64 | long | | sint64 | long | | sfixed32 | int | | sfixed64 | long | | string | string | | bytes | binary | | map | map | | message | struct | There are some cases where the Protobuf type does not map directly to an Iceberg type and Redpanda applies the following transformations: - Repeated values are translated into Iceberg `list` types. - Enums are translated into the Iceberg `string` type. - `uint32` and `fixed32` are translated into Iceberg `long` types as that is the existing semantic for unsigned 32-bit values in Iceberg. - `uint64` and `fixed64` values are translated into their Base-10 string representation. - `google.protobuf.Timestamp` is translated into `timestamp` in Iceberg. Recursive types are not supported. #### JSON Schema Requirements: - Only JSON Schema Draft-07 is currently supported. - You must declare the JSON Schema dialect using the `$schema` keyword, for example `"$schema": "http://json-schema.org/draft-07/schema#"`. - You must use a JSON Schema that constrains JSON documents to a strict type so Redpanda can translate to Iceberg. In most cases this means each subschema uses the `type` keyword, but a subschema can also use `$ref` if the referenced schema resolves to a strict type. Valid JSON Schema example ```json { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "productId": { "type": "integer" }, "tags": { "type": "array", "items": { "type": "string" } } } } ``` | JSON type | Iceberg type | Notes | | --- | --- | --- | | array | list | The keywords items and additionalItems must be used to constrain element types. | | boolean | boolean | | | null | | The null type is only supported as a nullability marker, either in a type array (for example, ["string", "null"]) or in an exclusive oneOf nullable pattern. | | number | double | | | integer | long | | | string | string | The format keyword can be used for custom Iceberg types. See format annotation translation for details. | | object | struct or map | Use properties to define struct fields and constrain their types. additionalProperties: false is supported for closed objects.If additionalProperties contains a schema, it translates to an Iceberg map.You cannot combine properties and additionalProperties in an object if additionalProperties is set to a schema. | | format value | Iceberg type | | --- | --- | | date-time | timestamptz | | date | date | | time | time | The following keywords have specific behavior: - The `$ref` keyword is supported for internal references resolved from schema resources declared in the same document (using `$id`), including relative and absolute URI forms. References to external resources and references to unknown keywords are not supported. A root-level `$ref` schema is not supported. - The `oneOf` keyword is supported only for the nullable serializer pattern where exactly one branch is `{"type":"null"}` and the other branch is a non-null schema (`T|null`). - In Iceberg output, Redpanda writes all fields as nullable regardless of serializer nullability annotations. The following are not supported for JSON Schema: - The `$dynamicRef` keyword - The `default` keyword - Conditional typing (`if`, `then`, `else`, `dependencies` keywords) - Boolean JSON Schema combinations (`allOf`, `anyOf`, and non-nullable `oneOf` patterns) - Dynamic object members with the `patternProperties` keyword - The `additionalProperties` keyword when set to `true` ## [](#suggested-reading)Suggested reading - [`redpanda.iceberg.mode` topic property reference](../../../reference/properties/topic-properties/#redpanda-iceberg-mode) ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) [Search all labs](/redpanda-labs) --- # Page 155: Use Iceberg Catalogs **URL**: https://docs.redpanda.com/current/manage/iceberg/use-iceberg-catalogs.md --- # Use Iceberg Catalogs --- title: Use Iceberg Catalogs latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: iceberg/use-iceberg-catalogs page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: iceberg/use-iceberg-catalogs.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/iceberg/use-iceberg-catalogs.adoc description: Learn how to access Redpanda topic data stored in Iceberg tables, using table metadata or a catalog integration. page-git-created-date: "2025-04-07" page-git-modified-date: "2026-04-06" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../get-started/licensing/#self-managed) apply. To read from the Redpanda-generated [Iceberg table](../about-iceberg-topics/), your Iceberg-compatible client or tool needs access to the catalog to retrieve the table metadata and know the current state of the table. The catalog provides the current table metadata, which includes locations for all the table’s data files. You can configure Redpanda to either connect to a REST-based catalog, or use a filesystem-based catalog. For production deployments, Redpanda recommends [using an external REST catalog](#rest) to manage Iceberg metadata. This enables built-in table maintenance, safely handles multiple engines and tools accessing tables at the same time, facilitates data governance, and maximizes data discovery. However, if it is not possible to use a REST catalog, you can [use the filesystem-based catalog](#object-storage) (`object_storage` catalog type), which does not require you to maintain a separate service to access the Iceberg data. In either case, you use the catalog to load, query, or refresh the Iceberg table as you produce to the Redpanda topic. See the documentation for your query engine or Iceberg-compatible tool for specific guidance on adding the Iceberg tables to your data warehouse or lakehouse using the catalog. After you have selected a catalog type at the cluster level and [enabled the Iceberg integration](../about-iceberg-topics/#enable-iceberg-integration) for a topic, you cannot switch to another catalog type. ## [](#rest)Connect to a REST catalog > 📝 **NOTE** > > Redpanda connects to an Iceberg catalog that you provision and manage. Redpanda does not create or manage the catalog service, its databases, or any associated network configuration. Connect to an Iceberg REST catalog using the standard [REST API](https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml) supported by many catalog providers. Use this catalog integration type with REST-enabled Iceberg catalog services, such as [Databricks Unity](https://docs.databricks.com/en/data-governance/unity-catalog/index.html) and [Snowflake Open Catalog](https://other-docs.snowflake.com/en/opencatalog/overview). > 💡 **TIP** > > This section provides general guidance on using REST catalogs with Redpanda. For instructions on integrating with specific REST catalog services, see the following: > > - [AWS Glue Data Catalog](../iceberg-topics-aws-glue/) > > - [Databricks Unity Catalog](../iceberg-topics-databricks-unity/) > > - [Snowflake with Open Catalog](../redpanda-topics-iceberg-snowflake-catalog/) ### [](#limitations)Limitations The Iceberg integration for Redpanda Self-Managed supports multiple Iceberg catalogs, with progressive levels of release maturity. Each catalog integration is tested and released independently. The following shows the current status of Iceberg catalog integrations. Check this list regularly as Redpanda continues to expand GA coverage for Iceberg topics. | Catalog service | Status | | --- | --- | | Databricks Unity Catalog | Supported | | Snowflake Open Catalog | Supported | | AWS Glue Data Catalog | Beta | | Google BigQuery | Beta | Other REST catalogs, such as Apache Polaris, Dremio Nessie (to be [merged with Polaris](https://www.dremio.com/newsroom/polaris-catalog-to-be-merged-with-nessie-now-available-on-github/)), and the Apache reference implementation, have been tested but are not regularly verified. For more information, contact [Redpanda Support](https://support.redpanda.com/hc/en-us/requests/new). ### [](#set-cluster-properties)Set cluster properties To connect to a REST catalog, set the following cluster configuration properties: - `[iceberg_catalog_type](../../../reference/properties/cluster-properties/#iceberg_catalog_type)`: `rest` - `[iceberg_rest_catalog_endpoint](../../../reference/properties/cluster-properties/#iceberg_rest_catalog_endpoint)`: The endpoint URL for your Iceberg catalog. You either manage this directly, or you have this managed by an external catalog service. > 📝 **NOTE** > > You must set `iceberg_rest_catalog_endpoint` at the same time that you set `iceberg_catalog_type` to `rest`. #### [](#configure-table-namespace)Configure table namespace Check if your REST catalog provider has specific requirements or recommendations for namespaces. For example, AWS Glue offers only a single global catalog per account, and each cluster that writes to the same Glue catalog must use a distinct namespace to avoid table name collisions. By default, Redpanda creates Iceberg tables in a namespace called `redpanda`. To use a unique namespace, configure the `[iceberg_default_catalog_namespace](../../../reference/properties/cluster-properties/#iceberg_default_catalog_namespace)` cluster property. You must set this property before enabling the Iceberg integration or at the same time. After you have enabled Iceberg, do not change this property value. #### [](#configure-authentication)Configure authentication To authenticate with the REST catalog, set the following cluster properties: - `[iceberg_rest_catalog_authentication_mode](../../../reference/properties/cluster-properties/#iceberg_rest_catalog_authentication_mode)`: The authentication mode to use for the REST catalog. Choose from `oauth2`, `aws_sigv4`, `bearer`, or `none` (default). You must use `aws_sigv4` for [AWS Glue Data Catalog](../iceberg-topics-aws-glue/). - For `oauth2`, also configure the following properties: - `[iceberg_rest_catalog_oauth2_server_uri](../../../reference/properties/cluster-properties/#iceberg_rest_catalog_oauth2_server_uri)`: The OAuth endpoint URI used to retrieve tokens for REST catalog authentication. If left unset, the deprecated catalog endpoint `/v1/oauth/tokens` is used as the token endpoint instead. - `[iceberg_rest_catalog_client_id](../../../reference/properties/cluster-properties/#iceberg_rest_catalog_client_id)`: The ID used to query the OAuth token endpoint for REST catalog authentication. - `[iceberg_rest_catalog_client_secret](../../../reference/properties/cluster-properties/#iceberg_rest_catalog_client_secret)`: The secret used with the client ID to query the OAuth token endpoint for REST catalog authentication. - For `bearer`, configure the `[iceberg_rest_catalog_token](../../../reference/properties/cluster-properties/#iceberg_rest_catalog_token)` property with your bearer token. Redpanda uses the bearer token unconditionally and does not attempt to refresh the token. Only use the bearer authentication mode for ad hoc or testing purposes. For REST catalogs that use self-signed certificates, also configure these properties: - `[iceberg_rest_catalog_trust](../../../reference/properties/cluster-properties/#iceberg_rest_catalog_trust)`: The contents of a certificate chain to trust for the REST catalog. - Or, use `[iceberg_rest_catalog_trust_file](../../../reference/properties/cluster-properties/#iceberg_rest_catalog_trust_file)` to specify the path to the certificate chain file. - `[iceberg_rest_catalog_crl](../../../reference/properties/cluster-properties/#iceberg_rest_catalog_crl)`: The contents of a certificate revocation list for `iceberg_rest_catalog_trust`. - Or, use `[iceberg_rest_catalog_crl_file](../../../reference/properties/cluster-properties/#iceberg_rest_catalog_crl_file)` to specify the path to the certificate revocation list file. See [Cluster Configuration Properties](../../../reference/properties/cluster-properties/) for the full list of cluster properties to configure for a catalog integration. ### [](#example-rest-catalog-configuration)Example REST catalog configuration Suppose you configure the following Redpanda cluster properties for connecting to a REST catalog: ```yaml iceberg_catalog_type: rest iceberg_rest_catalog_endpoint: http://catalog-service:8181 iceberg_rest_catalog_authentication_mode: oauth2 iceberg_rest_catalog_oauth2_server_uri: iceberg_rest_catalog_client_id: iceberg_rest_catalog_client_secret: ``` If you use Apache Spark as a processing engine, your Spark configuration might look like the following. This example uses a catalog named `streaming`: ```spark spark.sql.catalog.streaming = org.apache.iceberg.spark.SparkCatalog spark.sql.catalog.streaming.type = rest spark.sql.catalog.streaming.uri = http://catalog-service:8181 spark.sql.catalog.streaming.warehouse = # You may need to configure additional properties based on your object storage provider. # See https://iceberg.apache.org/docs/latest/spark-configuration/#catalog-configuration and https://spark.apache.org/docs/latest/configuration.html # For example, for AWS S3: # spark.sql.catalog.streaming.io-impl = org.apache.iceberg.aws.s3.S3FileIO # spark.sql.catalog.streaming.s3.endpoint = http:// ``` > 📝 **NOTE** > > Redpanda recommends setting credentials in environment variables so Spark can securely access your Iceberg data in object storage. For example, for AWS, use `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`. The Spark engine can use the REST catalog to automatically discover the topic’s Iceberg table. Using Spark SQL, you can query the Iceberg table directly by specifying the catalog name, the namespace, and the table name: ```sql SELECT * FROM streaming.redpanda.; ``` The Iceberg table name is the name of your Redpanda topic. If you configured a different namespace using `[iceberg_default_catalog_namespace](../../../reference/properties/cluster-properties/#iceberg_default_catalog_namespace)`, replace `redpanda` with your configured namespace. > 💡 **TIP** > > You may need to explicitly create a table for the Iceberg data in your query engine. For an example, see [Query Iceberg Topics using Snowflake and Open Catalog](../redpanda-topics-iceberg-snowflake-catalog/). ## [](#object-storage)Integrate filesystem-based catalog (`object_storage`) By default, Iceberg topics use the filesystem-based catalog (`[iceberg_catalog_type](../../../reference/properties/cluster-properties/#iceberg_catalog_type)` cluster property set to `object_storage`). Redpanda stores the table metadata in [HadoopCatalog](https://iceberg.apache.org/docs/latest/java-api-quickstart/#using-a-hadoop-catalog) format in the same object storage bucket or container as the data files. If using the `object_storage` catalog type, you provide the object storage URI of the table’s `metadata.json` file to an Iceberg client so it can access the catalog and data files for your Redpanda Iceberg tables. > 📝 **NOTE** > > The `metadata.json` file points to a specific Iceberg table snapshot. In your query engine, you must update your tables whenever a new snapshot is created so that they point to the latest snapshot. See the [official Iceberg documentation](https://iceberg.apache.org/docs/latest/maintenance/) for more information, and refer to the documentation for your query engine or Iceberg-compatible tool for specific guidance on Iceberg table update or refresh. ### [](#example-filesystem-based-catalog-configuration)Example filesystem-based catalog configuration To configure Apache Spark to use a filesystem-based catalog, specify at least the following properties: ```spark spark.sql.catalog.streaming = org.apache.iceberg.spark.SparkCatalog spark.sql.catalog.streaming.type = hadoop # URI for table metadata: AWS S3 example spark.sql.catalog.streaming.warehouse = s3a:///redpanda-iceberg-catalog # You may need to configure additional properties based on your object storage provider. # See https://iceberg.apache.org/docs/latest/spark-configuration/#spark-configuration and https://spark.apache.org/docs/latest/configuration.html # For example, for AWS S3: # spark.hadoop.fs.s3.impl = org.apache.hadoop.fs.s3a.S3AFileSystem # spark.hadoop.fs.s3a.endpoint = http:// # spark.sql.catalog.streaming.s3.endpoint = http:// ``` > 📝 **NOTE** > > Redpanda recommends setting credentials in environment variables so Spark can securely access your Iceberg data in object storage. For example, for AWS, use `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`. Depending on your processing engine, you may need to also create a new table to point the data lakehouse to the table location. ### [](#specify-metadata-location)Specify metadata location The `[iceberg_catalog_base_location](../../../reference/properties/cluster-properties/#iceberg_catalog_base_location)` property stores the base path for the filesystem-based catalog if using the `object_storage` catalog type. The default value is `redpanda-iceberg-catalog`. > ⚠️ **CAUTION** > > Do not change the `iceberg_catalog_base_location` value after you have enabled Iceberg integration for a topic. > 💡 **TIP** > > For an end-to-end example of using the filesystem-based catalog to access Iceberg topics, see the [Getting Started with Iceberg Topics on Redpanda BYOC](https://www.redpanda.com/blog/iceberg-topics-redpanda-cloud-byoc-setup) blog post. > > The blog post uses a Redpanda Cloud cluster, but you follow the same steps for a Self-Managed cluster. ## [](#next-steps)Next steps - [Query Iceberg Topics](../query-iceberg-topics/) - [Query Iceberg Topics using AWS Glue](../iceberg-topics-aws-glue/) - [Query Iceberg Topics using Databricks and Unity Catalog](../iceberg-topics-databricks-unity/) - [Query Iceberg Topics using Snowflake and Open Catalog](../redpanda-topics-iceberg-snowflake-catalog/) ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) [Search all labs](/redpanda-labs) --- # Page 156: Optimize I/O **URL**: https://docs.redpanda.com/current/manage/io-optimization.md --- # Optimize I/O --- title: Optimize I/O latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: io-optimization page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: io-optimization.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/io-optimization.adoc description: Learn how to optimize I/O performance. page-git-created-date: "2023-05-30" page-git-modified-date: "2024-02-26" support-status: supported --- Redpanda relies on its own disk I/O scheduler, and by default, it tells the kernel to use the `noop` scheduler. Additionally, `rpk` comes with an embedded database of I/O settings, which are specific combinations of CPUs, SSD types, and VM sizes. Because running software on four VCPUs isn’t the same as running on an EC2 i3.metal with 96 physical cores, Redpanda tries to predict the best known settings for VM cloud types. [rpk iotune](../../reference/rpk/rpk-iotune/) is a tool to optimize I/O performance for a specific Redpanda instance and its hardware. It runs benchmarks to capture the read/write IOPS and bandwidth capabilities of a node, then it outputs parameters to an I/O configuration file (`io-config.yaml`) that Redpanda reads upon startup to optimize itself for the node. `rpk iotune` by default saves its I/O configuration file to `/etc/redpanda/io-config.yaml`, and Redpanda by default reads from there at startup. > 📝 **NOTE** > > `rpk iotune` differs from `rpk redpanda tune`: > > - `rpk iotune` runs benchmarks to produce an I/O configuration file that Redpanda reads on startup to optimize its I/O performance. > > - `rpk redpanda tune` (autotuner) is a suite of tuners that automatically modify Linux kernel settings to optimize performance. > > > For reference, see [rpk iotune](../../reference/rpk/rpk-iotune/) and [rpk redpanda tune](../../reference/rpk/rpk-redpanda/rpk-redpanda-tune/) It isn’t necessary to run `rpk iotune` each time Redpanda is started, as its I/O output configuration file can be reused in nodes running on the same type of hardware. Reuse an I/O output configuration file by starting Redpanda with the `--io-properties-file` flag and the path to the file: ```bash rpk redpanda start --io-properties-file '' ``` Alternatively, the contents of the I/O configuration file can be converted to a string, and the string can be passed with the `--io-properties` flag: ```bash rpk redpanda start --io-properties '' ``` Currently in its database of I/O settings, Redpanda has well-known-types for AWS and GCP. On startup, `rpk` tries to detect the cloud and instance type from the cloud’s metadata API, setting the correct `iotune` properties. If access to the metadata API isn’t allowed from the instance, you can hint the desired setup by passing the `--well-known-io` flag with the cloud vendor, VM type, and storage type: ```bash rpk redpanda start --well-known-io 'aws:i3.xlarge:default' ``` It can also be specified in the `redpanda.yaml` configuration file, under the `rpk` object: ```yaml rpk: well_known_io: 'gcp:c2-standard-16:nvme' ``` > 💡 **TIP** > > - If `well-known-io` is specified in the config file and also as a flag, then the flag takes precedence. > > - Both `--well-known-io` and `rpk.well_known_io` cannot be set at the same time as `--io-properties-file` or `--io-properties`. If a certain cloud vendor, machine type, or storage type isn’t found, or if the metadata isn’t available and no hint is given, then `rpk` prints a warning and continues to use the default values. ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Owl Shop Example Application in Docker](/redpanda-labs/docker-compose/owl-shop/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) See more [Search all labs](/redpanda-labs) --- # Page 157: Manage Redpanda in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes.md --- # Manage Redpanda in Kubernetes --- title: Manage Redpanda in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/index.adoc description: Learn how to manage Redpanda in Kubernetes. page-git-created-date: "2023-06-02" page-git-modified-date: "2024-08-12" support-status: supported --- - [Configure Redpanda in Kubernetes](k-configure-helm-chart/) Customize the values of the Redpanda Helm chart or Redpanda resource to configure both the Redpanda cluster and the Kubernetes components. - [Configure Redpanda in Kubernetes](k-configure-helm-chart/) Customize the values of the Redpanda Helm chart or Redpanda resource to configure both the Redpanda cluster and the Kubernetes components. - [Manage Topics with the Redpanda Operator](k-manage-topics/) Use the Topic resource to declaratively create Kafka topics as part of a Redpanda deployment. Each Topic resource is mapped to a topic in your Redpanda cluster. The topic controller keeps the corresponding Kafka topic in sync with the Topic resource. - [Create and Manage Kafka Connect Connectors in Kubernetes](k-manage-connectors/) Learn how to create and manage connectors using Redpanda Console or the Kafka Connect REST API. - [Storage for Redpanda in Kubernetes](storage/) Find information about Redpanda storage in Kubernetes. - [Cloud Topics on Kubernetes](k-cloud-topics/) Configure Cloud Topics on Kubernetes to optimize for latency-tolerant, high-throughput workloads using object storage as the primary data tier. - [Tiered Storage in Kubernetes](tiered-storage/) Tiered Storage helps to lower storage costs by offloading log segments to object storage. - [Networking and Connectivity in Kubernetes](networking/) Learn how to set up and manage network connections for Redpanda in Kubernetes. This section covers a range of topics, including how to enable external access, connect clients to a Redpanda cluster, and configure listeners. - [Security for Redpanda in Kubernetes](security/) Learn what options are available for securing Redpanda clusters, including TLS encryption, authentication, authorization, and audit logging. - [Enable Rack Awareness in Kubernetes](k-rack-awareness/) Enable rack awareness to place partition replicas across different failure zones. - [Remote Read Replicas in Kubernetes](k-remote-read-replicas/) Create read-only topics (Remote Read Replica topics) that mirror topics on a different cluster. - [Shadowing in Kubernetes](shadowing/) Configure and manage shadow links for disaster recovery in Kubernetes deployments. - [Manage Pod Resources in Kubernetes](k-manage-resources/) Configure your Pod resources such as memory, CPU, and storage. - [Scale Redpanda in Kubernetes](k-scale-redpanda/) Learn how to scale a Redpanda cluster vertically to increase its resources and horizontally to add or remove brokers from a cluster. - [Enable the PVCUnbinder](k-nodewatcher/) The PVCUnbinder is an emergency backstop for Redpanda clusters that use PersistentVolumes (PVs) for the Redpanda data directory. When a node running a Redpanda Pod suddenly goes offline, the PVCUnbinder detects the lost node, retains the associated PV, and removes the corresponding PersistentVolumeClaim (PVC). This workflow allows the Redpanda Pod to be rescheduled on a new node without losing critical data. - [Decommission Brokers in Kubernetes](k-decommission-brokers/) Remove a Redpanda broker from the cluster without risking data loss or causing instability. - [Recovery Mode in Kubernetes](tiered-storage/k-recovery-mode/) Recovery mode starts Redpanda with limited functionality and disables partitions so you can repair a failed cluster. - [Monitor in Kubernetes](monitoring/) Find topics about how to monitor Redpanda deployments in Kubernetes. - [Perform a Rolling Restart of Redpanda in Kubernetes](k-rolling-restart/) Learn how to perform a rolling restart of your Redpanda cluster when it's running in Kubernetes. - [Resilience Testing in Kubernetes](k-resilience-testing/) With resilience testing, you can introduce failures and observe how the system behaves under each failure scenario. --- # Page 158: Cloud Topics on Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/k-cloud-topics.md --- # Cloud Topics on Kubernetes --- title: Cloud Topics on Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/k-cloud-topics page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/k-cloud-topics.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/k-cloud-topics.adoc description: Configure Cloud Topics on Kubernetes to optimize for latency-tolerant, high-throughput workloads using object storage as the primary data tier. page-topic-type: how-to personas: platform_admin, streaming_developer learning-objective-1: Configure object storage for Cloud Topics on Kubernetes learning-objective-2: Enable and create Cloud Topics using the Redpanda Operator or Helm learning-objective-3: Verify topic storage mode configuration page-git-created-date: "2026-03-31" page-git-modified-date: "2026-03-31" support-status: supported --- Starting in v26.1, Redpanda provides [Cloud Topics](https://docs.redpanda.com/current/reference/glossary/#cloud-topic) to support multi-modal streaming workloads in the most cost-effective way possible: as a per-topic configuration running mixed latency workloads. While standard Redpanda [topics](../../../develop/manage-topics/config-topics/) that use local storage or Tiered Storage are ideal for latency-sensitive workloads (for example, for audit logs or analytics), Cloud Topics are optimized for latency-tolerant, high-throughput workloads where cross-AZ networking charges are a major consideration that can become the dominant cost driver at high throughput. These workloads can include observability streams, offline analytics, AI/ML model training data feeds, or development environments that have flexible latency requirements. Instead of replicating every byte across expensive network links, Cloud Topics leverage durable, inexpensive cloud storage (S3, ADLS, GCS, MinIO) as the primary mechanism to both replicate data and serve it to consumers. This eliminates over 90% of the cost of replicating data over network links in multi-AZ clusters. After reading this page, you will be able to: - Configure object storage for Cloud Topics on Kubernetes - Enable and create Cloud Topics using the Redpanda Operator or Helm - Verify topic storage mode configuration ## [](#how-cloud-topics-work)How Cloud Topics work With standard Redpanda topics, data is replicated across brokers using Raft consensus and stored locally on each replica. Cloud Topics change this model: data is acknowledged only after it is uploaded to object storage, making object storage the source of truth for both replication and consumption. The end-to-end latency experienced when using Cloud Topics can range from 500 ms to as high as a few seconds with different object stores. Lower latencies may be achievable in certain environments, but Cloud Topics is optimized for throughput rather than low latency or tightly constrained tail latency. This latency profile is often acceptable for many streaming workloads, and can unlock new streaming use cases that previously were not cost effective. With Cloud Topics, data from the client is not acknowledged until it is uploaded to object storage. This maintains durability in the face of infrastructure failures, but results in an increase in both produce latency and end-to-end latency, driven by both batching of produced data and the inherent latency of the underlying object store. You should generally expect end-to-end latencies of 1-2 seconds with public cloud stores. ### [](#storage-modes)Storage modes Redpanda supports multiple storage modes that you can set at the cluster or topic level using the `redpanda.storage.mode` property: | Mode | Behavior | | --- | --- | | unset | Follows legacy behavior. Topics inherit cluster-level remote read/write settings. | | local | Data is stored only on local disk. No remote storage is used. | | tiered | Data is written locally and offloaded to object storage asynchronously using Tiered Storage. | | cloud | Data is managed primarily in object storage. Local storage acts as a cache. | ### [](#ideal-use-cases)Ideal use cases Cloud Topics are best suited for latency-tolerant workloads, including: - Observability and logging streams - Offline analytics pipelines - AI/ML training data ingestion - Development and staging environments with flexible latency requirements ### [](#limitations)Limitations - Shadow links do not currently support Cloud Topics. - Once created, a Cloud Topic cannot be converted back to a standard Redpanda topic that uses local or Tiered Storage. Conversely, existing topics created as local or Tiered Storage topics cannot be converted to Cloud Topics. - Higher produce latency compared to standard topics (expect 1-2 seconds with public cloud stores). ## [](#prerequisites)Prerequisites You must have the following: - **kubectl**: Ensure you have the [`kubectl`](https://kubernetes.io/docs/tasks/tools/#kubectl) command-line tool installed and configured to communicate with your cluster. - **Redpanda**: A [Redpanda Operator and a Redpanda resource deployed](../../../deploy/redpanda/kubernetes/k-production-deployment/) in your Kubernetes cluster running Redpanda v26.1 or later. - **Object storage**: A configured object storage backend (Amazon S3, Google Cloud Storage, Azure Blob Storage, or an S3-compatible store such as MinIO). - **Enterprise license**: A valid Redpanda Enterprise license applied to the cluster. > 📝 **NOTE** > > This feature requires an [enterprise license](../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../get-started/licensing/#self-managed) apply. To check if you already have a license key applied to your cluster: ```bash rpk cluster license info ``` ## [](#configure-object-storage)Configure object storage Cloud Topics use the same object storage configuration as Tiered Storage. If you have already configured object storage for Tiered Storage, you can skip this step and proceed to [Enable Cloud Topics](#enable-cloud-topics). For detailed instructions including IAM role configuration, access key management, and encryption options, see [Configure object storage](../tiered-storage/k-tiered-storage/#configure-object-storage) in the Tiered Storage documentation. The following examples show the minimum required configuration for each cloud provider. ### [](#amazon-s3)Amazon S3 #### Helm + Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: clusterSpec: storage: tiered: credentialsSecretRef: accessKey: name: storage-secrets key: access-key secretKey: name: storage-secrets key: secret-key config: cloud_storage_enabled: true cloud_storage_credentials_source: config_file (1) cloud_storage_region: cloud_storage_bucket: ``` | 1 | Use aws_instance_metadata instead if you are using an IAM role attached to your nodes. | | --- | --- | #### Helm `cloud-storage.yaml` ```yaml storage: tiered: credentialsSecretRef: accessKey: name: storage-secrets key: access-key secretKey: name: storage-secrets key: secret-key config: cloud_storage_enabled: true cloud_storage_credentials_source: config_file (1) cloud_storage_region: cloud_storage_bucket: ``` | 1 | Use aws_instance_metadata instead if you are using an IAM role attached to your nodes. | | --- | --- | For details on IAM roles, access keys, and AWS KMS encryption, see [Amazon S3](../tiered-storage/k-tiered-storage/#amazon-s3) in the Tiered Storage documentation. ### [](#google-cloud-storage-gcs)Google Cloud Storage (GCS) #### Helm + Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: clusterSpec: storage: tiered: credentialsSecretRef: accessKey: name: storage-secrets key: access-key secretKey: name: storage-secrets key: secret-key config: cloud_storage_enabled: true cloud_storage_credentials_source: config_file (1) cloud_storage_api_endpoint: storage.googleapis.com cloud_storage_region: cloud_storage_bucket: ``` | 1 | Use gcp_instance_metadata instead if you are using a GCP service account attached to your nodes. | | --- | --- | #### Helm `cloud-storage.yaml` ```yaml storage: tiered: credentialsSecretRef: accessKey: name: storage-secrets key: access-key secretKey: name: storage-secrets key: secret-key config: cloud_storage_enabled: true cloud_storage_credentials_source: config_file (1) cloud_storage_api_endpoint: storage.googleapis.com cloud_storage_region: cloud_storage_bucket: ``` | 1 | Use gcp_instance_metadata instead if you are using a GCP service account attached to your nodes. | | --- | --- | For details on IAM roles, HMAC access keys, and customer-managed encryption keys, see [Google Cloud Storage](../tiered-storage/k-tiered-storage/#google-cloud-storage) in the Tiered Storage documentation. ### [](#azure-blob-storage)Azure Blob Storage #### Helm + Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: clusterSpec: storage: tiered: credentialsSecretRef: accessKey: name: storage-secrets key: shared-key config: cloud_storage_enabled: true cloud_storage_credentials_source: config_file (1) cloud_storage_azure_storage_account: cloud_storage_azure_container: ``` | 1 | Use azure_aks_oidc_federation instead if you are using an Azure managed identity. When using managed identities, omit credentialsSecretRef and configure workload identity annotations on the service account. | | --- | --- | #### Helm `cloud-storage.yaml` ```yaml storage: tiered: credentialsSecretRef: accessKey: name: storage-secrets key: shared-key config: cloud_storage_enabled: true cloud_storage_credentials_source: config_file (1) cloud_storage_azure_storage_account: cloud_storage_azure_container: ``` | 1 | Use azure_aks_oidc_federation instead if you are using an Azure managed identity. When using managed identities, omit credentialsSecretRef and configure workload identity annotations on the service account. | | --- | --- | For details on managed identities and account access keys, see [Microsoft ABS/ADLS](../tiered-storage/k-tiered-storage/#microsoft-absadls) in the Tiered Storage documentation. ## [](#enable-cloud-topics)Enable Cloud Topics To enable Cloud Topics, set the `cloud_topics_enabled` cluster property to `true` and set the default storage mode for all new topics to `cloud`. ### Helm + Operator 1. Add the following to your Redpanda custom resource to enable Cloud Topics and set the default storage mode: `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: clusterSpec: storage: tiered: mountType: none credentialsSecretRef: accessKey: name: cloud-storage-creds key: access-key secretKey: name: cloud-storage-creds key: secret-key config: cloud_storage_enabled: true cloud_storage_region: cloud_storage_bucket: config: cluster: cloud_topics_enabled: true default_redpanda_storage_mode: cloud (1) ``` | 1 | Optional. Set to cloud to make all new topics Cloud Topics by default. Omit this to create Cloud Topics individually. | | --- | --- | 2. Apply the configuration: ```bash kubectl apply -f redpanda-cluster.yaml -n ``` 3. The Redpanda Operator reconciles the configuration. Wait for the cluster to be ready: ```bash kubectl rollout status statefulset redpanda -n --watch ``` 4. Verify that Cloud Topics are enabled: ```bash kubectl exec -n redpanda-0 -c redpanda -- \ rpk cluster config get cloud_topics_enabled ``` Expected output: `true` ### Helm 1. Add the following to your Helm values file: `cloud-topics-values.yaml` ```yaml storage: tiered: mountType: none credentialsSecretRef: accessKey: name: cloud-storage-creds key: access-key secretKey: name: cloud-storage-creds key: secret-key config: cloud_storage_enabled: true cloud_storage_region: cloud_storage_bucket: config: cluster: cloud_topics_enabled: true default_redpanda_storage_mode: cloud (1) ``` | 1 | Optional. Set to cloud to make all new topics Cloud Topics by default. Omit this to create Cloud Topics individually. | | --- | --- | 2. Deploy or upgrade the Helm chart: ```bash helm upgrade --install redpanda redpanda/redpanda \ -n --create-namespace \ -f cloud-topics-values.yaml ``` 3. Wait for the cluster to be ready: ```bash kubectl rollout status statefulset redpanda -n --watch ``` 4. Verify that Cloud Topics are enabled: ```bash kubectl exec -n redpanda-0 -c redpanda -- \ rpk cluster config get cloud_topics_enabled ``` Expected output: `true` ## [](#create-a-cloud-topic)Create a Cloud Topic You can create Cloud Topics either by setting the cluster default storage mode to `cloud`, or by configuring individual topics. ### [](#create-cloud-topics-by-default)Create Cloud Topics by default If you set `default_redpanda_storage_mode` to `cloud` in the cluster configuration, all new topics inherit the `cloud` storage mode automatically. Verify the cluster default: ```bash kubectl exec -n redpanda-0 -c redpanda -- \ rpk cluster config get default_redpanda_storage_mode ``` Expected output: `cloud` Any new topic created without an explicit storage mode inherits this default: `cloud-topic.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Topic metadata: name: my-cloud-topic namespace: spec: partitions: 3 replicationFactor: 3 cluster: clusterRef: name: redpanda ``` ```bash kubectl apply -f cloud-topic.yaml ``` ### [](#create-individual-cloud-topics)Create individual Cloud Topics If the cluster default storage mode is not set to `cloud`, you can create individual Cloud Topics by setting the `redpanda.storage.mode` property on the topic. `cloud-topic.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Topic metadata: name: my-cloud-topic namespace: spec: partitions: 3 replicationFactor: 3 additionalConfig: redpanda.storage.mode: "cloud" cluster: clusterRef: name: redpanda ``` ```bash kubectl apply -f cloud-topic.yaml ``` ### [](#override-the-cluster-default)Override the cluster default Topic-level storage mode settings override the cluster default. For example, if the cluster default is `cloud`, you can create a topic that uses Tiered Storage instead: `tiered-topic.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Topic metadata: name: my-tiered-topic namespace: spec: partitions: 3 replicationFactor: 3 additionalConfig: redpanda.storage.mode: "tiered" cluster: clusterRef: name: redpanda ``` ## [](#verify-topic-storage-mode)Verify topic storage mode To verify the storage mode of a topic, inspect its configuration through the Topic resource status: ```bash kubectl get topic -n -o jsonpath=\ '{range .status.topicConfiguration[*]}{.name}={.value} ({.source}){"\n"}{end}' \ | grep storage.mode ``` Expected output for a Cloud Topic: storage.mode=cloud (DEFAULT\_CONFIG) Or, if explicitly set on the topic: storage.mode=cloud (DYNAMIC\_TOPIC\_CONFIG) The `source` field indicates whether the value was inherited from the cluster default (`DEFAULT_CONFIG`) or explicitly set on the topic (`DYNAMIC_TOPIC_CONFIG`). ## [](#suggested-reading)Suggested reading - [Use Tiered Storage on Kubernetes](../tiered-storage/k-tiered-storage/) - [Manage Topics with the Redpanda Operator](../k-manage-topics/) --- # Page 159: Configure Redpanda in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/k-configure-helm-chart.md --- # Configure Redpanda in Kubernetes --- title: Configure Redpanda in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/k-configure-helm-chart page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/k-configure-helm-chart.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/k-configure-helm-chart.adoc description: Customize the values of the Redpanda Helm chart or Redpanda resource to configure both the Redpanda cluster and the Kubernetes components. page-git-created-date: "2024-01-04" page-git-modified-date: "2025-08-27" support-status: supported --- To configure the cluster and the Kubernetes components that the chart deploys, you can customize the values of the Redpanda Helm chart. Helm does a three-way merge with the following: - Your overridden values - The values in the existing Helm release - The default values in the new Helm release (if you’re upgrading) ## [](#find-configuration-options)Find configuration options To see what options you can override in the chart, use the `helm show values` command: ```bash helm repo add redpanda https://charts.redpanda.com helm repo update helm show values redpanda/redpanda ``` This command displays all the values, descriptions, and defaults, which are also documented in the [Redpanda Helm Chart Specification](../../../reference/k-redpanda-helm-spec/). ## [](#configure-redpanda)Configure Redpanda #### Operator To customize the values of the Redpanda Helm chart, you can override the defaults in the [Redpanda custom resource](../../../reference/k-crd/#redpanda). You must add all your overrides to the `spec.clusterSpec` configuration. `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: {} ``` For example, to override the `storage.persistentVolume.storageClass` configuration: `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: storage: persistentVolume: storageClass: "" ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` The values in your Redpanda custom resource override their counterparts in the Helm chart’s `values.yaml` file. Any values that are not overridden maintain their defaults. #### Helm To customize the values of the Redpanda Helm chart, you can override the defaults in your own YAML file with the `--values` option or in the command line with the `--set` option. > 💡 **TIP** > > Redpanda Data recommends using the `--values` option and creating separate YAML files for each configuration block that you need to override. The Redpanda documentation follows this best practice. This way, it’s clearer to understand what you’ve overridden from the `helm` command. > > You can pass more than one `--values` option in the same command. For example, if you wanted to override the TLS configuration and the storage configuration, you could put those overrides in separate files: > > ```bash > helm upgrade --install redpanda redpanda/redpanda \ > --namespace --create-namespace \ > --values custom-storage-class.yaml \ > --values enable-tls.yaml > ``` ##### --values The `--values` option enables you to keep your overrides in one or more YAML files. If you specify multiple files and then override the same values in two or more of them, the rightmost file takes precedence. For example, you might override the `storage.persistentVolume.storageClass` configuration in a file called `storage-class.yaml`: `storage-class.yaml` ```yaml storage: persistentVolume: storageClass: "my-storage-class" ``` The `helm` command to apply this configuration override looks something like the following: ```bash helm upgrade --install redpanda redpanda/redpanda \ --namespace --create-namespace \ --values storage-class.yaml --reuse-values ``` The values in your YAML files override their counterparts in the Helm chart’s `values.yaml` file. Any values that are not overridden maintain their defaults. Use the `--reuse-values` flag to apply your overrides on top of existing overrides that you’ve already made. Don’t include this flag if you’re upgrading to a new version of the Helm chart. If you’re upgrading to a new version of the Helm chart, this flag prevents any values in the new release from being applied. ##### --set The `--set` option allows you to specify configuration overrides in the command line. For example, you might override the `storage.persistentVolume.storageClass` configuration like so: ```bash helm upgrade --install redpanda redpanda/redpanda \ --namespace --create-namespace \ --set storage.persistentVolume.storageClass=my-storage-class ``` For more details, see the [Helm documentation](https://helm.sh/docs/intro/using_helm/#customizing-the-chart-before-installing). The values in the `--set` options override their counterparts in the Helm chart’s `values.yaml` file. Any values that are not overridden maintain their defaults. > 📝 **NOTE** > > If you’re upgrading and you already have Redpanda Console installed, set `console.enabled` to `false` to stop Helm from trying to deploy it again. ### [](#set-redpanda-cli-flags)Set Redpanda CLI flags You can specify Redpanda CLI flags, such as `--smp`, `--memory`, or `--reserve-memory`, directly rather than having to find the appropriate stanza in the YAML values. When you specify CLI flags, those values take precedence over the values defined in the YAML values. #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: statefulset: additionalRedpandaCmdFlags: - ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `redpanda-flags.yaml` ```yaml statefulset: additionalRedpandaCmdFlags: - ``` ```bash helm upgrade --install redpanda redpanda/redpanda \ --namespace --create-namespace \ --values redpanda-flags.yaml --reuse-values ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda \ --namespace --create-namespace \ --set "statefulset.additionalRedpandaCmdFlags=[]" ``` ### [](#set-redpanda-cluster-properties)Set Redpanda cluster properties Cluster properties control the core behavior of your Redpanda cluster, such as topic auto-creation, log retention, and feature flags. You can set any cluster property using the `config.cluster` field in your Helm values or Redpanda custom resource. For a full list of available properties and their defaults, see [cluster configuration properties](../../../reference/properties/cluster-properties/). Example: Enable automatic topic creation ```yaml config: cluster: auto_create_topics_enabled: true ``` You can set multiple properties under `config.cluster` as needed. This method works for all cluster properties, including those for advanced features like Tiered Storage. To set cluster properties using the Operator or Helm, add the `config.cluster` block to your YAML file or use the `--set` flag. See the examples below for both approaches. ### [](#extra-cluster-config)Use Kubernetes Secrets or ConfigMaps Starting in v25.1.1 of the Redpanda Operator and Redpanda Helm chart, you can set **any Redpanda cluster configuration property** by referencing Kubernetes Secrets or ConfigMaps using the `config.extraClusterConfiguration` field. This feature provides a more secure, maintainable, and declarative way to manage sensitive or shared configuration values across your Redpanda deployment. Use this method to: - Securely inject sensitive values, such as credentials for Iceberg, TLS, or object storage. - Reuse the same value across multiple features, such as Tiered Storage, Iceberg, and disaster recovery, without duplication. - Centralize config management in Kubernetes-native resources to support GitOps and reduce drift. For example, to set `iceberg_rest_catalog_client_secret` using a Secret called `iceberg-config`: #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: clusterSpec: config: extraClusterConfiguration: iceberg_rest_catalog_client_secret: secretKeyRef: name: iceberg-config key: iceberg_rest_catalog_client_secret ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `redpanda-config.yaml` ```yaml config: extraClusterConfiguration: iceberg_rest_catalog_client_secret: secretKeyRef: name: iceberg-config key: iceberg_rest_catalog_client_secret ``` ```bash helm upgrade --install redpanda redpanda/redpanda \ --namespace --create-namespace \ --values redpanda-config.yaml --reuse-values ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda \ --namespace \ --create-namespace \ --set config.extraClusterConfiguration.iceberg_rest_catalog_client_secret.secretKeyRef.name=iceberg-config \ --set config.extraClusterConfiguration.iceberg_rest_catalog_client_secret.secretKeyRef.key=iceberg_rest_catalog_client_secret ``` This method supports both `secretKeyRef` and `configMapKeyRef`: - Use `secretKeyRef` for sensitive data like access keys or credentials. - Use `configMapKeyRef` for shared, non-sensitive values such as URIs or feature flags. You can apply this approach to any Redpanda configuration key, making your deployments more secure, modular, and easier to manage at scale. For full configuration options, see [Properties](../../../reference/properties/). ### [](#export-a-redpanda-configuration-file)Export a Redpanda configuration file To see all Redpanda configurations for a broker, you can use the `rpk cluster config export` command to save the current Redpanda configuration to a file. For example, you may want to use the configuration file during debugging. > 💡 **TIP** > > To get more detailed information about your Redpanda deployment, generate a [diagnostics bundle](../../../troubleshoot/debug-bundle/generate/kubernetes/), which includes the Redpanda configuration files for all brokers in the cluster. 1. Execute the `rpk cluster config export` command inside a Pod container that’s running a Redpanda broker. ```bash kubectl exec redpanda-0 --namespace -c redpanda -- \ rpk cluster config export --filename .yaml ``` To save the configuration file outside of your current working directory, provide an absolute path to the `--filename` flag. Otherwise, the file is saved in your current working directory. Example output ```none Wrote configuration to file "/tmp/config_625125906.yaml". ``` 2. On your host machine, make a directory in which to save the configuration file: ```bash mkdir configs ``` 3. Copy the configuration file from the Pod to your host machine: Replace `` with the path to your exported file. ```bash kubectl cp redpanda/redpanda-0: configs/redpanda-0-configuration-file.yaml ``` 4. Remove the exported file from the Redpanda container: ```bash kubectl exec redpanda-0 -c redpanda --namespace -- rm ``` When you’ve finished with the file, remove it from your host machine: ```bash rm -r configs ``` ### [](#reset-config)Reset configuration values You may want to reset a configuration value back to its default. The method to do this depends on how you’re managing your Redpanda deployment. #### Operator If you’re using the Redpanda Operator and want to reset a configuration property back to its default: 1. Add the following annotation to your Redpanda custom resource to enable declarative configuration sync: ```yaml metadata: annotations: operator.redpanda.com/config-sync-mode: Declarative ``` 2. Remove the configuration key you want to reset from `spec.clusterSpec.config`. With this annotation, the Redpanda Operator ensures that removed keys are also removed from the Redpanda cluster configuration. If this annotation is not set, the Redpanda Operator retains previously applied values even if you remove them from the custom resource. #### CLI To reset a configuration property using the Redpanda CLI: - Run the [`rpk cluster config set`](../../../reference/rpk/rpk-cluster/rpk-cluster-config-set/) command with an empty string: ```bash rpk cluster config set "" ``` - Or, use the [`rpk cluster config edit`](../../../reference/rpk/rpk-cluster/rpk-cluster-config-edit/) command and delete the line for the property. If you’re using a file, such as a `values.yaml` or a Redpanda resource, to manage your configuration, make sure to also remove the property from that file. Otherwise, it may be reapplied the next time you run `helm upgrade` or the Pods restart. ## [](#configure-redpanda-console)Configure Redpanda Console Redpanda Console is included as a subchart of the Redpanda Helm chart. You can configure Redpanda Console in the `console.config` object using the [Redpanda Console configuration values](../../../console/config/configure-console/). For example, to enable the admin API for Redpanda Console: ### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: console: enabled: true console: config: redpanda: adminApi: enabled: true urls: - http://redpanda-0.redpanda..svc.cluster.local.:9644 ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ### Helm #### --values `console-enable-admin-api.yaml` ```yaml console: enabled: true console: config: redpanda: adminApi: enabled: true urls: - http://redpanda-0.redpanda..svc.cluster.local.:9644 ``` ```bash helm upgrade --install redpanda redpanda/redpanda \ --namespace --create-namespace \ --values console-enable-admin-api.yaml --reuse-values ``` #### --set ```bash helm upgrade --install redpanda redpanda/redpanda \ --namespace --create-namespace \ --set console.console.config.redpanda.adminApi.enabled=true \ --set console.console.config.redpanda.adminApi.urls={"http://redpanda-0.redpanda..svc.cluster.local.:9644"} ``` If you want to use the separate Redpanda Console Helm chart, disable Redpanda Console in the Redpanda Helm chart with `console.enabled=false`. To see what options you can override in the Redpanda Console chart, use the `helm show values` command: ```bash helm repo add redpanda https://charts.redpanda.com helm repo update helm show values redpanda/console ``` For default values and documentation for configuration options, see the [`values.yaml`](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values) file. ## [](#differences-between-helm-install-and-helm-upgrade)Differences between helm install and helm upgrade When managing Redpanda deployments with Helm, it’s important to understand the differences between `helm install` and `helm upgrade`, particularly in how they handle cluster configuration overrides. Use `helm install` to install or reinstall Redpanda. Use `helm upgrade` to reconfigure an existing deployment. ### [](#reinstall-redpanda)Reinstall Redpanda When reinstalling Redpanda with `helm install`, cluster configuration overrides specified in the Helm values may not take effect due to PersistentVolumeClaim (PVC) retention. By default, most PVCs are retained when a Helm release is uninstalled. As a result, when Redpanda is reinstalled, the previously created PVCs are adopted, restoring the state of the previous cluster. This adoption results in the new `bootstrap.yaml` file being ignored and the `post_upgrade` job not running. The `post_upgrade` job is a component in the Helm chart that applies configuration overrides during an upgrade. To ensure the new installation does not adopt the old PVCs and restore the previous state: 1. Delete the existing PVCs before reinstalling Redpanda: ```bash kubectl delete pvc -l app=redpanda --namespace ``` 2. Execute the `helm install` command to reinstall Redpanda with a clean state. ### [](#configure-an-existing-cluster)Configure an existing cluster During a `helm upgrade`, the `post_upgrade` job is triggered, which applies the latest overrides to the cluster. ## [](#suggested-reading)Suggested reading - [Customizing the Chart Before Installing](https://helm.sh/docs/intro/using_helm/#customizing-the-chart-before-installing). ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Owl Shop Example Application in Docker](/redpanda-labs/docker-compose/owl-shop/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) See more [Search all labs](/redpanda-labs) --- # Page 160: Decommission Brokers in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/k-decommission-brokers.md --- # Decommission Brokers in Kubernetes --- title: Decommission Brokers in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/k-decommission-brokers page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/k-decommission-brokers.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/k-decommission-brokers.adoc description: Remove a Redpanda broker from the cluster without risking data loss or causing instability. page-git-created-date: "2024-01-04" page-git-modified-date: "2026-03-31" support-status: supported --- Decommissioning a broker is the **safe and controlled** way to remove a Redpanda broker from the cluster without risking data loss or causing instability. By decommissioning, you ensure that partition replicas are reallocated across the remaining brokers so that you can then safely shut down the broker. You may want to decommission a broker in the following situations: - You are removing a broker to decrease the size of the cluster, also known as scaling down. - The broker has lost its storage and you need a new broker with a new node ID (broker ID). - You are replacing a worker node, for example, by upgrading the Kubernetes cluster or replacing the hardware. > 📝 **NOTE** > > When a broker is decommissioned, it cannot rejoin the cluster. If a broker with the same ID tries to rejoin the cluster, it is rejected. ## [](#decommissioning-methods)Decommissioning methods There are two ways to decommission brokers in Redpanda: - Manual decommissioning (described in this guide): Use `rpk` commands or Kubernetes automation to explicitly decommission a broker when you need full control over the timing and selection of brokers to remove. - Automatic decommissioning: When [Continuous Data Balancing](../../cluster-maintenance/continuous-data-balancing/) is enabled, you can configure the [partition\_autobalancing\_node\_autodecommission\_timeout\_sec](../../cluster-maintenance/continuous-data-balancing/#partition_autobalancing_node_autodecommission_timeout_sec) property to automatically decommission brokers that remain unavailable for a specified duration. Both methods permanently remove the broker from the cluster. Decommissioned brokers cannot rejoin. ## [](#prerequisites)Prerequisites You must have the following: - Kubernetes cluster: Ensure you have a running Kubernetes cluster, either locally, with minikube or kind, or remotely. - [Kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl): Ensure you have the `kubectl` command-line tool installed and configured to communicate with your cluster. - [`jq`](https://stedolan.github.io/jq/download/): This guide uses `jq` make parsing JSON output easier. ## [](#what-happens-when-a-broker-is-decommissioned)What happens when a broker is decommissioned? When a broker is decommissioned, the controller leader creates a reallocation plan for all partition replicas that are allocated to that broker. By default, this reallocation is done in batches of 50 to avoid overwhelming the remaining brokers with Raft recovery. See [`partition_autobalancing_concurrent_moves`](../../../reference/properties/cluster-properties/#partition_autobalancing_concurrent_moves). The reallocation of each partition is translated into a Raft group reconfiguration and executed by the controller leader. The partition leader then handles the reconfiguration for its Raft group. After the reallocation for a partition is complete, it is recorded in the controller log and the status is updated in the topic tables of each broker. The decommissioning process is successful only when all partition reallocations have been completed. The controller leader polls for the status of all the partition-level reallocations to ensure that everything completes as expected. During the decommissioning process, new partitions are not allocated to the broker that is being decommissioned. After all the reallocations have been completed successfully, the broker is removed from the cluster. > 📝 **NOTE** > > The decommissioning process is designed to tolerate controller leadership transfers. ## [](#should-you-decommission-brokers)Should you decommission brokers? Deciding whether to decommission brokers requires careful evaluation of various factors that contribute to the overall health your cluster. For the purposes of this section, the focus is on a cluster with seven brokers. In subsequent sections, the output from the given commands provides additional details to help you determine the minimum number of brokers required in a cluster before it’s safe to decommission brokers. ### [](#availability)Availability You should have enough brokers to span across each rack or availability zone. Run the following command to determine whether rack awareness is enabled in your cluster: ```bash rpk cluster config get enable_rack_awareness ``` When rack awareness is enabled, you can view which rack each broker is assigned to by running the following command: ```bash rpk cluster info ``` Example output ```none CLUSTER ======= redpanda.560e2403-3fd6-448c-b720-7b456d0aa78c BROKERS ======= ID HOST PORT RACK 0 redpanda-0.testcluster.local 32180 A 1 redpanda-1.testcluster.local 32180 A 4 redpanda-3.testcluster.local 32180 B 5* redpanda-2.testcluster.local 32180 B 6 redpanda-4.testcluster.local 32180 C 8 redpanda-6.testcluster.local 32180 C 9 redpanda-5.testcluster.local 32180 D ``` The output shows four racks (A/B/C/D), so you might want to have at least four brokers to use all racks. Rack awareness is just one aspect of availability. Refer to [High Availability](../../../deploy/redpanda/kubernetes/k-high-availability/) for more details on deploying Redpanda for high availability. ### [](#cost)Cost Infrastructure costs increase with each broker because each broker requires a dedicated node (instance), so adding a broker means an additional instance cost. For example, if the instance cost is $1925 per month in a cluster with seven brokers, the instance cost for each broker is $275. Reducing the number of brokers from seven to five would save $550 per month ($275 x 2), and reducing it to three brokers would save $1100 per month. You must also consider other costs, but they won’t be as impacted by changing the broker count. ### [](#data-retention)Data retention Local data retention is determined by the storage capability of each broker and producer throughput, which is the amount of data produced over a given period. When decommissioning, storage capability must consider both the free storage space and the amount of space already in use by existing partitions. Run the following command to determine how much storage is being used, in bytes, on each broker: ```bash rpk cluster logdirs describe --aggregate-into broker ``` Example output ```none BROKER SIZE ERROR 0 263882790656 1 256177979648 2 257698037504 3 259934992896 4 254087316992 5 258369126144 6 255227998208 ``` This example shows that each broker has roughly 240GB of data. This means scaling in to five brokers would require each broker to have at least 337GB to store that same data. Keep in mind that the actual space used on disk will be greater than the data size reported by Redpanda. Redpanda reserves some data on disk per partition and reserves less space per partition as available disk space decreases. Incoming data for each partition is then written to disk as segments (files). The time when segments are written to disk is based on a number of factors, including the topic’s segment configuration, broker restarts, and changes in Raft leadership. Throughput is the primary measurement required to calculate future data storage requirements. For example, if the throughput is 200MB/sec, the application will generate 0.72TB/hour (17.28TB/day, or 120.96TB/wk). Divide this amount by the target number of brokers to get an estimate of how much storage is needed to retain that much data for various periods of time: | Retention | Disk size (on each of the 5 brokers) | | --- | --- | | 30mins | (200MB/sec * 30mins * 1.1) = 0.396TB / 5 brokers = 79.2GB | | 6hrs | (200MB/sec * 6hrs * 1.1) = = 4.752TB / 5 brokers = 950.4GB | | 1d | (200MB/sec * 1d * 1.1) = 19.008TB / 5 brokers = 3.8TB | | 3d | (200MB/sec * 3d * 1.1) = 57.024TB / 5 brokers = 11.4TB | In the example cluster, only six hours of data locally must be retained. Any older data can be moved to [Tiered Storage](../tiered-storage/k-tiered-storage/) with a retention of one year. So each broker should have 1.2TB of storage available, taking into account both throughput and current data. Cost and use case requirements determine how much to spend on local disk capacity. Tiered Storage can help to both decrease costs and expand data retention capabilities. > 📝 **NOTE** > > At this point in the example, it remains unclear whether it is safe to scale down to five brokers. Current calculations are based on five brokers. > > Additionally, some assumptions have been made regarding a constant throughput and perfect data balancing. Throughput fluctuates across all partitions, which causes data imbalance. The calculations presented as examples attempt to accommodate for this by padding disk size by 1%. You can increase this buffer, for example in the case of expected hot spot partitions. For details on sizing, see [Sizing Guidelines](../../../deploy/redpanda/manual/sizing/). ### [](#durability)Durability The brokers in a Redpanda cluster are part of a Raft group that requires at least enough brokers to form a quorum-based majority (three brokers minimally). Each topic’s partitions are also Raft groups, so your cluster also needs to have at least as many brokers as the lowest replication factor across all topics. To find the maximum replication factor across all topics in a cluster, run the following command: ```bash rpk topic list | tail -n +2 | awk '{print $3}' | sort -n | tail -1 ``` Example output: 5 In this example, the highest replication factor is five, which means that at least five brokers are required in this cluster. Generally, a cluster can withstand a higher number of brokers going down if more brokers exist in the cluster. For details, see [Raft consensus algorithm](../../../get-started/architecture/#raft-consensus-algorithm). ### [](#partition-count)Partition count It is best practice to make sure the total partition count does not exceed 1K per core. This maximum partition count depends on many other factors, such as memory per core, CPU performance, throughput, and latency requirements. Exceeding 1K partitions per core can lead to increased latency, an increased number of partition leadership elections, and generally reduced stability. Run the following command to get the total partition count for your cluster: ```bash curl -sk http://:/v1/partitions/local_summary | jq .count ``` Example output: 3018 Next, determine the number of cores that are available across the remaining brokers: ```bash rpk redpanda admin brokers list ``` Example output ```none ID HOST PORT RACK CORES MEMBERSHIP IS-ALIVE VERSION UUID 0 redpanda-0.testcluster.local 32180 A 8 active true 25.2.13 24c08934-94f6-478c-b57d-45239f452488 1 redpanda-1.testcluster.local 32180 B 8 active true 25.2.13 7f3c1c6e-2f4d-4c8a-9c6e-0a8a6d8b2b61 2 redpanda-2.testcluster.local 32180 C 8 active true 25.2.13 b2e8d4a9-91c1-4b55-9f6a-3f7a2d3c5e44 3 redpanda-3.testcluster.local 32180 A 8 active true 25.2.13 c9a6f7d2-5e3b-4f8c-8d1a-6e2b4a9f7c31 4 redpanda-4.testcluster.local 32180 B 8 active true 25.2.13 4e8b1c3a-9d7f-4a6e-b2c5-8f6d1a3e9b74 5 redpanda-5.testcluster.local 32180 C 8 active true 25.2.13 a1f9c6b4-3d2e-4a8f-9e5b-7c6d8a1b2f93 6 redpanda-6.testcluster.local 32180 A 8 active true 25.2.13 e6b4d2a8-5f1c-4e9b-8a3d-9c7f1b6a5e42 ``` In this example, each broker has eight cores available. If you plan to scale down to five brokers, then you would have 40 cores available, which means that your cluster is limited by core count to 40K partitions, which exceeds the current 3018 partitions. > 📝 **NOTE** > > To best ensure the stability of the cluster, maintain less than 50K partitions per cluster. ### [](#decommission-assessment)Decommission assessment The considerations tested above yield the following for the example case: - At least four brokers are required based on availability. - Cost is not a limiting factor in this example, but lower cost and lower broker count is always best. - At least 1.2TB of data resides on each broker when spread across five brokers. This falls within the 1.5TB of local storage available in the example. - At least five brokers are required based on the highest replication factor across all topics. - At 3018 partitions, the partition count is so low as to not be a determining factor in broker count (a single broker in this example environment could handle many more partitions). So the primary limitation consideration is the replication factor of five, meaning that you could scale down to five brokers at minimum. ## [](#decommission-a-broker)Decommission a broker To decommission a broker, you can use one of the following methods: - [Manually decommission a broker](#Manual): Use `rpk` to decommission one broker at a time. - [Use the BrokerDecommissioner](#Automated): Use the BrokerDecommissioner to automatically decommission brokers whenever you reduce the number of StatefulSet replicas. ### [](#Manual)Manually decommission a broker Follow this workflow to manually decommission a broker before reducing the number of StatefulSet replicas: flowchart TB %% Define classes classDef userAction stroke:#374D7C, fill:#E2EBFF, font-weight:bold,rx:5,ry:5 A\[Start Manual Scale-In\]:::userAction --> B\["Identify broker to R=remove (highest Pod ordinal)"\]:::userAction B --> C\[Decommission broker running on Pod with highest ordinal\]:::userAction C --> D\[Monitor decommission status\]:::userAction D --> E{Is broker removed?}:::userAction E -- No --> D E -- Yes --> F\[Decrease StatefulSet replicas by 1\]:::userAction F --> G\[Wait for rolling update and cluster health\]:::userAction G --> H{More brokers to remove?}:::userAction H -- Yes --> B H -- No --> I\[Done\]:::userAction 1. List your brokers and their associated broker IDs: ```bash kubectl --namespace exec -ti redpanda-0 -c redpanda -- \ rpk cluster info ``` Example output ```none CLUSTER ======= redpanda.560e2403-3fd6-448c-b720-7b456d0aa78c BROKERS ======= ID HOST PORT RACK 0 redpanda-0.testcluster.local 32180 A 1 redpanda-1.testcluster.local 32180 A 4 redpanda-3.testcluster.local 32180 B 5* redpanda-2.testcluster.local 32180 B 6 redpanda-4.testcluster.local 32180 C 8 redpanda-6.testcluster.local 32180 C 9 redpanda-5.testcluster.local 32180 D ``` The output shows that the IDs don’t match the StatefulSet ordinal, which appears in the hostname. In this example, two brokers will be decommissioned: `redpanda-6` (ID 8) and `redpanda-5` (ID 9). > 📝 **NOTE** > > When scaling in a cluster, you cannot choose which broker is removed. Redpanda is deployed as a StatefulSet in Kubernetes. The StatefulSet controls which Pods are destroyed and always starts with the Pod that has the highest ordinal. So the first broker to be removed when updating the StatefulSet in this example is `redpanda-6` (ID 8). 2. Decommission the broker with the highest Pod ordinal: ```bash kubectl --namespace exec -ti -c -- \ rpk redpanda admin brokers decommission ``` This message is displayed before the decommission process is complete. ```bash Success, broker has been decommissioned! ``` > 💡 **TIP** > > If the broker is not running, use the `--force` flag. 3. Monitor the decommissioning status: ```bash kubectl --namespace exec -ti -c -- \ rpk redpanda admin brokers decommission-status ``` The output uses cached cluster health data that is refreshed every 10 seconds. When the completion column for all rows is 100%, the broker is decommissioned. Another way to verify decommission is complete is by running the following command: ```bash kubectl --namespace exec -ti -c -- \ rpk cluster health ``` Be sure to verify that the decommissioned broker’s ID does not appear in the list of IDs. In this example, ID 9 is missing, which means the decommission is complete. ```none CLUSTER HEALTH OVERVIEW ======================= Healthy: true Controller ID: 0 All nodes: [4 1 0 5 6 8] Nodes down: [] Leaderless partitions: [] Under-replicated partitions: [] ``` 4. Decrease the number of replicas **by one** to remove the Pod with the highest ordinal (the one you just decommissioned). > ⚠️ **CAUTION: Reduce replicas by one** > > When scaling in (removing brokers), remove only one broker at a time. If you reduce the StatefulSet replicas by more than one, Kubernetes can terminate multiple Pods simultaneously, causing quorum loss and cluster unavailability. #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: statefulset: replicas: ``` Apply the Redpanda resource: ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `decommission.yaml` ```yaml statefulset: replicas: ``` ##### --set ```bash helm upgrade redpanda redpanda/redpanda --namespace --wait --reuse-values --set statefulset.replicas= ``` This process triggers a rolling restart of each Pod so that each broker has an up-to-date `seed_servers` configuration to reflect the new list of brokers. You can repeat this procedure to continue to scale down. ### [](#Automated)Use the BrokerDecommissioner The BrokerDecommissioner is responsible for monitoring the StatefulSet for changes in the number replicas. When the number of replicas is reduced, the controller decommissions brokers, starting from the highest Pod ordinal, until the number of brokers matches the number of replicas. flowchart TB %% Define classes classDef userAction stroke:#374D7C, fill:#E2EBFF, font-weight:bold,rx:5,ry:5 classDef systemAction fill:#F6FBF6,stroke:#25855a,stroke-width:2px,color:#20293c,rx:5,ry:5 %% Legend subgraph Legend direction TB UA(\[User action\]):::userAction SE(\[System event\]):::systemAction end Legend ~~~ Workflow %% Main workflow subgraph Workflow direction TB A\[Start automated scale-in\]:::userAction --> B\[Decrease StatefulSet replicas by 1\]:::userAction B --> C\[BrokerDecommissioner detects reduced replicas\]:::systemEvent C --> D\[Controller marks highest ordinal Pod for removal\]:::systemEvent D --> E\[Controller orchestrates broker decommission\]:::systemEvent E --> F\[Partitions reallocate under controller supervision\]:::systemEvent F --> G\[Check cluster health\]:::systemEvent G --> H{Broker fully removed?}:::systemEvent H -- No --> F H -- Yes --> I\[Done, or repeat if further scale-in needed\]:::userAction end For example, you have a Redpanda cluster with the following brokers: ID HOST 0 redpanda-0.testcluster.local 1 redpanda-1.testcluster.local 4 redpanda-3.testcluster.local 5\* redpanda-2.testcluster.local 6 redpanda-4.testcluster.local 8 redpanda-6.testcluster.local 9 redpanda-5.testcluster.local The IDs are the broker IDs. The output shows that the IDs don’t match the StatefulSet ordinal, which appears in the hostname. In this example, the Pod with the highest ordinal is `redpanda-6` (ID 8). You cannot choose which broker is decommissioned. Redpanda is deployed as a StatefulSet in Kubernetes. The StatefulSet controls which Pods are destroyed and always starts with the Pod that has the highest ordinal. So the first broker to be destroyed when the controller decommissions the brokers in this example is `redpanda-6` (ID 8). When you reduce the number of replicas, the controller terminates the Pod with the highest ordinal, removes its PVC, and then attempts to set the reclaim policy of the PV to `Retain`. Finally, the controller waits for the cluster state to become healthy before committing to decommissioning the broker that was running in the terminated Pod. > 📝 **NOTE** > > Always decommission one broker at a time. 1. Enable the BrokerDecommissioner: #### Operator 1. Deploy the Redpanda Operator with the Decommission controller: ```bash helm repo add redpanda https://charts.redpanda.com helm repo update helm upgrade --install redpanda-controller redpanda/operator \ --namespace \ --set image.tag=v26.1.2 \ --create-namespace \ --set additionalCmdFlags={--additional-controllers="decommission"} \ --set rbac.createAdditionalControllerCRs=true ``` - `--additional-controllers="decommission"`: Enables the Decommission controller. - `rbac.createAdditionalControllerCRs=true`: Creates the required RBAC rules for the Redpanda Operator to monitor the StatefulSet and update PVCs and PVs. 2. Configure a Redpanda resource with seven Redpanda brokers: `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: statefulset: replicas: 7 ``` - `statefulset.replicas`: This example starts with a seven-broker Redpanda cluster. 3. Apply the Redpanda resource: ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `decommission-controller.yaml` ```yaml statefulset: replicas: 7 (1) sideCars: brokerDecommissioner: enabled: true (2) decommissionAfter: 60s (3) decommissionRequeueTimeout: 10s (4) rbac: enabled: true (5) ``` | 1 | statefulset.replicas: This example starts with a seven-broker Redpanda cluster. | | --- | --- | | 2 | statefulset.sideCars.brokerDecommissioner.enabled: Enables the sidecar. | | 3 | statefulset.sideCars.brokerDecommissioner.decommissionAfter: The sidecar will wait 60 seconds after detecting a failed broker before triggering decommissioning. | | 4 | statefulset.sideCars.brokerDecommissioner.decommissionRequeueTimeout: How often the sidecar rechecks the cluster for invalid brokers. | | 5 | rbac.enabled: Creates the required RBAC rules for the controller to monitor the StatefulSet and update PVCs and PVs. | ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda \ --namespace \ --create-namespace \ --set statefulset.replicas=7 \ (1) --set statefulset.sideCars.brokerDecommissioner.enabled=true \ (2) --set statefulset.sideCars.brokerDecommissioner.decommissionAfter=60s \ (3) --set statefulset.sideCars.brokerDecommissioner.decommissionRequeueTimeout=10s \ (4) --set rbac.enabled=true(5) ``` | 1 | statefulset.replicas: This example starts with a seven-broker Redpanda cluster. | | --- | --- | | 2 | statefulset.sideCars.brokerDecommissioner.enabled: Enables the sidecar. | | 3 | statefulset.sideCars.brokerDecommissioner.decommissionAfter: The sidecar will wait 60 seconds after detecting a failed broker before triggering decommissioning. | | 4 | statefulset.sideCars.brokerDecommissioner.decommissionRequeueTimeout: How often the sidecar rechecks the cluster for invalid brokers. | | 5 | rbac.enabled: Creates the required RBAC rules for the controller to monitor the StatefulSet and update PVCs and PVs. | 2. Verify that your cluster is in a healthy state: ```bash kubectl exec redpanda-0 --namespace -- rpk cluster health ``` 3. Decrease the number of replicas **by one**. > ⚠️ **CAUTION: Reduce replicas by one** > > When scaling in (removing brokers), remove only one broker at a time. If you reduce the StatefulSet replicas by more than one, Kubernetes can terminate multiple Pods simultaneously, causing quorum loss and cluster unavailability. #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: statefulset: replicas: 6 sideCars: brokerDecommissioner: enabled: true decommissionAfter: 60s decommissionRequeueTimeout: 10s rbac: enabled: true ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `replicas.yaml` ```yaml statefulset: replicas: 6 ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values replicas.yaml --reuse-values ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set statefulset.replicas=6 ``` The BrokerDecommissioner detects when the number of replicas decreases and decommissions the brokers, starting from the Pod with the highest ordinal. This process triggers a rolling restart of each Pod so that each broker has an up-to-date `seed_servers` configuration to reflect the new list of brokers. 4. Verify that your cluster is in a healthy state: ```bash kubectl exec redpanda-0 --namespace -- rpk cluster health ``` It may take some time for the BrokerDecommissioner to reconcile. You can check the progress by looking at the logs: ```bash kubectl logs --namespace -c sidecars ``` You can repeat this procedure to continue to scale down. ## [](#troubleshooting)Troubleshooting If the decommissioning process is not making progress, investigate the following potential issues: - **Absence of a controller leader or partition leader**: The controller leader serves as the orchestrator for decommissioning. Additionally, if one of the partitions undergoing reconfiguration does not have a leader, the reconfiguration process may stall. Make sure that an elected leader is present for all partitions. - **Bandwidth limitations for partition recovery**: Try increasing the value of [`raft_learner_recovery_rate`](../../../reference/properties/cluster-properties/#raft_learner_recovery_rate), and monitor the status using the [`redpanda_raft_recovery_partition_movement_available_bandwidth`](../../../reference/public-metrics-reference/#redpanda_raft_recovery_partition_movement_available_bandwidth) metric. If these steps do not allow the decommissioning process to complete, enable `TRACE` level logging in the Helm chart to investigate any other issues. For default values and documentation for configuration options, see the [`values.yaml`](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=logging) file. ## [](#next-steps)Next steps If you have rack awareness enabled, you may want to reassign the remaining brokers to appropriate racks after the decommission process is complete. See [Enable Rack Awareness in Kubernetes](../k-rack-awareness/). ## [](#suggested-reading)Suggested reading - [`rpk-redpanda-admin-brokers-decommission`](../../../reference/rpk/rpk-redpanda/rpk-redpanda-admin-brokers-decommission/) - [Engineering a more robust Raft group reconfiguration](https://redpanda.com/blog/raft-protocol-reconfiguration-solution) ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Owl Shop Example Application in Docker](/redpanda-labs/docker-compose/owl-shop/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) See more [Search all labs](/redpanda-labs) --- # Page 161: Create and Manage Kafka Connect Connectors in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/k-manage-connectors.md --- # Create and Manage Kafka Connect Connectors in Kubernetes --- title: Create and Manage Kafka Connect Connectors in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/k-manage-connectors page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/k-manage-connectors.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/k-manage-connectors.adoc description: Learn how to create and manage connectors using Redpanda Console or the Kafka Connect REST API. page-git-created-date: "2024-01-04" page-git-modified-date: "2025-08-15" support-status: supported --- When you have Kafka Connect deployed, you can create and manage connectors using Redpanda Console or the Kafka Connect REST API. > 📝 **NOTE: Community** > > **The Connectors Helm chart is a community-supported artifact**. Redpanda Data does not provide enterprise support for this chart. For support, reach out to the Redpanda team in [Redpanda Community Slack](https://redpanda.com/slack). ## [](#prerequisites)Prerequisites - [Deploy a Redpanda cluster with Redpanda Console](../../../deploy/redpanda/kubernetes/k-production-deployment/). - [Deploy Kafka Connect](../../../deploy/kafka-connect/k-deploy-kafka-connect/). - Ensure Redpanda Console is configured to connect to Kafka Connect (see the [Redpanda Console configuration](../../../deploy/kafka-connect/k-deploy-kafka-connect/#configure-redpanda-console-to-connect-to-kafka-connect) in the deployment guide). ## [](#verify-kafka-connect-is-accessible)Verify Kafka Connect is accessible Before managing connectors, verify that Kafka Connect is running and accessible: 1. Check the Pod status: ```bash kubectl get pod -l app.kubernetes.io/name=connectors --namespace ``` Expected output: ```bash NAME READY STATUS RESTARTS AGE redpanda-connectors-6d64b948f6-dk484 1/1 Running 0 5m ``` 2. Test the Kafka Connect REST API: ```bash POD_NAME=$(kubectl get pod -l app.kubernetes.io/name=connectors --namespace -o jsonpath='{.items[0].metadata.name}') kubectl exec $POD_NAME --namespace -- curl -s localhost:8083 | jq '.version' ``` This should return the Kafka Connect version. 3. Verify the available connector plugins: ```bash kubectl exec $POD_NAME --namespace -- curl -s localhost:8083/connector-plugins | jq '.[].class' ``` Expected output should include the MirrorMaker2 connectors: ```bash "org.apache.kafka.connect.mirror.MirrorCheckpointConnector" "org.apache.kafka.connect.mirror.MirrorHeartbeatConnector" "org.apache.kafka.connect.mirror.MirrorSourceConnector" ``` ## [](#manage-connectors-in-redpanda-console)Manage connectors in Redpanda Console Redpanda Console provides a web interface for managing Kafka Connect connectors. This is the recommended approach for most users as it provides a user-friendly interface and validation. ### [](#access-redpanda-console)Access Redpanda Console By default, Redpanda Console is deployed with a ClusterIP Service. To access Redpanda Console, you can use the `kubectl port-forward` command to forward one of your local ports to the Pod. > 📝 **NOTE** > > The `kubectl port-forward` command is a development tool. To expose services to external traffic in a more permanent and controlled manner, use Kubernetes Services such as LoadBalancer or NodePort. 1. Expose Redpanda Console to your localhost: ```bash kubectl --namespace port-forward svc/redpanda-console 8080:8080 ``` This command actively runs in the command-line window. To execute other commands while the command is running, open another command-line window. 2. Open Redpanda Console on [http://localhost:8080](http://localhost:8080). ### [](#using-the-connect-interface)Using the Connect interface When you have access to Redpanda Console: 1. Navigate to **Connect** in the left menu. 2. If Kafka Connect is properly configured, you should see: - The Kafka Connect cluster - A list of available connector types - Any existing tasks From here, you can: - View connector status and health - Pause/resume connectors - View connector configuration - Delete connectors - View connector logs and metrics ### [](#troubleshoot-redpanda-console-connectivity)Troubleshoot Redpanda Console connectivity If you see "Kafka Connect is not configured": 1. Verify the Redpanda Console configuration includes Kafka Connect settings (see [deployment guide troubleshooting](../../../deploy/kafka-connect/k-deploy-kafka-connect/#troubleshooting-console-connectivity)) 2. Check the Redpanda Console logs for connection errors: ```bash kubectl logs -n -l app.kubernetes.io/name=console --tail=20 ``` 3. Look for successful connection messages: "creating Kafka connect HTTP clients and testing connectivity to all clusters" "tested Kafka connect cluster connectivity","successful\_clusters":1,"failed\_clusters":0" ## [](#manage-connectors-with-the-rest-api)Manage connectors with the REST API This section provides examples of managing connectors using the Kafka Connect REST API with cURL. This approach is useful for automation, scripting, and CI/CD pipelines. All REST API commands should be executed from within the Kafka Connect Pod or through `kubectl exec`. For comprehensive REST API documentation, see the [Kafka Connect REST API reference](https://kafka.apache.org/documentation/#connect_rest). > 💡 **TIP** > > For complex connector configurations and production deployments, consider using the [Helm chart configuration options](../../../reference/k-connector-helm-spec/) to manage connector settings. ### [](#get-connector-pod-information)Get connector Pod information Get the Pod name and verify connectivity: ```bash # Get the connector Pod name POD_NAME=$(kubectl get pod -l app.kubernetes.io/name=connectors --namespace -o jsonpath='{.items[0].metadata.name}') echo "Using pod: $POD_NAME" # Test basic connectivity kubectl exec $POD_NAME --namespace -- curl -s localhost:8083 ``` ### [](#view-version-of-kafka-connect)View version of Kafka Connect ```bash kubectl exec $POD_NAME --namespace -- curl -s localhost:8083 | jq ``` Expected output: ```json { "version": "3.8.0", "commit": "771b9576b00ecf5b", "kafka_cluster_id": "redpanda.3e2649b0-f84c-4c03-b5e3-d6d1643f65b2" } ``` ### [](#view-available-connector-plugins)View available connector plugins ```bash kubectl exec $POD_NAME --namespace -- curl -s localhost:8083/connector-plugins | jq ``` ### [](#view-cluster-worker-information)View cluster worker information ```bash kubectl exec $POD_NAME --namespace -- curl -s localhost:8083 | jq ``` This returns basic cluster information including version and Kafka cluster ID. ### [](#view-all-connectors)View all connectors ```bash # List connector names only kubectl exec $POD_NAME --namespace -- curl -s localhost:8083/connectors | jq # View connectors with detailed status and configuration kubectl exec $POD_NAME --namespace -- curl -s 'localhost:8083/connectors?expand=status&expand=info' | jq ``` ### [](#create-a-connector)Create a connector To create a connector, use a POST request with JSON configuration: ```bash kubectl exec $POD_NAME --namespace -- curl -s "localhost:8083/connectors" \ -H 'Content-Type: application/json' \ --data-raw '{ "name": "heartbeat-connector", "config": { "connector.class": "org.apache.kafka.connect.mirror.MirrorHeartbeatConnector", "heartbeats.topic.replication.factor": "1", "replication.factor": "1", "source.cluster.alias": "source", "target.cluster.alias": "target", "source.cluster.bootstrap.servers": "redpanda.redpanda.svc.cluster.local:9093", "target.cluster.bootstrap.servers": "redpanda.redpanda.svc.cluster.local:9093", "emit.heartbeats.interval.seconds": "30" } }' | jq ``` Example for MirrorSourceConnector: ```bash kubectl exec $POD_NAME --namespace -- curl -s "localhost:8083/connectors" \ -H 'Content-Type: application/json' \ --data-raw '{ "name": "mirror-source-connector", "config": { "connector.class": "org.apache.kafka.connect.mirror.MirrorSourceConnector", "source.cluster.alias": "source", "target.cluster.alias": "target", "source.cluster.bootstrap.servers": "source-cluster:9092", "target.cluster.bootstrap.servers": "redpanda.redpanda.svc.cluster.local:9093", "topics": "my-topic", "replication.factor": "1" } }' | jq ``` ### [](#view-connector-details)View connector details ```bash # View connector configuration kubectl exec $POD_NAME --namespace -- curl -s localhost:8083/connectors//config | jq # View connector status kubectl exec $POD_NAME --namespace -- curl -s localhost:8083/connectors//status | jq # View connector tasks kubectl exec $POD_NAME --namespace -- curl -s localhost:8083/connectors//tasks | jq ``` Example: ```bash kubectl exec $POD_NAME --namespace -- curl -s localhost:8083/connectors/heartbeat-connector/status | jq ``` ### [](#update-connector-configuration)Update connector configuration ```bash kubectl exec $POD_NAME --namespace -- curl -s "localhost:8083/connectors//config" \ -H 'Content-Type: application/json' \ -X PUT \ --data-raw '{ "connector.class": "org.apache.kafka.connect.mirror.MirrorHeartbeatConnector", "heartbeats.topic.replication.factor": "1", "replication.factor": "1", "source.cluster.alias": "source", "target.cluster.alias": "target", "source.cluster.bootstrap.servers": "redpanda.redpanda.svc.cluster.local:9093", "target.cluster.bootstrap.servers": "redpanda.redpanda.svc.cluster.local:9093", "emit.heartbeats.interval.seconds": "60" }' | jq ``` ### [](#pause-and-resume-connectors)Pause and resume connectors ```bash # Pause a connector kubectl exec $POD_NAME --namespace -- curl -s "localhost:8083/connectors//pause" -X PUT # Resume a connector kubectl exec $POD_NAME --namespace -- curl -s "localhost:8083/connectors//resume" -X PUT # Restart a connector kubectl exec $POD_NAME --namespace -- curl -s "localhost:8083/connectors//restart" -X POST ``` ### [](#delete-a-connector)Delete a connector ```bash kubectl exec $POD_NAME --namespace -- curl -s "localhost:8083/connectors/" -X DELETE ``` Example: ```bash kubectl exec $POD_NAME --namespace -- curl -s "localhost:8083/connectors/heartbeat-connector" -X DELETE ``` ### [](#troubleshoot-rest-api-issues)Troubleshoot REST API issues #### [](#common-error-responses)Common error responses - **404 Not Found**: Connector doesn’t exist - **409 Conflict**: Connector with the same name already exists - **400 Bad Request**: Invalid configuration #### [](#debugging-connector-failures)Debugging connector failures 1. Check connector status for error details: ```bash kubectl exec $POD_NAME --namespace -- curl -s localhost:8083/connectors//status | jq '.connector.trace' ``` 2. View task-level errors: ```bash kubectl exec $POD_NAME --namespace -- curl -s localhost:8083/connectors//status | jq '.tasks[].trace' ``` 3. Check Kafka Connect logs: ```bash kubectl logs -n -l app.kubernetes.io/name=connectors --tail=50 ``` For more detailed logging configuration, see [logging configuration](../../../deploy/kafka-connect/k-deploy-kafka-connect/#logging) in the deployment guide. ### [](#connector-management-best-practices)Connector management best practices #### [](#configuration-validation)Configuration validation Before creating a connector, validate the configuration: ```bash kubectl exec $POD_NAME --namespace -- curl -s "localhost:8083/connector-plugins//config/validate" \ -H 'Content-Type: application/json' \ -X PUT \ --data-raw '{"connector.class": "", ...}' | jq ``` #### [](#monitoring-connector-health)Monitoring connector health Regularly check connector status: ```bash # Check all connectors at once kubectl exec $POD_NAME --namespace -- curl -s 'localhost:8083/connectors?expand=status' | \ jq '.[] | {name: .status.name, state: .status.connector.state, tasks: [.status.tasks[].state]}' ``` For comprehensive monitoring and alerting, see [Kafka Connect monitoring guide](../monitoring/k-monitor-connectors/). #### [](#backup-connector-configurations)Backup connector configurations Save connector configurations for disaster recovery: ```bash # Export all connector configs kubectl exec $POD_NAME --namespace -- curl -s 'localhost:8083/connectors?expand=info' | \ jq '.[] | {name: .info.name, config: .info.config}' > connectors-backup.json ``` ## [](#next-steps)Next steps - [Monitor Kafka Connect performance and health](../monitoring/k-monitor-connectors/) - [Install additional connector plugins](../../../deploy/kafka-connect/k-deploy-kafka-connect/#install-a-new-connector) - [Configure advanced Kafka Connect settings](../../../reference/k-connector-helm-spec/) - Explore [Redpanda Connect](../../../../redpanda-connect/home/) for simpler data pipeline creation ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) [Search all labs](/redpanda-labs) --- # Page 162: Manage Pod Resources in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/k-manage-resources.md --- # Manage Pod Resources in Kubernetes --- title: Manage Pod Resources in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/k-manage-resources page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/k-manage-resources.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/k-manage-resources.adoc description: Configure your Pod resources such as memory, CPU, and storage. page-git-created-date: "2024-01-04" page-git-modified-date: "2026-03-24" support-status: supported --- Managing Pod resources, such as CPU, memory, and storage, is critical for ensuring that your Redpanda cluster runs well in Kubernetes. In this guide, you’ll learn how to define and configure resource requests and limits using the Redpanda Helm chart and Redpanda CRD. Setting these values before deployment helps guarantee predictable scheduling, enforces the Guaranteed QoS classification, and minimizes the risk of performance issues such as resource contention or unexpected evictions. ## [](#prerequisites)Prerequisites - See [Kubernetes Cluster Requirements and Recommendations](../../../deploy/redpanda/kubernetes/k-requirements/) for the minimum worker node, memory, CPU, and storage requirements. - Make sure that your physical or virtual machines have enough resources to give to Redpanda. To see the available resources on the worker nodes that you have provisioned: ```bash kubectl describe nodes ``` ## [](#production-considerations)Production considerations - [Enable the `Guaranteed` quality of service class for Pods that run Redpanda](#qos). This setup ensures that the CPU and memory allocated to Redpanda are not subject to throttling or other contention issues, providing a stable and predictable performance environment. - [Enable memory locking](#memory). This configuration prevents the operating system from paging out Redpanda’s memory to disk, which can significantly impact performance. - Ensure you [give each Redpanda broker at least 4 CPU cores](#cpu). This configuration ensures that Redpanda has enough CPU resources to run efficiently. - Ensure you [give Redpanda at least 2 Gi of memory](#memory) per core. This configuration ensures that Redpanda has enough memory to run efficiently. - Ensure that the number of CPU cores you allocate to Redpanda is an even integer. This configuration allows Redpanda to leverage the [static CPU manager policy](https://kubernetes.io/docs/tasks/administer-cluster/cpu-management-policies/#static-policy-configuration), granting the Pod exclusive access to the requested cores for optimal performance. ## [](#memory)Configure memory resources When deploying Redpanda, you must reserve sufficient memory for both Redpanda and other system processes. Redpanda uses the Seastar framework to manage memory through two important flags. In Kubernetes, the values of these flags are usually set for you, depending on how you configure the Redpanda CRD or the Helm chart. - **`--memory`**: When set, explicitly defines the Redpanda heap size. - **`--reserve-memory`**: When set, reserves a specific amount of memory for system overhead. If not set, a reserve is automatically calculated. Learn more about these Seastar flags | | --memory Not set | --memory Set (M) | | --- | --- | --- | | --reserve-memory Not set | Heap size = available memory - calculated reserve | Heap size = exactly M (if M plus calculated reserve ≤ available memory). Otherwise, startup fails | | --reserve-memory set (R) | Heap size = available memory - R | Heap size = exactly M (if M + R ≤ available memory). Otherwise, startup fails | Definitions and behavior: - **Available memory**: The memory remaining after subtracting system requirements, such as `/proc/sys/vm/min_free_kbytes`, from the total or cgroup-limited memory. - **Calculated reserve**: The greater of 1.5 GiB or 7% of _available memory_ used when `--reserve-memory` is not explicitly set. These flags are set for you by default when using the Redpanda Helm chart or Operator. However, you can manually set these flags using the `statefulset.additionalRedpandaCmdFlags` configuration if needed. > ⚠️ **CAUTION** > > Avoid manually setting the `--memory` and `--reserve-memory` flags unless absolutely necessary. Incorrect settings can lead to performance issues, instability, or data loss. > 📝 **NOTE** > > This option is deprecated and maintained only for backward compatibility. ### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: statefulset: additionalRedpandaCmdFlags: - '--lock-memory' (1) resources: requests: memory: (2) limits: memory: (3) ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ### Helm #### --values `memory.yaml` ```yaml statefulset: additionalRedpandaCmdFlags: - '--lock-memory' (1) resources: requests: memory: (2) limits: memory: (3) ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values memory.yaml --reuse-values ``` #### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set statefulset.additionalRedpandaCmdFlags=="{--lock-memory}" \ (1) --set resources.requests.memory= \ (2) --set resources.limits.memory= (3) ``` | 1 | Enable memory locking to prevent the operating system from paging out Redpanda’s memory to disk. This can significantly improve performance by ensuring Redpanda has uninterrupted access to its allocated memory. | | --- | --- | | 2 | Request at least 2.22 Gi of memory per core to ensure Redpanda has the 2 Gi per core it requires after accounting for the 90% allocation to the --memory flag.Redpanda supports the following memory resource units: B, K, M, G, Ki, Mi, and Gi.Memory units are truncated to the nearest whole MiB. For example, a memory request of 1024 KiB will result in 1 MiB being allocated. For a description of memory resource units, see the Kubernetes documentation. | | 3 | Set the memory limit to match the memory request. This ensures Kubernetes enforces a strict upper bound on memory usage and helps maintain the Guaranteed QoS classification. | When the StatefulSet is deployed, make sure that the memory request and limit are set: ```bash kubectl --namespace= get pod -o jsonpath='{.spec.containers[?(@.name=="redpanda")].resources}{"\n"}' ``` ## [](#cpu)Configure CPU resources Redpanda uses the Seastar framework to manage CPU usage through the `--smp` flag, which sets the number of CPU cores available to Redpanda. This is configured using `resources.cpu.cores`, which automatically applies the same value to both `resources.requests.cpu` and `resources.limits.cpu`. | Default Configuration | Production Recommendation | | --- | --- | | resources.cpu.cores: 1 Equivalent to setting resources.requests.cpu and resources.limits.cpu to 1. | Set resources.cpu.cores to 4 or greater.Set CPU cores to an even integer to leverage the static CPU manager policy, granting the Pod exclusive access to the requested cores for optimal performance. | ### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: resources: cpu: cores: (1) ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ### Helm #### --values `cpu-cores.yaml` ```yaml resources: cpu: cores: (1) ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values cpu-cores.yaml --reuse-values ``` #### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set resources.cpu.cores= \ (1) ``` | 1 | Set resources.cpu.cores to the desired number of CPU cores for Redpanda. This value is applied as both the CPU request and limit, ensuring that the Pod maintains the Guaranteed QoS classification by enforcing a strict upper bound on CPU usage. | | --- | --- | When the StatefulSet is deployed, make sure that the CPU request and limit are set: ```bash kubectl --namespace get pod -o jsonpath='{.spec.containers[?(@.name=="redpanda")].resources}{"\n"}' ``` ## [](#qos)Quality of service and resource guarantees To ensure that Redpanda receives stable and consistent resources, set the [quality of service (QoS) class](https://kubernetes.io/docs/tasks/configure-pod-container/quality-service-pod/#create-a-pod-that-gets-assigned-a-qos-class-of-guaranteed) to `Guaranteed` by matching resource requests and limits on all containers in the Pods that run Redpanda. Kubernetes uses QoS to decide which Pods to evict from a worker node that runs out of resources. When a worker node runs out of resources, Kubernetes evicts Pods with a `Guaranteed` QoS last. This stability is crucial for Redpanda because it requires consistent computational and memory resources to maintain high performance. Kubernetes gives a Pod a `Guaranteed` QoS class when every container inside it has identical resource requests and limits set for both CPU and memory. This strict configuration signals to Kubernetes that these resources are critical and should not be throttled or reclaimed under normal operating conditions. To configure the Pods that run Redpanda with `Guaranteed` QoS, specify both resource requests and limits for all _enabled_ containers in the Pods. For example: ### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: resources: cpu: cores: requests: memory: limits: memory: # Matches the request statefulset: sideCars: configWatcher: resources: requests: cpu: memory: limits: cpu: # Matches the request memory: # Matches the request initContainers: tuning: resources: requests: cpu: memory: limits: cpu: # Matches the request memory: # Matches the request setTieredStorageCacheDirOwnership: resources: requests: cpu: memory: limits: cpu: # Matches the request memory: # Matches the request configurator: resources: requests: cpu: memory: limits: cpu: # Matches the request memory: # Matches the request ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ### Helm #### --values `memory.yaml` ```yaml resources: cpu: cores: requests: memory: limits: memory: # Matches the request statefulset: sideCars: configWatcher: resources: requests: cpu: memory: limits: cpu: # Matches the request memory: # Matches the request podTemplate: spec: initContainers: - name: tuning resources: requests: cpu: memory: limits: cpu: # Matches the request memory: # Matches the request - name: set-tiered-storage-cache-dir-ownership resources: requests: cpu: memory: limits: cpu: # Matches the request memory: # Matches the request - name: configurator resources: requests: cpu: memory: limits: cpu: # Matches the request memory: # Matches the request ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values memory.yaml --reuse-values ``` #### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set resources.cpu.cores= \ --set resources.requests.memory= \ --set resources.limits.memory= \ --set statefulset.sideCars.configWatcher.resources.requests.cpu= \ --set statefulset.sideCars.configWatcher.resources.requests.memory= \ --set statefulset.sideCars.configWatcher.resources.limits.cpu= \ --set statefulset.sideCars.configWatcher.resources.limits.memory= ``` > 📝 **NOTE** > > Init container resources must be configured using a values file with the `statefulset.podTemplate.spec.initContainers` structure. See the `--values` example above. When the StatefulSet is deployed, make sure that the QoS for the Pods is set to `Guaranteed`: ```bash kubectl --namespace= get pod -o jsonpath='{ .status.qosClass}{"\n"}' ``` ## [](#configure-storage-capacity)Configure storage capacity Make sure to provision enough disk storage for your streaming workloads. If you use PersistentVolumes, you can set the storage capacity for each volume. For instructions, see [Configure Storage for the Redpanda data directory in Kubernetes](../storage/k-configure-storage/). ## [](#pinning)Run Redpanda in shared environments If Redpanda runs in a shared environment, where multiple applications run on the same worker node, you can make Redpanda less aggressive in CPU usage by enabling overprovisioning. This adjustment ensures a fairer distribution of CPU time among all processes, improving overall system efficiency at the cost of Redpanda’s performance. You can enable overprovisioning by either setting the CPU request to a fractional value less than 1 or enabling the `--overprovisioned` flag. > 📝 **NOTE** > > You cannot enable overprovisioning using `resources.cpu.overprovisioned` when both `resources.requests` and `resources.limits` are set. When both of these configurations are set, the `resources.cpu` parameter (including cores) is ignored. Instead, use the `statefulset.additionalRedpandaCmdFlags` configuration to enable overprovisioning. ### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: statefulset: additionalRedpandaCmdFlags: - '--overprovisioned' resources: cpu: cores: ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ### Helm #### --values `cpu-cores-overprovisioned.yaml` ```yaml statefulset: additionalRedpandaCmdFlags: - '--overprovisioned' resources: cpu: cores: ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values cpu-cores-overprovisioned.yaml --reuse-values ``` #### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set resources.cpu.cores= \ --set statefulset.additionalRedpandaCmdFlags=="{--overprovisioned}" ``` If you’re experimenting with Redpanda in Kubernetes, you can also set the number of CPU cores to millicores to automatically enable overprovisioning. `cpu-cores.yaml` ```yaml resources: cpu: cores: 200m ``` ## [](#config-watcher)Configure config-watcher sidecar resources Each Redpanda Pod includes a config-watcher sidecar container that monitors for SASL user changes and configuration updates. The sidecar polls a Secret for user credential changes and synchronizes them with the running brokers. The config-watcher sidecar does not set any CPU or memory resource requests or limits by default. For most clusters, this is acceptable because the sidecar is lightweight. In practice, the sidecar typically consumes single-digit millicores of CPU and approximately 20-40 MiB of memory. Configure explicit resource requests and limits for the config-watcher sidecar in the following cases: - Your namespace enforces a [LimitRange](https://kubernetes.io/docs/concepts/policy/limit-range/) policy that requires all containers to specify resource requests or limits. - Your namespace enforces a [ResourceQuota](https://kubernetes.io/docs/concepts/policy/resource-quotas/) that accounts for resource requests across all containers. - You want to ensure the [Guaranteed QoS class](#qos) for your Redpanda Pods. Kubernetes requires every container in a Pod to have matching requests and limits to qualify. ### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: statefulset: sideCars: configWatcher: resources: requests: cpu: 10m (1) memory: 64Mi (2) limits: cpu: 100m memory: 128Mi ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ### Helm #### --values `config-watcher-resources.yaml` ```yaml statefulset: sideCars: configWatcher: resources: requests: cpu: 10m (1) memory: 64Mi (2) limits: cpu: 100m memory: 128Mi ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values config-watcher-resources.yaml --reuse-values ``` #### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set statefulset.sideCars.configWatcher.resources.requests.cpu=10m \ --set statefulset.sideCars.configWatcher.resources.requests.memory=64Mi \ --set statefulset.sideCars.configWatcher.resources.limits.cpu=100m \ --set statefulset.sideCars.configWatcher.resources.limits.memory=128Mi ``` | 1 | A CPU request of 10m (10 millicores) is sufficient for typical config-watcher workloads. The sidecar spends most of its time idle between polling intervals. | | --- | --- | | 2 | A memory request of 64Mi provides headroom for the sidecar process. Actual usage is typically 20-40 Mi. | When the StatefulSet is deployed, verify that the sidecar container has the expected resource configuration: ```bash kubectl --namespace get pod -o jsonpath='{.spec.containers[?(@.name=="config-watcher")].resources}{"\n"}' ``` ## [](#suggested-reading)Suggested reading - [Redpanda Helm Specification](../../../reference/k-redpanda-helm-spec/#resources) - [Redpanda CRD Reference](../../../reference/k-crd/) ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Owl Shop Example Application in Docker](/redpanda-labs/docker-compose/owl-shop/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) See more [Search all labs](/redpanda-labs) --- # Page 163: Manage Topics with the Redpanda Operator **URL**: https://docs.redpanda.com/current/manage/kubernetes/k-manage-topics.md --- # Manage Topics with the Redpanda Operator --- title: Manage Topics with the Redpanda Operator latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/k-manage-topics page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/k-manage-topics.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/k-manage-topics.adoc description: Use the Topic resource to declaratively create Kafka topics as part of a Redpanda deployment. Each Topic resource is mapped to a topic in your Redpanda cluster. The topic controller keeps the corresponding Kafka topic in sync with the Topic resource. page-git-created-date: "2024-01-04" page-git-modified-date: "2025-12-04" support-status: supported --- The Redpanda Operator allows you to declaratively create and manage Kafka topics using [Topic custom resources](../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-topic) (resources) in Kubernetes. Each Topic resource is mapped to a topic in your Redpanda cluster. The topic controller, a component of the Redpanda Operator, keeps the corresponding Kafka topic in sync with the Topic resource. This resource allows you to create topics as part of a Redpanda deployment. ## [](#prerequisites)Prerequisites You must have the following: - **Kubectl**: Ensure you have the [`kubectl`](https://kubernetes.io/docs/tasks/tools/#kubectl) command-line tool installed and configured to communicate with your cluster. - **Redpanda**: Ensure you have the [Redpanda Operator and a Redpanda resource deployed](../../../deploy/redpanda/kubernetes/k-production-deployment/) in your Kubernetes cluster. ## [](#limitations)Limitations You cannot create access control lists (ACLs) directly in the Topic resource. To create ACLs for your topics, you can use: - [The User resource](../security/authentication/k-user-controller/) - [`rpk`](../../../get-started/rpk-install/) or another Kafka client For details about ACLs, see [Configure Authorization](../../security/authorization/). ## [](#create-a-topic)Create a topic 1. Define a topic using the Topic resource. Here’s a basic example configuration: `topic.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Topic metadata: name: namespace: spec: cluster: clusterRef: name: partitions: replicationFactor: additionalConfig: {} ``` Replace the following placeholders: - ``: The name of the Topic resource. If the [`overwriteTopicName`](#overwrite) property is not set, the name of the Topic resource is also given to the topic in Redpanda. Valid names must consist of lowercase alphanumeric characters, hyphens (-), or periods (.). Names cannot start or end with a non-alphanumeric character. Underscores (\_) are not allowed. For example, `chat-room` is a valid name, whereas `chat_room` is not. To use other characters such as underscores in your topic names, use the [`overwriteTopicName`](#overwrite) property. - ``: The namespace in which to deploy the Topic resource. The Topic resource must be deployed in the same namespace as the Redpanda resource defined in `clusterRef.name`. - ``: The name of the Redpanda resource that defines the Redpanda cluster in which you want to create the topic. - ``: The number of topic shards distributed across the brokers in a Redpanda cluster. This value cannot be decreased post-creation. Overrides the default cluster property [`default_topic_partitions`](../../../reference/properties/cluster-properties/#default_topic_partitions). - ``: Specifies the number of topic replicas. The value must be an odd number. Overrides the default cluster property [`default_topic_replications`](../../../reference/properties/cluster-properties/#default_topic_replications). 2. Apply the manifest: ```bash kubectl apply -f topic.yaml --namespace ``` When the manifest is applied, the topic will be created in your Redpanda cluster. 3. Check the status of the Topic resource using the following command: ```bash kubectl get topic --namespace ``` Additional configuration options: - [`spec.additionalConfig`](../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-topicspec): A map of any topic-specific configuration options. See [Topic Configuration Properties](../../../reference/properties/topic-properties/). - [`spec.metricsNamespace`](../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-topicspec): The fully-qualified name of the topic metrics for use in multi-operator environments. Defaults to `redpanda-operator`. - [`spec.overwriteTopicName`](../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-topicspec): Overwrites the topic name in `metadata.name`. - [`spec.interval`](../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-topicspec): Sets the reconciliation interval for the topic controller. Default is 3 seconds (`3s`). You can find all configuration options for the Topic resource in the [CRD reference](../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-topic). ## [](#topic-examples)Topic examples This example demonstrates how to create a basic topic in your Redpanda cluster. `topic.yaml` ```yaml # In this example manifest, a topic called "topic1" is created in a cluster called "basic". It has a replication factor of 1 and is distributed across a single partition. --- apiVersion: cluster.redpanda.com/v1alpha2 kind: Topic metadata: name: topic1 spec: cluster: clusterRef: name: basic partitions: 1 replicationFactor: 1 ``` Apply the manifest: ```bash kubectl apply -f topic.yaml --namespace ``` Replace `` with the namespace in which you deployed the Redpanda cluster. ## [](#choose-a-cluster-connection-method)Choose a cluster connection method When creating a Topic resource, you can connect to your Redpanda cluster in two ways: - **clusterRef**: Reference the Redpanda cluster by name for automatic connection. This is the recommended approach for most users. - **staticConfiguration**: Manually specify connection details for Kafka and Admin API if you need custom settings. The Redpanda Operator automatically configures the Topic controller to connect to the referenced cluster when using `clusterRef`. Use `staticConfiguration` only if you need to: - Override the default connection settings - Connect to a Redpanda cluster not managed by the Redpanda Operator - Use custom TLS or SASL authentication settings ### [](#use-clusterref-recommended)Use clusterRef (recommended) The `clusterRef` method automatically discovers connection details from the referenced Redpanda resource: ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Topic metadata: name: example-topic namespace: spec: cluster: clusterRef: name: partitions: 3 replicationFactor: 3 ``` ### [](#use-staticconfiguration)Use staticConfiguration The `staticConfiguration` method requires manually specifying all connection details: ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Topic metadata: name: example-topic namespace: spec: cluster: staticConfiguration: kafka: brokers: - "redpanda-0.redpanda..svc.cluster.local:9093" - "redpanda-1.redpanda..svc.cluster.local:9093" - "redpanda-2.redpanda..svc.cluster.local:9093" tls: caCertSecretRef: name: "redpanda-default-cert" key: "ca.crt" sasl: username: "admin" passwordSecretRef: name: "redpanda-admin-password" key: "password" mechanism: "SCRAM-SHA-256" admin: urls: - "http://redpanda-0.redpanda..svc.cluster.local:9644" - "http://redpanda-1.redpanda..svc.cluster.local:9644" - "http://redpanda-2.redpanda..svc.cluster.local:9644" tls: caCertSecretRef: name: "redpanda-default-cert" key: "ca.crt" partitions: 3 replicationFactor: 3 ``` For all available configuration options, see the [ClusterSource reference](../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-clustersource). ## [](#choose-the-number-of-partitions)Choose the number of partitions A partition acts as a log file where topic data is written. Dividing topics into partitions allows producers to write messages in parallel and consumers to read messages in parallel. The higher the number of partitions, the greater the throughput. > 💡 **TIP** > > As a general rule, select a number of partitions that corresponds to the maximum number of consumers in any consumer group that will consume the data. ## [](#choose-the-replication-factor)Choose the replication factor Replicas are copies of partitions that are distributed across different brokers, so if one broker goes down, other brokers still have a copy of the data. The default replication factor in the cluster configuration is set to 1. By choosing a replication factor greater than 1, you ensure that each partition has a copy of its data on at least one other broker. One replica acts as the leader, and the other replicas are followers. > 📝 **NOTE** > > The replication factor must be an odd number. Redpanda Data recommends a replication factor of 3 for most use cases. ## [](#choose-the-cleanup-policy)Choose the cleanup policy The cleanup policy determines how to manage the partition log files when they reach a certain size: - `delete` deletes data based on age or log size. - `compact` compacts the data by only keeping the latest values for each KEY. - `compact,delete` combines both methods. If the cleanup policy is `delete` or `compact,delete` you can [Delete records from a topic](#delete-records-from-a-topic). > ⚠️ **WARNING** > > All topic properties take effect immediately after being set. Do not modify properties on internal Redpanda topics (such as `__consumer_offsets`, `_schemas`, or other system topics) as this can cause cluster instability. ## [](#configure-iceberg-topics)Configure Iceberg topics Iceberg topics allow you to create a seamless integration with Apache Iceberg by writing records in Redpanda topics to object storage in Iceberg format. > 📝 **NOTE** > > This feature requires an [enterprise license](../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../get-started/licensing/#self-managed) apply. In addition to the general prerequisites for managing topics, you must have the following: - [Iceberg support](../../iceberg/about-iceberg-topics/) must be enabled on your Redpanda cluster. - [Tiered Storage](../tiered-storage/k-tiered-storage/) must be enabled on your Redpanda cluster. To create an Iceberg topic, set the `redpanda.iceberg.mode` configuration in the `additionalConfig` property of the `Topic` resource. ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Topic metadata: name: iceberg-key-value namespace: spec: cluster: clusterRef: name: additionalConfig: redpanda.iceberg.mode: "" (1) ``` | 1 | Supported modes:key_value: Data is written with explicit keys and values.value_schema_id_prefix: Data is serialized using schemas managed by the Schema Registry, ensuring compatibility with schema-based systems.disabled (default) | | --- | --- | Apply the resource to your Kubernetes cluster: ```bash kubectl apply -f iceberg-topic.yaml --namespace ``` ## [](#configure-write-caching)Configure write caching Write caching is a relaxed mode of [`acks=all`](../../../develop/produce-data/configure-producers/#acksall) that provides better performance at the expense of durability. It acknowledges a message as soon as it is received and acknowledged on a majority of brokers, without waiting for it to be written to disk. This provides lower latency while still ensuring that a majority of brokers acknowledge the write. Write caching applies to user topics. It does not apply to transactions or consumer offsets. Transactions and offset commits are always fsynced. > 📝 **NOTE** > > For clusters in [development mode](../../../reference/rpk/rpk-redpanda/rpk-redpanda-mode/#development-mode), write caching is enabled by default. For clusters in production mode, it is disabled by default. Only enable write caching on workloads that can tolerate some data loss in the case of multiple, simultaneous broker failures. Leaving write caching disabled safeguards your data against complete data center or availability zone failures. ### [](#configure-at-cluster-level)Configure at cluster level To enable write caching by default in all user topics, set the cluster-level property [`write_caching_default`](../../../reference/properties/cluster-properties/#write_caching_default): #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: config: cluster: write_caching_default: true ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `write-caching.yaml` ```yaml config: cluster: write_caching_default: true ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values write-caching.yaml --reuse-values ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set config.cluster.write_caching_default=true ``` With `write_caching` enabled at the cluster level, Redpanda fsyncs to disk according to [`raft_replica_max_pending_flush_bytes`](../../../reference/properties/cluster-properties/#raft_replica_max_pending_flush_bytes) and [`raft_replica_max_flush_delay_ms`](../../../reference/properties/cluster-properties/#raft_replica_max_flush_delay_ms), whichever is reached first. ### [](#configure-at-topic-level)Configure at topic level To override the cluster-level setting at the topic level, set the topic-level property [`write.caching`](../../../reference/properties/topic-properties/#writecaching): `example-topic.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Topic metadata: name: chat-room namespace: spec: cluster: clusterRef: name: partitions: 3 replicationFactor: 3 additionalConfig: write.caching: true ``` With `write.caching` enabled at the topic level, Redpanda fsyncs to disk according to [`flush.ms`](../../../reference/properties/topic-properties/#flushms) and [`flush.bytes`](../../../reference/properties/topic-properties/#flushbytes), whichever is reached first. ## [](#verify-a-topic)Verify a topic After deploying a Topic resource, verify that the Redpanda Operator reconciled it. ```bash kubectl logs -l app.kubernetes.io/name=operator -c manager --namespace ``` Example output ```json { "level":"info", "ts":"2023-09-25T16:20:09.538Z", "logger":"TopicReconciler.Reconcile", "msg":"Starting reconcile loop", "controller":"topic", "controllerGroup":"cluster.redpanda.com", "controllerKind":"Topic", "Topic": { "name":"chat-room", "namespace":"" }, "namespace":"", "name":"chat-room", "reconcileID":"c0cf9abc-a553-48b7-9b6e-2de3cdfb4432" } { "level":"info", "ts":"2023-09-25T16:20:09.581Z", "logger":"TopicReconciler.Reconcile", "msg":"reconciliation finished in 43.436125ms, next run in 3s", "controller":"topic", "controllerGroup":"cluster.redpanda.com", "controllerKind":"Topic", "Topic": { "name":"chat-room", "namespace":"" }, "namespace":"", "name":"chat-room", "reconcileID":"c0cf9abc-a553-48b7-9b6e-2de3cdfb4432", "result": { "Requeue":false, "RequeueAfter":3000000000 } } ``` Then, verify that the topic now exists in your Redpanda cluster: ```bash kubectl --namespace exec -ti -c -- \ rpk topic list ``` Example output: NAME PARTITIONS REPLICAS chat-room 3 3 ## [](#view-topic-configuration)View topic configuration To view the configuration for all Topic resources: ```bash kubectl get topic -o yaml --namespace ``` You should see a list of all Topic resources and their configurations. Example output ```yaml apiVersion: v1 items: - apiVersion: cluster.redpanda.com/v1alpha2 kind: Topic metadata: annotations: kubectl.kubernetes.io/last-applied-configuration: | {"apiVersion":"cluster.redpanda.com/v1alpha2","kind":"Topic","metadata":{"annotations":{},"name":"chat-room","namespace":"redpanda"},"spec":{"additionalConfig":{"cleanup.policy":"compact"},"cluster":{"clusterRef":{"name":"redpanda"}},"partitions":3,"replicationFactor":3}} creationTimestamp: "2023-10-04T10:51:20Z" finalizers: - operator.redpanda.com/finalizer generation: 2 name: chat-room namespace: redpanda resourceVersion: "5262" uid: a26e5a79-cb04-48cb-a2d1-4be9f7f3168f spec: additionalConfig: cleanup.policy: compact interval: 3s cluster: clusterRef: name: redpanda partitions: 3 replicationFactor: 3 status: conditions: - lastTransitionTime: "2023-10-04T10:54:05Z" message: Topic reconciliation succeeded observedGeneration: 2 reason: Succeeded status: "True" type: Ready observedGeneration: 2 topicConfiguration: - configType: STRING isDefault: false isSensitive: false name: compression.type readOnly: false source: DEFAULT_CONFIG unknownTags: {} value: producer - configType: STRING isDefault: false isSensitive: false name: cleanup.policy readOnly: false source: DYNAMIC_TOPIC_CONFIG unknownTags: {} value: compact - configType: LONG isDefault: false isSensitive: false name: segment.bytes readOnly: false source: DEFAULT_CONFIG unknownTags: {} value: "67108864" - configType: LONG isDefault: false isSensitive: false name: retention.ms readOnly: false source: DEFAULT_CONFIG unknownTags: {} value: "604800000" - configType: LONG isDefault: false isSensitive: false name: retention.bytes readOnly: false source: DEFAULT_CONFIG unknownTags: {} value: "-1" - configType: STRING isDefault: false isSensitive: false name: message.timestamp.type readOnly: false source: DEFAULT_CONFIG unknownTags: {} value: CreateTime - configType: INT isDefault: false isSensitive: false name: max.message.bytes readOnly: false source: DEFAULT_CONFIG unknownTags: {} value: "1048576" - configType: BOOLEAN isDefault: false isSensitive: false name: redpanda.remote.read readOnly: false source: DEFAULT_CONFIG unknownTags: {} value: "false" - configType: BOOLEAN isDefault: false isSensitive: false name: redpanda.remote.write readOnly: false source: DEFAULT_CONFIG unknownTags: {} value: "false" - configType: LONG isDefault: false isSensitive: false name: retention.local.target.bytes readOnly: false source: DEFAULT_CONFIG unknownTags: {} value: "-1" - configType: LONG isDefault: false isSensitive: false name: retention.local.target.ms readOnly: false source: DEFAULT_CONFIG unknownTags: {} value: "86400000" - configSynonyms: - name: redpanda.remote.delete source: DEFAULT_CONFIG value: "true" configType: BOOLEAN isDefault: false isSensitive: false name: redpanda.remote.delete readOnly: false source: DEFAULT_CONFIG unknownTags: {} value: "true" - configType: LONG isDefault: false isSensitive: false name: segment.ms readOnly: false source: DEFAULT_CONFIG unknownTags: {} value: "1209600000" kind: List metadata: resourceVersion: "" ``` To see only the topic configuration as reported by Redpanda: ```bash kubectl get topic --namespace -o go-template=' {{- printf "%-30s %-30s %-30s\n" "KEY" "VALUE" "SOURCE" -}} {{- range .items -}} {{- range .status.topicConfiguration -}} {{- printf "%-30s %-30s %-30s\n" .name .value .source -}} {{- end -}} {{- end -}} ' ``` Example output KEY VALUE SOURCE compression.type producer DEFAULT\_CONFIG cleanup.policy compact DYNAMIC\_TOPIC\_CONFIG segment.bytes 67108864 DEFAULT\_CONFIG retention.ms 604800000 DEFAULT\_CONFIG retention.bytes -1 DEFAULT\_CONFIG message.timestamp.type CreateTime DEFAULT\_CONFIG max.message.bytes 1048576 DEFAULT\_CONFIG redpanda.remote.read false DEFAULT\_CONFIG redpanda.remote.write false DEFAULT\_CONFIG retention.local.target.bytes -1 DEFAULT\_CONFIG retention.local.target.ms 86400000 DEFAULT\_CONFIG redpanda.remote.delete true DEFAULT\_CONFIG segment.ms 1209600000 DEFAULT\_CONFIG ## [](#update-a-topic)Update a topic To update a topic, edit the Topic resource configuration, and apply the changes. > ⚠️ **CAUTION** > > Do not use `rpk` or any other Kafka clients to edit topics that you created using the Topic resource. The topic controller monitors the Redpanda cluster for changes to topics. If you use a Kafka client to edit the topic, the topic controller detects those changes as a drift from the desired state and attempts to reconcile those changes by reverting them to match the Topic resource’s state. The following example changes the cleanup policy for a topic: `example-topic.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Topic metadata: name: namespace: spec: cluster: clusterRef: name: partitions: 3 replicationFactor: 3 additionalConfig: cleanup.policy: "delete" ``` ```bash kubectl apply -f example-topic.yaml --namespace ``` To set a property back to its default value, remove it from the Topic resource. ## [](#delete-a-topic)Delete a topic To delete a topic, delete the Topic resource. For example: ```bash kubectl delete -f example-topic.yaml --namespace ``` When a topic is deleted, its underlying data is deleted, too. > 📝 **NOTE** > > If you delete the Kafka topic directly using a client such as `rpk`, the topic controller recreates an empty topic with the same name. ## [](#delete-records-from-a-topic)Delete records from a topic Redpanda allows you to delete data from the beginning of a partition up to a specific offset (a monotonically increasing sequence number for records in a partition). Deleting records frees up disk space, which is especially helpful if your producers are pushing more data than anticipated in your retention plan. Delete records when you know that all consumers have read up to that given offset, and the data is no longer needed. There are different ways to delete records from a topic, including using the [`rpk topic trim-prefix`](../../../reference/rpk/rpk-topic/rpk-topic-trim-prefix/) command, using the `DeleteRecords` Kafka API with Kafka clients, or using Redpanda Console. > 📝 **NOTE** > > - To delete records, `cleanup.policy` must be set to `delete` or `compact,delete`. > > - Object storage is deleted asynchronously. After messages are deleted, the partition’s start offset will have advanced, but garbage collection of deleted segments may not be complete. > > - Similar to Kafka, after deleting records, local storage and object storage may still contain data for deleted offsets. (Redpanda does not truncate segments. Instead, it bumps the start offset, then it attempts to delete as many whole segments as possible.) Data before the new start offset is not visible to clients but could be read by someone with access to the local disk of a Redpanda node. > ⚠️ **WARNING** > > When you delete records from a topic with a timestamp, Redpanda advances the partition start offset to the first record whose timestamp is after the threshold. If record timestamps are not in order with respect to offsets, this may result in unintended deletion of data. Before using a timestamp, verify that timestamps increase in the same order as offsets in the topic to avoid accidental data loss. For example: > > ```bash > rpk topic consume -n 50 --format '%o %d{go[2006-01-02T15:04:05Z07:00]} %k %v' > ``` ## [](#cluster-wide-topic-configurations)Cluster-wide topic configurations Topics provide a way to organize events in a data streaming platform. When you create a topic, the default cluster-level topic configurations are applied using the cluster configuration file, unless you specify different configurations. The following table shows the default cluster-level properties and their equivalent topic-level properties: | Cluster property | Default | Topic property | | --- | --- | --- | | log_cleanup_policy | delete | cleanup.policy | | retention_bytes | null (no limit) | retention.bytes | | log_retention_ms | 604800000 ms (1 week) | retention.ms | | log_segment_ms | null (no limit) | segment.ms | | log_segment_size | 134217728 bytes (128 MiB) | segment.bytes | | log_compression_type | producer | compression.type | | log_message_timestamp_type | CreateTime | message.timestamp.type | | kafka_batch_max_bytes | 1048576 bytes (1 MiB) | max.message.bytes | | write_caching_default | false | write.caching | These default settings are best suited to a one-broker cluster in a development environment. To learn how to modify the default cluster-wide configurations, see [Configure Cluster Properties](../k-configure-helm-chart/). Even if you set default values that work for most topics, you may still want to change some properties for a specific topic. > 📝 **NOTE** > > For details about topic properties, see [Topic Configuration Properties](../../../reference/properties/topic-properties/). ## [](#suggested-reading)Suggested reading - [cluster.redpanda.com/v1alpha2](../../../reference/k-crd/) - [Topic Configuration Properties](../../../reference/properties/topic-properties/) ## [](#next-steps)Next steps Combine [SASL authentication](../security/authentication/k-authentication/) with [authorization](../../security/authorization/) to control which users have permissions to interact with your topics. --- # Page 164: Enable the PVCUnbinder **URL**: https://docs.redpanda.com/current/manage/kubernetes/k-nodewatcher.md --- # Enable the PVCUnbinder --- title: Enable the PVCUnbinder latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/k-nodewatcher page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/k-nodewatcher.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/k-nodewatcher.adoc description: The PVCUnbinder is an emergency backstop for Redpanda clusters that use PersistentVolumes (PVs) for the Redpanda data directory. When a node running a Redpanda Pod suddenly goes offline, the PVCUnbinder detects the lost node, retains the associated PV, and removes the corresponding PersistentVolumeClaim (PVC). This workflow allows the Redpanda Pod to be rescheduled on a new node without losing critical data. page-git-created-date: "2025-01-28" page-git-modified-date: "2025-04-07" support-status: supported --- The PVCUnbinder is an emergency backstop for Redpanda clusters that use PersistentVolumes (PVs) for the Redpanda data directory. When a node running a Redpanda Pod suddenly goes offline, the PVCUnbinder detects the lost node, retains the associated PV, and removes the corresponding PersistentVolumeClaim (PVC). This workflow allows the Redpanda Pod to be rescheduled on a new node without losing critical data. > ⚠️ **WARNING: Emergency use only** > > The PVCUnbinder is intended only for emergency scenarios (for example, node hardware or infrastructure failures). **Never use the PVCUnbinder as a routine method for removing brokers.** If you want to remove brokers, see [Decommission brokers](../k-decommission-brokers/) for the correct procedure. ## [](#why-use-the-pvcunbinder)Why use the PVCUnbinder? If a worker node hosting a Redpanda Pod suddenly fails or disappears, Kubernetes might leave the associated PV and PVC in an _attached_ or _in-use_ state. Without the PVCUnbinder (or manual intervention), the Redpanda Pod cannot safely reschedule to another node because the volume is still recognized as occupied. Also, the default reclaim policy might delete the volume, risking data loss. The PVCUnbinder automates the steps needed to retain the volume and remove the stale PVC, so Redpanda Pods can move to healthy nodes without losing the data in the original PV. ## [](#how-the-pvcunbinder-works)How the PVCUnbinder works When the PVCUnbinder detects events that indicate a Node resource is no longer available, it does the following: - For each Redpanda Pod on that Node, it identifies the PVC (if any) the Pod was using for its storage. - It sets the reclaim policy of the affected PersistentVolume (PV) to `Retain`. - It deletes the associated PersistentVolumeClaim (PVC) to allow the Redpanda broker Pod to reschedule onto a new, operational node. flowchart TB %% Define classes classDef systemAction fill:#F6FBF6,stroke:#25855a,stroke-width:2px,color:#20293c,rx:5,ry:5 A\[Node fails\] --> B{Is Node running Redpanda?}:::systemAction B -- Yes --> C\[Identify Redpanda Pod PVC\]:::systemAction C --> D\[Set PV reclaim policy to 'Retain'\]:::systemAction D --> E\[Delete PVC\]:::systemAction E --> F\[Redpanda Pod is rescheduled\]:::systemAction B -- No --> G\[Ignore event\]:::systemAction ## [](#enable-the-pvcunbinder)Enable the PVCUnbinder ### Operator To enable the PVCUnbinder: `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: statefulset: sideCars: pvcUnbinder: enabled: true (1) unbindAfter: 60s (2) rbac: enabled: true (3) ``` | 1 | statefulset.sideCars.pvcUnbinder.enabled: Enables the PVCUnbinder sidecar. | | --- | --- | | 2 | statefulset.sideCars.pvcUnbinder.unbindAfter: Sets the time in seconds after which the PVCUnbinder sidecar removes the PVC after the Node resource is deleted. | | 3 | rbac.enabled: Creates the required RBAC rules for the PVCUnbinder to monitor the Node resources and update PVCs and PVs. | ### Helm #### --values `pvcunbinder.yaml` ```yaml statefulset: sideCars: pvcUnbinder: enabled: true (1) unbindAfter: 60s (2) rbac: enabled: true (3) ``` | 1 | statefulset.sideCars.pvcUnbinder.enabled: Enables the PVCUnbinder sidecar. | | --- | --- | | 2 | statefulset.sideCars.pvcUnbinder.unbindAfter: Sets the time in seconds after which the PVCUnbinder sidecar removes the PVC after the Node resource is deleted. | | 3 | rbac.enabled: Creates the required RBAC rules for the PVCUnbinder to monitor the Node resources and update PVCs and PVs. | #### --set ```bash helm upgrade --install redpanda redpanda/redpanda \ --namespace \ --create-namespace \ --set statefulset.sideCars.pvcUnbinder.enabled=true \ (1) --set statefulset.sideCars.pvcUnbinder.unbindAfter=60s\ (2) --set rbac.enabled=true (3) ``` | 1 | statefulset.sideCars.pvcUnbinder.enabled: Enables the PVCUnbinder sidecar. | | --- | --- | | 2 | statefulset.sideCars.pvcUnbinder.unbindAfter: Sets the time in seconds after which the PVCUnbinder sidecar removes the PVC after the Node resource is deleted. | | 3 | rbac.enabled: Creates the required RBAC rules for the PVCUnbinder to monitor the Node resources and update PVCs and PVs. | ## [](#test-the-pvcunbinder-sidecar)Test the PVCUnbinder sidecar 1. Test the PVCUnbinder sidecar by deleting a Node resource: ```bash kubectl delete node ``` > 📝 **NOTE** > > This step is for testing purposes only. 2. Monitor the logs of the PVCUnbinder sidecar: ```bash kubectl logs --namespace -c sidecars ``` You should see that the PVCUnbinder successfully deleted the PVC of the Pod that was running on the deleted Node resource. ```bash kubectl get persistentvolumeclaim --namespace ``` 3. Verify that the reclaim policy of the PV is set to `Retain` to allow you to recover the node, if necessary: ```bash kubectl get persistentvolume --namespace ``` After the PVCUnbinder has finished, [decommission the broker](../k-decommission-brokers/) that was removed from the node. This is necessary to prevent a potential loss of quorum and ensure cluster stability. > 📝 **NOTE** > > Make sure to use the `--force` flag when decommissioning the broker with [`rpk redpanda admin brokers decommission`](../../../reference/rpk/rpk-redpanda/rpk-redpanda-admin-brokers-decommission/). This flag is required when the broker is no longer running. ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Owl Shop Example Application in Docker](/redpanda-labs/docker-compose/owl-shop/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) See more [Search all labs](/redpanda-labs) --- # Page 165: Enable Rack Awareness in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/k-rack-awareness.md --- # Enable Rack Awareness in Kubernetes --- title: Enable Rack Awareness in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/k-rack-awareness page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/k-rack-awareness.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/k-rack-awareness.adoc description: Enable rack awareness to place partition replicas across different failure zones. page-git-created-date: "2024-01-04" page-git-modified-date: "2025-12-04" support-status: supported --- Rack awareness allows you to distribute replicas of the same partition across different racks to minimize data loss in the event of a rack failure. A rack is a failure zone that has one or more Redpanda brokers assigned to it. When you create a topic, you specify the number of partitions for the topic and the number of partition replicas. By default, Redpanda determines where to place the replicas on the cluster such that each replica is on a different broker, if possible. By defining different racks for a Redpanda cluster, you can specify a preference for the way partition replicas are assigned to brokers. When Redpanda places partition replicas, it takes into account whether a replica has already been placed on a broker in a particular rack. If so, Redpanda chooses a broker in a different rack. This way, partition replicas are distributed across different failure zones, which provides a measure of fault tolerance in the event that a broker or an entire rack becomes unavailable. When rack awareness is enabled, Redpanda places replicas according to these criteria: - Number of racks vs. replicas - If the cluster has more racks than the number of replicas, each replica is placed on a broker in a unique rack. If the cluster has fewer racks than the number of replicas, some replicas are placed on brokers in the same rack. - Number of available CPU cores - Brokers with more available CPU cores are chosen over brokers with fewer available CPU cores. - Broker utilization - Brokers with fewer partitions are chosen over brokers with more partitions. When you enable rack awareness in the Redpanda Helm chart, Kubernetes failure zones are treated as racks. Redpanda maps each rack to a failure zone and places partition replicas across them. For more details about Kubernetes failure zones, see the [Kubernetes documentation](https://kubernetes.io/docs/setup/best-practices/multiple-zones/). ## [](#prerequisites)Prerequisites You must have the following: - Kubernetes cluster: Ensure you have a running Kubernetes cluster, either locally, such as with minikube or kind, or remotely. - [Kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl): Ensure you have the `kubectl` command-line tool installed and configured to communicate with your cluster. ## [](#annotate-or-label-node-resources)Annotate or label Node resources To assign a failure zone to your Kubernetes nodes, ensure that each of your Node resources is annotated or labeled with a key/value pair that corresponds to a failure zone. The Helm chart assigns each Redpanda broker to a particular rack, according to the failure zone of the Kubernetes node on which the broker is running. Managed Kubernetes platforms usually annotate Node resources with the availability zone in which the node instance is hosted. For example `topology.kubernetes.io/zone=use-az1`. To check the value of the `topology.kubernetes.io/zone` key, run the following: ```bash kubectl get node \ -o=custom-columns=NODE:.metadata.name,ZONE:.metadata.annotations."topology\.kubernetes\.io/zone" ``` Example output: ```text NODE ZONE example-worker use1-az1 example-worker2 use1-az2 example-worker3 use1-az3 ``` If you don’t see any values in the Zone column, make sure to annotate or label your Node resources with key/value pairs that correspond to your fault-tolerance requirements. For example: ```bash kubectl annotate node example-worker topology.kubernetes.io/zone=rack1 kubectl annotate node example-worker2 topology.kubernetes.io/zone=rack2 kubectl annotate node example-worker3 topology.kubernetes.io/zone=rack3 ``` If you’re running Redpanda in Amazon AWS, you can use the following DaemonSet to label your Node resources with a zone ID: Example labeler DaemonSet ```yaml --- apiVersion: v1 kind: ServiceAccount metadata: name: labeler --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: name: labeler rules: - apiGroups: - "" resources: - nodes verbs: - patch --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: name: labeler roleRef: apiGroup: rbac.authorization.k8s.io kind: ClusterRole name: labeler subjects: - kind: ServiceAccount name: labeler namespace: --- apiVersion: apps/v1 kind: DaemonSet metadata: name: labeler spec: selector: matchLabels: name: labeler template: metadata: labels: name: labeler spec: serviceAccountName: labeler initContainers: - name: labeler image: debian:bullseye-slim imagePullPolicy: IfNotPresent command: - /bin/bash - -c - -- args: - | apt-get update -y && apt-get install -y curl jq apt-transport-https ca-certificates curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.28/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg # This overwrites any existing configuration in /etc/apt/sources.list.d/kubernetes.list echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.28/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list apt-get update -y && apt-get install -y kubectl # Get a token to be able to interact with the EC2 instance metadata API v2 # https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html TOKEN=$(curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600") # Get the current node's AZ ID AZ_ID=$(curl -H "X-aws-ec2-metadata-token: $TOKEN" -v "http://169.254.169.254/latest/meta-data/placement/availability-zone-id") kubectl label node/"$HOST" "topology.cloud.redpanda.com/zone-id=$AZ_ID" --overwrite containers: - name: pause image: debian:bullseye-slim imagePullPolicy: IfNotPresent command: - /bin/bash - -c - -- args: - | trap : TERM INT; sleep infinity & wait ``` ## [](#configure-rack-awareness)Configure rack awareness To enable rack awareness in your Redpanda cluster, configure the cluster with the key you used to annotate or label Node resources with the availability zone. ### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: rackAwareness: enabled: true nodeAnnotation: '' serviceAccount: create: true rbac: enabled: true ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ### Helm #### --values `rack-awareness.yaml` ```yaml rackAwareness: enabled: true nodeAnnotation: '' serviceAccount: create: true rbac: enabled: true ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values rack-awareness.yaml --reuse-values ``` #### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set rackAwareness.enabled=true \ --set rackAwareness.nodeAnnotation='' \ --set serviceAccount.create=true \ --set rbac.enabled=true ``` - `rackAwareness.enabled` (**required**): Enables rack awareness for your Redpanda cluster. - `rackAwareness.nodeAnnotation` (**required**): The label or annotation key to use to define racks. Defaults to the [well-known](https://kubernetes.io/docs/reference/labels-annotations-taints/#topologykubernetesiozone) `topology.kubernetes.io/zone` key. > 📝 **NOTE** > > The `serviceAccount` and `rbac` configurations are required. These configurations allow the initialization container to securely read the node annotations using the Kubernetes API. ## [](#verify-that-rack-awareness-is-enabled)Verify that rack awareness is enabled After deploying Redpanda, make sure that rack awareness is enabled and configured on your Redpanda brokers. Make sure that rack awareness has been enabled and configured on your Redpanda brokers: ```bash kubectl --namespace exec -i -t redpanda-0 -c redpanda -- \ rpk cluster config get enable_rack_awareness ``` Example output: true ## [](#next-steps)Next steps Use rack awareness with [Continuous Data Balancing](../../cluster-maintenance/continuous-data-balancing/) to continually maintain the configured replication level, even after a rack failure. For a given partition, Redpanda tries to move excess replicas from racks that have more than one replica to racks that have no replicas. ## [](#suggested-reading)Suggested reading - [Redpanda Helm Specification](../../../reference/k-redpanda-helm-spec/#rackawareness) - [Redpanda CRD Reference](../../../reference/k-crd/) ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) [Search all labs](/redpanda-labs) --- # Page 166: Remote Read Replicas in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/k-remote-read-replicas.md --- # Remote Read Replicas in Kubernetes --- title: Remote Read Replicas in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/k-remote-read-replicas page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/k-remote-read-replicas.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/k-remote-read-replicas.adoc description: Create read-only topics (Remote Read Replica topics) that mirror topics on a different cluster. page-git-created-date: "2024-01-04" page-git-modified-date: "2025-07-31" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../get-started/licensing/#self-managed) apply. A Remote Read Replica topic is a read-only topic that mirrors a topic on a different cluster. Remote Read Replicas work with both [Tiered Storage](../tiered-storage/k-tiered-storage/) and [archival storage](../tiered-storage/k-tiered-storage/#data-archiving). When a topic has object storage enabled, you can create a separate remote cluster just for consumers of this topic, and populate its topics from remote storage. A read-only topic on a remote cluster can serve any consumer, without increasing the load on the origin cluster. Use cases for Remote Read Replicas include data analytics, offline model training, and development clusters. You can create Remote Read Replica topics in a Redpanda cluster that directly accesses data stored in object storage. Because these read-only topics access data directly from object storage instead of the topics' origin cluster, there’s no impact to the performance of the cluster. Topic data can be consumed within a region of your choice, regardless of the region where it was produced. > ❗ **IMPORTANT** > > - The Remote Read Replica cluster must run on the same version of Redpanda as the origin cluster, or just one feature release ahead of the origin cluster. For example, if the origin cluster is version 24.1, the Remote Read Replica cluster can be 24.2, but not 24.3. It cannot skip feature releases. > > - When upgrading, upgrade the Remote Read Replica cluster before upgrading the origin cluster. For default values and documentation for configuration options, see the [`values.yaml`](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=storage.tiered.config) file. ## [](#prerequisites)Prerequisites You need the following: - An origin cluster with [Tiered Storage](../tiered-storage/k-tiered-storage/#set-up-tiered-storage) set up. Multi-region buckets or containers are not supported. - A topic on the origin cluster, which you can use as a Remote Read Replica topic on the remote cluster. - A separate remote cluster. - AWS: The remote cluster can be in the same or a different region as the origin cluster’s S3 bucket. For cross-region Remote Read Replica topics, see [Create a cross-region Remote Read Replica topic on AWS](#create-cross-region-rrr-topic). - GCP: The remote cluster can be in the same or a different region as the bucket/container. - Azure: Remote read replicas are not supported. This feature requires an [enterprise license](../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../get-started/licensing/#self-managed) apply. To check if you already have a license key applied to your cluster: ```bash rpk cluster license info ``` ## [](#configure-object-storage-for-the-remote-cluster)Configure object storage for the remote cluster You must configure access to the same object storage as the origin cluster. #### Amazon S3 You can configure access to Amazon S3 with either an IAM role attached to the instance or with access keys. ### Use IAM roles To configure access to an S3 bucket with an IAM role: 1. Configure an [IAM role](../../security/iam-roles/#configuring-iam-roles) with read permissions for the S3 bucket. 2. Override the following required cluster properties in the Helm chart: Replace the following placeholders: - ``: The region of your S3 bucket. ### Use access keys To configure access to an S3 bucket with access keys instead of an IAM role: 1. Grant a user the following permissions to read objects on the bucket to be used with the cluster (or on all buckets): - `GetObject` - `ListBucket` 2. Create a Secret in which to store the access key and secret key. ```yaml apiVersion: v1 kind: Secret metadata: name: storage-secrets namespace: type: Opaque data: access-key: secret-key: ``` - Replace `` with your base64-encoded access key. - Replace `` with your base64-encoded secret key. 3. Override the following required cluster properties in the Helm chart: Replace `` with the region of your S3 bucket. ##### --values `cloud-storage.yaml` ```yaml storage: tiered: config: cloud_storage_enabled: true cloud_storage_credentials_source: aws_instance_metadata cloud_storage_region: cloud_storage_bucket: "none" ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values cloud-storage.yaml ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set storage.tiered.config.cloud_storage_enabled=true \ --set storage.tiered.config.cloud_storage_credentials_source=aws_instance_metadata \ --set storage.tiered.config.cloud_storage_region= \ --set storage.tiered.config.cloud_storage_bucket="none" ``` ##### --values `cloud-storage.yaml` ```yaml storage: tiered: credentialsSecretRef: accessKey: name: storage-secrets key: access-key secretKey: name: storage-secrets key: secret-key config: cloud_storage_enabled: true cloud_storage_credentials_source: config_file cloud_storage_region: cloud_storage_bucket: "none" ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values cloud-storage.yaml ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set storage.tiered.config.cloud_storage_enabled=true \ --set storage.tiered.credentialsSecretRef.accessKey.name=storage-secrets \ --set storage.tiered.credentialsSecretRef.accessKey.key=access-key \ --set storage.tiered.credentialsSecretRef.secretKey.name=storage-secrets \ --set storage.tiered.credentialsSecretRef.secretKey.key=secret-key \ --set storage.tiered.config.cloud_storage_credentials_source=config_file \ --set storage.tiered.config.cloud_storage_region= \ --set storage.tiered.config.cloud_storage_bucket="none" ``` #### Google Cloud Storage You can configure access to Google Cloud Storage with either an IAM role attached to the instance or with access keys. ### Use IAM roles To configure access to Google Cloud Storage with an IAM role, override the following required cluster properties in the Helm chart: Replace `` with the region of your bucket. ### Use access keys To configure access to Google Cloud Storage with access keys instead of an IAM role: 1. Create a Secret in which to store the access key and secret key. ```yaml apiVersion: v1 kind: Secret metadata: name: storage-secrets namespace: type: Opaque data: access-key: secret-key: ``` - Replace `` with your base64-encoded access key. - Replace `` with your base64-encoded secret key. 2. Override the following required cluster properties in the Helm chart: Replace `` with the region of your bucket. ##### --values `cloud-storage.yaml` ```yaml storage: tiered: config: cloud_storage_enabled: true cloud_storage_credentials_source: gcp_instance_metadata cloud_storage_region: cloud_storage_bucket: "none" ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values cloud-storage.yaml ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set storage.tiered.config.cloud_storage_enabled=true \ --set storage.tiered.config.cloud_storage_credentials_source=aws_instance_metadata \ --set storage.tiered.config.cloud_storage_region= \ --set storage.tiered.config.cloud_storage_bucket="none" ``` ##### --values `cloud-storage.yaml` ```yaml storage: tiered: credentialsSecretRef: accessKey: name: storage-secrets key: access-key secretKey: name: storage-secrets key: secret-key config: cloud_storage_enabled: true cloud_storage_credentials_source: config_file cloud_storage_api_endpoint: storage.googleapis.com cloud_storage_region: cloud_storage_bucket: "none" ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values cloud-storage.yaml ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set storage.tiered.config.cloud_storage_enabled=true \ --set storage.tiered.credentialsSecretRef.accessKey.name=storage-secrets \ --set storage.tiered.credentialsSecretRef.accessKey.key=access-key \ --set storage.tiered.credentialsSecretRef.secretKey.name=storage-secrets \ --set storage.tiered.credentialsSecretRef.secretKey.key=secret-key \ --set storage.tiered.config.cloud_storage_credentials_source=config_file \ --set storage.tiered.config.cloud_storage_api_endpoint=storage.googleapis.com \ --set storage.tiered.config.cloud_storage_region= \ --set storage.tiered.config.cloud_storage_bucket="none" ``` #### Azure Blob Storage To configure access to Azure Blob Storage(ABS): 1. Create a Secret in which to store the access key. ```yaml apiVersion: v1 kind: Secret metadata: name: storage-secrets namespace: type: Opaque data: access-key: ``` - Replace `` with your base64-encoded access key. 2. Override the following required cluster properties in the Helm chart: Replace `` with the name of your Azure account. ##### --values `cloud-storage.yaml` ```yaml storage: tiered: credentialsSecretRef: secretKey: configurationKey: cloud_storage_azure_shared_key name: storage-secrets key: access-key config: cloud_storage_enabled: true cloud_storage_azure_storage_account: cloud_storage_azure_container: "none" ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values cloud-storage.yaml ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set storage.tiered.config.cloud_storage_enabled=true \ --set storage.tiered.credentialsSecretRef.secretKey.configurationKey=cloud_storage_azure_shared_key \ --set storage.tiered.credentialsSecretRef.secretKey.name=storage-secrets \ --set storage.tiered.credentialsSecretRef.secretKey.key=access-key \ --set storage.tiered.config.cloud_storage_azure_storage_account= \ --set storage.tiered.config.cloud_storage_azure_container="none" ``` ## [](#create-a-remote-read-replica-topic)Create a Remote Read Replica topic To create the Remote Read Replica topic, run: ```bash rpk topic create -c redpanda.remote.readreplica= ``` - For ``, use the same name as the original topic. - For ``, use the bucket/container specified in the `cloud_storage_bucket` or `cloud_storage_azure_container` properties for the origin cluster. > 📝 **NOTE** > > - The Remote Read Replica cluster must run on the same version of Redpanda as the origin cluster, or just one feature release ahead of the origin cluster. For example, if the origin cluster is version 23.1, the Remote Read Replica cluster can be 23.2, but not 23.4. It cannot skip feature releases. > > - During upgrades, upgrade the Remote Read Replica cluster before upgrading the origin cluster. > > - Do not use `redpanda.remote.read` or `redpanda.remote.write` with `redpanda.remote.readreplica`. Redpanda ignores the values for remote read and remote write properties on read replica topics. ### [](#create-cross-region-rrr-topic)Create a cross-region Remote Read Replica topic on AWS Use this configuration only when the remote cluster is in a **different AWS region** than the origin cluster’s S3 bucket. For same-region AWS or GCP deployments, use the standard [topic creation command](#create-a-remote-read-replica-topic). #### [](#prerequisites-2)Prerequisites You must explicitly set the [`cloud_storage_url_style`](../../../reference/properties/object-storage-properties/#cloud_storage_url_style) cluster property to `virtual_host` or `path` on the remote cluster. The default value does not support cross-region Remote Read Replicas. #### [](#create-the-topic)Create the topic To create a cross-region Remote Read Replica topic, append `region` and `endpoint` query-string parameters to the bucket name. In the following example, replace the placeholders: - ``: The name of the topic in the cluster hosting the Remote Read Replica. - ``: The S3 bucket configured on the origin cluster (`cloud_storage_bucket`). - ``: The AWS region of the origin cluster’s S3 bucket (not the remote cluster’s region). ```bash rpk topic create \ -c redpanda.remote.readreplica=?region=&endpoint=s3..amazonaws.com ``` For example, if the origin cluster stores data in a bucket called `my-bucket` in `us-east-1`: ```bash rpk topic create my-topic \ -c redpanda.remote.readreplica=my-bucket?region=us-east-1&endpoint=s3.us-east-1.amazonaws.com ``` > 📝 **NOTE** > > The `endpoint` value must not include the bucket name. When using `virtual_host` URL style, Redpanda automatically prepends the bucket name to the endpoint. When using `path` URL style, Redpanda appends the bucket name as a path segment. #### [](#limits)Limits Each unique combination of region and endpoint creates a separate object storage target on the remote cluster. A cluster supports a maximum of 10 targets. How targets are counted depends on `cloud_storage_url_style`: - `virtual_host`: Each unique combination of bucket, region, and endpoint counts as one target. You can create up to 10 distinct cross-region Remote Read Replica topics for each cluster. - `path`: Each unique combination of region and endpoint counts as one target (the bucket name is not part of the key). You can create cross-region Remote Read Replica topics for multiple buckets using the same region/endpoint combination, with a maximum of 10 distinct region/endpoint combinations for each cluster. ## [](#reduce-lag-in-data-availability)Reduce lag in data availability When object storage is enabled on a topic, Redpanda copies closed log segments to the configured object store. Log segments are closed when the value of the segment size has been reached. A topic’s object store thus lags behind the local copy by the [`log_segment_size`](../../../reference/properties/cluster-properties/#log_segment_size) or, if set, by the topic’s `segment.bytes` value. To reduce this lag in the data availability for the Remote Read Replica: - You can lower the value of `segment.bytes`. This lets Redpanda archive smaller log segments more frequently, at the cost of increasing I/O and file count. - Redpanda Self-Managed deployments can set an idle timeout with `[storage.tiered.config.cloud_storage_segment_max_upload_interval_sec](../../../reference/properties/object-storage-properties/#cloud_storage_segment_max_upload_interval_sec)` to force Redpanda to periodically archive the contents of open log segments to object storage. This is useful if a topic’s write rate is low and log segments are kept open for long periods of time. The appropriate interval may depend on your total partition count: a system with less partitions can handle a higher number of segments per partition. ## [](#suggested-reading)Suggested reading [Remote Read Replicas: Read-only topics in Tiered Storage](https://redpanda.com/blog/remote-read-replicas-for-distributing-work) ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) [Search all labs](/redpanda-labs) --- # Page 167: Resilience Testing in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/k-resilience-testing.md --- # Resilience Testing in Kubernetes --- title: Resilience Testing in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/k-resilience-testing page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/k-resilience-testing.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/k-resilience-testing.adoc description: With resilience testing, you can introduce failures and observe how the system behaves under each failure scenario. page-git-created-date: "2024-01-04" page-git-modified-date: "2024-02-26" support-status: supported --- Resilience testing is an important part of ensuring that a system is reliable and can recover from failures. To perform resilience testing for Redpanda in Kubernetes, you can introduce failure scenarios and observe how the system behaves under each scenario. ## [](#prerequisites)Prerequisites - Create a test environment that mimics your production environment as closely as possible. The test environment should include a Redpanda cluster with at least three replicas, and any services that your application depends on. You can find guides for deploying Redpanda in [Get Started with Redpanda in Kubernetes](../../../deploy/redpanda/kubernetes/get-started-dev/). - [Set up monitoring](../monitoring/) so that you can observe changes in the system behavior. ## [](#simulate-failure-scenarios)Simulate failure scenarios This section provides the steps to simulate failure scenarios in Kubernetes. After each simulation, it’s important to monitor the behavior of the Redpanda cluster and any clients that are connected to it. ### [](#broker-going-down)Broker going down You can simulate a broker going down for an extended period of time by manually terminating one of them. 1. Find out on which node each of your brokers is running: ```bash kubectl get pod --namespace \ -o=custom-columns=NODE:.spec.nodeName,NAME:.metadata.name -l \ app.kubernetes.io/component=redpanda-statefulset ``` 2. Taint the node that’s running the broker that you want to terminate: ```bash kubectl taint nodes isolate-broker=true:NoExecute ``` Replace `` with the name of the node you want to taint. Any Pods that do not tolerate this taint are terminated and evicted from the node. 3. Monitor the logs and metrics of the remaining brokers to observe how they behave when a broker is unexpectedly terminated. 4. Remove the taint when you’re ready for the broker to come back online: ```bash kubectl taint nodes isolate-broker=true:NoExecute- ``` 5. Check whether the terminated broker can rejoin the cluster when it is rescheduled on the node and comes back online. ## [](#suggested-reading)Suggested reading It’s best practice to automate failure scenarios as part of your regular testing to identify any weaknesses in your deployment. You can use tools, such as [Chaos Monkey](https://netflix.github.io/chaosmonkey/) and [LitmusChaos](https://docs.litmuschaos.io/docs/getting-started/installation/). ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) [Search all labs](/redpanda-labs) --- # Page 168: Perform a Rolling Restart of Redpanda in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/k-rolling-restart.md --- # Perform a Rolling Restart of Redpanda in Kubernetes --- title: Perform a Rolling Restart of Redpanda in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/k-rolling-restart page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/k-rolling-restart.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/k-rolling-restart.adoc description: Learn how to perform a rolling restart of your Redpanda cluster when it's running in Kubernetes. page-git-created-date: "2023-12-13" page-git-modified-date: "2025-12-04" support-status: supported --- A rolling restart involves restarting one broker at a time while the remaining brokers in your cluster continue running. Rolling restarts help to minimize downtime during a full cluster restart. You should perform a rolling restart during operations such as configuration updates that require a restart, version upgrades, or cluster maintenance. ## [](#prerequisites)Prerequisites You must have the following: - [A Redpanda cluster running in Kubernetes](../../../deploy/redpanda/kubernetes/get-started-dev/). - The default [RollingUpdate strategy](../../../reference/k-redpanda-helm-spec/#statefulset-updatestrategy-type) configured in the Helm values. ## [](#what-happens-during-a-rolling-restart)What happens during a rolling restart When you run Redpanda in Kubernetes, your Redpanda cluster is managed as a StatefulSet where each broker runs inside its own Pod. As a result, you can perform a rolling restart using the Kubernetes API to terminate one Pod at a time, starting from the one with the highest ordinal. During a rolling restart the [Redpanda Helm chart](../../../deploy/redpanda/kubernetes/k-deployment-overview/) automates the following procedure on each broker, using the `preStop` and `postStart` lifecycle hooks: 1. The `preStop` hook is executed immediately before a container is terminated. The `preStop` hook is responsible for the following: 1. Place the broker into maintenance mode. Placing brokers into maintenance mode reduces the risk of interruption or degradation in service. When a broker is placed into maintenance mode, it reassigns its partition leadership to other brokers for all topics that have a replication factor greater than one (three is the default replication factor for topics). Reassigning partition leadership involves _draining_ leadership from the broker and _transferring_ that leadership to another broker. 2. Terminate the Pod. After the `preStop` hook completes its tasks, Kubernetes sends a SIGTERM signal to the container, signaling it to shut down. Maintenance mode may not have finished when the SIGTERM is sent. As a result, Kubernetes waits for the duration of the `terminationGracePeriodSeconds` for Redpanda to shut down gracefully. If it’s still executing, a SIGKILL is sent to the container to forcefully terminate Redpanda. The Pod is then terminated and restarted due to the default rolling update policy of the StatefulSet. > 📝 **NOTE** > > The default `terminationGracePeriod` is 90 seconds, which should be long enough for maintenance mode to finish in large clusters. You can test different values in a development environment. To configure the `terminationGracePeriod`, use the `statefulset.podTemplate.spec.terminationGracePeriodSeconds` setting. 2. The `postStart` hook is executed immediately after a container is created. The `postStart` hook takes the broker out of maintenance mode. This action re-integrates the broker into the cluster, allowing it to start handling requests and participate in the cluster’s operations again. ## [](#impact-of-broker-restarts)Impact of broker restarts When brokers restart, clients may experience higher latency, nodes may experience CPU spikes when the broker becomes available again, and you may receive alerts about under-replicated partitions. Topics that weren’t using replication (that is, topics that had `replication.factor=1`) will be unavailable. ### [](#temporary-increase-in-latency-on-clients-producers-and-consumers)Temporary increase in latency on clients (producers and consumers) When you restart one or more brokers in a cluster, clients (consumers and producers) may experience higher latency due to partition leadership reassignment. Because clients must communicate with the leader of a partition, they may send a request to a broker whose leadership has been transferred, and receive `NOT_LEADER_FOR_PARTITION`. In this case, clients must request metadata from the cluster to find out the address of the new leader. Clients refresh their metadata periodically, or when the client receives some retryable errors that indicate that the metadata may be stale. For example: 1. Broker A shuts down. 2. Client sends a request to broker A, and receives `NOT_LEADER_FOR_PARTITION`. 3. Client requests metadata, and learns that the new leader is broker B. 4. Client sends the request to broker B. ### [](#cpu-spikes-upon-broker-restart)CPU spikes upon broker restart When a restarted broker becomes available again, you may see your nodes' CPU usage increase temporarily. This temporary increase in CPU usage is due to the cluster rebalancing the partition replicas. ### [](#under-replicated-partitions)Under-replicated partitions When a broker is in maintenance mode, Redpanda continues to replicate updates to that broker. When a broker is taken offline during a restart, partitions with replicas on the broker could become out of sync until it is brought back online. Once the broker is available again, data is copied to its under-replicated replicas until all affected partitions are in sync with the partition leader. ## [](#perform-a-rolling-restart)Perform a rolling restart 1. Check for topics that have a replication factor greater than one. Partitions that live on only one broker will be offline during the restart. If you have topics with a replication factor of 1, and if you have sufficient disk space, temporarily [increase the replication factor](../../../migrate/data-migration/#change-topic-replication-factor) to limit outages for these topics during the rolling upgrade. 2. Ensure that the cluster is healthy: ```bash kubectl exec --namespace -c redpanda -- \ rpk cluster health ``` The draining process won’t start until the cluster is healthy. Example output: CLUSTER HEALTH OVERVIEW ======================= Healthy: true **(1)** Controller ID: 0 All nodes: \[0 1 2\] **(2)** Nodes down: \[\] **(3)** Leaderless partitions: \[\] **(3)** Under-replicated partitions: \[\] **(3)** | 1 | The cluster is either healthy (true) or unhealthy (false). | | --- | --- | | 2 | The node IDs of all brokers in the cluster. | | 3 | These fields contain data only when the cluster is unhealthy. | 3. Trigger a rolling restart of all Pods in the StatefulSet: ```bash kubectl rollout restart statefulset redpanda --namespace= ``` 4. Wait for all Pods to restart: ```bash kubectl rollout status statefulset redpanda --namespace= --watch ``` ## [](#verify-the-clusters-health)Verify the cluster’s health To verify that the cluster is running properly, run: ```bash kubectl exec --namespace -c redpanda -- \ rpk cluster health ``` To view additional information about your brokers, run: ```bash kubectl exec --namespace -c redpanda -- \ rpk redpanda admin brokers list ``` ## [](#suggested-reading)Suggested reading - [Monitor Redpanda](../../monitoring/) ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) [Search all labs](/redpanda-labs) --- # Page 169: Scale Redpanda in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/k-scale-redpanda.md --- # Scale Redpanda in Kubernetes --- title: Scale Redpanda in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/k-scale-redpanda page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/k-scale-redpanda.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/k-scale-redpanda.adoc description: Learn how to scale a Redpanda cluster vertically to increase its resources and horizontally to add or remove brokers from a cluster. page-git-created-date: "2024-01-04" page-git-modified-date: "2025-05-06" support-status: supported --- You can scale a cluster both vertically (by increasing or decreasing the resources available to existing brokers) and horizontally (by adding or removing brokers from the cluster). ## [](#vertical-scaling)Vertical scaling Vertical scaling involves increasing or decreasing the amount of resources available to Redpanda brokers, referred to as scaling up or scaling down. Resources include hardware resources such as CPU cores, memory, and storage. To scale a Redpanda cluster vertically, see [Manage Pod Resources in Kubernetes](../k-manage-resources/). If your existing worker nodes have either too many resources or not enough resources, you may need to move Redpanda brokers to new worker nodes that meet your resource requirements. This process involves: - Making sure the new worker nodes are available. - Deleting each worker node individually. - Deleting the Pod’s PersistentVolumeClaim (PVC). - Ensuring that the PersistentVolume’s (PV) reclaim policy is set to `Retain` to make sure that you can roll back to the original worker node without losing data. > 💡 **TIP** > > For emergency scenarios in which a node unexpectedly fails or is decommissioned without warning, the PVCUnbinder can help protect your Redpanda data. For details, see [Enable the PVCUnbinder](../k-nodewatcher/). ## [](#horizontal-scaling)Horizontal scaling Horizontal scaling involves modifying the number of brokers in your cluster, either by adding new ones (scaling out) or removing existing ones (scaling in). In situations where the workload is variable, horizontal scaling allows for flexibility. You can scale out when demand is high and scale in when demand is low, optimizing resource usage and cost. > ⚠️ **CAUTION: Do not use autoscalers** > > Redpanda does not support Kubernetes autoscalers. Autoscalers rely on CPU and memory metrics for scaling decisions, which do not fully capture the complexities involved in scaling Redpanda clusters. Always manually scale your Redpanda clusters as described in this topic. Do not rely on Kubernetes autoscalers to scale your Redpanda brokers. Instead, prevent infrastructure-level autoscalers, such as Karpenter, from terminating nodes that host Redpanda Pods. For example, you can set the [`statefulset.podTemplate.annotations`](../../../reference/k-redpanda-helm-spec/#statefulset-podtemplate-annotations) field in the Redpanda Helm values, or the [`statefulset.podTemplate.annotations`](../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-podtemplate) field in the Redpanda custom resource to include: ```yaml karpenter.sh/do-not-disrupt: "true" ``` This annotation tells Karpenter not to disrupt the node on which the annotated Pod is running. This can help protect Redpanda brokers from unexpected shutdowns in environments that use Karpenter to manage infrastructure nodes. ### [](#scale-out)Scale out Scaling out involves adding more brokers to your Redpanda cluster. You may want to add more brokers to increase throughput, enhance high availability, and improve fault tolerance. Adding more brokers enables a more effective distribution of data across the cluster. This is particularly important when dealing with large datasets. To add Redpanda brokers to your cluster: 1. Ensure that you have one additional worker node for each Redpanda broker that you want to add. Each Redpanda broker requires its own dedicated worker node so that it has access to all resources. For more details, see [Kubernetes Cluster Requirements and Recommendations](../../../deploy/redpanda/kubernetes/k-requirements/). 2. If you use local PersistentVolumes (PV), ensure that your additional worker nodes have local disks available that meet the requirements of the configured StorageClass. See [Store the Redpanda Data Directory in PersistentVolumes](../storage/k-persistent-storage/). 3. If you have external access enabled, make sure that your new node has the necessary node ports open to external clients. See [Networking and Connectivity in Kubernetes](../networking/). 4. Verify that your cluster is in a healthy state: ```bash kubectl exec redpanda-0 --namespace -- rpk cluster health ``` 5. Increase the number of replicas in the Helm values: #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: statefulset: replicas: ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `replicas.yaml` ```yaml statefulset: replicas: ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values replicas.yaml --reuse-values ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set statefulset.replicas= ``` 6. Wait until the StatefulSet is rolled out: ```bash kubectl --namespace rollout status statefulset redpanda --watch ``` 7. Verify that your cluster is in a healthy state: ```bash kubectl exec redpanda-0 --namespace -- rpk cluster health ``` ### [](#scale-in)Scale in Scaling in is the process of removing brokers from your Redpanda cluster. You may want to remove brokers for cost reduction and resource optimization. To scale in a Redpanda cluster, follow the [instructions for decommissioning brokers in Kubernetes](../k-decommission-brokers/) to safely remove brokers from the Redpanda cluster. --- # Page 170: Manage Schemas with the Redpanda Operator **URL**: https://docs.redpanda.com/current/manage/kubernetes/k-schema-controller.md --- # Manage Schemas with the Redpanda Operator --- title: Manage Schemas with the Redpanda Operator latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/k-schema-controller page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/k-schema-controller.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/k-schema-controller.adoc description: Use the Schema resource to declaratively create and manage schemas as part of a Redpanda deployment in Kubernetes. page-git-created-date: "2024-12-03" page-git-modified-date: "2026-03-31" support-status: supported --- Use the Schema resource to declaratively create and manage schemas as part of a Redpanda deployment in Kubernetes. Each Schema resource maps to a schema in your Redpanda cluster, allowing you to define data structures, compatibility, and schema evolution in a declarative way. ## [](#prerequisites)Prerequisites Ensure you have the following: - **Kubectl**: Ensure the [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) command-line tool is installed and configured to communicate with your cluster. - **Redpanda cluster**: Ensure you have at least version v2.3.0-24.3.1 of the [Redpanda Operator](../../../deploy/redpanda/kubernetes/k-production-deployment/) and a Redpanda resource deployed and accessible. ## [](#create-a-schema)Create a schema 1. Define a schema using the Schema resource. Here’s a basic example configuration that defines an Avro schema: `schema.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Schema metadata: name: example-schema namespace: spec: cluster: clusterRef: name: schemaType: avro compatibilityLevel: Backward text: | { "type": "record", "name": "ExampleRecord", "fields": [ { "type": "string", "name": "field1" }, { "type": "int", "name": "field2" } ] } ``` Replace the following placeholders: - ``: The namespace in which to deploy the Schema resource. The Schema resource must be deployed in the same namespace as the Redpanda resource defined in `clusterRef.name`. - ``: The name of the Redpanda resource that defines the Redpanda cluster to which you want to upload the schema. 2. Apply the manifest: ```bash kubectl apply -f schema.yaml --namespace ``` When the manifest is applied, the schema will be created in your Redpanda cluster. 3. Check the status of the Schema resource using the following command: ```bash kubectl get schema example-schema --namespace ``` 4. Create an alias to simplify running `rpk` commands on your cluster: ```bash alias internal-rpk="kubectl --namespace exec -i -t -c redpanda -- rpk" ``` Replace `` with the name of a Pod that’s running Redpanda. 5. Verify that the schema was created in Redpanda: ```bash internal-rpk registry subject list ``` You should see `example-schema` in the output. ## [](#schema-examples)Schema examples These examples demonstrate how to define schemas in Avro, Protobuf, and JSON Schema formats. ### [](#create-an-avro-schema)Create an Avro schema `avro-schema.yaml` ```yaml # This manifest creates an Avro schema named "customer-profile" in the "basic" cluster. # The schema defines a record with fields for customer ID, name, and age. --- apiVersion: cluster.redpanda.com/v1alpha2 kind: Schema metadata: name: customer-profile spec: cluster: clusterRef: name: basic schemaType: avro compatibilityLevel: Backward text: | { "type": "record", "name": "CustomerProfile", "fields": [ { "type": "string", "name": "customer_id" }, { "type": "string", "name": "name" }, { "type": "int", "name": "age" } ] } ``` ### [](#create-a-protobuf-schema)Create a Protobuf schema `proto-schema.yaml` ```yaml # This manifest creates a Protobuf schema named "product-catalog" in the "basic" cluster. # The schema defines a message "Product" with fields for product ID, name, price, and category. --- apiVersion: cluster.redpanda.com/v1alpha2 kind: Schema metadata: name: product-catalog spec: cluster: clusterRef: name: basic schemaType: protobuf compatibilityLevel: Backward text: | syntax = "proto3"; message Product { int32 product_id = 1; string product_name = 2; double price = 3; string category = 4; } ``` ### [](#create-a-json-schema)Create a JSON schema `json-schema.yaml` ```yaml # This manifest creates a JSON schema named "order-event" in the "basic" cluster. # The schema requires an "order_id" (string) and a "total" (number) field, with no additional properties allowed. --- apiVersion: cluster.redpanda.com/v1alpha2 kind: Schema metadata: name: order-event spec: cluster: clusterRef: name: basic schemaType: json compatibilityLevel: None text: | { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "order_id": { "type": "string" }, "total": { "type": "number" } }, "required": ["order_id", "total"], "additionalProperties": false } ``` ## [](#configuration)Configuration The Schema resource in Redpanda offers various options to customize and control schema behavior. This section covers schema compatibility, schema references, and schema types, providing a detailed guide on using each of these features to maintain data integrity, manage dependencies, and facilitate schema evolution. You can find all configuration options for the Schema resource in the [CRD reference](../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-schema). `schema.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Schema metadata: name: (1) namespace: (2) spec: cluster: clusterRef: name: (3) schemaType: avro (4) compatibilityLevel: Backward (5) references: [] (6) text: | (7) { "type": "record", "name": "test", "fields": [ { "type": "string", "name": "field1" }, { "type": "int", "name": "field2" } ] } ``` | 1 | Subject name: The name of the subject for the schema. When data formats are updated, a new version of the schema can be registered under the same subject, enabling backward and forward compatibility. | | --- | --- | | 2 | Namespace: The namespace in which to deploy the Schema resource. The Schema resource must be deployed in the same namespace as the Redpanda resource defined in clusterRef.name. | | 3 | Cluster name: The name of the Redpanda resource that defines the Redpanda cluster to which you want to upload the schema. | | 4 | Compatibility level: Defines the compatibility level for the schema. Options are Backward (default), BackwardTransitive, Forward, ForwardTransitive Full, FullTransitive, or None. See Choose a compatibility mode. | | 5 | Schema type: Specifies the type of the schema. Options are avro (default) or protobuf. For JSON Schema, include "$schema": in the text to indicate the JSON Schema draft version. See Choose a schema type. | | 6 | References: Any references you want to add to other schemas. If no references are needed, this can be an empty list (default). See Use schema references. | | 7 | Schema body: The body of the schema, which defines the data structure. | ### [](#choose-a-schema-type)Choose a schema type Redpanda’s Schema Registry supports the following schema types: - **Avro**: A widely used serialization format in event-driven architectures. - **Protobuf**: Popular for defining data structures in gRPC APIs and efficient data serialization. - **JSON Schema**: Dynamic, schema-based validation for JSON documents. If no type is specified, Redpanda defaults to Avro. ### [](#choose-a-compatibility-mode)Choose a compatibility mode Compatibility modes determine how schema versions within a subject can evolve without breaking existing data consumers. Redpanda supports the following compatibility levels: - `None`: Disables compatibility checks, allowing any schema change. - `Backward`: Consumers using the new schema (for example, version 10) can read data from producers using the previous schema (for example, version 9). - `BackwardTransitive`: Enforces backward compatibility across all versions, not just the latest. - `Forward`: Consumers using the previous schema (for example, version 9) can read data from producers using the new schema (for example, version 10). - `ForwardTransitive`: Ensures forward compatibility across all schema versions. - `Full`: Combines backward and forward compatibility, requiring that changes maintain compatibility in both directions. A new schema and the previous schema (for example, versions 10 and 9) are both backward and forward-compatible with each other. - `FullTransitive`: Enforces full compatibility across all schema versions. For example, to set full compatibility, configure the Schema resource with: ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Schema metadata: name: fully-compatible-schema namespace: redpanda spec: cluster: clusterRef: name: basic schemaType: avro compatibilityLevel: Full text: | { "type": "record", "name": "ExampleRecord", "fields": [ { "type": "string", "name": "field1" }, { "type": "int", "name": "field2" } ] } ``` Compatibility settings are essential for maintaining data consistency, especially when updating schemas over time. ### [](#use-schema-references)Use schema references For complex data structures, you can define schema references that allow one schema to reference another, enabling modular and reusable schema components. Schema references are helpful for shared data structures across topics like product information or user profiles, reducing redundancy. > 📝 **NOTE** > > This feature is supported for Avro and Protobuf schemas. Define a schema reference using the `references` field. The reference includes the name, subject, and version of the referenced schema: ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Schema metadata: name: order-schema namespace: redpanda spec: cluster: clusterRef: name: basic references: - name: product-schema subject: product version: 1 text: | { "type": "record", "name": "Order", "fields": [ { "name": "product", "type": "Product" } ] } ``` ## [](#update-a-schema)Update a schema To update a schema, modify the Schema resource and apply the changes: ```bash kubectl apply -f .yaml --namespace ``` ## [](#check-schema-version)Check schema version Ensure the schema has been versioned by running: ```bash kubectl get schema --namespace ``` You can also check specific versions of the schema: ```bash internal-rpk registry schema get --id 1 internal-rpk registry schema get --id 2 ``` ## [](#delete-a-schema)Delete a schema To delete a schema, use the following command: ```bash kubectl delete schema --namespace redpanda ``` Verify that the schema was deleted by checking the Redpanda Schema Registry: ```bash internal-rpk registry subject list ``` ## [](#suggested-reading)Suggested reading For more details on using schemas in Redpanda, see: - [Schema Registry](../../schema-reg/) - [Manage Schema Registry ACLs (Operator)](../security/authentication/k-schema-registry-acls/) - [Schema Registry Authorization](../../schema-reg/schema-reg-authorization/) --- # Page 171: Monitor in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/monitoring.md --- # Monitor in Kubernetes --- title: Monitor in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/monitoring/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/monitoring/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/monitoring/index.adoc description: Find topics about how to monitor Redpanda deployments in Kubernetes. page-git-created-date: "2023-11-01" page-git-modified-date: "2024-02-26" support-status: supported --- Find topics about how to monitor Redpanda deployments in Kubernetes. - [Monitor Redpanda in Kubernetes](k-monitor-redpanda/) Monitor the health of your system to predict issues and optimize performance. - [Monitor Kafka Connect in Kubernetes](k-monitor-connectors/) Monitor the health of Kafka Connect using managed connector metrics. --- # Page 172: Monitor Kafka Connect in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/monitoring/k-monitor-connectors.md --- # Monitor Kafka Connect in Kubernetes --- title: Monitor Kafka Connect in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/monitoring/k-monitor-connectors page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/monitoring/k-monitor-connectors.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/monitoring/k-monitor-connectors.adoc description: Monitor the health of Kafka Connect using managed connector metrics. page-git-created-date: "2024-01-04" page-git-modified-date: "2025-07-31" support-status: supported --- You can monitor the health of Kafka Connect with metrics that are exported through a Prometheus endpoint at the default port 9404. You can use Grafana to visualize the metrics and set up alerts. > 📝 **NOTE: Community** > > **The Connectors Helm chart is a community-supported artifact**. Redpanda Data does not provide enterprise support for this chart. For support, reach out to the Redpanda team in [Redpanda Community Slack](https://redpanda.com/slack). ## [](#prerequisites)Prerequisites - A Kubernetes cluster with `kubectl` installed at least version 1.27.0-0. To check if you have `kubectl` installed: ```bash kubectl version --client ``` - [Helm](https://helm.sh/docs/intro/install/) installed with at least version 3.10.0. To check if you have Helm installed: ```bash helm version ``` - [Kafka Connect deployed](../../../../deploy/kafka-connect/k-deploy-kafka-connect/) with monitoring enabled. ## [](#limitations)Limitations The connectors dashboard renders metrics that are exported by managed connectors. However, when a connector does not create a task (for example, an empty topic list), the dashboard will not show metrics for that connector. ## [](#verify-monitoring-is-enabled)Verify monitoring is enabled Before configuring Prometheus, verify that Kafka Connect is exposing metrics: 1. Check that the connectors service exposes port 9404: ```bash kubectl get service --namespace -connectors ``` Expected output should include `9404/TCP`: ```bash NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE redpanda-connectors ClusterIP 10.96.78.129 8083/TCP,9404/TCP 1h ``` 2. Test that metrics are being exported: ```bash POD_NAME=$(kubectl get pod -l app.kubernetes.io/name=connectors --namespace -o jsonpath='{.items[0].metadata.name}') kubectl exec $POD_NAME --namespace -- curl -s localhost:9404/metrics | head -10 ``` Expected output should show Prometheus metrics: ```bash # HELP jmx_exporter_build_info A metric with a constant '1' value labeled with the version of the JMX exporter. # TYPE jmx_exporter_build_info gauge jmx_exporter_build_info{version="0.20.0",name="jmx_prometheus_javaagent",} 1.0 # HELP kafka_producer_iotime_total Kafka producer JMX metric type producer # TYPE kafka_producer_iotime_total gauge ``` ## [](#configure-prometheus)Configure Prometheus [Prometheus](https://prometheus.io/) is a system monitoring and alerting tool. It collects and stores metrics as time-series data identified by a metric name and key/value pairs. To configure Prometheus to monitor Kafka Connect metrics in Kubernetes, you can use the [Prometheus Operator](https://prometheus-operator.dev/). The Prometheus Operator provides Kubernetes-native deployment and management of Prometheus and related monitoring components. 1. Follow the steps to [deploy the Prometheus Operator](https://prometheus-operator.dev/docs/getting-started/installation/). 2. Configure the Prometheus resource to target your Pods running Kafka Connect: `prometheus.yaml` ```yaml apiVersion: monitoring.coreos.com/v1 kind: Prometheus metadata: name: prometheus namespace: spec: serviceAccountName: prometheus # To select PodMonitors in all namespaces, omit podMonitorNamespaceSelector or set to an empty selector: podMonitorNamespaceSelector: {} podMonitorSelector: matchLabels: app.kubernetes.io/name: connectors resources: requests: memory: 400Mi enableAdminAPI: false ``` - `podMonitorNamespaceSelector.matchLabels.name`: The namespace where Redpanda is deployed. - `podMonitorSelector.matchLabels.app.kubernetes.io/name`: Must match the label on your connectors Pods (default is `connectors`). 3. Deploy the standalone Kafka Connect chart with monitoring enabled. This will automatically create a PodMonitor resource: ### --values `connectors-monitoring.yaml` ```yaml monitoring: enabled: true scrapeInterval: 30s ``` ```bash helm upgrade --install redpanda-connectors redpanda/connectors --namespace --create-namespace \ --values connectors-monitoring.yaml ``` ### --set ```bash helm upgrade --install redpanda-connectors redpanda/connectors \ --namespace \ --create-namespace \ --set monitoring.enabled=true \ --set monitoring.scrapeInterval=30s ``` 4. Wait until the connectors deployment is ready: ```bash kubectl --namespace rollout status deployment -connectors --watch ``` 5. Verify that the PodMonitor was automatically created: ```bash kubectl get podmonitor --namespace ``` Expected output: ```bash NAME AGE redpanda-connectors 30s ``` 6. Find the Prometheus Service name: ```bash kubectl get svc -n | rg -i 'prometheus.*prometheus' || true ``` 1. Port-forward using the discovered service name: ```bash kubectl port-forward svc/ 9090:9090 --namespace ``` 2. Navigate to [http://localhost:9090/targets](http://localhost:9090/targets) to verify that the Kafka Connect targets are being scraped. ## [](#important-metrics-to-monitor)Important metrics to monitor The most important Kafka Connect metrics to monitor with alerts are: - **Connector task status**: `kafka_connect_connector_status` and `kafka_connect_task_status` - **Connector task failures**: `kafka_connect_task_error_count` - **Consumer lag**: `kafka_consumer_lag_max` (for sink connectors) - **Producer record send rate**: `kafka_producer_record_send_rate` (for source connectors) - **Error rates**: `kafka_connect_connector_failed_task_count` ### [](#example-queries)Example queries Important Prometheus queries for monitoring: ```promql # Failed connector tasks kafka_connect_connector_failed_task_count > 0 # Connector status (should be "running") kafka_connect_connector_status{status!="running"} # High consumer lag kafka_consumer_lag_max > 1000 # Low throughput for source connectors rate(kafka_producer_record_send_total[5m]) < 1 ``` ## [](#import-the-grafana-dashboard)Import the Grafana dashboard You can use [Grafana](https://grafana.com/oss/grafana/) to query, visualize, and generate alerts for metrics. Redpanda provides a [Grafana dashboard for connectors](https://github.com/redpanda-data/observability/blob/main/grafana-dashboards/Connectors.json). To create and use the Grafana dashboard to gather telemetry for your managed connectors, import the connectors dashboard JSON file (`Connectors.json`). ## [](#managed-connector-metrics)Managed connector metrics You can monitor the following metrics for your Redpanda managed connectors. ### [](#connector-tasks)Connector tasks Number of tasks for a specific connector, grouped by status: - `running` - Tasks that are healthy and running. - `paused` - Tasks that were paused by a user request. - `failed` - Tasks that failed during execution. Expect only `running` and `paused` tasks. Create an alert for failed tasks. * * * ### [](#sink-connector-lag)Sink connector lag The number of records still to be processed by a connector. This metric is emitted for sink connectors only (`last_offset` - `current_offset`). For newly-created connectors, the metric is high until the connector sinks all historical data. Expect the lag not to increase over time. * * * ### [](#mm2-replication-latency)MM2 replication latency Age of the last record written to the target cluster by the MirrorMaker 2 connector. This metric is emitted for each partition. For newly-created connectors, the metric is high until the connector processes all historical data. Expect the latency to not increase over time. * * * ### [](#count-of-the-records-sent-to-target-by-topic)Count of the records sent to target (by topic) Count of records sent to the cluster by source connectors for each topic. * * * ### [](#redpanda-consumer-latency)Redpanda consumer latency The Redpanda consumer fetch latency for sink connectors. * * * ### [](#redpanda-producer-latency)Redpanda producer latency The Redpanda producer request latency for source connectors. * * * ### [](#bytes-in)Bytes in Bytes per second (throughput) of data from Redpanda to managed connectors. * * * ### [](#bytes-out)Bytes out Bytes per second (throughput) of data from managed connectors to Redpanda. * * * ### [](#record-error-rate)Record error rate - `record errors` - Total number of record errors seen in connector tasks. - `record failures` - Total number of record failures seen in connector tasks. - `record skipped` - Total number of records skipped by connector tasks. * * * ### [](#producer-record-rate)Producer record rate - `record sent` - Total number of records sent by connector producers. - `record retry` - Total number of records sent retries by connector producers. * * * ### [](#producer-record-error-rate)Producer record error rate Rate of producer errors when producing records to Redpanda. ## [](#connectors-support)Connectors support Redpanda monitors the managed connector infrastructure 24/7 to ensure the service is available. The monitoring of individual connectors is expected to be done by the end user. If an incident occurs, Redpanda Support follows an incident response process to quickly mitigate it. ### [](#consumer-lag)Consumer lag A connector generally performs lower than expected when it is underprovisioned. Increase the number of `Max Tasks` (`tasks.max`) in the connector configuration for a given number of instances and instance types. Additional reasons for increasing consumer lag: - Available memory for the connector is too low. - Insufficient number of instances. Autoscaling is based on the total running task count for connectors. #### [](#sink-connector-lag-rate-metric)Sink connector lag rate metric The sink connector lag rate metric shows the difference between a topic max offset rate and a sink connector committed offsets rate. When the message rate for the topic is greater than the sink connector consume rate, the lag rate metric is positive. You should expect the metric to drop below 0 regularly, which means progress is being made and the connector is able to catch up with the produce rate. Contact [Redpanda support](https://support.redpanda.com/hc/en-us/requests/new) to align connector instances with your needs. ### [](#connector-in-a-failed-state)Connector in a failed state If a connector is in a failed state, first check the connector configuration and logs. If a connector fails, it typically occurs immediately after a configuration change. - Check exception details and stacktrace by clicking **Show Error**. - Check connector logs in the **Logs** tab. - Restart the connector by clicking **Restart**. The following table lists the most frequent connector configuration issues that cause a failed status: | Issue | Action | | --- | --- | | External system connectivity issue | Check that the external system is up and running.Check that the external system is available.Check the connector configuration to confirm that external system properties are correct (URL, table name, bucket name). | | External system authentication issue | Check that the given account exists in an external system.Check the credentials defined in the connector configuration. | | Incorrect topic name or topic name pattern | Check that the expected topic is created.Check that the given topic name pattern matches at least one topic name. | | Out Of Memory error | Change the connector configuration, lower the connector cache buffer size, and decrease the maximum records allowed in a batch.Limit the number of topics set in Topics to export (topics) or Topics regex (topics.regex) properties.Decrease Max Tasks (tasks.max) in the connector configuration.Contact Redpanda support. | ## [](#next-steps)Next steps - [Create and manage Kafka Connect connectors](../../k-manage-connectors/) - Set up Grafana dashboards using the [Redpanda connectors dashboard](https://github.com/redpanda-data/observability/blob/main/grafana-dashboards/Connectors.json) - Configure alerting rules for critical connector metrics - Learn about [scaling connector deployments](../../../../deploy/kafka-connect/k-deploy-kafka-connect/#scaling) ## Suggested labs - [Owl Shop Example Application in Docker](/redpanda-labs/docker-compose/owl-shop/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) [Search all labs](/redpanda-labs) --- # Page 173: Monitor Redpanda in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/monitoring/k-monitor-redpanda.md --- # Monitor Redpanda in Kubernetes --- title: Monitor Redpanda in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/monitoring/k-monitor-redpanda page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/monitoring/k-monitor-redpanda.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/monitoring/k-monitor-redpanda.adoc description: Monitor the health of your system to predict issues and optimize performance. page-git-created-date: "2024-01-04" page-git-modified-date: "2026-01-06" support-status: supported --- Redpanda exports metrics through two endpoints on the Admin API port (default: 9644) for you to monitor system health and optimize system performance. > 💡 **TIP** > > Use [/public\_metrics](../../../../reference/public-metrics-reference/) for your primary dashboards for monitoring system health. These metrics have low cardinality and are designed for customer consumption, with aggregated labels for better performance. **Public metrics use the `redpanda_` prefix.** > > Use [/metrics](../../../../reference/internal-metrics-reference/) for detailed analysis and debugging. These metrics can have high cardinality with thousands of series, providing granular operational insights. **Internal metrics use the `vectorized_` prefix.** The [`/metrics`](../../../../reference/internal-metrics-reference/) endpoint is a legacy endpoint that includes many internal metrics that are unnecessary for a typical Redpanda user to monitor. The `/metrics` endpoint is also referred to as the 'internal metrics' endpoint, and Redpanda recommends that you use it for development, testing, and analysis. Alternatively, the [`/public_metrics`](../../../../reference/public-metrics-reference/) endpoint provides a smaller set of important metrics that can be queried and ingested more quickly and inexpensively. > 📝 **NOTE** > > To maximize monitoring performance by minimizing the cardinality of data, some metrics are exported when their underlying features are in use, and are not exported when not in use. For example, a metric for consumer groups, [`redpanda_kafka_consumer_group_committed_offset`](../../../../reference/public-metrics-reference/#redpanda_kafka_consumer_group_committed_offset), is not exported when no groups are registered. > > When monitoring internal metrics, consider enabling [aggregate\_metrics](../../../../reference/properties/cluster-properties/#aggregate_metrics) to reduce the cardinality of data to monitor. This topic covers the following about monitoring Redpanda metrics: - [Configure Prometheus to monitor Redpanda metrics](#configure-prometheus) - [Generate Grafana dashboard](#generate-grafana-dashboard) - [Learn from examples in the Redpanda monitoring examples repository](#use-redpanda-monitoring-examples) - [Metrics and queries to monitor for system performance and health](#monitor-for-performance-and-health) - [References of public and internal metrics](#references) ## [](#configure-prometheus)Configure Prometheus [Prometheus](https://prometheus.io/) is a system monitoring and alerting tool. It collects and stores metrics as time-series data identified by a metric name and key/value pairs. To configure Prometheus to monitor Redpanda metrics in Kubernetes, you can use the [Prometheus Operator](https://prometheus-operator.dev/): 1. Follow the steps to [deploy the Prometheus Operator](https://prometheus-operator.dev/docs/getting-started/installation/). Make sure to configure the Prometheus resource to target your Redpanda cluster: `prometheus.yaml` ```yaml apiVersion: monitoring.coreos.com/v1 kind: Prometheus metadata: name: prometheus spec: serviceAccountName: prometheus serviceMonitorNamespaceSelector: matchLabels: name: serviceMonitorSelector: matchLabels: app.kubernetes.io/name: redpanda resources: requests: memory: 400Mi enableAdminAPI: false ``` - `serviceMonitorNamespaceSelector.matchLabels.name`: The namespace in which you will deploy Redpanda. The Prometheus Operator looks for ServiceMonitor resources in this namespace. - `serviceMonitorSelector.matchLabels.app.kubernetes.io/name`: The value of `fullnameOverride` in your Redpanda Helm chart. The default is `redpanda`. The Redpanda Helm chart creates the ServiceMonitor resource with this label. 2. Deploy Redpanda with monitoring enabled to deploy the ServiceMonitor resource: ### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: monitoring: enabled: true scrapeInterval: 30s ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ### Helm #### --values `prometheus-monitoring.yaml` ```yaml monitoring: enabled: true scrapeInterval: 30s ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values prometheus-monitoring.yaml --reuse-values ``` #### --set ```bash helm upgrade --install redpanda redpanda/redpanda \ --namespace \ --create-namespace \ --set monitoring.enabled=true \ --set monitoring.scrapeInterval="30s" ``` 3. Wait until all Pods are running: ```bash kubectl -n rollout status statefulset redpanda --watch ``` 4. Ensure that the ServiceMonitor was deployed: ```bash kubectl get servicemonitor --namespace ``` 5. Ensure that you’ve [exposed the Prometheus Service](https://prometheus-operator.dev/docs/user-guides/getting-started/#exposing-the-prometheus-service). 6. Expose the Prometheus server to your localhost: ```bash kubectl port-forward svc/prometheus 9090 ``` 7. [Open Prometheus](http://localhost:9090/graph), and see that Prometheus is scraping metrics from your Redpanda endpoints. ## [](#generate-grafana-dashboard)Generate Grafana dashboard [Grafana](https://grafana.com/oss/grafana/) is a tool to query, visualize, and generate alerts for metrics. Redpanda supports generating Grafana dashboards from its metrics endpoints with `rpk generate grafana-dashboard`. To generate a comprehensive Grafana dashboard, run the following command and pipe the output to a file that can be imported into Grafana: ```bash rpk generate grafana-dashboard --datasource --metrics-endpoint > ``` - `` is the name of the Prometheus data source configured in your Grafana instance. - `` is the address to a Redpanda broker’s metrics endpoint (public or internal). - For `/public_metrics`, for example, run the following command: ```bash rpk generate grafana-dashboard \ --datasource prometheus \ --metrics-endpoint :9644/public_metrics > redpanda-dashboard.json ``` - For `/metrics`, for example, run the following command: ```bash rpk generate grafana-dashboard \ --datasource prometheus \ --metrics-endpoint :9644/metrics > redpanda-dashboard.json ``` For details about the command, see [`rpk generate grafana-dashboard`](../../../../reference/rpk/rpk-generate/rpk-generate-grafana-dashboard/). In Grafana, import the generated JSON file to create a dashboard. Out of the box, Grafana generates panels tracking latency for 50%, 95%, and 99% (based on the maximum latency set), throughput, and error segmentation by type. To use the imported dashboard to create new panels: 1. Click **+** in the left pane, and select **Add a new panel**. 2. On the **Query** tab, select **Prometheus** data source. 3. Decide which metric you want to monitor, click **Metrics browser**, and type `redpanda` to show available public metrics (or `vectorized` for internal metrics) from the Redpanda cluster. ## [](#use-redpanda-monitoring-examples)Use Redpanda monitoring examples For hands-on learning, Redpanda provides a repository with examples of monitoring Redpanda with Prometheus and Grafana: [redpanda-data/observability](https://github.com/redpanda-data/observability). ![Example Redpanda Ops Dashboard^](https://github.com/redpanda-data/observability/blob/main/docs/images/Ops%20Dashboard.png?raw=true) It includes [example Grafana dashboards](https://github.com/redpanda-data/observability#grafana-dashboards) and a [sandbox environment](https://github.com/redpanda-data/observability#sandbox-environment) in which you launch a Dockerized Redpanda cluster and create a custom workload to monitor with dashboards. ## [](#monitor-for-performance-and-health)Monitor for performance and health This section provides guidelines and example queries using Redpanda’s public metrics to optimize your system’s performance and monitor its health. To help detect and mitigate anomalous system behaviors, capture baseline metrics of your healthy system at different stages (at start-up, under high load, in steady state) so you can set thresholds and alerts according to those baselines. > 💡 **TIP** > > For counter type metrics, a broker restart causes the count to reset to zero in tools like Prometheus and Grafana. Redpanda recommends wrapping counter metrics in a rate query to account for broker restarts, for example: > > ```promql > rate(redpanda_kafka_records_produced_total[5m]) > ``` ### [](#redpanda-architecture)Redpanda architecture Understanding the unique aspects of Redpanda’s architecture and data path can improve your performance, debugging, and tuning skills: - Redpanda replicates partitions across brokers in a cluster using [Raft](https://raft.github.io/), where each partition is a Raft consensus group. A message written from the Kafka API flows down to the Raft implementation layer that eventually directs it to a broker to be stored. Metrics about the Raft layer can reveal the health of partitions and data flowing within Redpanda. - Redpanda is designed with a [thread-per-core](https://docs.redpanda.com/current/reference/glossary/#thread-per-core) model that it implements with the [Seastar](https://seastar.io/) library. With each application thread pinned to a CPU core, when observing or analyzing the behavior of a specific application, monitor the relevant metrics with the label for the specific [shard](https://docs.redpanda.com/current/reference/glossary/#shard), if available. ### [](#infrastructure-resources)Infrastructure resources The underlying infrastructure of your system should have sufficient margins to handle peaks in processing, storage, and I/O loads. Monitor infrastructure health with the following queries. #### [](#cpu-usage)CPU usage For the total CPU uptime, monitor [`redpanda_uptime_seconds_total`](../../../../reference/public-metrics-reference/#redpanda_uptime_seconds_total). Monitoring its rate of change with the following query can help detect unexpected dips in uptime: ```promql rate(redpanda_uptime_seconds_total[5m]) ``` For the total CPU busy (non-idle) time, monitor [`redpanda_cpu_busy_seconds_total`](../../../../reference/public-metrics-reference/#redpanda_cpu_busy_seconds_total). To detect unexpected idling, you can query the rate of change as a fraction of the shard that is in use at a given point in time. ```promql rate(redpanda_cpu_busy_seconds_total[5m]) ``` > 💡 **TIP** > > While CPU utilization at the host-level might appear high (for example, 99-100% utilization) when I/O events like message arrival occur, the actual Redpanda process utilization is likely low. System-level metrics such as those provided by the `top` command can be misleading. > > This high host-level CPU utilization happens because Redpanda uses Seastar, which runs event loops on every core (also referred to as a _reactor_), constantly polling for the next task. This process never blocks and will increment clock ticks. It doesn’t necessarily mean that Redpanda is busy. > > Use [`redpanda_cpu_busy_seconds_total`](../../../../reference/public-metrics-reference/#redpanda_cpu_busy_seconds_total) to monitor the actual Redpanda CPU utilization. When it indicates close to 100% utilization over a given period of time, make sure to also monitor produce and consume [latency](#latency) as they may then start to increase as a result of resources becoming overburdened. #### [](#memory-availability-and-pressure)Memory availability and pressure To monitor memory, use [`redpanda_memory_available_memory`](../../../../reference/public-metrics-reference/#redpanda_memory_available_memory), which includes both free memory and reclaimable memory from the batch cache. This provides a more accurate picture than using allocated memory alone, since allocated does not include reclaimable cache memory. To monitor the fraction of memory available: ```promql min(redpanda_memory_available_memory / (redpanda_memory_free_memory + redpanda_memory_allocated_memory)) ``` To monitor memory pressure (fraction of memory being used), which may be more intuitive for alerting: ```promql min(redpanda_memory_available_memory / redpanda_memory_allocated_memory) ``` You can also monitor the lowest available memory available since the process started to understand historical memory pressure: ```promql min(redpanda_memory_available_memory_low_water_mark / (redpanda_memory_free_memory + redpanda_memory_allocated_memory)) ``` #### [](#disk-used)Disk used To monitor the fraction of disk consumed, use a formula with [`redpanda_storage_disk_free_bytes`](../../../../reference/public-metrics-reference/#redpanda_storage_disk_free_bytes) and [`redpanda_storage_disk_total_bytes`](../../../../reference/public-metrics-reference/#redpanda_storage_disk_total_bytes): ```promql 1 - (sum(redpanda_storage_disk_free_bytes) / sum(redpanda_storage_disk_total_bytes)) ``` Also monitor [`redpanda_storage_disk_free_space_alert`](../../../../reference/public-metrics-reference/#redpanda_storage_disk_free_space_alert) for an alert when available disk space is low or degraded. #### [](#iops)IOPS For read and write I/O operations per second (IOPS), monitor the [`redpanda_io_queue_total_read_ops`](../../../../reference/public-metrics-reference/#redpanda_io_queue_total_read_ops) and [`redpanda_io_queue_total_write_ops`](../../../../reference/public-metrics-reference/#redpanda_io_queue_total_write_ops) counters: ```promql rate(redpanda_io_queue_total_read_ops[5m]), rate(redpanda_io_queue_total_write_ops[5m]) ``` ### [](#throughput)Throughput While maximizing the rate of messages moving from producers to brokers then to consumers depends on tuning each of those components, the total throughput of all topics provides a system-level metric to monitor. When you observe abnormal, unhealthy spikes or dips in producer or consumer throughput, look for correlation with changes in the number of active connections ([`redpanda_rpc_active_connections`](../../../../reference/public-metrics-reference/#redpanda_rpc_active_connections)) and logged errors to drill down to the root cause. The total throughput of a cluster can be measured by the producer and consumer rates across all topics. To observe the total producer and consumer rates of a cluster, monitor [`redpanda_rpc_received_bytes`](../../../../reference/public-metrics-reference/#redpanda_rpc_received_bytes) for producer traffic and [`redpanda_rpc_sent_bytes`](../../../../reference/public-metrics-reference/#redpanda_rpc_sent_bytes) for consumer traffic. Filter both metrics using the `redpanda_server` label with the value `kafka`. #### [](#producer-throughput)Producer throughput For the produce rate, create a query to get the produce rate across all topics: ```promql rate(redpanda_rpc_received_bytes{redpanda_server="kafka"}[$__rate_interval]) ``` #### [](#consumer-throughput)Consumer throughput For the consume rate, create a query to get the total consume rate across all topics: ```promql rate(redpanda_rpc_sent_bytes{redpanda_server="kafka"}[$__rate_interval]) ``` #### [](#identify-high-throughput-clients)Identify high-throughput clients Use [`rpk cluster connections list`](../../../../reference/rpk/rpk-cluster/rpk-cluster-connections-list/) or the [ListKafkaConnections](/api/doc/admin/v2/operation/operation-redpanda-core-admin-v2-clusterservice-listkafkaconnections) endpoint in Admin API to identify which client connections are driving the majority of, or the change in, the produce or consume throughput for a cluster. For example, to list connections with a current produce throughput greater than 1MB, run: ##### rpk ```bash rpk cluster connections list --filter-raw="recent_request_statistics.produce_bytes > 1000000" --order-by="recent_request_statistics.produce_bytes desc" ``` ```bash UID STATE USER CLIENT-ID IP:PORT NODE SHARD OPEN-TIME IDLE PROD-TPUT/SEC FETCH-TPUT/SEC REQS/MIN b20601a3-624c-4a8c-ab88-717643f01d56 OPEN UNAUTHENTICATED perf-producer-client 127.0.0.1:55012 0 0 9s 0s 78.9MB 0B 292 ``` ##### curl ```bash curl -s -X POST "localhost:9644/redpanda.core.admin.v2.ClusterService/ListKafkaConnections" --header "Content-Type: application/json" --data '{"filter":"recent_request_statistics.produce_bytes > 1000000", "order_by":"recent_request_statistics.produce_bytes desc"}' | jq ``` Show example API response ```bash { "connections": [ { "nodeId": 0, "shardId": 0, "uid": "b20601a3-624c-4a8c-ab88-717643f01d56", "state": "KAFKA_CONNECTION_STATE_OPEN", "openTime": "2025-10-15T14:15:15.755065000Z", "closeTime": "1970-01-01T00:00:00.000000000Z", "authenticationInfo": { "state": "AUTHENTICATION_STATE_UNAUTHENTICATED", "mechanism": "AUTHENTICATION_MECHANISM_UNSPECIFIED", "userPrincipal": "" }, "listenerName": "", "tlsInfo": { "enabled": false }, "source": { "ipAddress": "127.0.0.1", "port": 55012 }, "clientId": "perf-producer-client", "clientSoftwareName": "apache-kafka-java", "clientSoftwareVersion": "3.9.0", "transactionalId": "my-tx-id", "groupId": "", "groupInstanceId": "", "groupMemberId": "", "apiVersions": { "18": 4, "22": 3, "3": 12, "24": 3, "0": 7 }, "idleDuration": "0s", "inFlightRequests": { "sampledInFlightRequests": [ { "apiKey": 0, "inFlightDuration": "0.000406892s" } ], "hasMoreRequests": false }, "totalRequestStatistics": { "produceBytes": "78927173", "fetchBytes": "0", "requestCount": "4853", "produceBatchCount": "4849" }, "recentRequestStatistics": { "produceBytes": "78927173", "fetchBytes": "0", "requestCount": "4853", "produceBatchCount": "4849" } } ] } ``` You can adjust the filter and sorting criteria as necessary. ### [](#latency)Latency Latency should be consistent between produce and fetch sides. It should also be consistent over time. Take periodic snapshots of produce and fetch latencies, including at upper percentiles (95%, 99%), and watch out for significant changes over a short duration. In Redpanda, the latency of produce and fetch requests includes the latency of inter-broker RPCs that are born from Redpanda’s internal implementation using Raft. #### [](#kafka-consumer-latency)Kafka consumer latency To monitor Kafka consumer request latency, use the [`redpanda_kafka_request_latency_seconds`](../../../../reference/public-metrics-reference/#redpanda_kafka_request_latency_seconds) histogram with the label `redpanda_request="consume"`. For example, create a query for the 99th percentile: ```promql histogram_quantile(0.99, sum(rate(redpanda_kafka_request_latency_seconds_bucket{redpanda_request="consume"}[5m])) by (le, provider, region, instance, namespace, pod)) ``` You can monitor the rate of Kafka consumer requests using `redpanda_kafka_request_latency_seconds_count` with the `redpanda_request="consume"` label: rate(redpanda\_kafka\_request\_latency\_seconds\_count{redpanda\_request="consume"}\[5m\]) #### [](#kafka-producer-latency)Kafka producer latency To monitor Kafka producer request latency, use the [`redpanda_kafka_request_latency_seconds`](../../../../reference/public-metrics-reference/#redpanda_kafka_request_latency_seconds) histogram with the `redpanda_request="produce"` label. For example, create a query for the 99th percentile: ```promql histogram_quantile(0.99, sum(rate(redpanda_kafka_request_latency_seconds_bucket{redpanda_request="produce"}[5m])) by (le, provider, region, instance, namespace, pod)) ``` You can monitor the rate of Kafka producer requests with `redpanda_kafka_request_latency_seconds_count` with the `redpanda_request="produce"` label: ```promql rate(redpanda_kafka_request_latency_seconds_count{redpanda_request="produce"}[5m]) ``` #### [](#internal-rpc-latency)Internal RPC latency To monitor Redpanda internal RPC latency, use the [`redpanda_rpc_request_latency_seconds`](../../../../reference/public-metrics-reference/#redpanda_rpc_request_latency_seconds) histogram with the `redpanda_server="internal"` label. For example, create a query for the 99th percentile latency: ```promql histogram_quantile(0.99, (sum(rate(redpanda_rpc_request_latency_seconds_bucket{redpanda_server="internal"}[5m])) by (le, provider, region, instance, namespace, pod))) ``` You can monitor the rate of internal RPC requests with [`redpanda_rpc_request_latency_seconds`](../../../../reference/public-metrics-reference/#redpanda_rpc_request_latency_seconds) histogram’s count: ```promql rate(redpanda_rpc_request_latency_seconds_count[5m]) ``` ### [](#partition-health)Partition health The health of Kafka partitions often reflects the health of the brokers that host them. Thus, when alerts occur for conditions such as under-replicated partitions or more frequent leadership transfers, check for unresponsive or unavailable brokers. With Redpanda’s internal implementation of the Raft consensus protocol, the health of partitions is also reflected in any errors in the internal RPCs exchanged between Raft peers. #### [](#leadership-changes)Leadership changes Stable clusters have a consistent balance of leaders across all brokers, with few to no leadership transfers between brokers. To observe changes in leadership, monitor the [`redpanda_raft_leadership_changes`](../../../../reference/public-metrics-reference/#redpanda_raft_leadership_changes) counter. For example, use a query to get the total rate of increase of leadership changes for a cluster: ```promql sum(rate(redpanda_raft_leadership_changes[5m])) ``` #### [](#under-replicated-partitions)Under-replicated partitions A healthy cluster has partition data fully replicated across its brokers. An under-replicated partition is at higher risk of data loss. It also adds latency because messages must be replicated before being committed. To know when a partition isn’t fully replicated, create an alert for the [`redpanda_kafka_under_replicated_replicas`](../../../../reference/public-metrics-reference/#redpanda_kafka_under_replicated_replicas) gauge when it is greater than zero: ```promql redpanda_kafka_under_replicated_replicas > 0 ``` Under-replication can be caused by unresponsive brokers. When an alert on `redpanda_kafka_under_replicated_replicas` is triggered, identify the problem brokers and examine their logs. #### [](#leaderless-partitions)Leaderless partitions A healthy cluster has a leader for every partition. A partition without a leader cannot exchange messages with producers or consumers. To identify when a partition doesn’t have a leader, create an alert for the [`redpanda_cluster_unavailable_partitions`](../../../../reference/public-metrics-reference/#redpanda_cluster_unavailable_partitions) gauge when it is greater than zero: ```promql redpanda_cluster_unavailable_partitions > 0 ``` Leaderless partitions can be caused by unresponsive brokers. When an alert on `redpanda_cluster_unavailable_partitions` is triggered, identify the problem brokers and examine their logs. #### [](#raft-rpcs)Raft RPCs Redpanda’s Raft implementation exchanges periodic status RPCs between a broker and its peers. The [`redpanda_node_status_rpcs_timed_out`](../../../../reference/public-metrics-reference/#redpanda_node_status_rpcs_timed_out) gauge increases when a status RPC times out for a peer, which indicates that a peer may be unresponsive and may lead to problems with partition replication that Raft manages. Monitor for non-zero values of this gauge, and correlate it with any logged errors or changes in partition replication. ### [](#consumers)Consumer group lag Consumer group lag is an important performance indicator that measures the difference between the broker’s latest (max) offset and the consumer group’s last committed offset. The lag indicates how current the consumed data is relative to real-time production. A high or increasing lag means that consumers are processing messages slower than producers are generating them. A decreasing or stable lag implies that consumers are keeping pace with producers, ensuring real-time or near-real-time data consumption. By monitoring consumer lag, you can identify performance bottlenecks and make informed decisions about scaling consumers, tuning configurations, and improving processing efficiency. A high maximum lag may indicate that a consumer is experiencing connectivity problems or cannot keep up with the incoming workload. A high or increasing total lag (lag sum) suggests that the consumer group lacks sufficient resources to process messages at the rate they are produced. In such cases, scaling the number of consumers within the group can help, but only up to the number of partitions available in the topic. If lag persists despite increasing consumers, repartitioning the topic may be necessary to distribute the workload more effectively and improve processing efficiency. Redpanda provides the following methods for monitoring consumer group lag: - [Dedicated gauges](#dedicated-gauges): Redpanda brokers can internally calculate consumer group lag and expose two dedicated gauges. This method is recommended for environments where your observability platform does not support complex queries required to calculate the lag from offset metrics. Enabling these gauges may add a small amount of additional processing overhead to the brokers. - [Offset-based calculation](#offset-based-calculation): You can use your observability platform to calculate consumer group lag from offset metrics. Use this method if your observability platform supports functions, such as `max()`, and you prefer to avoid additional processing overhead on the broker. #### [](#dedicated-gauges)Dedicated gauges Redpanda can internally calculate consumer group lag and expose it as two dedicated gauges. - [`redpanda_kafka_consumer_group_lag_max`](../../../../reference/public-metrics-reference/#redpanda_kafka_consumer_group_lag_max): Reports the maximum lag observed among all partitions for a consumer group. This metric helps pinpoint the partition with the greatest delay, indicating potential performance or configuration issues. - [`redpanda_kafka_consumer_group_lag_sum`](../../../../reference/public-metrics-reference/#redpanda_kafka_consumer_group_lag_sum): Aggregates the lag across all partitions, providing an overall view of data consumption delay for the consumer group. To enable these dedicated gauges, you must enable consumer group metrics in your cluster properties. Add the following to your Redpanda configuration: - [`enable_consumer_group_metrics`](../../../../reference/properties/cluster-properties/#enable_consumer_group_metrics): A list of properties to enable for consumer group metrics. You must add the `consumer_lag` property to enable consumer group lag metrics. - [`consumer_group_lag_collection_interval_sec`](../../../../reference/properties/cluster-properties/#consumer_group_lag_collection_interval_sec) (optional): The interval in seconds for collecting consumer group lag metrics. The default is 60 seconds. Set this value equal to the scrape interval of your metrics collection system. Aligning these intervals ensures synchronized data collection, reducing the likelihood of missing or misaligned lag measurements. For example: ##### Helm + Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: config: cluster: enable_consumer_group_metrics: - group - partition - consumer_lag ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ##### Helm ###### --values `enable-consumer-metrics.yaml` ```yaml config: cluster: enable_consumer_group_metrics: - group - partition - consumer_lag ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values enable-consumer-metrics.yaml --reuse-values ``` ###### --set ```bash helm upgrade --install redpanda redpanda/redpanda \ --namespace \ --create-namespace \ --set config.cluster.enable_consumer_group_metrics[0]=group \ --set config.cluster.enable_consumer_group_metrics[1]=partition \ --set config.cluster.enable_consumer_group_metrics[2]=consumer_lag ``` When these properties are enabled, Redpanda computes and exposes the `redpanda_kafka_consumer_group_lag_max` and `redpanda_kafka_consumer_group_lag_sum` gauges to the `/public_metrics` endpoint. #### [](#offset-based-calculation)Offset-based calculation If your environment is sensitive to the performance overhead of the [dedicated gauges](#dedicated-gauges), use the offset-based calculation method to calculate consumer group lag. This method requires your observability platform to support functions like `max()`. Redpanda provides two metrics to calculate consumer group lag: - [`redpanda_kafka_max_offset`](../../../../reference/public-metrics-reference/#redpanda_kafka_max_offset): The broker’s latest offset for a partition. - [`redpanda_kafka_consumer_group_committed_offset`](../../../../reference/public-metrics-reference/#redpanda_kafka_consumer_group_committed_offset): The last committed offset for a consumer group on that partition. For example, here’s a typical query to compute consumer lag: ```promql max by(redpanda_namespace, redpanda_topic, redpanda_partition)(redpanda_kafka_max_offset{redpanda_namespace="kafka"}) - on(redpanda_topic, redpanda_partition) group_right max by(redpanda_group, redpanda_topic, redpanda_partition)(redpanda_kafka_consumer_group_committed_offset) ``` ### [](#services)Services Monitor the health of specific Redpanda services with the following metrics. #### [](#schema-registry)Schema Registry Schema Registry request latency: ```promql histogram_quantile(0.99, (sum(rate(redpanda_schema_registry_request_latency_seconds_bucket[5m])) by (le, provider, region, instance, namespace, pod))) ``` Schema Registry request rate: ```promql rate(redpanda_schema_registry_request_latency_seconds_count[5m]) + sum without(redpanda_status)(rate(redpanda_schema_registry_request_errors_total[5m])) ``` Schema Registry request error rate: ```promql rate(redpanda_schema_registry_request_errors_total[5m]) ``` #### [](#rest-proxy)REST proxy REST proxy request latency: ```promql histogram_quantile(0.99, (sum(rate(redpanda_rest_proxy_request_latency_seconds_bucket[5m])) by (le, provider, region, instance, namespace, pod))) ``` REST proxy request rate: ```promql rate(redpanda_rest_proxy_request_latency_seconds_count[5m]) + sum without(redpanda_status)(rate(redpanda_rest_proxy_request_errors_total[5m])) ``` REST proxy request error rate: ```promql rate(redpanda_rest_proxy_request_errors_total[5m]) ``` ### [](#data-transforms)Data transforms See [Monitor Data Transforms](../../../../develop/data-transforms/monitor/). ## [](#references)References - [Public Metrics Reference](../../../../reference/public-metrics-reference/) - [Internal Metrics Reference](../../../../reference/internal-metrics-reference/) - [Redpanda monitoring examples repository](https://github.com/redpanda-data/observability) ## [](#suggested-reading)Suggested reading - [Monitor Shadow Links](../../shadowing/k-monitor-shadowing/) - [Monitoring Redpanda in Kubernetes(Day 2 Ops)](https://killercoda.com/redpanda/scenario/redpanda-k8s-day2) ## Suggested labs - [Owl Shop Example Application in Docker](/redpanda-labs/docker-compose/owl-shop/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) [Search all labs](/redpanda-labs) --- # Page 174: Networking and Connectivity in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/networking.md --- # Networking and Connectivity in Kubernetes --- title: Networking and Connectivity in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/networking/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/networking/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/networking/index.adoc description: Learn how to set up and manage network connections for Redpanda in Kubernetes. This section covers a range of topics, including how to enable external access, connect clients to a Redpanda cluster, and configure listeners. page-git-created-date: "2023-08-03" page-git-modified-date: "2024-09-12" support-status: supported --- Learn how to set up and manage network connections for Redpanda in Kubernetes. This section covers a range of topics, including how to enable external access, connect clients to a Redpanda cluster, and configure listeners. - [About Networking and Connectivity in Kubernetes](k-networking-and-connectivity/) Learn how internal and external connectivity works when Redpanda is running in Kubernetes. - [Connect to Redpanda in Kubernetes](k-connect-to-redpanda/) Learn how to connect to a Redpanda cluster running in Kubernetes. - [Configure Listeners in Kubernetes](k-configure-listeners/) Configure your Redpanda deployment in Kubernetes to meet specific network requirements by customizing advertised ports and TLS certificates for each listener. Learn to enable or disable access to these listeners as needed. - [Configure External Access](external/) Use Kubernetes Services to expose your Redpanda cluster to clients outside of your Kubernetes cluster. --- # Page 175: Configure External Access **URL**: https://docs.redpanda.com/current/manage/kubernetes/networking/external.md --- # Configure External Access --- title: Configure External Access latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/networking/external/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/networking/external/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/networking/external/index.adoc description: Use Kubernetes Services to expose your Redpanda cluster to clients outside of your Kubernetes cluster. page-git-created-date: "2023-11-14" page-git-modified-date: "2024-02-26" support-status: supported --- Setting up external access to your Redpanda cluster allows applications running outside the Kubernetes cluster to communicate with Redpanda. To make the Redpanda brokers externally accessible, the Pods must be exposed through Kubernetes Services. - [Configure External Access through a NodePort Service](k-nodeport/) Use a NodePort Service to expose your Redpanda cluster to clients outside of your Kubernetes cluster. - [Configure External Access through LoadBalancer Services](k-loadbalancer/) Use LoadBalancer Services to expose your Redpanda cluster to clients outside of your Kubernetes cluster. - [Use a Custom Service for External Access](k-custom-services/) Expose your Redpanda cluster to clients outside of your Kubernetes cluster by using a custom Service. --- # Page 176: Use a Custom Service for External Access **URL**: https://docs.redpanda.com/current/manage/kubernetes/networking/external/k-custom-services.md --- # Use a Custom Service for External Access --- title: Use a Custom Service for External Access latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/networking/external/k-custom-services page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/networking/external/k-custom-services.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/networking/external/k-custom-services.adoc description: Expose your Redpanda cluster to clients outside of your Kubernetes cluster by using a custom Service. page-git-created-date: "2024-01-04" page-git-modified-date: "2025-04-07" support-status: supported --- By default, the Helm chart deploys a NodePort Service to provide external access to the Redpanda cluster. To use a custom Service, set `external.service.enabled` to `false`. Then, you can create your own Services to provide external access. #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: external: enabled: true service: enabled: false addresses: - - - ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `disable-external-service.yaml` ```yaml external: enabled: true service: enabled: false addresses: - - - ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values disable-external-service.yaml --reuse-values ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set external.enabled=true \ --set external.service.enabled=false \ --set "external.addresses={,,}" ``` Make sure to configure `external.addresses` with addresses that point to the worker nodes on which each Redpanda broker is running. The addresses must be listed in order of the StatefulSet replicas. For example, the first address in the list is assigned to the first replica (`redpanda-0` by default). If you use a custom domain (`external.domain`), provide subdomains for each replica in `external.addresses`. This custom domain is appended to each subdomain (`.`). Make sure that your custom Service listens on the advertised ports that are configured for each listener. See [Configure Listeners in Kubernetes](../../k-configure-listeners/). ## [](#next-steps)Next steps - [Configure Listeners in Kubernetes](../../k-configure-listeners/) - [Connect to Redpanda in Kubernetes](../../k-connect-to-redpanda/) ## [](#suggested-reading)Suggested reading - [Redpanda Helm Specification](../../../../../reference/k-redpanda-helm-spec/#external) - [Redpanda CRD Reference](../../../../../reference/k-crd/) --- # Page 177: Configure External Access through LoadBalancer Services **URL**: https://docs.redpanda.com/current/manage/kubernetes/networking/external/k-loadbalancer.md --- # Configure External Access through LoadBalancer Services --- title: Configure External Access through LoadBalancer Services latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/networking/external/k-loadbalancer page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/networking/external/k-loadbalancer.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/networking/external/k-loadbalancer.adoc description: Use LoadBalancer Services to expose your Redpanda cluster to clients outside of your Kubernetes cluster. page-git-created-date: "2024-01-04" page-git-modified-date: "2025-04-07" support-status: supported --- When the `external.type` field is set to `LoadBalancer`, the Helm chart creates one LoadBalancer Service for each replica in the StatefulSet. Each LoadBalancer Service routes traffic to the external listener ports on a single Redpanda broker. To set up external access using LoadBalancer Services, you must configure the brokers to advertise addresses that resolve to the load balancer instances. ![A client connects to a Pod through a load balancer](../../../../../shared/_images/loadbalancer.png) > 📝 **NOTE** > > The Helm chart adds the `spec.selector.statefulset.kubernetes.io/pod-name` setting to each LoadBalancer Service so that each Service targets only one Redpanda broker. Each Pod in a StatefulSet is automatically given the `statefulset.kubernetes.io/pod-name` label, which contains the name of the Pod. By setting the `spec.selector.statefulset.kubernetes.io/pod-name` field of the LoadBalancer Service to the name of a Pod, it makes the LoadBalancer Service target only the individual Redpanda broker and not the whole cluster. ## [](#prerequisites)Prerequisites - One worker node for each Redpanda broker that you want to deploy. - Install [rpk](../../../../../get-started/rpk-install/) on your local machine so that you can test external connections to your Redpanda cluster from outside Kubernetes. - Make sure that your Kubernetes cluster is accessible through your desired node port range. You may need to edit your inbound firewall rules. - If you want brokers to advertise a custom domain, you must have control over the DNS settings for that domain. > 💡 **TIP** > > For internal testing, you can use any domain without owning that domain, as long as: > > - Your local DNS server is configured to resolve that domain to the correct IP address. > > - Your client systems are configured to use your DNS server for resolution. > > > For production, it’s best to buy a domain from a domain registrar. This way, your domain is resolvable without any additional client-side configuration. ## [](#advertise-a-custom-domain)Advertise a custom domain To configure your Redpanda brokers to advertise a custom domain, each broker must also have a hostname that points to the address of the broker’s corresponding load balancer instance. Your brokers can advertise one of the following hostnames: - The [default Redpanda hostname](#advertise-the-default-redpanda-hostnames) The default hostnames are `redpanda-`, where `redpanda` is the name of the Helm release and the `` placeholder is the Pod ordinal generated by the StatefulSet. - [Custom hostnames](#advertise-custom-hostnames) Custom hostnames override the default. For example, you can configure your brokers to advertise `.`. ### [](#advertise-the-default-redpanda-hostnames)Advertise the default Redpanda hostnames By default, the Helm chart gives each broker a hostname that consists of the Helm release and the Pod ordinal. For example, `redpanda-0`, where `redpanda` is the Helm release and `0` is the Pod ordinal. To configure brokers to advertise these hostnames, you must configure the brokers with a custom domain. 1. Specify your domain and optional subdomains in the `external.domain` configuration. Replace `` with your domain. #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: external: enabled: true domain: type: LoadBalancer ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `custom-domain.yaml` ```yaml external: enabled: true domain: type: LoadBalancer ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values custom-domain.yaml --reuse-values --wait ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set external.enabled=true \ --set external.type=LoadBalancer \ --set external.domain= \ --wait ``` 2. [Create DNS records](#create-dns-records) for each of your broker’s FQDNs, relative to the zone. ### [](#advertise-custom-hostnames)Advertise custom hostnames You can give each Redpanda broker a custom hostname to advertise instead of the default hostnames. Custom hostnames can either be suffixed with the Pod ordinal or they can be fully custom. #### [](#advertise-custom-hostnames-suffixed-with-the-pod-ordinal)Advertise custom hostnames suffixed with the Pod ordinal 1. Configure the chart name with your chosen hostname. Replace `` with your domain, and replace `` with your hostname. ##### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: fullnameOverride: external: enabled: true type: LoadBalancer domain: ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ##### Helm ###### --values `custom-hostname-ordinal.yaml` ```yaml fullnameOverride: external: enabled: true type: LoadBalancer domain: ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values custom-hostname-ordinal.yaml --reuse-values --wait ``` ###### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set external.enabled=true \ --set external.type=LoadBalancer \ --set external.domain= \ --set fullnameOverride= \ --wait ``` This configuration renames your Pods to `-`. Your Redpanda brokers will advertise the `-.` address. 2. [Create DNS records](#create-dns-records) for each of your broker’s FQDNs, relative to the zone. #### [](#advertise-fully-custom-hostnames)Advertise fully custom hostnames 1. Add each hostname to the `external.addresses` setting. Replace `` with your domain, and replace the placeholders in the `external.addresses` setting with your own hostname in the order that you want them to be applied to the Redpanda brokers. The hostnames must be given to each Redpanda broker in order of the StatefulSet replicas. For example, the Redpanda broker running inside the `redpanda-0` Pod advertises `.`. ##### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: external: enabled: true type: LoadBalancer domain: addresses: - - - ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ##### Helm ###### --values `custom-hostname.yaml` ```yaml external: enabled: true type: LoadBalancer domain: addresses: - - - ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values custom-hostname.yaml --reuse-values --wait ``` ###### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set external.enabled=true \ --set external.type=LoadBalancer \ --set external.domain= \ --set "external.addresses={,,}" \ --wait ``` 2. [Create DNS records](#create-dns-records) for each of your broker’s FQDNs, relative to the zone. ### [](#create-dns-records)Create DNS records When your brokers are configured to advertise a custom domain, the next step is to create DNS records that point the FQDNs at the load balancer instances. You can: - Create the DNS records manually. - Use ExternalDNS to manage DNS records. #### [](#manual)Manual 1. Find the addresses for each of your load balancers. 2. Update the CNAME record for your domain so that each FQDN points to the correct load balancer’s address. | Hostname | Load balancer | | --- | --- | | | | | | | | | | 3. Wait for your DNS changes to be propagated. 4. Use your custom domain to communicate with the Redpanda cluster from outside the Kubernetes cluster: ```bash rpk cluster info -X brokers=.:31092 ``` #### [](#externaldns)ExternalDNS ExternalDNS is a tool for Kubernetes that manages DNS records. Whenever you add, change, or remove Kubernetes Services or Ingresses, ExternalDNS automatically makes the same updates to the DNS records by communicating with DNS providers through their public APIs. This communication keeps your DNS records up to date with your Kubernetes Services. 1. Ensure that you have a DNS zone available where ExternalDNS can create DNS records. See the [supported DNS providers](https://github.com/kubernetes-sigs/external-dns#status-of-providers) in the ExternalDNS documentation. 2. Deploy ExternalDNS in your Kubernetes cluster. For an example manifest, see the [ExternalDNS documentation](https://github.com/kubernetes-sigs/external-dns/blob/master/docs/tutorials/hostport.md#external-dns). Set the `--provider` flag to your DNS provider. > 💡 **TIP** > > The `txtOwnerId` and `interval` flags are recommended. The `txtOwnerId` flag prevents DNS record conflicts between different instances of ExternalDNS. The `interval` flag controls the sync period with the DNS provider. 3. Enable ExternalDNS in the Redpanda Helm chart: ##### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: external: externalDns: enabled: true ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ##### Helm ###### --values `enable-external-dns.yaml` ```yaml external: externalDns: enabled: true ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values enable-external-dns.yaml --reuse-values --wait ``` ###### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set external.externalDns.enabled=true \ --wait ``` When `external.externalDns` is enabled, each LoadBalancer Service is annotated with `external-dns.alpha.kubernetes.io/hostname` and the value is set to the configured FQDN of each Redpanda broker. ExternalDNS will now automatically create DNS records for your Redpanda brokers, update the records if the LoadBalancer Services change, and delete them if you delete the Service. ## [](#advertise-the-default-addresses-of-the-load-balancer-instances)Advertise the default addresses of the load balancer instances You can configure each Redpanda broker to advertise the DNS name or IP address of its corresponding load balancer instance. > ❗ **IMPORTANT** > > If your cluster has TLS enabled (default), you must [Advertise a custom domain](#advertise-a-custom-domain). The Helm chart adds custom domains to the SAN list of TLS certificates and not IP addresses. Therefore, IP addresses assigned to LoadBalancer Services must be made resolvable by DNS names to ensure secure TLS access. > > While adding entries to the `/etc/hosts` file may work for development purposes, it’s not a suitable approach for production environments. In production, you’ll need to update your organization’s DNS service to make the IP addresses resolvable by DNS names. Updating your organization’s DNS service ensures that users can access your services securely without encountering any SSL/TLS warnings or errors. If you’re hosting Redpanda on a managed Kubernetes platform, follow the [Managed Kubernetes](#managed-kubernetes) steps. Otherwise, follow the [Bare metal](#bare-metal) steps. ### [](#managed-kubernetes)Managed Kubernetes 1. Deploy Redpanda with TLS disabled and enable the LoadBalancer Service type: #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: external: enabled: true type: LoadBalancer tls: enabled: false ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `loadbalancer-tls-disabled.yaml` ```yaml external: enabled: true type: LoadBalancer tls: enabled: false ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values loadbalancer-tls-disabled.yaml --reuse-values --wait ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set external.enabled=true \ --set external.type=LoadBalancer \ --set tls.enabled=false \ --wait ``` 2. Make sure that your managed Kubernetes platform assigned external addresses to your LoadBalancer Services: ```bash kubectl get service --namespace ``` Example output: NAME TYPE CLUSTER-IP EXTERNAL-IP lb-redpanda-0 LoadBalancer 10.100.113.102 loadbalancer1.com lb-redpanda-1 LoadBalancer 10.100.53.8 loadbalancer2.com lb-redpanda-2 LoadBalancer 10.100.231.13 loadbalancer3.com 3. Configure the Redpanda brokers to advertise these external addresses: #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: external: enabled: true type: LoadBalancer addresses: - - - tls: enabled: false ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ```bash helm upgrade redpanda redpanda/redpanda \ --namespace \ --set $( kubectl get svc \ --namespace \ --selector "app.kubernetes.io/name=redpanda,app.kubernetes.io/instance=redpanda" \ -o jsonpath='{"external.addresses={"}{ range .items[*]}{.status.loadBalancer.ingress[0].ip }{.status.loadBalancer.ingress[0].hostname}{","}{ end }{"}\n"}') \ --reuse-values \ --wait ``` 4. Use the load balancers' addresses to communicate with the Redpanda cluster from outside the Kubernetes cluster: ```bash rpk cluster info -X brokers=:31092 ``` ### [](#bare-metal)Bare metal 1. Deploy Redpanda with TLS disabled and enable the LoadBalancer Service type: #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: external: enabled: true type: LoadBalancer tls: enabled: false ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `loadbalancer-tls-disabled.yaml` ```yaml external: enabled: true type: LoadBalancer tls: enabled: false ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values loadbalancer-tls-disabled.yaml --reuse-values --wait ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set external.enabled=true \ --set external.type=LoadBalancer \ --set tls.enabled=false \ --wait ``` 2. Find the node ports that each LoadBalancer Service exposes: ```bash kubectl get service --namespace ``` Example output: NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) lb-redpanda-0 LoadBalancer 10.96.162.129 31644:30733/TCP,31092:30951/TCP,30082:30158/TCP,30081:32404/TCP 4m49s lb-redpanda-1 LoadBalancer 10.96.53.61 31644:30274/TCP,31092:32483/TCP,30082:30779/TCP,30081:30420/TCP 4m49s lb-redpanda-2 LoadBalancer 10.96.203.230 31644:32025/TCP,31092:30424/TCP,30082:30611/TCP,30081:32080/TCP 3. Create one load balancer instance outside of your Kubernetes cluster for each worker node that runs Redpanda, and forward the traffic to the node ports that are opened by the LoadBalancer Services. 4. Add the DNS names or IP addresses of your load balancer instances to the `external.addresses` field in order of the StatefulSet replicas. For example, the first address in the list is assigned to `redpanda-0`, the second is assigned to `redpanda-1`, and so on. #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: external: enabled: true type: LoadBalancer addresses: - - - tls: enabled: false ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set "external.addresses={,,}" --reuse-values --wait ``` 5. Use the load balancers' addresses to communicate with the Redpanda cluster from outside the Kubernetes cluster: ```bash rpk cluster info -X brokers=:31092 ``` ## [](#next-steps)Next steps - [Configure listeners](../../k-configure-listeners/) - [Connect to Redpanda in Kubernetes](../../k-connect-to-redpanda/) ## [](#suggested-reading)Suggested reading - [Redpanda Helm Specification](../../../../../reference/k-redpanda-helm-spec/#external) - [Redpanda CRD Reference](../../../../../reference/k-crd/) --- # Page 178: Configure External Access through a NodePort Service **URL**: https://docs.redpanda.com/current/manage/kubernetes/networking/external/k-nodeport.md --- # Configure External Access through a NodePort Service --- title: Configure External Access through a NodePort Service latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/networking/external/k-nodeport page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/networking/external/k-nodeport.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/networking/external/k-nodeport.adoc description: Use a NodePort Service to expose your Redpanda cluster to clients outside of your Kubernetes cluster. page-git-created-date: "2024-01-04" page-git-modified-date: "2025-04-07" support-status: supported --- By default, the Helm chart deploys a NodePort Service that routes traffic to the external listener ports on the Redpanda brokers. To set up external access using this NodePort Service, you must configure the brokers to advertise addresses that resolve to the IP address of the worker node. ![A client connects to a Pod through the NodePort Service](../../../../../shared/_images/nodeport.png) ## [](#prerequisites)Prerequisites - One worker node for each Redpanda broker that you want to deploy. - Install [rpk](../../../../../get-started/rpk-install/) on your local machine so that you can test connections to your Redpanda cluster from outside Kubernetes. - Review [Kubernetes Cluster Requirements and Recommendations](../../../../../deploy/redpanda/kubernetes/k-requirements/). - Understand [Kubernetes networking for Redpanda](../../k-networking-and-connectivity/). - Ensure that your Kubernetes cluster is accessible through your desired node port range. For example, with AWS EKS you must edit your inbound firewall rules. And with Azure AKS, you must [enable public IPs](https://learn.microsoft.com/en-us/azure/aks/use-node-public-ips) on nodes in your node pool. - If you want brokers to advertise a custom domain, you must have control over the DNS settings for that domain. > 💡 **TIP** > > For internal testing, you can use any domain without owning that domain, as long as: > > - Your local DNS server is configured to resolve that domain to the correct IP address. > > - Your client systems are configured to use your DNS server for resolution. > > > For production, it’s best to buy a domain from a domain registrar. This way, your domain is resolvable without any additional client-side configuration. ## [](#advertise-custom-domains)Advertise custom domains Advertising custom domains rather than IP addresses has several advantages, including: - **Flexibility**: IP addresses can change, especially in cloud environments where services can be moved around or scaled up and down. If you use domain names, you can update the DNS record when the IP address changes and the clients won’t need any configuration changes. - **High Availability**: If a server fails, you can quickly point the domain name to another IP address, which would not be possible if clients connect directly using IP addresses. - **Security**: If the IP address of a server changes, you won’t need to reissue TLS certificates if it’s bound to a domain name. To configure your Redpanda brokers to advertise a custom domain, each broker must also have a hostname that points to the address of the broker’s worker node. Your brokers can advertise one of the following hostnames: - The [default Redpanda hostname](#advertise-the-default-redpanda-hostnames) The default hostnames are `redpanda-`, where `redpanda` is the name of the Helm release and the `` placeholder is the Pod ordinal generated by the StatefulSet. - [Custom hostnames](#advertise-custom-hostnames) Custom hostnames override the default. For example, you can configure your brokers to advertise `.`. ### [](#advertise-the-default-redpanda-hostnames)Advertise the default Redpanda hostnames By default, the Helm chart gives each broker a hostname that consists of the Helm release and the Pod ordinal. For example, `redpanda-0`, where `redpanda` is the Helm release and `0` is the Pod ordinal. To configure brokers to these hostnames, you must configure the brokers with a custom domain. 1. Specify your domain and optional subdomains in the `external.domain` configuration. Replace `` with your domain. #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: external: enabled: true domain: type: NodePort ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `custom-domain.yaml` ```yaml external: enabled: true domain: type: NodePort ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values custom-domain.yaml --reuse-values --wait ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set external.enabled=true \ --set external.type=NodePort \ --set external.domain= \ --wait ``` 2. [Create DNS records](#create-dns-records) for each of your broker’s FQDNs, relative to the zone. ### [](#custom-hostnames)Custom hostnames You can give each Redpanda broker a custom hostname to advertise instead of the default hostnames. Custom hostnames can either be suffixed with the Pod ordinal or they can be fully custom. #### [](#advertise-custom-hostnames-suffixed-with-the-pod-ordinal)Advertise custom hostnames suffixed with the Pod ordinal 1. Configure the chart name with your chosen hostname. Replace `` with your domain, and replace `` with your hostname. ##### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: fullnameOverride: external: enabled: true type: NodePort domain: ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ##### Helm ###### --values `custom-hostname-ordinal.yaml` ```yaml fullnameOverride: external: enabled: true type: NodePort domain: ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values custom-hostname-ordinal.yaml --reuse-values --wait ``` ###### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set external.enabled=true \ --set external.type=NodePort \ --set external.domain= \ --set fullnameOverride= \ --wait ``` This configuration renames your Pods to `-`. Your Redpanda brokers will advertise the `-.` address. 2. [Create DNS records](#create-dns-records) for each of your broker’s FQDNs, relative to the zone. #### [](#advertise-fully-custom-hostnames)Advertise fully custom hostnames 1. Add each hostname to the `external.addresses` setting. Replace `` with your domain, and replace the placeholders in the `external.addresses` setting with your own hostname in the order that you want them to be applied to the Redpanda brokers. The hostnames must be given to each Redpanda broker in order of the StatefulSet replicas. For example, the Redpanda broker running inside the `redpanda-0` Pod advertises `.`. ##### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: external: enabled: true type: NodePort domain: addresses: - - - ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ##### Helm ###### --values `custom-hostname.yaml` ```yaml external: enabled: true type: NodePort domain: addresses: - - - ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values custom-hostname.yaml --reuse-values --wait ``` ###### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set external.enabled=true \ --set external.type=NodePort \ --set external.domain= \ --set "external.addresses={,,}" \ --wait ``` 2. [Create DNS records](#create-dns-records) for each of your broker’s FQDNs, relative to the zone. ### [](#create-dns-records)Create DNS records When your brokers are configured to advertise a custom domain, the next step is to create DNS records that point the FQDNs at the IP addresses of the worker nodes on which the brokers are running. You can: - [Create the DNS records manually](#manual). - [Use ExternalDNS to manage DNS records](#externaldns). #### [](#manual)Manual 1. Find out on which worker nodes your Redpanda brokers are running. ```bash kubectl get pod --namespace \ -o=custom-columns=NODE:.spec.nodeName,NAME:.metadata.name -l \ app.kubernetes.io/component=redpanda-statefulset ``` 2. Find the IP address of each worker node. ```bash kubectl get node -o wide ``` 3. Update the A/AAAA records for your domain so that each FQDN points to the correct worker node’s IP address. | Hostname | IP address | | --- | --- | | | | | | | | | | > ⚠️ **WARNING** > > IP addresses can change. If the IP addresses of your worker nodes change, you must reconfigure your DNS records with the new IP addresses. 4. Wait for your DNS changes to be propagated. 5. Use the FQDN to communicate with the Redpanda brokers from outside the Kubernetes cluster: ```bash rpk cluster info -X brokers=.:31092 ``` #### [](#externaldns)ExternalDNS ExternalDNS is a tool for Kubernetes that manages DNS records. Whenever you add, change, or remove Kubernetes Services or Ingresses, ExternalDNS automatically makes the same updates to the DNS records by communicating with DNS providers through their public APIs. This communication keeps your DNS records up to date with your Kubernetes Services. 1. Ensure that you have a DNS zone available where ExternalDNS can create DNS records. See the [supported DNS providers](https://github.com/kubernetes-sigs/external-dns#status-of-providers) in the ExternalDNS documentation. 2. Deploy ExternalDNS in your Kubernetes cluster. For an example manifest, see the [ExternalDNS documentation](https://github.com/kubernetes-sigs/external-dns/blob/master/docs/tutorials/hostport.md#external-dns). Set the `--provider` flag to your DNS provider. > 💡 **TIP** > > The `txtOwnerId` and `interval` flags are recommended. The `txtOwnerId` flag prevents DNS record conflicts between different instances of ExternalDNS. The `interval` flag controls the sync period with the DNS provider. 3. Annotate the headless ClusterIP Service to use ExternalDNS: ##### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: service: internal: annotations: "external-dns.alpha.kubernetes.io/hostname": "external-dns.alpha.kubernetes.io/endpoints-type": ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ##### Helm ###### --values `external-dns.yaml` ```yaml service: internal: annotations: "external-dns.alpha.kubernetes.io/hostname": "external-dns.alpha.kubernetes.io/endpoints-type": ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values external-dns.yaml --reuse-values --wait ``` ###### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set "service.internal.annotations.external-dns\.alpha\.kubernetes\.io/hostname=" \ --set "service.internal.annotations.external-dns\.alpha\.kubernetes\.io/endpoints-type=" \ --wait ``` For guidance, see [Setting up ExternalDNS for Headless Services](https://github.com/kubernetes-sigs/external-dns/blob/master/docs/tutorials/hostport.md#headless-service) in the ExternalDNS documentation. ExternalDNS will now automatically create DNS records for your Redpanda brokers, update the records if the IP addresses change, and delete them if you delete the ClusterIP Service. ## [](#advertise-ip-addresses)Advertise IP addresses You can configure each Redpanda broker to advertise the IP address of the worker node on which it’s running. > ❗ **IMPORTANT** > > If your cluster has TLS enabled (default), you must [Advertise custom domains](#advertise-custom-domains). The Helm chart adds custom domains to the SAN list of TLS certificates and not IP addresses. Therefore, IP addresses assigned to LoadBalancer Services must be made resolvable by DNS names to ensure secure TLS access. > > While adding entries to the `/etc/hosts` file may work for development purposes, it’s not a suitable approach for production environments. In production, you’ll need to update your organization’s DNS service to make the IP addresses resolvable by DNS names. Updating your organization’s DNS service ensures that users can access your services securely without encountering any SSL/TLS warnings or errors. 1. Deploy Redpanda with TLS disabled and enable the NodePort Service type: ### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: external: enabled: true type: NodePort tls: enabled: false ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ### Helm #### --values `loadbalancer-tls-disabled.yaml` ```yaml external: enabled: true type: NodePort tls: enabled: false ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values loadbalancer-tls-disabled.yaml --reuse-values --wait ``` #### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set external.enabled=true \ --set external.type=NodePort \ --set tls.enabled=false \ --wait ``` 2. Find out on which worker nodes your Redpanda brokers are running. ```bash kubectl get pod --namespace \ -o=custom-columns=NODE:.spec.nodeName,NAME:.metadata.name -l \ app.kubernetes.io/component=redpanda-statefulset ``` 3. Find the IP address of each worker node. ```bash kubectl get node -o wide ``` 4. Add the IP addresses of each worker node to the `external.addresses` field in order. For example, the first IP address in the list is assigned to `redpanda-0`, the second is assigned to `redpanda-1`, and so on. ### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: external: addresses: - - - ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ### Helm #### --values `external-access-ip-addresses.yaml` ```yaml external: addresses: - - - ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values external-access-ip-addresses.yaml --reuse-values --wait ``` #### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set external.enabled=true \ --set external.type=NodePort \ --set tls.enabled=false \ --set external.domain= \ --set "external.addresses={,,}" \ --wait ``` > ⚠️ **WARNING** > > IP addresses can change. If the IP addresses of your worker nodes change, you must reconfigure the Redpanda brokers and all your external clients with the new IP addresses. 5. Use the IP addresses to communicate with the Redpanda cluster from outside the Kubernetes cluster: ```bash rpk cluster info -X brokers=:31092 ``` ## [](#next-steps)Next steps - [Configure listeners](../../k-configure-listeners/) - [Connect to Redpanda in Kubernetes](../../k-connect-to-redpanda/) ## [](#suggested-reading)Suggested reading - [Redpanda Helm Specification](../../../../../reference/k-redpanda-helm-spec/#external) - [Redpanda CRD Reference](../../../../../reference/k-crd/) --- # Page 179: Configure Listeners in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/networking/k-configure-listeners.md --- # Configure Listeners in Kubernetes --- title: Configure Listeners in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/networking/k-configure-listeners page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/networking/k-configure-listeners.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/networking/k-configure-listeners.adoc description: Configure your Redpanda deployment in Kubernetes to meet specific network requirements by customizing advertised ports and TLS certificates for each listener. Learn to enable or disable access to these listeners as needed. page-git-created-date: "2024-01-04" page-git-modified-date: "2025-07-31" support-status: supported --- You can fine-tune client interactions with Redpanda by customizing internal and external listener configurations. ## [](#anatomy-of-a-listener)Anatomy of a listener Listeners are gateways for client communications in Redpanda. Redpanda uses TCP sockets for client connections, where each TCP socket consists of: - **IP address or DNS name**: The unique network identifier of the Redpanda server. This can be a local address or a public address for cloud-based services. - **Port**: A specific entry point for network traffic. Redpanda listens on designated ports for client connections. Clients must specify both the IP address or DNS name and port for a successful connection, such as `203.0.113.5:9093`. The Redpanda Helm chart defines two listeners by default: | Listener | Description | | --- | --- | | default | Internal connections. These endpoints use internal addresses assigned to brokers by Kubernetes through the headless ClusterIP Service. | | external | External connections. These endpoints are accessible through addresses configured in the external.domain and/or external.addresses settings in the Helm values. | For example, these are the default settings for the internal Kafka API listener: ```yaml listeners: kafka: port: 9093 authenticationMethod: tls: enabled: true cert: default requireClientAuth: false ``` - `listeners.kafka.port`: The container port for internal client connections. - `listeners.kafka.authenticationMethod`: The authentication method to use when the top-level `auth.sasl.enabled` setting is `true`. Default is `sasl`. - `listeners.kafka.tls.enabled`: Whether TLS is enabled for this listener when the top-level `tls.enabled` setting is `true` for all listeners. - `listeners.kafka.tls.cert`: The TLS certificates that this listener should use to secure client connections. TLS certificates are defined in `tls.certs`. - `listeners.kafka.tls.requireClientAuth`: Whether mTLS is enabled. These are the settings for the external Kafka API listener: ```yaml listeners: kafka: external: default: enabled: true port: 9094 # -- If undefined, `listeners.kafka.external.default.port` is used. advertisedPorts: - 31092 tls: enabled: true cert: external # default is "sasl" authenticationMethod: ``` - `listeners.kafka.external.default.port`: The container port for external client connections. - `listeners.kafka.external.default.advertisedPorts`: The node port that is routed to `listeners.kafka.external.default.port`. This port is opened in Kubernetes Services when `external.service.enabled` is `true`. - `listeners.kafka.external.default.authenticationMethod`: The authentication method to use when the top-level `auth.sasl.enabled` setting is `true`. Default is `sasl`. - `listeners.kafka.external.default.tls.enabled`: Whether TLS is enabled for this listener when the top-level `tls.enabled` setting is `true` for all listeners. - `listeners.kafka.external.default.tls.cert`: The TLS certificates that this listener should use to secure client connections. TLS certificates are defined in `tls.certs`. Schema Registry and HTTP Proxy connect to Redpanda over the Kafka API. If you configure a TLS listener for the Kafka API, you must configure `listeners.schemaRegistry.tls` and `listeners.http.tls`. All APIs, except the internal RPC port, support multiple listeners. ## [](#customize-the-external-node-ports)Customize the external node ports Each listener has separate ports for internal and external connections. To customize the external node ports for each listener, replace `` with the port that you want to use. > 📝 **NOTE** > > Redpanda doesn’t validate the configured port numbers. Make sure to verify the following: > > - Your configured port numbers are within the range that is assigned for node ports in your Kubernetes cluster. > > - Your Kubernetes cluster is accessible through your desired node port range. You may need to edit your inbound firewall rules. > > - Your configured port numbers are not in use by any other service. For the default ports, see the [Redpanda Helm Chart Specification](../../../../reference/k-redpanda-helm-spec/#listeners) For example, to customize the node ports for the external Kafka API listener: `custom-kafka-port.yaml` ```yaml listeners: kafka: external: default: advertisedPorts: - ``` ## [](#tls)Configure TLS certificates A Redpanda cluster provides granular control over the TLS certificates used by different listeners. This level of flexibility enables you to ensure the required level of security for each listener. For example, you can use a self-signed certificate for the internal RPC listener, while using a public certificate authority (CA) certificate for other listeners such as the Kafka API. > ❗ **IMPORTANT** > > All listeners must use the same certificate if mTLS is enabled. Redpanda on Kubernetes does not support configuring different TLS certificates for mTLS-enabled listeners, or mixed configurations where some listeners use mTLS and others do not. - **Internal listeners**: By default, all internal listeners use the self-signed certificate defined globally in the `tls.certs.default` configuration. To customize the certificates for each internal listener, you can edit the `listeners..tls.cert` setting. - **External listeners**: By default, all external listeners use the self-signed certificate defined globally in the `tls.certs.external` configuration. To customize the certificates for each internal listener, you can edit the `listeners..external.default.tls.cert` setting. Here’s an example that configures two certificates: - `public-ca-cert`: This certificate is configured with an [Issuer managed by cert-manager](../../security/tls/k-cert-manager/). - `private-ca-cert`. This certificate is configured with an [Opaque Secret](../../security/tls/k-secrets/) containing the `tls.crt`, `tls.key`, and `ca.crt` files. The external Admin API listener is configured with the `public-ca-cert` certificate. The internal Kafka API listener is configured with the `private-ca-cert` certificate, and the other listeners are configured with the default self-signed certificate. `multiple-certs-tls.yaml` ```yaml tls: enabled: true certs: public-ca-cert: issuerRef: name: kind: Issuer caEnabled: false private-ca-cert: secretRef: name: caEnabled: true default: caEnabled: true listeners: admin: external: default: tls: cert: public-ca-cert kafka: tls: cert: private-ca-cert http: tls: cert: default rpc: tls: cert: default schemaRegistry: tls: cert: default ``` ## [](#disable-external-access)Disable external access You can disable external access for all listeners or for individual listeners. To disable external access for all listeners: `disable-external-access.yaml` ```yaml external: enabled: false ``` To disable external access for a specific listener, set `listeners..external.default` to `false`. For example, to disable external access to the Kafka API listener: `disable-external-kafka-api.yaml` ```yaml listeners: kafka: external: default: enabled: false ``` ## [](#next-steps)Next steps [Connect to Redpanda in Kubernetes](../k-connect-to-redpanda/) ## [](#suggested-reading)Suggested reading - [Redpanda Helm Specification](../../../../reference/k-redpanda-helm-spec/#listeners) - [Redpanda CRD Reference](../../../../reference/k-crd/) --- # Page 180: Connect to Redpanda in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/networking/k-connect-to-redpanda.md --- # Connect to Redpanda in Kubernetes --- title: Connect to Redpanda in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/networking/k-connect-to-redpanda page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/networking/k-connect-to-redpanda.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/networking/k-connect-to-redpanda.adoc description: Learn how to connect to a Redpanda cluster running in Kubernetes. page-git-created-date: "2024-01-04" page-git-modified-date: "2025-08-20" support-status: supported --- To work with a Redpanda cluster running in Kubernetes, you can connect clients to the listeners that are exposed by Redpanda brokers. Depending on how the listeners are configured, you can access them from within the Kubernetes cluster and/or from outside the Kubernetes cluster. | API | Purpose | | --- | --- | | Admin API | Operate Redpanda clusters. For example, you can modify the cluster’s configuration, decommission brokers, and place brokers in maintenance mode. | | Kafka API | Interact with the Kafka protocol in Redpanda. | | HTTP Proxy (PandaProxy) | Access your data through a REST API. For example, you can list topics or brokers, get events, and produce events. | | Schema Registry | Store and manage event schemas. For example, you can query supported serialization formats, register schemas for a subject, and retrieve schemas of specific versions. | ## [](#prerequisites)Prerequisites You must have the following: - Kubernetes cluster: Ensure you have a running Kubernetes cluster, either locally, such as with minikube or kind, or remotely. - [Kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl): Ensure you have the `kubectl` command-line tool installed and configured to communicate with your cluster. - Redpanda cluster: [Deploy a Redpanda cluster](../../../../deploy/redpanda/kubernetes/get-started-dev/). ## [](#connect-to-an-internal-cluster)Connect to an internal cluster To connect a client to Redpanda brokers running in the same Kubernetes cluster, use their [fully qualified domain names](../k-networking-and-connectivity/#internal-networking) (FQDNs) and the internal port of a listener. Together, the FQDN and internal port are called an endpoint. These endpoints may be secured using TLS and/or authentication. The `rpk` client on each Redpanda broker is pre-configured to connect to the internal Admin API, Kafka API, and Schema Registry of the local Redpanda cluster. To use other clients, such as a Kafka client, you must configure them. ### [](#connect-internally-with-a-local-rpk-client)Connect internally with a local `rpk` client The `rpk` command-line client, available on each Redpanda broker, allows you to communicate with the internal listeners of the Admin API, the Kafka API and Schema Registry. By default, the Redpanda Helm chart configures `rpk` with a local `redpanda.yaml` configuration file located in the `/etc/redpanda/` directory. As a result, you can use `rpk` from inside the container. For example, this command executes the `rpk cluster info` command: ```bash kubectl exec --namespace -- rpk cluster info ``` If you have SASL authentication enabled for the internal Kafka API listeners, you must specify the username, password, and SASL mechanism. ```bash kubectl exec --namespace -- rpk cluster info \ -X user= -X pass= -X sasl.mechanism= ``` You can also use environment variables instead of flags to specify the username, password, and SASL mechanism: ```bash export RPK_USER= export RPK_PASS= export RPK_SASL_MECHANISM= ``` For details about SASL authentication, see [Configure Authentication for Redpanda in Kubernetes](../../security/authentication/k-authentication/). ### [](#connect-to-the-internal-kafka-api)Connect to the internal Kafka API To connect to the internal Kafka API using a client other than `rpk`, you must configure the client with the correct endpoints, authentication credentials, and TLS certificates. You can find the connection details in the `/etc/redpanda/redpanda.yaml` file of any Pod that’s running a Redpanda broker: ```bash kubectl exec --namespace -- cat /etc/redpanda/redpanda.yaml ``` The `rpk.kafka_api.brokers` list contains the internal Kafka API endpoints of the Redpanda brokers: `redpanda.yaml` ```yaml rpk: kafka_api: brokers: - .redpanda..svc.cluster.local.:9093 - redpanda-1.redpanda..svc.cluster.local.:9093 - redpanda-2.redpanda..svc.cluster.local.:9093 ``` If the internal listeners have SASL authentication or TLS enabled, you must also configure your clients with valid credentials. To find out if a listener has authentication enabled, check the Helm values: ```bash helm get values --namespace --all ``` In this example, the Kafka API has SASL authentication enabled: ```yaml auth: sasl: enabled: true listeners: kafka: port: 9093 # default is "sasl" when empty or "null" authenticationMethod: null ``` If the internal listeners have TLS or mTLS enabled, you must configure your clients with valid TLS files. To find out if the Redpanda cluster has TLS or mTLS enabled, check the Helm values. In this example, the Kafka API has TLS and mTLS enabled: ```yaml listeners: kafka: port: 9093 tls: cert: default requireClientAuth: true ``` TLS files are stored in Secret resources that you can mount onto any Pods that run clients. TLS files may include: - Certificate files (`*.crt`): These files contain the public key and the identity (domain name) and are used for encryption. They can be self-signed or signed by a certificate authority (CA). - Key files (`*.key`): These contain the private key associated with the certificate. The private key should be kept secure and confidential. - CA files: These are certificates of the certificate authorities. They are used to verify if a given certificate is trusted. You can find the names of all TLS Secrets using this command: ```bash join -t $'\t' \ <(kubectl get pod --namespace -o jsonpath="{range .spec.containers[0].volumeMounts[*]}{.name}{'\t'}{.mountPath}{'\n'}{end}" | awk '$2 ~ /^\/etc\/tls\/certs\// {print $1"\t"$2}' | sort) \ <(kubectl get pod --namespace -o jsonpath="{range .spec.volumes[?(@.secret)]}{.name}{'\t'}{.secret.secretName}{'\n'}{end}" | sort) \ | awk 'BEGIN{printf "%-25s\t%-40s\n", "SECRET", "MOUNT PATH"} {printf "%-25s\t%-40s\n", $3, $2}' ``` For example: SECRET MOUNT PATH redpanda-client /etc/tls/certs/redpanda-client redpanda-default-cert /etc/tls/certs/default redpanda-external-cert /etc/tls/certs/external Then, you can mount the required Secrets into the Pods that run the clients: ```yaml apiVersion: v1 kind: Pod metadata: name: redpanda-client-pod labels: app: redpanda-client spec: volumes: - name: tls-certs secret: secretName: redpanda-client containers: - name: client-container image: example/client-image volumeMounts: - name: tls-certs mountPath: /etc/tls/certs readOnly: true ``` Now, you can configure clients with the mount path to the TLS files in your Secrets. For details about TLS, see [TLS for Redpanda in Kubernetes](../../security/tls/). ### [](#connect-to-the-internal-http-proxy)Connect to the internal HTTP Proxy To connect to the HTTP Proxy, use its configured internal port. 1. Check the Helm values to find the port: ```bash helm get values --namespace --all ``` In this example, the internal port is 8082. ```yaml listeners: http: port: 8082 ``` 2. Use the curl command-line client inside the container running a Redpanda broker: ```bash kubectl exec --namespace -- curl http://.redpanda..svc.cluster.local:8082/topics -sS ``` If SASL authentication is enabled, provide a valid username and password using basic authentication: ```bash kubectl exec --namespace -- curl http://.redpanda..svc.cluster.local:8082/topics -u : -sS ``` If TLS is enabled, specify the HTTPS protocol and pass the path to the `ca.crt` file: ```bash kubectl exec --namespace -- curl https://.redpanda..svc.cluster.local:8082/topics --cacert /etc/tls/certs/default/ca.crt -sS ``` > 📝 **NOTE** > > If the broker’s certificate is signed by a well-known, trusted CA, and you’re confident about the integrity of your system’s CA trust store, you don’t need the `--cacert` flag. If mTLS is enabled, pass the path to the client’s key and certificate: ```bash kubectl exec --namespace -- curl https://.redpanda..svc.cluster.local:8082/topics \ --cacert /etc/tls/certs/default/ca.crt \ --cert /etc/tls/certs/redpanda-client/tls.crt \ --key /etc/tls/certs/redpanda-client/tls.key ``` For all available endpoints, see the [HTTP Proxy API reference](/api/doc/http-proxy/). ### [](#connect-to-internal-schema-registry)Connect to internal Schema Registry #### rpk The [`rpk registry`](../../../../reference/rpk/rpk-registry/rpk-registry/) command can manage schemas directly: ```bash kubectl exec --namespace -- rpk registry subject list ``` #### curl To connect to the Schema Registry, use its configured internal port. 1. Check the Helm values to find the port: ```bash helm get values --namespace --all ``` In this example, the internal port is 8081. ```yaml listeners: schemaRegistry: port: 8081 ``` 2. Use the curl command-line client inside the container running a Redpanda broker: ```bash kubectl exec --namespace -- curl http://.redpanda..svc.cluster.local:8081/subjects -sS ``` If SASL authentication is enabled, provide a username and password using basic authentication: ```bash kubectl exec --namespace -- curl http://.redpanda..svc.cluster.local:8081/subjects -u : -sS ``` If TLS is enabled, specify the HTTPS protocol and pass the path to the `ca.crt` file: ```bash kubectl exec --namespace -- curl https://.redpanda..svc.cluster.local:8081/subjects --cacert /etc/tls/certs/default/ca.crt -sS ``` > 📝 **NOTE** > > If the broker’s certificate is signed by a well-known, trusted CA, and you’re confident about the integrity of your system’s CA trust store, you don’t need the `--cacert` flag. If mTLS is enabled, pass the path to the client’s key and certificate: ```bash kubectl exec --namespace -- curl https://.redpanda..svc.cluster.local:8081/subjects \ --cacert /etc/tls/certs/default/ca.crt \ --cert /path/to/client.crt \ --key /path/to/client.key ``` For all available endpoints, see the [Schema Registry API](/api/doc/schema-registry/). ### [](#connect-to-the-internal-admin-api)Connect to the internal Admin API #### rpk Using `rpk`, which is already configured inside the Redpanda Pod, you can interact with the Admin API. For example, to export cluster configuration: ```bash kubectl exec --namespace -- rpk cluster config export ``` If SASL is enabled, set your environment variables first: ```bash export RPK_USER= export RPK_PASS= export RPK_SASL_MECHANISM= ``` #### curl If you prefer to use curl from within the Redpanda Pod: ```bash kubectl exec --namespace -- curl http://.redpanda..svc.cluster.local:9644/v1/node_config -sS ``` If TLS is enabled, use `https` and `--cacert`: ```bash kubectl exec --namespace -- \ curl https://.redpanda..svc.cluster.local:9644/v1/node_config \ --cacert /etc/tls/certs/default/ca.crt -sS ``` If mTLS is enabled, also include the client certificate and key: ```bash kubectl exec --namespace -- \ curl https://.redpanda..svc.cluster.local:9644/v1/node_config \ --cacert /etc/tls/certs/default/ca.crt \ --cert /path/to/client.crt \ --key /path/to/client.key -sS ``` > 📝 **NOTE** > > If the broker’s certificate is signed by a well-known, trusted CA, and your system’s CA trust store is reliable, you may omit `--cacert`. For all available endpoints, see the [Admin API reference](/api/doc/admin/). ## [](#connect-to-an-external-cluster)Connect to an external cluster To connect to your Redpanda cluster from outside Kubernetes, the Redpanda cluster must be configured with external access. See [Configure External Access](../external/). ### [](#rpk-profile)Create an `rpk` profile An rpk profile contains a reusable configuration for a Redpanda cluster. When running `rpk`, you can create a profile, configure it for a cluster you’re working with, and use it repeatedly when running an `rpk` command for the cluster. When `external.enabled` is set to `true` (default), the Helm chart generates a ConfigMap that contains settings for an `rpk` profile. You can use these settings to connect to the cluster externally. The ConfigMap configures an `rpk` profile using the `listeners.admin.external.default` and `listeners.kafka.external.default` objects in Helm values. 1. [Install `rpk`](../../../../get-started/rpk-install/). 2. Configure `rpk` to use the profile in the ConfigMap: ```bash rpk profile create --from-profile <(kubectl get configmap --namespace redpanda-rpk -o go-template='{{ .data.profile }}') ``` 3. If you have SASL authentication enabled, you must configure `rpk` with a valid username and password. When you first deploy Redpanda, the Helm chart prints some notes with the commands necessary to configure a username and password locally. For example: ```bash kubectl --namespace get secret -o go-template="{{ range .data }}{{ . | base64decode }}{{ end }}" | IFS=: read -r RPK_USER RPK_PASS RPK_SASL_MECHANISM export RPK_USER RPK_PASS RPK_SASL_MECHANISM ``` 4. If you have TLS or mTLS enabled, you must save the TLS files to your local filesystem external to the Kubernetes cluster. When you first deploy Redpanda, the Helm chart prints some notes with the commands necessary to save the TLS files locally. For example: ```bash kubectl get secret --namespace -o go-template='{{ index .data "ca.crt" | base64decode }}' > ca.crt kubectl get secret --namespace -o go-template='{{ index .data "tls.crt" | base64decode }}' > tls.crt kubectl get secret --namespace -o go-template='{{ index .data "tls.key" | base64decode }}' > tls.key ``` For more details about `rpk` profiles, see [rpk Profiles](../../../../get-started/config-rpk-profile/). ### [](#connect-to-the-external-kafka-api)Connect to the external Kafka API To connect to the external Kafka API using a client other than `rpk`, you must configure the client with the correct broker endpoints, authentication credentials, and TLS certificates. You can find the connection details in the `/etc/redpanda/redpanda.yaml` file of any Pod that’s running a Redpanda broker: ```bash kubectl exec --namespace -- cat /etc/redpanda/redpanda.yaml ``` The `redpanda.advertised_kafka_api` list item called `default` contains the external Kafka API endpoints for the Redpanda brokers: `redpanda.yaml` ```yaml redpanda: advertised_kafka_api: - address: .redpanda..svc.cluster.local. port: 9093 name: internal - address: .customredpandadomain.local port: 31092 name: default ``` If the external listeners have SASL authentication enabled, you must also configure your clients with valid credentials. To find out if the Redpanda cluster has authentication enabled, check the Helm values: ```bash helm get values --namespace --all ``` In this example, the Kafka API has SASL authentication enabled: ```yaml auth: sasl: enabled: true listeners: kafka: external: default: # default is "sasl" when empty or "null" authenticationMethod: null ``` For details about SASL authentication, see [Configure Authentication for Redpanda in Kubernetes](../../security/authentication/k-authentication/). If the external listeners have TLS or mTLS enabled, you must configure your clients with valid TLS files. To find out if the Redpanda cluster has TLS enabled, check the Helm values. In this example, the Kafka API has TLS enabled: ```yaml listeners: kafka: external: default: # enabled: true port: 9094 advertisedPorts: - 31092 tls: # enabled: true cert: external ``` TLS files are stored in Secrets that you can mount onto the Pods that are running the clients. TLS files may include: - Certificate files (`*.crt`): These files contain the public key and the identity (domain name) and are used for encryption. They can be self-signed or signed by a certificate authority (CA). - Key files (`*.key`): These contain the private key associated with the certificate. The private key should be kept secure and confidential. - CA files: These are certificates of the certificate authorities. They are used to verify if a given certificate is trusted. You can find the names of all TLS Secrets using this command: ```bash join -t $'\t' \ <(kubectl get pod --namespace -o jsonpath="{range .spec.containers[0].volumeMounts[*]}{.name}{'\t'}{.mountPath}{'\n'}{end}" | awk '$2 ~ /^\/etc\/tls\/certs\// {print $1"\t"$2}' | sort) \ <(kubectl get pod --namespace -o jsonpath="{range .spec.volumes[?(@.secret)]}{.name}{'\t'}{.secret.secretName}{'\n'}{end}" | sort) \ | awk 'BEGIN{printf "%-25s\t%-40s\n", "SECRET", "MOUNT PATH"} {printf "%-25s\t%-40s\n", $3, $2}' ``` SECRET MOUNT PATH redpanda-client /etc/tls/certs/redpanda-client redpanda-default-cert /etc/tls/certs/default redpanda-external-cert /etc/tls/certs/external Then, you can save the TLS files to your local file system. For example: ```bash kubectl get secret --namespace redpanda-client -o go-template='{{ index .data "ca.crt" | base64decode }}' > ca.crt kubectl get secret --namespace redpanda-client -o go-template='{{ index .data "tls.crt" | base64decode }}' > tls.crt kubectl get secret --namespace redpanda-client -o go-template='{{ index .data "tls.key" | base64decode }}' > tls.key ``` Now, you can configure clients with the path to the TLS files. For details about TLS, see [TLS for Redpanda in Kubernetes](../../security/tls/). ### [](#connect-to-the-external-http-proxy)Connect to the external HTTP Proxy To connect to the HTTP Proxy, use its configured external port. To find the port, check the Helm values: ```bash helm get values --namespace --all ``` In this example, the external port on the container is 8082. The external node port on the worker node is 30082. ```yaml listeners: http: external: default: port: 8083 advertisedPorts: - 30082 ``` To test an external connection, you can use the curl command-line client inside the container running a Redpanda broker: ```bash curl http://.redpanda..svc.cluster.local:30082/topics -sS ``` If SASL authentication is enabled, provide a username and password using basic authentication: ```bash curl http://.redpanda..svc.cluster.local:30082/topics -u : -sS ``` If TLS is enabled, specify the HTTPS protocol and pass the path to the `ca.crt` file: ```bash curl https://.redpanda..svc.cluster.local:30082/topics --cacert /etc/tls/certs/external/ca.crt -sS ``` > 📝 **NOTE** > > If the broker’s certificate is signed by a well-known, trusted CA, and you’re confident about the integrity of your system’s CA trust store, you don’t need the `--cacert` flag. If mTLS is enabled, pass the path to the client’s key and certificate: ```bash curl https://.redpanda..svc.cluster.local:30082/topics \ --cacert /etc/tls/certs/external/ca.crt \ --cert /etc/tls/certs/external/tls.crt \ --key /etc/tls/certs/external/tls.key ``` For all available endpoints, see the [HTTP Proxy API reference](/api/doc/http-proxy/). ### [](#connect-to-external-schema-registry)Connect to external Schema Registry To connect to the Schema Registry with a HTTP client, use its configured external port. To find the port, check the Helm values: ```bash helm get values --namespace --all ``` In this example, the external port on the container is 8084. The external node port on the worker node is 30081. ```yaml listeners: schemaRegistry: external: default: port: 8084 advertisedPorts: - 30081 ``` To test an external connection, you can use the curl command-line client inside the container running a Redpanda broker: ```bash curl http://.redpanda..svc.cluster.local:30081/subjects -sS ``` If SASL authentication is enabled, provide a username and password using basic authentication: ```bash curl http://.redpanda..svc.cluster.local:30081/subjects -u : -sS ``` If TLS is enabled, specify the HTTPS protocol and pass the path to the `ca.crt` file: ```bash curl https://.redpanda..svc.cluster.local:30081/subjects --cacert /etc/tls/certs/external/ca.crt -sS ``` > 📝 **NOTE** > > If the broker’s certificate is signed by a well-known, trusted CA, and you’re confident about the integrity of your system’s CA trust store, you don’t need the `--cacert` flag. If mTLS is enabled, pass the path to the client’s key and certificate: ```bash curl https://.redpanda..svc.cluster.local:30081/subjects \ --cacert /etc/tls/certs/external/ca.crt \ --cert /etc/tls/certs/external/tls.crt \ --key /etc/tls/certs/external/tls.key ``` For all available endpoints, see the [Schema Registry API](/api/doc/schema-registry/). ### [](#connect-to-external-admin-api)Connect to external Admin API To connect to the Admin API using an HTTP client, use its configured external port. To find the port, check the Helm values: ```bash helm get values --namespace --all ``` In this example, the external port on the container is 8084. The external node port on the worker node is 30081. ```yaml listeners: schemaRegistry: external: default: port: 9645 advertisedPorts: - 31644 ``` To test an external connection, you can use the curl command-line client inside the container running a Redpanda broker: ```bash curl http://.redpanda..svc.cluster.local:31644/v1/node_config -sS ``` If TLS is enabled, specify the HTTPS protocol and pass the path to the `ca.crt` file: ```bash curl https://.redpanda..svc.cluster.local:31644/v1/node_config --cacert /etc/tls/certs/external/ca.crt -sS ``` > 📝 **NOTE** > > If the broker’s certificate is signed by a well-known, trusted CA, and you’re confident about the integrity of your system’s CA trust store, you don’t need the `--cacert` flag. If mTLS is enabled, pass the path to the client’s key and certificate: ```bash curl https://.redpanda..svc.cluster.local:31644/v1/node_config \ --cacert /etc/tls/certs/external/ca.crt \ --cert /etc/tls/certs/external/tls.crt \ --key /etc/tls/certs/external/tls.key ``` For all available endpoints, see the [Admin API reference](/api/doc/admin/). ## [](#next-steps)Next steps [Configure Listeners in Kubernetes](../k-configure-listeners/) ## [](#suggested-reading)Suggested reading - [About Networking and Connectivity in Kubernetes](../k-networking-and-connectivity/) - [rpk Profiles](../../../../get-started/config-rpk-profile/) - [Configure Authentication for Redpanda in Kubernetes](../../security/authentication/k-authentication/) - [TLS for Redpanda in Kubernetes](../../security/tls/) - [API Reference](../../../../reference/api-reference/) - [Kubernetes Helm Chart Specifications](../../../../reference/k-helm-index/) - [Kubernetes Custom Resource Definitions](../../../../reference/k-crd-index/) --- # Page 181: About Networking and Connectivity in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/networking/k-networking-and-connectivity.md --- # About Networking and Connectivity in Kubernetes --- title: About Networking and Connectivity in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/networking/k-networking-and-connectivity page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/networking/k-networking-and-connectivity.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/networking/k-networking-and-connectivity.adoc description: Learn how internal and external connectivity works when Redpanda is running in Kubernetes. page-git-created-date: "2024-01-04" page-git-modified-date: "2024-02-26" support-status: supported --- To work with a Redpanda cluster running in Kubernetes, clients connect to the listeners that are exposed by Redpanda brokers. Each listener exposes an API. Each API can have multiple listeners. Depending on how the listeners are configured, clients can access them from within the Kubernetes cluster and/or from outside the Kubernetes cluster. For example, one listener may be configured for internal connections and another may be configured for external connections. | API | Purpose | | --- | --- | | Admin API | Operate Redpanda clusters. For example, you can modify the cluster’s configuration, decommission brokers, and place brokers in maintenance mode. | | Kafka API | Interact with the Kafka protocol in Redpanda. | | HTTP Proxy (PandaProxy) | Access your data through a REST API. For example, you can list topics or brokers, get events, and produce events. | | Schema registry | Store and manage event schemas. For example, you can query supported serialization formats, register schemas for a subject, and retrieve schemas of specific versions. | ## [](#statefulsets-and-pod-identities)StatefulSets and Pod identities Redpanda is a stateful application. Each Redpanda broker needs to store its state, such as topic partitions, in its own storage volume. As a result, Redpanda is deployed in a StatefulSet to manage the Pods in which the Redpanda brokers are running. StatefulSets ensure that the state associated with a particular Pod replica is always the same, no matter how often the Pod is recreated. In a StatefulSet, each Pod is given a unique ordinal number in its name such as `redpanda-0`. A Pod with a particular ordinal number is always associated with a PersistentVolumeClaim with the same number. When a Pod in the StatefulSet is deleted and recreated, it is given the same ordinal number and so it mounts the same storage volume as the deleted Pod that it replaced. ## [](#internal-networking)Internal networking Internal networking facilitates communication between Redpanda brokers and clients within the same Kubernetes cluster. To allow both Redpanda brokers in the same Redpanda cluster and clients within the same Kubernetes cluster to communicate, Redpanda deploys a headless ClusterIP Service (headless Service). When a headless Service is associated with a StatefulSet, each Pod gets its own A/AAAA record that resolves directly to the individual Pod’s IP address. This setup is crucial for Kafka clients, allowing them to connect to the leader broker for specific partitions after retrieving broker addresses from any Redpanda broker’s Kafka API. For example, the IP address of the `redpanda-0` Pod is resolvable at the following address: ![Fully qualified domain name for a Pod called redpanda-0 in the redpanda namespace](../../../../shared/_images/headless-clusterip-dns.png) 1. Pod name 2. Service name 3. Service namespace 4. Cluster domain To allow internal clients to connect to individual brokers, each broker advertises these internal addresses on the internal listeners. For example, this is the Kafka API configuration for an internal listener: `/etc/redpanda/redpanda.yaml` ```yaml redpanda: advertised_kafka_api: - address: redpanda-0.redpanda.redpanda.svc.cluster.local. port: 9093 name: internal ``` ## [](#external-networking)External networking External clients cannot resolve the internal addresses of the headless ClusterIP Service because they are not in the Kubernetes cluster where the Redpanda brokers are running. Instead, Redpanda brokers must also advertise an externally accessible address that external clients can connect to. The Redpanda brokers advertise these addresses on the external listeners so that external clients can connect to individual brokers. For example, this is the Kafka API configuration for an external listener: `/etc/redpanda/redpanda.yaml` ```yaml redpanda: advertised_kafka_api: - address: redpanda-0.customredpandadomain.local port: 31092 name: default ``` To make the Redpanda brokers externally accessible, the Pods must be exposed through one of following Kubernetes Services: - NodePort (fastest and cheapest) - LoadBalancer ![A client connects to a Pod directly through the NodePort Service or indirectly through the load balancer](../../../../shared/_images/nodeport-loadbalancer.png) > 📝 **NOTE** > > To make each Redpanda broker addressable through a Service, each Redpanda broker should run on its own worker node. This way, clients or load balancers can use the address of the worker nodes to connect to specific Redpanda brokers. ### [](#nodeport-service)NodePort Service When you use a NodePort Service, each worker node that runs a Redpanda broker is allocated a port for each listener. All traffic to these ports is routed through the NodePort Service directly to the worker node’s local Pod that runs the Redpanda broker. Clients then connect to the addresses of the worker nodes. > 📝 **NOTE** > > The NodePort Service has its `service.spec.externalTrafficPolicy` configuration set to `Local` so that clients can send a request to a specific worker node and it will go to the local Redpanda broker on the node. For details, see [Traffic policies](https://kubernetes.io/docs/reference/networking/virtual-ips/#external-traffic-policy) in the Kubernetes documentation. ### [](#loadbalancer-service)LoadBalancer Service When you use LoadBalancer Services, each Redpanda broker needs its own LoadBalancer Service so that clients can address each broker individually. Behind each LoadBalancer Service, you need a load balancer instance that is hosted outside your Kubernetes cluster to forward traffic to the worker node. Clients then connect to the addresses of the load balancer instances. Using LoadBalancer Services is most useful on managed Kubernetes services because in these environments, the service provider usually creates the associated load balancer instances for you automatically. In bare-metal environments, you need to create the load balancer instances manually. > ❗ **IMPORTANT** > > Load balancers are slower than the NodePort Service. Load balancers force client traffic to make more network hops as the requests must go through the load balancer to get to the worker node, and then the LoadBalancer Service must forward the request to the local Pod. Load balancers are also expensive, so using a load balancer adds to the cost of running a cluster. ## [](#next-steps)Next steps Configure external access through a Service: - [NodePort](../external/k-nodeport/) - [LoadBalancer](../external/k-loadbalancer/) - [Configure individual listeners](../k-configure-listeners/) --- # Page 182: Security for Redpanda in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/security.md --- # Security for Redpanda in Kubernetes --- title: Security for Redpanda in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/security/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/security/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/security/index.adoc description: Learn what options are available for securing Redpanda clusters, including TLS encryption, authentication, authorization, and audit logging. page-git-created-date: "2023-06-02" page-git-modified-date: "2024-09-12" support-status: supported --- Learn what options are available for securing Redpanda clusters, including TLS encryption, authentication, authorization, and audit logging. Redpanda Data recommends that you configure the following security features in production environments. - [TLS for Redpanda in Kubernetes](tls/) Use TLS to authenticate Redpanda brokers and encrypt communication between clients and brokers. - [Authentication and Authorization for Redpanda in Kubernetes](authentication/) Learn how to configure authentication and authorization for Redpanda in Kubernetes using Helm values or the User resource with the Redpanda Operator. - [Audit Logging in Kubernetes](k-audit-logging/) Learn how to use Redpanda's audit logging capabilities. --- # Page 183: Authentication and Authorization for Redpanda in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/security/authentication.md --- # Authentication and Authorization for Redpanda in Kubernetes --- title: Authentication and Authorization for Redpanda in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/security/authentication/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/security/authentication/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/security/authentication/index.adoc description: Learn how to configure authentication and authorization for Redpanda in Kubernetes using Helm values or the User resource with the Redpanda Operator. page-git-created-date: "2024-10-30" page-git-modified-date: "2025-12-04" support-status: supported --- Redpanda offers two methods to manage authentication and authorization in a Kubernetes environment. These options allow administrators to control user access and permissions, ensuring secure communication with the Redpanda cluster. - [Configure Authentication for Redpanda in Kubernetes](k-authentication/) Use Helm values or the Redpanda resource manifest to enable authentication for Redpanda. This method provides a way to configure authentication during the initial deployment or updates to the cluster configuration. - [Manage Users and ACLs with the Redpanda Operator](k-user-controller/) Use the User resource to declaratively create and manage users and ACLs as part of a Redpanda deployment. Each User resource is mapped to a user in your Redpanda cluster. The user controller keeps the corresponding user in sync with the User resource. - [Manage Roles with the Redpanda Operator](../authorization/k-role-controller/) Use the RedpandaRole resource to declaratively create and manage roles as part of a Redpanda deployment. Each RedpandaRole resource defines a set of permissions that can be assigned to multiple users, providing role-based access control (RBAC) for your Redpanda cluster. - [Manage Groups and ACLs with the Redpanda Operator](../authorization/k-group-controller/) Use the Group resource to declaratively manage ACLs for OIDC groups as part of a Redpanda deployment. Each Group resource maps to an external OIDC group identity and manages the Kafka ACLs for that group principal. - [Manage Schema Registry ACLs with the Redpanda Operator](k-schema-registry-acls/) Manage Schema Registry ACLs declaratively in Kubernetes using User, RedpandaRole, and Group custom resources with the Redpanda Operator. --- # Page 184: Configure Authentication for Redpanda in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/security/authentication/k-authentication.md --- # Configure Authentication for Redpanda in Kubernetes --- title: Configure Authentication for Redpanda in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/security/authentication/k-authentication page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/security/authentication/k-authentication.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/security/authentication/k-authentication.adoc description: Use Helm values or the Redpanda resource manifest to enable authentication for Redpanda. This method provides a way to configure authentication during the initial deployment or updates to the cluster configuration. page-git-created-date: "2024-01-04" page-git-modified-date: "2025-07-31" support-status: supported --- Authentication verifies the identity of users and applications that connect to Redpanda clusters. Different Redpanda APIs support different authentication methods. You can configure multiple listeners for each API, and you can configure each listener with an authentication method. Redpanda APIs support these authentication methods: | API | Supported Authentication Methods | | --- | --- | | Kafka API | SASLSASL/SCRAMSASL/PLAINSASL/OAUTHBEARER (OIDC) | | Admin API | Basic authenticationOIDC | | HTTP Proxy (PandaProxy) | Basic authenticationOIDC | | Schema Registry | Basic authenticationOIDC | ## [](#principals)Users, principals, and superusers When you configure authentication and authorization in Redpanda, it’s important to understand the distinction between **users**, **principals**, and **superusers**: - A user refers to a stored credential within Redpanda, typically a username and password stored in the internal SASL credential store. These are created using commands such as `rpk security user create`. - A principal is the authenticated identity string associated with a client session. It’s what Redpanda uses for access control, ACLs, and superuser assignment. - A superuser is a privileged principal who has unrestricted access to [all operations](../../../../security/authorization/#operations) in a Redpanda cluster. Superusers can: - Grant or revoke permissions to other users through ACLs. - Access all Admin API endpoints. - Create, modify, or delete topics and consumer groups. - View and manage the cluster’s internal state. Depending on how a client authenticates, the principal might be: - The SCRAM username - A claim from a JWT - A certificate DN - A Kerberos identity You assign ACLs and superuser roles to principals, not users. Even if a user exists, they have no access unless its associated principal is granted permissions. For example, with OIDC: Configure superusers and ACL rules using the exact value from your OIDC token’s sub (subject) claim. For example, if your token’s sub claim is [example@company.com](mailto:example@company.com), use that exact value in your configuration. OIDC principals use the value extracted from the token’s claims according to your configured principal mapping. SASL users require the User: prefix, but OIDC principals do not use any prefix. ## [](#prerequisites)Prerequisites You must have the following: - Kubernetes cluster. Ensure you have a running Kubernetes cluster, either locally, such as with minikube or kind, or remotely. - [Kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl). Ensure you have the `kubectl` command-line tool installed and configured to communicate with your cluster. ## [](#enable)Enable authentication When you enable authentication in the Redpanda Helm chart: - SASL authentication is enabled for the Kafka API listeners - Basic authentication is enabled for the HTTP Proxy and Schema Registry listeners - Authorization is enabled When enabling authentication, you must create at least one superuser. Without a superuser, you can create other users, but you can’t grant them permissions to the cluster. > ⚠️ **CAUTION** > > Do not enable authorization without a superuser. Without a superuser, you may be locked out of the cluster and lose the ability to manage cluster settings or users. ### [](#create_superusers)Create superusers To create one or more superusers, you must define a username and password. You can also set the SASL/SCRAM authentication mechanism for each superuser. Redpanda supports the following SASL/SCRAM authentication mechanisms for the Kafka API: - `SCRAM-SHA-256` - `SCRAM-SHA-512` You can use the following to store superuser credentials: - [Use a Secret resource](#use-a-secret-resource) - [Use a YAML list](#use-a-yaml-list) For default values and documentation for configuration options, see the [`values.yaml`](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=auth.sasl) file. #### [](#use-a-secret-resource)Use a Secret resource To use a Secret resource to store superuser credentials: 1. Create a file in which to store the credentials. ```bash echo '::' >> superusers.txt ``` Replace the following placeholders with your own values for the superuser: - ``: The name of the superuser. - ``: The superuser’s password. - ``: The authentication mechanism. Valid values are `SCRAM-SHA-256` or `SCRAM-SHA-512`. Or, leave this placeholder empty to set it to the default authentication mechanism. The default is `SCRAM-SHA-512`. This default is applied to all superusers that don’t include an explicit authentication mechanism. 2. Use the file to create a Secret resource in the same namespace as your Redpanda cluster. ```bash kubectl --namespace create secret generic redpanda-superusers --from-file=superusers.txt ``` 3. Enable SASL and create the superuser using your Secret: ##### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: auth: sasl: enabled: true secretRef: "redpanda-superusers" users: [] ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ##### Helm ###### --values `enable-sasl.yaml` ```yaml auth: sasl: enabled: true secretRef: "redpanda-superusers" users: [] ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values enable-sasl.yaml --reuse-values ``` ###### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set auth.sasl.enabled=true \ --set auth.sasl.secretRef=redpanda-superusers \ --set "auth.sasl.users=null" ``` - `auth.sasl.enabled`: Enable authentication. - `auth.sasl.secretRef`: The name of the Secret that contains the superuser credentials. The Secret must be in the same namespace as the Redpanda cluster. - `auth.sasl.users`: Make sure that this list is empty. Otherwise, the chart will try to create a new Secret with the same name as the one set in `auth.sasl.secretRef` and fail because it already exists. #### [](#use-a-yaml-list)Use a YAML list You can use a YAML list item to store superuser credentials in configuration settings. Replace the following placeholders with your own values for the superuser: - ``: The name of the superuser. - ``: The superuser’s password. - ``: The authentication mechanism. Valid values are `SCRAM-SHA-256` or `SCRAM-SHA-512`. If you leave this placeholder empty, the Helm chart uses the default authentication mechanism. The default is `SCRAM-SHA-512`. This default is applied to all superusers that don’t include an explicit authentication mechanism. ##### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: auth: sasl: enabled: true secretRef: redpanda-superusers users: - name: password: mechanism: ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ##### Helm ###### --values `enable-sasl.yaml` ```yaml auth: sasl: enabled: true secretRef: redpanda-superusers users: - name: password: mechanism: ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values sasl-enable.yaml --reuse-values ``` ###### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set auth.sasl.enabled=true \ --set auth.sasl.secretRef=redpanda-superusers \ --set "auth.sasl.users[0].name=" \ --set "auth.sasl.users[0].password=" \ --set "auth.sasl.users[0].mechanism=" ``` - `auth.sasl.enabled`: Enable authentication. - `auth.sasl.secretRef`: The name of the Secret that the Redpanda Helm chart will create and use to store the superuser credentials listed in `auth.sasl.users`. This Secret must not already exist in the cluster. - `auth.sasl.users`: A list of superusers. > 📝 **NOTE** > > As a security best practice: > > - Don’t use the superuser to interact with the cluster. > > - Don’t delete the superuser (in case you need to grant permissions to new users later). > > When you create the superuser, you specify a password, which adds a level of security. If you delete the user, someone else could re-create the user with a different password. ### [](#edit-superusers)Edit superusers You can add new superusers to the cluster or update existing users. For example, if you wanted to rotate credentials for superusers, you could update the username or password of an existing superuser. > 📝 **NOTE** > > You cannot delete superusers by changing the Helm values or updating the Secret. - If you created superusers using a Secret, you can edit the `superusers.txt` file and reapply the Secret resource: ```bash kubectl create secret generic redpanda-superusers \ --namespace \ --from-file=superusers.txt \ --save-config \ --dry-run=client -o yaml | kubectl apply -f - ``` The [`config-watcher` sidecar](../../../../../reference/k-redpanda-helm-spec/#statefulset-sidecars-configwatcher-enabled) in the Pod watches the superusers Secret for changes. When changes are observed, it creates and updates users accordingly. - If you created superusers using a YAML list, you can update the list: #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: auth: sasl: enabled: true secretRef: redpanda-superusers users: - name: password: mechanism: ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `enable-sasl.yaml` ```yaml auth: sasl: enabled: true secretRef: redpanda-superusers users: - name: password: mechanism: ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values sasl-enable.yaml --reuse-values ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set auth.sasl.enabled=true \ --set auth.sasl.secretRef=redpanda-superusers \ --set "auth.sasl.users[0].name=" \ --set "auth.sasl.users[0].password=" \ --set "auth.sasl.users[0].mechanism=" ``` ## [](#authentication-for-the-kafka-api)Authentication for the Kafka API Redpanda supports the following authentication methods for the Kafka API: - [SASL](#sasl) (Simple Authentication and Security Layer) ### [](#sasl)SASL SASL provides a flexible and adaptable framework for implementing various authentication mechanisms. Redpanda supports these SASL mechanisms: - [SASL/SCRAM](#scram) - [SASL/PLAIN](#plain) - [SASL/OAUTHBEARER](#oidc) (OpenID Connect, also known as OIDC) > 📝 **NOTE** > > Redpanda provides an option to configure different SASL authentication mechanisms for specific listeners. For example, you could specify SCRAM for internal traffic and OAUTHBEARER for external clients. For details, see [sasl\_mechanisms\_overrides](../../../../../reference/properties/cluster-properties/#sasl_mechanisms_overrides). #### [](#enable-sasl)Enable SASL To enable SASL authentication for the Kafka API, set the [`authentication_method`](../../../../../reference/properties/broker-properties/#kafka_api_auth_method) broker property of the Kafka listeners to `sasl`. The Redpanda Helm chart sets the [`authentication_method`](../../../../../reference/properties/broker-properties/#kafka_api_auth_method) broker property to `sasl` for all Kafka listeners by default when you [enable authentication](#enable-authentication). #### [](#enable-sasl-with-tls-encryption)Enable SASL with TLS encryption SASL provides authentication, but not encryption. To provide encryption, you can enable TLS in addition to SASL. See [TLS for Redpanda in Kubernetes](../../tls/). TLS is enabled in the Helm chart by default. #### [](#scram)SASL/SCRAM SASL/SCRAM does not require sending passwords over the network, even in an encrypted form. It uses a challenge-response mechanism, ensuring that the password is not directly accessible to the server. It works with hashed passwords, providing additional security against dictionary attacks. ##### [](#create-scram-users)Create SCRAM users When you have SASL authentication enabled for your Redpanda cluster, you can create SCRAM users. Redpanda supports the following SASL/SCRAM authentication mechanisms for the Kafka API: - `SCRAM-SHA-256` - `SCRAM-SHA-512` By default, SCRAM users don’t have any permissions in the cluster. Only superusers can grant permissions to new users through ACLs. 1. To create the SCRAM user `` with a password ``, run [`rpk security user create`](../../../../../reference/rpk/rpk-security/rpk-security-user-create/): ```bash rpk security user create \ -p '' \ --mechanism SCRAM-SHA-256 ``` > 💡 **TIP** > > Enclose passwords in single quotes to avoid conflicts with special characters. Enclosing characters in single quotes preserves the literal value of each character. 2. Use the [`rpk security acl create`](../../../../../reference/rpk/rpk-security/rpk-security-acl-create/) command to grant [`create` and `describe` permissions](../../../../security/authorization/acl/) to `myuser` in the cluster: ```bash rpk security acl create --allow-principal User:myuser \ --operation create,describe \ --cluster \ -X user= \ -X pass='' \ -X sasl.mechanism= ``` 3. Grant the new user `describe` privileges for a topic called `myfirsttopic`: ```bash rpk security acl create --allow-principal User:myuser \ --operation describe \ --topic myfirsttopic \ -X user= \ -X pass='' \ -X sasl.mechanism= ``` > 📝 **NOTE** > > You must grant privileges for specific topics. Even if a user has `describe` privileges for a cluster, it does not mean that the user is granted `describe` privileges for topics. See also: [User create](../../../../security/authorization/#user-create). ##### [](#connect-to-redpanda)Connect to Redpanda This section provides examples of connecting to Redpanda as a SCRAM user when SASL/SCRAM authentication is enabled. Create a topic as the `myuser` user by running [`rpk topic create`](../../../../../reference/rpk/rpk-topic/rpk-topic-create/): ```bash rpk topic create myfirsttopic \ -X user=myuser \ -X pass='changethispassword' \ -X sasl.mechanism=SCRAM-SHA-256 ``` To describe the topic, run [`rpk topic describe`](../../../../../reference/rpk/rpk-topic/rpk-topic-describe/): ```bash rpk topic describe myfirsttopic \ -X user=myuser \ -X pass='changethispassword' \ -X sasl.mechanism=SCRAM-SHA-256 ``` For more details on connecting to Redpanda, see [Connect to Redpanda in Kubernetes](../../../networking/k-connect-to-redpanda/). ##### [](#schema-and-http-to-redpanda)Configure Schema Registry and HTTP Proxy to connect to Redpanda with SASL Schema Registry and HTTP Proxy connect to Redpanda over the Kafka API. **Breaking change in Redpanda 25.2:** Ephemeral credentials for HTTP Proxy are removed. If your HTTP Proxy API listeners use [`authentication_method`](../../../../../reference/properties/broker-properties/#http_proxy_auth_method): `none`, you must configure explicit SASL credentials ([`scram_username`](../../../../../reference/properties/broker-properties/#scram_username), [`scram_password`](../../../../../reference/properties/broker-properties/#scram_password), and [`sasl_mechanism`](../../../../../reference/properties/broker-properties/#sasl_mechanism)) for HTTP Proxy to authenticate with the Kafka API. > ⚠️ **WARNING** > > This allows any HTTP API user to access Kafka using shared credentials. Redpanda Data recommends enabling [HTTP Proxy authentication](../../../../../develop/http-proxy/#authenticate-with-http-proxy) instead. For details about this breaking change, see [What’s new](../../../../../get-started/release-notes/redpanda/#http-proxy-authentication-changes). Schema Registry and HTTP Proxy support only the SASL/SCRAM mechanism. #### [](#plain)SASL/PLAIN You can configure Kafka clients to authenticate using either SASL/SCRAM or SASL/PLAIN with a single account using the same username and password. Unlike SASL/SCRAM, which uses a challenge response with hashed credentials, SASL/PLAIN transmits plaintext passwords. While not required, it is recommended that you use TLS for external encryption when using SASL/PLAIN authentication. If you have existing PLAIN Kafka clients and applications, you can migrate to Redpanda without updating your application by creating local Redpanda SCRAM accounts and enabling PLAIN as an authentication mechanism. > 📝 **NOTE** > > Clusters configured with _only_ a SASL/PLAIN mechanism are not supported. ##### [](#enable-saslplain)Enable SASL/PLAIN You must enable SASL/PLAIN explicitly by appending PLAIN to the list of SASL mechanisms: ###### Helm + Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: auth: sasl: enabled: true secretRef: redpanda-superusers config: cluster: sasl_mechanisms: - "SCRAM" - "PLAIN" ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ###### Helm ###### --values `enable-sasl.yaml` ```yaml auth: sasl: enabled: true secretRef: redpanda-superusers config: cluster: sasl_mechanisms: - "SCRAM" - "PLAIN" ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values sasl-enable.yaml --reuse-values ``` ###### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set auth.sasl.enabled=true \ --set auth.sasl.secretRef=redpanda-superusers \ --set "config.cluster.sasl_mechanisms[0]=SCRAM" \ --set "config.cluster.sasl_mechanisms[1]=PLAIN" \ ``` #### [](#oidc)OAUTHBEARER (OIDC) > 📝 **NOTE** > > OpenID Connect (OIDC) authentication requires an [enterprise license](../../../../../get-started/licensing/). To upgrade, contact [Redpanda sales](https://redpanda.com/try-redpanda?section=enterprise-trial). When you enable [OIDC](https://openid.net/developers/how-connect-works/), Redpanda and Redpanda Console can delegate the authentication process to an external identity provider (IdP) such as Okta, Microsoft Entra ID, or on-premise Active Directory Federation Service (AD FS). With OIDC enabled, Redpanda does not need to manage user credentials directly, but can instead rely on the trusted authentication capabilities of established IdPs. Redpanda’s implementation of OIDC provides SASL/OAUTHBEARER support for the Kafka API, and supports standard OIDC authentication across all other HTTP APIs, including Schema Registry, HTTP Proxy, and the Admin API. > 💡 **TIP** > > With OIDC enabled, you can also use [group-based access control (GBAC)](../../../../security/authorization/gbac/) to assign Redpanda permissions to OIDC groups instead of individual users. To use GBAC, configure your IdP to include group claims in the access token (for example, a `groups` claim). See your IdP’s documentation for how to add group claims to tokens. ##### [](#oidc-limitations)OIDC limitations - Redpanda requires JWT-formatted access tokens (not ID tokens) for Kafka API authentication using SASL/OAUTHBEARER. Access tokens issued by some IdPs, such as Google, are opaque and not supported. - The `rpk` CLI does not support OIDC login. - Redpanda requires OIDC principals to be set as superusers to access the Admin API. Granular authorization is not supported. - The `rpk` CLI does not support the SASL/OAUTHBEARER mechanism for deploying data transforms. Use SASL/SCRAM instead. ##### [](#oidc-credentials-flow-and-access-token-validation)OIDC credentials flow and access token validation Before configuring OIDC, you should understand the credentials flow, and in particular, the validation claims included in the access token, as you will need to provide them in the OIDC configuration. Redpanda’s implementation of OIDC adheres to the client credentials flow defined in [OAuth 2.0 RFC 6749, section 4.4](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) in which a client obtains an access token from the authorization server, and provides this access token to Redpanda, either using SASL/OAUTHBEARER for the Kafka API, or an HTTP Authorization (Bearer) header. The access token is a _bearer token_. A bearer token is used for authentication and authorization in web applications and APIs, and holds user credentials, usually in the form of random strings of characters. Bearer tokens are generated based on protocols and specifications such as JWT (JSON Web Token), which has a header, payload, and signature. The signature must be verified according to the JWK. Claims inside the token and the token signature must both be validated. After validation, a configurable claim from the token payload is extracted as the principal and attached to the connection, as with any other authentication method. Following is an example JWT header: ```json { "alg": "RS256", "typ": "JWT", "kid": "tMQzailSAdaW4nojXxES9" } ``` Following is an example JWT payload: ```json { "iss": "https://dev-ltxchcls4igzho78.us.auth0.com/", "sub": "3JJeI4tmMC6v8mCVCSDnAGVf2vrnJ0BT@clients", "aud": "localhost", "iat": 1694430088, "exp": 1694516488, "azp": "3JJeI4tmMC6v8mCVCSDnAGVf2vrnJ0BT", "scope": "email2", "gty": "client-credentials" } ``` Following are additional validation claims (JWT properties) that are included in the access token: - `alg`: The signature algorithm. The extension point in the JWT header is the signature algorithm used to sign the token, and cannot contain the value `none`. - `aud`: Audience. Must match the configuration specified in `oidc_token_audience`. Cannot contain the value `none`. - `kid`: Key identifier. Must match _any_ of the public JWK listed in the `jwks_uri` endpoint. - `exp`: Expiration. The timestamp listed is greater than current time. Must validate within acceptable bounds of the value specified in `oidc_clock_skew_tolerance`. A clock skew tolerance period may be configured by an Admin to account for clock drift between Redpanda and the OIDC Identity Provider (IdP). - `iss`: Issuer. Must exactly match the `issuer` property of the JSON returned from the URL specified in `oidc_discovery_url`. - `scope`: Scope. Must include the value `openid`. - `sub`: Subject. This default claim identifies the principal subject. While `sub` is the default mapping (`$.sub`) in Redpanda, any claim within the JWT can be mapped to a Redpanda principal. ##### [](#enable-oidc)Enable OIDC 1. Register a client application with your IdP. A client application, in this context, refers to any application or service that will authenticate against the Redpanda cluster using OIDC. This registration process involves creating a new entry in the IdP’s management console for the application, sometimes called a client. During this process, you’ll specify details about your application, such as the type of application, the callback URLs, and any other required information as per your IdP’s requirements. In an enterprise environment, OIDC integration typically requires coordination with your organization’s security team. 2. [Enable SASL authentication](#enable-authentication) if it’s not already enabled. 3. Configure [ACLs](../../../../security/authorization/#acls) for your users so they can access Redpanda resources. 4. Configure OIDC: ###### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: auth: sasl: enabled: true secretRef: redpanda-superusers config: cluster: sasl_mechanisms: - "SCRAM" - "OAUTHBEARER" oidc_discovery_url: "" oidc_token_audience: "" oidc_principal_mapping: "" oidc_clock_skew_tolerance: oidc_token_expire_disconnect: oidc_keys_refresh_interval: ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ###### Helm ###### --values `enable-sasl.yaml` ```yaml auth: sasl: enabled: true secretRef: redpanda-superusers config: cluster: sasl_mechanisms: - "SCRAM" - "OAUTHBEARER" oidc_discovery_url: "" oidc_token_audience: "" oidc_principal_mapping: "" oidc_clock_skew_tolerance: oidc_token_expire_disconnect: oidc_keys_refresh_interval: ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values sasl-enable.yaml --reuse-values ``` ###### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set auth.sasl.enabled=true \ --set auth.sasl.secretRef=redpanda-superusers \ --set "config.cluster.sasl_mechanisms[0]=SCRAM" \ --set "config.cluster.sasl_mechanisms[1]=OAUTHBEARER" \ --set config.cluster.oidc_discovery_url="" \ --set config.cluster.oidc_token_audience="" \ --set config.cluster.oidc_principal_mapping="" \ --set config.cluster.oidc_clock_skew_tolerance= \ --set config.cluster.oidc_token_expire_disconnect= \ --set config.cluster.oidc_keys_refresh_interval= ``` - `config.cluster.sasl_mechanisms`: Enable SCRAM and OIDC SASL mechanisms. - `config.cluster.oidc_discovery_url`: The discovery URL of your identity provider (IdP). The default is `[https://auth.prd.cloud.redpanda.com/.well-known/openid-configuration](https://auth.prd.cloud.redpanda.com/.well-known/openid-configuration)`. - `config.cluster.oidc_token_audience`: The intended audience of the token. The default is `redpanda`. - `config.cluster.oidc_principal_mapping`: The principal mapping, which is a JSON path that extracts a principal from any claim in the access token payload. The default is `$.sub`. - `config.cluster.oidc_clock_skew_tolerance`: The amount of time (in seconds) to allow for when validating the expiration claim in the token. - `config.cluster.oidc_token_expire_disconnect`: Whether to enable OIDC to disconnect clients when their token expires. - `config.cluster.oidc_keys_refresh_interval`: The amount of time keys from the `jwks_uri` are cached. ## [](#authentication-for-the-http-apis)Authentication for the HTTP APIs Redpanda provides the following HTTP APIs that support authentication: - Admin API: Management and monitoring of the Redpanda cluster - Schema Registry API: Management of schemas and schema evolution - HTTP Proxy API: RESTful interface for Kafka clients ### [](#permission-models)Permission models Each of the HTTP APIs implements its own permission model with different levels of access control. This section lists what permissions are available to different user types, and how to enable authentication. #### [](#admin-api-permissions)Admin API permissions The Admin API primarily requires superuser privileges, with a few exceptions for read-only status endpoints. For a complete list of all Admin API endpoints, see the [Admin API reference](/api/doc/admin/). #### [](#schema-registry-api-permissions)Schema Registry API permissions The Schema Registry implements a granular permission model. Most read operations require only user-level authentication, while write operations that affect the global state or mode typically require superuser privileges. #### [](#http-proxy-permissions)HTTP Proxy permissions The HTTP Proxy API impersonates the authenticated user when making Kafka API calls: Regular users are subject to the same ACL restrictions as they would be when using the Kafka API directly. ### [](#enable-authentication)Enable authentication Redpanda supports authentication for the HTTP APIs using either basic authentication or OIDC (OpenID Connect). #### [](#prerequisites-2)Prerequisites Before enabling authentication for the HTTP APIs, you must [enable SASL authentication for the Kafka API](#sasl). This creates the credential store that HTTP authentication will use. #### [](#basic-authentication)Basic authentication > 📝 **NOTE** > > Redpanda Data recommends that you use TLS when enabling HTTP Basic Auth. Basic authentication provides a method for securing HTTP endpoints. With basic authentication enabled, HTTP user agents, such as web browsers, must provide a username and password when making a request. To add users to the Redpanda credential store that HTTP basic authentication uses, create users with [`rpk security user create`](../../../../../reference/rpk/rpk-security/rpk-security-user-create/). The HTTP Proxy API and the Schema Registry API use the same credential store as the Kafka API, so you can use the same credentials for all three APIs. The Admin API uses the same credential store as the Kafka API, but it requires superuser credentials to access it. When you [enable authentication](#enable-authentication) in the Redpanda Helm chart, the Schema Registry API and the HTTP Proxy API are configured with basic authentication by default. To enable basic authentication for the Admin API: ##### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: auth: sasl: enabled: true secretRef: redpanda-superusers config: cluster: admin_api_require_auth: true ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ##### Helm ###### --values `enable-sasl.yaml` ```yaml auth: sasl: enabled: true secretRef: redpanda-superusers config: cluster: admin_api_require_auth: true ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values sasl-enable.yaml --reuse-values ``` ###### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set auth.sasl.enabled=true \ --set auth.sasl.secretRef=redpanda-superusers \ --set config.cluster.admin_api_require_auth=true ``` ##### [](#connect-to-the-http-api)Connect to the HTTP API By default, the Redpanda Helm chart configures an internal and external listener for the HTTP Proxy API. To access the internal listener: ```bash kubectl exec --namespace -- curl http://redpanda-0.redpanda.redpanda.svc.cluster.local:8082/topics -u : -sS ``` If TLS is enabled, specify the HTTPS protocol and pass the path to the `ca.crt` file: ```bash kubectl exec --namespace -- curl https://redpanda-0.redpanda.redpanda.svc.cluster.local:8082/topics --cacert /etc/tls/certs/default/ca.crt -u : -sS ``` > 📝 **NOTE** > > If the broker’s certificate is signed by a well-known, trusted CA, and you’re confident about the integrity of your system’s CA trust store, you don’t need the `--cacert` flag. For all available endpoints, see the [HTTP Proxy API reference](/api/doc/http-proxy/). ##### [](#connect-to-the-schema-registry-api)Connect to the Schema Registry API By default, the Redpanda Helm chart configures an internal and external listener for the Schema Registry API. To access the internal listener: ```bash kubectl exec --namespace -- curl http://redpanda-0.redpanda.redpanda.svc.cluster.local:8081/subjects -u : -sS ``` If TLS is enabled, specify the HTTPS protocol and pass the path to the `ca.crt` file: ```bash kubectl exec --namespace -- curl https://redpanda-0.redpanda.redpanda.svc.cluster.local:8081/subjects --cacert /etc/tls/certs/default/ca.crt -u : -sS ``` > 📝 **NOTE** > > If the broker’s certificate is signed by a well-known, trusted CA, and you’re confident about the integrity of your system’s CA trust store, you don’t need the `--cacert` flag. For all available endpoints, see the [Schema Registry API](/api/doc/schema-registry/). #### [](#oidc-http)OIDC You can configure the HTTP APIs to authenticate users with the OIDC bearer token. By using OIDC, you can centralize credentials and provide a password-free SSO experience. See [Enable OIDC](#enable-oidc) to configure the required OIDC cluster configuration properties before enabling OIDC for the HTTP APIs. You can configure OIDC without enabling it for the Kafka API. > 📝 **NOTE** > > If you enable OIDC authentication for the Admin API, you must also [create a SCRAM superuser](#create-superusers) so that you can use `rpk` to create ACLs. `rpk` supports only basic authentication for the Admin API. See [Authentication for the HTTP APIs](#authentication-for-the-http-apis). To enable OIDC for the HTTP API listeners as well as basic authentication, include OIDC in the `http_authentication` cluster property list: > 📝 **NOTE** > > Valid values for the cluster configuration property [`http_authentication`](../../../../../reference/properties/cluster-properties/#http_authentication) (cluster-wide) are `BASIC` and `OIDC`. The value `BASIC` here is different from the per-listener setting `http_basic`, which enables authentication on a listener using the broker property `authentication_method` (see [`authentication_method`](../../../../../reference/properties/broker-properties/#schema_registry_auth_method) for the Schema Registry listener and [`authentication_method`](../../../../../reference/properties/broker-properties/#http_proxy_auth_method) for the HTTP Proxy listener). ##### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: auth: sasl: enabled: true config: cluster: sasl_mechanisms: - "SCRAM" - "OAUTHBEARER" http_authentication: - "BASIC" - "OIDC" ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ##### Helm ###### --values `enable-sasl.yaml` ```yaml auth: sasl: enabled: true config: cluster: sasl_mechanisms: - "SCRAM" - "OAUTHBEARER" http_authentication: - "BASIC" - "OIDC" ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values sasl-enable.yaml --reuse-values ``` ###### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set auth.sasl.enabled=true \ --set "config.cluster.sasl_mechanisms[0]=SCRAM" \ --set "config.cluster.sasl_mechanisms[1]=OAUTHBEARER" \ --set "config.cluster.http_authentication[0]=BASIC" \ --set "config.cluster.http_authentication[1]=OIDC" ``` ##### [](#connect-to-the-http-api-2)Connect to the HTTP API By default, the Redpanda Helm chart configures an internal and external listener for the HTTP Proxy API. To access the internal listener: ```bash kubectl exec --namespace -- curl http://redpanda-0.redpanda.redpanda.svc.cluster.local:8082/topics -H "Authorization: Bearer " -sS ``` If TLS is enabled, specify the HTTPS protocol and pass the path to the `ca.crt` file: ```bash kubectl exec --namespace -- curl https://redpanda-0.redpanda.redpanda.svc.cluster.local:8082/topics --cacert /etc/tls/certs/default/ca.crt -H "Authorization: Bearer " -sS ``` > 📝 **NOTE** > > If the broker’s certificate is signed by a well-known, trusted CA, and you’re confident about the integrity of your system’s CA trust store, you don’t need the `--cacert` flag. For all available endpoints, see the [HTTP Proxy API reference](/api/doc/http-proxy/). ##### [](#connect-to-the-schema-registry-api-2)Connect to the Schema Registry API By default, the Redpanda Helm chart configures an internal and external listener for the Schema Registry API. To access the internal listener: ```bash kubectl exec --namespace -- curl http://redpanda-0.redpanda.redpanda.svc.cluster.local:8081/subjects -H "Authorization: Bearer " -sS ``` If TLS is enabled, specify the HTTPS protocol and pass the path to the `ca.crt` file: ```bash kubectl exec --namespace -- curl https://redpanda-0.redpanda.redpanda.svc.cluster.local:8081/subjects --cacert /etc/tls/certs/default/ca.crt -H "Authorization: Bearer " -sS ``` > 📝 **NOTE** > > If the broker’s certificate is signed by a well-known, trusted CA, and you’re confident about the integrity of your system’s CA trust store, you don’t need the `--cacert` flag. For all available endpoints, see the [Schema Registry API](/api/doc/schema-registry/). ## [](#disable-authentication)Disable authentication To disable authentication for a listener, set [`authentication_method`](../../../../../reference/properties/broker-properties/#kafka_api_auth_method) broker property to `none`: **Breaking change in Redpanda 25.2:** Ephemeral credentials for HTTP Proxy are removed. If your HTTP Proxy API listeners use [`authentication_method`](../../../../../reference/properties/broker-properties/#http_proxy_auth_method): `none`, you must configure explicit SASL credentials ([`scram_username`](../../../../../reference/properties/broker-properties/#scram_username), [`scram_password`](../../../../../reference/properties/broker-properties/#scram_password), and [`sasl_mechanism`](../../../../../reference/properties/broker-properties/#sasl_mechanism)) for HTTP Proxy to authenticate with the Kafka API. > ⚠️ **WARNING** > > This allows any HTTP API user to access Kafka using shared credentials. Redpanda Data recommends enabling [HTTP Proxy authentication](../../../../../develop/http-proxy/#authenticate-with-http-proxy) instead. For details about this breaking change, see [What’s new](../../../../../get-started/release-notes/redpanda/#http-proxy-authentication-changes). ### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: auth: sasl: enabled: true listeners: http: authentication_method: "none" schemaRegistry: authentication_method: "none" kafka: authentication_method: "none" ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ### Helm #### --values `enable-sasl.yaml` ```yaml auth: sasl: enabled: true listeners: http: authentication_method: "none" schemaRegistry: authentication_method: "none" kafka: authentication_method: "none" ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values sasl-enable.yaml --reuse-values ``` #### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set auth.sasl.enabled=true \ --set listeners.http.authentication_method=none \ --set listeners.schemaRegistry.authentication_method=none \ --set listeners.kafka.authentication_method=none ``` ## [](#generate-security-report)Generate security report Use the [`/v1/security/report`](/api/doc/admin/operation/operation-get_security_report) endpoint to generate a comprehensive security report for your cluster. This endpoint provides detailed information about current TLS configuration, authentication methods, authorization status, and security alerts across all Redpanda interfaces (Kafka, RPC, Admin, Schema Registry, HTTP Proxy). To generate a security report for your Redpanda cluster, run: Input ```bash curl 'http://localhost:9644/v1/security/report' ``` View output ```bash { "interfaces": { "kafka": [ { "name": "test_kafka_listener", "host": "0.0.0.0", "port": 9092, "advertised_host": "0.0.0.0", "advertised_port": 9092, "tls_enabled": false, "mutual_tls_enabled": false, "authentication_method": "None", "authorization_enabled": false } ], "rpc": { "host": "0.0.0.0", "port": 33145, "advertised_host": "127.0.0.1", "advertised_port": 33145, "tls_enabled": false, "mutual_tls_enabled": false }, "admin": [ { "name": "test_admin_listener", "host": "0.0.0.0", "port": 9644, "tls_enabled": false, "mutual_tls_enabled": false, "authentication_methods": [], "authorization_enabled": false } ] }, "alerts": [ { "affected_interface": "kafka", "listener_name": "test_kafka_listener", "issue": "NO_TLS", "description": "\"kafka\" interface \"test_kafka_listener\" is not using TLS. This is insecure and not recommended." }, { "affected_interface": "kafka", "listener_name": "test_kafka_listener", "issue": "NO_AUTHN", "description": "\"kafka\" interface \"test_kafka_listener\" is not using authentication. This is insecure and not recommended." }, { "affected_interface": "kafka", "listener_name": "test_kafka_listener", "issue": "NO_AUTHZ", "description": "\"kafka\" interface \"test_kafka_listener\" is not using authorization. This is insecure and not recommended." }, { "affected_interface": "rpc", "issue": "NO_TLS", "description": "\"rpc\" interface is not using TLS. This is insecure and not recommended." }, { "affected_interface": "admin", "listener_name": "test_admin_listener", "issue": "NO_TLS", "description": "\"admin\" interface \"test_admin_listener\" is not using TLS. This is insecure and not recommended." }, { "affected_interface": "admin", "listener_name": "test_admin_listener", "issue": "NO_AUTHZ", "description": "\"admin\" interface \"test_admin_listener\" is not using authorization. This is insecure and not recommended." }, { "affected_interface": "admin", "listener_name": "test_admin_listener", "issue": "NO_AUTHN", "description": "\"admin\" interface \"test_admin_listener\" is not using authentication. This is insecure and not recommended." } ] } ``` ## [](#troubleshoot)Troubleshoot This section lists error messages and provides ways to diagnose and solve issues. For more troubleshooting steps, see [Troubleshoot Redpanda in Kubernetes](../../../../../troubleshoot/errors-solutions/k-resolve-errors/). ### [](#unable-to-continue-with-update-secret)Unable to continue with update: Secret When you use a YAML list to specify superusers, the Helm chart creates a Secret using the value of `auth.sasl.secretRef` as the Secret’s name, and stores those superusers in the Secret. If the Secret already exists in the namespace when you deploy Redpanda, the following error is displayed: Error: UPGRADE FAILED: rendered manifests contain a resource that already exists. Unable to continue with update: Secret To fix this error, ensure that you use only one of the following methods to create superusers: - `auth.sasl.secretRef` - `auth.sasl.users` ### [](#is-sasl-missing)Is SASL missing? This error appears when you try to interact with a cluster that has SASL enabled without passing a user’s credentials. unable to request metadata: broker closed the connection immediately after a request was issued, which happens when SASL is required but not provided: is SASL missing? If you’re using `rpk`, ensure to specify the `-X user`, `-X pass`, and `-X sasl.mechanism` flags. For all available flags, see the [`rpk` options reference](../../../../../reference/rpk/rpk-x-options/). ## [](#next-steps)Next steps - [Configure Authorization](../../../../security/authorization/) - [Configure Listeners in Kubernetes](../../../networking/k-configure-listeners/) - [Connect to Redpanda in Kubernetes](../../../networking/k-connect-to-redpanda/) ## [](#suggested-reading)Suggested reading - [Securing Redpanda in Kubernetes(Day 2 Ops)](https://killercoda.com/redpanda/scenario/redpanda-k8s-secure) - [Redpanda Helm Specification](../../../../../reference/k-redpanda-helm-spec/) - [Redpanda CRD Reference](../../../../../reference/k-crd/) - [`rpk security acl`](../../../../../reference/rpk/rpk-security/rpk-security-acl/) ## Suggested labs - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) [Search all labs](/redpanda-labs) --- # Page 185: Manage Schema Registry ACLs with the Redpanda Operator **URL**: https://docs.redpanda.com/current/manage/kubernetes/security/authentication/k-schema-registry-acls.md --- # Manage Schema Registry ACLs with the Redpanda Operator --- title: Manage Schema Registry ACLs with the Redpanda Operator latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/security/authentication/k-schema-registry-acls page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/security/authentication/k-schema-registry-acls.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/security/authentication/k-schema-registry-acls.adoc description: Manage Schema Registry ACLs declaratively in Kubernetes using User, RedpandaRole, and Group custom resources with the Redpanda Operator. page-topic-type: how-to personas: platform_operator page-git-created-date: "2026-03-31" page-git-modified-date: "2026-03-31" support-status: supported --- With the Redpanda Operator, you can declaratively manage Schema Registry ACLs alongside standard Kafka ACLs using the existing [User](../../../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-user), [RedpandaRole](../../../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-role), and Group custom resources. This allows you to control which users and roles perform specific operations within Schema Registry. For Schema Registry Authorization concepts and the available operations, see [Schema Registry Authorization](../../../../schema-reg/schema-reg-authorization/). ## [](#prerequisites)Prerequisites You must have the following: - **kubectl**: The [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) command-line tool, installed and configured to communicate with your cluster. - **Redpanda Operator v25.3 or later**: See [Deploy Redpanda for Production in Kubernetes](../../../../../deploy/redpanda/kubernetes/k-production-deployment/). - **Redpanda cluster with SASL enabled**: See [Enable SASL authentication](../k-authentication/#enable). - **Schema Registry Authorization enabled**: See [Enable Schema Registry Authorization](../../../../schema-reg/schema-reg-authorization/#enable-schema-registry-authorization). ## [](#schema-registry-acl-resource-types)Schema Registry ACL resource types The Redpanda Operator supports two Schema Registry ACL resource types in addition to the standard Kafka ACL resource types (`topic`, `group`, `cluster`, `transactionalId`): - `subject`: Controls ACL access for specific Schema Registry subjects. Specify the subject name in `resource.name`. Supports both `literal` and `prefixed` pattern types. - `registry`: Controls access to global Schema Registry operations. The `registry` resource type does not require a `name` because it applies to all global registry operations. For a full list of supported operations by resource type, see [Supported operations](../../../../schema-reg/schema-reg-authorization/#supported-operations). ## [](#define-schema-registry-acls-in-a-user-resource)Define Schema Registry ACLs in a User resource The [User resource](../k-user-controller/) supports Schema Registry ACLs alongside standard Kafka ACLs. `user-with-sr-acls.yaml` ```yaml --- apiVersion: cluster.redpanda.com/v1alpha2 kind: User metadata: name: travis spec: cluster: clusterRef: name: sasl authentication: type: scram-sha-512 password: valueFrom: secretKeyRef: name: travis-password key: password authorization: acls: - type: allow resource: type: topic name: some-topic patternType: prefixed operations: [Read] - type: allow resource: type: subject name: some-topic patternType: prefixed operations: [Read] ``` In this example, the User resource creates ACLs for an existing user called `travis` in the cluster called `sasl`. The first ACL rule grants read access to all topics whose names start with `some-topic` using a `prefixed` pattern type. The second ACL rule grants read access to Schema Registry subjects matching the same prefix. When both Kafka and Schema Registry ACLs are defined in the same User resource, the operator syncs them independently. Kafka ACLs are applied through the Kafka API and Schema Registry ACLs are applied through the Schema Registry API. ## [](#define-schema-registry-acls-in-a-redpandarole-resource)Define Schema Registry ACLs in a RedpandaRole resource The [RedpandaRole resource](../../authorization/k-role-controller/) groups Schema Registry ACLs into reusable permission sets for multiple users. `role-with-sr-acls.yaml` ```yaml --- apiVersion: cluster.redpanda.com/v1alpha2 kind: RedpandaRole metadata: name: read-only-role spec: cluster: clusterRef: name: sasl principals: - User:charlie authorization: acls: - type: allow resource: type: topic name: public- patternType: prefixed operations: [Read, Describe] - type: allow resource: type: subject name: public- patternType: prefixed operations: [Read, Describe] ``` In this example, a RedpandaRole called `read-only-role` is created in the cluster called `sasl`. The user `charlie` is assigned as a principal. The authorization rules grant `Read` and `Describe` access to all topics with names starting with `public-` using a `prefixed` pattern type, and the same `Read` and `Describe` access to Schema Registry subjects matching the same prefix. ## [](#define-schema-registry-acls-in-a-group-resource)Define Schema Registry ACLs in a Group resource The Group resource supports Schema Registry ACLs for OIDC groups. `group-with-sr-acls.yaml` ```yaml # In this example manifest, ACLs are created for an OIDC group called "engineering" # in a cluster called "sasl". The group is granted read access to topics matching "team-" # and read access to Schema Registry subjects matching "team-". --- apiVersion: cluster.redpanda.com/v1alpha2 kind: Group metadata: name: engineering spec: cluster: clusterRef: name: sasl authorization: acls: - type: allow resource: type: topic name: team- patternType: prefixed operations: [Read, Describe] - type: allow resource: type: subject name: team- patternType: prefixed operations: [Read, Describe] ``` In this example, ACLs are created for an OIDC group called `engineering` in the cluster called `sasl`. The authorization rules grant `Read` and `Describe` access to all topics with names starting with `team-` using a `prefixed` pattern type, and the same `Read` and `Describe` access to Schema Registry subjects matching the same prefix. ## [](#common-use-cases)Common use cases The following examples show common patterns for configuring Schema Registry ACLs using the User resource. ### [](#grant-a-user-read-access-to-a-subject)Grant a user read access to a subject This example gives a consumer application read access to the `orders` topic and its associated Schema Registry subject `orders-value`. Both ACLs use a `literal` pattern type to match exact resource names. `consumer-app.yaml` ```yaml --- apiVersion: cluster.redpanda.com/v1alpha2 kind: User metadata: name: consumer-app spec: cluster: clusterRef: name: redpanda authorization: acls: - type: allow resource: type: topic name: orders patternType: literal operations: [Read] - type: allow resource: type: subject name: orders-value patternType: literal operations: [Read] ``` ### [](#grant-a-producer-write-access-using-prefix-patterns)Grant a producer write access using prefix patterns This example creates a user called `producer-app` with both authentication credentials and authorization rules. The ACLs grant `Write` and `Describe` access to all topics and Schema Registry subjects whose names start with `events-` using a `prefixed` pattern type. This allows the producer to register new schema versions for any subject matching the prefix. `producer-app.yaml` ```yaml --- apiVersion: cluster.redpanda.com/v1alpha2 kind: User metadata: name: producer-app spec: cluster: clusterRef: name: redpanda authentication: type: scram-sha-512 password: valueFrom: secretKeyRef: name: producer-app-secret key: password authorization: acls: - type: allow resource: type: topic name: events- patternType: prefixed operations: [Write, Describe] - type: allow resource: type: subject name: events- patternType: prefixed operations: [Write, Describe] ``` ### [](#grant-global-schema-registry-access)Grant global Schema Registry access This example gives a schema administrator full access to all Schema Registry operations. The first ACL rule uses the `registry` resource type, which applies to global operations such as getting or setting the global compatibility level. The `registry` resource type does not require a `name` field. The second ACL rule uses a `subject` resource type with an empty name and `prefixed` pattern type to match all subjects. `schema-admin.yaml` ```yaml --- apiVersion: cluster.redpanda.com/v1alpha2 kind: User metadata: name: schema-admin spec: cluster: clusterRef: name: redpanda authorization: acls: - type: allow resource: type: registry operations: [Read, Write, Delete, Describe, DescribeConfigs, AlterConfigs] - type: allow resource: type: subject name: "" patternType: prefixed operations: [Read, Write, Delete, Describe, DescribeConfigs, AlterConfigs] ``` ## [](#partial-sync-behavior)Partial sync behavior When a resource includes both Kafka and Schema Registry ACLs, the operator syncs them independently. If the Kafka ACLs sync successfully but the Schema Registry ACLs fail (for example, if Schema Registry Authorization is not enabled), the resource enters a `PartiallySynced` state. Check the resource status conditions for details: ```bash kubectl get user -o jsonpath='{.status.conditions}' --namespace ``` ## [](#deploy-and-verify)Deploy and verify To deploy a resource with Schema Registry ACLs, apply the manifest to the same namespace as your Redpanda cluster: ```bash kubectl apply -f .yaml --namespace ``` After deploying, verify that the Redpanda Operator reconciled the resource: ```bash kubectl logs -l app.kubernetes.io/name=operator -c manager --namespace ``` ## [](#next-steps)Next steps - [Schema Registry Authorization](../../../../schema-reg/schema-reg-authorization/) - [Manage Users and ACLs with the Redpanda Operator](../k-user-controller/) - [Manage Roles with the Redpanda Operator](../../authorization/k-role-controller/) - [ACLResourceSpec](../../../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-aclresourcespec) - [Configure Access Control Lists](../../../../security/authorization/acl/) ## Suggested labs - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) [Search all labs](/redpanda-labs) --- # Page 186: Manage Users and ACLs with the Redpanda Operator **URL**: https://docs.redpanda.com/current/manage/kubernetes/security/authentication/k-user-controller.md --- # Manage Users and ACLs with the Redpanda Operator --- title: Manage Users and ACLs with the Redpanda Operator latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/security/authentication/k-user-controller page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/security/authentication/k-user-controller.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/security/authentication/k-user-controller.adoc description: Use the User resource to declaratively create and manage users and ACLs as part of a Redpanda deployment. Each User resource is mapped to a user in your Redpanda cluster. The user controller keeps the corresponding user in sync with the User resource. page-git-created-date: "2024-10-30" page-git-modified-date: "2025-12-04" support-status: supported --- With the Redpanda Operator, you can declaratively create and manage Redpanda users and [access control lists (ACLs)](https://docs.redpanda.com/current/reference/glossary/#access-control-list-acl) using [User custom resources](../../../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-user) (resources) in Kubernetes. Each User resource is mapped to a user in your Redpanda cluster. The user controller, a component of the Redpanda Operator, keeps the corresponding user in sync with the User resource. For role-based access control where you want to define permissions once and apply them to multiple users, see [Manage Roles and ACLs](../../authorization/k-role-controller/). ## [](#prerequisites)Prerequisites You must have the following: - **Kubectl**: Ensure you have the [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) command-line tool installed and configured to communicate with your cluster. - **Redpanda Operator**: Ensure you have at least version v2.2.2-24.2.4 of the [Redpanda Operator](../../../../../deploy/redpanda/kubernetes/k-production-deployment/). - **Redpanda cluster with SASL enabled**: Ensure you have a Redpanda resource deployed with [SASL authentication enabled](../k-authentication/#enable). ## [](#create-a-user)Create a user You can use the User resource to: - [Create a new user and its ACLs](#both) - [Create a new user without any authorization (ACLs)](#no-acl) - [Create only the ACLs for a user](#only-acl) Each User instance is responsible for managing both the user credentials (authentication) and the user’s ACLs within the Redpanda cluster. You cannot use one User resource to manage the user and another resource to manage the ACLs. Only one User instance is allowed per user in the Redpanda cluster. ### [](#no-acl)Create a new user without any ACLs - **Use case**: You want to create and manage user credentials (authentication) without managing ACLs. Use this option if you have a separate process to manage ACLs or if you’re working in an environment where access control is handled externally. - **What happens when deleted**: The user is deleted, but ACLs for that user will remain in the cluster. This example shows how to manage the creation and authentication of a user without configuring ACLs. `new-user.yaml` ```yaml # In this example manifest, a user called "jason" is created in a cluster called "sasl". # The user's password is defined in a Secret called "jason-password". # This example assumes that you will create ACLs for this user separately. --- apiVersion: cluster.redpanda.com/v1alpha2 kind: User metadata: name: jason spec: cluster: clusterRef: name: sasl authentication: type: scram-sha-512 password: valueFrom: secretKeyRef: name: jason-password key: password ``` ### [](#only-acl)Create only ACLs - **Use case**: You want to manage ACLs for an existing user in the Redpanda cluster, but not modify the user’s credentials. Use this option if user credentials are managed by another process or tool, and you only want to control what resources the user can access (authorization). - **What happens when deleted**: The ACLs are removed, but the user remains. This is useful when you want to revoke access but retain the user’s credentials for future use. When you create ACLs with the User resource, the specified ACLs are applied only to the user defined in the `metadata.name` field. For example, if you create ACLs for a user named `data-consumer`, those ACLs apply only to that user. Other users in the Redpanda cluster are not affected by these ACLs. This example shows how to manage only the ACLs for an existing user in the Redpanda cluster. `new-acl.yaml` ```yaml --- apiVersion: cluster.redpanda.com/v1alpha2 kind: User metadata: name: travis spec: cluster: clusterRef: name: sasl authentication: type: scram-sha-512 password: valueFrom: secretKeyRef: name: travis-password key: password authorization: acls: - type: allow resource: type: topic name: some-topic patternType: prefixed operations: [Read] - type: allow resource: type: subject name: some-topic patternType: prefixed operations: [Read] ``` ### [](#both)Create a new user and assign ACLs - **Use case**: You want to manage both user credentials and ACLs within the same resource. - **What happens when deleted**: Both the user and the associated ACLs are removed. This example shows how to manage both authentication and ACLs for a user within the same User resource. `new-user-and-acl.yaml` ```yaml # In this example manifest, the user "full-user" is created and managed for both authentication and authorization. # The user is granted both read and write access to the topic critical-topic. apiVersion: cluster.redpanda.com/v1alpha2 kind: User metadata: name: full-user spec: cluster: clusterRef: name: sasl authentication: type: scram-sha-512 password: valueFrom: secretKeyRef: name: full-user-secret key: password authorization: acls: - type: allow resource: type: topic name: critical-topic patternType: literal operations: [Read,Write] ``` ## [](#configuration)Configuration The following sections provide guidance on setting up user authentication, managing secrets, and defining ACLs within your Kubernetes environment. These recommendations ensure proper user management while minimizing manual interventions and preventing potential security issues. You can find all configuration options for the User resource in the [CRD reference](../../../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-user). ### [](#choose-a-username)Choose a username The `metadata.name` field in the User resource is used to specify the username. Keep in mind the following best practices when choosing a username: - **Unique**: Ensure each user has a unique name to avoid conflicts. The username must be unique within the Redpanda cluster. - **Descriptive**: Choose a name that identifies the purpose or role of the user. For example, use names like `app-consumer` or `admin-user`. - **Stable**: Avoid changing usernames frequently. Usernames are tied to authentication and authorization rules (ACLs). Renaming a user involves deleting and recreating the user. ```yaml metadata: name: full-user ``` In this example, `full-user` is the username, which will be referenced in both authentication and authorization rules. ### [](#configure-authentication)Configure authentication This section provides guidance on configuring authentication for users with the User resource. You can find all configuration options for authentication in the [UserAuthenticationSpec](../../../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-userauthenticationspec) of the CRD reference. #### [](#choose-an-authentication-type)Choose an authentication type You can specify the authentication type for a user using the [`spec.authentication.type`](../../../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-userauthenticationspec) field. Supported values include `scram-sha-256`, `scram-sha-512`, and their uppercase variants. ```yaml spec: authentication: type: scram-sha-512 ``` If no authentication credentials are provided, no user will be created, but ACLs can still be managed for existing users. #### [](#manage-user-secrets)Manage user secrets Redpanda users require a password, which you can provide directly, using the [`spec.password.value`](../../../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-password) field, or through a Kubernetes Secret, using the [`spec.password.valueFrom.secretKeyRef`](../../../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-password). The Redpanda operator offers flexibility in how these secrets are handled: - If the Secret exists and the key exists within that Secret, the existing password will be used. - If the Secret exists but the key does not exist, the Secret will be updated with an autogenerated password. - If the Secret does not exist, a new Secret with the provided key will be created with an autogenerated password. This behavior ensures that you can manage user credentials securely and programmatically, while also automating password generation if necessary. To use an existing Kubernetes Secret, ensure that the Secret and key are both defined. For example: ```yaml spec: authentication: password: valueFrom: secretKeyRef: name: user-secret key: password ``` This example is based on the assumption that a Kubernetes Secret named `user-secret` with a key `password` exists. If the Secret does not exist or the key is missing, the Redpanda Operator will handle it by creating or updating the Secret with an autogenerated password. The autogenerated password will follow best practices for secure password generation. If you need to create a Secret, you can use the following command as an example: ```bash kubectl --namespace create secret generic user-secret --from-file=password.txt ``` In this example, the `password.txt` file contains the password you want to use. ### [](#define-acls)Define ACLs The [`spec.authorization`](../../../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-userauthorizationspec) field allows you to manage ACLs for users. ACLs define the permissions users have over specific resources in Redpanda, such as topics, consumer groups, and clusters. You can define ACLs for a user by specifying which resources they can access and the operations they are permitted to perform. Here’s an example configuration for managing ACLs: ```yaml spec: authorization: acls: - type: allow resource: type: topic name: my-topic patternType: literal operations: [Read, Write] ``` - `type`: Defines whether the ACL is `allow` or `deny`. - `resource.type`: Specifies the resource type. - `patternType`: Specifies if the resource name is treated as a `literal` or a `prefixed` pattern. Default: `literal`. > 💡 **TIP** > > Use specific resource names where possible. Using `literal` names for resources ensures that only the exact resources you intend are accessible. Use `prefixed` patterns cautiously to avoid accidental permission grants. - `operations`: Lists the allowed operations, such as `Read`, `Write`, `Create`, and `Delete`. You can find all configuration options for authorization in the [UserAuthorizationSpec](../../../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-userauthorizationspec) of the CRD reference. For more details about ACLs, including supported operations and resources in Redpanda, see [Configure Access Control Lists](../../../../security/authorization/acl/). ## [](#deploy-a-user-resource)Deploy a User resource To deploy a User resource, apply the manifest to the same namespace as your Redpanda cluster: ```bash kubectl apply -f .yaml --namespace ``` - Replace `` with the filename of your manifest. - Replace `` with the namespace in which you deployed Redpanda. ## [](#verify-a-user)Verify a user After deploying a User resource, verify that the Redpanda Operator reconciled it: ```bash kubectl logs -l app.kubernetes.io/name=operator -c manager --namespace ``` Example output: ```json { "level": "info", "ts": "2024-09-25T16:20:09.538Z", "logger": "UserReconciler.Reconcile", "msg": "Starting reconcile loop", "controller": "user", "User": { "name": "my-user", "namespace": "" }, "reconcileID": "c0cf9abc-a553-48b7-9b6e-2de3cdfb4432" } { "level": "info", "ts": "2024-09-25T16:20:09.581Z", "logger": "UserReconciler.Reconcile", "msg": "Reconciliation finished in 43.436125ms, next run in 3s", } ``` ## [](#update-a-user)Update a user To update a user, edit the User resource configuration and apply the changes. ```bash kubectl apply -f .yaml --namespace ``` ## [](#delete-a-user)Delete a user To delete a user, delete the User resource: ```bash kubectl delete -f example-user.yaml --namespace ``` When a User resource is deleted, its underlying data is removed as well. If the user has ACLs, those ACLs are also removed. Deleting a User resource will have different impacts depending on how it is configured: - **Authentication-only**: When a User resource that manages only authentication is deleted, the user is removed from the cluster. However, any ACLs not managed by the same resource will remain in place. - **Authorization-only**: When a User resource that manages only ACLs is deleted, the ACLs are removed, but the user remains in the cluster. - **Full user management (both authentication and authorization)**: When the resource manages both users and ACLs, the user and its associated ACLs are removed. ## [](#best-practices)Best practices When working with User resources, consider the following best practices: ### [](#user-design)User design - **Principle of least privilege**: Grant only the minimum permissions necessary for users to perform their tasks. - **Descriptive usernames**: Use clear, consistent naming conventions that identify the user’s purpose or role. - **Avoid shared accounts**: Create individual user accounts rather than sharing credentials between multiple people or applications. ### [](#permission-management)Permission management - **Consider roles for shared permissions**: When multiple users need the same set of permissions, consider using [RedpandaRole resources](../../authorization/k-role-controller/) instead of duplicating ACLs across individual User resources. - **User-specific permissions**: Use User resource ACLs for permissions that are specific to individual users and don’t need to be shared. - **Avoid conflicts**: If using both Role and User resources, be careful not to create conflicting ACLs for the same users. ### [](#secret-management)Secret management - **Use Kubernetes Secrets**: Store passwords in Kubernetes Secrets rather than hardcoding them in manifests. - **Regular rotation**: Implement a regular password rotation strategy for production environments. ## [](#suggested-reading)Suggested reading - [User resource](../../../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-user) - [UserList resource](../../../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-userlist) - [Manage Roles and ACLs](../../authorization/k-role-controller/) - [Configure Authentication for Redpanda in Kubernetes](../k-authentication/) - [Role-Based Access Control (RBAC)](../../../../security/authorization/rbac/) - [Access Control Lists (ACLs)](../../../../security/authorization/acl/) --- # Page 187: Manage Groups and ACLs with the Redpanda Operator **URL**: https://docs.redpanda.com/current/manage/kubernetes/security/authorization/k-group-controller.md --- # Manage Groups and ACLs with the Redpanda Operator --- title: Manage Groups and ACLs with the Redpanda Operator latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/security/authorization/k-group-controller page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/security/authorization/k-group-controller.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/security/authorization/k-group-controller.adoc description: Use the Group resource to declaratively manage ACLs for OIDC groups as part of a Redpanda deployment. Each Group resource maps to an external OIDC group identity and manages the Kafka ACLs for that group principal. page-topic-type: how-to learning-objective-1: Create Group resources to manage ACLs for OIDC groups learning-objective-2: Configure authorization rules for group principals learning-objective-3: Deploy and verify Group resources in Kubernetes personas: platform_admin, security_admin page-git-created-date: "2026-03-31" page-git-modified-date: "2026-03-31" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../../../get-started/licensing/#self-managed) apply. With the Redpanda Operator, you can declaratively manage Kafka ACLs for OIDC groups using [Group custom resources](../../../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-group) in Kubernetes. Each Group resource maps to an external OIDC group identity and manages the Kafka ACLs for that group’s principal. The group controller (a component of the Redpanda Operator) keeps ACLs in sync with the Group resource. > 📝 **NOTE** > > Groups are external identities sourced from your OIDC identity provider (IdP) via JWT token claims. Unlike [User resources](../../authentication/k-user-controller/), Group resources do not create entities in Redpanda — they only manage ACLs for the `Group:` principal. After reading this page, you will be able to: - Create Group resources to manage ACLs for OIDC groups - Configure authorization rules for group principals - Deploy and verify Group resources in Kubernetes ## [](#what-are-groups-and-why-use-them)What are groups and why use them? Groups let you assign Kafka ACL permissions to OIDC identities without creating individual Redpanda users. When a user authenticates through your OIDC provider, the JWT token includes group claims. Redpanda maps those group claims to ACL principals of the form `Group:`, so any user in that OIDC group inherits the group’s permissions. This is useful when: - **You use an external identity provider**: Your organization manages identities in an IdP such as Okta, Azure AD, or Keycloak, and you want Redpanda permissions to follow those group memberships. - **You want centralized access management**: Instead of creating individual Redpanda users and assigning permissions one by one, you grant permissions to groups. When someone joins or leaves a group in your IdP, their Redpanda access updates automatically. - **You want to combine with roles**: Groups can be assigned as principals in [RedpandaRole resources](../k-role-controller/), allowing OIDC groups to inherit role-based permissions. ## [](#prerequisites)Prerequisites You must have the following: - **Kubectl**: Ensure you have the [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) command-line tool installed and configured to communicate with your cluster. - **Redpanda Operator**: Ensure you have at least version 25.3 of the [Redpanda Operator](../../../../../deploy/redpanda/kubernetes/k-production-deployment/). - **Redpanda cluster with OIDC enabled**: Ensure you have a Redpanda cluster deployed with [OIDC authentication](../../../../security/authorization/gbac/) configured. Group-based access control (GBAC) is an enterprise feature that requires OIDC. - **Redpanda v26.1+**: The cluster must be running Redpanda v26.1 or later, which supports the v2 Security API required for group principals. ## [](#create-a-group-resource)Create a Group resource You can use the Group resource to: - [Create ACLs for an OIDC group](#with-acls) - [Register a group without ACLs](#without-acls) Each Group resource manages the ACLs for a single group principal (`Group:`). Only one Group resource is allowed per group name in the Redpanda cluster. ### [](#with-acls)Create ACLs for an OIDC group - **Use case**: You want to grant specific Kafka permissions to all users who belong to an OIDC group. This is the most common use case, where your IdP manages group membership and Redpanda enforces the permissions. - **What happens when deleted**: All ACLs managed by this Group resource are removed. Users in the OIDC group lose the permissions granted by this resource. This example shows how to create ACLs for an OIDC group called `engineering`, granting read access to topics and Schema Registry subjects matching `team-`. `engineering-group.yaml` ```yaml # In this example manifest, ACLs are created for an OIDC group called "engineering" # in a cluster called "sasl". The group is granted read access to topics matching "team-" # and read access to Schema Registry subjects matching "team-". --- apiVersion: cluster.redpanda.com/v1alpha2 kind: Group metadata: name: engineering spec: cluster: clusterRef: name: sasl authorization: acls: - type: allow resource: type: topic name: team- patternType: prefixed operations: [Read, Describe] - type: allow resource: type: subject name: team- patternType: prefixed operations: [Read, Describe] ``` ### [](#without-acls)Register a group without ACLs - **Use case**: You want to ensure no stale ACLs exist for a group, or you want to create the Group resource first and add ACLs later. - **What happens when deleted**: No ACLs are affected because none were defined. When you create a Group resource without an `authorization` section, the operator ensures that no ACLs exist for the group principal. If any pre-existing ACLs were previously set for this group, they are removed. `empty-group.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Group metadata: name: empty-group spec: cluster: clusterRef: name: redpanda ``` ## [](#configuration)Configuration The following sections provide guidance on configuring Group resources and defining ACLs for OIDC groups. ### [](#choose-a-group-name)Choose a group name The `metadata.name` field in the Group resource must match the group name in your OIDC provider’s JWT token claims. Keep in mind the following: - **Match your IdP**: The name must exactly match the group claim value from your OIDC provider. For example, if your IdP sends `engineering` as a group claim, the Group resource must be named `engineering`. - **Unique**: Each group name must be unique within the Redpanda cluster. - **Stable**: Avoid changing group names, as this involves deleting and recreating the Group resource. The cluster source is immutable. ```yaml metadata: name: engineering ``` ### [](#reference-the-redpanda-cluster)Reference the Redpanda cluster The `spec.cluster` field specifies which Redpanda cluster the ACLs should be applied to. This field is immutable after creation. ```yaml spec: cluster: clusterRef: name: redpanda ``` ### [](#define-authorization-rules)Define authorization rules The `spec.authorization` field allows you to manage ACLs for the group. ACLs define the permissions that all members of the OIDC group have over specific resources in Redpanda, such as topics, consumer groups, and Schema Registry subjects. ```yaml spec: authorization: acls: - type: allow resource: type: topic name: team- patternType: prefixed operations: [Read, Describe] - type: allow resource: type: subject name: team- patternType: prefixed operations: [Read, Describe] ``` - `type`: Defines whether the ACL allows or denies access. Acceptable values: `allow`, `deny`. - `resource.type`: Specifies the resource type. Acceptable values: `topic`, `group`, `cluster`, `transactionalId`, `subject`. - `patternType`: Specifies how the resource name is interpreted. Acceptable values: `literal`, `prefixed`. Default: `literal`. > 💡 **TIP** > > Using `literal` names for resources ensures that only the exact resources you intend are accessible. Use `prefixed` patterns cautiously to avoid accidental permission grants. - `operations`: Lists the allowed operations, such as `Read`, `Write`, `Create`, `Describe`, and `Delete`. When the `authorization` field is omitted or contains an empty `acls` list, the operator removes any existing ACLs for the group principal. For more details about ACLs, including supported operations and resources in Redpanda, see [Configure Access Control Lists](../../../../security/authorization/acl/). ## [](#deploy-a-group-resource)Deploy a Group resource To deploy a Group resource, apply the manifest to the same namespace as your Redpanda cluster: ```bash kubectl apply -f .yaml --namespace ``` - Replace `` with the filename of your manifest. - Replace `` with the namespace in which you deployed Redpanda. ## [](#verify-a-group)Verify a group After deploying a Group resource, verify that the Redpanda Operator reconciled it: ```bash kubectl get groups --namespace ``` The `SYNCED` column should show `True` when the group’s ACLs have been successfully applied. You can also check the operator logs for details: ```bash kubectl logs -l app.kubernetes.io/name=operator -c manager --namespace ``` ## [](#update-a-group)Update a group To update a group’s ACLs, edit the Group resource configuration and apply the changes. The operator will reconcile the ACLs to match the updated specification, adding new ACLs and removing any that are no longer defined. ```bash kubectl apply -f .yaml --namespace ``` For example, to expand permissions for a group from read-only to read-write: ```yaml spec: authorization: acls: - type: allow resource: type: topic name: platform- patternType: prefixed operations: [Read, Write, Describe] ``` ## [](#delete-a-group)Delete a group To delete a group, delete the Group resource: ```bash kubectl delete -f .yaml --namespace ``` When a Group resource is deleted, all ACLs managed by that resource are removed from the Redpanda cluster. The group itself continues to exist in your OIDC provider — only the Redpanda ACLs are affected. ## [](#best-practices)Best practices When working with Group resources, consider the following best practices: ### [](#group-design)Group design - **Align with your IdP**: Structure your Group resources to mirror the group hierarchy in your OIDC provider. This makes it easier to reason about who has access to what. - **Principle of least privilege**: Grant only the minimum permissions necessary for the group’s function. Start with read-only access and expand as needed. - **Naming conventions**: Use the same group names as your IdP to avoid confusion. Document which IdP groups map to which Redpanda permissions. ### [](#permission-management)Permission management - **Prefer group-based over user-based ACLs**: When your organization uses OIDC, manage permissions through groups rather than individual users for easier administration. - **Use specific resource patterns**: Prefer `literal` patterns over `prefixed` patterns unless you specifically need pattern matching. - **Combine with roles**: For complex permission models, use Group resources for direct ACLs and [RedpandaRole resources](../k-role-controller/) to assign groups to roles. - **Regular reviews**: Periodically review group permissions to ensure they remain appropriate and necessary. ### [](#integration-with-other-resources)Integration with other resources - **Groups and roles**: OIDC groups can be assigned as principals in RedpandaRole resources using the `Group:` format. This allows groups to inherit role-level permissions in addition to any direct ACLs. - **Groups and users**: Group ACLs and user ACLs are independent. A user who belongs to an OIDC group receives both the group’s permissions and any individual ACLs defined through a User resource. - **Avoid conflicts**: Be careful not to create conflicting ACLs (allow vs. deny) between Group, Role, and User resources for the same principals and resources. ## [](#suggested-reading)Suggested reading - [Group resource](../../../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-group) - [Manage Users and ACLs](../../authentication/k-user-controller/) - [Manage Roles and ACLs](../k-role-controller/) - [Access Control Lists (ACLs)](../../../../security/authorization/acl/) ## Suggested labs - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) [Search all labs](/redpanda-labs) --- # Page 188: Manage Roles with the Redpanda Operator **URL**: https://docs.redpanda.com/current/manage/kubernetes/security/authorization/k-role-controller.md --- # Manage Roles with the Redpanda Operator --- title: Manage Roles with the Redpanda Operator latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/security/authorization/k-role-controller page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/security/authorization/k-role-controller.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/security/authorization/k-role-controller.adoc description: Use the RedpandaRole resource to declaratively create and manage roles as part of a Redpanda deployment. Each RedpandaRole resource defines a set of permissions that can be assigned to multiple users, providing role-based access control (RBAC) for your Redpanda cluster. page-git-created-date: "2025-12-04" page-git-modified-date: "2025-12-04" support-status: supported --- With the Redpanda Operator, you can declaratively create and manage Redpanda roles using [RedpandaRole custom resources](../../../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-role) (resources) in Kubernetes. Each RedpandaRole resource defines a set of permissions that can be assigned to multiple users, providing role-based access control (RBAC) for your Redpanda cluster. The role controller, a component of the Redpanda Operator, keeps the corresponding Redpanda role in sync with the RedpandaRole resource. > 📝 **NOTE** > > RedpandaRole resources do not create users. Users must already exist in the Redpanda cluster before they can be assigned to roles, unless they are OIDC principals. OIDC principals do not need to be created as users in the cluster. Use [User resources](../../authentication/k-user-controller/) to create and manage Redpanda users. ## [](#what-are-roles-and-why-use-them)What are roles and why use them? Think of roles like job titles in a company. Instead of giving each employee individual permissions for every door, system, and resource, you create job titles (roles) like "Developer," "Manager," or "Security Guard." Each job title comes with a specific set of permissions, and you assign employees to those job titles. In Redpanda, roles work the same way: - **Without roles**: You set up permissions individually for each user. If you have 10 developers who all need the same access to certain topics, you configure the same permissions 10 times. - **With roles**: You create a "Developer" role once with all the necessary permissions, then assign all 10 developers to that role. When you need to change what developers can access, you update the role once instead of updating 10 individual users. ## [](#prerequisites)Prerequisites You must have the following: - **Kubectl**: Ensure you have the [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) command-line tool installed and configured to communicate with your cluster. - **Redpanda Operator**: Ensure you have at least version 25.2 of the [Redpanda Operator](../../../../../deploy/redpanda/kubernetes/k-production-deployment/). - **Redpanda cluster with SASL enabled**: Ensure you have a Redpanda resource deployed with [SASL authentication enabled](../../authentication/k-authentication/#enable). - **Existing users**: If you plan to assign users to roles, ensure the users already exist in your Redpanda cluster. You can create users using [User resources](../../authentication/k-user-controller/). ## [](#create-a-role)Create a role You can use the RedpandaRole resource to: - [Create a role with authorization rules (ACLs)](#with-authorization) - [Create a role with principals (users)](#with-principals) - [Create authorization rules for an existing role](#authorization-only) Each Role instance is responsible for managing both the role membership (principals) and the role’s ACLs within the Redpanda cluster. You cannot use one RedpandaRole resource to manage the principals and another resource to manage the ACLs. Only one Role instance is allowed per role in the Redpanda cluster. ### [](#with-authorization)Create a role with authorization rules - **Use case**: You want to create a role that defines permissions and assign users to inherit those permissions. This is the most common use case for role-based access control, where you define permissions once and apply them to multiple users. - **What happens when deleted**: Both the role and its associated ACLs are removed. Users assigned to the role lose the permissions granted by this role but retain any other permissions they have. This example shows how to create a role with both principals and authorization rules. `read-only-role.yaml` ```yaml --- apiVersion: cluster.redpanda.com/v1alpha2 kind: RedpandaRole metadata: name: read-only-role spec: cluster: clusterRef: name: sasl principals: - User:charlie authorization: acls: - type: allow resource: type: topic name: public- patternType: prefixed operations: [Read, Describe] - type: allow resource: type: subject name: public- patternType: prefixed operations: [Read, Describe] ``` ### [](#with-principals)Create a role with principals - **Use case**: You want to create a role and assign users (principals) to it. This is useful for grouping users together without necessarily defining permissions at the role level, allowing you to manage group membership centrally. - **What happens when deleted**: The role is deleted, but users assigned to the role remain in the cluster. Any ACLs defined at the user level are unaffected. This example shows how to create a role and assign principals to it. `admin-role.yaml` ```yaml # In this example manifest, a role called "admin-role" is created in a cluster called "sasl". # The role includes two principals (alice and bob) who will inherit the role's permissions. --- apiVersion: cluster.redpanda.com/v1alpha2 kind: RedpandaRole metadata: name: admin-role spec: cluster: clusterRef: name: sasl principals: - User:alice - User:bob ``` ### [](#authorization-only)Create authorization rules for an existing role - **Use case**: You want to manage ACLs for an existing role in the Redpanda cluster, but not modify the role’s membership. Use this option if role membership is managed by another process or tool, and you only want to control what resources the role can access. - **What happens when deleted**: The ACLs are removed, but the role and its members remain. This is useful when you want to revoke permissions but retain the role structure for future use. This example shows how to manage only the ACLs for an existing role in the Redpanda cluster. `authorization-only-role.yaml` ```yaml # In this example manifest, a role CRD called "travis-role" manages ACLs for an existing role. # The role includes authorization rules that allow reading from topics with names starting with "some-topic". # This example assumes that you already have a role called "travis-role" in your cluster. # Note: When the CRD is deleted, the operator will remove both the role and ACLs since it takes full ownership. --- apiVersion: cluster.redpanda.com/v1alpha2 kind: RedpandaRole metadata: name: travis-role spec: cluster: clusterRef: name: sasl principals: - User:travis authorization: acls: - type: allow resource: type: topic name: some-topic patternType: prefixed operations: [Read] ``` ## [](#configuration)Configuration The following sections provide guidance on setting up role membership, managing authorization rules, and defining ACLs within your Kubernetes environment. These recommendations ensure proper role management while minimizing manual interventions and preventing potential security issues. You can find all configuration options for the RedpandaRedpandaRole resource in the [CRD reference](../../../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-role). ### [](#choose-a-role-name)Choose a role name The `metadata.name` field in the RedpandaRedpandaRole resource is used to specify the role name. Keep in mind the following best practices when choosing a role name: - **Unique**: Ensure each role has a unique name to avoid conflicts. The role name must be unique within the Redpanda cluster. - **Descriptive**: Choose a name that identifies the purpose or permissions of the role. For example, use names like `data-readers` or `topic-admins`. - **Stable**: Avoid changing role names frequently. Role names are tied to authorization rules (ACLs) and user assignments. Renaming a role involves deleting and recreating the role. ```yaml metadata: name: read-only-role ``` In this example, `read-only-role` is the role name, which will be referenced in authorization rules and user assignments. ### [](#configure-principals)Configure principals The [`spec.principals`](../../../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-rolespec) field allows you to specify which users are assigned to the role. Principals are specified in the format `User:`. > ❗ **IMPORTANT** > > Users must already exist in the Redpanda cluster before they can be assigned to a role. The RedpandaRole resource does not create users that don’t exist. ```yaml spec: principals: - User:alice - User:bob ``` When users are assigned to a role, they inherit all the permissions defined in the role’s ACLs. If a role has no ACLs defined, the users gain no additional permissions from the role membership. ### [](#define-authorization-rules)Define authorization rules The [`spec.authorization`](../../../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-roleauthorizationspec) field allows you to manage ACLs for the role. ACLs define the permissions that all members of the role have over specific resources in Redpanda, such as topics, consumer groups, and clusters. You can define ACLs for a role by specifying which resources members can access and the operations they are permitted to perform. Here’s an example configuration for managing ACLs: ```yaml spec: authorization: acls: - type: allow resource: type: topic name: public- patternType: prefixed operations: [Read, Describe] ``` - `type`: Defines whether the ACL allows or denies access. Acceptable values: `allow`, `deny`. - `resource.type`: Specifies the resource type. Acceptable values: `topic`, `group`, `cluster`, `transactionalId`. - `patternType`: Specifies how the resource name is interpreted. Acceptable values: `literal`, `prefixed`. Default: `literal`. > 💡 **TIP** > > Using `literal` names for resources ensures that only the exact resources you intend are accessible. Use `prefixed` patterns cautiously to avoid accidental permission grants. - `operations`: Lists the allowed operations, such as `Read`, `Write`, `Create`, and `Delete`. You can find all configuration options for authorization in the [RoleAuthorizationSpec](../../../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-roleauthorizationspec) of the CRD reference. For more details about ACLs, including supported operations and resources in Redpanda, see [Configure Access Control Lists](../../../../security/authorization/acl/). ## [](#deploy-a-redpandarole-resource)Deploy a RedpandaRole resource To deploy a RedpandaRole resource, apply the manifest to the same namespace as your Redpanda cluster: ```bash kubectl apply -f .yaml --namespace ``` - Replace `` with the filename of your manifest. - Replace `` with the namespace in which you deployed Redpanda. ## [](#verify-a-role)Verify a role After deploying a RedpandaRole resource, verify that the Redpanda Operator reconciled it: ```bash kubectl logs -l app.kubernetes.io/name=operator -c manager --namespace ``` ## [](#update-a-role)Update a role To update a role, edit the RedpandaRole resource configuration and apply the changes. ```bash kubectl apply -f .yaml --namespace ``` ## [](#delete-a-role)Delete a role To delete a role, delete the RedpandaRole resource: ```bash kubectl delete -f .yaml --namespace ``` When a RedpandaRole resource is deleted, its underlying data is removed as well. If the role has ACLs, those ACLs are also removed. Deleting a RedpandaRole resource has different impacts depending on how it is configured: - **Principals-only**: When a RedpandaRole resource that manages only principals is deleted, the role is removed from the cluster. However, any ACLs not managed by the same resource will remain in place. - **Authorization-only**: When a RedpandaRole resource that manages only ACLs is deleted, the ACLs are removed, but the role and its members remain in the cluster. - **Full role management (both principals and authorization)**: When the resource manages both membership and ACLs, the role and its associated ACLs are removed. ## [](#best-practices)Best practices When working with RedpandaRole resources, consider the following best practices: ### [](#role-design)Role design - **Principle of least privilege**: Grant only the minimum permissions necessary for users to perform their tasks. - **Logical grouping**: Create roles that align with job functions or responsibilities rather than individual users. - **Naming conventions**: Use consistent, descriptive names that indicate the role’s purpose, such as `topic-readers` or `admin-users`. ### [](#permission-management)Permission management - **Prefer role-based over user-based ACLs**: When possible, assign permissions to roles rather than individual users to simplify management. - **Use specific resource patterns**: Prefer `literal` patterns over `prefixed` patterns unless you specifically need pattern matching. - **Regular reviews**: Periodically review role permissions to ensure they remain appropriate and necessary. ### [](#integration-with-user-resources)Integration with User resources - **Consistent management**: If you’re using both Role and User resources, establish clear guidelines about which permissions are managed at the role level versus the user level. - **Avoid conflicts**: Be careful not to create conflicting ACLs between Role and User resources for the same users. ## [](#suggested-reading)Suggested reading - [RedpandaRole resource](../../../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-role) - [RoleList resource](../../../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-rolelist) - [Manage Users and ACLs](../../authentication/k-user-controller/) - [Role-Based Access Control (RBAC)](../../../../security/authorization/rbac/) - [Access Control Lists (ACLs)](../../../../security/authorization/acl/) ## Suggested labs - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) [Search all labs](/redpanda-labs) --- # Page 189: Audit Logging in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/security/k-audit-logging.md --- # Audit Logging in Kubernetes --- title: Audit Logging in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/security/k-audit-logging page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/security/k-audit-logging.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/security/k-audit-logging.adoc description: Learn how to use Redpanda's audit logging capabilities. page-git-created-date: "2024-01-05" page-git-modified-date: "2025-07-31" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../../get-started/licensing/#self-managed) apply. Many scenarios for streaming data include the need for fine-grained auditing of user activity related to the system. This is especially true for regulated industries such as finance, healthcare, and the public sector. Complying with [PCI DSS v4](https://www.pcisecuritystandards.org/document_library/?document=pci_dss) standards, for example, requires verbose and detailed activity auditing, alerting, and analysis capabilities. Redpanda’s auditing capabilities support recording both administrative and operational interactions with topics and with users. Redpanda complies with the Open Cybersecurity Schema Framework (OCSF), providing a predictable and extensible solution that works seamlessly with industry standard tools. With audit logging enabled, there should be no noticeable changes in performance other than slightly elevated CPU usage. > 📝 **NOTE** > > Audit logging is configured at the cluster level. Redpanda supports excluding specific topics or principals from auditing to help reduce noise in the log. Audit logging is disabled by default. ## [](#audit-log-flow)Audit log flow The Redpanda audit log mechanism functions similar to the Kafka flow. When a user interacts with another user or with a topic, Redpanda writes an event to a specialized audit topic. The audit topic is immutable. Only Redpanda can write to it. Users are prevented from writing to the audit topic directly and the Kafka API cannot create or delete it. ![Audit log flow](../../../../shared/_images/audit-logging-flow.png) By default, any management and authentication actions performed on the cluster yield messages written to the audit log topic that are retained for seven days. Interactions with all topics by all principals are audited. Actions performed using the Kafka API and Admin API are all audited, as are actions performed directly through `rpk`. Messages recorded to the audit log topic comply with the [open cybersecurity schema framework](https://schema.ocsf.io/). Any number of analytics frameworks, such as Splunk or Sumo Logic, can receive and process these messages. Using an open standard ensures Redpanda’s audit logs coexist with those produced by other IT assets, powering holistic monitoring and analysis of your assets. ## [](#audit-log-configuration-options)Audit log configuration options Redpanda’s audit logging mechanism supports several options to control the volume and availability of audit records. Configuration is applied at the cluster level. You can configure these options directly in either the Helm values or the Redpanda resource. - `auditLogging.enabled`: Sets the value of the [`audit_enabled`](../../../../reference/properties/cluster-properties/#audit_enabled) cluster property to enable audit logging. When you set this to `true`, Redpanda checks for an existing topic named `_redpanda.audit_log`. If none is found, Redpanda automatically creates one for you. Default: `false`. - `auditLogging.partitions`: Sets the value of the [`audit_log_num_partitions`](../../../../reference/properties/cluster-properties/#audit_log_num_partitions) cluster property to define the number of partitions used by a newly created audit topic. This configuration applies only to the audit log topic and may be different from the cluster or other topic configurations. This cannot be altered for an existing audit log topic. Default: `12`. - `auditLogging.replicationFactor`: Sets the value of the [`audit_log_replication_factor`](../../../../reference/properties/cluster-properties/#audit_log_replication_factor) cluster property to define the replication factor for a newly created audit log topic. This configuration applies only to the audit log topic and may be different from the cluster or other topic configurations. This cannot be altered for existing audit log topics. If a value is not provided, Redpanda uses the `internal_topic_replication_factor` cluster property value. Default: `null`. - `auditLogging.enabledEventTypes`: Sets the value of the [`audit_enabled_event_types`](../../../../reference/properties/cluster-properties/#audit_enabled_event_types) cluster property. This option is a list of JSON strings identifying the [event types](#audit-logging-event-types) to include in the audit log. Valid values include any of the following: `management`, `produce`, `consume`, `describe`, `heartbeat`, `authenticate`, `schema_registry`, `admin`. Default: `'["management","authenticate","admin"]'`. - `auditLogging.excludedTopics`: Sets the value of the [`audit_excluded_topics`](../../../../reference/properties/cluster-properties/#audit_excluded_topics) cluster property. This option is a list of JSON strings identifying the topics the audit logging system should ignore. This list cannot include the `_redpanda.audit_log` topic. Redpanda rejects the command if you do attempt to include that topic. Default: `null`. - `auditLogging.excludedPrincipals`: Sets the value of the [`audit_excluded_principals`](../../../../reference/properties/cluster-properties/#audit_excluded_principals) cluster property. This option is a list of JSON strings identifying the principals the audit logging system should ignore. Principals can be listed as `User:name` or `name`, both are accepted. Default: `null`. - `auditLogging.clientMaxBufferSize`: Sets the value of the [`audit_client_max_buffer_size`](../../../../reference/properties/cluster-properties/#audit_client_max_buffer_size) cluster property to define the number of bytes allocated by the internal audit client for audit messages. When changing this, you must disable audit logging and then re-enable it for the change to take effect. Consider increasing this if your system generates a very large number of audit records in a short amount of time. Default: `16777216`. - `auditLogging.queueDrainIntervalMs`: Sets the value of the [`audit_queue_drain_interval_ms`](../../../../reference/properties/cluster-properties/#audit_queue_drain_interval_ms) cluster property. Internally, Redpanda batches audit log messages in memory and periodically writes them to the audit log topic. This option defines the period in milliseconds between draining this queue to the audit log topic. Longer intervals may help prevent duplicate messages, especially in high throughput scenarios, but they also increase the risk of data loss during hard shutdowns where the queue is lost. Default: `500`. - `auditLogging.queueMaxBufferSizePerShard`: Sets the value of the [`audit_queue_max_buffer_size_per_shard`](../../../../reference/properties/cluster-properties/#audit_queue_max_buffer_size_per_shard) cluster property to define the maximum amount of memory in bytes used by the audit buffer in each shard. When this size is reached, requests to log additional audit messages return a non-retryable error. Default: `1048576`. Even though audited event messages are stored to a specialized immutable topic, standard topic settings still apply. For example, you can apply the same Tiered Storage, retention time, and replication settings available to normal topics. These particular options are important for controlling the amount of disk space utilized by your audit topics. > ❗ **IMPORTANT** > > You cannot change the values of `auditLogging.partitions` and `auditLogging.replicationFactor` after enabling audit logging because these settings impact the creation of the `_redpanda.audit_log` topic. The Kafka API allows you to add partitions or alter the replication factor after enabling audit logging, but Redpanda prevents you from altering these two configuration values directly. ## [](#audit-logging-event-types)Audit logging event types Redpanda’s auditable events fall into one of eight different event types. The APIs associated with each event type are as follows. | Audit event type | Associated APIs | | --- | --- | | management | AlterPartitionReassignmentsCreateACLsCreatePartitionsCreateTopicsDeleteAclsDeleteGroupsDeleteRecordsDeleteTopicsIncrementalAlterconfigsOffsetDelete | | produce | AddPartitionsToTxnEndTxnInitProducerIdProduce | | consume | AddOffsetsToTxnFetchJoinGroupLeaveGroupListOffsetOffsetCommitSyncGroupTxOffsetCommit | | describe | DescribeAclsDescribeConfigsDescribeGroupsDescribeLogDirsFindCoordinatorListGroupsListPartitionReassignmentsMetadataOffsetForLeaderEpochDescribeProducersDescribeTransationsListTransactions | | heartbeat | Heartbeat | | authenticate | All authentication events | | schema_registry | All Schema Registry API calls | | admin | All Admin API calls | ### [](#logged-events)Logged events The following table identifies the data logging level for each audit event entry. > 📝 **NOTE** > > The Included column captures whether the event itself is included (for example, successful and failed access attempts), or whether a piece of data is included in the event itself (for example, Source IP address). | Data Logging Level | Audit Event | Included? | Details | | --- | --- | --- | --- | | System Level | Date and time stamp for each entry | Yes | time field on each event | | Successful and failed access attempts | Yes | The status_id field shows success/failure for all access attempts for which auditing is enabled | | User ID | Yes | user.name | | User group memberships | Yes | user.groups field with type idp_group. Included in authentication events for OIDC users and in authorization events when a group ACL matches. See Configure Group-Based Access Control. | | User connect and disconnect time | No | Connect and disconnect time may be inferred from the presence or absence of activity. | | Password change | Yes | For SCRAM users managed through Redpanda core, the Admin API call associated with the password change is logged. Note that this does not cover users synced from external IdPs, such as through OIDC. | | Changes of security settings | Yes | For example, ACL creation is logged (kafka create_acls), and cluster configuration changes are logged (Admin API events) | | Successful and failed attempts to add/remove users from the system | Yes | See Password change | | Failed attempts to access system data | Yes | Generally, access attempts are logged. For example, kafka produce and consume calls are audited. | | Failed attempts to access critical directories and files | No | Not applicable | | Date and time of system start-up and shut-down | Yes | An application lifecycle event is logged when the broker starts/stops | | Use of external/peripheral devices | No | Not applicable | | Application Level | Transaction date and time | Yes | time field on each event | | User ID | Yes | user.name | | Source IP address | Yes | src_endpoint.ip field | | Type of transaction | Yes | api.operation shows the relevant Kafka API accessed or HTTP method used (Admin/Schema Registry) | | Transaction data | Yes | resources[] for Kafka ops; http_request (headers, URL) for HTTP endpoints | | Transaction result (success/fail) and reason of failure | Partial | Auditing occurs at request time (start of event). Authentication failures are captured with status_id and status_detail fields. However, downstream operation outcomes (whether the actual Kafka/Admin API/Schema Registry operation succeeded or failed) are not included in audit logs. | | Transaction number | No | Redpanda auditing does not assign a unique number to each request | | Failed attempts to access system data | Yes | Access attempts are logged through various audit event types | | Failed attempts to access critical directories and files | No | Not applicable | | Use of external/peripheral devices | Yes | Device access events are captured when applicable | | Network Level | Source IP address (IPv4 or IPv6) | Yes | src_endpoint.ip field | | Destination IP address (IPv4 or IPv6) | Yes | dst_endpoint.ip field | | Protocol/Ports | Yes | service.name shows the service/protocol used (kafka/http). http_request.url.scheme shows http/https for http requests. dst_endpoint.port may be indicative of the protocol. | | Timestamp | Yes | time field | | Host name | Yes | url.hostname: HTTP endpoints (Admin API / Schema Registry) include the HTTP hostname. Not included for Kafka (only source/destination IP). | | VLAN ID | No | Not applicable | | MAC address | No | Not applicable | ## [](#enable-audit-logging)Enable audit logging All audit log settings are applied at the cluster level. You can configure audit log settings in the Redpanda Helm chart, using Helm values or the Redpanda resource with the Redpanda Operator. ### Operator If you want to manage the audit topic using a [Topic resource](../../k-manage-topics/): 1. Create the Redpanda resource with SASL enabled: `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: auth: sasl: enabled: true secretRef: "redpanda-users" ``` 2. Create a Secret to hold the password of either a user or a superuser: ```bash kubectl --namespace create secret generic audit-topic-user-password --from-literal=password= ``` > 📝 **NOTE** > > If you aren’t using a superuser, make sure the user is authorized to manage the `_redpanda.audit_log` topic. 3. Create the Topic resource, and make sure to set `overwriteTopicName` to `_redpanda.audit_log`: ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Topic metadata: name: audit-topic spec: partitions: overwriteTopicName: _redpanda.audit_log kafkaApiSpec: brokers: - "redpanda-0.redpanda..svc.cluster.local:9093" - "redpanda-1.redpanda..svc.cluster.local:9093" - "redpanda-2.redpanda..svc.cluster.local:9093" tls: caCertSecretRef: name: "redpanda-default-cert" key: "ca.crt" sasl: username: mechanism: passwordSecretRef: name: audit-topic-user-password key: password ``` This example configuration contains values for the `kafkaApiSpec.tls` and `kafkaApiSpec.brokers` settings that work with the default Helm values. If you modified these settings in your deployment, make sure to replace those values. 4. Update the Redpanda resource to enable audit logging: `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: auth: sasl: enabled: true secretRef: "redpanda-users" auditLogging: enabled: true ``` If you don’t want to use the Topic resource, you can enable audit logging and Redpanda creates the audit topic for you: `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: auth: sasl: enabled: true secretRef: "redpanda-users" auditLogging: enabled: true ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ### Helm #### --values `audit-logging.yaml` ```yaml auth: sasl: enabled: true secretRef: "redpanda-users" auditLogging: enabled: true ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values audit-logging.yaml --reuse-values ``` #### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set auth.sasl.enabled=true \ --set auth.sasl.secretRef="redpanda-users" \ --set auditLogging.enabled=true ``` - `auth.sasl.enabled`: To enable audit logging, you must have: - SASL authentication enabled. - At least one Kafka listener that uses the SASL authentication mechanism. By default, the internal Kafka listener is used (`listeners.kafka`). To use a different listener, see [Audit log configuration options](#audit-log-configuration-options). - At least one superuser. For details, see [Configure Authentication for Redpanda in Kubernetes](../authentication/k-authentication/). - `auditLogging.enabled`: Enable audit logging. When you set this to `true`, Redpanda checks for an existing topic named `_redpanda.audit_log`. If the topic is not found, Redpanda automatically creates one for you. Default: `false`. ## [](#optimize-costs-for-audit-logging)Optimize costs for audit logging When enabled, audit logging can quickly generate a very large amount of data, especially if all event types are selected. Proper configuration of audit logging is critical to avoid filling your disk or using excess Tiered Storage. The configuration options available help ensure your audit logs contain only the volume of data necessary to meet your regulatory or legal requirements. With audit logging, the pattern of message generation may be very different from your typical sources of data. These messages reflect usage of your system as opposed to the operational data your topics typically process. As a result, your retention, replication, and Tiered Storage requirements may differ from your other topics. A typical scenario with audit logging is to route the messages to an analytics platform like Splunk. If your retention period is too long, you may find that you are storing excessive amounts of replicated messages in both Redpanda and in your analytics suite. Identifying the right balance of retention and replication settings minimizes this duplication while retaining your data in a system that provides actionable intelligence. Assess the retention needs for your audit logs. You may not need to keep the logs for the default seven days. This is controlled by setting [`retention.ms`](../../../../reference/properties/topic-properties/#retentionms) for the `_redpanda.audit_log` topic or by setting [`log_retention_ms`](../../../../reference/properties/cluster-properties/#log_retention_ms) at the cluster level. ## [](#next-steps)Next steps [See samples of audit log messages](../../../audit-logging/audit-log-samples/) ## [](#suggested-reading)Suggested reading - [Topic Configuration Properties](../../../../reference/properties/topic-properties/) - [Manage Topics](../../../../develop/manage-topics/config-topics/) ## Suggested labs - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) [Search all labs](/redpanda-labs) --- # Page 190: TLS for Redpanda in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/security/tls.md --- # TLS for Redpanda in Kubernetes --- title: TLS for Redpanda in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/security/tls/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/security/tls/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/security/tls/index.adoc description: Use TLS to authenticate Redpanda brokers and encrypt communication between clients and brokers. page-git-created-date: "2023-11-14" page-git-modified-date: "2025-07-31" support-status: supported --- Redpanda clusters can use Transport Layer Security (TLS) and mTLS (Mutual TLS) to secure internal and external communications with clients and other brokers. In the Redpanda Helm chart, TLS is enabled by default for all internal and external listeners, using self-signed certificates managed by [cert-manager](https://cert-manager.io/docs/). You can configure the chart to use your own certificates with or without cert-manager. Redpanda exposes several public metrics to help administrators manage their installed certificates. Configuring alerts on these metrics is a critical tool for managing certificate expiration and avoiding surprise outages. The [public metrics reference](../../../../reference/public-metrics-reference/#tls_metrics) contains a full list of available TLS metrics. You can refer to the [monitor Redpanda in Kubernetes](../../monitoring/k-monitor-redpanda/) guide for full details on configuring Prometheus to monitor these metrics. This guide also explains how to create a Grafana dashboard for visualizations and alerting. - [Use cert-manager to manage TLS certificates](k-cert-manager/) Learn how to enable TLS encryption in your Redpanda cluster and use cert-manager to simplify the process of obtaining, renewing, and using certificates. - [Use Kubernetes Secrets to manage TLS certificates](k-secrets/) Create TLS files and store them in Kubernetes Secret resources to configure Redpanda listeners with TLS certificates. --- # Page 191: Use cert-manager to manage TLS certificates **URL**: https://docs.redpanda.com/current/manage/kubernetes/security/tls/k-cert-manager.md --- # Use cert-manager to manage TLS certificates --- title: Use cert-manager to manage TLS certificates latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/security/tls/k-cert-manager page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/security/tls/k-cert-manager.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/security/tls/k-cert-manager.adoc description: Learn how to enable TLS encryption in your Redpanda cluster and use cert-manager to simplify the process of obtaining, renewing, and using certificates. page-git-created-date: "2024-01-04" page-git-modified-date: "2025-04-07" support-status: supported --- When using [cert-manager](https://cert-manager.io/docs/) for TLS certificate management, you can use a self-signed certificate or a certificate signed by a trusted certificate authority (CA). This topic provides instructions for each option. Redpanda supports both TLS and mTLS: - TLS, previously SSL, provides encryption for client-server communication. A server certificate prevents third parties from accessing data transferred between the client and the server. - mTLS, or mutual TLS, is a protocol that authenticates both the server and the client. In addition to the server certificate required in TLS, mTLS also requires the client to give a certificate. mTLS is useful for environments that require additional security and only have a small number of verified clients. ## [](#prerequisites)Prerequisites You must have the following: - Kubernetes cluster: Ensure you have a running Kubernetes cluster, either locally, such as with minikube or kind, or remotely. - [Kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl). Ensure you have the `kubectl` command-line tool installed and configured to communicate with your cluster. - [cert-manager](https://cert-manager.io/docs/installation/helm/). Ensure you have cert-manager and its custom resource definitions (CRDs) installed. - If you want to connect to your Redpanda cluster from outside Kubernetes, make sure to [enable external access](../../../networking/external/). ## [](#use-a-self-signed-certificate)Use a self-signed certificate By default, the Redpanda Helm chart uses cert-manager to generate four Certificate resources. These resources provide Redpanda brokers with self-signed TLS certificates for internal and external listeners. | Type | Default Certificates | | --- | --- | | Internal | redpanda-default-cert: Self-signed certificate for internal communications.redpanda-default-root-certificate: Root CA for the internal certificate. | | External | redpanda-external-cert: Self-signed certificate for external communications.redpanda-external-root-certificate: Root CA for the external certificate. | A corresponding Secret resource exists for each Certificate resource. The Secret contains the TLS files. Having separate self-signed certificates for internal and external connections provides security isolation. If an external certificate or its corresponding private key is compromised, it doesn’t affect the security of internal communications. The following steps explain how to set up self-signed certificates in your Redpanda cluster: 1. Make sure that TLS is enabled: ### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: tls: enabled: true ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ### Helm #### --values `self-signed-tls.yaml` ```yaml tls: enabled: true ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values self-signed-tls.yaml --reuse-values ``` #### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set tls.enabled=true ``` > 📝 **NOTE** > > Enabling or disabling TLS for the RPC listener requires you to delete all Pods that run Redpanda. When you change the `rpc.tls.enabled` setting, or if it is not overridden and you change the global `tls.enabled` option, Redpanda cannot safely apply the change because RPC listener configurations must be the same across all brokers. To apply the change, all Redpanda Pods must be deleted simultaneously so that they all start with the updated RPC listener. This action results in temporary downtime of the cluster. > > Although you can use the `--force` option to speed up the rollout, it may result in data loss as Redpanda will not be given time to shut down gracefully. > > ```bash > kubectl delete pod -l app=redpanda --namespace > ``` 2. Make sure the Certificates are in a `READY` state. ```bash kubectl get certificate --namespace ``` NAME READY redpanda-default-cert True redpanda-default-root-certificate True redpanda-external-cert True redpanda-external-root-certificate True ## [](#connect-to-redpanda)Connect to Redpanda You can use the `rpk` command-line client to test both internal and external connections to Redpanda. ### [](#test-internal-connections)Test internal connections Your self-signed certificate’s SAN includes the internal addresses assigned to brokers by Kubernetes through the headless ClusterIP Service. As such, you can use `rpk` within the Redpanda container to securely communicate with the cluster. You can validate your internal connection to Redpanda with `rpk` by executing the following command: ```bash kubectl exec redpanda-0 --namespace -c redpanda -- rpk cluster info ``` Expected output: ```none CLUSTER ======= redpanda.19ae8532-c8fa-49ed-8b35-82d74813db3a BROKERS ======= ID HOST PORT 0* redpanda-0.redpanda..svc.cluster.local. 9093 1 redpanda-.redpanda..svc.cluster.local. 9093 2 redpanda-2.redpanda..svc.cluster.local. 9093 ``` ### [](#test-external-connections)Test external connections To test external connections, you must enable external access using a custom domain. See [Prerequisites](#prerequisites). The SAN list of your self-signed certificate does not contain the IP addresses of your worker nodes, but when you enable external access using a custom domain, that domain is included in the SAN list. Then, you can use `rpk` on your local machine to communicate with the cluster externally using the self-signed certificate for encryption. 1. Configure [external access](../../../networking/external/) to your Redpanda cluster using a custom domain. > 📝 **NOTE** > > Your Redpanda brokers should advertise addresses in your custom domain. 2. Install `rpk` on your local machine, not inside the container: #### Linux > 💡 **TIP** > > You can use `rpk` on Windows only with [WSL](https://learn.microsoft.com/windows/wsl/install). However, commands that require Redpanda to be installed on your machine are not supported, such as [`rpk container`](../../../../../reference/rpk/rpk-container/rpk-container/) commands, [`rpk iotune`](../../../../../reference/rpk/rpk-iotune/), and [`rpk redpanda`](../../../../../reference/rpk/rpk-redpanda/rpk-redpanda/) commands. ##### amd64 ```bash curl -LO https://github.com/redpanda-data/redpanda/releases/latest/download/rpk-linux-amd64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-linux-amd64.zip -d ~/.local/bin/ ``` ##### arm64 ```bash curl -LO https://github.com/redpanda-data/redpanda/releases/latest/download/rpk-linux-arm64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-linux-arm64.zip -d ~/.local/bin/ ``` #### macOS 1. If you don’t have Homebrew installed, [install it](https://brew.sh/). 2. To install or update `rpk`, run: ```bash brew install redpanda-data/tap/redpanda ``` 3. Save the external root CA to your local file system outside Kubernetes: ```bash kubectl --namespace get secret redpanda-external-root-certificate -o go-template='{{ index .data "ca.crt" | base64decode }}' > ca.crt ``` 4. Configure `rpk` to connect to your cluster using the [pre-configured profile](../../../networking/k-connect-to-redpanda/#rpk-profile): ```bash rpk profile create --from-profile <(kubectl get configmap --namespace redpanda-rpk -o go-template='{{ .data.profile }}') ``` 5. Test the connection: ```bash rpk cluster info ``` ## [](#use-a-public-ca-certificate)Use a public CA certificate Certificates from a public CA are trusted by default. You can configure the Helm chart to use an Issuer resource or a ClusterIssuer resource to generate publicly trusted Certificates for external connections. These custom resources are managed by cert-manager. The Issuer or ClusterIssuer specifies the CA that will be used when generating certificates. If you select an ACME server such as Let’s Encrypt as the CA, cert-manager automatically handles the required HTTP01 or DNS01 ACME challenges to issue certificates. 1. Create an Issuer in the same namespace as your Redpanda cluster, or create a ClusterIssuer in any namespace. For details, see the [cert-manager documentation](https://cert-manager.io/docs/configuration/). 2. Configure the Helm chart with your Issuer or ClusterIssuer. Replace the following placeholders: - ``: The name of your Issuer or ClusterIssuer resource. - ``: `Issuer` or `ClusterIssuer`. - ``: Your domain. ### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: tls: enabled: true certs: external: issuerRef: name: kind: caEnabled: false external: domain: ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ### Helm #### --values `external-tls.yaml` ```yaml tls: enabled: true certs: external: issuerRef: name: kind: caEnabled: false external: domain: ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values external-tls.yaml ``` #### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set tls.enabled=true \ --set tls.certs.external.issuerRef.name= \ --set tls.certs.external.issuerRef.kind= \ --set tls.certs.external.caEnabled=false \ --set external.domain= ``` > 📝 **NOTE** > > Enabling or disabling TLS for the RPC listener requires you to delete all Pods that run Redpanda. When you change the `rpc.tls.enabled` setting, or if it is not overridden and you change the global `tls.enabled` option, Redpanda cannot safely apply the change because RPC listener configurations must be the same across all brokers. To apply the change, all Redpanda Pods must be deleted simultaneously so that they all start with the updated RPC listener. This action results in temporary downtime of the cluster. > > Although you can use the `--force` option to speed up the rollout, it may result in data loss as Redpanda will not be given time to shut down gracefully. > > ```bash > kubectl delete pod -l app=redpanda --namespace > ``` 3. Make sure the Certificates are in a `READY` state. ```bash kubectl get certificate --namespace ``` By default, this certificate is used to encrypt traffic between clients and all external listeners. You can select specific certificates for each external listener. See [Configure Listeners in Kubernetes](../../../networking/k-configure-listeners/#tls). ## [](#connect-to-redpanda-2)Connect to Redpanda You can use the `rpk` command-line client to test both internal and external connections to Redpanda. ### [](#test-internal-connections-2)Test internal connections Validate your internal connection to Redpanda with `rpk` by executing the following command. ```bash kubectl exec redpanda-0 --namespace -c redpanda -- rpk cluster info ``` You should see the Kafka API endpoints for the internal listener. For example: CLUSTER ======= redpanda.271dac90-2dc8-48e4-9dc6-652f63684d73 BROKERS ======= ID HOST PORT 0\* redpanda-0.redpanda.redpanda.svc.cluster.local. 9093 1 redpanda-1.redpanda.redpanda.svc.cluster.local. 9093 2 redpanda-2.redpanda.redpanda.svc.cluster.local. 9093 Kubernetes assigns the `*.redpanda.redpanda.svc.cluster.local.` DNS names to the brokers through the headless ClusterIP Service. These are internal Kubernetes addresses. Port 9093 is the default port of the internal listener for the Kafka API. ### [](#test-external-connections-2)Test external connections To test external connections, external access must be enabled on your cluster and your brokers must advertise an address that’s resolvable externally by your clients. To test external connections: 1. Install `rpk` on your local machine, not inside the container: #### Linux > 💡 **TIP** > > You can use `rpk` on Windows only with [WSL](https://learn.microsoft.com/windows/wsl/install). However, commands that require Redpanda to be installed on your machine are not supported, such as [`rpk container`](../../../../../reference/rpk/rpk-container/rpk-container/) commands, [`rpk iotune`](../../../../../reference/rpk/rpk-iotune/), and [`rpk redpanda`](../../../../../reference/rpk/rpk-redpanda/rpk-redpanda/) commands. ##### amd64 ```bash curl -LO https://github.com/redpanda-data/redpanda/releases/latest/download/rpk-linux-amd64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-linux-amd64.zip -d ~/.local/bin/ ``` ##### arm64 ```bash curl -LO https://github.com/redpanda-data/redpanda/releases/latest/download/rpk-linux-arm64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-linux-arm64.zip -d ~/.local/bin/ ``` #### macOS 1. If you don’t have Homebrew installed, [install it](https://brew.sh/). 2. To install or update `rpk`, run: ```bash brew install redpanda-data/tap/redpanda ``` 2. If your TLS certificates were issued by a private CA, save the root CA to your local file system outside Kubernetes: ```bash kubectl --namespace get secret -o go-template='{{ index .data "ca.crt" | base64decode }}' > ca.crt ``` 3. Configure `rpk` to connect to your cluster using the [pre-configured profile](../../../networking/k-connect-to-redpanda/#rpk-profile): ```bash rpk profile create --from-profile <(kubectl get configmap --namespace redpanda-rpk -o go-template='{{ .data.profile }}') ``` 4. Test the connection: ```bash rpk cluster info ``` You should see the Kafka API endpoints for the external listener. For example: CLUSTER ======= redpanda.271dac90-2dc8-48e4-9dc6-652f63684d73 BROKERS ======= ID HOST PORT 0\* redpanda-0.customredpandadomain.local 31092 1 redpanda-1.customredpandadomain.local 31092 2 redpanda-2.customredpandadomain.local 31092 The Helm chart configures brokers with these addresses using the values of the `external.domain` and/or `external.addresses` settings in the Helm values. These are external addresses that external clients use to connect. Port 31092 is the default node port of the external listener for the Kafka API. This node port is assigned to the Kubernetes Services. If your brokers external addresses are not resolvable, you can test external connections by sending API requests to the container port that’s assigned to the external listener. For example: ```bash kubectl exec redpanda-0 -n redpanda -c redpanda -- rpk cluster info -X brokers=redpanda-0.redpanda.redpanda.svc.cluster.local:9094 -X tls.ca=/etc/tls/certs/external/ca.crt ``` Port 9094 is the default container port for the external Kafka API. For more details on connecting to Redpanda, see [Connect to Redpanda in Kubernetes](../../../networking/k-connect-to-redpanda/). ## [](#manage-the-minimum-tls-version)Manage the minimum TLS version Redpanda sets the minimum TLS version for all clusters to 1.2, using the [`tls_min_version`](../../../../../reference/properties/cluster-properties/#tls_min_version) cluster configuration property. This prevents client applications from negotiating a downgrade to the TLS version when they make a connection to a Redpanda cluster. You can update the minimum TLS version of your clusters to `v1.0`, `v1.1` or `v1.3` using `rpk`. Replace the placeholder in brackets. ### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: config: cluster: tls_min_version: ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ### Helm #### --values `tls-version.yaml` ```yaml config: cluster: tls_min_version: ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values tls-version.yaml --reuse-values ``` #### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set config.cluster.tls_min_version= ``` ## [](#configure-mtls-encryption)Configure mTLS encryption Mutual TLS (mTLS), is an enhanced security protocol that extends the standard TLS encryption protocol. While standard TLS involves a server presenting a certificate to the client to prove its identity, mTLS adds an additional layer of security by requiring the client to also present a certificate to the server. To enable mTLS, set the `requireClientAuth` setting to `true` for **all listeners**. ```yaml listeners: kafka: tls: enabled: true cert: default requireClientAuth: true admin: tls: enabled: true cert: default requireClientAuth: true schemaRegistry: tls: enabled: true cert: default requireClientAuth: true rpc: tls: enabled: true cert: default requireClientAuth: true http: tls: enabled: true cert: default requireClientAuth: true ``` When you enable mTLS, the Helm chart generates a TLS Secret resource called `redpanda-client` that contains the client’s `tls.crt` and `tls.key` files. If you want to use your own TLS files, you can instead provide the Helm chart with a custom TLS Secret or Issuer (if you’re using cert-manager) to use in `tls.certs` and then reference its name in your listener configuration. > ❗ **IMPORTANT** > > All listeners must use the same certificate if mTLS is enabled. Redpanda on Kubernetes does not support configuring different TLS certificates for mTLS-enabled listeners, or mixed configurations where some listeners use mTLS and others do not. ```yaml listeners: kafka: tls: enabled: true cert: requireClientAuth: true admin: tls: enabled: true cert: requireClientAuth: true schemaRegistry: tls: enabled: true cert: requireClientAuth: true rpc: tls: enabled: true cert: requireClientAuth: true http: tls: enabled: true cert: requireClientAuth: true ``` ### [](#configure-a-truststore)Configure a truststore To ensure that mTLS functions correctly, it is important to properly configure the truststore. The truststore contains the CA certificates that the server uses to validate the client certificates. By explicitly setting the truststore, you ensure that mTLS will use the correct CA certificates to validate client certificates, enhancing the security and reliability of your Redpanda cluster. To set a truststore for a listener, you can use a Secret or a ConfigMap reference: #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: tls: enabled: true certs: default: caEnabled: true listeners: admin: tls: trustStore: SecretKeyRef: key: name: ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `redpanda-tls.yaml` ```yaml tls: enabled: true certs: default: caEnabled: true listeners: admin: tls: trustStore: SecretKeyRef: key: name: ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values redpanda-tls.yaml --reuse-values ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set tls.enabled=true \ --set tls.certs.default.caEnabled=true \ --set listeners.admin.tls.trustStore.SecretKeyRef.key= \ --set listeners.admin.tls.trustStore.SecretKeyRef.name= ``` ## [](#disable-tls)Disable TLS If you disable TLS, Redpanda communicates over a plain-text network connection, where any malicious party can see all communication. To disable TLS for all listeners, set `tls.enabled` to `false`: `no-tls.yaml` ```yaml tls: enabled: false ``` To disable TLS for a specific listener, set `tls.enabled` to `false` for the listener. For example, to disable TLS for the internal Kafka API listener: ```yaml listeners: kafka: tls: enabled: false ``` Enabling or disabling TLS for the RPC listener requires you to delete all Pods that run Redpanda. When you change the `rpc.tls.enabled` setting, or if it is not overridden and you change the global `tls.enabled` option, Redpanda cannot safely apply the change because RPC listener configurations must be the same across all brokers. To apply the change, all Redpanda Pods must be deleted simultaneously so that they all start with the updated RPC listener. This action results in temporary downtime of the cluster. Although you can use the `--force` option to speed up the rollout, it may result in data loss as Redpanda will not be given time to shut down gracefully. ```bash kubectl delete pod -l app=redpanda --namespace ``` ## [](#troubleshoot)Troubleshoot Here are some common troubleshooting scenarios and their solutions. For more troubleshooting steps, see [Troubleshoot Redpanda in Kubernetes](../../../../../troubleshoot/errors-solutions/k-resolve-errors/). ### [](#io-timeout)I/O timeout This error appears when your worker nodes are unreachable through the given address. Check the following: - The address and port are correct. - Your DNS records point to addresses that resolve to your worker nodes. ### [](#redpanda-not-applying-tls-changes)Redpanda not applying TLS changes Enabling or disabling TLS for the RPC listener requires you to delete all Pods that run Redpanda. When you change the `rpc.tls.enabled` setting, or if it is not overridden and you change the global `tls.enabled` option, Redpanda cannot safely apply the change because RPC listener configurations must be the same across all brokers. To apply the change, all Redpanda Pods must be deleted simultaneously so that they all start with the updated RPC listener. This action results in temporary downtime of the cluster. Although you can use the `--force` option to speed up the rollout, it may result in data loss as Redpanda will not be given time to shut down gracefully. ```bash kubectl delete pod -l app=redpanda --namespace ``` ### [](#invalid-large-response-size)Invalid large response size This error appears when your cluster is configured to use TLS, but you don’t specify that you are connecting over TLS. unable to request metadata: invalid large response size 352518912 > limit 104857600; the first three bytes received appear to be a tls alert record for TLS v1.2; is this a plaintext connection speaking to a tls endpoint? If you’re using `rpk`, ensure to add the `-X tls.enabled` flag, and any other necessary TLS flags such as the TLS certificate: ```bash kubectl exec -c redpanda --namespace -- \ rpk cluster info -X tls.enabled=true ``` For all available flags, see the [`rpk` options reference](../../../../../reference/rpk/rpk-x-options/). ### [](#malformed-http-response)Malformed HTTP response This error appears when a cluster has TLS enabled, and you try to access the admin API without passing the required TLS parameters. Retrying POST for error: Post "http://127.0.0.1:9644/v1/security/users": net/http: HTTP/1.x transport connection broken: malformed HTTP response "\\x15\\x03\\x03\\x00\\x02\\x02" If you’re using `rpk`, ensure to include the TLS flags. For all available flags, see the [`rpk` options reference](../../../../../reference/rpk/rpk-x-options/). ### [](#x509-certificate-signed-by-unknown-authority)x509: certificate signed by unknown authority This error appears when the Certificate Authority (CA) that signed your certificates is not trusted by your system. Check the following: - Ensure you have installed the root CA certificate correctly on your local system. - If using a self-signed certificate, ensure it is properly configured and included in your system’s trust store. - If you are using a certificate issued by a CA, ensure the issuing CA is included in your system’s trust store. - If you are using cert-manager, ensure it is correctly configured and running properly. - Check the validity of your certificates. They might have expired. ### [](#x509-certificate-is-not-valid-for-any-names)x509: certificate is not valid for any names This error indicates that the certificate you are using is not valid for the specific domain or IP address you are trying to use it with. This error typically occurs when there is a mismatch between the certificate’s Subject Alternative Name (SAN) or Common Name (CN) field and the name being used to access the broker. To fix this error, you may need to obtain a new certificate that is valid for the specific domain or IP address you are using. Ensure that the certificate’s SAN or CN entry matches the name being used, and that the certificate is not expired or revoked. ### [](#cannot-validate-certificate-for-127-0-0-1)cannot validate certificate for 127.0.0.1 This error appears if you are using a CA certificate when you try to establish an internal connection using localhost. For example: ```none unable to request metadata: unable to dial: x509: cannot validate certificate for 127.0.0.1 because it doesn't contain any IP SANs ``` To fix this error, you must either specify the URL with a public domain or use self-signed certificates: ```bash kubectl exec redpanda-0 -c redpanda --namespace -- \ rpk cluster info \ -X brokers=: \ -X tls.enabled=true ``` ## [](#next-steps)Next steps - [Configure Authentication for Redpanda in Kubernetes](../../authentication/k-authentication/) - [Configure Listeners in Kubernetes](../../../networking/k-configure-listeners/) - [Connect to Redpanda in Kubernetes](../../../networking/k-connect-to-redpanda/) ## [](#suggested-reading)Suggested reading - [Securing Redpanda in Kubernetes (Day 2 Ops)](https://killercoda.com/redpanda/scenario/redpanda-k8s-secure) - [Redpanda Helm Specification](../../../../../reference/k-redpanda-helm-spec/#external) - [Redpanda CRD Reference](../../../../../reference/k-crd/) ## Suggested labs - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) [Search all labs](/redpanda-labs) --- # Page 192: Use Kubernetes Secrets to manage TLS certificates **URL**: https://docs.redpanda.com/current/manage/kubernetes/security/tls/k-secrets.md --- # Use Kubernetes Secrets to manage TLS certificates --- title: Use Kubernetes Secrets to manage TLS certificates latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/security/tls/k-secrets page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/security/tls/k-secrets.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/security/tls/k-secrets.adoc description: Create TLS files and store them in Kubernetes Secret resources to configure Redpanda listeners with TLS certificates. page-git-created-date: "2024-01-04" page-git-modified-date: "2025-04-07" support-status: supported --- Learn how to configure Redpanda listeners with TLS using TLS certificates in your own Secret resources. Redpanda supports both TLS and mTLS: - TLS, previously SSL, provides encryption for client-server communication. A server certificate prevents third parties from accessing data transferred between the client and server. - mTLS, or mutual TLS, is a protocol that authenticates both the server and the client. In addition to the server certificate required in TLS, mTLS also requires the client to give a certificate. mTLS is useful for environments that require additional security and only have a small number of verified clients. ## [](#prerequisites)Prerequisites You must have the following: - Kubernetes cluster. Ensure you have a running Kubernetes cluster, either locally, such as with minikube or kind, or remotely. - [Kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl). Ensure you have the `kubectl` command-line tool installed and configured to communicate with your cluster. - If you want to connect to your Redpanda cluster from outside Kubernetes, make sure to [enable external access](../../../networking/external/). - Create your TLS certificates. Make sure to include the correct addresses in the SAN: - If you’re creating certificates for internal listeners, make sure to include the internal addresses assigned to brokers by Kubernetes through the headless ClusterIP Service. - If you’re creating certificates for external listeners, make sure to include the external addresses assigned to brokers through the `external.domain` and/or `external.addresses` Helm values. > 💡 **TIP** > > For an example of creating the TLS certificates, see the [`helm-charts` GitHub repository](https://github.com/redpanda-data/helm-charts/blob/main/.github/create_tls.sh). ## [](#create-a-kubernetes-secret)Create a Kubernetes Secret A Secret is an object that contains sensitive data such as a TLS certificate and its associated key. When creating a Secret, you can specify its type using the `type` field of the Secret resource. The type is used to facilitate programmatic handling of the Secret data. For details, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/secret/). The type of Secret you need to create depends on whether you need to store the certificate of the root certificate authority (CA) in the Secret. When using certificates issued by public certificate authorities, you don’t need to provide the root CA in the Secret. Public CAs are already trusted by default in most systems and web browsers. The trust chain is built into the operating system or web browser, which includes the root certificates of well-known CAs. If your certificates are issued by a public CA, create a TLS Secret that includes your `tls.crt` and `tls.key` files: ```bash kubectl create secret tls \ --cert=tls.crt \ --key=tls.key \ --namespace ``` If your certificates are issued by a private CA, create an Opaque Secret that includes the root CA (`ca.crt`) file: ```bash kubectl create secret generic \ --from-file=tls.crt \ --from-file=tls.key \ --from-file=ca.crt \ --namespace ``` Replace the `` placeholders with the paths to your certificate files. ## [](#configure-redpanda-with-the-secret)Configure Redpanda with the Secret You can configure Redpanda to use your TLS certificates for internal or external listeners. the default internal listeners use the TLS certificates defined in `tls.certs.default`. the default external listeners use the TLS certificates defined in `tls.certs.external`. 1. Update your Redpanda Helm configuration to use the Secret: ### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: tls: enabled: true certs: # Internal listeners default: secretRef: name: # External listeners external: secretRef: name: ``` If you are using a private CA, set `caEnabled` to `true`. `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: tls: enabled: true certs: # Internal listeners default: secretRef: name: caEnabled: true # External listeners external: secretRef: name: caEnabled: true ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ### Helm #### --values `tls-secret.yml` ```yaml tls: enabled: true certs: # Internal listeners default: secretRef: name: # External listeners external: secretRef: name: ``` If you are using a private CA, set `caEnabled` to `true`. `tls-secret.yml` ```yaml tls: enabled: true certs: # Internal listeners default: secretRef: name: caEnabled: true # External listeners external: secretRef: name: caEnabled: true ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values tls-secret.yaml --reuse-values ``` #### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set tls.enabled=true \ --set tls.certs.default.secretRef.name= ``` If you are using a private CA, set `caEnabled` to `true`. ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set tls.enabled=true \ --set tls.certs.default.secretRef.name= \ --set tls.certs.default.caEnabled=true ``` > 📝 **NOTE** > > Enabling or disabling TLS for the RPC listener requires you to delete all Pods that run Redpanda. When you change the `rpc.tls.enabled` setting, or if it is not overridden and you change the global `tls.enabled` option, Redpanda cannot safely apply the change because RPC listener configurations must be the same across all brokers. To apply the change, all Redpanda Pods must be deleted simultaneously so that they all start with the updated RPC listener. This action results in temporary downtime of the cluster. > > Although you can use the `--force` option to speed up the rollout, it may result in data loss as Redpanda will not be given time to shut down gracefully. > > ```bash > kubectl delete pod -l app=redpanda --namespace > ``` By default, certificates will be used to encrypt traffic between clients and all external listeners. You can also select specific certificates for each external listener. See [Configure Listeners](../../../networking/k-configure-listeners/#tls). ## [](#connect-to-redpanda)Connect to Redpanda You can use the `rpk` command-line client to test both internal and external connections to Redpanda. ### [](#test-internal-connections)Test internal connections Validate your internal connection to Redpanda with `rpk` by executing the following command. ```bash kubectl exec redpanda-0 --namespace -c redpanda -- rpk cluster info ``` You should see the Kafka API endpoints for the internal listener. For example: CLUSTER ======= redpanda.271dac90-2dc8-48e4-9dc6-652f63684d73 BROKERS ======= ID HOST PORT 0\* redpanda-0.redpanda.redpanda.svc.cluster.local. 9093 1 redpanda-1.redpanda.redpanda.svc.cluster.local. 9093 2 redpanda-2.redpanda.redpanda.svc.cluster.local. 9093 Kubernetes assigns the `*.redpanda.redpanda.svc.cluster.local.` DNS names to the brokers through the headless ClusterIP Service. These are internal Kubernetes addresses. Port 9093 is the default port of the internal listener for the Kafka API. ### [](#test-external-connections)Test external connections To test external connections, external access must be enabled on your cluster and your brokers must advertise an address that’s resolvable externally by your clients. To test external connections: 1. Install `rpk` on your local machine, not inside the container: #### Linux > 💡 **TIP** > > You can use `rpk` on Windows only with [WSL](https://learn.microsoft.com/windows/wsl/install). However, commands that require Redpanda to be installed on your machine are not supported, such as [`rpk container`](../../../../../reference/rpk/rpk-container/rpk-container/) commands, [`rpk iotune`](../../../../../reference/rpk/rpk-iotune/), and [`rpk redpanda`](../../../../../reference/rpk/rpk-redpanda/rpk-redpanda/) commands. ##### amd64 ```bash curl -LO https://github.com/redpanda-data/redpanda/releases/latest/download/rpk-linux-amd64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-linux-amd64.zip -d ~/.local/bin/ ``` ##### arm64 ```bash curl -LO https://github.com/redpanda-data/redpanda/releases/latest/download/rpk-linux-arm64.zip && mkdir -p ~/.local/bin && export PATH="~/.local/bin:$PATH" && unzip rpk-linux-arm64.zip -d ~/.local/bin/ ``` #### macOS 1. If you don’t have Homebrew installed, [install it](https://brew.sh/). 2. To install or update `rpk`, run: ```bash brew install redpanda-data/tap/redpanda ``` 2. If your TLS certificates were issued by a private CA, save the root CA to your local file system outside Kubernetes: ```bash kubectl --namespace get secret -o go-template='{{ index .data "ca.crt" | base64decode }}' > ca.crt ``` 3. Configure `rpk` to connect to your cluster using the [pre-configured profile](../../../networking/k-connect-to-redpanda/#rpk-profile): ```bash rpk profile create --from-profile <(kubectl get configmap --namespace redpanda-rpk -o go-template='{{ .data.profile }}') ``` 4. Test the connection: ```bash rpk cluster info ``` You should see the Kafka API endpoints for the external listener. For example: CLUSTER ======= redpanda.271dac90-2dc8-48e4-9dc6-652f63684d73 BROKERS ======= ID HOST PORT 0\* redpanda-0.customredpandadomain.local 31092 1 redpanda-1.customredpandadomain.local 31092 2 redpanda-2.customredpandadomain.local 31092 The Helm chart configures brokers with these addresses using the values of the `external.domain` and/or `external.addresses` settings in the Helm values. These are external addresses that external clients use to connect. Port 31092 is the default node port of the external listener for the Kafka API. This node port is assigned to the Kubernetes Services. If your brokers external addresses are not resolvable, you can test external connections by sending API requests to the container port that’s assigned to the external listener. For example: ```bash kubectl exec redpanda-0 -n redpanda -c redpanda -- rpk cluster info -X brokers=redpanda-0.redpanda.redpanda.svc.cluster.local:9094 -X tls.ca=/etc/tls/certs/external/ca.crt ``` Port 9094 is the default container port for the external Kafka API. For more details on connecting to Redpanda, see [Connect to Redpanda in Kubernetes](../../../networking/k-connect-to-redpanda/). ## [](#manage-the-minimum-tls-version)Manage the minimum TLS version Redpanda sets the minimum TLS version for all clusters to 1.2, using the [`tls_min_version`](../../../../../reference/properties/cluster-properties/#tls_min_version) cluster configuration property. This prevents client applications from negotiating a downgrade to the TLS version when they make a connection to a Redpanda cluster. You can update the minimum TLS version of your clusters to `v1.0`, `v1.1` or `v1.3` using `rpk`. Replace the placeholder in brackets. ### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: config: cluster: tls_min_version: ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ### Helm #### --values `tls-version.yaml` ```yaml config: cluster: tls_min_version: ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values tls-version.yaml --reuse-values ``` #### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set config.cluster.tls_min_version= ``` ## [](#configure-mtls-encryption)Configure mTLS encryption Mutual TLS (mTLS), is an enhanced security protocol that extends the standard TLS encryption protocol. While standard TLS involves a server presenting a certificate to the client to prove its identity, mTLS adds an additional layer of security by requiring the client to also present a certificate to the server. To enable mTLS, set the `requireClientAuth` setting to `true` for **all listeners**. ```yaml listeners: kafka: tls: enabled: true cert: default requireClientAuth: true admin: tls: enabled: true cert: default requireClientAuth: true schemaRegistry: tls: enabled: true cert: default requireClientAuth: true rpc: tls: enabled: true cert: default requireClientAuth: true http: tls: enabled: true cert: default requireClientAuth: true ``` When you enable mTLS, the Helm chart generates a TLS Secret resource called `redpanda-client` that contains the client’s `tls.crt` and `tls.key` files. If you want to use your own TLS files, you can instead provide the Helm chart with a custom TLS Secret or Issuer (if you’re using cert-manager) to use in `tls.certs` and then reference its name in your listener configuration. > ❗ **IMPORTANT** > > All listeners must use the same certificate if mTLS is enabled. Redpanda on Kubernetes does not support configuring different TLS certificates for mTLS-enabled listeners, or mixed configurations where some listeners use mTLS and others do not. ```yaml listeners: kafka: tls: enabled: true cert: requireClientAuth: true admin: tls: enabled: true cert: requireClientAuth: true schemaRegistry: tls: enabled: true cert: requireClientAuth: true rpc: tls: enabled: true cert: requireClientAuth: true http: tls: enabled: true cert: requireClientAuth: true ``` ### [](#configure-a-truststore)Configure a truststore To ensure that mTLS functions correctly, it is important to properly configure the truststore. The truststore contains the CA certificates that the server uses to validate the client certificates. By explicitly setting the truststore, you ensure that mTLS will use the correct CA certificates to validate client certificates, enhancing the security and reliability of your Redpanda cluster. To set a truststore for a listener, you can use a Secret or a ConfigMap reference: #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: tls: enabled: true certs: default: caEnabled: true listeners: admin: tls: trustStore: SecretKeyRef: key: name: ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `redpanda-tls.yaml` ```yaml tls: enabled: true certs: default: caEnabled: true listeners: admin: tls: trustStore: SecretKeyRef: key: name: ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values redpanda-tls.yaml --reuse-values ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set tls.enabled=true \ --set tls.certs.default.caEnabled=true \ --set listeners.admin.tls.trustStore.SecretKeyRef.key= \ --set listeners.admin.tls.trustStore.SecretKeyRef.name= ``` ## [](#disable-tls)Disable TLS If you disable TLS, Redpanda communicates over a plain-text network connection, where any malicious party can see all communication. To disable TLS for all listeners, set `tls.enabled` to `false`: `no-tls.yaml` ```yaml tls: enabled: false ``` To disable TLS for a specific listener, set `tls.enabled` to `false` for the listener. For example, to disable TLS for the internal Kafka API listener: ```yaml listeners: kafka: tls: enabled: false ``` Enabling or disabling TLS for the RPC listener requires you to delete all Pods that run Redpanda. When you change the `rpc.tls.enabled` setting, or if it is not overridden and you change the global `tls.enabled` option, Redpanda cannot safely apply the change because RPC listener configurations must be the same across all brokers. To apply the change, all Redpanda Pods must be deleted simultaneously so that they all start with the updated RPC listener. This action results in temporary downtime of the cluster. Although you can use the `--force` option to speed up the rollout, it may result in data loss as Redpanda will not be given time to shut down gracefully. ```bash kubectl delete pod -l app=redpanda --namespace ``` ## [](#troubleshoot)Troubleshoot Here are some common troubleshooting scenarios and their solutions. For more troubleshooting steps, see [Troubleshoot Redpanda in Kubernetes](../../../../../troubleshoot/errors-solutions/k-resolve-errors/). ### [](#io-timeout)I/O timeout This error appears when your worker nodes are unreachable through the given address. Check the following: - The address and port are correct. - Your DNS records point to addresses that resolve to your worker nodes. ### [](#redpanda-not-applying-tls-changes)Redpanda not applying TLS changes Enabling or disabling TLS for the RPC listener requires you to delete all Pods that run Redpanda. When you change the `rpc.tls.enabled` setting, or if it is not overridden and you change the global `tls.enabled` option, Redpanda cannot safely apply the change because RPC listener configurations must be the same across all brokers. To apply the change, all Redpanda Pods must be deleted simultaneously so that they all start with the updated RPC listener. This action results in temporary downtime of the cluster. Although you can use the `--force` option to speed up the rollout, it may result in data loss as Redpanda will not be given time to shut down gracefully. ```bash kubectl delete pod -l app=redpanda --namespace ``` ### [](#invalid-large-response-size)Invalid large response size This error appears when your cluster is configured to use TLS, but you don’t specify that you are connecting over TLS. unable to request metadata: invalid large response size 352518912 > limit 104857600; the first three bytes received appear to be a tls alert record for TLS v1.2; is this a plaintext connection speaking to a tls endpoint? If you’re using `rpk`, ensure to add the `-X tls.enabled` flag, and any other necessary TLS flags such as the TLS certificate: ```bash kubectl exec -c redpanda --namespace -- \ rpk cluster info -X tls.enabled=true ``` For all available flags, see the [`rpk` options reference](../../../../../reference/rpk/rpk-x-options/). ### [](#malformed-http-response)Malformed HTTP response This error appears when a cluster has TLS enabled, and you try to access the admin API without passing the required TLS parameters. Retrying POST for error: Post "http://127.0.0.1:9644/v1/security/users": net/http: HTTP/1.x transport connection broken: malformed HTTP response "\\x15\\x03\\x03\\x00\\x02\\x02" If you’re using `rpk`, ensure to include the TLS flags. For all available flags, see the [`rpk` options reference](../../../../../reference/rpk/rpk-x-options/). ### [](#x509-certificate-signed-by-unknown-authority)x509: certificate signed by unknown authority This error appears when the Certificate Authority (CA) that signed your certificates is not trusted by your system. Check the following: - Ensure you have installed the root CA certificate correctly on your local system. - If using a self-signed certificate, ensure it is properly configured and included in your system’s trust store. - If you are using a certificate issued by a CA, ensure the issuing CA is included in your system’s trust store. - If you are using cert-manager, ensure it is correctly configured and running properly. - Check the validity of your certificates. They might have expired. ### [](#x509-certificate-is-not-valid-for-any-names)x509: certificate is not valid for any names This error indicates that the certificate you are using is not valid for the specific domain or IP address you are trying to use it with. This error typically occurs when there is a mismatch between the certificate’s Subject Alternative Name (SAN) or Common Name (CN) field and the name being used to access the broker. To fix this error, you may need to obtain a new certificate that is valid for the specific domain or IP address you are using. Ensure that the certificate’s SAN or CN entry matches the name being used, and that the certificate is not expired or revoked. ### [](#cannot-validate-certificate-for-127-0-0-1)cannot validate certificate for 127.0.0.1 This error appears if you are using a CA certificate when you try to establish an internal connection using localhost. For example: ```none unable to request metadata: unable to dial: x509: cannot validate certificate for 127.0.0.1 because it doesn't contain any IP SANs ``` To fix this error, you must either specify the URL with a public domain or use self-signed certificates: ```bash kubectl exec redpanda-0 -c redpanda --namespace -- \ rpk cluster info \ -X brokers=: \ -X tls.enabled=true ``` ## [](#next-steps)Next steps - [Configure Authentication for Redpanda in Kubernetes](../../authentication/k-authentication/) - [Configure Listeners in Kubernetes](../../../networking/k-configure-listeners/) - [Connect to Redpanda in Kubernetes](../../../networking/k-connect-to-redpanda/) ## [](#suggested-reading)Suggested reading - [Securing Redpanda in Kubernetes (Day 2 Ops)](https://killercoda.com/redpanda/scenario/redpanda-k8s-secure) - [Redpanda Helm Specification](../../../../../reference/k-redpanda-helm-spec/#external) - [Redpanda CRD Reference](../../../../../reference/k-crd/) ## Suggested labs - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) [Search all labs](/redpanda-labs) --- # Page 193: Shadowing in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/shadowing.md --- # Shadowing in Kubernetes --- title: Shadowing in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/shadowing/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/shadowing/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/shadowing/index.adoc description: Configure and manage shadow links for disaster recovery in Kubernetes deployments. page-git-created-date: "2025-12-16" page-git-modified-date: "2025-12-16" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../get-started/licensing/#self-managed) apply. Shadow linking enables asynchronous, unidirectional replication between Redpanda clusters for disaster recovery. Configure shadow links using the Redpanda Operator’s `ShadowLink` custom resource or using `rpk` commands. > ❗ **IMPORTANT: Experiencing an active disaster?** > > See [Kubernetes Failover Runbook](k-failover-runbook/) for immediate step-by-step disaster procedures. For general shadowing concepts and architecture, see [Shadowing Overview](../../disaster-recovery/shadowing/overview/). - [Configure Shadowing in Kubernetes](k-shadow-linking/) Set up disaster recovery with Shadowing using the Redpanda Operator or Helm chart. - [Monitor Kubernetes Shadow Links](k-monitor-shadowing/) Monitor shadow link health in Kubernetes using ShadowLink resources, status commands, metrics, and best practices. - [Kubernetes Failover Runbook](k-failover-runbook/) Step-by-step emergency guide for failing over Redpanda shadow links in Kubernetes during disasters. --- # Page 194: Kubernetes Failover Runbook **URL**: https://docs.redpanda.com/current/manage/kubernetes/shadowing/k-failover-runbook.md --- # Kubernetes Failover Runbook --- title: Kubernetes Failover Runbook latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/shadowing/k-failover-runbook page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/shadowing/k-failover-runbook.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/shadowing/k-failover-runbook.adoc description: Step-by-step emergency guide for failing over Redpanda shadow links in Kubernetes during disasters. page-git-created-date: "2025-12-16" page-git-modified-date: "2025-12-16" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../../get-started/licensing/#self-managed) apply. This guide provides step-by-step procedures for emergency failover when your primary Redpanda cluster becomes unavailable. Follow these procedures only during active disasters when immediate failover is required. > ❗ **IMPORTANT** > > This is an emergency procedure. For planned failover testing or day-to-day shadow link management, see [Failover](../../../disaster-recovery/shadowing/failover/). Ensure you have completed the [disaster readiness checklist](../../../disaster-recovery/shadowing/overview/#disaster-readiness-checklist) before an emergency occurs. ## [](#emergency-failover-procedure)Emergency failover procedure Follow these steps during an active disaster: 1. [Assess the situation](#assess-situation) 2. [Verify shadow cluster status](#verify-shadow-status) 3. [Document current state](#document-state) 4. [Initiate failover](#initiate-failover) 5. [Monitor failover progress](#monitor-progress) 6. [Update application configuration](#update-applications) 7. [Verify application functionality](#verify-functionality) 8. [Clean up and stabilize](#cleanup-stabilize) ### [](#assess-situation)Assess the situation Confirm that failover is necessary: #### Operator ```bash # Check if source cluster is responding kubectl exec --namespace --container redpanda -- \ rpk cluster info # If source cluster is down, check shadow cluster health kubectl exec --namespace --container redpanda -- \ rpk cluster info ``` #### Helm ```bash # Check if source cluster is responding kubectl exec --namespace --container redpanda -- \ rpk cluster info # If source cluster is down, check shadow cluster health kubectl exec --namespace --container redpanda -- \ rpk cluster info ``` **Decision point**: If the primary cluster is responsive, consider whether failover is actually needed. Partial outages may not require full disaster recovery. **Examples that require full failover:** - Primary cluster is completely unreachable (network partition, regional outage) - Multiple broker failures preventing writes to critical topics - Data center failure affecting majority of brokers - Persistent authentication or authorization failures across the cluster **Examples that may NOT require failover:** - Single broker failure with sufficient replicas remaining - Temporary network connectivity issues affecting some clients - High latency or performance degradation (but cluster still functional) - Non-critical topic or partition unavailability ### [](#verify-shadow-status)Verify shadow cluster status Check the health of your shadow links: #### Operator ```bash # List all shadow links kubectl get shadowlink --namespace # Check the ShadowLink resource details kubectl describe shadowlink --namespace ``` Verify that the following conditions exist before proceeding with failover: - ShadowLink resource shows `Synced: True` in conditions - Shadow topic statuses show `state: active` (not `faulted`) - Task statuses show `state: active` #### Helm ```bash # List all shadow links kubectl exec --namespace --container redpanda -- \ rpk shadow list # Check the configuration of your shadow link kubectl exec --namespace --container redpanda -- \ rpk shadow describe # Check the status of your disaster recovery link kubectl exec --namespace --container redpanda -- \ rpk shadow status ``` For detailed command options, see [`rpk shadow list`](../../../../reference/rpk/rpk-shadow/rpk-shadow-list/), [`rpk shadow describe`](../../../../reference/rpk/rpk-shadow/rpk-shadow-describe/), and [`rpk shadow status`](../../../../reference/rpk/rpk-shadow/rpk-shadow-status/). Verify that the following conditions exist before proceeding with failover: - Shadow link state should be `ACTIVE` - Topics should be in `ACTIVE` state (not `FAULTED`) - Replication lag should be reasonable for your RPO requirements #### [](#understanding-replication-lag)Understanding replication lag Use status commands to check lag, which shows the message count difference between source and shadow partitions: - **Acceptable lag examples**: 0-1000 messages for low-throughput topics, 0-10000 messages for high-throughput topics - **Concerning lag examples**: Growing lag over 50,000 messages, or lag that continuously increases without recovering - **Critical lag examples**: Lag exceeding your data loss tolerance (for example, if you can only afford to lose 1 minute of data, lag should represent less than 1 minute of typical message volume) ### [](#document-state)Document current state Record the current lag and status before proceeding: #### Operator ```bash # Capture current status for post-mortem analysis kubectl describe shadowlink --namespace > failover-status-$(date +%Y%m%d-%H%M%S).log ``` #### Helm ```bash # Capture current status for post-mortem analysis kubectl exec --namespace --container redpanda -- \ rpk shadow status > failover-status-$(date +%Y%m%d-%H%M%S).log ``` > ❗ **IMPORTANT** > > Note the replication lag to estimate potential data loss during failover. For details about shadow link replication tasks, see [Shadow link tasks](../../../disaster-recovery/shadowing/overview/#shadow-link-tasks). ### [](#initiate-failover)Initiate failover A complete cluster failover is appropriate if you observe that the source cluster is no longer reachable: #### Operator Delete the `ShadowLink` resource to fail over all topics: ```bash kubectl delete shadowlink --namespace ``` Expected output shadowlink.cluster.redpanda.com "" deleted This immediately converts all shadow topics to regular writable topics and stops replication. > 📝 **NOTE** > > The Redpanda Operator does not support selective topic failover. For selective failover, use the `rpk` commands shown in the Helm tab. #### Helm For complete cluster failover (all topics): ```bash kubectl exec --namespace --container redpanda -- \ rpk shadow failover --all ``` **Expected output**: Successfully initiated the Fail Over for Shadow Link "". To check the status, run: rpk shadow status For selective topic failover (when only specific services are affected): ```bash # Fail over individual topics kubectl exec --namespace --container redpanda -- \ rpk shadow failover --topic ``` For detailed command options, see [`rpk shadow failover`](../../../../reference/rpk/rpk-shadow/rpk-shadow-failover/). ### [](#monitor-progress)Monitor failover progress Track the failover process: #### Operator After deleting the `ShadowLink` resource, verify topics are now writable: ```bash # Check that shadow link is gone kubectl get shadowlink --namespace # List topics on shadow cluster kubectl exec --namespace --container redpanda -- \ rpk topic list # Test write to a previously shadow topic echo "test message" | kubectl exec --namespace --container redpanda -i -- \ rpk topic produce ``` Expected output for kubectl get No resources found in namespace. Expected output for rpk topic produce Produced to partition 0 at offset 123 with timestamp 1734567890123. If the shadow link is deleted and you can successfully produce to topics, failover is complete. #### Helm Monitor status until all topics show `FAILED_OVER`: ```bash # Monitor status during failover watch -n 5 "kubectl exec --namespace --container redpanda -- rpk shadow status " # Check detailed topic status kubectl exec --namespace --container redpanda -- \ rpk shadow status --print-topic ``` Expected output during failover OVERVIEW === NAME disaster-recovery-link STATE ACTIVE TOPICS === Name: orders, State: FAILED\_OVER Name: inventory, State: FAILED\_OVER Name: transactions, State: FAILING\_OVER Wait for all critical topics to reach `FAILED_OVER` state before proceeding. ### [](#update-applications)Update application configuration Redirect your applications to the shadow cluster by updating connection strings in your applications to point to shadow cluster brokers. If using DNS-based service discovery, update DNS records accordingly. Restart applications to pick up new connection settings and verify connectivity from application hosts to shadow cluster. ### [](#verify-functionality)Verify application functionality Test critical application workflows: ```bash # Verify applications can produce messages echo "failover test" | kubectl exec --namespace --container redpanda -i -- \ rpk topic produce # Verify applications can consume messages kubectl exec --namespace --container redpanda -- \ rpk topic consume --num 1 ``` Expected output for produce Produced to partition 0 at offset 456 with timestamp 1734567890456. Expected output for consume { "topic": "", "value": "failover test", "timestamp": 1734567890456, "partition": 0, "offset": 456 } Test message production and consumption, consumer group functionality, and critical business workflows to ensure everything is working properly. ### [](#cleanup-stabilize)Clean up and stabilize After all applications are running normally: #### Operator The `ShadowLink` resource has already been deleted during failover. No additional cleanup is needed. #### Helm Optionally delete the shadow link (no longer needed): ```bash kubectl exec --namespace --container redpanda -- \ rpk shadow delete ``` For detailed command options, see [`rpk shadow delete`](../../../../reference/rpk/rpk-shadow/rpk-shadow-delete/). Document the time of failover initiation and completion, applications affected and recovery times, data loss estimates based on replication lag, and issues encountered during failover. ## [](#troubleshoot)Troubleshoot ### [](#application-connection-failures-after-failover)Application connection failures after failover Applications may not be able to connect to the shadow cluster after failover. Verify shadow cluster Kubernetes Service endpoints: ```bash kubectl get service --namespace ``` Check NetworkPolicy if using network policies: ```bash kubectl get networkpolicy --namespace ``` Confirm authentication credentials are valid for the shadow cluster and test network connectivity from application hosts. ### [](#consumer-group-offset-issues-after-failover)Consumer group offset issues after failover After failover, consumers may start from the beginning or wrong positions. Verify consumer group offsets were replicated (check your shadow link filters): ```bash kubectl exec --namespace --container redpanda -- \ rpk group describe ``` If necessary, manually reset offsets to appropriate positions. See [How to manage consumer group offsets in Redpanda](https://support.redpanda.com/hc/en-us/articles/23499121317399-How-to-manage-consumer-group-offsets-in-Redpanda) for detailed reset procedures. ## [](#next-steps)Next steps After successful failover, focus on recovery planning and process improvement. Begin by assessing the source cluster failure and determining whether to restore the original cluster or permanently promote the shadow cluster as your new primary. **Immediate recovery planning:** 1. **Assess source cluster**: Determine root cause of the outage 2. **Plan recovery**: Decide whether to restore source cluster or promote shadow cluster permanently 3. **Data synchronization**: Plan how to synchronize any data produced during failover 4. **Fail forward**: Create a new shadow link with the failed over shadow cluster as source to maintain a DR cluster **Process improvement:** 1. **Document the incident**: Record timeline, impact, and lessons learned 2. **Update runbooks**: Improve procedures based on what you learned 3. **Test regularly**: Schedule regular disaster recovery drills 4. **Review monitoring**: Ensure monitoring caught the issue appropriately For general failover concepts and procedures, see [Failover](../../../disaster-recovery/shadowing/failover/). --- # Page 195: Monitor Kubernetes Shadow Links **URL**: https://docs.redpanda.com/current/manage/kubernetes/shadowing/k-monitor-shadowing.md --- # Monitor Kubernetes Shadow Links --- title: Monitor Kubernetes Shadow Links latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/shadowing/k-monitor-shadowing page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/shadowing/k-monitor-shadowing.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/shadowing/k-monitor-shadowing.adoc description: Monitor shadow link health in Kubernetes using ShadowLink resources, status commands, metrics, and best practices. page-git-created-date: "2025-12-16" page-git-modified-date: "2026-01-06" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../../get-started/licensing/#self-managed) apply. Monitor your [shadow links](../k-shadow-linking/) to ensure proper replication performance and understand your disaster recovery readiness. For Kubernetes deployments, you can monitor shadow links using the Redpanda Operator’s `ShadowLink` resource status or by using `rpk` commands directly. > ❗ **IMPORTANT: Experiencing an active disaster?** > > See [Kubernetes Failover Runbook](../k-failover-runbook/) for immediate step-by-step disaster procedures. ## [](#status-commands)Status commands ### Operator To list existing shadow links: ```bash kubectl get shadowlink --namespace ``` Example output NAME SYNCED link True The synced status is `True` for a healthy shadow link. If the synced status is `False`, use `kubectl describe` to investigate the issue. To view detailed shadow link status and configuration: ```bash kubectl describe shadowlink --namespace ``` Example output Name: link Namespace: redpanda-system API Version: cluster.redpanda.com/v1alpha2 Kind: ShadowLink Status: Conditions: Status: True Type: Synced Message: Shadow link is synced Shadow Topics: Name: orders State: active Name: inventory State: active Tasks: Name: Source Topic Sync State: active Name: Consumer Group Shadowing State: active Name: Security Migrator State: active The `kubectl describe` output shows: - **Shadow link state**: Overall operational state in the `Status` section - **Individual topic states**: Current state of each replicated topic under `Shadow Topics` - **Task status**: Health of replication tasks under `Tasks` - **Sync status**: Whether the resource is properly synced (`Synced: True` in conditions) - **Configuration**: Complete shadow link configuration including connection settings and filters Look for `Synced: True` in Conditions and `active` state for topics and tasks. For more detailed monitoring or troubleshooting, you can also use `rpk` commands as shown in the Helm tab. ### Helm To list existing shadow links: ```bash kubectl exec --namespace --container redpanda -- \ rpk shadow list ``` Example output NAME UID STATE disaster-recovery-link 70f25b41-9bad-4e31-9f81-d302c8676397 ACTIVE To view shadow link configuration details: ```bash kubectl exec --namespace --container redpanda -- \ rpk shadow describe ``` For detailed command options, see [`rpk shadow list`](../../../../reference/rpk/rpk-shadow/rpk-shadow-list/) and [`rpk shadow describe`](../../../../reference/rpk/rpk-shadow/rpk-shadow-describe/). This command shows the complete configuration of the shadow link, including connection settings, filters, and synchronization options. To check your shadow link status and ensure proper operation: ```bash kubectl exec --namespace --container redpanda -- \ rpk shadow status ``` Example output OVERVIEW === NAME disaster-recovery-link UID 70f25b41-9bad-4e31-9f81-d302c8676397 STATE ACTIVE TASKS === NAME BROKER\_ID SHARD STATE REASON Source Topic Sync 0 0 ACTIVE Source Topic Sync has started Consumer Group Shadowing 0 0 ACTIVE Group mirroring task finished successfully Security Migrator Task 0 0 ACTIVE Security Migrator Task has started TOPICS === Name: orders, State: ACTIVE PARTITION SRC\_LSO SRC\_HWM DST\_HWM LAG 0 1000 1234 1230 4 1 2000 2456 2450 6 Name: inventory, State: ACTIVE PARTITION SRC\_LSO SRC\_HWM DST\_HWM LAG 0 500 789 789 0 Key indicators: - **State: active**: Shadow link is replicating - **Tasks: active**: All replication tasks are running - **Lag**: Message count difference between source and shadow (lower is better) For troubleshooting specific issues, you can use command options to show individual status sections. See [`rpk shadow status`](../../../../reference/rpk/rpk-shadow/rpk-shadow-status/) for available status options. The status output includes the following: - **Shadow link state**: Overall operational state (`ACTIVE`, `PAUSED`). - **Individual topic states**: Current state of each replicated topic (`ACTIVE`, `FAULTED`, `FAILING_OVER`, `FAILED_OVER`, `PAUSED`). - **Task status**: Health of replication tasks across brokers (`ACTIVE`, `FAULTED`, `NOT_RUNNING`, `LINK_UNAVAILABLE`). For details about shadow link tasks, see [Shadow link tasks](../../../disaster-recovery/shadowing/overview/#shadow-link-tasks). - **Lag information**: Replication lag per partition showing source vs shadow high watermarks (HWM). ## [](#troubleshoot)Troubleshoot ### [](#topics-in-faulted-state)Topics in FAULTED state When monitoring shadow links, you may see topics showing `FAULTED` state in status output. Check shadow cluster logs for specific error messages: ```bash kubectl logs --namespace --container redpanda | grep -i "shadow\|error" ``` Common causes include: - Source topic deleted: topic no longer exists on source cluster - Permission denied: shadow link service account lacks required permissions - Network interruption: temporary connectivity issues If the source topic still exists and should be replicated, delete and recreate the shadow link to reset the faulted state. ### [](#high-replication-lag)High replication lag When monitoring shadow links, you may see LAG values continuously increasing in `rpk shadow status`. Check the following: - Check source cluster load: high produce rate may exceed replication capacity - Check shadow cluster resources: CPU, memory, or disk constraints - Check network bandwidth: verify sufficient bandwidth between clusters To resolve: - Scale shadow cluster resources if constrained - Verify network connectivity and bandwidth - Review topic configuration for optimization opportunities ### [](#task-shows-link_unavailable)Task shows LINK\_UNAVAILABLE When monitoring shadow links, you may see tasks showing `LINK_UNAVAILABLE` state with "No brokers available" message. Common causes include: - Source cluster requires SASL authentication but shadow link not configured for it - Source cluster unreachable from shadow cluster - Network policy blocking traffic between clusters To resolve: - Verify SASL configuration if source cluster requires authentication - Test network connectivity: `kubectl exec` into shadow pod and try connecting to source cluster - Check Kubernetes NetworkPolicies and firewall rules ## [](#shadow-link-metrics)Metrics Shadowing provides comprehensive metrics to track replication performance and health with the [`public_metrics`](../../../../reference/public-metrics-reference/) endpoint. | Metric | Type | Description | | --- | --- | --- | | redpanda_shadow_link_shadow_lag | Gauge | The lag of the shadow partition against the source partition, calculated as source partition LSO (Last Stable Offset) minus shadow partition HWM (High Watermark). Monitor by shadow_link_name, topic, and partition to understand replication lag for each partition. | | redpanda_shadow_link_total_bytes_fetched | Count | The total number of bytes fetched by a sharded replicator (bytes received by the client). Labeled by shadow_link_name and shard to track data transfer volume from the source cluster. | | redpanda_shadow_link_total_bytes_written | Count | The total number of bytes written by a sharded replicator (bytes written to the write_at_offset_stm). Uses shadow_link_name and shard labels to monitor data written to the shadow cluster. | | redpanda_shadow_link_client_errors | Count | The number of errors seen by the client. Track by shadow_link_name and shard to identify connection or protocol issues between clusters. | | redpanda_shadow_link_shadow_topic_state | Gauge | Number of shadow topics in the respective states. Labeled by shadow_link_name and state to monitor topic state distribution across your shadow links. | | redpanda_shadow_link_total_records_fetched | Count | The total number of records fetched by the sharded replicator (records received by the client). Monitor by shadow_link_name and shard to track message throughput from the source. | | redpanda_shadow_link_total_records_written | Count | The total number of records written by a sharded replicator (records written to the write_at_offset_stm). Uses shadow_link_name and shard labels to monitor message throughput to the shadow cluster. | See also: [Public Metrics](../../../../reference/public-metrics-reference/) ## [](#monitoring-best-practices)Monitoring best practices ### [](#health-check-procedures)Health check procedures Establish regular monitoring workflows to ensure shadow link health: #### Operator ```bash # Check all shadow links are synced and healthy kubectl get shadowlink --namespace # View detailed status for a specific shadow link kubectl describe shadowlink --namespace # Check for any shadow links with issues (not synced) kubectl get shadowlink --namespace -o json | \ jq '.items[] | select(.status.conditions[] | select(.type=="Synced" and .status!="True")) | .metadata.name' ``` #### Helm ```bash # Check all shadow links are active kubectl exec --namespace --container redpanda -- \ rpk shadow list | grep -v "ACTIVE" || echo "All shadow links healthy" # Monitor lag for critical topics kubectl exec --namespace --container redpanda -- \ rpk shadow status | grep -E "LAG|Lag" ``` ### [](#alert-conditions)Alert conditions Configure monitoring alerts for the following conditions, which indicate problems with Shadowing: - **High replication lag**: When `redpanda_shadow_link_shadow_lag` exceeds your RPO requirements - **Connection errors**: When `redpanda_shadow_link_client_errors` increases rapidly - **Topic state changes**: When topics move to `FAULTED` state - **Task failures**: When replication tasks enter `FAULTED` or `NOT_RUNNING` states - **Throughput drops**: When bytes/records fetched drops significantly - **Link unavailability**: When tasks show `LINK_UNAVAILABLE` indicating source cluster connectivity issues For more information about shadow link tasks and their states, see [Shadow link tasks](../../../disaster-recovery/shadowing/overview/#shadow-link-tasks). --- # Page 196: Configure Shadowing in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/shadowing/k-shadow-linking.md --- # Configure Shadowing in Kubernetes --- title: Configure Shadowing in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/shadowing/k-shadow-linking page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/shadowing/k-shadow-linking.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/shadowing/k-shadow-linking.adoc description: Set up disaster recovery with Shadowing using the Redpanda Operator or Helm chart. page-git-created-date: "2025-12-16" page-git-modified-date: "2026-01-14" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../../get-started/licensing/#self-managed) apply. Shadowing provides disaster recovery for Redpanda clusters through asynchronous, offset-preserving replication. To set up Shadowing, you create a shadow link and configure filters to select which topics, consumer groups, and ACLs to replicate. Redpanda offers two Kubernetes deployment methods with different shadow link management workflows. For conceptual information about Shadowing, see [Shadowing Overview](../../../disaster-recovery/shadowing/overview/). ## [](#prerequisites)Prerequisites ### [](#license-and-version-requirements)License and version requirements - Both clusters must be running Redpanda v25.3 or later. - [Redpanda Operator version 25.3.1 or later](../../../../deploy/redpanda/kubernetes/k-deployment-overview/) (for Operator deployments). - [Redpanda Helm chart version 25.3.1 or later](../../../../deploy/redpanda/kubernetes/k-deployment-overview/) (for Helm deployments). - You must have [Enterprise Edition](../../../../get-started/licensing/overview/) licenses on both clusters. - If using Redpanda Console, ensure it is running v3.30 or later for managing Shadowing. ### [](#cluster-configuration)Cluster configuration The shadow cluster must have the [`enable_shadow_linking`](../../../../reference/properties/cluster-properties/#enable_shadow_linking) cluster property set to `true`. #### Operator Set this property in your Redpanda custom resource: ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: clusterSpec: config: cluster: enable_shadow_linking: true ``` #### Helm Set this property in your Helm values file: ```yaml config: cluster: enable_shadow_linking: true ``` ### [](#replication-service-account)Replication service account A service account (SASL user) on the source cluster is required for shadow link replication only when SASL authentication is enabled on the source cluster. When SASL authentication is disabled on the source cluster, no service account credentials are required for shadow link setup. When SASL authentication is enabled, the service account must have the following [ACL](../../../security/authorization/acl/) permissions: - **Topics**: `read` permission on all topics you want to replicate - **Topic configurations**: `describe_configs` permission on topics for configuration synchronization - **Consumer groups**: `describe` and `read` permission on consumer groups for offset replication - **ACLs**: `describe` permission on ACL resources to replicate security policies - **Cluster**: `describe` permission on the cluster resource to access ACLs This service account authenticates from the shadow cluster to the source cluster and performs the data replication. #### Operator When using `clusterRef` to connect to a source cluster managed by the same operator, authentication is handled automatically. The operator creates a `kubernetes-controller` user on both clusters when SASL is enabled. When using `staticConfiguration` to connect to an external source cluster with SASL enabled, you must provide credentials for a service account that exists on the source cluster. Create the service account using the `User` CRD (see [Manage Users and ACLs with the Redpanda Operator](../../security/authentication/k-user-controller/)). #### Helm Create the replication service account on the source cluster using one of these methods: In your Helm values file: ```yaml auth: sasl: enabled: true users: - name: replication-user password: mechanism: SCRAM-SHA-512 ``` Or using `rpk` after deployment: ```bash kubectl exec --namespace --container redpanda -- \ rpk security user create replication-user \ --password \ --mechanism SCRAM-SHA-512 ``` Then configure the [required ACL permissions](#acl). ### [](#network-connectivity)Network connectivity You must configure network connectivity between clusters with appropriate firewall rules to allow the shadow cluster to connect to the source cluster for data replication. Shadowing uses a pull-based architecture where the shadow cluster fetches data from the source cluster. In Kubernetes, ensure: - The shadow cluster can reach the source cluster’s Kafka API endpoints. This may involve configuring Kubernetes NetworkPolicies, Services, or Ingress resources. - If using TLS, the shadow cluster has access to the source cluster’s CA certificate. - Network policies allow egress from the shadow cluster to the source cluster. For Kubernetes-specific networking configuration, see [Networking and Connectivity in Kubernetes](../../networking/). ## [](#deploy-redpanda-clusters)Deploy Redpanda clusters Deploy both your source and shadow Redpanda clusters with Shadowing enabled. See [Deploy Redpanda in Kubernetes](../../../../deploy/redpanda/kubernetes/k-deployment-overview/) for full deployment instructions. ## [](#create-a-shadow-link)Create a shadow link In the examples, `` represents the namespace where your shadow Redpanda cluster is deployed, and `` represents the namespace where your source Redpanda cluster is deployed. The shadow cluster and its associated resources (shadow links, secrets) should be deployed in the same namespace as the shadow cluster. ### Operator 1. Create a shadow link using the `ShadowLink` CRD. The CRD supports two connection methods. - For clusters managed by the same operator, use `clusterRef`: Create a shadow link that references both clusters by name: `shadowlink.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: ShadowLink metadata: name: link spec: shadowCluster: clusterRef: name: sasl sourceCluster: clusterRef: name: basic topicMetadataSyncOptions: interval: 2s autoCreateShadowTopicFilters: - name: topic1 filterType: include patternType: literal ``` This example uses example resource names. Replace `redpanda-shadow` and `redpanda-source` with your actual cluster names. The operator automatically resolves cluster connection details from the referenced `Redpanda` resources. > 📝 **NOTE** > > When using `clusterRef`, the operator handles authentication automatically using the cluster’s internal credentials. For cross-namespace or external clusters, use `staticConfiguration` instead. - For external or cross-namespace clusters, use `staticConfiguration`: Create a shadow link with explicit connection details: `shadowlink.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: ShadowLink metadata: name: disaster-recovery-link spec: shadowCluster: clusterRef: name: redpanda-shadow sourceCluster: staticConfiguration: kafka: brokers: - redpanda-source-0.redpanda-source.source.svc.cluster.local.:9093 - redpanda-source-1.redpanda-source.source.svc.cluster.local.:9093 - redpanda-source-2.redpanda-source.source.svc.cluster.local.:9093 tls: enabled: true caCertSecretRef: name: redpanda-source-default-cert key: ca.crt sasl: mechanism: SCRAM-SHA-512 username: replication-user passwordSecretRef: name: source-cluster-credentials key: password topicMetadataSyncOptions: autoCreateShadowTopicFilters: - name: '*' filterType: include patternType: literal ``` This example uses example values. Replace the resource names, broker addresses, and credentials with your actual configuration. With `staticConfiguration`, you must explicitly provide: - Bootstrap broker addresses - TLS configuration (if enabled) - SASL authentication credentials (only when SASL is enabled on the source cluster) - CA certificates for TLS verification (when TLS is enabled) 2. Apply the ShadowLink resource in the same namespace as your shadow cluster: ```bash kubectl apply --namespace -f shadowlink.yaml ``` ### Helm Create a shadow link using `rpk` commands. This is consistent with how topics, schemas, and users are managed in Helm-based deployments. 1. Create a YAML configuration file for your shadow link: ```yaml # shadow-config.yaml name: "disaster-recovery-link" client_options: bootstrap_servers: - "redpanda-source-0.redpanda-source.source.svc.cluster.local:9093" - "redpanda-source-1.redpanda-source.source.svc.cluster.local:9093" - "redpanda-source-2.redpanda-source.source.svc.cluster.local:9093" tls_settings: enabled: true tls_file_settings: ca_path: "/etc/tls/certs/default/ca.crt" authentication_configuration: scram_configuration: username: "replication-user" password: "" scram_mechanism: SCRAM-SHA-512 topic_metadata_sync_options: interval: "30s" auto_create_shadow_topic_filters: - pattern_type: "LITERAL" filter_type: "INCLUDE" name: "*" ``` This example uses example resource names and service addresses. Replace the bootstrap servers, username, and password with your actual source cluster configuration. Replace the `` placeholder with the actual password. When using TLS with self-signed certificates (the default with `tls.certs.default.caEnabled=true`), the `ca_path` must point to the source cluster’s CA certificate. Extract and copy it to the shadow cluster: ```bash # Extract source cluster's CA kubectl exec --namespace --container redpanda -- \ cat /etc/tls/certs/default/ca.crt > source-ca.crt # Copy to shadow cluster kubectl cp source-ca.crt /:/tmp/source-ca.crt # Reference in config: ca_path: "/tmp/source-ca.crt" ``` To generate a configuration template with the correct format, use: ```bash kubectl exec --namespace --container redpanda -- \ rpk shadow config generate > shadow-config.yaml ``` Then edit the generated file with your source cluster details before creating the shadow link. 2. Copy the configuration into a shadow cluster Pod and create the shadow link: ```bash # Copy configuration file into pod kubectl cp --namespace shadow-config.yaml :/tmp/shadow-config.yaml # Create shadow link kubectl exec --namespace --container redpanda -- \ rpk shadow create -c /tmp/shadow-config.yaml --no-confirm ``` For minimal configuration without TLS or authentication (testing only): ```yaml name: "test-link" client_options: bootstrap_servers: - "source-pod.source-namespace.svc.cluster.local:9092" topic_metadata_sync_options: interval: "30s" auto_create_shadow_topic_filters: - pattern_type: "LITERAL" filter_type: "INCLUDE" name: "*" ``` Limitations of the Helm approach: - Changes require manual `kubectl exec` commands. - Configuration exists as files copied into Pods. - Shadow link not visible to `kubectl get`. - No automatic reconciliation or recovery. - Cannot be managed by ArgoCD/Flux. - Must delete and recreate to modify configuration. For production deployments requiring declarative configuration and GitOps workflows, consider using the Redpanda Operator. ## [](#configure-topic-filters)Configure topic filters Topic filters determine which source topics are replicated to the shadow cluster. ### Operator Configure filters in the `ShadowLink` resource: ```yaml spec: topicMetadataSyncOptions: autoCreateShadowTopicFilters: # Include all topics by default - name: '*' filterType: include patternType: literal # Exclude temporary or test topics - name: temp- filterType: exclude patternType: prefixed - name: test- filterType: exclude patternType: prefixed # Include specific critical topics - name: orders filterType: include patternType: literal ``` Filter evaluation rules: - Filters are evaluated in order. - The first matching filter determines the result. - If no filters match, the topic is excluded. - The wildcard `*` matches all topics. Pattern types: - `literal`: Exact topic name match - `prefixed`: Matches topics starting with the specified name ### Helm Configure filters in your shadow link configuration file: ```yaml # shadow-config.yaml topic_metadata_sync_options: interval: "30s" auto_create_shadow_topic_filters: # Include all topics by default - pattern_type: "LITERAL" filter_type: "INCLUDE" name: "*" # Exclude temporary or test topics - pattern_type: "PREFIX" filter_type: "EXCLUDE" name: "temp-" - pattern_type: "PREFIX" filter_type: "EXCLUDE" name: "test-" # Include specific critical topics - pattern_type: "LITERAL" filter_type: "INCLUDE" name: "orders" ``` Filter evaluation rules: - Filters are evaluated in order. - The first matching filter determines the result. - If no filters match, the topic is excluded. - The wildcard `*` matches all topics. Pattern types: - `LITERAL`: Exact topic name match - `PREFIX`: Matches topics starting with the specified name Configure starting offset to control where new shadow topics begin replication: ### Operator ```yaml spec: topicMetadataSyncOptions: # Start from the earliest available offset (default) startAtEarliest: {} # Or start from the latest offset # startAtLatest: {} # Or start from a specific timestamp # startAtTimestamp: # timestamp: "2024-12-01T00:00:00Z" ``` ### Helm ```yaml # shadow-config.yaml topic_metadata_sync_options: # Start from the earliest available offset (default) start_at_earliest: {} # Or start from the latest offset # start_at_latest: {} # Or start from a specific timestamp # start_at_timestamp: # timestamp: "2024-12-01T00:00:00Z" ``` ## [](#configure-consumer-offset-synchronization)Configure consumer offset synchronization Enable consumer offset replication so consumers can resume from the same position after failover: ### Operator ```yaml spec: consumerOffsetSyncOptions: enabled: true interval: 30s groupFilters: - name: '*' filterType: include patternType: literal - name: debug-consumer filterType: exclude patternType: literal ``` ### Helm ```yaml # shadow-config.yaml consumer_offset_sync_options: enabled: true interval: "30s" group_filters: - pattern_type: "LITERAL" filter_type: "INCLUDE" name: "*" - pattern_type: "LITERAL" filter_type: "EXCLUDE" name: "debug-consumer" ``` ## [](#configure-acl-synchronization)Configure ACL synchronization Replicate access control lists to maintain security policies on the shadow cluster: ### Operator ```yaml spec: aclSyncOptions: enabled: true interval: 60s aclFilters: - resourceType: TOPIC resourcePatternType: LITERAL operation: ALL permissionType: ALLOW ``` ### Helm ```yaml # shadow-config.yaml security_sync_options: enabled: true interval: "60s" acl_filters: - resource_filter: resource_type: "TOPIC" pattern_type: "LITERAL" access_filter: operation: "ALL" permission_type: "ALLOW" ``` ## [](#verify-shadow-link)Verify shadow link #### Operator Check the status of your shadow link: ```bash kubectl get shadowlink --namespace -o yaml ``` The status section shows replication details: ```yaml status: conditions: - type: Ready status: "True" lastTransitionTime: "2024-12-10T10:00:00Z" reason: ReconciliationSucceeded message: Shadow link is active and replicating observedGeneration: 1 ``` Verify replication: ```bash # List topics on shadow cluster kubectl exec --namespace --container redpanda -- \ rpk topic list # Check shadow link status kubectl exec --namespace --container redpanda -- \ rpk shadow status ``` #### Helm List shadow links: ```bash kubectl exec --namespace --container redpanda -- \ rpk shadow list ``` Check shadow link status: ```bash kubectl exec --namespace --container redpanda -- \ rpk shadow status kubectl exec --namespace --container redpanda -- \ rpk shadow describe ``` List replicated topics: ```bash kubectl exec --namespace --container redpanda -- \ rpk topic list ``` ### [](#test-replication)Test replication Produce data to the source cluster and verify it appears on the shadow cluster: #### Operator ```bash # Produce to source cluster kubectl exec --namespace --container redpanda -- \ rpk topic produce --key # Consume from shadow cluster kubectl exec --namespace --container redpanda -- \ rpk topic consume ``` #### Helm ```bash # Produce to source cluster kubectl exec --namespace --container redpanda -- \ rpk topic produce --key # Consume from shadow cluster kubectl exec --namespace --container redpanda -- \ rpk topic consume ``` > 📝 **NOTE** > > Shadow topics are read-only. Attempting to produce or delete topics on the shadow cluster will fail while the shadow link is active. ## [](#update-a-shadow-link)Update a shadow link ### Operator Update the `ShadowLink` resource: ```bash kubectl edit shadowlink --namespace ``` Or apply an updated manifest: ```bash kubectl apply --namespace -f shadowlink-updated.yaml ``` The operator automatically reconciles the changes. Common updates include: - Adding or removing topic filters - Adjusting synchronization intervals - Enabling or disabling consumer offset/ACL sync - Updating authentication credentials ### Helm To update a shadow link configuration: ```bash # Delete existing shadow link kubectl exec --namespace --container redpanda -- \ rpk shadow delete # Copy updated configuration kubectl cp --namespace shadow-config-updated.yaml :/tmp/shadow-config.yaml # Recreate shadow link kubectl exec --namespace --container redpanda -- \ rpk shadow create -c /tmp/shadow-config.yaml ``` > ⚠️ **WARNING** > > Deleting and recreating a shadow link causes a brief interruption in replication. Plan updates during maintenance windows. ## [](#delete-a-shadow-link)Delete a shadow link ### Operator Delete the `ShadowLink` resource: ```bash kubectl delete shadowlink --namespace ``` ### Helm Delete the shadow link using `rpk`: ```bash kubectl exec --namespace --container redpanda -- \ rpk shadow delete ``` > ❗ **IMPORTANT** > > After deleting a shadow link: > > - Shadow topics remain on the cluster as regular topics. > > - The topics are no longer read-only and can be written to. > > - Replication from the source cluster stops immediately. > > - Consumer offset and ACL synchronization stops. > > > This is the first step in a disaster recovery failover scenario. ## [](#failover-procedure)Failover procedure In a disaster scenario, follow these steps to failover to the shadow cluster: ### Operator 1. **Delete the shadow link**: ```bash kubectl delete shadowlink --namespace ``` 2. **Verify topics are writable**: ```bash kubectl exec --namespace --container redpanda -- \ rpk topic produce --key test ``` 3. **Update client configurations** to point to the shadow cluster endpoints 4. **Verify consumer groups** can resume from their last committed offsets: ```bash kubectl exec --namespace --container redpanda -- \ rpk group describe ``` ### Helm 1. **Delete the shadow link**: ```bash kubectl exec --namespace --container redpanda -- \ rpk shadow delete ``` 2. **Verify topics are writable**: ```bash kubectl exec --namespace --container redpanda -- \ rpk topic produce --key test ``` 3. **Update client configurations** to point to the shadow cluster endpoints 4. **Verify consumer groups** can resume from their last committed offsets: ```bash kubectl exec --namespace --container redpanda -- \ rpk group describe ``` For detailed failover procedures and best practices, see [Failover](../../../disaster-recovery/shadowing/failover/). For emergency failover procedures, see [Kubernetes Failover Runbook](../k-failover-runbook/). ## [](#troubleshoot)Troubleshoot ### [](#shadowing-not-working)Shadowing not working #### Operator Check the operator logs: ```bash kubectl logs --namespace -l app.kubernetes.io/name=operator --tail=100 ``` Verify the operator has shadow link support enabled: ```bash kubectl get deployment --namespace -o yaml | grep enable-shadowlinks ``` Check the `ShadowLink` resource status: ```bash kubectl describe shadowlink --namespace ``` #### Helm Verify shadow linking is enabled on both clusters: ```bash kubectl exec --namespace --container redpanda -- \ rpk cluster config get enable_shadow_linking kubectl exec --namespace --container redpanda -- \ rpk cluster config get enable_shadow_linking ``` Check shadow link status for errors: ```bash kubectl exec --namespace --container redpanda -- \ rpk shadow describe ``` ### [](#connection-errors)Connection errors Verify network connectivity: ```bash # Test from shadow cluster pod kubectl exec --namespace --container redpanda -- \ rpk cluster info -X brokers=:9093 \ -X tls.enabled=true \ -X sasl.mechanism=SCRAM-SHA-512 \ -X user= \ -X pass= ``` Check that secrets exist and contain correct values: ```bash kubectl get secret --namespace kubectl get secret --namespace -o jsonpath='{.data.password}' | base64 -d ``` ### [](#replication-lag)Replication lag Monitor replication lag: ```bash kubectl exec --namespace --container redpanda -- \ rpk shadow status --detailed ``` High replication lag can be caused by: - Network bandwidth limitations between clusters - High write throughput on the source cluster - Resource constraints on the shadow cluster Consider adjusting: - Shadow cluster resources (CPU, memory) - Network bandwidth between regions - Replication batch sizes and intervals ### [](#authentication-failures)Authentication failures Verify SASL credentials: ```bash # Check if user exists on source cluster kubectl exec -it -n source redpanda-source-0 -c redpanda -- \ rpk acl user list ``` Ensure the replication user has required ACL permissions: ```bash kubectl exec -it -n source redpanda-source-0 -c redpanda -- \ rpk acl list --principal User:replication-user ``` ## [](#related-topics)Related topics - [Shadow Linking Overview](../../../disaster-recovery/shadowing/overview/) - [Configure Shadow Linking with rpk](../../../disaster-recovery/shadowing/setup/) - [Monitor Shadow Links](../../../disaster-recovery/shadowing/monitor/) - [Shadow Link Failover](../../../disaster-recovery/shadowing/failover/) - [Redpanda Operator Helm Configuration](../../../../reference/k-operator-helm-spec/) - [Manage Users with Kubernetes](../../security/authentication/k-user-controller/) --- # Page 197: Storage for Redpanda in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/storage.md --- # Storage for Redpanda in Kubernetes --- title: Storage for Redpanda in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/storage/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/storage/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/storage/index.adoc description: Find information about Redpanda storage in Kubernetes. page-git-created-date: "2023-09-27" page-git-modified-date: "2025-05-15" support-status: supported --- Find information about Redpanda storage in Kubernetes. - [Supported Volume Types for Data in Redpanda](k-volume-types/) Understand the three Kubernetes volume types supported by Redpanda, their lifecycles, use cases, storage locations, and their suitability for different Redpanda data requirements. - [Configure Storage for the Redpanda data directory in Kubernetes](k-configure-storage/) Configure Redpanda to store the data directory in PersistentVolumes, `hostPath` volumes, or `emptyDir` volumes. - [Expand PersistentVolumes](k-resize-persistentvolumes/) Learn how to expand the size of your PersistentVolumes to give Redpanda brokers more storage capacity. - [Delete PersistentVolumes in Kubernetes](k-delete-persistentvolume/) Learn how to delete a PersistentVolume (PV) before removing a broker and its data from the cluster or to perform maintenance or upgrades on the PersistentVolume. --- # Page 198: Configure Storage for the Redpanda data directory in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/storage/k-configure-storage.md --- # Configure Storage for the Redpanda data directory in Kubernetes --- title: Configure Storage for the Redpanda data directory in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/storage/k-configure-storage page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/storage/k-configure-storage.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/storage/k-configure-storage.adoc description: Configure Redpanda to store the data directory in PersistentVolumes, hostPath volumes, or emptyDir volumes. page-git-created-date: "2024-01-04" page-git-modified-date: "2024-02-26" support-status: supported --- Redpanda brokers must store their data directories on disk (`/var/lib/redpanda/data`). By default, the Redpanda Helm chart uses the default StorageClass in a Kubernetes cluster to create one PersistentVolumeClaim for each Pod that runs a Redpanda broker. The default StorageClass in your Kubernetes cluster depends on the Kubernetes platform that you are using. You can customize your deployment to use the following storage volumes. - [Store the Redpanda Data Directory in PersistentVolumes](../k-persistent-storage/) Learn how to configure Redpanda to store the data directory in Kubernetes PersistentVolumes with a static provisioner or a dynamic provisioner. - [Store the Redpanda Data Directory in hostPath Volumes](../k-hostpath/) Learn how to configure Redpanda to store the data directory in Kubernetes `hostPath` volumes. This setup is only for development environments. - [Store the Redpanda Data Directory in emptyDir Volumes](../k-emptydir/) Learn how to configure Redpanda to store the data directory in Kubernetes `emptyDir` volumes. This setup is only for development environments. --- # Page 199: Delete PersistentVolumes in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/storage/k-delete-persistentvolume.md --- # Delete PersistentVolumes in Kubernetes --- title: Delete PersistentVolumes in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/storage/k-delete-persistentvolume page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/storage/k-delete-persistentvolume.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/storage/k-delete-persistentvolume.adoc description: Learn how to delete a PersistentVolume (PV) before removing a broker and its data from the cluster or to perform maintenance or upgrades on the PersistentVolume. page-git-created-date: "2024-01-04" page-git-modified-date: "2024-02-26" support-status: supported --- Deleting a PersistentVolume (PV) can be necessary for a variety of reasons, such as removing a broker and its data from the cluster or performing maintenance or upgrades on the PersistentVolume. ## [](#prerequisites)Prerequisites - A running Redpanda deployment on a Kubernetes cluster. - PersistentVolumes for either the Redpanda data directory or the Tiered Storage cache. ## [](#delete-a-persistentvolume)Delete a PersistentVolume To delete a PersistentVolume, follow these steps to ensure that your data is moved to other brokers in the cluster. 1. Identify the PV that you want to delete: ```bash kubectl get persistentvolume ``` 2. [Decommission the broker](../../k-decommission-brokers/) that has a PersistentVolumeClaim (PVC) bound to the PV. Decommissioning helps prevent data loss by gracefully moving the broker’s topic partitions and replicas to other brokers in the cluster. 3. Delete the PVC that is bound to your PV: ```bash kubectl delete persistentvolumeclaim --namespace ``` > 📝 **NOTE** > > To prevent accidental loss of data, PersistentVolumesClaims are not deleted when Redpanda brokers are removed from a cluster. When you no longer need PersistentVolumeClaims, you must delete them manually. Check the [reclaim policy](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#reclaim-policy) of your PersistentVolumes before deleting a PersistentVolumeClaim. > > ```bash > kubectl get persistentvolume --namespace > ``` 4. If the `reclaimPolicy` of your PV is not `Delete`, delete the PV: ```bash kubectl delete persistentvolume ``` 5. Delete the Pod whose PVC was bound to the deleted PV: The StatefulSet schedules a new Pod on the same worker node and assigns it a unique node ID. If you use PVs for the Redpanda data directory, the Pod will have a new PVC bound to a PV that is set in [`storage.persistentVolume.storageClass`](../../../../reference/k-redpanda-helm-spec/#storagepersistentvolumestorageclass). See [Use PersistentVolumes](../k-configure-storage/). If you use PVs for the Tiered Storage cache, the Pod will have a new PVC bound to a PV that is set in [`storage.tieredStoragePersistentVolume.storageClass`](../../../../reference/k-redpanda-helm-spec/#storagetieredstoragepersistentvolumestorageclass). See [Tiered Storage Caching](../../tiered-storage/k-tiered-storage/#caching). 6. Verify that the new Redpanda broker is running and that it has access to the appropriate PersistentVolume. ```bash kubectl --namespace exec -ti -c -- \ rpk cluster info ``` You should see your new broker running with a new node ID. ## [](#suggested-reading)Suggested reading - [PersistentVolume documentation](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) - [StatefulSet documentation](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/) ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Owl Shop Example Application in Docker](/redpanda-labs/docker-compose/owl-shop/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) See more [Search all labs](/redpanda-labs) --- # Page 200: Store the Redpanda Data Directory in emptyDir Volumes **URL**: https://docs.redpanda.com/current/manage/kubernetes/storage/k-emptydir.md --- # Store the Redpanda Data Directory in emptyDir Volumes --- title: Store the Redpanda Data Directory in emptyDir Volumes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/storage/k-emptydir page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/storage/k-emptydir.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/storage/k-emptydir.adoc description: Learn how to configure Redpanda to store the data directory in Kubernetes emptyDir volumes. This setup is only for development environments. page-git-created-date: "2024-01-04" page-git-modified-date: "2025-04-07" support-status: supported --- You can configure Redpanda to use Kubernetes [`emptyDir`](../k-volume-types/) volumes to store the Redpanda data directory. > ⚠️ **WARNING** > > Use `emptyDir` volumes only for development environments. When a Pod is removed from a node for any reason, the data in the `emptyDir` volume is deleted permanently. ## [](#prerequisites)Prerequisites You must have the following: - Kubernetes cluster: Ensure you have a running Kubernetes cluster, either locally, such as with minikube or kind, or remotely. - [Kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl): Ensure you have the `kubectl` command-line tool installed and configured to communicate with your cluster. ## [](#configure-redpanda-to-use-emptydir-volumes)Configure Redpanda to use emptyDir volumes Both the Redpanda Helm chart and the Redpanda custom resource provide an interface for configuring `emptyDir` volumes. To store the Redpanda data directory in `emptyDir` volumes: ### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: storage: hostPath: "" persistentVolume: enabled: false ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ### Helm #### --values `emptydir.yaml` ```yaml storage: hostPath: "" persistentVolume: enabled: false ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values emptydir.yaml --reuse-values ``` #### --set ```bash helm upgrade --install redpanda redpanda/redpanda \ --namespace \ --create-namespace \ --set storage.hostPath="" \ --set storage.persistentVolume.enabled=false ``` - `storage.hostPath`: Absolute path on the host to store the Redpanda data directory. If unspecified, then an `emptyDir` volume is used. - `storage.persistentVolume.enabled`: Determine if a PersistentVolumeClaim (PVC) should be created for the Redpanda data directory. When set to `false`, a PVC is not created. ## [](#suggested-reading)Suggested reading - [Supported Volume Types for Data in Redpanda](../k-volume-types/) - For more details about `emptyDir` volumes, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/storage/volumes/#emptydir). - [Redpanda Helm Specification](../../../../reference/k-redpanda-helm-spec/) - [Redpanda CRD Reference](../../../../reference/k-crd/) ## [](#next-steps)Next steps [Monitor disk usage](../../monitoring/#infrastructure-resources) to detect issues early, optimize performance, and plan capacity. ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Owl Shop Example Application in Docker](/redpanda-labs/docker-compose/owl-shop/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) See more [Search all labs](/redpanda-labs) --- # Page 201: Store the Redpanda Data Directory in hostPath Volumes **URL**: https://docs.redpanda.com/current/manage/kubernetes/storage/k-hostpath.md --- # Store the Redpanda Data Directory in hostPath Volumes --- title: Store the Redpanda Data Directory in hostPath Volumes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/storage/k-hostpath page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/storage/k-hostpath.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/storage/k-hostpath.adoc description: Learn how to configure Redpanda to store the data directory in Kubernetes hostPath volumes. This setup is only for development environments. page-git-created-date: "2024-01-04" page-git-modified-date: "2025-04-07" support-status: supported --- You can configure Redpanda to use Kubernetes [`hostPath`](../k-volume-types/) volumes to store the Redpanda data directory. A `hostPath` volume mounts a file or directory from the host node’s file system into your Pod. > ⚠️ **WARNING** > > Use `hostPath` volumes only for development environments. If the Pod is deleted and recreated, it might be scheduled on another worker node and lose access to the data. ## [](#prerequisites)Prerequisites You must have the following: - Kubernetes cluster: Ensure you have a running Kubernetes cluster, either locally, such as with minikube or kind, or remotely. - [Kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl): Ensure you have the `kubectl` command-line tool installed and configured to communicate with your cluster. - Dedicated directory: Ensure you have a dedicated directory on the host worker node to prevent potential conflicts with other applications or system processes. - File system: Ensure that the chosen directory is on an ext4 or XFS file system. ## [](#configure-redpanda-to-use-hostpath-volumes)Configure Redpanda to use hostPath volumes Both the Redpanda Helm chart and the Redpanda custom resource provide an interface for configuring `hostPath` volumes. To store Redpanda data in `hostPath` volumes: ### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: storage: hostPath: "" persistentVolume: enabled: false initContainers: setDataDirOwnership: enabled: true ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ### Helm #### --values `hostpath.yaml` ```yaml storage: hostPath: "" persistentVolume: enabled: false initContainers: setDataDirOwnership: enabled: true ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values hostpath.yaml --reuse-values ``` #### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set storage.hostPath= \ --set storage.persistentVolume.enabled=false \ --set statefulset.initContainers.setDataDirOwnership.enabled=true ``` - `storage.hostPath`: Absolute path on the host to store the Redpanda data directory. - `storage.persistentVolume.enabled`: Determine if a PersistentVolumeClaim (PVC) should be created for the Redpanda data directory. When set to `false`, a PVC is not created. - `statefulset.initContainers.setDataDirOwnership.enabled`: Enable the init container to set write permissions on the data directories. Pods that run Redpanda brokers must have read/write access to their data directories. The initContainer is responsible for setting write permissions on the data directories. By default, `statefulset.initContainers.setDataDirOwnership` is disabled because most storage drivers call `SetVolumeOwnership` to give Redpanda permissions to the root of the storage mount. However, some storage drivers, such as `hostPath`, do not call `SetVolumeOwnership`. In this case, you must enable the initContainer to set the permissions. > ❗ **IMPORTANT** > > To set permissions on the data directories, the initContainer must run as root. However, be aware that an initContainer running as root can introduce the following security risks: > > - **Privilege escalation:** If attackers gains access to the initContainer, they can escalate privileges to gain full control over the system. For example, attackers could use the initContainer to gain unauthorized access to sensitive data, tamper with the system, or start denial-of-service attacks. > > - **Container breakouts:** If the container is misconfigured or the container runtime has a vulnerability, attackers could escape from the initContainer and access the host operating system. > > - **Image tampering:** If attackers gain access to the container image of the initContainer, they could add malicious code or backdoors to it. Image tampering could compromise the security of the entire cluster. ## [](#suggested-reading)Suggested reading - [Supported Volume Types for Data in Redpanda](../k-volume-types/) - For details about `hostPath` volumes, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/storage/volumes/#hostpath). - [Redpanda Helm Specification](../../../../reference/k-redpanda-helm-spec/) - [Redpanda CRD Reference](../../../../reference/k-crd/) ## [](#next-steps)Next steps [Monitor disk usage](../../monitoring/#infrastructure-resources) to detect issues early, optimize performance, and plan capacity. ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Owl Shop Example Application in Docker](/redpanda-labs/docker-compose/owl-shop/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) See more [Search all labs](/redpanda-labs) --- # Page 202: Store the Redpanda Data Directory in PersistentVolumes **URL**: https://docs.redpanda.com/current/manage/kubernetes/storage/k-persistent-storage.md --- # Store the Redpanda Data Directory in PersistentVolumes --- title: Store the Redpanda Data Directory in PersistentVolumes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/storage/k-persistent-storage page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/storage/k-persistent-storage.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/storage/k-persistent-storage.adoc description: Learn how to configure Redpanda to store the data directory in Kubernetes PersistentVolumes with a static provisioner or a dynamic provisioner. page-git-created-date: "2024-01-04" page-git-modified-date: "2025-04-07" support-status: supported --- You can configure Redpanda to use Kubernetes [PersistentVolumes](../k-volume-types/) (PV) to store the Redpanda data directory using either a static provisioner or a dynamic provisioner. ## [](#prerequisites)Prerequisites You must have the following: - Kubernetes cluster: Ensure you have a running Kubernetes cluster, either locally, such as with minikube or kind, or remotely. - [Kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl): Ensure you have the `kubectl` command-line tool installed and configured to communicate with your cluster. - Storage resources: You need to set up the necessary storage resources in your Kubernetes cluster. - File system: Ensure that the chosen volume is on an ext4 or XFS file system. ## [](#configure-rp)Configure Redpanda to use PersistentVolumes Both the Redpanda Helm chart and the Redpanda custom resource provide an interface for configuring persistent storage. These are the default settings: ### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: storage: persistentVolume: enabled: true size: 20Gi storageClass: "" labels: {} annotations: {} ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ### Helm #### --values `redpanda-persistent-storage.yaml` ```yaml storage: persistentVolume: enabled: true size: 20Gi storageClass: "" labels: {} annotations: {} ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values redpanda-persistent-storage.yaml --reuse-values ``` #### --set ```bash helm upgrade --install redpanda redpanda/redpanda \ --namespace \ --create-namespace \ --set storage.persistentVolume.enabled=true \ --set storage.persistentVolume.size=20Gi \ --set storage.persistentVolume.storageClass="" \ --set storage.persistentVolume.labels={} \ --set storage.persistentVolume.annotations={} ``` - `storage.persistentVolume.enabled`: Determines if a PersistentVolumeClaim (PVC) should be created for the Redpanda data directory. When set to `true`, a PVC is created. - `storage.persistentVolume.size`: The size of the PVC. By default, it’s set to `20Gi`, indicating a volume of 20 Gigabytes. Your underlying PV or StorageClass must support this size. - `storage.persistentVolume.storageClass`: Specifies the StorageClass name for the PVC. If set to `"-"`, dynamic provisioning is disabled. Leaving it undefined or empty uses the default dynamic provisioner. - `storage.persistentVolume.labels`: For adding additional labels to the created PVC. - `storage.persistentVolume.annotations`: For adding additional annotations to the created PVC. ## [](#verify-persistentvolumeclaims)Verify PersistentVolumeClaims After configuring Redpanda for persistent storage, verify that the Redpanda Pods have claimed the required PV. 1. Use the following command to list the PVCs in your cluster: ```bash kubectl get pvc --namespace ``` Ensure that the PVCs related to Redpanda are in the Bound state and note the PVs they’re bound to. 2. Choose a Pod and describe it: ```bash kubectl describe pod --namespace ``` In the output, ensure the PVC is mounted to the correct path and that the source PV matches what you’ve configured. ## [](#suggested-reading)Suggested reading - [Supported Volume Types for Data in Redpanda](../k-volume-types/) - For more details about PersistentVolumes, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/storage/persistent-volumes/). - [Redpanda Helm Specification](../../../../reference/k-redpanda-helm-spec/) - [Redpanda CRD Reference](../../../../reference/k-crd/) ## [](#next-steps)Next Steps - After setting up persistent storage for Redpanda, monitor your storage usage. Monitoring storage helps to detect issues early, optimize performance, and plan capacity changes. - [Monitor disk usage](../../monitoring/#infrastructure-resources) in Redpanda. - [Volume health monitoring](https://kubernetes.io/docs/concepts/storage/volume-health-monitoring/) in Kubernetes. - Enable [rack awareness](../../k-rack-awareness/) to minimize data loss in the event of a rack failure. ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Owl Shop Example Application in Docker](/redpanda-labs/docker-compose/owl-shop/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) See more [Search all labs](/redpanda-labs) --- # Page 203: Expand PersistentVolumes **URL**: https://docs.redpanda.com/current/manage/kubernetes/storage/k-resize-persistentvolumes.md --- # Expand PersistentVolumes --- title: Expand PersistentVolumes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/storage/k-resize-persistentvolumes page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/storage/k-resize-persistentvolumes.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/storage/k-resize-persistentvolumes.adoc description: Learn how to expand the size of your PersistentVolumes to give Redpanda brokers more storage capacity. page-git-created-date: "2024-01-04" page-git-modified-date: "2025-04-07" support-status: supported --- To give Redpanda brokers more storage, you can expand the size of PersistentVolumes (PVs). The way you expand PVs depends on the provisioner that you use. > ⚠️ **CAUTION** > > Some storage operations may cause temporary disruptions to your service or require the restart of associated Pods. Plan these operations during maintenance windows or times of low usage. ## [](#expand-persistentvolumes-that-use-static-provisioners)Expand PersistentVolumes that use static provisioners The process of resizing PVs that use a static provisioner varies depending on the way your file system is allocated. Follow the recommended process for your system. You do not need to make any configuration changes to the Redpanda Helm chart or your Redpanda custom resource. ## [](#expand-persistentvolumes-that-use-dynamic-provisioners)Expand PersistentVolumes that use dynamic provisioners To expand a PersistentVolume that uses a dynamic provisioner, you can reconfigure the Redpanda Helm chart to increase the size specification of your Pods' PersistentVolumeClaims (PVCs). Before making this change, make sure that your StorageClass is capable of volume expansions. For a list of volumes that support volume expansion, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#expanding-persistent-volumes-claims). > 📝 **NOTE** > > When you increase the size of a PVC connected to a StatefulSet, only new Pods recognize the changed PVC size. Existing Pods remain associated with the original PVC size. Manual intervention is necessary to modify the size of PVCs for existing Pods. Not all storage drivers recognize and act upon such modifications. Before making any changes, ensure your storage driver supports this operation. 1. Delete the StatefulSet associated with your Redpanda brokers using the `cascade=orphan` option. This action deletes the StatefulSet while leaving the Pods and their associated PVCs intact. ```bash kubectl --namespace delete statefulset --cascade=orphan ``` 2. Manually resize any pre-existing PVCs to your desired capacity by modifying the `spec.resources.requests.storage` field to the new size. 3. Redeploy the StatefulSet with the updated PVC size. For the Redpanda data directory: ### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: storage: persistentVolume: enabled: true size: Gi ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ### Helm #### --values `persistentvolume-size.yaml` ```yaml storage: persistentVolume: enabled: true size: Gi ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values persistentvolume-size.yaml --reuse-values ``` #### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set storage.persistentVolume.enabled=true \ --set storage.persistentVolume.size=Gi ``` For the Tiered Storage cache: ### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: storage: tieredStoragePersistentVolume: enabled: true size: Gi ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ### Helm #### --values `persistentvolume-size.yaml` ```yaml storage: tieredStoragePersistentVolume: enabled: true size: Gi ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values persistentvolume-size.yaml --reuse-values ``` #### --set ```bash helm upgrade --install redpanda redpanda/redpanda \ --namespace \ --create-namespace \ --set storage.tieredStoragePersistentVolume.enabled=true \ --set storage.tieredStoragePersistentVolume.size=Gi ``` ## [](#verify-persistentvolumeclaims)Verify PersistentVolumeClaims After redeploying the StatefulSet, verify that the Redpanda Pods have claimed the required PVs. 1. Use the following command to list the PVCs in your cluster: ```bash kubectl get pvc --namespace ``` Ensure that the PVCs related to Redpanda are in the Bound state and note the PVs to which they’re bound. 2. Choose a Pod and describe it: ```bash kubectl describe pod --namespace ``` In the output, ensure the PVC is mounted to the correct path and that the source PV matches what you’ve configured. ## [](#suggested-reading)Suggested reading [Expanding Persistent Volumes Claims](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#expanding-persistent-volumes-claims) ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Owl Shop Example Application in Docker](/redpanda-labs/docker-compose/owl-shop/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) See more [Search all labs](/redpanda-labs) --- # Page 204: Supported Volume Types for Data in Redpanda **URL**: https://docs.redpanda.com/current/manage/kubernetes/storage/k-volume-types.md --- # Supported Volume Types for Data in Redpanda --- title: Supported Volume Types for Data in Redpanda latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/storage/k-volume-types page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/storage/k-volume-types.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/storage/k-volume-types.adoc description: Understand the three Kubernetes volume types supported by Redpanda, their lifecycles, use cases, storage locations, and their suitability for different Redpanda data requirements. page-git-created-date: "2024-01-04" page-git-modified-date: "2024-02-26" support-status: supported --- Redpanda supports PersistentVolumes, `emptyDir` volumes, and `hostPath` volumes for storing the [Redpanda data directory](#redpanda-data) and the [Tiered Storage cache](#ts-cache) in Kubernetes. The volume type you choose directly impacts performance and data integrity. This topic explains the three Kubernetes volume types supported by Redpanda, their lifecycles, use cases, storage locations, and their suitability for different Redpanda data requirements. | Volume Type | Data Persistence | | --- | --- | | hostPath | Persists across Pod restarts but lost if the worker node fails. | | emptyDir | Lost if the Pod is deleted or evicted from a worker node. | | PersistentVolumes | Persists beyond the Pod’s lifecycle. | ## [](#data-in-redpanda-that-can-be-stored-in-separate-volumes)Data in Redpanda that can be stored in separate volumes Redpanda allows you to select separate volume types for the Redpanda data directory and the Tiered Storage cache. ### [](#redpanda-data)Redpanda data directory The Redpanda data directory contains essential data that each Redpanda broker requires to operate, including: - **ring0**: The Raft group that stores all Redpanda configurations. - **Partition segments**: If the particular broker participates in partition replication as either the leader or a follower, the data directory includes those partition segments. - **Crash loop tracker**: A file that logs recurrent Redpanda system crashes. The Redpanda data directory is always required. ### [](#ts-cache)Tiered storage cache The Tiered Storage cache contains older, less frequently accessed data segments in Tiered Storage. When a client fetches data not available locally, Redpanda retrieves these segments from object storage and puts them in the Tiered Storage cache to optimize subsequent data access requests. The Tiered Storage cache is required only when [Tiered Storage](../../tiered-storage/k-tiered-storage/) is enabled. ## [](#hostpath)hostPath With `hostPath` volumes, each Pod that runs a Redpanda broker stores data on the host worker node’s file system. This volume provides storage that lasts as long as the worker node is running. - **Lifecycle**: A `hostPath` volume mounts a file or directory from the host worker node’s file system into your Pod. - **Storage location**: Points to a specific location on the host worker node’s file system. - **Suitability for the Redpanda data directory**: Only for development environments where fast data access is important but data integrity is secondary. - **Suitability for Tiered Storage cache**: Suitable if the primary concern is latency. If the worker node fails, Redpanda must rebuild the cache, potentially leading to increased fetches from the primary storage. > ⚠️ **WARNING** > > If the worker node fails, the data in `hostPath` volumes is lost. ## [](#emptydir)emptyDir With `emptyDir` volumes, data is stored on the worker node’s local storage. This volume provides temporary storage that lasts only as long as the Pod is running. If a container within the Pod restarts, the data persists. > ⚠️ **WARNING** > > If the Pod is deleted or evicted from the worker node, the `emptyDir` volume is deleted, and data is lost. - **Lifecycle**: An `emptyDir` volume is tied to the lifecycle of the Pod that uses it. When the Pod is deleted, the `emptyDir` volume is also deleted and the data is permanently lost. - **Storage location**: The data in `emptyDir` volumes is stored on the worker node’s local storage where the Pod runs. - **Suitability for the Redpanda data directory**: Not recommended. Due to its transient nature, `emptyDir` volumes are unsuitable for the Redpanda data directory. - **Suitability for the Tiered Storage cache**: Suitable if the primary concern is latency and the cost to request data from primary storage is minimal. If the Pod restarts, Redpanda must rebuild the cache, potentially leading to increased fetches from the primary storage. ## [](#persistentvolumes)PersistentVolumes PersistentVolumes offer data retention beyond the Pod’s lifecycle. Pods access storage by creating a PersistentVolumeClaim (PVC). The PVC requests specific attributes and a size. Kubernetes then binds that PVC to a suitable PersistentVolume. - **Lifecycle**: PersistentVolumes are resources in the cluster that have a lifecycle independent of any individual Pod that uses the PersistentVolume. Data persists beyond the lifecycle of a Pod. - **Storage location**: PersistentVolumes can be backed by various storage systems including local storage on the worker node or cloud storage, such as AWS EBS, Azure Disk, and Google Persistent Disk. - **Suitability for the Redpanda data directory**: Recommended for safeguarding Redpanda topics and crucial data. - **Suitability for the Tiered Storage cache**: Strikes a balance between persistence and performance. Ensures cache data is preserved, reducing fetches from primary storage. > 💡 **TIP** > > Make regular backups of PersistentVolumes to reduce the risk of data loss in cases where the volume is lost. ### [](#local-and-remote-storage)Local and remote storage PersistentVolumes can be backed by local or remote storage. | PersistentVolume | Description | Best Use | | --- | --- | --- | | Local | Local PersistentVolumes store Redpanda data on a local disk that’s attached to the worker node. | High throughput and low latency. Redpanda reads and writes data faster on a local disk. | | Remote | Remote storage persists data outside of the worker node so that the data is not tied to a specific worker node and it can be recovered. | High availability. | > 💡 **TIP** > > For best performance, use local PersistentVolumes that are backed by NVMe disks with an XFS file system. ### [](#reclaim-policies)Reclaim policies PVCs are not deleted when Redpanda brokers are removed from a cluster. It is your responsibility to delete PVCs when they are no longer needed. As a result, it’s important to consider your volume’s reclaim policy: - **Delete**: The associated storage is removed once the PVC is deleted. - **Retain**: Even after the PVC is deleted, the actual storage persists. You can reclaim it with a new PVC. > 💡 **TIP** > > Redpanda Data recommends the `Retain` policy to ensure no accidental data loss. ### [](#persistent-volume-provisioners-in-kubernetes)Persistent Volume Provisioners in Kubernetes Kubernetes offers two methods to provision PersistentVolumes: static provisioning and dynamic provisioning. #### [](#static-provisioners)Static provisioners Static provisioners require manual intervention. An administrator pre-provisions a set of PersistentVolumes. These volumes are physical storage spaces within the cluster that are ready for use but aren’t bound to any specific PVCs yet. When a PVC is created, the Kubernetes control plane looks for a PersistentVolume that matches the requirements of the PVC and binds them together. When you use a static provisioner, You must create one PersistentVolume for each Redpanda broker. When the Redpanda Helm chart is deployed, an existing PersistentVolume in the cluster is selected and bound to one PVC for each Redpanda broker. #### [](#dynamic-provisioners)Dynamic provisioners Dynamic provisioners eliminate the manual step of creating PersistentVolumes. A dynamic provisioner creates a PersistentVolume on-demand for each PVC. Automatic provisioning is achieved using StorageClasses. A StorageClass provides a way for administrators to describe the classes of storage they offer. Each class can specify: - The type of provisioner to use - The type of storage backend - Other storage-specific parameters When the Redpanda Helm chart creates a PVC that specifies a StorageClass with a dynamic provisioner, Kubernetes automatically creates a new PersistentVolume that matches the requirements of the PVC. Managed Kubernetes services and cloud environments usually provide a dynamic provisioner. If you are not using a managed service, you may need to install a dynamic provisioner for your storage type. > 💡 **TIP** > > Create StorageClasses that use the [local volume manager (LVM) CSI driver](https://github.com/metal-stack/csi-driver-lvm) to automatically provision PVs. The LVM allows you to group physical storage devices into a logical volume group. Allocating logical volumes from a logical volume group provides greater flexibility in terms of storage expansion and management. The LVM supports features such as resizing, snapshots, and striping, which are not available with the other drivers, such as the local volume static provisioner. ## [](#differences-between-hostpath-volumes-and-local-persistentvolumes)Differences between hostPath volumes and local PersistentVolumes While both `hostPath` volumes and local PersistentVolumes allow for local storage on worker nodes, local PersistentVolumes are a more robust solution designed for production workloads. | | hostPath | Local PersistentVolume | | --- | --- | --- | | Persistence | Data is not guaranteed to persist across Pod rescheduling. Data exists as long as the worker node does. | The data is persistent across Pod restarts. Unavailable if the worker node fails. | | Scheduling Awareness | If the Pod is deleted and scheduled onto another worker node, it won’t have access to the original data. | Kubernetes ensures the Pod using the local PersistentVolume is scheduled on the correct worker node. | | Protection | Pods in different namespaces can overwrite or delete data if they specify the same path to the host. | Kubernetes protects against accidental data loss. PVCs bound to a local PersistentVolume are kept in a "Terminating" state if they are deleted while in use. | ## [](#data-safety-with-local-disks)Data safety with local disks Because Redpanda uses the Raft protocol to replicate data, it is safe to store the Redpanda data directory on local disks as long as your Redpanda cluster consists of the following: - At least three brokers (Pod replicas) - Topics configured with a replication factor of at least 3 This way, even if a worker node fails and you lose its local disk, the data still exists on at least two other worker nodes. ## [](#suggested-reading)Suggested reading - Kubernetes official documentation: - [PersistentVolumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) - [hostPath volumes](https://kubernetes.io/docs/concepts/storage/volumes/#hostpath) - [emptyDir volumes](https://kubernetes.io/docs/concepts/storage/volumes/#emptydir) - [Kubernetes Cluster Requirements and Recommendations](../../../../deploy/redpanda/kubernetes/k-requirements/) ## [](#next-steps)Next steps [Configure Storage for the Redpanda data directory in Kubernetes](../k-configure-storage/) ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Owl Shop Example Application in Docker](/redpanda-labs/docker-compose/owl-shop/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) See more [Search all labs](/redpanda-labs) --- # Page 205: Tiered Storage in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/tiered-storage.md --- # Tiered Storage in Kubernetes --- title: Tiered Storage in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/tiered-storage/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/tiered-storage/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/tiered-storage/index.adoc description: Tiered Storage helps to lower storage costs by offloading log segments to object storage. page-git-created-date: "2024-08-15" page-git-modified-date: "2025-05-15" support-status: supported --- With Tiered Storage, your cluster consists of two storage tiers, local and remote (using object storage with a cloud provider). Tiered Storage helps to lower storage costs by offloading log segments to object storage. Tiered Storage also provides simple data archiving that you can use for data recovery. Tiered Storage enables fast commission and decommission, remote read replicas, single topic recovery, and whole cluster restore, ensuring high availability of your Redpanda cluster. - [Use Tiered Storage in Kubernetes](k-tiered-storage/) Configure your Redpanda cluster to offload log segments to object storage and save storage costs. - [Fast Commission and Decommission Brokers in Kubernetes](k-fast-commission-decommission/) Configure fast partition movement during cluster resize for high availability. - [Remote Read Replicas in Kubernetes](k-remote-read-replicas/) Learn how to create a Remote Read Replica topic, which is a read-only topic that mirrors a topic on a different cluster. - [Topic Recovery in Kubernetes](k-topic-recovery/) Restore a single topic from object storage. - [Whole Cluster Restore in Kubernetes](k-whole-cluster-restore/) Restore a failed cluster, including its metadata. --- # Page 206: Fast Commission and Decommission Brokers in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/tiered-storage/k-fast-commission-decommission.md --- # Fast Commission and Decommission Brokers in Kubernetes --- title: Fast Commission and Decommission Brokers in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/tiered-storage/k-fast-commission-decommission page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/tiered-storage/k-fast-commission-decommission.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/tiered-storage/k-fast-commission-decommission.adoc description: Configure fast partition movement during cluster resize for high availability. page-git-created-date: "2024-08-15" page-git-modified-date: "2025-07-31" support-status: supported --- Tiered Storage gives you the option to boost the speed and reduce the impact of broker operations, particularly when resizing a cluster. For instance, adding a new broker to increase capacity for an overburdened cluster could introduce additional stress as partition replicas are transferred to the new broker. For cloud deployments, commissioning or decommissioning a broker can be a slow and expensive process, especially across multiple availability zones (AZs). Tiered Storage can help make the cluster resize process faster and more cost-efficient by leveraging data that has already been uploaded to object storage. Instead of transferring all data from local storage to the reassigned replicas, the replicas can instead be initialized to rely more heavily on Tiered Storage for read requests. To accomplish this, Redpanda takes an on-demand snapshot at an offset that is already uploaded to object storage. This is a later offset compared to the default log start offset managed by [Raft](https://raft.github.io/). When an empty replica is initialized, the later offset uploaded to object storage can be used as the start offset source. Reads that access data before the uploaded offset can be executed as remote reads. Therefore, the only data that needs to be sent over the network to replicas is the data locally retained after the uploaded offset. This also results in less time taken overall to grow or shrink the cluster. ## [](#configure-fast-commission-and-decommission)Configure fast commission and decommission To activate fast commission and decommission when brokers enter and leave the cluster: 1. Make sure to [configure topics for Tiered Storage](../k-tiered-storage/#enable-tiered-storage). 2. Configure at least one of the following cluster configuration properties. These properties limit the size of data replicated across brokers to local storage using Raft: - `initial_retention_local_target_bytes_default`: Initial local retention size target for partitions of topics with Tiered Storage enabled. The default is null. - Use the `initial.retention.local.target.bytes` topic configuration property to override on the topic level. - `initial_retention_local_target_ms_default`: Initial local retention time target for partitions of topics with Tiered Storage enabled. The default is null. - Use the `initial.retention.local.target.ms` topic configuration property to override on the topic level. If no values are set for the cluster configuration properties, all locally-retained data is delivered by default to the new broker (learner) when joining a partition replica set. > ❗ **IMPORTANT** > > Because topics become more reliant on object storage to serve data, you may experience higher latency reads for data beyond the range of the configured local [retention target](../k-tiered-storage/#set-retention-limits). Carefully weigh the tradeoffs between faster broker commission/decommission and the increased read latency due to less data being available in local storage. ## [](#monitor-fast-commission-and-decommission)Monitor fast commission and decommission Use the following to monitor fast commission and decommission: - The `vectorized_cluster_partition_start_offset` metric on newly-joined brokers should be greater than on existing brokers. - Raft protocol logs taking an on-demand snapshot are logged. For example: ```bash INFO 2025-03-12 09:32:23,280 [shard 13:raft] raft - [follower: {id: 39, revision: 19481451}, term: 34] [group_id:116908, {kafka/foo/999}] - recovery_stm.cc:473 - creating on demand snapshot with last included offset: 316791, current leader start offset: 203732. Total partition size on leader 46.109MiB, expected to transfer to learner: 683.000 bytes ``` - Depending on retention settings, disk usage on a newly-joined broker should generally be much lower than on existing brokers. ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) [Search all labs](/redpanda-labs) --- # Page 207: Recovery Mode in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/tiered-storage/k-recovery-mode.md --- # Recovery Mode in Kubernetes --- title: Recovery Mode in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/tiered-storage/k-recovery-mode page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/tiered-storage/k-recovery-mode.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/tiered-storage/k-recovery-mode.adoc description: Recovery mode starts Redpanda with limited functionality and disables partitions so you can repair a failed cluster. page-git-created-date: "2024-08-15" page-git-modified-date: "2025-07-31" support-status: supported --- Recovery mode allows you to repair and restore a failed cluster that cannot start normally due to issues such as system crashes or out-of-memory (OOM) errors. In recovery mode, Redpanda limits functionality to cluster configuration changes and other manual administrative actions so that you can repair the cluster. ## [](#enabled-functionality)Enabled functionality In recovery mode, Redpanda enables the following functionality so that you can repair the cluster: - Kafka API - Modify topic properties - Delete topics - Add and remove access control lists (ACLs) - Edit consumer group metadata - Admin API - Edit cluster configuration properties - Add and remove users - Add new brokers to the cluster - Delete WASM transforms ## [](#disabled-functionality)Disabled functionality In recovery mode, Redpanda disables the following functionality to provide a more stable environment for troubleshooting issues and restoring the cluster to a usable state. - The following APIs are disabled because some connections, especially malicious ones, can disrupt availability for all users, including admin users: - Kafka API (fetch and produce requests) - HTTP Proxy - Schema Registry - The following node-wide and cluster-wide processes are disabled as they may disrupt recovery operations: - Partition and leader balancers - Tiered Storage housekeeping - Tiered Storage cache management - Compaction - Redpanda does not load user-managed partitions on disk to prevent triggering partition leadership elections and replication that may occur on startup. ## [](#prerequisites)Prerequisites You must have the following: - A running Redpanda deployment on a Kubernetes cluster. - If you are using the Redpanda Helm chart, you need permission to upgrade the Helm release in the namespace where it’s deployed. - If you are using the Redpanda Operator, you need access to the Redpanda resource manifest. ## [](#start-redpanda-in-recovery-mode)Start Redpanda in recovery mode A broker can only enter recovery mode as it starts up, and not while it is already running. You first set the broker configuration property to enable recovery mode, and then do a broker restart. When you enable recovery mode in the Redpanda Helm chart or Redpanda resource, the Helm chart triggers a restart automatically. 1. Enable recovery mode: ### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: config: node: recovery_mode_enabled: true ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ### Helm #### --values `recovery-mode.yaml` ```yaml config: node: recovery_mode_enabled: true ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values recovery-mode.yaml --reuse-values ``` #### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set config.node.recovery_mode_enabled=true ``` 2. Check whether the cluster has entered recovery mode: ```bash kubectl --namespace exec -i -t -c redpanda -- \ rpk cluster health ``` You should see a list of brokers that are in recovery mode. For example: ```bash CLUSTER HEALTH OVERVIEW ======================= Healthy: true Unhealthy reasons: [] Controller ID: 0 All nodes: [0 1 2] Nodes down: [] Nodes in recovery mode: [0 1 2] Leaderless partitions (0): [] Under-replicated partitions (0): [] ``` In recovery mode, all private Redpanda topics such as `__consumer_offsets` are accessible. Data in user-created topics is not available, but you can still manage the metadata for these topics. ## [](#exit-recovery-mode)Exit recovery mode Exit recovery mode by disabling it on all brokers: ### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: config: node: recovery_mode_enabled: false ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ### Helm #### --values `recovery-mode.yaml` ```yaml config: node: recovery_mode_enabled: false ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values recovery-mode.yaml --reuse-values ``` #### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set config.node.recovery_mode_enabled=false ``` ## [](#disable-partitions)Disable partitions Problems that prevent normal cluster startup may be isolated to certain partitions or topics. You can use rpk or the [Admin API](/api/doc/admin/group/endpoint-partitions) to disable these partitions at the topic level, or individual partition level. A disabled partition or topic returns a `Replica Not Available` error code for Kafka API requests. To disable a partition, you need a healthy controller in the cluster, so you must start the cluster in recovery mode if a problematic partition is affecting cluster startup. If you disable a partition while in recovery mode, starting Redpanda again in non-recovery mode leaves the partition in a deactivated state. You must explicitly re-enable the partition. You can also disable a partition _outside_ of recovery mode, if the issue is localized to the partition and does not interfere with cluster startup. The following examples show you how to use the Admin API to enable or disable partitions. The examples are based on the assumption that the Admin API port is `9644`. For help connecting to the Admin API, see [Connect to Redpanda in Kubernetes](../../networking/k-connect-to-redpanda/). > 📝 **NOTE** > > Use `kafka` as the `partition-namespace` when making API calls to manage partitions in user topics. ### [](#disable-a-specific-partition-of-a-topic)Disable a specific partition of a topic #### rpk ```bash rpk cluster partitions disable --partitions ``` #### Curl ```bash curl -X POST -d '{"disabled": true}' http://localhost:9644/v1/cluster/partitions/// ``` ### [](#enable-a-specific-partition-of-a-topic)Enable a specific partition of a topic #### rpk ```bash rpk cluster partitions enable --partitions ``` #### Curl ```bash curl -X POST -d '{"disabled": false}' http://localhost:9644/v1/cluster/partitions/// ``` ### [](#disable-all-partitions-of-a-specific-topic)Disable all partitions of a specific topic #### rpk ```bash rpk cluster partitions disable --all ``` #### Curl ```bash curl -X POST -d '{"disabled": true}' http://localhost:9644/v1/cluster/partitions// ``` ### [](#enable-all-partitions-of-a-specific-topic)Enable all partitions of a specific topic #### rpk ```bash rpk cluster partitions enable --all ``` #### Curl ```bash curl -X POST -d '{"disabled": false}' http://localhost:9644/v1/cluster/partitions// ``` ### [](#list-all-disabled-partitions)List all disabled partitions #### rpk ```bash rpk cluster partitions list --all --disabled-only ``` #### Curl ```bash curl http://localhost:9644/v1/cluster/partitions?disabled=true ``` ### [](#list-all-disabled-partitions-of-a-specific-topic)List all disabled partitions of a specific topic #### rpk ```bash rpk cluster partitions list --disabled-only ``` #### Curl ```bash curl http://localhost:9644/v1/cluster/partitions//?disabled=true ``` ## [](#suggested-reading)Suggested reading - [Admin API reference](/api/doc/admin/) - [Perform a Rolling Restart](../../../cluster-maintenance/rolling-restart/) --- # Page 208: Remote Read Replicas in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/tiered-storage/k-remote-read-replicas.md --- # Remote Read Replicas in Kubernetes --- title: Remote Read Replicas in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/tiered-storage/k-remote-read-replicas page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/tiered-storage/k-remote-read-replicas.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/tiered-storage/k-remote-read-replicas.adoc description: Learn how to create a Remote Read Replica topic, which is a read-only topic that mirrors a topic on a different cluster. page-git-created-date: "2024-08-15" page-git-modified-date: "2025-07-31" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../../get-started/licensing/#self-managed) apply. A Remote Read Replica topic is a read-only topic that mirrors a topic on a different cluster. Remote Read Replicas work with both [Tiered Storage](../k-tiered-storage/) and [archival storage](../k-tiered-storage/#data-archiving). When a topic has object storage enabled, you can create a separate remote cluster just for consumers of this topic, and populate its topics from remote storage. A read-only topic on a remote cluster can serve any consumer, without increasing the load on the origin cluster. Use cases for Remote Read Replicas include data analytics, offline model training, and development clusters. You can create Remote Read Replica topics in a Redpanda cluster that directly accesses data stored in object storage. Because these read-only topics access data directly from object storage instead of the topics' origin cluster, there’s no impact to the performance of the cluster. Topic data can be consumed within a region of your choice, regardless of the region where it was produced. > ❗ **IMPORTANT** > > - The Remote Read Replica cluster must run on the same version of Redpanda as the origin cluster, or just one feature release ahead of the origin cluster. For example, if the origin cluster is version 24.1, the Remote Read Replica cluster can be 24.2, but not 24.3. It cannot skip feature releases. > > - When upgrading, upgrade the Remote Read Replica cluster before upgrading the origin cluster. For default values and documentation for configuration options, see the [`values.yaml`](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=storage.tiered.config) file. ## [](#prerequisites)Prerequisites You need the following: - An origin cluster with [Tiered Storage](../k-tiered-storage/#set-up-tiered-storage) set up. Multi-region buckets or containers are not supported. - A topic on the origin cluster, which you can use as a Remote Read Replica topic on the remote cluster. - A separate remote cluster. - AWS: The remote cluster can be in the same or a different region as the origin cluster’s S3 bucket. For cross-region Remote Read Replica topics, see [Create a cross-region Remote Read Replica topic on AWS](#create-cross-region-rrr-topic). - GCP: The remote cluster can be in the same or a different region as the bucket/container. - Azure: Remote read replicas are not supported. This feature requires an [enterprise license](../../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../../get-started/licensing/#self-managed) apply. To check if you already have a license key applied to your cluster: ```bash rpk cluster license info ``` ## [](#configure-object-storage-for-the-remote-cluster)Configure object storage for the remote cluster You must configure access to the same object storage as the origin cluster. #### Amazon S3 You can configure access to Amazon S3 with either an IAM role attached to the instance or with access keys. ### Use IAM roles To configure access to an S3 bucket with an IAM role: 1. Configure an [IAM role](../../../security/iam-roles/#configuring-iam-roles) with read permissions for the S3 bucket. 2. Override the following required cluster properties in the Helm chart: Replace the following placeholders: - ``: The region of your S3 bucket. ### Use access keys To configure access to an S3 bucket with access keys instead of an IAM role: 1. Grant a user the following permissions to read objects on the bucket to be used with the cluster (or on all buckets): - `GetObject` - `ListBucket` 2. Create a Secret in which to store the access key and secret key. ```yaml apiVersion: v1 kind: Secret metadata: name: storage-secrets namespace: type: Opaque data: access-key: secret-key: ``` - Replace `` with your base64-encoded access key. - Replace `` with your base64-encoded secret key. 3. Override the following required cluster properties in the Helm chart: Replace `` with the region of your S3 bucket. ##### --values `cloud-storage.yaml` ```yaml storage: tiered: config: cloud_storage_enabled: true cloud_storage_credentials_source: aws_instance_metadata cloud_storage_region: cloud_storage_bucket: "none" ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values cloud-storage.yaml ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set storage.tiered.config.cloud_storage_enabled=true \ --set storage.tiered.config.cloud_storage_credentials_source=aws_instance_metadata \ --set storage.tiered.config.cloud_storage_region= \ --set storage.tiered.config.cloud_storage_bucket="none" ``` ##### --values `cloud-storage.yaml` ```yaml storage: tiered: credentialsSecretRef: accessKey: name: storage-secrets key: access-key secretKey: name: storage-secrets key: secret-key config: cloud_storage_enabled: true cloud_storage_credentials_source: config_file cloud_storage_region: cloud_storage_bucket: "none" ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values cloud-storage.yaml ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set storage.tiered.config.cloud_storage_enabled=true \ --set storage.tiered.credentialsSecretRef.accessKey.name=storage-secrets \ --set storage.tiered.credentialsSecretRef.accessKey.key=access-key \ --set storage.tiered.credentialsSecretRef.secretKey.name=storage-secrets \ --set storage.tiered.credentialsSecretRef.secretKey.key=secret-key \ --set storage.tiered.config.cloud_storage_credentials_source=config_file \ --set storage.tiered.config.cloud_storage_region= \ --set storage.tiered.config.cloud_storage_bucket="none" ``` #### Google Cloud Storage You can configure access to Google Cloud Storage with either an IAM role attached to the instance or with access keys. ### Use IAM roles To configure access to Google Cloud Storage with an IAM role, override the following required cluster properties in the Helm chart: Replace `` with the region of your bucket. ### Use access keys To configure access to Google Cloud Storage with access keys instead of an IAM role: 1. Create a Secret in which to store the access key and secret key. ```yaml apiVersion: v1 kind: Secret metadata: name: storage-secrets namespace: type: Opaque data: access-key: secret-key: ``` - Replace `` with your base64-encoded access key. - Replace `` with your base64-encoded secret key. 2. Override the following required cluster properties in the Helm chart: Replace `` with the region of your bucket. ##### --values `cloud-storage.yaml` ```yaml storage: tiered: config: cloud_storage_enabled: true cloud_storage_credentials_source: gcp_instance_metadata cloud_storage_region: cloud_storage_bucket: "none" ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values cloud-storage.yaml ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set storage.tiered.config.cloud_storage_enabled=true \ --set storage.tiered.config.cloud_storage_credentials_source=aws_instance_metadata \ --set storage.tiered.config.cloud_storage_region= \ --set storage.tiered.config.cloud_storage_bucket="none" ``` ##### --values `cloud-storage.yaml` ```yaml storage: tiered: credentialsSecretRef: accessKey: name: storage-secrets key: access-key secretKey: name: storage-secrets key: secret-key config: cloud_storage_enabled: true cloud_storage_credentials_source: config_file cloud_storage_api_endpoint: storage.googleapis.com cloud_storage_region: cloud_storage_bucket: "none" ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values cloud-storage.yaml ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set storage.tiered.config.cloud_storage_enabled=true \ --set storage.tiered.credentialsSecretRef.accessKey.name=storage-secrets \ --set storage.tiered.credentialsSecretRef.accessKey.key=access-key \ --set storage.tiered.credentialsSecretRef.secretKey.name=storage-secrets \ --set storage.tiered.credentialsSecretRef.secretKey.key=secret-key \ --set storage.tiered.config.cloud_storage_credentials_source=config_file \ --set storage.tiered.config.cloud_storage_api_endpoint=storage.googleapis.com \ --set storage.tiered.config.cloud_storage_region= \ --set storage.tiered.config.cloud_storage_bucket="none" ``` #### Azure Blob Storage To configure access to Azure Blob Storage(ABS): 1. Create a Secret in which to store the access key. ```yaml apiVersion: v1 kind: Secret metadata: name: storage-secrets namespace: type: Opaque data: access-key: ``` - Replace `` with your base64-encoded access key. 2. Override the following required cluster properties in the Helm chart: Replace `` with the name of your Azure account. ##### --values `cloud-storage.yaml` ```yaml storage: tiered: credentialsSecretRef: secretKey: configurationKey: cloud_storage_azure_shared_key name: storage-secrets key: access-key config: cloud_storage_enabled: true cloud_storage_azure_storage_account: cloud_storage_azure_container: "none" ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values cloud-storage.yaml ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set storage.tiered.config.cloud_storage_enabled=true \ --set storage.tiered.credentialsSecretRef.secretKey.configurationKey=cloud_storage_azure_shared_key \ --set storage.tiered.credentialsSecretRef.secretKey.name=storage-secrets \ --set storage.tiered.credentialsSecretRef.secretKey.key=access-key \ --set storage.tiered.config.cloud_storage_azure_storage_account= \ --set storage.tiered.config.cloud_storage_azure_container="none" ``` ## [](#create-a-remote-read-replica-topic)Create a Remote Read Replica topic To create the Remote Read Replica topic, run: ```bash rpk topic create -c redpanda.remote.readreplica= ``` - For ``, use the same name as the original topic. - For ``, use the bucket/container specified in the `cloud_storage_bucket` or `cloud_storage_azure_container` properties for the origin cluster. > 📝 **NOTE** > > - The Remote Read Replica cluster must run on the same version of Redpanda as the origin cluster, or just one feature release ahead of the origin cluster. For example, if the origin cluster is version 23.1, the Remote Read Replica cluster can be 23.2, but not 23.4. It cannot skip feature releases. > > - During upgrades, upgrade the Remote Read Replica cluster before upgrading the origin cluster. > > - Do not use `redpanda.remote.read` or `redpanda.remote.write` with `redpanda.remote.readreplica`. Redpanda ignores the values for remote read and remote write properties on read replica topics. ### [](#create-cross-region-rrr-topic)Create a cross-region Remote Read Replica topic on AWS Use this configuration only when the remote cluster is in a **different AWS region** than the origin cluster’s S3 bucket. For same-region AWS or GCP deployments, use the standard [topic creation command](#create-a-remote-read-replica-topic). #### [](#prerequisites-2)Prerequisites You must explicitly set the [`cloud_storage_url_style`](../../../../reference/properties/object-storage-properties/#cloud_storage_url_style) cluster property to `virtual_host` or `path` on the remote cluster. The default value does not support cross-region Remote Read Replicas. #### [](#create-the-topic)Create the topic To create a cross-region Remote Read Replica topic, append `region` and `endpoint` query-string parameters to the bucket name. In the following example, replace the placeholders: - ``: The name of the topic in the cluster hosting the Remote Read Replica. - ``: The S3 bucket configured on the origin cluster (`cloud_storage_bucket`). - ``: The AWS region of the origin cluster’s S3 bucket (not the remote cluster’s region). ```bash rpk topic create \ -c redpanda.remote.readreplica=?region=&endpoint=s3..amazonaws.com ``` For example, if the origin cluster stores data in a bucket called `my-bucket` in `us-east-1`: ```bash rpk topic create my-topic \ -c redpanda.remote.readreplica=my-bucket?region=us-east-1&endpoint=s3.us-east-1.amazonaws.com ``` > 📝 **NOTE** > > The `endpoint` value must not include the bucket name. When using `virtual_host` URL style, Redpanda automatically prepends the bucket name to the endpoint. When using `path` URL style, Redpanda appends the bucket name as a path segment. #### [](#limits)Limits Each unique combination of region and endpoint creates a separate object storage target on the remote cluster. A cluster supports a maximum of 10 targets. How targets are counted depends on `cloud_storage_url_style`: - `virtual_host`: Each unique combination of bucket, region, and endpoint counts as one target. You can create up to 10 distinct cross-region Remote Read Replica topics for each cluster. - `path`: Each unique combination of region and endpoint counts as one target (the bucket name is not part of the key). You can create cross-region Remote Read Replica topics for multiple buckets using the same region/endpoint combination, with a maximum of 10 distinct region/endpoint combinations for each cluster. ## [](#reduce-lag-in-data-availability)Reduce lag in data availability When object storage is enabled on a topic, Redpanda copies closed log segments to the configured object store. Log segments are closed when the value of the segment size has been reached. A topic’s object store thus lags behind the local copy by the [`log_segment_size`](../../../../reference/properties/cluster-properties/#log_segment_size) or, if set, by the topic’s `segment.bytes` value. To reduce this lag in the data availability for the Remote Read Replica: - You can lower the value of `segment.bytes`. This lets Redpanda archive smaller log segments more frequently, at the cost of increasing I/O and file count. - Redpanda Self-Managed deployments can set an idle timeout with `[storage.tiered.config.cloud_storage_segment_max_upload_interval_sec](../../../../reference/properties/object-storage-properties/#cloud_storage_segment_max_upload_interval_sec)` to force Redpanda to periodically archive the contents of open log segments to object storage. This is useful if a topic’s write rate is low and log segments are kept open for long periods of time. The appropriate interval may depend on your total partition count: a system with less partitions can handle a higher number of segments per partition. ## [](#suggested-reading)Suggested reading [Remote Read Replicas: Read-only topics in Tiered Storage](https://redpanda.com/blog/remote-read-replicas-for-distributing-work) ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) [Search all labs](/redpanda-labs) --- # Page 209: Use Tiered Storage in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/tiered-storage/k-tiered-storage.md --- # Use Tiered Storage in Kubernetes --- title: Use Tiered Storage in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/tiered-storage/k-tiered-storage page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/tiered-storage/k-tiered-storage.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/tiered-storage/k-tiered-storage.adoc description: Configure your Redpanda cluster to offload log segments to object storage and save storage costs. page-git-created-date: "2024-08-15" page-git-modified-date: "2024-12-03" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../../get-started/licensing/#self-managed) apply. Tiered Storage helps to lower storage costs by offloading log segments to object storage. You can specify the amount of storage you want to retain in local storage. You don’t need to specify which log segments you want to move, because Redpanda moves them automatically based on cluster-level configuration properties. Tiered Storage indexes where data is offloaded, so it can look up the data when you need it. The following image illustrates the Tiered Storage architecture: remote write uploads data from Redpanda to object storage, and remote read fetches data from object storage to Redpanda. ![Tiered Storage architecture](../../../../shared/_images/tiered_storage1.png) ## [](#prerequisites)Prerequisites This feature requires an [enterprise license](../../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../../get-started/licensing/#self-managed) apply. To check if you already have a license key applied to your cluster: ```bash rpk cluster license info ``` ## [](#limitations)Limitations - Migrating topics from one object storage provider to another is not supported. - Migrating topics from one bucket or container to another is not supported. - Multi-region buckets or containers are not supported. > ⚠️ **CAUTION** > > Redpanda Data recommends that you do not re-enable Tiered Storage after previously enabling and disabling it. Re-enabling Tiered Storage can result in inconsistent data and data gaps in Tiered Storage for a topic. ## [](#set-up-tiered-storage)Set up Tiered Storage To set up Tiered Storage: 1. [Configure object storage](#configure-object-storage). 2. [Enable Tiered Storage](#enable-tiered-storage). You can enable Tiered Storage for the cluster (all topics) or for specific topics. 3. [Set retention limits](#set-retention-limits). ### [](#configure-object-storage)Configure object storage Redpanda natively supports Tiered Storage with Amazon Simple Storage Service (S3), Google Cloud Storage (GCS, which uses the Google Cloud Platform S3 API), and Microsoft Azure Blob Storage (ABS) and Azure Data Lake Storage (ADLS). #### [](#amazon-s3)Amazon S3 > 📝 **NOTE** > > If you deploy Redpanda directly on AWS EC2 instances managed by an Auto-Scaling Group (ASG), be aware that ASG may terminate and replace instances based on system-level health checks. This can result in unexpected Redpanda broker terminations, risking availability or data loss. > > Redpanda Data recommends deploying on Kubernetes or using other orchestrators that understand Redpanda’s stateful nature and can handle Pod lifecycle and storage gracefully. > > See [Deploy Redpanda](../../../../deploy/redpanda/) for deployment best practices. You can configure access to Amazon S3 with either an IAM role attached to the instance or with access keys. If you need to manage and store encryption keys separately from your cloud provider, you can [configure access to an AWS S3 bucket that Redpanda Tiered Storage uses to leverage your AWS KMS key (SSE-KMS)](#configure-access-with-an-aws-kms-key) instead of the default AWS S3-managed key (SSE-S3). This option enables you to segregate data from different teams or departments and remove that data at will by removing the encryption keys. ##### [](#configure-access-with-an-iam-role)**Configure access with an IAM role** 1. Configure an [IAM role](../../../security/iam-roles/#configuring-iam-roles). 2. Override the following required cluster properties in the Helm chart: ###### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: storage: tiered: config: cloud_storage_enabled: "true" cloud_storage_credentials_source: aws_instance_metadata cloud_storage_region: cloud_storage_bucket: ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ###### Helm ###### --values `cloud-storage.yaml` ```yaml storage: tiered: config: cloud_storage_enabled: true cloud_storage_credentials_source: aws_instance_metadata cloud_storage_region: cloud_storage_bucket: ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values cloud-storage.yaml ``` ###### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set storage.tiered.config.cloud_storage_enabled=true \ --set storage.tiered.config.cloud_storage_credentials_source=aws_instance_metadata \ --set storage.tiered.config.cloud_storage_region= \ --set storage.tiered.config.cloud_storage_bucket= ``` Replace the following placeholders: - ``: The region of your S3 bucket. - ``: The name of your S3 bucket. > ⚠️ **CAUTION** > > Do not set an object storage property to an empty string (`""`) or `null` to reset it. This may result in invalid or incomplete configuration. For safe ways to reset a property, see [Reset configuration values](../../k-configure-helm-chart/#reset-config). > 💡 **TIP** > > Starting in Redpanda Operator v25.1.1, you can configure object storage settings using `config.extraClusterConfiguration`. This lets you securely reference sensitive values from Kubernetes Secrets or ConfigMaps, and reuse values like your bucket name across multiple features, such as Tiered Storage, Iceberg, and topic recovery. > > See [Set Redpanda cluster properties from Kubernetes Secrets or ConfigMaps](../../k-configure-helm-chart/#extra-cluster-config). ##### [](#configure-access-with-access-keys)**Configure access with access keys** 1. In AWS, grant an IAM user the following permissions to read and create objects in your buckets: - `GetObject` - `DeleteObject` - `PutObject` - `PutObjectTagging` - `ListBucket` 2. Make a note of the access key and secret key. 3. Create a Secret in which to store the access key and secret key. ```yaml apiVersion: v1 kind: Secret metadata: name: storage-secrets namespace: type: Opaque data: access-key: secret-key: ``` - Replace `` with your base64-encoded access key. - Replace `` with your base64-encoded secret key. 4. Override the following required cluster properties: ###### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: storage: tiered: credentialsSecretRef: accessKey: name: storage-secrets key: access-key secretKey: name: storage-secrets key: secret-key config: cloud_storage_enabled: "true" cloud_storage_credentials_source: config_file cloud_storage_region: cloud_storage_bucket: ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ###### Helm ###### --values `cloud-storage.yaml` ```yaml storage: tiered: credentialsSecretRef: accessKey: name: storage-secrets key: access-key secretKey: name: storage-secrets key: secret-key config: cloud_storage_enabled: true cloud_storage_credentials_source: config_file cloud_storage_region: cloud_storage_bucket: ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values cloud-storage.yaml ``` ###### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set storage.tiered.config.cloud_storage_enabled=true \ --set storage.tiered.credentialsSecretRef.accessKey.name=storage-secrets \ --set storage.tiered.credentialsSecretRef.accessKey.key=access-key \ --set storage.tiered.credentialsSecretRef.secretKey.name=storage-secrets \ --set storage.tiered.credentialsSecretRef.secretKey.key=secret-key \ --set storage.tiered.config.cloud_storage_credentials_source=config_file \ --set storage.tiered.config.cloud_storage_region= \ --set storage.tiered.config.cloud_storage_bucket= ``` Replace the following placeholders: - ``: The region of your S3 bucket. - ``: The name of your S3 bucket. > ⚠️ **CAUTION** > > Do not set an object storage property to an empty string (`""`) or `null` to reset it. This may result in invalid or incomplete configuration. For safe ways to reset a property, see [Reset configuration values](../../k-configure-helm-chart/#reset-config). > 💡 **TIP** > > Starting in Redpanda Operator v25.1.1, you can configure object storage settings using `config.extraClusterConfiguration`. This lets you securely reference sensitive values from Kubernetes Secrets or ConfigMaps, and reuse values like your bucket name across multiple features, such as Tiered Storage, Iceberg, and topic recovery. > > See [Set Redpanda cluster properties from Kubernetes Secrets or ConfigMaps](../../k-configure-helm-chart/#extra-cluster-config). ##### [](#configure-access-with-an-aws-kms-key)**Configure access with an AWS KMS key** When there are strict data compliance requirements and you must manage and store encryption keys separate from your cloud provider, you can configure an Amazon S3 bucket that Tiered Storage can use to leverage your customer-provided key (SSE-KMS) instead of the default AWS-managed key (SSE-S3). To convert an existing S3 bucket and its contents, you must: 1. Create a new KMS key. 2. Configure the S3 bucket to use the new KMS key. 3. (Optional) Re-encrypt existing objects to use the new KMS key. > 📝 **NOTE** > > You cannot configure a cloud provider-managed encryption key at the topic level. > > For topic-level control, each CLI Get or Put for a partition must use the correct key as configured on the topic. ###### [](#prerequisites-2)**Prerequisites** - The user configuring S3 bucket encryption must be assigned the Key admin permission. Without this permission, the user is unable to re-encrypt existing bucket objects to use the KMS key. - The S3 bucket must be assigned the Key user permission. Without this permission, Redpanda is unable to write new objects to Tiered Storage. - If you intend to retroactively re-encrypt existing data with the new KMS key, store the ARN identifier of the key upon creation. It is required for AWS CLI commands. To create a new KMS key in the AWS Console: 1. In AWS Console, search for “Key Management Service”. 2. Click **Create a key**. 3. On the Configure key page, select the **Symmetric** key type, then select **Encrypt and decrypt**. 4. Click the **Advanced options** tab and configure Key material origin and Regionality as needed. For example, if you are using [Remote Read Replicas](../../../remote-read-replicas/) or have Redpanda spanning across regions, select **Multi-Region key**. 5. Click **Next**. 6. On the Add labels page, specify an alias name and description for the key. Do not include sensitive information in these fields. 7. Click **Next**. 8. On the Define key administrative permissions page, specify a user who can administer this key through the KMS API. 9. Click **Next**. 10. On the Define key usage permissions page, assign the S3 bucket as a Key user. This is required for the S3 bucket to encrypt and decrypt. 11. Click **Next**. 12. Review your KMS key configuration and click **Finish**. For more information, see the [AWS documentation](https://docs.aws.amazon.com/kms/latest/developerguide/create-symmetric-cmk.html). To configure the S3 bucket to use the new KMS key (and reduce KMS costs through caching): 1. In AWS Console, search for "S3". 2. Select the bucket used by Redpanda. 3. Click the **Properties** tab. 4. In Default encryption, click **Edit**. 5. For Encryption type, select “Server-side encryption with AWS Key Management Service keys (SSE-KMS)”. 6. Locate and select your AWS KMS key ARN identifier. 7. Click **Save changes**. (Optional) To re-encrypt existing data using the new KMS key: Existing data in your S3 bucket continues to be read using the AWS-managed key, while new objects are encrypted using the new KMS key. If you wish to re-encrypt all S3 bucket data to use the KMS key, run: ```bash aws s3 cp s3://{BUCKET_NAME}/ s3://{BUCKET_NAME}/ --recursive --sse-kms-key-id {KMS_KEY_ARN} --sse aws:kms ``` For more information, see the [AWS documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/configuring-bucket-key.html). #### [](#google-cloud-storage)Google Cloud Storage Configure access to Google Cloud Storage with either an IAM role attached to the instance, with access keys, or with customer-managed keys. ##### [](#configure-access-with-an-iam-role-2)**Configure access with an IAM role** 1. Configure an [IAM role](../../../security/iam-roles/#configuring-iam-roles). 2. Override the following required cluster properties in the Helm chart: ###### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: storage: tiered: config: cloud_storage_enabled: "true" cloud_storage_api_endpoint: storage.googleapis.com cloud_storage_credentials_source: gcp_instance_metadata cloud_storage_region: cloud_storage_bucket: ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ###### Helm ###### --values `cloud-storage.yaml` ```yaml storage: tiered: config: cloud_storage_enabled: true cloud_storage_api_endpoint: storage.googleapis.com cloud_storage_credentials_source: gcp_instance_metadata cloud_storage_region: cloud_storage_bucket: ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values cloud-storage.yaml ``` ###### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set storage.tiered.config.cloud_storage_enabled=true \ --set storage.tiered.config.cloud_storage_api_endpoint=storage.googleapis.com \ --set storage.tiered.config.cloud_storage_credentials_source=aws_instance_metadata \ --set storage.tiered.config.cloud_storage_region= \ --set storage.tiered.config.cloud_storage_bucket= ``` Replace the following placeholders: - ``: The region of your bucket. - ``: The name of your bucket. > ⚠️ **CAUTION** > > Do not set an object storage property to an empty string (`""`) or `null` to reset it. This may result in invalid or incomplete configuration. For safe ways to reset a property, see [Reset configuration values](../../k-configure-helm-chart/#reset-config). > 💡 **TIP** > > Starting in Redpanda Operator v25.1.1, you can configure object storage settings using `config.extraClusterConfiguration`. This lets you securely reference sensitive values from Kubernetes Secrets or ConfigMaps, and reuse values like your bucket name across multiple features, such as Tiered Storage, Iceberg, and topic recovery. > > See [Set Redpanda cluster properties from Kubernetes Secrets or ConfigMaps](../../k-configure-helm-chart/#extra-cluster-config). ##### [](#configure-access-with-access-keys-2)**Configure access with access keys** To configure access to Google Cloud Storage with access keys instead of an IAM role: 1. Choose a uniform access control when you create the bucket. 2. Use a Google-managed encryption key. 3. Set a [default project](https://cloud.google.com/storage/docs/migrating#defaultproj). 4. Create a service user with [HMAC keys](https://cloud.google.com/storage/docs/authentication/managing-hmackeys) and make a note of the access key and secret key. 5. Create a Secret in which to store the access key and secret key. ```yaml apiVersion: v1 kind: Secret metadata: name: storage-secrets namespace: type: Opaque data: access-key: secret-key: ``` - Replace `` with your base64-encoded access key. - Replace `` with your base64-encoded secret key. 6. Override the following required cluster properties in the Helm chart: ###### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: storage: tiered: credentialsSecretRef: accessKey: name: storage-secrets key: access-key secretKey: name: storage-secrets key: secret-key config: cloud_storage_enabled: "true" cloud_storage_credentials_source: config_file cloud_storage_api_endpoint: storage.googleapis.com cloud_storage_region: cloud_storage_bucket: ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ###### Helm ###### --values `cloud-storage.yaml` ```yaml storage: tiered: credentialsSecretRef: accessKey: name: storage-secrets key: access-key secretKey: name: storage-secrets key: secret-key config: cloud_storage_enabled: true cloud_storage_credentials_source: config_file cloud_storage_api_endpoint: storage.googleapis.com cloud_storage_region: cloud_storage_bucket: ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values cloud-storage.yaml ``` ###### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set storage.tiered.config.cloud_storage_enabled=true \ --set storage.tiered.credentialsSecretRef.accessKey.name=storage-secrets \ --set storage.tiered.credentialsSecretRef.accessKey.key=access-key \ --set storage.tiered.credentialsSecretRef.secretKey.name=storage-secrets \ --set storage.tiered.credentialsSecretRef.secretKey.key=secret-key \ --set storage.tiered.config.cloud_storage_credentials_source=config_file \ --set storage.tiered.config.cloud_storage_api_endpoint=storage.googleapis.com \ --set storage.tiered.config.cloud_storage_region= \ --set storage.tiered.config.cloud_storage_bucket= ``` Replace the following placeholders: - ``: The region of your bucket. - ``: The name of your bucket. > ⚠️ **CAUTION** > > Do not set an object storage property to an empty string (`""`) or `null` to reset it. This may result in invalid or incomplete configuration. For safe ways to reset a property, see [Reset configuration values](../../k-configure-helm-chart/#reset-config). > 💡 **TIP** > > Starting in Redpanda Operator v25.1.1, you can configure object storage settings using `config.extraClusterConfiguration`. This lets you securely reference sensitive values from Kubernetes Secrets or ConfigMaps, and reuse values like your bucket name across multiple features, such as Tiered Storage, Iceberg, and topic recovery. > > See [Set Redpanda cluster properties from Kubernetes Secrets or ConfigMaps](../../k-configure-helm-chart/#extra-cluster-config). ##### [](#configure-access-with-a-kms-key)**Configure access with a KMS key** To configure the Google Cloud bucket used by Redpanda Tiered Storage to leverage a customer-managed key using the Cloud Key Management Service API instead of the default Google-managed key, you must: 1. Create a KMS key. 2. Configure the bucket to use the KMS key. 3. Optionally, re-encrypt existing data with the new KMS key. To manage Google Cloud KMS using the command line, first install or upgrade to the latest version of [Google Cloud CLI](https://cloud.google.com/sdk/docs/install). To create a KMS key: 1. In Google Cloud Console, search for "Cloud Key Managment Service API". Click **Enable** if the service is not already enabled. 2. Using the Google Cloud CLI, create a new keyring in the [region](https://cloud.google.com/kms/docs/locations^) where the bucket used by Redpanda is located. Note that region is case sensitive. ```bash gcloud kms keyrings create "redpanda-keyring" --location="{REGION}" ``` 3. Create a new key for the keyring in the same region as the bucket: ```bash gcloud kms keys create "redpanda-key" \ --location="{REGION}" \ --keyring="redpanda-keyring" \ --purpose="encryption" ``` 4. Get the key identifier: ```bash gcloud kms keys list \ --location="REGION" \ --keyring="redpanda-keyring" ``` The result should look like the following. Be sure to store the name, as this is used to assign and manage the key. Use this as the {KEY\_RESOURCE} placeholder in subsequent commands. ```bash NAME PURPOSE ALGORITHM PROTECTION_LEVEL LABELS PRIMARY_ID PRIMARY_STATE projects/{PROJECT_NAME}/locations/us/keyRings/redpanda-keyring/cryptoKeys/redpanda-key ENCRYPT_DECRYPT GOOGLE_SYMMETRIC_ENCRYPTION SOFTWARE 1 ENABLED ``` To configure the GCP bucket to use the KMS key: 1. Assign the key to a service agent: ```bash gcloud storage service-agent \ --project={PROJECT_ID_STORING_OBJECTS} \ --authorize-cmek={KEY_RESOURCE} ``` 2. Set the bucket default encryption key to the KMS key: ```bash gcloud storage buckets update gs://{BUCKET_NAME} \ --default-encryption-key={KEY_RESOURCE} ``` (Optional) To re-encrypt existing data using the new KMS key: Existing data in the bucket continues to be read using the Google-managed key, while new objects are encrypted using the new KMS key. If you wish to re-encrypt all data in the bucket to use the KMS key, run: ```bash gcloud storage objects update gs://{BUCKET_NAME}/ --recursive \ --encryption-key={KEY_RESOURCE} ``` #### [](#microsoft-absadls)Microsoft ABS/ADLS You can configure access to Azure Blob Storage with either account access keys or Azure’s managed identities system to securely interact with Azure Blob Storage. Account access keys, as static credentials, require manual management and vigilant security practices to prevent breaches due to their unchanging nature. In contrast, managed identities provide a more secure and maintenance-free solution by automating credential management and rotation, though they are exclusive to the Azure ecosystem. > 📝 **NOTE** > > Starting in release 23.2.8, Redpanda supports storage accounts configured for ADLS Gen2 with [hierarchical namespaces](https://learn.microsoft.com/en-us/azure/storage/blobs/data-lake-storage-namespace) enabled. For hierarchical namespaces created with a custom endpoint, set `cloud_storage_azure_adls_endpoint` and `cloud_storage_azure_adls_port`. If you haven’t configured custom endpoints in Azure, there’s no need to edit these properties. ##### [](#configure-access-with-a-managed-identity)**Configure access with a managed identity** 1. Configure an [Azure managed identity](../../../security/iam-roles/#configuring-iam-roles). 2. Override the following required cluster properties in the Helm chart: ###### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: storage: tiered: config: cloud_storage_enabled: "true" cloud_storage_credentials_source: azure_aks_oidc_federation cloud_storage_azure_storage_account: cloud_storage_azure_container: serviceAccount: create: true annotations: "azure.workload.identity/client-id": statefulset: podTemplate: labels: "azure.workload.identity/use": "true" ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ###### Helm ###### --values `cloud-storage.yaml` ```yaml storage: tiered: config: cloud_storage_enabled: true cloud_storage_credentials_source: azure_aks_oidc_federation cloud_storage_azure_storage_account: cloud_storage_azure_container: serviceAccount: create: true annotations: "azure.workload.identity/client-id": statefulset: podTemplate: labels: "azure.workload.identity/use": "true" ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values cloud-storage.yaml ``` ###### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set storage.tiered.config.cloud_storage_enabled=true \ --set storage.tiered.config.cloud_storage_credentials_source=azure_aks_oidc_federation \ --set storage.tiered.config.cloud_storage_azure_storage_account= \ --set storage.tiered.config.cloud_storage_azure_container= \ --set serviceAccount.create=true \ --set serviceAccount.annotations."azure\.workload\.identity/client-id"="" \ --set statefulset.podTemplate.labels."azure\.workload\.identity/use"="true" ``` Replace the following placeholders: - ``: The name of your Azure account. - ``: The name of the Azure container in your Azure account. - ``: The client ID for your Azure managed identity. > ⚠️ **CAUTION** > > Do not set an object storage property to an empty string (`""`) or `null` to reset it. This may result in invalid or incomplete configuration. For safe ways to reset a property, see [Reset configuration values](../../k-configure-helm-chart/#reset-config). The `serviceAccount` annotations and the `statefulset` Pod labels are essential for the Azure webhook to inject the necessary Azure-specific environment variables and the projected service account token volume into the pods. For more information, visit [Microsoft Entra Workload ID with Azure Kubernetes Service (AKS)](https://learn.microsoft.com/en-us/azure/aks/workload-identity-overview?tabs=dotnet). > 💡 **TIP** > > Starting in Redpanda Operator v25.1.1, you can configure object storage settings using `config.extraClusterConfiguration`. This lets you securely reference sensitive values from Kubernetes Secrets or ConfigMaps, and reuse values like your bucket name across multiple features, such as Tiered Storage, Iceberg, and topic recovery. > > See [Set Redpanda cluster properties from Kubernetes Secrets or ConfigMaps](../../k-configure-helm-chart/#extra-cluster-config). ##### [](#configure-access-with-account-access-keys)**Configure access with account access keys** 1. Get an account access key for the Azure container that Redpanda will run on. For information on how to view your account access keys, see the [Azure documentation](https://learn.microsoft.com/en-us/azure/storage/common/storage-account-keys-manage?toc=%2Fazure%2Fstorage%2Fblobs%2Ftoc.json&bc=%2Fazure%2Fstorage%2Fblobs%2Fbreadcrumb%2Ftoc.json&tabs=azure-portal#view-account-access-keys). 2. Create a Secret in which to store the access key. ```yaml apiVersion: v1 kind: Secret metadata: name: storage-secrets namespace: type: Opaque data: access-key: ``` - Replace `` with your base64-encoded access key. 3. Override the following required cluster properties in the Helm chart: ###### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: storage: tiered: credentialsSecretRef: secretKey: configurationKey: cloud_storage_azure_shared_key name: storage-secrets key: access-key config: cloud_storage_enabled: "true" cloud_storage_azure_storage_account: cloud_storage_azure_container: ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ###### Helm ###### --values `cloud-storage.yaml` ```yaml storage: tiered: credentialsSecretRef: secretKey: configurationKey: cloud_storage_azure_shared_key name: storage-secrets key: access-key config: cloud_storage_enabled: true cloud_storage_azure_storage_account: cloud_storage_azure_container: ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values cloud-storage.yaml ``` ###### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set storage.tiered.config.cloud_storage_enabled=true \ --set storage.tiered.credentialsSecretRef.secretKey.configurationKey=cloud_storage_azure_shared_key \ --set storage.tiered.credentialsSecretRef.secretKey.name=storage-secrets \ --set storage.tiered.credentialsSecretRef.secretKey.key=access-key \ --set storage.tiered.config.cloud_storage_azure_storage_account= \ --set storage.tiered.config.cloud_storage_azure_container= ``` Replace the following placeholders: - ``: The name of your Azure account. - ``: The name of the Azure container in your Azure account. > ⚠️ **CAUTION** > > Do not set an object storage property to an empty string (`""`) or `null` to reset it. This may result in invalid or incomplete configuration. For safe ways to reset a property, see [Reset configuration values](../../k-configure-helm-chart/#reset-config). > 💡 **TIP** > > Starting in Redpanda Operator v25.1.1, you can configure object storage settings using `config.extraClusterConfiguration`. This lets you securely reference sensitive values from Kubernetes Secrets or ConfigMaps, and reuse values like your bucket name across multiple features, such as Tiered Storage, Iceberg, and topic recovery. > > See [Set Redpanda cluster properties from Kubernetes Secrets or ConfigMaps](../../k-configure-helm-chart/#extra-cluster-config). - For information about how to grant access from an internet IP range (if you need to open additional routes/ports between your broker nodes and Azure Blob Storage; for example, in a hybrid cloud deployment), see the [Microsoft documentation](https://learn.microsoft.com/en-us/azure/storage/common/storage-network-security?toc=%2Fazure%2Fstorage%2Fblobs%2Ftoc.json&bc=%2Fazure%2Fstorage%2Fblobs%2Fbreadcrumb%2Ftoc.json&tabs=azure-portal#grant-access-from-an-internet-ip-range). - For more information about Shared Key authentication, see the [Microsoft documentation](https://learn.microsoft.com/en-us/rest/api/storageservices/authorize-with-shared-key). For additional properties, see [Tiered Storage configuration properties](#tiered-storage-configuration-properties). ### [](#enable-tiered-storage)Enable Tiered Storage 1. To enable Tiered Storage, set `[storage.tiered.config.cloud_storage_enabled](../../../../reference/properties/object-storage-properties/#cloud_storage_enabled)` to `true`. 2. Configure topics for Tiered Storage. You can configure either all topics in a cluster or only specific topics. - [Enable Tiered Storage for a cluster](#enable-tiered-storage-for-a-cluster) - [Enable Tiered Storage for specific topics](#enable-tiered-storage-for-specific-topics) When you enable Tiered Storage on a topic already containing data, Redpanda uploads any existing data in that topic on local storage to the object store bucket. It will start from the earliest offset available on local disk. Redpanda strongly recommends that you avoid repeatedly toggling remote write on and off, because this can result in inconsistent data and data gaps in Tiered Storage for a topic. #### [](#enable-tiered-storage-for-a-cluster)Enable Tiered Storage for a cluster To enable Tiered Storage for a cluster (in addition to setting `cloud_storage_enabled` to `true`), set the following cluster-level properties to `true`: - `[storage.tiered.config.cloud_storage_enable_remote_write](../../../../reference/properties/object-storage-properties/#cloud_storage_enable_remote_write)` - `[storage.tiered.config.cloud_storage_enable_remote_read](../../../../reference/properties/object-storage-properties/#cloud_storage_enable_remote_read)` When you enable Tiered Storage for a cluster, you enable it for all existing topics in the cluster. You must restart your cluster after enabling Tiered Storage. > 📝 **NOTE** > > `cloud_storage_enable_remote_write` and `cloud_storage_enable_remote_read` act as creation-time defaults only for topics with `redpanda.storage.mode=unset`. They have no effect on topics where `redpanda.storage.mode` is explicitly set to `local`, `tiered`, or `cloud`. To apply a default storage mode to all new topics, use the `[storage.tiered.config.default_redpanda_storage_mode](../../../../reference/properties/cluster-properties/#default_redpanda_storage_mode)` cluster property instead. #### [](#enable-tiered-storage-for-specific-topics)Enable Tiered Storage for specific topics Starting in Redpanda v26.1, the recommended way to enable Tiered Storage for a topic is to set the `redpanda.storage.mode` topic property to `tiered`: ```bash rpk topic create -c redpanda.storage.mode=tiered ``` To enable Tiered Storage on an existing topic that was created in `local` mode: ```bash rpk topic alter-config --set redpanda.storage.mode=tiered ``` When `redpanda.storage.mode=tiered` is set, Tiered Storage is fully enabled for the topic. The `redpanda.remote.read` and `redpanda.remote.write` topic properties have no effect on a topic’s storage when `redpanda.storage.mode` is set to any value other than `unset`. #### [](#configure-tiered-storage-using-legacy-topic-properties)Configure Tiered Storage using legacy topic properties For topics with `redpanda.storage.mode=unset` (the default when `default_redpanda_storage_mode` is not configured), Tiered Storage is controlled by the `redpanda.remote.read` and `redpanda.remote.write` topic properties: - `redpanda.remote.write`: Uploads data from Redpanda to object storage. - `redpanda.remote.read`: Fetches data from object storage to Redpanda. For example, to create a topic using the legacy properties when the storage mode is `unset`: ```bash rpk topic create -c redpanda.remote.read=true -c redpanda.remote.write=true ``` To enable Tiered Storage on an existing topic where the storage mode is `unset`: ```bash rpk topic alter-config --set redpanda.remote.read=true --set redpanda.remote.write=true ``` For newly-created unset topics, the cluster-level `cloud_storage_enable_remote_write` and `cloud_storage_enable_remote_read` properties dictate the topic-level properties `redpanda.remote.write` and `redpanda.remote.read` at topic creation time, respectively. Altering the cluster properties has no effect on existing topics, only newly-created ones. To alter the permissions for existing topics, you can set these topic properties directly. For example, `redpanda.remote.write=false` to disable uploads for a specific topic. Tiered Storage topic-level properties: | Property | Description | | --- | --- | | redpanda.remote.write | Uploads data from Redpanda to object storage. For topics with redpanda.storage.mode=unset, overrides the cluster-level cloud_storage_enable_remote_write setting. Has no effect on topics with redpanda.storage.mode set to local, tiered, or cloud. | | redpanda.remote.read | Fetches data from object storage to Redpanda. For topics with redpanda.storage.mode=unset, overrides the cluster-level cloud_storage_enable_remote_read setting. Has no effect on topics with redpanda.storage.mode set to local, tiered, or cloud. | | redpanda.remote.recovery | Recovers or reproduces a topic from object storage. Use this property during topic creation. It does not apply to existing topics. | | redpanda.remote.delete | When set to true, deleting a topic also deletes its objects in object storage. Applies to both Tiered Storage topics and Cloud Topics.For Tiered Storage topics, the topic must not be a Remote Read Replica topic.When set to false, deleting a topic does not delete its objects in object storage.Default is true for new topics. | The following tables show outcomes for combinations of cluster-level and topic-level configurations for topics with `redpanda.storage.mode=unset` at topic creation time: | Cluster-level configuration with cloud_storage_enable_remote_write | Topic-level configuration with redpanda.remote.write | Outcome: whether remote write is enabled or disabled on the topic | | --- | --- | --- | | true | Not set | Enabled | | true | false | Disabled | | true | true | Enabled | | false | Not set | Disabled | | false | false | Disabled | | false | true | Enabled | | Cluster-level configuration with cloud_storage_enable_remote_read | Topic-level configuration with redpanda.remote.read | Outcome: whether remote read is enabled or disabled on the topic | | --- | --- | --- | | true | Not set | Enabled | | true | false | Disabled | | true | true | Enabled | | false | Not set | Disabled | | false | false | Disabled | | false | true | Enabled | ### [](#set-retention-limits)Set retention limits Redpanda supports retention limits and compaction for topics using Tiered Storage. Set retention limits to purge topic data after it reaches a specified age or size. Starting in Redpanda version 22.3, object storage is the default storage tier for all streaming data, and retention properties work the same for Tiered Storage topics and local storage topics. Data is retained in object storage until it reaches the configured time or size limit. Data becomes eligible for deletion from object storage following `retention.ms` or `retention.bytes`. For example, if `retention.bytes` is set to 10 GiB, then every partition in the topic has a limit of 10 GiB in object storage. When `retention.bytes` is exceeded by data in object storage, the data in object storage is trimmed. If neither `retention.ms` nor `retention.bytes` is specified, then cluster-level defaults are used. > 📝 **NOTE** > > - During upgrade, Redpanda preserves retention settings for existing topics. > > - Both size-based and time-based retention policies are applied simultaneously, so it’s possible for your size-based property to override your time-based property, or vice versa. For example, if your size-based property requires removing one segment, and your time-based property requires removing three segments, then three segments are removed. Size-based properties reclaim disk space as close as possible to the maximum size, without exceeding the limit. See also: [Configure message retention](../../../cluster-maintenance/disk-utilization/#configure-message-retention) and [Space management](../../../cluster-maintenance/disk-utilization/#space-management) #### [](#compacted-topics-in-tiered-storage)Compacted topics in Tiered Storage When you set [`cleanup.policy`](../../../../reference/properties/topic-properties/#cleanuppolicy) for a topic to `compact`, nothing gets deleted from object storage based on retention settings. When set to `compact,delete`, compacted segments are deleted from object storage based on `retention.ms` and `retention.bytes`. For compacted topics, Redpanda compacts segments after they have been uploaded to object storage. Redpanda initially uploads all uncompacted segments. It then re-uploads the segments with compaction applied. It’s likely that some segments in object storage are not compacted, but the Tiered Storage read path can manage this. #### [](#manage-local-capacity-for-tiered-storage-topics)Manage local capacity for Tiered Storage topics You can use properties to control retention of topic data in local storage. With Tiered Storage enabled, data in local storage expires after the topic-level properties `retention.local.target.ms` or `retention.local.target.bytes`. (These settings are equivalent to `retention.ms` and `retention.bytes` without Tiered Storage.) You can also use the cluster-level properties `retention_local_target_ms_default` and `retention_local_target_bytes_default`. Settings can depend on the size of your drive, how many partitions you have, and how much data you keep for each partition. When set, Redpanda keeps actively-used and sequential (next segment) data in local cache and targets to maintain this age of data in local storage. It purges data based on actual available local volume space, without forcing disk full situations when there is data skew. At topic creation with Tiered Storage enabled: - If `retention.ms` or `retention.bytes` is set, Redpanda initializes the `retention.local.target.*` properties. - If `retention.local.target.ms` or `retention.local.target.bytes` is set, Redpanda initializes the `min(retention.bytes, retention.local.target.bytes)` and `max(retention.ms, retention.local.target.ms)` properties. - If properties are not specified: - Starting in version 22.3, new topics use the default retention values of one day for local storage (`[storage.tiered.config.retention_local_target_ms_default](../../../../reference/properties/cluster-properties/#retention_local_target_ms_default)`) and seven days for all storage, including object storage (`[storage.tiered.config.log_retention_ms](../../../../reference/properties/cluster-properties/#log_retention_ms)`). - Upgraded topics retain their historical defaults of infinite retention. After topic configuration, if Tiered Storage was disabled and must be enabled, or was enabled and must be disabled, Redpanda uses the local retention properties set for the topic. It is strongly recommended that you do not re-enable Tiered Storage after previously enabling and disabling it. Re-enabling Tiered Storage can result in inconsistent data and data gaps in Tiered Storage for a topic. See also: [Space management](../../../cluster-maintenance/disk-utilization/#space-management) ## [](#view-space-usage)View space usage Use [`rpk cluster logdirs describe`](../../../../reference/rpk/rpk-cluster/rpk-cluster-logdirs-describe/) to get details about Tiered Storage space usage in both object storage and local disk. The directories for object storage start with `remote://`. For example: ```bash rpk cluster logdirs describe BROKER DIR TOPIC PARTITION SIZE ERROR 0 /home/redpanda/var/node0/data monday 0 18406863 0 remote://data monday 0 60051220 1 /home/redpanda/var/node1/data monday 0 22859882 1 remote://data monday 0 60051220 2 /home/redpanda/var/node2/data monday 0 17169935 2 remote://data monday 0 60051220 ``` ### [](#integration-with-space-utilization-tools)Integration with space utilization tools Third-party tools that query space utilization from the Redpanda cluster might not handle `remote://` entries properly. Redpanda space usage is reported from each broker, but object storage is shared between brokers. Third-party tools could over-count storage and show unexpectedly high disk usage for Tiered Storage topics. In this situation, you can disable output of `remote://` entries by setting `kafka_enable_describe_log_dirs_remote_storage` to `false`. ## [](#remote-write)Remote write Remote write is the process that constantly uploads log segments to object storage. The process is created for each partition and runs on the leader broker of the partition. It only uploads the segments that contain offsets that are smaller than the last stable offset. This is the latest offset that the client can read. To ensure all data is uploaded, you must enable remote write before any data is produced to the topic. If you enable remote write after data has been written to the topic, only the data that currently exists on disk based on local retention settings will be scheduled for uploading. Redpanda strongly recommends that you avoid repeatedly toggling remote write on and off, because this can result in inconsistent data and data gaps in Tiered Storage for a topic. To enable Tiered Storage, use both remote write and remote read. To create a topic with remote write enabled: ```bash rpk topic create -c redpanda.remote.write=true ``` To enable remote write on an existing topic: ```bash rpk topic alter-config --set redpanda.remote.write=true ``` If remote write is enabled, log segments are not deleted until they’re uploaded to object storage. Because of this, the log segments may exceed the configured retention period until they’re uploaded, so the topic might require more disk space. This prevents data loss if segments cannot be uploaded fast enough or if the retention period is very short. To see the object storage status for a given topic: ```bash rpk topic describe-storage --print-all ``` See the [reference](../../../../reference/rpk/rpk-topic/rpk-topic-describe-storage/) for a list of flags you can use to filter the command output. > 💡 **TIP** > > A constant stream of data is necessary to build up the log segments and roll them into object storage. This upload process is asynchronous. You can monitor its status with the [`/metrics/vectorized_ntp_archiver_pending`](../../../../reference/internal-metrics-reference/#vectorized_ntp_archiver_pending) metric. > > To see new log segments faster, you can edit the `segment.bytes` topic-level property. Or, you can edit the [`cloud_storage_segment_max_upload_interval_sec`](../../../../reference/properties/object-storage-properties/#cloud_storage_segment_max_upload_interval_sec) property, which sets the frequency with which new segments are generated in Tiered Storage, even if the local segment has not exceeded the `segment.bytes` size or the `segment.ms` age. > 📝 **NOTE** > > Starting in version 22.3, when you delete a topic in Redpanda, the data is also deleted in object storage. See [Enable Tiered Storage for specific topics](#enable-tiered-storage-for-specific-topics). ### [](#idle-timeout)Idle timeout You can configure Redpanda to start a remote write periodically. This is useful if the ingestion rate is low and the segments are kept open for long periods of time. You specify a number of seconds for the timeout, and if that time has passed since the previous write and the partition has new data, Redpanda starts a new write. This limits data loss in the event of catastrophic failure and adds a guarantee that you only lose the specified number of seconds of data. Setting idle timeout to a very short interval can create a lot of small files, which can affect throughput. If you decide to set a value for idle timeout, start with 600 seconds, which prevents the creation of so many small files that throughput is affected when you recover the files. Use the [`cloud_storage_segment_max_upload_interval_sec`](../../../../reference/properties/object-storage-properties/#cloud_storage_segment_max_upload_interval_sec) property to set the number of seconds for idle timeout. If this property is set to null, Redpanda uploads metadata to object storage, but the segment is not uploaded until it reaches the `segment.bytes` size. ### [](#reconciliation)Reconciliation Reconciliation is a Redpanda process that monitors partitions and decides which partitions are uploaded on each broker to guarantee that data is uploaded only once. It runs periodically on every broker. It also balances the workload evenly between brokers. > 📝 **NOTE** > > The broker uploading to object storage is always with the partition leader. Therefore, when partition leadership balancing occurs, Redpanda stops uploads to object storage from one broker and starts uploads on another broker. ### [](#upload-backlog-controller)Upload backlog controller Remote write uses a proportional derivative (PD) controller to minimize the backlog size for the write. The backlog consists of data that has not been uploaded to object storage but must be uploaded eventually. The upload backlog controller prevents Redpanda from running out of disk space. If `remote.write` is set to `true`, Redpanda cannot evict log segments that have not been uploaded to object storage. If the remote write process cannot keep up with the amount of data that needs to be uploaded to object storage, the upload backlog controller increases priority for the upload process. The upload backlog controller measures the size of the upload periodically and tunes the priority of the remote write process. ### [](#data-archiving)Data archiving If you only enable remote write on a topic, you have a simple backup to object storage that you can use for recovery. In the event of a data center failure, data corruption, or cluster migration, you can recover your archived data from the cloud back to your cluster. #### [](#configure-data-archiving)Configure data archiving Data archiving requires a [Tiered Storage configuration](#set-up-tiered-storage). To recover a topic from object storage, use [single topic recovery](../k-topic-recovery/). > ⚠️ **WARNING** > > While performing topic recovery, avoid adding additional load (such as produces, consumes, lists or additional recovery operations) to the target cluster. Doing so could destabilize the recovery process and result in either an unsuccessful or corrupted recovered topic. #### [](#stop-data-archiving)Stop data archiving To cancel archiving jobs, disable remote write. To delete archival data, adjust `retention.ms` or `retention.bytes`. ## [](#remote-read)Remote read Remote read fetches data from object storage using the Kafka API. Without Tiered Storage, when data is evicted locally, it is no longer available. If the consumer starts consuming the partition from the beginning, the first offset is the smallest offset available locally. However, when Tiered Storage is enabled with the `redpanda.remote.read` and `redpanda.remote.write` properties, data is always uploaded to object storage before it’s deleted. This guarantees that data is always available either locally or remotely. When data is available remotely and Tiered Storage is enabled, clients can consume data, even if the data is no longer stored locally. To create a topic with remote read enabled: ```bash rpk topic create -c redpanda.remote.read=true ``` To enable remote read on an existing topic: ```bash rpk topic alter-config --set redpanda.remote.read=true ``` See also: [Topic Recovery](../k-topic-recovery/), [Remote Read Replicas](../../k-remote-read-replicas/) ## [](#pause-and-resume-uploads)Pause and resume uploads > ❗ **IMPORTANT** > > Redpanda strongly recommends using pause and resume only under the guidance of [Redpanda Support](https://support.redpanda.com/hc/en-us/requests/new) or a member of your account team. Starting in version 25.1, you can troubleshoot issues your cluster has interacting with object storage by pausing and resuming uploads. You can do this with no risk of data consistency or data loss. To pause or resume segment uploads to object storage, use the [`cloud_storage_enable_segment_uploads`](../../../../reference/properties/object-storage-properties/#cloud_storage_enable_segment_uploads) configuration property (default is `true`). This allows segment uploads to proceed after the pause completes and uploads resume. While uploads are paused, data accumulates locally, which can lead to full disks if the pause is prolonged. If the disks fill, Redpanda throttles produce requests and rejects new Kafka produce requests to prevent data from being written. Additionally, this pauses object storage housekeeping, meaning segments are neither uploaded nor removed from object storage. However, it is still possible to consume data from object storage while uploads are paused. When you set `cloud_storage_enable_segment_uploads` to `false`, all in-flight segment uploads complete, but no new segment uploads begin until the value is set back to `true`. During this pause, Tiered Storage enforces consistency by ensuring that no segment in local storage is deleted until it successfully uploads to object storage. This means that when uploads are resumed, no user intervention is needed, and no data gaps are created. Use the `redpanda_cloud_storage_paused_archivers` metric to monitor the status of paused uploads. It displays a non-zero value whenever uploads are paused. > ⚠️ **WARNING** > > Do not use `redpanda.remote.read` or `redpanda.remote.write` to pause and resume segment uploads. Doing so can lead to a gap between local data and data in object storage. In such cases, it is possible that the oldest segment is not aligned with the last uploaded segment. Given that these settings are unsafe, if you choose to set either `redpanda.remote.write` or the cluster configuration setting `cloud_storage_enable_remote_write` to `false`, you receive a warning: > > ```bash > Warning: disabling Tiered Storage may lead to data loss. If you only want to pause Tiered Storage temporarily, use the `cloud_storage_enable_segment_uploads` option. Abort? > # The default is Yes. > ``` The following example shows a simple pause and resume with no gaps allowed: ```bash rpk cluster config set cloud_storage_enable_segment_uploads false # Segments are not uploaded to cloud storage, and cloud storage housekeeping is not running. # The new data added to the topics with Tiered Storage is not deleted from disk # because it can't be uploaded. The disks may fill up eventually. # If the disks fill up, produce requests will be rejected. ... rpk cluster config set cloud_storage_enable_segment_uploads true # At this point the uploads should resume seamlessly and # there should not be any data loss. ``` For some applications, where the newest data is more valuable than historical data, data accumulation can be worse than data loss. In such cases, where you cannot afford to lose the most recently-produced data by rejecting produce requests after producers have filled the local disks during the period of paused uploads, there is a less safe pause and resume mechanism. This mechanism prioritizes the ability to receive new data over retaining data that cannot be uploaded when disks are full: - Set the [`cloud_storage_enable_remote_allow_gaps`](../../../../reference/properties/object-storage-properties/#cloud_storage_enable_remote_allow_gaps) cluster configuration property to `true`. This allows for gaps in the logs of all Tiered Storage topics in the cluster. When you pause uploads and set one of these properties to `true`, there may be gaps in the range of offsets stored in object storage. You can seamlessly resume uploads by setting `*allow_gaps` to `true` at either the cluster or topic level. If set to `false`, disk space could be depleted and produce requests would be throttled. The following example shows how to pause and resume Tiered Storage uploads while allowing for gaps: ```bash rpk cluster config set cloud_storage_enable_segment_uploads false # Segment uploads are paused and cloud storage housekeeping is not running. # New data is stored on the local volume, which may overflow. # To avoid overflow when allowing gaps in the log. # In this example, data that is not uploaded to cloud storage may be # deleted if a disk fills before uploads are resumed. ... rpk cluster config set cloud_storage_enable_segment_uploads true # Uploads are resumed but there could be gaps in the offsets. # Wait until you see that the `redpanda_cloud_storage_paused_archivers` # metric is equal to zero, indicating that uploads have resumed. ``` ## [](#caching)Caching When a consumer fetches an offset range that isn’t available locally in the Redpanda data directory, Redpanda downloads remote segments from object storage. These downloaded segments are stored in the object storage cache. ### [](#change-the-cache-directory)Change the cache directory By default, the cache directory is created in Redpanda’s data directory, but it can be placed anywhere in the system. For example, you might want to put the cache directory on a dedicated drive with cheaper storage. Use the [`cloud_storage_cache_directory`](../../../../reference/properties/broker-properties/#cloud_storage_cache_directory) broker property to specify a different location for the cache directory. You must specify the full path. To specify a different volume for the cache directory, use one of the following: - PersistentVolume - `hostPath` volume #### [](#persistentvolume)PersistentVolume A PersistentVolume is storage in the cluster that has been provisioned by an administrator or dynamically provisioned using StorageClasses. For details about PersistentVolumes, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/storage/persistent-volumes/). You can configure the Helm chart to use a PersistentVolume for the cache directory with either a static provisioner or a dynamic provisioner. A dynamic provisioner creates a PersistentVolume on demand for each Redpanda broker. Managed Kubernetes platforms and cloud environments usually provide a dynamic provisioner. If you are running Kubernetes on-premises, make sure that you have a dynamic provisioner for your storage type. 1. Make sure that you have at least one StorageClass in the cluster: ```bash kubectl get storageclass ``` Example output: In a Google GKE cluster, this is the result: NAME PROVISIONER AGE standard (default) kubernetes.io/gce-pd 1d This StorageClass is marked as the default, which means that this class is used to provision a PersistentVolume when the PersistentVolumeClaim doesn’t specify the StorageClass. 2. Configure the Helm chart with your StorageClass: - To use your Kubernetes cluster’s default StorageClass, set `storage.persistentVolume.storageClass` to an empty string (`""`): ##### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: storage: tiered: mountType: persistentVolume persistentVolume: storageClass: "" config: cloud_storage_cache_size: cloud_storage_cache_directory: ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ##### Helm ###### --values `storageclass.yaml` ```yaml storage: tiered: mountType: persistentVolume persistentVolume: storageClass: "" config: cloud_storage_cache_size: cloud_storage_cache_directory: ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values storageclass.yaml --reuse-values ``` ###### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set storage.tiered.mountType=persistentVolume \ --set storage.tiered.persistentVolume.storageClass="" \ --set storage.tiered.config.cloud_storage_cache_size= \ --set storage.tiered.config.cloud_storage_cache_directory= ``` - To use a specific StorageClass, set its name in the `storage.tieredStoragePersistentVolume.storageClass` configuration: ##### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: storage: tiered: mountType: persistentVolume persistentVolume: storageClass: "" config: cloud_storage_cache_size: cloud_storage_cache_directory: ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ##### Helm ###### --values `storageclass.yaml` ```yaml storage: tiered: mountType: persistentVolume persistentVolume: storageClass: "" config: cloud_storage_cache_size: cloud_storage_cache_directory: ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values storageclass.yaml --reuse-values ``` ###### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set storage.tiered.mountType=persistentVolume \ --set storage.tiered.persistentVolume.storageClass="" \ --set storage.tiered.config.cloud_storage_cache_size= \ --set storage.tiered.config.cloud_storage_cache_directory= ``` > ⚠️ **CAUTION** > > Do not set an object storage property to an empty string `""` or to `null` as a way to reset it to its default value. When you use a static provisioner, an existing PersistentVolume in the cluster is selected and bound to one PersistentVolumeClaim for each Redpanda broker. 1. Create one PersistentVolume for each Redpanda broker. Make sure to create PersistentVolumes with a capacity of at least the value of the `storage.tiered.config.cloud_storage_cache_size` configuration. 2. Set the `storage.tiered.persistentVolume.storageClass` to a dash (`"-"`) to use a PersistentVolume with a static provisioner: ##### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: storage: tiered: mountType: persistentVolume persistentVolume: storageClass: "-" config: cloud_storage_cache_size: cloud_storage_cache_directory: ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ##### Helm ###### --values `storageclass.yaml` ```yaml storage: tiered: mountType: persistentVolume persistentVolume: storageClass: "-" config: cloud_storage_cache_size: cloud_storage_cache_directory: ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values storageclass.yaml --reuse-values ``` ###### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set storage.tiered.mountType=persistentVolume \ --set storage.tiered.persistentVolume.storageClass="-" \ --set storage.tiered.config.cloud_storage_cache_size= \ --set storage.tiered.config.cloud_storage_cache_directory= ``` > ⚠️ **CAUTION** > > Do not set an object storage property to an empty string `""` or to `null` as a way to reset it to its default value. #### [](#hostpath)hostPath A hostPath volume mounts a file or directory from the host node’s file system into your Pod. For details about hostPath volumes, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/storage/volumes/#hostpath). To use a hostPath volume for the cache directory: 1. Set the `storage.tiered.mountPath` configuration to `hostPath`. 2. Set the `storage.tiered.hostPath` configuration to the absolute path of a file on the local worker node. 3. Set `statefulset.initContainers.setDataDirOwnership.enabled` to `true`. Pods that run Redpanda brokers must have read/write access to their data directories. The initContainer is responsible for setting write permissions on the data directories. By default, `statefulset.initContainers.setDataDirOwnership` is disabled because most storage drivers call `SetVolumeOwnership` to give Redpanda permissions to the root of the storage mount. However, some storage drivers, such as `hostPath`, do not call `SetVolumeOwnership`. In this case, you must enable the initContainer to set the permissions. > ❗ **IMPORTANT** > > To set permissions on the data directories, the initContainer must run as root. However, be aware that an initContainer running as root can introduce the following security risks: > > - **Privilege escalation:** If attackers gains access to the initContainer, they can escalate privileges to gain full control over the system. For example, attackers could use the initContainer to gain unauthorized access to sensitive data, tamper with the system, or start denial-of-service attacks. > > - **Container breakouts:** If the container is misconfigured or the container runtime has a vulnerability, attackers could escape from the initContainer and access the host operating system. > > - **Image tampering:** If attackers gain access to the container image of the initContainer, they could add malicious code or backdoors to it. Image tampering could compromise the security of the entire cluster. ##### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: storage: tiered: mountType: hostPath hostPath: "" config: cloud_storage_cache_size: cloud_storage_cache_directory: ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` ##### Helm ###### --values `hostpath.yaml` ```yaml storage: tiered: mountType: hostPath hostPath: "" config: cloud_storage_cache_size: cloud_storage_cache_directory: ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values hostpath.yaml --reuse-values ``` ###### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set storage.tiered.mountType=hostPath \ --set storage.tiered.hostPath="" \ --set storage.tiered.config.cloud_storage_cache_size= \ --set storage.tiered.config.cloud_storage_cache_directory= ``` > ⚠️ **CAUTION** > > Do not set an object storage property to an empty string `""` or to `null` as a way to reset it to its default value. ### [](#max-cache)Set a maximum cache size To ensure that the cache does not grow uncontrollably, which could lead to performance issues or disk space exhaustion, you can control the maximum size of the cache. Redpanda checks the cache periodically according to the interval set in `[storage.tiered.config.cloud_storage_cache_check_interval_ms](../../../../reference/properties/object-storage-properties/#cloud_storage_cache_check_interval_ms)`. If the size of the stored data exceeds the configured limit, the eviction process starts. This process removes segments that haven’t been accessed recently until the cache size drops to the target level. **Related properties**: - `[storage.tiered.config.cloud_storage_cache_size_percent](../../../../reference/properties/object-storage-properties/#cloud_storage_cache_size_percent)` - `[storage.tiered.config.cloud_storage_cache_max_objects](../../../../reference/properties/object-storage-properties/#cloud_storage_cache_max_objects)` - `[storage.tiered.config.cloud_storage_cache_size](../../../../reference/properties/object-storage-properties/#cloud_storage_cache_size)` **Recommendation**: By default, `cloud_storage_cache_size_percent` is tuned for a shared disk configuration. If you are using a dedicated cache disk, consider increasing this value. #### [](#cache-trimming)Cache trimming Cache trimming helps to balance optimal cache use with the need to avoid blocking reads due to a full cache. The trimming process is triggered when the cache exceeds certain thresholds relative to the [maximum cache size](#max-cache). **Related properties**: - `[storage.tiered.config.cloud_storage_cache_trim_threshold_percent_objects](../../../../reference/properties/object-storage-properties/#cloud_storage_cache_trim_threshold_percent_objects)` - `[storage.tiered.config.cloud_storage_cache_trim_threshold_percent_size](../../../../reference/properties/object-storage-properties/#cloud_storage_cache_trim_threshold_percent_size)` - `[storage.tiered.config.cloud_storage_cache_trim_walk_concurrency](../../../../reference/properties/object-storage-properties/#cloud_storage_cache_trim_walk_concurrency)` **Recommendations**: - A threshold of 70% is recommended for most use cases. This percentage helps balance optimal cache use and ensures the cache has enough free space to handle sudden spikes in data without blocking reads. For example, setting `cloud_storage_cache_trim_threshold_percent_size` to 80% means that the cache trimming process starts when the cache takes up 80% of the maximum cache size. - Monitor the behavior of your cache and the performance of your Redpanda cluster. If reads are taking longer than expected or if you encounter timeout errors, your cache may be filling up too quickly. In these cases, consider lowering the thresholds to trigger trimming sooner. > 📝 **NOTE** > > The lower you set the threshold, the earlier the trimming starts, but it can also waste cache space. A higher threshold uses more cache space efficiently, but it risks blocking reads if the cache fills up too quickly. Adjust the settings based on your workload and monitor the cache performance to find the right balance for your environment. ### [](#chunk-remote-segments)Chunk remote segments To support more concurrent consumers of historical data with less local storage, Redpanda can download small chunks of remote segments to the cache directory. For example, when a client fetch request spans a subsection of a 1 GiB segment, instead of downloading the entire 1 GiB segment, Redpanda can download 16 MiB chunks that contain just enough data required to fulfill the fetch request. Use the `[storage.tiered.config.cloud_storage_cache_chunk_size](../../../../reference/properties/object-storage-properties/#cloud_storage_cache_chunk_size)` property to define the size of the chunks. The paths on disk to a chunk are structured as `p_chunks/{chunk_start_offset}`, where `p` is the original path to the segment in the object storage cache. The `_chunks/` subdirectory holds chunk files identified by the chunk start offset. These files can be reclaimed by the cache eviction process during the normal eviction path. ### [](#chunk-eviction-strategies)Chunk eviction strategies Selecting an appropriate chunk eviction strategy helps manage cache space effectively. A chunk that isn’t shared with any data source can be evicted from the cache, so space is returned to disk. Use the `[storage.tiered.config.cloud_storage_chunk_eviction_strategy](../../../../reference/properties/object-storage-properties/#cloud_storage_chunk_eviction_strategy)` property to change the eviction strategy. The strategies are: - `eager` (default): Evicts chunks that aren’t shared with other data sources. Eviction is fast, because no sorting is involved. - `capped`: Evicts chunks until the number of hydrated chunks is below or equal to the maximum hydrated chunks at a time. This limit is for each segment and calculated using `cloud_storage_hydrated_chunks_per_segment_ratio` by the remote segment. Eviction is fastest, because no sorting is involved, and the process stops after the cap is reached. - `predictive`: Uses statistics from readers to determine which chunks to evict. Chunks that aren’t in use are sorted by the count of readers that will use the chunk in the future. The counts are populated by readers using the chunk data source. The chunks that are least expensive to re-hydrate are then evicted, taking into account the maximum hydrated chunk count. Eviction is slowest, because chunks are sorted before evicting them. **Recommendation**: For general use, the `eager` strategy is recommended due to its speed. For workloads with specific access patterns, the `predictive` strategy may offer better cache efficiency. ### [](#caching-and-chunking-properties)Caching and chunking properties Use the following cluster-level properties to set the maximum cache size, the cache check interval, and chunking qualities. | Property | Description | | --- | --- | | storage.tiered.config.cloud_storage_cache_check_interval_ms | The time, in milliseconds, between cache checks. The size of the cache can grow quickly, so it’s important to have a small interval between checks. However, if the checks are too frequent, they consume a lot of resources. Default is 30000 ms (30 sec). | | storage.tiered.config.cloud_storage_cache_chunk_size | The size of a chunk downloaded into object storage cache. Default is 16 MiB. | | storage.tiered.config.cloud_storage_cache_directory | The directory where the cache archive is stored. | | storage.tiered.config.cloud_storage_cache_max_objects | Maximum number of objects that may be held in the Tiered Storage cache. This applies simultaneously with cloud_storage_cache_size, and whichever limit is hit first will trigger trimming of the cache. | | storage.tiered.config.cloud_storage_cache_num_buckets | Divide the object storage cache across the specified number of buckets. This only works for objects with randomized prefixes. The names are not changed when the value is set to zero. | | storage.tiered.config.cloud_storage_cache_size_percent | Maximum size (as a percentage) of the disk cache used by Tiered Storage.If both this property and cloud_storage_cache_size are set, Redpanda uses the minimum of the two. | | storage.tiered.config.cloud_storage_cache_size | Maximum size (in bytes) of the disk cache used by Tiered Storage.If both this property and cloud_storage_cache_size_percent are set, Redpanda uses the minimum of the two. | | storage.tiered.config.cloud_storage_cache_trim_threshold_percent_objects | Trigger cache trimming when the number of objects in the cache reaches this percentage relative to its maximum object count. If unset, the default behavior is to start trimming when the cache is full. | | storage.tiered.config.cloud_storage_cache_trim_threshold_percent_size | Trigger cache trimming when the cache size reaches this percentage relative to its maximum capacity. If unset, the default behavior is to start trimming when the cache is full. | | storage.tiered.config.cloud_storage_cache_trim_walk_concurrency | The maximum number of concurrent tasks launched for traversing the directory structure during cache trimming. A higher number allows cache trimming to run faster but can cause latency spikes due to increased pressure on I/O subsystem and syscall threads. | | storage.tiered.config.cloud_storage_chunk_eviction_strategy | Strategy for evicting unused cache chunks, either eager (default), capped, or predictive. | | storage.tiered.config.cloud_storage_disable_chunk_reads | Flag to turn off chunk-based reads and enable full-segment downloads. Default is false. | | storage.tiered.config.cloud_storage_hydrated_chunks_per_segment_ratio | The ratio of hydrated to non-hydrated chunks for each segment, where a current ratio above this value results in unused chunks being evicted. Default is 0.7. | | storage.tiered.config.cloud_storage_min_chunks_per_segment_threshold | The threshold below which all chunks of a segment can be hydrated without eviction. If the number of chunks in a segment is below this threshold, the segment is small enough that all chunks in it can be hydrated at any given time. Default is 5. | ## [](#retries-and-backoff)Retries and backoff If the object storage provider replies with an error message that the server is busy, Redpanda retries the request. Redpanda may retry on other errors, depending on the object storage provider. Redpanda always uses exponential backoff with cloud connections. You can configure the `[storage.tiered.config.cloud_storage_initial_backoff_ms](../../../../reference/properties/object-storage-properties/#cloud_storage_initial_backoff_ms)` property to set the time used as an initial backoff interval in the exponential backoff algorithm to handle an error. Default is 100 ms. ## [](#transport)Transport Tiered Storage creates a connection pool for each CPU that limits simultaneous connections to the object storage provider. It also uses persistent HTTP connections with a configurable maximum idle time. A custom S3 client is used to send and receive data. For normal usage, you do not need to configure the transport properties. The Redpanda defaults are sufficient, and the certificates used to connect to the object storage client are available through public key infrastructure. Redpanda detects the location of the CA certificates automatically. Redpanda uses the following properties to configure transport. | Property | Description | | --- | --- | | storage.tiered.config.cloud_storage_max_connections | The maximum number of connections to object storage on a broker for each CPU. Remote read and remote write share the same pool of connections. This means that if a connection is used to upload a segment, it cannot be used to download another segment. If this value is too small, some workloads might starve for connections, which results in delayed uploads and downloads. If this value is too large, Redpanda tries to upload a lot of files at the same time and might overwhelm the system. Default is 20. | | storage.tiered.config.cloud_storage_segment_upload_timeout_ms | Timeout for segment upload. Redpanda retries the upload after the timeout. Default is 30000 ms. | | storage.tiered.config.cloud_storage_manifest_upload_timeout_ms | Timeout for manifest upload. Redpanda retries the upload after the timeout. Default is 10000 ms. | | storage.tiered.config.cloud_storage_max_connection_idle_time_ms | The maximum idle time for persistent HTTP connections. This differs depending on the object storage provider. Default is 5000 ms, which is sufficient for most providers. | | storage.tiered.config.cloud_storage_segment_max_upload_interval_sec | The number of seconds for idle timeout. If this property is empty, Redpanda uploads metadata to the object storage, but the segment is not uploaded until it reaches the segment.bytes size. By default, the property is empty. | | storage.tiered.config.cloud_storage_trust_file | The public certificate used to validate the TLS connection to object storage. If this is empty, Redpanda uses your operating system’s CA cert pool. | ## [](#object-storage-housekeeping)Object storage housekeeping To improve performance and scalability, Redpanda performs object storage housekeeping when the system is idle. This housekeeping includes adjacent segment merging, which analyzes the data layout of the partition in object storage. If it finds a run of small segments, it can merge and reupload the segment. To determine when the system is idle for housekeeping, Redpanda constantly calculates object storage utilization using the moving average with a sliding window algorithm. The width of the sliding window is defined by the `[storage.tiered.config.cloud_storage_idle_timeout_ms](../../../../reference/properties/object-storage-properties/#cloud_storage_idle_timeout_ms)` property, which has a default of 10 seconds. If the utilization (requests per second) drops below the threshold, then object storage is considered idle, and object storage housekeeping begins. The threshold is defined by the `[storage.tiered.config.cloud_storage_idle_threshold_rps](../../../../reference/properties/object-storage-properties/#cloud_storage_idle_threshold_rps)` property, which has a default of one request per second. Object storage is considered idle if, during the last 10 seconds, there were 10 or less object storage API requests. If the object storage API becomes active after housekeeping begins, then housekeeping is paused until it becomes idle again. If object storage is not idle for `[storage.tiered.config.cloud_storage_housekeeping_interval_ms](../../../../reference/properties/object-storage-properties/#cloud_storage_housekeeping_interval_ms)`, then housekeeping is forced to run until it completes. This guarantees that all housekeeping jobs are run once for every `cloud_storage_housekeeping_interval_ms`. See also: [Space management](../../../cluster-maintenance/disk-utilization/#space-management) ### [](#adjacent-segment-merging)Adjacent segment merging By default, and as part of this object storage housekeeping, Redpanda runs adjacent segment merging on all segments in object storage that are smaller than the threshold. Two properties control the behavior of `[storage.tiered.config.cloud_storage_enable_segment_merging](../../../../reference/properties/object-storage-properties/#cloud_storage_enable_segment_merging)`: - `[storage.tiered.config.cloud_storage_segment_size_target](../../../../reference/properties/object-storage-properties/#cloud_storage_segment_size_target)`: The desired segment size in object storage. The default segment size is the local segment size for the topic, which is controlled by the `[storage.tiered.config.log_segment_size](../../../../reference/properties/cluster-properties/#log_segment_size)` configuration property and the `segment.bytes` topic property. You can set the `cloud_storage_segment_size_target` property to a value larger than the default segment size, but because this triggers a lot of segment re-uploads, it’s not recommended. - `[storage.tiered.config.cloud_storage_segment_size_min](../../../../reference/properties/object-storage-properties/#cloud_storage_segment_size_min)`: The smallest segment size that Redpanda keeps in object storage. The default is 50% of `[storage.tiered.config.log_segment_size](../../../../reference/properties/cluster-properties/#log_segment_size)`. If the adjacent segment merging job finds a run of small segments, it can perform one of the following operations: - Merge and re-upload a segment with a size up to `cloud_storage_segment_size_target`. - Merge and re-upload a segment with a size less than `cloud_storage_segment_size_min` if there are no other options (the run of small segments is followed by the large segment). - Wait until new segments are added if the run is at the end of the partition. Suppose the `[storage.tiered.config.cloud_storage_segment_max_upload_interval_sec](../../../../reference/properties/object-storage-properties/#cloud_storage_segment_max_upload_interval_sec)` property is set and the partition contains a large number of small segments. For example, if `sec` is set to 10 minutes and the produce rate is 1 MiB per minute, then Redpanda uploads a new 10 MiB segment every 10 minutes. If adjacent segment merging is enabled and `cloud_storage_segment_size_target` is set to 500 MiB, then every 50 segments are re-uploaded as one large 500 MiB segment. This doubles the amount of data that Redpanda uploads to object storage, but it also reduces the memory footprint of the partition, which results in better scalability because 98% less memory is needed to keep information about the uploaded segment. > 📝 **NOTE** > > Adjacent segment merging doesn’t work for compacted topics, because compacted segments are reuploaded after they’re compacted. The results are the same. ## [](#archived-metadata)Archived metadata As data in object storage grows, the metadata for it grows. Starting in version 23.2, Redpanda archives older metadata in object storage to support efficient long-term data retention. Only metadata for recently-updated segments is kept in memory or on local disk, while the rest is safely stored in object storage and cached locally as needed. Archived metadata is loaded only when historical data is accessed. This allows Tiered Storage to handle partitions of virtually any size or retention length. You can configure these object storage properties to control the metadata archiving behavior: | Property | Description | | --- | --- | | storage.tiered.config.cloud_storage_spillover_manifest_size | When the in-memory manifest size for a partition exceeds double this value, Redpanda triggers metadata spillover. The oldest metadata is packaged into a new spillover manifest and uploaded to object storage, after which the in-memory manifest is truncated. This process continues until the in-memory manifest size falls below the threshold. (Default: 65536 bytes) | | storage.tiered.config.cloud_storage_spillover_manifest_max_segments | Triggers the upload of metadata to object storage when the number of segments in the spillover manifest exceeds this value. Redpanda recommends using this property only in testing scenarios, and cloud_storage_spillover_manifest_size in production settings. (Default: null) | | storage.tiered.config.cloud_storage_manifest_cache_size | Controls the amount of memory used by the cache for spilled manifests. (Default: 1048576 bytes) | ## [](#tiered-storage-configuration-properties)Tiered Storage configuration properties The following list contains cluster-level configuration properties for Tiered Storage. Configure or verify the following properties before you use Tiered Storage: | Property | Description | | --- | --- | | storage.tiered.config.cloud_storage_enabled | Global property that enables Tiered Storage.Set to true to enable Tiered Storage. Default is false. | | storage.tiered.config.cloud_storage_region | Object storage region.Required for AWS and GCS. | | storage.tiered.config.cloud_storage_bucket | AWS or GCS bucket name.Required for AWS and GCS. | | storage.tiered.config.cloud_storage_credentials_source | AWS or GCS instance metadata.Required for AWS and GCS authentication with IAM roles. | | storage.tiered.config.cloud_storage_access_key | AWS or GCS access key.Required for AWS and GCS authentication with access keys. | | storage.tiered.config.cloud_storage_secret_key | AWS or GCS secret key.Required for AWS and GCS authentication with access keys. | | storage.tiered.config.cloud_storage_api_endpoint | AWS or GCS API endpoint.For AWS, this can be left blank. It’s generated automatically using the region and bucket.For GCS, you must use storage.googleapis.com. | | storage.tiered.config.cloud_storage_azure_container | Azure container name.Required for ABS/ADLS. | | storage.tiered.config.cloud_storage_azure_storage_account | Azure account name.Required for ABS/ADLS. | | storage.tiered.config.cloud_storage_azure_shared_key | Azure storage account access key.Required for ABS/ADLS. | | storage.tiered.config.cloud_storage_cache_size_percent | Maximum size (as a percentage) of the disk cache used by Tiered Storage.If both this property and cloud_storage_cache_size are set, Redpanda uses the minimum of the two. | | storage.tiered.config.cloud_storage_cache_size | Maximum size of the disk cache used by Tiered Storage.If both this property and cloud_storage_cache_size_percent are set, Redpanda uses the minimum of the two. | | storage.tiered.config.disk_reservation_percent | Amount of disk space (as a percentage) reserved for general system overhead.Default is 20%. | | storage.tiered.config.retention_local_target_capacity_bytes | Target size (in bytes) of the log data.Default is not set (null). | | storage.tiered.config.retention_local_target_capacity_percent | Target size (as a percentage) of the log data.Default is the amount of remaining disk space after deducting cloud_storage_cache_size_percent and disk_reservation_percent. | | storage.tiered.config.retention_local_strict | Allows the housekeeping process to remove data above the configured consumable retention. This means that data usage is allowed to expand to occupy more of the log data reservation.Default is false. | | storage.tiered.config.retention_local_trim_interval | Period at which disk usage is checked for disk pressure, where data is optionally trimmed to meet the target.Default is 30 seconds. | In addition, you might want to change the following property for each broker: | Property | Description | | --- | --- | | storage.tiered.config.cloud_storage_cache_directory | The directory for the Tiered Storage cache. You must specify the full path. Default is: /cloud_storage_cache. | You may want to configure the following properties: | Property | Description | | --- | --- | | storage.tiered.config.cloud_storage_max_connections | The maximum number of connections to object storage on a broker for each CPU. Remote read and remote write share the same pool of connections. This means that if a connection is used to upload a segment, it cannot be used to download another segment. If this value is too small, some workloads might starve for connections, which results in delayed uploads and downloads. If this value is too large, Redpanda tries to upload a lot of files at the same time and might overwhelm the system. Default is 20. | | storage.tiered.config.initial_retention_local_target_bytes_default | The initial local retention size target for partitions of topics with Tiered Storage enabled. Default is null. | | storage.tiered.config.initial_retention_local_target_ms_default | The initial local retention time target for partitions of topics with Tiered Storage enabled. Default is null. | | storage.tiered.config.cloud_storage_initial_backoff_ms | The time, in milliseconds, for an initial backoff interval in the exponential backoff algorithm to handle an error. Default is 100 ms. | | storage.tiered.config.cloud_storage_segment_upload_timeout_ms | Timeout for segment upload. Redpanda retries the upload after the timeout. Default is 30000 ms. | | storage.tiered.config.cloud_storage_manifest_upload_timeout_ms | Timeout for manifest upload. Redpanda retries the upload after the timeout. Default is 10000 ms. | | storage.tiered.config.cloud_storage_max_connection_idle_time_ms | The maximum idle time for persistent HTTP connections. Differs depending on the object storage provider. Default is 5000 ms, which is sufficient for most providers. | | storage.tiered.config.cloud_storage_segment_max_upload_interval_sec | Sets the number of seconds for idle timeout. If this property is empty, Redpanda uploads metadata to the object storage, but the segment is not uploaded until it reaches the segment.bytes size. By default, the property is empty. | | storage.tiered.config.cloud_storage_cache_check_interval_ms | The time, in milliseconds, between cache checks. The size of the cache can grow quickly, so it’s important to have a small interval between checks, but if the checks are too frequent, they consume a lot of resources. Default is 30000 ms. | | storage.tiered.config.cloud_storage_idle_timeout_ms | The width of the sliding window for the moving average algorithm that calculates object storage utilization. Default is 10 seconds. | | storage.tiered.config.cloud_storage_idle_threshold_rps | The utilization threshold for object storage housekeeping. Object storage is considered idle if, during the last 10 seconds, there were 10 or less object storage API requests. Default is 1 request per second. | | storage.tiered.config.cloud_storage_enable_segment_merging | Enables adjacent segment merging on all segments in object storage that are smaller than the threshold. Two properties control this behavior: storage.tiered.config.cloud_storage_segment_size_target and storage.tiered.config.cloud_storage_segment_size_min. Default is enabled. | | storage.tiered.config.cloud_storage_segment_size_target | The desired segment size in object storage. The default segment size is controlled by storage.tiered.config.log_segment_size and the segment.bytes topic configuration property. This property can be set to a value larger than this default segment size, but because that triggers a lot of segment reuploads, it’s not recommended. | | storage.tiered.config.cloud_storage_segment_size_min | The smallest segment size in object storage that Redpanda keeps. Default is 50% of log segment size. | Under normal circumstances, you should not need to configure the following tunable properties: | Property | Description | | --- | --- | | storage.tiered.config.cloud_storage_upload_ctrl_update_interval_ms | The recompute interval for the upload controller. Default is 60000 ms. | | storage.tiered.config.cloud_storage_upload_ctrl_p_coeff | The proportional coefficient for the upload controller. Default is -2. | | storage.tiered.config.cloud_storage_upload_ctrl_d_coeff | The derivative coefficient for the upload controller. Default is 0. | | storage.tiered.config.cloud_storage_upload_ctrl_min_shares | The minimum number of I/O and CPU shares that the remote write process can use. Default is 100. | | storage.tiered.config.cloud_storage_upload_ctrl_max_shares | The maximum number of I/O and CPU shares that the remote write process can use. Default is 1000. | | storage.tiered.config.cloud_storage_disable_tls | Disables TLS encryption. Set to true if TLS termination is done by the proxy, such as HAProxy. Default is false. | | storage.tiered.config.cloud_storage_api_endpoint_port | Overrides the default API endpoint port. Default is 443. | | storage.tiered.config.cloud_storage_trust_file | The public certificate used to validate the TLS connection to object storage. If this is empty, Redpanda uses your operating system’s CA cert pool. | | storage.tiered.config.cloud_storage_reconciliation_interval_ms | Deprecated.The interval, in milliseconds, to reconcile partitions that need to be uploaded. A long reconciliation interval can result in a delayed reaction to topic creation, topic deletion, or leadership rebalancing events. A short reconciliation interval guarantees that new partitions are picked up quickly, but the process uses more resources. Default is 10000 ms. | ## [](#suggested-reading)Suggested reading - [How we built Tiered Storage to supercharge storage and data streaming](https://www.redpanda.com/blog/tiered-storage-architecture-deep-dive) ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) [Search all labs](/redpanda-labs) --- # Page 210: Topic Recovery in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/tiered-storage/k-topic-recovery.md --- # Topic Recovery in Kubernetes --- title: Topic Recovery in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/tiered-storage/k-topic-recovery page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/tiered-storage/k-topic-recovery.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/tiered-storage/k-topic-recovery.adoc description: Restore a single topic from object storage. page-git-created-date: "2024-08-15" page-git-modified-date: "2025-07-31" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../../get-started/licensing/#self-managed) apply. When you create a topic, you can use remote recovery to download the topic data from object storage. This is useful when you need to restore a single topic in Tiered Storage that was accidentally deleted from a cluster. > ⚠️ **WARNING** > > While performing topic recovery, avoid adding additional load (such as produces, consumes, lists or additional recovery operations) to the target cluster. Doing so could destabilize the recovery process and result in either an unsuccessful or corrupted recovered topic. ## [](#prerequisites)Prerequisites You must have: - [Tiered Storage](../k-tiered-storage/) enabled on your Redpanda cluster. - [Remote read](../k-tiered-storage/#remote-read) (`redpanda.remote.read`) enabled on the topic you want to recover. ## [](#limitations)Limitations - Remote recovery is only safe when no other clusters are writing to the same bucket or container. - If you disable `redpanda.remote.read` after remote recovery, previously downloaded data will not be used to serve requests. ## [](#recover-a-topic)Recover a topic To create a new topic using remote recovery, in which the recovered topic can read and write in the cloud: ```bash rpk topic create -c redpanda.remote.recovery=true -c redpanda.remote.write=true -c redpanda.remote.read=true ``` To create a new topic using remote recovery, while also disabling the `redpanda.remote.write` property: ```bash rpk topic create -c redpanda.remote.recovery=true -c redpanda.remote.write=false -c redpanda.remote.read=true ``` ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) [Search all labs](/redpanda-labs) --- # Page 211: Whole Cluster Restore in Kubernetes **URL**: https://docs.redpanda.com/current/manage/kubernetes/tiered-storage/k-whole-cluster-restore.md --- # Whole Cluster Restore in Kubernetes --- title: Whole Cluster Restore in Kubernetes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/tiered-storage/k-whole-cluster-restore page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/tiered-storage/k-whole-cluster-restore.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/tiered-storage/k-whole-cluster-restore.adoc description: Restore a failed cluster, including its metadata. page-git-created-date: "2024-08-15" page-git-modified-date: "2025-11-19" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../../get-started/licensing/#self-managed) apply. With [Tiered Storage](../k-tiered-storage/) enabled, you can use Whole Cluster Restore to restore data from a failed cluster (source cluster you are restoring from), including its metadata, onto a new cluster (target cluster you are restoring to). This is a simpler and cheaper alternative to active-active replication, for example with [MirrorMaker 2](../../../../migrate/data-migration/). Use this recovery method to restore your application to the latest functional state as quickly as possible. > ⚠️ **CAUTION** > > Whole Cluster Restore is not a fully-functional disaster recovery solution. It does not provide snapshot-style consistency. Some partitions in some topics will be more up-to-date than others. Committed transactions are not guaranteed to be atomic. > 💡 **TIP** > > If you need to restore only a subset of topic data, consider using [topic recovery](../../../disaster-recovery/topic-recovery/) instead of a Whole Cluster Restore. The following metadata is included in a Whole Cluster Restore: - Topic definitions. If you have enabled Tiered Storage only for specific topics, topics without Tiered Storage enabled will be restored empty. - Users and access control lists (ACLs). - [Schemas](../../../schema-reg/schema-reg-overview/). To ensure that your schemas are also archived and restored, you must also enable Tiered Storage for the `_schemas` topic. - The [consumer offsets topic](../../../../develop/consume-data/consumer-offsets/). Some restored committed consumer offsets may be truncated to a lower value than in the original cluster, to keep offsets at or below the highest restored offset in the partition. - Transaction metadata, up to the highest committed transaction. In-flight transactions are treated as aborted and will not be included in the restore. - [Cluster configurations](../../../../reference/properties/cluster-properties/), including your Redpanda license key, with the exception of the following properties: - `cloud_storage_cache_size` - `cluster_id` - `cloud_storage_access_key` - `cloud_storage_secret_key` - `cloud_storage_region` - `cloud_storage_bucket` - `cloud_storage_api_endpoint` - `cloud_storage_credentials_source` - `cloud_storage_trust_file` - `cloud_storage_backend` - `cloud_storage_credentials_host` - `cloud_storage_azure_storage_account` - `cloud_storage_azure_container` - `cloud_storage_azure_shared_key` - `cloud_storage_azure_adls_endpoint` - `cloud_storage_azure_adls_port` ## [](#manage-source-metadata-uploads)Manage source metadata uploads By default, Redpanda uploads cluster metadata to object storage periodically. You can manage metadata uploads for your source cluster, or disable them entirely, with the following cluster configuration properties: - [`enable_cluster_metadata_upload_loop`](../../../../reference/properties/cluster-properties/#enable_cluster_metadata_upload_loop): Enable metadata uploads. This property is enabled by default and is required for Whole Cluster Restore. - [`cloud_storage_cluster_metadata_upload_interval_ms`](../../../../reference/properties/object-storage-properties/#cloud_storage_cluster_metadata_upload_interval_ms): Set the time interval to wait between metadata uploads. - [`controller_snapshot_max_age_sec`](../../../../reference/properties/cluster-properties/#controller_snapshot_max_age_sec): Maximum amount of time that can pass before Redpanda attempts to take a controller snapshot after a new controller command appears. This property affects how current the uploaded metadata can be. - [`cloud_storage_cluster_name`](../../../../reference/properties/object-storage-properties/#cloud_storage_cluster_name): This is an internal-only configuration and should be enabled only after consulting with Redpanda support. Specify a custom name for cluster’s metadata in object storage. For use when multiple clusters share the same storage bucket (for example, for Whole Cluster Restore). > 📝 **NOTE** > > You can monitor the [redpanda\_cluster\_latest\_cluster\_metadata\_manifest\_age](../../../../reference/public-metrics-reference/#redpanda_cluster_latest_cluster_metadata_manifest_age) metric to track the age of the most recent metadata upload. ## [](#restore-data-from-a-source-cluster)Restore data from a source cluster To restore data from a source cluster: 1. [Start a target cluster](#start-a-target-cluster) (new cluster) with cluster restore enabled. 2. [Verify that the cluster restore is complete](#verify-that-the-cluster-restore-is-complete). ### [](#prerequisites)Prerequisites You must have the following: - Redpanda v23.3 or later on both source and target clusters. - [Tiered Storage](../k-tiered-storage/) enabled on the source cluster. - Physical or virtual machines on which to deploy the target cluster. ### [](#limitations)Limitations - You cannot use Whole Cluster Restore if the target cluster is in [recovery mode](../k-recovery-mode/). - Whole Cluster Restore supports only one source cluster. It is not possible to consolidate multiple clusters onto the target cluster. - If a duplicate cluster configuration is found in the target cluster, it will be overwritten by the restore. - The target cluster should not contain user-managed or application-managed topic data, schemas, users, ACLs, or ongoing transactions. ### [](#start-a-target-cluster)Start a target cluster Deploy the target Redpanda cluster. #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: storage: tiered: config: cluster: cloud_storage_attempt_cluster_restore_on_bootstrap: true ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `cluster-restore.yaml` ```yaml storage: tiered: config: cluster: cloud_storage_attempt_cluster_restore_on_bootstrap: true ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values cluster-restore.yaml ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set storage.tiered. \ --set config.cluster.cloud_storage_attempt_cluster_restore_on_bootstrap=true ``` - `storage.tiered`: Make sure to configure the target cluster with the same Tiered Storage settings as the failed source cluster. - `config.cluster.cloud_storage_attempt_cluster_restore_on_bootstrap`: Automate cluster restore in Kubernetes. Setting to `true` is recommended when using an automated method for deployment. When bootstrapping a cluster with a given bucket, make sure that any previous cluster using the bucket is fully destroyed, otherwise Tiered Storage subsystems may interfere with each other. > 💡 **TIP** > > Starting in Redpanda Operator v25.1.1, you can configure object storage settings using `config.extraClusterConfiguration`. This lets you securely reference sensitive values from Kubernetes Secrets or ConfigMaps, and reuse values like your bucket name across multiple features, such as Tiered Storage, Iceberg, and topic recovery. > > See [Set Redpanda cluster properties from Kubernetes Secrets or ConfigMaps](../../k-configure-helm-chart/#extra-cluster-config). ### [](#verify-that-the-cluster-restore-is-complete)Verify that the cluster restore is complete 1. Run the following command until it returns `inactive`: ```bash rpk cluster storage restore status ``` 2. Check if a rolling restart is required: ```bash rpk cluster config status ``` Example output when a restart is required: ```bash NODE CONFIG-VERSION NEEDS-RESTART INVALID UNKNOWN 1 4 true [] [] ``` 3. If a restart is required, perform a [rolling restart](../../k-rolling-restart/). When the cluster restore is successfully completed, you can redirect your application workload to the new cluster. Make sure to update your application code to use the new addresses of your brokers. ## [](#restore-data-from-multiple-clusters-sharing-the-same-bucket)Restore data from multiple clusters sharing the same bucket > ⚠️ **CAUTION** > > This is an advanced use case that should be performed only after consulting with Redpanda support. Typically, you will have a one-to-one mapping between a Redpanda cluster and its object storage bucket. However, it’s possible to run multiple clusters that share the same storage bucket. Sharing an object storage bucket allows you to move tenants between clusters without moving data. For example, you might wish to move topics (unmount on cluster A, mount on cluster B) to multiple clusters in the same bucket without having to move data. Running multiple clusters that share the same storage bucket presents unique challenges during Whole Cluster Restore operations. To manage these challenges, you must understand how Redpanda uses [UUIDs](#the-role-of-cluster-uuids-in-whole-cluster-restore) (universally unique identifiers) to identify clusters during a Whole Cluster Restore. This shared storage approach can create identification challenges during restore operations. ### [](#the-role-of-cluster-uuids-in-whole-cluster-restore)The role of cluster UUIDs in Whole Cluster Restore Each Redpanda cluster (single node or more) receives a unique UUID every time it starts. From that moment forward, all entities created by the cluster are identifiable using this cluster UUID. These entities include: - Topic data - Topic metadata - Whole Cluster Restore manifests - Controller log snapshots for Whole Cluster Restore - Consumer offsets for Whole Cluster Restore However, not all entities _managed_ by the cluster are identifiable using this cluster UUID. Each time a cluster uploads its metadata, the name of the object has two parts: the cluster UUID, which is unique each time you create a cluster (even after a restore it will have a new UUID), and a metadata (sequence) ID. When performing a restore, Redpanda scans the bucket to find the highest-sequenced ID uploaded by the cluster. It can be ambiguous what to restore when the highest sequential ID has been uploaded by another cluster, and result in a split-brain scenario, where you have two independent clusters that both believe they are the “rightful owner” of the same logical data. ### [](#configure-cluster-names-for-multiple-source-clusters)Configure cluster names for multiple source clusters To disambiguate cluster metadata from multiple clusters, use the [`cloud_storage_cluster_name`](../../../../reference/properties/object-storage-properties/#cloud_storage_cluster_name) property (off by default), which allows you to assign a unique name to each cluster sharing the same object storage bucket. Redpanda uses this name to organize the cluster metadata within the shared object storage bucket. This ensures that each cluster’s data remains distinct and prevents conflicts during recovery operations.The name must be unique within the bucket, 1-64 characters, and use only letters, numbers, underscores, and hyphens. Do not change this value once set. After setting, your object storage bucket organization may look like the following: ```bash / +- cluster_metadata/ | + /manifests/ | | +- 0/cluster_manifest.json | | +- 1/cluster_manifest.json | | +- 2/cluster_manifest.json | + /manifests/ | +- 0/cluster_manifest.json | +- 1/cluster_manifest.json # lost cluster +- cluster_name/ +- rp-foo/uuid/ +- rp-qux/uuid/ ``` During a Whole Cluster Restore, Redpanda looks for the cluster name specified in `cloud_storage_cluster_name` and only consider manifests associated with that name. Because the cluster name specified here is `rp-qux`, Redpanda only considers manifests for the clusters `` and `` (another new cluster sharing the bucket), ignoring cluster `` entirely. In this case, your object storage bucket may look like the following: ```bash +- cluster_metadata/ | + /manifests/ | | +- 0/cluster_manifest.json | | +- 1/cluster_manifest.json | | +- 2/cluster_manifest.json | + /manifests/ | | +- 0/cluster_manifest.json | | +- 1/cluster_manifest.json # lost cluster | + /manifests/ | +- 3/cluster_manifest.json # new cluster | # ^- next highest sequence number globally +- cluster_name/ +- rp-foo/uuid/ +- rp-qux/uuid/ +- +- # reference to new cluster ``` ### [](#resolve-repeated-recovery-failures)Resolve repeated recovery failures If you experience repeated failures when a cluster is lost and recreated, the automated recovery algorithm may have selected the manifest with the highest sequence number, which might be the most recent one with no data, instead of the original one containing the data. In such a scenario, your object storage bucket might be organized like the following: ```bash / +- cluster_metadata/ + /manifests/ | +- 0/cluster_manifest.json | +- 1/cluster_manifest.json #lost cluster + /manifests/ +- 3/cluster_manifest.json # lost again (not recovered) + /manifests/ +- 7/cluster_manifest.json # new attempt to recover uuid-b # it does not have the data ``` In such cases, you can explicitly specify the cluster UUID: #### rpk The `--cluster-uuid-override` option is available in v25.3.3 and later: ```bash rpk cluster storage restore start --cluster-uuid-override ``` #### Admin API ```bash curl -XPOST \ --data '{"cluster_uuid_override": ""}' \ http://localhost:9644/v1/cloud_storage/automated_recovery ``` For details, see the [Admin API reference](../../../use-admin-api/). --- # Page 212: Monitor Redpanda **URL**: https://docs.redpanda.com/current/manage/monitoring.md --- # Monitor Redpanda --- title: Monitor Redpanda latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: monitoring page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: monitoring.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/monitoring.adoc description: Metrics to monitor the health of your system to predict issues and optimize performance. page-git-created-date: "2023-05-30" page-git-modified-date: "2025-07-31" support-status: supported --- Redpanda exports metrics through two endpoints on the Admin API port (default: 9644) for you to monitor system health and optimize system performance. > 💡 **TIP** > > Use [/public\_metrics](../../reference/public-metrics-reference/) for your primary dashboards for monitoring system health. These metrics have low cardinality and are designed for customer consumption, with aggregated labels for better performance. **Public metrics use the `redpanda_` prefix.** > > Use [/metrics](../../reference/internal-metrics-reference/) for detailed analysis and debugging. These metrics can have high cardinality with thousands of series, providing granular operational insights. **Internal metrics use the `vectorized_` prefix.** The [`/metrics`](../../reference/internal-metrics-reference/) endpoint is a legacy endpoint that includes many internal metrics that are unnecessary for a typical Redpanda user to monitor. The `/metrics` endpoint is also referred to as the 'internal metrics' endpoint, and Redpanda recommends that you use it for development, testing, and analysis. Alternatively, the [`/public_metrics`](../../reference/public-metrics-reference/) endpoint provides a smaller set of important metrics that can be queried and ingested more quickly and inexpensively. > 📝 **NOTE** > > To maximize monitoring performance by minimizing the cardinality of data, some metrics are exported when their underlying features are in use, and are not exported when not in use. For example, a metric for consumer groups, [`redpanda_kafka_consumer_group_committed_offset`](../../reference/public-metrics-reference/#redpanda_kafka_consumer_group_committed_offset), is not exported when no groups are registered. > > When monitoring internal metrics, consider enabling [aggregate\_metrics](../../reference/properties/cluster-properties/#aggregate_metrics) to reduce the cardinality of data to monitor. This topic covers the following about monitoring Redpanda metrics: - [Configure Prometheus to monitor Redpanda metrics](#configure-prometheus) - [Generate Grafana dashboard](#generate-grafana-dashboard) - [Learn from examples in the Redpanda monitoring examples repository](#use-redpanda-monitoring-examples) - [Metrics and queries to monitor for system performance and health](#monitor-for-performance-and-health) - [References of public and internal metrics](#references) ## [](#configure-prometheus)Configure Prometheus [Prometheus](https://prometheus.io/) is a system monitoring and alerting tool. It collects and stores metrics as time-series data identified by a metric name and key/value pairs. To configure and use Prometheus to monitor Redpanda metrics: 1. Generate the configuration on an existing Prometheus instance. - For public metrics, run the command: ```bash rpk generate prometheus-config ``` - For internal metrics, run the command: ```bash rpk generate prometheus-config --internal-metrics ``` > 📝 **NOTE** > > When you run the command on a Redpanda broker, it displays other available brokers. To run the command on a machine that is not running Redpanda, you can either set the `--seed-addr` flag to specify a remote Redpanda broker to discover the additional brokers, or set `--node-addrs` with a comma-separated list of known broker addresses. For example, use `--node-addrs`: > > ```bash > rpk generate prometheus-config --job-name redpanda-metrics-test --node-addrs 172.31.18.239:9644,172.31.18.239:9643,172.31.18.239:9642 > ``` 2. Edit the `prometheus.yml` file in the Prometheus root folder to add the Redpanda configuration under `scrape_configs`. Customize `targets` for the names and number of running brokers. ```yaml scrape_configs: - job_name: redpanda-metrics-test static_configs: - targets: - redpanda-0:9644 - redpanda-1:9644 - redpanda-2:9644 metrics_path: /public_metrics ``` 3. Save the configuration file, and restart Prometheus to apply changes. 4. Observe in Prometheus that metrics from Redpanda endpoints are scraped. ## [](#generate-grafana-dashboard)Generate Grafana dashboard [Grafana](https://grafana.com/oss/grafana/) is a tool to query, visualize, and generate alerts for metrics. Redpanda supports generating Grafana dashboards from its metrics endpoints with `rpk generate grafana-dashboard`. To generate a comprehensive Grafana dashboard, run the following command and pipe the output to a file that can be imported into Grafana: ```bash rpk generate grafana-dashboard --datasource --metrics-endpoint > ``` - `` is the name of the Prometheus data source configured in your Grafana instance. - `` is the address to a Redpanda broker’s metrics endpoint (public or internal). - For `/public_metrics`, for example, run the following command: ```bash rpk generate grafana-dashboard \ --datasource prometheus \ --metrics-endpoint :9644/public_metrics > redpanda-dashboard.json ``` - For `/metrics`, for example, run the following command: ```bash rpk generate grafana-dashboard \ --datasource prometheus \ --metrics-endpoint :9644/metrics > redpanda-dashboard.json ``` For details about the command, see [`rpk generate grafana-dashboard`](../../reference/rpk/rpk-generate/rpk-generate-grafana-dashboard/). In Grafana, import the generated JSON file to create a dashboard. Out of the box, Grafana generates panels tracking latency for 50%, 95%, and 99% (based on the maximum latency set), throughput, and error segmentation by type. To use the imported dashboard to create new panels: 1. Click **+** in the left pane, and select **Add a new panel**. 2. On the **Query** tab, select **Prometheus** data source. 3. Decide which metric you want to monitor, click **Metrics browser**, and type `redpanda` to show available public metrics (or `vectorized` for internal metrics) from the Redpanda cluster. ## [](#use-redpanda-monitoring-examples)Use Redpanda monitoring examples For hands-on learning, Redpanda provides a repository with examples of monitoring Redpanda with Prometheus and Grafana: [redpanda-data/observability](https://github.com/redpanda-data/observability). ![Example Redpanda Ops Dashboard^](https://github.com/redpanda-data/observability/blob/main/docs/images/Ops%20Dashboard.png?raw=true) It includes [example Grafana dashboards](https://github.com/redpanda-data/observability#grafana-dashboards) and a [sandbox environment](https://github.com/redpanda-data/observability#sandbox-environment) in which you launch a Dockerized Redpanda cluster and create a custom workload to monitor with dashboards. ## [](#monitor-for-performance-and-health)Monitor for performance and health This section provides guidelines and example queries using Redpanda’s public metrics to optimize your system’s performance and monitor its health. To help detect and mitigate anomalous system behaviors, capture baseline metrics of your healthy system at different stages (at start-up, under high load, in steady state) so you can set thresholds and alerts according to those baselines. > 💡 **TIP** > > For counter type metrics, a broker restart causes the count to reset to zero in tools like Prometheus and Grafana. Redpanda recommends wrapping counter metrics in a rate query to account for broker restarts, for example: > > ```promql > rate(redpanda_kafka_records_produced_total[5m]) > ``` ### [](#redpanda-architecture)Redpanda architecture Understanding the unique aspects of Redpanda’s architecture and data path can improve your performance, debugging, and tuning skills: - Redpanda replicates partitions across brokers in a cluster using [Raft](https://raft.github.io/), where each partition is a Raft consensus group. A message written from the Kafka API flows down to the Raft implementation layer that eventually directs it to a broker to be stored. Metrics about the Raft layer can reveal the health of partitions and data flowing within Redpanda. - Redpanda is designed with a [thread-per-core](https://docs.redpanda.com/current/reference/glossary/#thread-per-core) model that it implements with the [Seastar](https://seastar.io/) library. With each application thread pinned to a CPU core, when observing or analyzing the behavior of a specific application, monitor the relevant metrics with the label for the specific [shard](https://docs.redpanda.com/current/reference/glossary/#shard), if available. ### [](#infrastructure-resources)Infrastructure resources The underlying infrastructure of your system should have sufficient margins to handle peaks in processing, storage, and I/O loads. Monitor infrastructure health with the following queries. #### [](#cpu-usage)CPU usage For the total CPU uptime, monitor [`redpanda_uptime_seconds_total`](../../reference/public-metrics-reference/#redpanda_uptime_seconds_total). Monitoring its rate of change with the following query can help detect unexpected dips in uptime: ```promql rate(redpanda_uptime_seconds_total[5m]) ``` For the total CPU busy (non-idle) time, monitor [`redpanda_cpu_busy_seconds_total`](../../reference/public-metrics-reference/#redpanda_cpu_busy_seconds_total). To detect unexpected idling, you can query the rate of change as a fraction of the shard that is in use at a given point in time. ```promql rate(redpanda_cpu_busy_seconds_total[5m]) ``` > 💡 **TIP** > > While CPU utilization at the host-level might appear high (for example, 99-100% utilization) when I/O events like message arrival occur, the actual Redpanda process utilization is likely low. System-level metrics such as those provided by the `top` command can be misleading. > > This high host-level CPU utilization happens because Redpanda uses Seastar, which runs event loops on every core (also referred to as a _reactor_), constantly polling for the next task. This process never blocks and will increment clock ticks. It doesn’t necessarily mean that Redpanda is busy. > > Use [`redpanda_cpu_busy_seconds_total`](../../reference/public-metrics-reference/#redpanda_cpu_busy_seconds_total) to monitor the actual Redpanda CPU utilization. When it indicates close to 100% utilization over a given period of time, make sure to also monitor produce and consume [latency](#latency) as they may then start to increase as a result of resources becoming overburdened. #### [](#memory-availability-and-pressure)Memory availability and pressure To monitor memory, use [`redpanda_memory_available_memory`](../../reference/public-metrics-reference/#redpanda_memory_available_memory), which includes both free memory and reclaimable memory from the batch cache. This provides a more accurate picture than using allocated memory alone, since allocated does not include reclaimable cache memory. To monitor the fraction of memory available: ```promql min(redpanda_memory_available_memory / (redpanda_memory_free_memory + redpanda_memory_allocated_memory)) ``` To monitor memory pressure (fraction of memory being used), which may be more intuitive for alerting: ```promql min(redpanda_memory_available_memory / redpanda_memory_allocated_memory) ``` You can also monitor the lowest available memory available since the process started to understand historical memory pressure: ```promql min(redpanda_memory_available_memory_low_water_mark / (redpanda_memory_free_memory + redpanda_memory_allocated_memory)) ``` #### [](#disk-used)Disk used To monitor the fraction of disk consumed, use a formula with [`redpanda_storage_disk_free_bytes`](../../reference/public-metrics-reference/#redpanda_storage_disk_free_bytes) and [`redpanda_storage_disk_total_bytes`](../../reference/public-metrics-reference/#redpanda_storage_disk_total_bytes): ```promql 1 - (sum(redpanda_storage_disk_free_bytes) / sum(redpanda_storage_disk_total_bytes)) ``` Also monitor [`redpanda_storage_disk_free_space_alert`](../../reference/public-metrics-reference/#redpanda_storage_disk_free_space_alert) for an alert when available disk space is low or degraded. #### [](#iops)IOPS For read and write I/O operations per second (IOPS), monitor the [`redpanda_io_queue_total_read_ops`](../../reference/public-metrics-reference/#redpanda_io_queue_total_read_ops) and [`redpanda_io_queue_total_write_ops`](../../reference/public-metrics-reference/#redpanda_io_queue_total_write_ops) counters: ```promql rate(redpanda_io_queue_total_read_ops[5m]), rate(redpanda_io_queue_total_write_ops[5m]) ``` ### [](#throughput)Throughput While maximizing the rate of messages moving from producers to brokers then to consumers depends on tuning each of those components, the total throughput of all topics provides a system-level metric to monitor. When you observe abnormal, unhealthy spikes or dips in producer or consumer throughput, look for correlation with changes in the number of active connections ([`redpanda_rpc_active_connections`](../../reference/public-metrics-reference/#redpanda_rpc_active_connections)) and logged errors to drill down to the root cause. The total throughput of a cluster can be measured by the producer and consumer rates across all topics. To observe the total producer and consumer rates of a cluster, monitor [`redpanda_rpc_received_bytes`](../../reference/public-metrics-reference/#redpanda_rpc_received_bytes) for producer traffic and [`redpanda_rpc_sent_bytes`](../../reference/public-metrics-reference/#redpanda_rpc_sent_bytes) for consumer traffic. Filter both metrics using the `redpanda_server` label with the value `kafka`. #### [](#producer-throughput)Producer throughput For the produce rate, create a query to get the produce rate across all topics: ```promql rate(redpanda_rpc_received_bytes{redpanda_server="kafka"}[$__rate_interval]) ``` #### [](#consumer-throughput)Consumer throughput For the consume rate, create a query to get the total consume rate across all topics: ```promql rate(redpanda_rpc_sent_bytes{redpanda_server="kafka"}[$__rate_interval]) ``` #### [](#identify-high-throughput-clients)Identify high-throughput clients Use [`rpk cluster connections list`](../../reference/rpk/rpk-cluster/rpk-cluster-connections-list/) or the [ListKafkaConnections](/api/doc/admin/v2/operation/operation-redpanda-core-admin-v2-clusterservice-listkafkaconnections) endpoint in Admin API to identify which client connections are driving the majority of, or the change in, the produce or consume throughput for a cluster. For example, to list connections with a current produce throughput greater than 1MB, run: ##### rpk ```bash rpk cluster connections list --filter-raw="recent_request_statistics.produce_bytes > 1000000" --order-by="recent_request_statistics.produce_bytes desc" ``` ```bash UID STATE USER CLIENT-ID IP:PORT NODE SHARD OPEN-TIME IDLE PROD-TPUT/SEC FETCH-TPUT/SEC REQS/MIN b20601a3-624c-4a8c-ab88-717643f01d56 OPEN UNAUTHENTICATED perf-producer-client 127.0.0.1:55012 0 0 9s 0s 78.9MB 0B 292 ``` ##### curl ```bash curl -s -X POST "localhost:9644/redpanda.core.admin.v2.ClusterService/ListKafkaConnections" --header "Content-Type: application/json" --data '{"filter":"recent_request_statistics.produce_bytes > 1000000", "order_by":"recent_request_statistics.produce_bytes desc"}' | jq ``` Show example API response ```bash { "connections": [ { "nodeId": 0, "shardId": 0, "uid": "b20601a3-624c-4a8c-ab88-717643f01d56", "state": "KAFKA_CONNECTION_STATE_OPEN", "openTime": "2025-10-15T14:15:15.755065000Z", "closeTime": "1970-01-01T00:00:00.000000000Z", "authenticationInfo": { "state": "AUTHENTICATION_STATE_UNAUTHENTICATED", "mechanism": "AUTHENTICATION_MECHANISM_UNSPECIFIED", "userPrincipal": "" }, "listenerName": "", "tlsInfo": { "enabled": false }, "source": { "ipAddress": "127.0.0.1", "port": 55012 }, "clientId": "perf-producer-client", "clientSoftwareName": "apache-kafka-java", "clientSoftwareVersion": "3.9.0", "transactionalId": "my-tx-id", "groupId": "", "groupInstanceId": "", "groupMemberId": "", "apiVersions": { "18": 4, "22": 3, "3": 12, "24": 3, "0": 7 }, "idleDuration": "0s", "inFlightRequests": { "sampledInFlightRequests": [ { "apiKey": 0, "inFlightDuration": "0.000406892s" } ], "hasMoreRequests": false }, "totalRequestStatistics": { "produceBytes": "78927173", "fetchBytes": "0", "requestCount": "4853", "produceBatchCount": "4849" }, "recentRequestStatistics": { "produceBytes": "78927173", "fetchBytes": "0", "requestCount": "4853", "produceBatchCount": "4849" } } ] } ``` You can adjust the filter and sorting criteria as necessary. ### [](#latency)Latency Latency should be consistent between produce and fetch sides. It should also be consistent over time. Take periodic snapshots of produce and fetch latencies, including at upper percentiles (95%, 99%), and watch out for significant changes over a short duration. In Redpanda, the latency of produce and fetch requests includes the latency of inter-broker RPCs that are born from Redpanda’s internal implementation using Raft. #### [](#kafka-consumer-latency)Kafka consumer latency To monitor Kafka consumer request latency, use the [`redpanda_kafka_request_latency_seconds`](../../reference/public-metrics-reference/#redpanda_kafka_request_latency_seconds) histogram with the label `redpanda_request="consume"`. For example, create a query for the 99th percentile: ```promql histogram_quantile(0.99, sum(rate(redpanda_kafka_request_latency_seconds_bucket{redpanda_request="consume"}[5m])) by (le, provider, region, instance, namespace, pod)) ``` You can monitor the rate of Kafka consumer requests using `redpanda_kafka_request_latency_seconds_count` with the `redpanda_request="consume"` label: rate(redpanda\_kafka\_request\_latency\_seconds\_count{redpanda\_request="consume"}\[5m\]) #### [](#kafka-producer-latency)Kafka producer latency To monitor Kafka producer request latency, use the [`redpanda_kafka_request_latency_seconds`](../../reference/public-metrics-reference/#redpanda_kafka_request_latency_seconds) histogram with the `redpanda_request="produce"` label. For example, create a query for the 99th percentile: ```promql histogram_quantile(0.99, sum(rate(redpanda_kafka_request_latency_seconds_bucket{redpanda_request="produce"}[5m])) by (le, provider, region, instance, namespace, pod)) ``` You can monitor the rate of Kafka producer requests with `redpanda_kafka_request_latency_seconds_count` with the `redpanda_request="produce"` label: ```promql rate(redpanda_kafka_request_latency_seconds_count{redpanda_request="produce"}[5m]) ``` #### [](#internal-rpc-latency)Internal RPC latency To monitor Redpanda internal RPC latency, use the [`redpanda_rpc_request_latency_seconds`](../../reference/public-metrics-reference/#redpanda_rpc_request_latency_seconds) histogram with the `redpanda_server="internal"` label. For example, create a query for the 99th percentile latency: ```promql histogram_quantile(0.99, (sum(rate(redpanda_rpc_request_latency_seconds_bucket{redpanda_server="internal"}[5m])) by (le, provider, region, instance, namespace, pod))) ``` You can monitor the rate of internal RPC requests with [`redpanda_rpc_request_latency_seconds`](../../reference/public-metrics-reference/#redpanda_rpc_request_latency_seconds) histogram’s count: ```promql rate(redpanda_rpc_request_latency_seconds_count[5m]) ``` ### [](#partition-health)Partition health The health of Kafka partitions often reflects the health of the brokers that host them. Thus, when alerts occur for conditions such as under-replicated partitions or more frequent leadership transfers, check for unresponsive or unavailable brokers. With Redpanda’s internal implementation of the Raft consensus protocol, the health of partitions is also reflected in any errors in the internal RPCs exchanged between Raft peers. #### [](#leadership-changes)Leadership changes Stable clusters have a consistent balance of leaders across all brokers, with few to no leadership transfers between brokers. To observe changes in leadership, monitor the [`redpanda_raft_leadership_changes`](../../reference/public-metrics-reference/#redpanda_raft_leadership_changes) counter. For example, use a query to get the total rate of increase of leadership changes for a cluster: ```promql sum(rate(redpanda_raft_leadership_changes[5m])) ``` #### [](#under-replicated-partitions)Under-replicated partitions A healthy cluster has partition data fully replicated across its brokers. An under-replicated partition is at higher risk of data loss. It also adds latency because messages must be replicated before being committed. To know when a partition isn’t fully replicated, create an alert for the [`redpanda_kafka_under_replicated_replicas`](../../reference/public-metrics-reference/#redpanda_kafka_under_replicated_replicas) gauge when it is greater than zero: ```promql redpanda_kafka_under_replicated_replicas > 0 ``` Under-replication can be caused by unresponsive brokers. When an alert on `redpanda_kafka_under_replicated_replicas` is triggered, identify the problem brokers and examine their logs. #### [](#leaderless-partitions)Leaderless partitions A healthy cluster has a leader for every partition. A partition without a leader cannot exchange messages with producers or consumers. To identify when a partition doesn’t have a leader, create an alert for the [`redpanda_cluster_unavailable_partitions`](../../reference/public-metrics-reference/#redpanda_cluster_unavailable_partitions) gauge when it is greater than zero: ```promql redpanda_cluster_unavailable_partitions > 0 ``` Leaderless partitions can be caused by unresponsive brokers. When an alert on `redpanda_cluster_unavailable_partitions` is triggered, identify the problem brokers and examine their logs. #### [](#raft-rpcs)Raft RPCs Redpanda’s Raft implementation exchanges periodic status RPCs between a broker and its peers. The [`redpanda_node_status_rpcs_timed_out`](../../reference/public-metrics-reference/#redpanda_node_status_rpcs_timed_out) gauge increases when a status RPC times out for a peer, which indicates that a peer may be unresponsive and may lead to problems with partition replication that Raft manages. Monitor for non-zero values of this gauge, and correlate it with any logged errors or changes in partition replication. ### [](#consumers)Consumer group lag Consumer group lag is an important performance indicator that measures the difference between the broker’s latest (max) offset and the consumer group’s last committed offset. The lag indicates how current the consumed data is relative to real-time production. A high or increasing lag means that consumers are processing messages slower than producers are generating them. A decreasing or stable lag implies that consumers are keeping pace with producers, ensuring real-time or near-real-time data consumption. By monitoring consumer lag, you can identify performance bottlenecks and make informed decisions about scaling consumers, tuning configurations, and improving processing efficiency. A high maximum lag may indicate that a consumer is experiencing connectivity problems or cannot keep up with the incoming workload. A high or increasing total lag (lag sum) suggests that the consumer group lacks sufficient resources to process messages at the rate they are produced. In such cases, scaling the number of consumers within the group can help, but only up to the number of partitions available in the topic. If lag persists despite increasing consumers, repartitioning the topic may be necessary to distribute the workload more effectively and improve processing efficiency. Redpanda provides the following methods for monitoring consumer group lag: - [Dedicated gauges](#dedicated-gauges): Redpanda brokers can internally calculate consumer group lag and expose two dedicated gauges. This method is recommended for environments where your observability platform does not support complex queries required to calculate the lag from offset metrics. Enabling these gauges may add a small amount of additional processing overhead to the brokers. - [Offset-based calculation](#offset-based-calculation): You can use your observability platform to calculate consumer group lag from offset metrics. Use this method if your observability platform supports functions, such as `max()`, and you prefer to avoid additional processing overhead on the broker. #### [](#dedicated-gauges)Dedicated gauges Redpanda can internally calculate consumer group lag and expose it as two dedicated gauges. - [`redpanda_kafka_consumer_group_lag_max`](../../reference/public-metrics-reference/#redpanda_kafka_consumer_group_lag_max): Reports the maximum lag observed among all partitions for a consumer group. This metric helps pinpoint the partition with the greatest delay, indicating potential performance or configuration issues. - [`redpanda_kafka_consumer_group_lag_sum`](../../reference/public-metrics-reference/#redpanda_kafka_consumer_group_lag_sum): Aggregates the lag across all partitions, providing an overall view of data consumption delay for the consumer group. To enable these dedicated gauges, you must enable consumer group metrics in your cluster properties. Add the following to your Redpanda configuration: - [`enable_consumer_group_metrics`](../../reference/properties/cluster-properties/#enable_consumer_group_metrics): A list of properties to enable for consumer group metrics. You must add the `consumer_lag` property to enable consumer group lag metrics. - [`consumer_group_lag_collection_interval_sec`](../../reference/properties/cluster-properties/#consumer_group_lag_collection_interval_sec) (optional): The interval in seconds for collecting consumer group lag metrics. The default is 60 seconds. Set this value equal to the scrape interval of your metrics collection system. Aligning these intervals ensures synchronized data collection, reducing the likelihood of missing or misaligned lag measurements. For example: ```bash rpk cluster config set enable_consumer_group_metrics '["group", "partition", "consumer_lag"]' ``` When these properties are enabled, Redpanda computes and exposes the `redpanda_kafka_consumer_group_lag_max` and `redpanda_kafka_consumer_group_lag_sum` gauges to the `/public_metrics` endpoint. #### [](#offset-based-calculation)Offset-based calculation If your environment is sensitive to the performance overhead of the [dedicated gauges](#dedicated-gauges), use the offset-based calculation method to calculate consumer group lag. This method requires your observability platform to support functions like `max()`. Redpanda provides two metrics to calculate consumer group lag: - [`redpanda_kafka_max_offset`](../../reference/public-metrics-reference/#redpanda_kafka_max_offset): The broker’s latest offset for a partition. - [`redpanda_kafka_consumer_group_committed_offset`](../../reference/public-metrics-reference/#redpanda_kafka_consumer_group_committed_offset): The last committed offset for a consumer group on that partition. For example, here’s a typical query to compute consumer lag: ```promql max by(redpanda_namespace, redpanda_topic, redpanda_partition)(redpanda_kafka_max_offset{redpanda_namespace="kafka"}) - on(redpanda_topic, redpanda_partition) group_right max by(redpanda_group, redpanda_topic, redpanda_partition)(redpanda_kafka_consumer_group_committed_offset) ``` ### [](#services)Services Monitor the health of specific Redpanda services with the following metrics. #### [](#schema-registry)Schema Registry Schema Registry request latency: ```promql histogram_quantile(0.99, (sum(rate(redpanda_schema_registry_request_latency_seconds_bucket[5m])) by (le, provider, region, instance, namespace, pod))) ``` Schema Registry request rate: ```promql rate(redpanda_schema_registry_request_latency_seconds_count[5m]) + sum without(redpanda_status)(rate(redpanda_schema_registry_request_errors_total[5m])) ``` Schema Registry request error rate: ```promql rate(redpanda_schema_registry_request_errors_total[5m]) ``` #### [](#rest-proxy)REST proxy REST proxy request latency: ```promql histogram_quantile(0.99, (sum(rate(redpanda_rest_proxy_request_latency_seconds_bucket[5m])) by (le, provider, region, instance, namespace, pod))) ``` REST proxy request rate: ```promql rate(redpanda_rest_proxy_request_latency_seconds_count[5m]) + sum without(redpanda_status)(rate(redpanda_rest_proxy_request_errors_total[5m])) ``` REST proxy request error rate: ```promql rate(redpanda_rest_proxy_request_errors_total[5m]) ``` ### [](#data-transforms)Data transforms See [Monitor Data Transforms](../../develop/data-transforms/monitor/). ## [](#references)References - [Public Metrics Reference](../../reference/public-metrics-reference/) - [Internal Metrics Reference](../../reference/internal-metrics-reference/) - [Redpanda monitoring examples repository](https://github.com/redpanda-data/observability) ## Suggested labs - [Owl Shop Example Application in Docker](/redpanda-labs/docker-compose/owl-shop/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) [Search all labs](/redpanda-labs) --- # Page 213: Mountable Topics **URL**: https://docs.redpanda.com/current/manage/mountable-topics.md --- # Mountable Topics --- title: Mountable Topics latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: mountable-topics page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: mountable-topics.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/mountable-topics.adoc description: Safely attach and detach Tiered Storage topics to and from a Redpanda cluster. page-git-created-date: "2024-12-03" page-git-modified-date: "2025-07-31" support-status: supported --- For topics with Tiered Storage enabled, you can unmount a topic to safely detach it from a cluster and keep the topic data in the cluster’s object storage bucket or container. You can mount the detached topic to either the same origin cluster, or a different one. This allows you to hibernate a topic and free up system resources taken up by the topic, or migrate a topic to a different cluster. ## [](#prerequisites)Prerequisites > 📝 **NOTE** > > This feature requires an [enterprise license](../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../get-started/licensing/#self-managed) apply. - [Install `rpk`](../../get-started/rpk-install/), or ensure that you have access to the Admin API. - Enable [Tiered Storage](../tiered-storage/) for specific topics, or for the entire cluster (all topics). ## [](#unmount-a-topic-from-a-cluster-to-object-storage)Unmount a topic from a cluster to object storage When you unmount a topic, all incoming writes to the topic are blocked as Redpanda unmounts the topic from the cluster to object storage. Producers and consumers of the topic receive a message in the protocol replies indicating that the topic is no longer available: - Produce requests receive an `invalid_topic_exception` or `resource_is_being_migrated` response from the broker. - Consume requests receive an `invalid_topic_exception` response from the broker. An unmounted topic in object storage is detached from all clusters. The original cluster releases ownership of the topic. > 📝 **NOTE** > > The unmounted topic is deleted in the source cluster, but can be mounted back again from object storage. ### rpk In your cluster, run this command to unmount a topic to object storage: ```none rpk cluster storage unmount / ``` ### Admin API To unmount topics from a cluster using the Admin API, make a POST request to the `/v1/topics/unmount` endpoint. Specify the names of the desired topics in the request body: ```none curl -X POST http://localhost:9644/v1/topics/unmount -d { "topics": [ { "topic": "" }, { "topic": "" }, { "topic": "" } ] } ``` You may optionally include the topic namespace (`ns`). Only `kafka` is supported. You can use the ID returned by the command to [monitor the progress](#monitor-progress) of the unmount operation using `rpk` or the API. ## [](#mount-a-topic-to-a-cluster)Mount a topic to a cluster ### rpk 1. In your target cluster, run this command to list the topics that are available to mount from object storage: ```none rpk cluster storage list-mountable ``` The command output returns a `LOCATION` value in the format `//`. Redpanda assigns an `initial-revision` number to a topic upon creation. The location value uniquely identifies a topic in object storage if multiple topics had the same name when they were unmounted from different origin clusters. For example: ```none TOPIC NAMESPACE LOCATION testtopic kafka testtopic/67f5505a-32f3-4677-bcad-3c75a1a702a6/10 ``` You can use the location as the topic reference instead of just the topic name to uniquely identify a topic to mount in the next step. 2. Mount a topic from object storage: ```none rpk cluster storage mount ``` Replace `` with the name of the topic to mount. If there are multiple topics wih the same name in object storage, you are required to use the location value from `rpk cluster storage list-mountable` to uniquely identify a topic. You can also specify a new name for the topic as you mount it to the target cluster: ```none rpk cluster storage mount --to ``` You only use the new name for the topic in the target cluster. This name does not persist if you unmount this topic again. Redpanda keeps the original name in object storage if you remount the topic later. ### Admin API 1. List the topics that are available to mount from object storage by making a GET request to the `v1/topics/mountable` endpoint. ```none curl http://localhost:9644/v1/topics/mountable ``` The response object contains an array of topics: ```bash "topics": [ { "topic_location": "topic-1-name//", "topic": "topic-1-name" }, { "topic_location": "topic-2-name//", "topic": "topic-2-name" } ] ``` The `topic_location` is the unique topic location in object storage, in the format `//`. Redpanda assigns the number `initial-revision` to a topic upon creation. You can use `topic-location` as the topic reference instead of just the topic name to identify a unique topic to mount in the next step. 2. To mount topics to a target cluster using the Admin API, make a POST request to the `/v1/topics/mount` endpoint. Specify the names of the topics in the request body: ```none curl -X POST http://localhost:9644/v1/topics/mount -d { "topics": [ { "source_topic_reference": {"ns": "kafka", "topic": "//"}, "alias": {"topic": ""} }, { "source_topic_reference": {"ns": "kafka", "topic": ""} } ] } ``` - `ns` is the topic namespace. This field is optional and only `kafka` is supported. - You may have multiple topics with the same name that are available to mount from object storage. This can happen if you have unmounted topics using the same name in different clusters. To uniquely identify a source topic, use `//` as the topic reference. - To rename a topic in the target cluster, use the optional `alias` object in the request body. The following example shows how to specify a new name for topic 1 in the target cluster, while topic 2 retains its original name in the target cluster. You can use the ID returned by the operation to [monitor its progress](#monitor-progress) using `rpk` or the API. When the mount operation is complete, the target cluster handles produce and consume workloads for the topics. ## [](#monitor-progress)Monitor progress ### rpk To list active mount and unmount operations, run the command: ```none rpk cluster storage list-mount ``` ### Admin API Issue a GET request to the `/migrations` endpoint to view the status of topic mount and unmount operations: ```none curl http://localhost:9644/v1/migrations ``` You can also retrieve the status of a specific operation by running the command: ### rpk ```none rpk cluster storage status-mount ``` ### Admin API ```none curl http://localhost:9644/v1/migrations/ ``` `` is the unique identifier of the operation. Redpanda returns this ID when you start a mount or unmount. You can also retrieve the ID by listing [existing operations](#monitor-progress). The response returns the IDs and state of existing mount and unmount operations ("migrations"): | State | Unmount operation (outbound) | Mount operation (inbound) | | --- | --- | --- | | planned | Redpanda validates the mount or unmount operation definition. | | preparing | Redpanda flushes topic data, including topic manifests, to the destination bucket or container in object storage. | Redpanda recreates the topics in a disabled state in the target cluster. The cluster allocates partitions but does not add log segments yet. Topic metadata is populated from the topic manifests found in object storage. | | prepared | The operation is ready to execute. In this state, the cluster still accepts client reads and writes for the topics. | Topics exist in the cluster but clients do not yet have access to consume or produce. | | executing | The cluster rejects client reads and writes for the topics. Redpanda uploads any remaining topic data that has not yet been copied to object storage. Uncommitted transactions involving the topic are aborted. | The target cluster checks that the topic to be mounted has not already been mounted in any cluster. | | executed | All unmounted topic data from the cluster is available in object storage. | The target cluster has verified that the topic has not already been mounted. | | cut_over | Redpanda deletes topic metadata from the cluster, and marks the data in object storage as available for mount operations. | The topic data in object storage is no longer available to mount to any clusters. | | finished | The operation is complete. | The operation is complete. The target cluster starts to handle produce and consume requests. | | canceling | Redpanda is in the process of canceling the mount or unmount operation. | | cancelled | The mount or unmount operation is cancelled. | ## [](#cancel-a-mount-or-unmount-operation)Cancel a mount or unmount operation You can cancel a topic mount or unmount by running the command: ### rpk ```none rpk cluster storage cancel-mount ``` ### Admin API ```none curl -X POST http://localhost:9644/v1//?action=cancel ``` You cannot cancel mount and unmount operations in the following [states](#monitor-progress): - `planned` (but you may still [delete](/api/doc/admin/operation/operation-delete_migration) a planned mount or unmount) - `cut_over` - `finished` - `canceling` - `cancelled` ## [](#additional-considerations)Additional considerations Redpanda prevents you from mounting the same topic to multiple clusters at once. This ensures that multiple clusters don’t write to the same location in object storage and corrupt the topic. If you attempt to mount a topic where the name matches a topic already in the target cluster, Redpanda fails the operation and emits a warning message in the logs. ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Owl Shop Example Application in Docker](/redpanda-labs/docker-compose/owl-shop/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) See more [Search all labs](/redpanda-labs) --- # Page 214: Maintenance Mode **URL**: https://docs.redpanda.com/current/manage/node-management.md --- # Maintenance Mode --- title: Maintenance Mode latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: node-management page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: node-management.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/node-management.adoc description: Enable maintenance mode to temporarily take a broker offline, for example during a rolling upgrade. page-git-created-date: "2023-05-30" page-git-modified-date: "2024-12-02" support-status: supported --- Maintenance mode lets you take a Redpanda broker offline temporarily while minimizing disruption to client operations. When a broker is in maintenance mode, you can safely perform operations that require the Redpanda process to be temporarily stopped; for example, system maintenance or a [rolling upgrade](../../upgrade/rolling-upgrade/). > ⚠️ **CAUTION** > > A broker cannot be decommissioned while it’s in maintenance mode. Take the broker out of maintenance mode first by running `rpk cluster maintenance disable `. When a broker is placed in maintenance mode, if the replication factor is greater than one, it reassigns partition leadership to other brokers in the cluster. The broker is not eligible for partition leadership again until it is taken out of maintenance mode. > 📝 **NOTE** > > - Maintenance mode only transfers leadership. It does not move any partitions to other brokers in the cluster. > > - If a broker hosts a partition with a replica count of one, the partition is unavailable when the Redpanda process is not running. > > - Maintenance mode operations only handle a single broker in maintenance at a time. If you attempt to place more than one broker in maintenance mode, you will get an error. The amount of time it takes to drain a broker and reassign leadership depends on the number of partitions and the health of the cluster. For healthy clusters, draining leadership should take less than a minute. For unhealthy clusters (for example, when follower is not in sync with the leader), draining the broker can take longer. Note that the draining process won’t start until the cluster is healthy. When a broker is in maintenance mode, Redpanda continues to replicate updates to that broker. When the broker is taken offline, partitions with replicas on the broker could become out of sync until the broker is brought back online. When the broker is available again, data is copied to under-replicated replicas on the broker until all affected partitions are in sync with the leader. ## [](#place-a-broker-in-maintenance-mode)Place a broker in maintenance mode Before shutting down a broker, you may want to temporarily disable or ignore alerts related to under-replicated partitions. These alerts likely point to false positives as a result of the broker being taken offline and replicas being temporarily unreachable. To prevent under-replicated partitions altogether, you can move all partitions to other brokers. To place a broker into maintenance mode, run: ```bash rpk cluster maintenance enable --wait ``` > 📝 **NOTE** > > The `--wait` option ensures that `rpk` waits until leadership is drained from the broker before responding. To remove a broker from maintenance mode (and thus enable the broker to start taking leadership of partitions), run: ```bash rpk cluster maintenance disable ``` To see the maintenance status of brokers in the cluster, run: ```bash rpk cluster maintenance status ``` The output of this command identifies which brokers in the cluster are in the process of draining leadership, which brokers are finished with that process, and whether any brokers had errors. ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Owl Shop Example Application in Docker](/redpanda-labs/docker-compose/owl-shop/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) - [Start a Single Redpanda Broker with Redpanda Console in Docker](/redpanda-labs/docker-compose/single-broker/) - [Start a Cluster of Redpanda Brokers with Redpanda Console in Docker](/redpanda-labs/docker-compose/three-brokers/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) See more [Search all labs](/redpanda-labs) --- # Page 215: Enable Rack Awareness **URL**: https://docs.redpanda.com/current/manage/rack-awareness.md --- # Enable Rack Awareness --- title: Enable Rack Awareness latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rack-awareness page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rack-awareness.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/rack-awareness.adoc description: Enable rack awareness to place partition replicas across different failure zones. page-git-created-date: "2023-05-30" page-git-modified-date: "2025-08-14" support-status: supported --- Rack awareness allows you to distribute replicas of the same partition across different racks to minimize data loss in the event of a rack failure. A rack is a failure zone that has one or more Redpanda brokers assigned to it. When you create a topic, you specify the number of partitions for the topic and the number of partition replicas. By default, Redpanda determines where to place the replicas on the cluster such that each replica is on a different broker, if possible. By defining different racks for a Redpanda cluster, you can specify a preference for the way partition replicas are assigned to brokers. When Redpanda places partition replicas, it takes into account whether a replica has already been placed on a broker in a particular rack. If so, Redpanda chooses a broker in a different rack. This way, partition replicas are distributed across different failure zones, which provides a measure of fault tolerance in the event that a broker or an entire rack becomes unavailable. When rack awareness is enabled, Redpanda places replicas according to these criteria: - Number of racks vs. replicas - If the cluster has more racks than the number of replicas, each replica is placed on a broker in a unique rack. If the cluster has fewer racks than the number of replicas, some replicas are placed on brokers in the same rack. - Number of available CPU cores - Brokers with more available CPU cores are chosen over brokers with fewer available CPU cores. - Broker utilization - Brokers with fewer partitions are chosen over brokers with more partitions. ## [](#configure-rack-awareness)Configure rack awareness The instructions in this section are based on a cluster with six brokers and three failure zones. The failure zones, or racks, are identified as A, B, and C, with brokers assigned to them: | Broker | Rack | | --- | --- | | 1 | A | | 2 | A | | 3 | B | | 4 | B | | 5 | C | | 6 | C | To set up rack awareness for this cluster: 1. Open a terminal window and log in to broker 1 on the cluster. 2. Run `rpk cluster config edit`. 3. In the text editor window that opens, set `enable_rack_awareness` to `true`. 4. Save your change and quit the editor. 5. Go to the `/etc/redpanda` directory. 6. Open the `redpanda.yaml` file for editing. 7. In the `redpanda` section, add the `rack` property and set the value to A as shown: ```yaml rack: "A" ``` 8. Log in to the remaining brokers and edit their `redpanda.yaml` files. For broker 2, set `rack` to `A`. For brokers 3 and 4, set `rack` to `B`. For brokers 5 and 6, set `rack` to `C`. 9. Restart each broker in the cluster for the rack assignments to take effect. > 💡 **TIP** > > For high availability, Redpanda recommends adding one or more brokers from each zone to the [`seed_servers`](../../reference/properties/broker-properties/#seed_servers) configuration. > 📝 **NOTE** > > Redpanda supports uneven rack assignments. For example, you may have four or five brokers to assign across three racks. > > An uneven assignment might cause undesirable effects: > > - The local storage in some racks will be more full than in others, which is generally less cost-efficient. > > - The compute capacity is also uneven across racks, which could result in uneven latency in some cases. > > > An equal number of brokers assigned to each rack helps to avoid these scenarios, and is therefore considered optimal. ## [](#next-steps)Next steps Use rack awareness with [Continuous Data Balancing](../cluster-maintenance/continuous-data-balancing/) to continually maintain the configured replication level, even after a rack failure. For a given partition, Redpanda tries to move excess replicas from racks that have more than one replica to racks that have no replicas. ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) [Search all labs](/redpanda-labs) --- # Page 216: Raft Group Reconfiguration **URL**: https://docs.redpanda.com/current/manage/raft-group-reconfiguration.md --- # Raft Group Reconfiguration --- title: Raft Group Reconfiguration latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: raft-group-reconfiguration page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: raft-group-reconfiguration.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/raft-group-reconfiguration.adoc description: Learn how the Redpanda Raft group protocol provides consistency and availability during reconfiguration. page-git-created-date: "2024-02-22" page-git-modified-date: "2024-02-22" support-status: supported --- Raft group reconfiguration in Redpanda involves dynamically changing the membership of a Raft group to ensure consistent and available distributed system operations. This process uses learners, new members that do not affect quorum, to maintain service continuity during additions, removals, or replacements in the group. ## [](#how-redpanda-uses-raft)How Redpanda uses Raft Redpanda uses the [Raft](https://raft.github.io/) consensus algorithm to replicate cluster metadata and application data across the brokers. This replication provides strong guarantees for data safety and fault tolerance. Redpanda stores cluster metadata as messages in a special topic in a Raft cluster instance, also known as a Raft group. In a Raft group, one member is the leader and the others are followers. A Raft group that stores cluster metadata is called a controller, and the leader of this group is the controller broker. The messages in the metadata topic contain the current set of brokers that are members of the group. Unlike Kafka with Raft (KRaft), Redpanda uses Raft not only for cluster metadata but also for the application data. Each topic [partition](https://docs.redpanda.com/current/reference/glossary/#partition) in Redpanda forms a Raft group comprised of its leader and follower brokers. Redpanda simplifies Kafka architecture because Raft handles both metadata management as well as data replication. See [How Redpanda Works](../../get-started/architecture/#raft-consensus-algorithm) for a further explanation of how Raft manages data replication in Redpanda. ## [](#about-raft-group-reconfiguration)About Raft group reconfiguration A Raft group’s member set changes during operations like cluster resize or [Continuous Data Balancing](../cluster-maintenance/continuous-data-balancing/). This change, also referred to as Raft group reconfiguration, includes adding, removing, or replacing Raft group members. When the group configuration changes, the current leader replicates a new configuration message and sends it to the followers. Raft uses joint consensus to maintain consistency during reconfiguration. Joint consensus involves both the old member set and the proposed new member set reaching an agreement, either on accepting writes or electing a new leader. The new leader can be elected from either the old or new member set. Redpanda’s implementation of Raft includes changes to the reconfiguration protocol to ensure high availability even as group membership changes. ## [](#redpandas-approach-to-raft-reconfiguration)Redpanda’s approach to Raft reconfiguration Redpanda’s Raft implementation adds the following behavior when reconfiguring Raft groups: - In addition to leader and follower, a broker can also be in learner status. Learners are followers that do not count towards quorum (the majority) and cannot be elected to leader. Learners do not trigger leader elections. New Raft group members start as learners. Brokers can be promoted or demoted between learner and voter. This means that when new members join the Raft group member set, the group continues to operate without interruption since members that can form quorum still accept writes, even if the majority has technically changed due to the additional members. As soon as a learner is synced with the current leader, the learner is promoted to voter. Learners are promoted one at a time. - Because all new brokers joining a Raft group start in learner status, the group does not yet have to enter the joint consensus phase as soon as new members join. - The Raft group only adds new members first. When all learners have been promoted to voters, the group can enter joint consensus. At this point, this is also a new group configuration that contains both the old as well as requested new member set. The current leader replicates this configuration to all brokers. Members that are not in the new configuration are demoted to learners before removal. When the Raft group leaves the joint consensus phase, a new leader may be elected if the old one was removed from the configuration. The following diagrams illustrate the reconfiguration steps in Redpanda. In this example, one member joins the three-broker member set of a Raft group. The box labeled "new" represents the new or current configuration, and "old" represents the old or previous configuration. Each configuration includes the member brokers as indicated by their IDs. Brokers in green are voters, whereas brokers in yellow are learners. If the old configuration is grayed out, it means that only the new configuration is active. 1. Start with a configuration containing brokers 1, 2, and 3: ![raft reconfiguration initial state](../../shared/_images/raft_reconfiguration_initial_state.png) 2. Replace broker 1 with a new member (broker 4). Broker 4 is added to the current configuration as a learner: ![raft reconfiguration new learner](../../shared/_images/raft_reconfiguration_new_learner.png) 3. The learner catches up with the leader and is promoted to voter: ![raft reconfiguration learner promote to voter](../../shared/_images/raft_reconfiguration_learner_promote_to_voter.png) 4. The group enters the joint consensus phase, where the new configuration contains the requested member set: ![raft reconfiguration joint consensus all voters](../../shared/_images/raft_reconfiguration_joint_consensus_all_voters.png) 5. Broker 1 is demoted to learner: ![raft reconfiguration voter demote to learner](../../shared/_images/raft_reconfiguration_voter_demote_to_learner.png) 6. Broker 1 is removed. The leader replicates the new configuration: ![raft reconfiguration final state](../../shared/_images/raft_reconfiguration_final_state.png) A Raft group that can tolerate _F_ broker failures needs to have at least 2_F_ + 1 members. The number of members is typically equal to the [replication factor](https://docs.redpanda.com/current/reference/glossary/#replication-factor). In this example, the group can tolerate a single-broker failure. The two remaining healthy group members can still reach quorum. In Redpanda, the number of voters in a member set is never smaller than the requested replication factor, even during joint consensus. The group can still tolerate failure as it goes through the reconfiguration steps, where not all members are voters. While Raft group reconfiguration in Redpanda requires more steps, this approach guarantees availability throughout the lifecycle of a partition. ## [](#suggested-reading)Suggested reading - [Kafka Raft vs. ZooKeeper vs. Redpanda](https://redpanda.com/guides/kafka-alternatives/kafka-raft) - [Simplifying Redpanda Raft implementation](https://redpanda.com/blog/simplifying-raft-replication-in-redpanda) - [Engineering a more robust Raft group reconfiguration](https://redpanda.com/blog/raft-protocol-reconfiguration-solution) - [Cluster Balancing](../cluster-maintenance/cluster-balancing/) --- # Page 217: Recovery Mode **URL**: https://docs.redpanda.com/current/manage/recovery-mode.md --- # Recovery Mode --- title: Recovery Mode latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: recovery-mode page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: recovery-mode.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/recovery-mode.adoc description: Recovery mode starts Redpanda with limited functionality and disables partitions so you can repair a failed cluster. page-git-created-date: "2023-12-22" page-git-modified-date: "2025-07-31" support-status: supported --- Recovery mode allows you to repair and restore a failed cluster that cannot start normally due to issues such as system crashes or out-of-memory (OOM) errors. In recovery mode, Redpanda limits functionality to cluster configuration changes and other manual administrative actions so that you can repair the cluster. ## [](#enabled-functionality)Enabled functionality In recovery mode, Redpanda enables the following functionality so that you can repair the cluster: - Kafka API - Modify topic properties - Delete topics - Add and remove access control lists (ACLs) - Edit consumer group metadata - Admin API - Edit cluster configuration properties - Add and remove users - Add new brokers to the cluster - Delete WASM transforms ## [](#disabled-functionality)Disabled functionality In recovery mode, Redpanda disables the following functionality to provide a more stable environment for troubleshooting issues and restoring the cluster to a usable state. - The following APIs are disabled because some connections, especially malicious ones, can disrupt availability for all users, including admin users: - Kafka API (fetch and produce requests) - HTTP Proxy - Schema Registry - The following node-wide and cluster-wide processes are disabled as they may disrupt recovery operations: - Partition and leader balancers - Tiered Storage housekeeping - Tiered Storage cache management - Compaction - Redpanda does not load user-managed partitions on disk to prevent triggering partition leadership elections and replication that may occur on startup. ## [](#prerequisites)Prerequisites You must have the following: - [`rpk`](../../get-started/intro-to-rpk/) installed. - Local access to machines running Redpanda. ## [](#start-redpanda-in-recovery-mode)Start Redpanda in recovery mode A broker can only enter recovery mode as it starts up, and not while it is already running. You first set the broker configuration property to enable recovery mode, and then do a broker restart. 1. Run the [`rpk redpanda mode recovery`](../../reference/rpk/rpk-redpanda/rpk-redpanda-mode/) command to set the `recovery_mode_enabled` broker configuration property to `true`. ```bash rpk redpanda mode recovery ``` Enable recovery mode for all brokers. Although, you can start a mixed-mode cluster, where some brokers are in recovery mode while others are not, it’s not recommended. 2. Restart the brokers. 3. Check whether the cluster has entered recovery mode: ```bash rpk cluster health ``` You should see a list of brokers that are in recovery mode. For example: ```bash CLUSTER HEALTH OVERVIEW ======================= Healthy: true Unhealthy reasons: [] Controller ID: 0 All nodes: [0 1 2] Nodes down: [] Nodes in recovery mode: [0 1 2] Leaderless partitions (0): [] Under-replicated partitions (0): [] ``` In recovery mode, all private Redpanda topics such as `__consumer_offsets` are accessible. Data in user-created topics is not available, but you can still manage the metadata for these topics. ## [](#exit-recovery-mode)Exit recovery mode Exit recovery mode by running one of the following commands: - To exit into developer mode: ```bash rpk redpanda mode developer ``` - To exit into production mode: ```bash rpk redpanda mode production ``` ## [](#disable-partitions)Disable partitions Problems that prevent normal cluster startup may be isolated to certain partitions or topics. You can use rpk or the [Admin API](/api/doc/admin/group/endpoint-partitions) to disable these partitions at the topic level, or individual partition level. A disabled partition or topic returns a `Replica Not Available` error code for Kafka API requests. To disable a partition, you need a healthy controller in the cluster, so you must start the cluster in recovery mode if a problematic partition is affecting cluster startup. If you disable a partition while in recovery mode, starting Redpanda again in non-recovery mode leaves the partition in a deactivated state. You must explicitly re-enable the partition. You can also disable a partition _outside_ of recovery mode, if the issue is localized to the partition and does not interfere with cluster startup. The following examples show you how to use the Admin API to enable or disable partitions. The examples are based on the assumption that the Admin API port is `9644`. > 📝 **NOTE** > > Use `kafka` as the `partition-namespace` when making API calls to manage partitions in user topics. ### [](#disable-a-specific-partition-of-a-topic)Disable a specific partition of a topic #### rpk ```bash rpk cluster partitions disable --partitions ``` #### Curl ```bash curl -X POST -d '{"disabled": true}' http://localhost:9644/v1/cluster/partitions/// ``` ### [](#enable-a-specific-partition-of-a-topic)Enable a specific partition of a topic #### rpk ```bash rpk cluster partitions enable --partitions ``` #### Curl ```bash curl -X POST -d '{"disabled": false}' http://localhost:9644/v1/cluster/partitions/// ``` ### [](#disable-all-partitions-of-a-specific-topic)Disable all partitions of a specific topic #### rpk ```bash rpk cluster partitions disable --all ``` #### Curl ```bash curl -X POST -d '{"disabled": true}' http://localhost:9644/v1/cluster/partitions// ``` ### [](#enable-all-partitions-of-a-specific-topic)Enable all partitions of a specific topic #### rpk ```bash rpk cluster partitions enable --all ``` #### Curl ```bash curl -X POST -d '{"disabled": false}' http://localhost:9644/v1/cluster/partitions// ``` ### [](#list-all-disabled-partitions)List all disabled partitions #### rpk ```bash rpk cluster partitions list --all --disabled-only ``` #### Curl ```bash curl http://localhost:9644/v1/cluster/partitions?disabled=true ``` ### [](#list-all-disabled-partitions-of-a-specific-topic)List all disabled partitions of a specific topic #### rpk ```bash rpk cluster partitions list --disabled-only ``` #### Curl ```bash curl http://localhost:9644/v1/cluster/partitions//?disabled=true ``` ## [](#suggested-reading)Suggested reading - [Admin API reference](/api/doc/admin/) - [Perform a Rolling Restart](../cluster-maintenance/rolling-restart/) --- # Page 218: Remote Read Replicas **URL**: https://docs.redpanda.com/current/manage/remote-read-replicas.md --- # Remote Read Replicas --- title: Remote Read Replicas latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: remote-read-replicas page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: remote-read-replicas.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/remote-read-replicas.adoc description: Learn how to create a Remote Read Replica topic, which is a read-only topic that mirrors a topic on a different cluster. page-git-created-date: "2023-05-30" page-git-modified-date: "2025-11-19" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../get-started/licensing/#self-managed) apply. A Remote Read Replica topic is a read-only topic that mirrors a topic on a different cluster. Remote Read Replicas work with both [Tiered Storage](../tiered-storage/) and [archival storage](../tiered-storage/#data-archiving). When a topic has object storage enabled, you can create a separate remote cluster just for consumers of this topic, and populate its topics from remote storage. A read-only topic on a remote cluster can serve any consumer, without increasing the load on the origin cluster. Use cases for Remote Read Replicas include data analytics, offline model training, and development clusters. You can create Remote Read Replica topics in a Redpanda cluster that directly accesses data stored in object storage. Because these read-only topics access data directly from object storage instead of the topics' origin cluster, there’s no impact to the performance of the cluster. Topic data can be consumed within a region of your choice, regardless of the region where it was produced. > ❗ **IMPORTANT** > > - The Remote Read Replica cluster must run on the same version of Redpanda as the origin cluster, or just one feature release ahead of the origin cluster. For example, if the origin cluster is version 24.1, the Remote Read Replica cluster can be 24.2, but not 24.3. It cannot skip feature releases. > > - When upgrading, upgrade the Remote Read Replica cluster before upgrading the origin cluster. ## [](#prerequisites)Prerequisites You need the following: - An origin cluster with [Tiered Storage](../tiered-storage/#set-up-tiered-storage) set up. Multi-region buckets or containers are not supported. - A topic on the origin cluster, which you can use as a Remote Read Replica topic on the remote cluster. - A separate remote cluster. - AWS: The remote cluster can be in the same or a different region as the origin cluster’s S3 bucket. For cross-region Remote Read Replica topics, see [Create a cross-region Remote Read Replica topic on AWS](#create-cross-region-rrr-topic). - GCP: The remote cluster can be in the same or a different region as the bucket/container. - Azure: Remote read replicas are not supported. This feature requires an [enterprise license](../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../get-started/licensing/#self-managed) apply. To check if you already have a license key applied to your cluster: ```bash rpk cluster license info ``` ## [](#configure-object-storage-for-the-remote-cluster)Configure object storage for the remote cluster You must configure access to the same object storage as the origin cluster. To set up a Remote Read Replica topic on a separate remote cluster: 1. Create a remote cluster for the Remote Read Replica topic. For GCP, the remote cluster can be in the same or a different region as the bucket/container. For AWS, the remote cluster can be in the same or a different region, but cross-region Remote Read Replica topics require additional configuration. See [Create a cross-region Remote Read Replica topic on AWS](#create-cross-region-rrr-topic). 2. Run `rpk cluster config edit`, and then specify properties specific to your object storage provider (your cluster will require a restart after any changes to these properties): ### Amazon S3 ```yaml cloud_storage_enabled : true cloud_storage_access_key : cloud_storage_secret_key : cloud_storage_region : cloud_storage_bucket : #Optional. Should not be changed after writing data to it ``` > ⚠️ **WARNING** > > Modifying the `cloud_storage_bucket` property after writing data to a bucket could cause data loss. ### Google Cloud Storage ```yaml cloud_storage_enabled : true cloud_storage_access_key : cloud_storage_secret_key : cloud_storage_region : cloud_storage_api_endpoint : `storage.googleapis.com` cloud_storage_bucket : #Optional. Should not be changed after writing data to it. ``` > ⚠️ **WARNING** > > Modifying the `cloud_storage_bucket` property after writing data to a bucket could cause data loss. ### Azure Blob Storage ```yaml cloud_storage_enabled : true cloud_storage_azure_container : cloud_storage_azure_storage_account : cloud_storage_azure_shared_key: ``` For a complete reference on object storage properties, see [Object Storage Properties](../../reference/properties/object-storage-properties/). ## [](#create-a-remote-read-replica-topic)Create a Remote Read Replica topic To create the Remote Read Replica topic, run: ```bash rpk topic create -c redpanda.remote.readreplica= ``` - For ``, use the same name as the original topic. - For ``, use the bucket/container specified in the `cloud_storage_bucket` or `cloud_storage_azure_container` properties for the origin cluster. > 📝 **NOTE** > > - The Remote Read Replica cluster must run on the same version of Redpanda as the origin cluster, or just one feature release ahead of the origin cluster. For example, if the origin cluster is version 23.1, the Remote Read Replica cluster can be 23.2, but not 23.4. It cannot skip feature releases. > > - During upgrades, upgrade the Remote Read Replica cluster before upgrading the origin cluster. > > - Do not use `redpanda.remote.read` or `redpanda.remote.write` with `redpanda.remote.readreplica`. Redpanda ignores the values for remote read and remote write properties on read replica topics. ### [](#create-cross-region-rrr-topic)Create a cross-region Remote Read Replica topic on AWS Use this configuration only when the remote cluster is in a **different AWS region** than the origin cluster’s S3 bucket. For same-region AWS or GCP deployments, use the standard [topic creation command](#create-a-remote-read-replica-topic). #### [](#prerequisites-2)Prerequisites You must explicitly set the [`cloud_storage_url_style`](../../reference/properties/object-storage-properties/#cloud_storage_url_style) cluster property to `virtual_host` or `path` on the remote cluster. The default value does not support cross-region Remote Read Replicas. #### [](#create-the-topic)Create the topic To create a cross-region Remote Read Replica topic, append `region` and `endpoint` query-string parameters to the bucket name. In the following example, replace the placeholders: - ``: The name of the topic in the cluster hosting the Remote Read Replica. - ``: The S3 bucket configured on the origin cluster (`cloud_storage_bucket`). - ``: The AWS region of the origin cluster’s S3 bucket (not the remote cluster’s region). ```bash rpk topic create \ -c redpanda.remote.readreplica=?region=&endpoint=s3..amazonaws.com ``` For example, if the origin cluster stores data in a bucket called `my-bucket` in `us-east-1`: ```bash rpk topic create my-topic \ -c redpanda.remote.readreplica=my-bucket?region=us-east-1&endpoint=s3.us-east-1.amazonaws.com ``` > 📝 **NOTE** > > The `endpoint` value must not include the bucket name. When using `virtual_host` URL style, Redpanda automatically prepends the bucket name to the endpoint. When using `path` URL style, Redpanda appends the bucket name as a path segment. #### [](#limits)Limits Each unique combination of region and endpoint creates a separate object storage target on the remote cluster. A cluster supports a maximum of 10 targets. How targets are counted depends on `cloud_storage_url_style`: - `virtual_host`: Each unique combination of bucket, region, and endpoint counts as one target. You can create up to 10 distinct cross-region Remote Read Replica topics for each cluster. - `path`: Each unique combination of region and endpoint counts as one target (the bucket name is not part of the key). You can create cross-region Remote Read Replica topics for multiple buckets using the same region/endpoint combination, with a maximum of 10 distinct region/endpoint combinations for each cluster. ## [](#reduce-lag-in-data-availability)Reduce lag in data availability When object storage is enabled on a topic, Redpanda copies closed log segments to the configured object store. Log segments are closed when the value of the segment size has been reached. A topic’s object store thus lags behind the local copy by the [`log_segment_size`](../../reference/properties/cluster-properties/#log_segment_size) or, if set, by the topic’s `segment.bytes` value. To reduce this lag in the data availability for the Remote Read Replica: - You can lower the value of `segment.bytes`. This lets Redpanda archive smaller log segments more frequently, at the cost of increasing I/O and file count. - Redpanda Self-Managed deployments can set an idle timeout with `[cloud_storage_segment_max_upload_interval_sec](../../reference/properties/object-storage-properties/#cloud_storage_segment_max_upload_interval_sec)` to force Redpanda to periodically archive the contents of open log segments to object storage. This is useful if a topic’s write rate is low and log segments are kept open for long periods of time. The appropriate interval may depend on your total partition count: a system with less partitions can handle a higher number of segments per partition. ## [](#suggested-reading)Suggested reading [Remote Read Replicas: Read-only topics in Tiered Storage](https://redpanda.com/blog/remote-read-replicas-for-distributing-work) --- # Page 219: Schema Registry **URL**: https://docs.redpanda.com/current/manage/schema-reg.md --- # Schema Registry --- title: Schema Registry latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: schema-reg/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: schema-reg/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/schema-reg/index.adoc description: Redpanda's Schema Registry provides the interface to store and manage event schemas. page-git-created-date: "2023-11-16" page-git-modified-date: "2024-02-26" support-status: supported --- - [Redpanda Schema Registry](schema-reg-overview/) Redpanda's Schema Registry provides the interface to store and manage event schemas. - [Use Schema Registry](manage-schema-reg/) Learn how to add, delete, and update schemas in Redpanda Self-Managed. - [Schema Registry Authorization](schema-reg-authorization/) Learn how to set up and manage Schema Registry Authorization using ACL definitions that control user access to specific Schema Registry operations. - [Server-Side Schema ID Validation](schema-id-validation/) Learn about server-side schema ID validation for clients using SerDes that produce to Redpanda brokers, and learn how to configure Redpanda to inspect and reject records with invalid schema IDs. - [Use Schema Registry in Redpanda Console](../../console/ui/schema-reg/) Learn how to perform common Schema Registry management operations in the Redpanda Console. --- # Page 220: Use Schema Registry **URL**: https://docs.redpanda.com/current/manage/schema-reg/manage-schema-reg.md --- # Use Schema Registry --- title: Use Schema Registry latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: schema-reg/manage-schema-reg page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: schema-reg/manage-schema-reg.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/schema-reg/manage-schema-reg.adoc description: Learn how to add, delete, and update schemas in Redpanda Self-Managed. page-git-created-date: "2024-12-03" page-git-modified-date: "2024-12-03" support-status: supported --- Learn how to add, delete, and update schemas in Redpanda Self-Managed. - [Use the Schema Registry API](../schema-reg-api/) Perform common Schema Registry management operations with the API. - [Manage Schemas with the Redpanda Operator](../../kubernetes/k-schema-controller/) Use the Schema resource to declaratively create and manage schemas as part of a Redpanda deployment in Kubernetes. --- # Page 221: Server-Side Schema ID Validation **URL**: https://docs.redpanda.com/current/manage/schema-reg/schema-id-validation.md --- # Server-Side Schema ID Validation --- title: Server-Side Schema ID Validation latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: schema-reg/schema-id-validation page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: schema-reg/schema-id-validation.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/schema-reg/schema-id-validation.adoc description: Learn about server-side schema ID validation for clients using SerDes that produce to Redpanda brokers, and learn how to configure Redpanda to inspect and reject records with invalid schema IDs. page-git-created-date: "2023-11-16" page-git-modified-date: "2026-02-04" support-status: supported --- You can use server-side schema ID validation for clients using Confluent’s SerDes format that produce to Redpanda brokers. You can also configure Redpanda to inspect and reject records with schema IDs that aren’t valid according to the configured Subject Name strategy and registered with the Schema Registry. > 📝 **NOTE** > > This feature requires an [enterprise license](../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../get-started/licensing/#self-managed) apply. ## [](#about-schema-id-validation)About schema ID validation Records produced to a topic may use a serializer/deserializer client library, such as Confluent’s SerDes library, to encode their keys and values according to a schema. When a client produces a record, the _schema ID_ for the topic is encoded in the record’s payload header. The schema ID must be associated with a subject and a version in the Schema Registry. That subject is determined by the _subject name strategy_, which maps the topic and schema onto a subject. A client may be misconfigured with either the wrong schema or the wrong subject name strategy, resulting in unexpected data on the topic. A produced record for an unregistered schema shouldn’t be stored by brokers or fetched by consumers. Yet, it may not be detected or dropped until after it’s been fetched and a consumer deserializes its mismatched schema ID. Schema ID validation enables brokers (servers) to detect and drop records that were produced with an incorrectly configured subject name strategy, that don’t conform to the SerDes wire format, or encode an incorrect schema ID. With schema ID validation, records associated with unregistered schemas are detected and dropped earlier, by a broker rather than a consumer. > ❗ **IMPORTANT** > > Schema ID validation doesn’t verify that a record’s payload is correctly encoded according to the associated schema. Schema ID validation only checks that the schema ID encoded in the record is registered in the Schema Registry. ## [](#configure-schema-id-validation)Configure schema ID validation To use schema ID validation: - [Enable the feature in Redpanda](#enable-schema-id-validation) - [Customize the subject name strategy per topic on the client](#set-subject-name-strategy-per-topic) ### [](#enable-schema-id-validation)Enable schema ID validation By default, server-side schema ID validation is disabled in Redpanda. To enable schema ID validation, change the [`enable_schema_id_validation`](../../../reference/properties/cluster-properties/#enable_schema_id_validation) cluster property from its default value of `none` to either `redpanda` or `compat`: - `none`: Schema validation is disabled (no schema ID checks are done). Associated topic properties cannot be modified. - `redpanda`: Schema validation is enabled. Only Redpanda topic properties are accepted. - `compat`: Schema validation is enabled. Both Redpanda and compatible topic properties are accepted. For example, use `rpk` to set the value of `enable_schema_id_validation` to `redpanda` through the Admin API: ```bash rpk cluster config set enable_schema_id_validation redpanda -X admin.hosts=:9644 ``` ### [](#set-subject-name-strategy-per-topic)Set subject name strategy per topic The subject name strategies supported by Redpanda: | Subject Name Strategy | Subject Name Source | Subject Name Format (Key) | Subject Name Format (Value) | | --- | --- | --- | --- | | TopicNameStrategy | Topic name | -key | -value | | RecordNameStrategy | Fully-qualified record name | | | | TopicRecordNameStrategy | Both topic name and fully-qualified record name | - | - | When [schema ID validation is enabled](#enable-schema-id-validation), Redpanda uses `TopicNameStrategy` by default. To customize the subject name strategy per topic, set the following client topic properties: - Set [`redpanda.key.schema.id.validation`](../../../reference/properties/topic-properties/#redpandakeyschemavalidation) to `true` to enable key schema ID validation for the topic, and set [`redpanda.key.subject.name.strategy`](../../../reference/properties/topic-properties/#redpandakeysubjectnamestrategy) to the desired subject name strategy for keys of the topic (default: `TopicNameStrategy`). - Set [`redpanda.value.schema.id.validation`](../../../reference/properties/topic-properties/#redpandavalueschemavalidation) to `true` to enable value schema ID validation for the topic, and set [`redpanda.value.subject.name.strategy`](../../../reference/properties/topic-properties/#redpandavaluesubjectnamestrategy) to the desired subject name strategy for values of the topic (default: `TopicNameStrategy`). > 📝 **NOTE** > > The `redpanda.` properties have corresponding `confluent.` properties. > > | Redpanda property | Confluent property | > | --- | --- | > | redpanda.key.schema.id.validation | confluent.key.schema.validation | > | redpanda.key.subject.name.strategy | confluent.key.subject.name.strategy | > | redpanda.value.schema.id.validation | confluent.value.schema.validation | > | redpanda.value.subject.name.strategy | confluent.value.subject.name.strategy | The `redpanda.` **and `confluent.`** properties are compatible. Either or both can be set simultaneously. If `subject.name.strategy` is prefixed with `confluent.`, the available subject name strategies must be prefixed with `io.confluent.kafka.serializers.subject.`. For example, `io.confluent.kafka.serializers.subject.TopicNameStrategy`. > 📝 **NOTE** > > To support schema ID validation for compressed topics, a Redpanda broker decompresses each batch written to it so it can access the schema ID. ### [](#configuration-examples)Configuration examples Create a topic with with `RecordNameStrategy`: ```bash rpk topic create topic_foo \ --topic-config redpanda.value.schema.id.validation=true \ --topic-config redpanda.value.subject.name.strategy=RecordNameStrategy \ -X brokers=:9092 ``` Alter a topic to `RecordNameStrategy`: ```bash rpk topic alter-config topic_foo \ --set redpanda.value.schema.id.validation=true \ --set redpanda.value.subject.name.strategy=RecordNameStrategy \ -X brokers=:9092 ``` --- # Page 222: Use the Schema Registry API **URL**: https://docs.redpanda.com/current/manage/schema-reg/schema-reg-api.md --- # Use the Schema Registry API --- title: Use the Schema Registry API latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: schema-reg/schema-reg-api page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: schema-reg/schema-reg-api.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/schema-reg/schema-reg-api.adoc description: Perform common Schema Registry management operations with the API. page-git-created-date: "2023-11-16" page-git-modified-date: "2025-11-21" support-status: supported --- Schemas provide human-readable documentation for an API. They verify that data conforms to an API, support the generation of serializers for data, and manage the compatibility of evolving APIs, allowing new versions of services to be rolled out independently. > 📝 **NOTE** > > The Schema Registry is built into Redpanda, and you can use it with the API or the UI. This section describes operations available in the [Schema Registry API](/api/doc/schema-registry/). The Redpanda Schema Registry has API endpoints that allow you to perform the following tasks: - Register schemas for a subject. When data formats are updated, a new version of the schema can be registered under the same subject, allowing for backward and forward compatibility. - Retrieve schemas of specific versions. - Retrieve a list of subjects. - Retrieve a list of schema versions for a subject. - Configure schema compatibility checking. - Query supported serialization formats. - Delete schemas from the registry. The following examples cover the basic functionality of the Redpanda Schema Registry based on an example Avro schema called `sensor_sample`. This schema contains fields that represent a measurement from a sensor for the value of the `sensor` topic, as defined below. ```json { "type": "record", "name": "sensor_sample", "fields": [ { "name": "timestamp", "type": "long", "logicalType": "timestamp-millis" }, { "name": "identifier", "type": "string", "logicalType": "uuid" }, { "name": "value", "type": "long" } ] } ``` ## [](#prerequisites)Prerequisites To run the sample commands and code in each example, follow these steps to set up Redpanda and other tools: 1. You need a running Redpanda cluster. If you don’t have one, you can follow the [quickstart](../../../get-started/quick-start/) to deploy a self-managed cluster. In these examples, it is assumed that the Schema Registry is available locally at `[http://localhost:8081](http://localhost:8081)`. If the Schema Registry is hosted on a different address or port in your cluster, change the URLs in the examples. 2. Download the [jq utility](https://stedolan.github.io/jq/download/). 3. Install [curl](https://curl.se/) or [Python](https://www.python.org/). You can also use [`rpk`](../../../get-started/intro-to-rpk/) to interact with the Schema Registry. The [`rpk registry`](../../../reference/rpk/rpk-registry/rpk-registry/) set of commands call the different API endpoints as shown in the curl and Python examples. If using Python, install the [Requests module](https://requests.readthedocs.io/en/latest/user/install/#install), then create an interactive Python session: ```python import requests import json def pretty(text): print(json.dumps(text, indent=2)) base_uri = "http://localhost:8081" ``` ## [](#manage-schema-registry-acls)Manage Schema Registry ACLs > 📝 **NOTE** > > This feature requires an [enterprise license](../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../get-started/licensing/#self-managed) apply. You can use ACLs to control access to Schema Registry resources. You can define fine-grained access on a global level, for example, to allow a principal to read all schemas, or on a per-subject basis, for example, to read and modify only the schemas of a specific subject. See [Schema Registry Authorization](../schema-reg-authorization/) for more details on Schema Registry Authorization. For example, to [create ACLs](/api/doc/schema-registry/group/endpoint-security) that allow users with the `admin` role read-only access to all registered schemas, run: ```bash curl -X POST "http://localhost:8081/security/acls" \ -H "Content-Type: application/json" \ -d '[ { "principal": "RedpandaRole:admin", "resource": "*", "resource_type": "REGISTRY", "pattern_type": "LITERAL", "host": "*", "operation": "DESCRIBE_CONFIGS", "permission": "ALLOW" }, { "principal": "RedpandaRole:admin", "resource": "*", "resource_type": "SUBJECT", "pattern_type": "LITERAL", "host": "*", "operation": "READ", "permission": "ALLOW" } ]' ``` This creates two ACLs: one for registry-level read operations (such as reading global configuration) and another for subject-level read operations (such as reading schemas). ## [](#query-supported-schema-formats)Query supported schema formats To get the supported data serialization formats in the Schema Registry, make a GET request to the `/schemas/types` endpoint: ### Curl ```bash curl -s "http://localhost:8081/schemas/types" | jq . ``` ### Python ```python res = requests.get(f'{base_uri}/schemas/types').json() pretty(res) ``` This returns the supported serialization formats: \[ "JSON", "PROTOBUF", "AVRO" \] ## [](#register-a-schema)Register a schema A schema is registered in the registry with a _subject_, which is a name that is associated with the schema as it evolves. Subjects are typically in the form `-key` or `-value`. To register the `sensor_sample` schema, make a POST request to the `/subjects/sensor-value/versions` endpoint with the Content-Type `application/vnd.schemaregistry.v1+json`: ### rpk ```bash rpk registry schema create sensor-value --schema ~/code/tmp/sensor_sample.avro ``` ### Curl ```bash curl -s \ -X POST \ "http://localhost:8081/subjects/sensor-value/versions" \ -H "Content-Type: application/vnd.schemaregistry.v1+json" \ -d '{"schema": "{\"type\":\"record\",\"name\":\"sensor_sample\",\"fields\":[{\"name\":\"timestamp\",\"type\":\"long\",\"logicalType\":\"timestamp-millis\"},{\"name\":\"identifier\",\"type\":\"string\",\"logicalType\":\"uuid\"},{\"name\":\"value\",\"type\":\"long\"}]}"}' \ | jq ``` To normalize the schema, add the query parameter `?normalize=true` to the endpoint. ### Python ```python sensor_schema = { "type": "record", "name": "sensor_sample", "fields": [ { "name": "timestamp", "type": "long", "logicalType": "timestamp-millis" }, { "name": "identifier", "type": "string", "logicalType": "uuid" }, { "name": "value", "type": "long" } ] } res = requests.post( url=f'{base_uri}/subjects/sensor-value/versions', data=json.dumps({ 'schema': json.dumps(sensor_schema) }), headers={'Content-Type': 'application/vnd.schemaregistry.v1+json'}).json() pretty(res) ``` This returns the version `id` unique for the schema in the Redpanda cluster: ### rpk SUBJECT VERSION ID TYPE sensor-value 1 1 AVRO ### Curl ```json { "id": 1 } ``` When you register an evolved schema for an existing subject, the version `id` is incremented by 1. ## [](#retrieve-a-schema)Retrieve a schema To retrieve a registered schema from the registry, make a GET request to the `/schemas/ids/{id}` endpoint: ### rpk ```bash rpk registry schema get --id 1 ``` ### Curl ```bash curl -s \ "http://localhost:8081/schemas/ids/1" \ | jq . ``` ### Python ```python res = requests.get(f'{base_uri}/schemas/ids/1').json() pretty(res) ``` The rpk output returns the subject and version, and the HTTP response returns the schema: ### rpk SUBJECT VERSION ID TYPE sensor-value 1 1 AVRO ### Curl ```json { "schema": "{\"type\":\"record\",\"name\":\"sensor_sample\",\"fields\":[{\"name\":\"timestamp\",\"type\":\"long\",\"logicalType\":\"timestamp-millis\"},{\"name\":\"identifier\",\"type\":\"string\",\"logicalType\":\"uuid\"},{\"name\":\"value\",\"type\":\"long\"}]}" } ``` ## [](#list-registry-subjects)List registry subjects To list all registry subjects, make a GET request to the `/subjects` endpoint: ### rpk ```bash rpk registry subject list --format json ``` ### Curl ```bash curl -s \ "http://localhost:8081/subjects" \ | jq . ``` ### Python ```python res = requests.get(f'{base_uri}/subjects').json() pretty(res) ``` This returns the subject: ```json [ "sensor-value" ] ``` ## [](#retrieve-schema-versions-of-a-subject)Retrieve schema versions of a subject To query the schema versions of a subject, make a GET request to the `/subjects/{subject}/versions` endpoint. For example, to get the schema versions of the `sensor-value` subject: ### Curl ```bash curl -s \ "http://localhost:8081/subjects/sensor-value/versions" \ | jq . ``` ### Python ```python res = requests.get(f'{base_uri}/subjects/sensor-value/versions').json() pretty(res) ``` This returns the version ID: ```json [ 1 ] ``` ## [](#retrieve-a-subjects-specific-version-of-a-schema)Retrieve a subject’s specific version of a schema To retrieve a specific version of a schema associated with a subject, make a GET request to the `/subjects/{subject}/versions/{version}` endpoint: ### rpk ```bash rpk registry schema get sensor-value --schema-version 1 ``` ### Curl ```bash curl -s \ "http://localhost:8081/subjects/sensor-value/versions/1" \ | jq . ``` ### Python ```python res = requests.get(f'{base_uri}/subjects/sensor-value/versions/1').json() pretty(res) ``` The rpk output returns the subject, and for HTTP requests, its associated schema as well: ### rpk SUBJECT VERSION ID TYPE sensor-value 1 1 AVRO ### Curl ```json { "subject": "sensor-value", "id": 1, "version": 1, "schema": "{\"type\":\"record\",\"name\":\"sensor_sample\",\"fields\":[{\"name\":\"timestamp\",\"type\":\"long\",\"logicalType\":\"timestamp-millis\"},{\"name\":\"identifier\",\"type\":\"string\",\"logicalType\":\"uuid\"},{\"name\":\"value\",\"type\":\"long\"}]}" } ``` To get the latest version, use `latest` as the version ID: ### rpk ```bash rpk registry schema get sensor-value --schema-version latest ``` ### Curl ```bash curl -s \ "http://localhost:8081/subjects/sensor-value/versions/latest" \ | jq . ``` ### Python ```python res = requests.get(f'{base_uri}/subjects/sensor-value/versions/latest').json() pretty(res) ``` To get only the schema, append `/schema` to the endpoint path: ### Curl ```bash curl -s \ "http://localhost:8081/subjects/sensor-value/versions/latest/schema" \ | jq . ``` ### Python ```python res = requests.get(f'{base_uri}/subjects/sensor-value/versions/latest/schema').json() pretty(res) ``` ```json { "type": "record", "name": "sensor_sample", "fields": [ { "name": "timestamp", "type": "long", "logicalType": "timestamp-millis" }, { "name": "identifier", "type": "string", "logicalType": "uuid" }, { "name": "value", "type": "long" } ] } ``` ## [](#configure-schema-compatibility)Configure schema compatibility As applications change and their schemas evolve, you may find that producer schemas and consumer schemas are no longer compatible. You decide how you want a consumer to handle data from a producer that uses an older or newer schema. Applications are often modeled around a specific business object structure. As applications change and the shape of their data changes, producer schemas and consumer schemas may no longer be compatible. You can decide how a consumer handles data from a producer that uses an older or newer schema, and reduce the chance of consumers hitting deserialization errors. You can configure different types of schema compatibility, which are applied to a subject when a new schema is registered. The Schema Registry supports the following compatibility types: - `BACKWARD` (**default**) - Consumers using the new schema (for example, version 10) can read data from producers using the previous schema (for example, version 9). - `BACKWARD_TRANSITIVE` - Consumers using the new schema (for example, version 10) can read data from producers using all previous schemas (for example, versions 1-9). - `FORWARD` - Consumers using the previous schema (for example, version 9) can read data from producers using the new schema (for example, version 10). - `FORWARD_TRANSITIVE` - Consumers using any previous schema (for example, versions 1-9) can read data from producers using the new schema (for example, version 10). - `FULL` - A new schema and the previous schema (for example, versions 10 and 9) are both backward and forward compatible with each other. - `FULL_TRANSITIVE` - Each schema is both backward and forward compatible with all registered schemas. - `NONE` - No schema compatibility checks are done. ### [](#compatibility-uses-and-constraints)Compatibility uses and constraints - A consumer that wants to read a topic from the beginning (for example, an AI learning process) benefits from backward compatibility. It can process the whole topic using the latest schema. This allows producers to remove fields and add attributes. - A real-time consumer that doesn’t care about historical events but wants to keep up with the latest data (for example, a typical streaming application) benefits from forward compatibility. Even if producers change the schema, the consumer can carry on. - Full compatibility can process historical data and future data. This is the safest option, but it limits the changes that can be done. This only allows for the addition and removal of optional fields. If you make changes that are not inherently backward-compatible, you may need to change compatibility settings or plan a transitional period, updating producers and consumers to use the new schema while the old one is still accepted. | Schema format | Backward-compatible tasks | Not backward-compatible tasks | | --- | --- | --- | | Avro | Add fields with default valuesMake fields nullable | Remove fieldsChange data types of fieldsChange enum valuesChange field constraintsChange record of field names | | Protobuf | Add fieldsRemove fields | Remove required fieldsChange data types of fields | | JSON | Add optional propertiesRelax constraints, for example:Decrease a minimum value or increase a maximum valueDecrease minItems, minLength, or minProperties; increase maxItems, maxLength, maxPropertiesAdd more property types (for example, "type": "integer" to "type": ["integer", "string"])Add more enum valuesReduce multipleOf by an integral factorRelaxing additional properties if additionalProperties was not previously specified as falseRemoving a uniqueItems property that was false | Remove propertiesAdd required propertiesChange property names and typesTighten or add constraints | To set the compatibility type for a subject, make a PUT request to `/config/{subject}` with the specific compatibility type: #### rpk ```bash rpk registry compatibility-level set sensor-value --level BACKWARD ``` #### Curl ```bash curl -s \ -X PUT \ "http://localhost:8081/config/sensor-value" \ -H "Content-Type: application/vnd.schemaregistry.v1+json" \ -d '{"compatibility": "BACKWARD"}' \ | jq . ``` #### Python ```python res = requests.put( url=f'{base_uri}/config/sensor-value', data=json.dumps( {'compatibility': 'BACKWARD'} ), headers={'Content-Type': 'application/vnd.schemaregistry.v1+json'}).json() pretty(res) ``` This returns the new compatibility type: #### rpk SUBJECT LEVEL ERROR sensor-value BACKWARD #### Curl ```json { "compatibility": "BACKWARD" } ``` If you POST an incompatible schema change, the request returns an error. For example, if you try to register a new schema with the `value` field’s type changed from `long` to `int`, and compatibility is set to `BACKWARD`, the request returns an error due to incompatibility: #### Curl ```bash curl -s \ -X POST \ "http://localhost:8081/subjects/sensor-value/versions" \ -H "Content-Type: application/vnd.schemaregistry.v1+json" \ -d '{"schema": "{\"type\":\"record\",\"name\":\"sensor_sample\",\"fields\":[{\"name\":\"timestamp\",\"type\":\"long\",\"logicalType\":\"timestamp-millis\"},{\"name\":\"identifier\",\"type\":\"string\",\"logicalType\":\"uuid\"},{\"name\":\"value\",\"type\":\"int\"}]}"}' \ | jq ``` #### Python ```python sensor_schema["fields"][2]["type"] = "int" res = requests.post( url=f'{base_uri}/subjects/sensor-value/versions', data=json.dumps({ 'schema': json.dumps(sensor_schema) }), headers={'Content-Type': 'application/vnd.schemaregistry.v1+json'}).json() pretty(res) ``` The request returns this error: ```json { "error_code": 409, "message": "Schema being registered is incompatible with an earlier schema for subject \"{sensor-value}\"" } ``` For an example of a compatible change, register a schema with the `value` field’s type changed from `long` to `double`: #### Curl ```bash curl -s \ -X POST \ "http://localhost:8081/subjects/sensor-value/versions" \ -H "Content-Type: application/vnd.schemaregistry.v1+json" \ -d '{"schema": "{\"type\":\"record\",\"name\":\"sensor_sample\",\"fields\":[{\"name\":\"timestamp\",\"type\":\"long\",\"logicalType\":\"timestamp-millis\"},{\"name\":\"identifier\",\"type\":\"string\",\"logicalType\":\"uuid\"},{\"name\":\"value\",\"type\":\"double\"}]}"}' \ | jq ``` #### Python ```python sensor_schema["fields"][2]["type"] = "double" res = requests.post( url=f'{base_uri}/subjects/sensor-value/versions', data=json.dumps({ 'schema': json.dumps(sensor_schema) }), headers={'Content-Type': 'application/vnd.schemaregistry.v1+json'}).json() pretty(res) ``` A successful registration returns the schema’s `id`: ```json { "id": 2 } ``` ## [](#reference-a-schema)Reference a schema To build more complex schema definitions, you can add a reference to other schemas. The following example registers a Protobuf schema in subject `test-simple` with a message name `Simple`. ### rpk ```bash rpk registry schema create test-simple --schema simple.proto ``` ```none SUBJECT VERSION ID TYPE test-simple 1 2 PROTOBUF ``` ### Curl ```bash curl -X POST -H 'Content-type: application/vnd.schemaregistry.v1+json' http://127.0.0.1:8081/subjects/test-simple/versions -d '{"schema": "syntax = \"proto3\";\nmessage Simple {\n string id = 1;\n}","schemaType": "PROTOBUF"}' ``` ```json {"id":2} ``` This schema is then referenced in a new schema in a different subject named `import`. ### rpk ```bash # --references flag takes the format {name}:{subject}:{schema version} rpk registry schema create import --schema import_schema.proto --references simple:test-simple:2 ``` ```none SUBJECT VERSION ID TYPE import 1 3 PROTOBUF ``` ### Curl ```bash curl -X POST -H 'Content-type: application/vnd.schemaregistry.v1+json' http://127.0.0.1:8081/subjects/import/versions -d '{"schema": "syntax = \"proto3\";\nimport \"simple\";\nmessage Test3 {\n Simple id = 1;\n}","schemaType": "PROTOBUF", "references": [{"name": "simple", "subject": "test-simple", "version":1}]}' ``` ```json {"id":3} ``` You cannot delete a schema when it is used as a reference. ### rpk ```bash rpk registry schema delete test-simple --schema-version 1 ``` ```none One or more references exist to the schema {magic=1,keytype=SCHEMA,subject=test-simple,version=1} ``` ### Curl ```bash curl -X DELETE -H 'Content-type: application/vnd.schemaregistry.v1+json' http://127.0.0.1:8081/subjects/test-simple/versions/1 ``` ```json {"error_code":42206,"message":"One or more references exist to the schema {magic=1,keytype=SCHEMA,subject=test-simple,version=1}"} ``` Call the `/subjects/test-simple/versions/1/referencedby` endpoint to see the schema IDs that reference version 1 for subject `test-simple`. ### rpk ```bash rpk registry schema references test-simple --schema-version 1 ``` ```none SUBJECT VERSION ID TYPE import 1 3 PROTOBUF ``` ### Curl ```bash curl -H 'Content-type: application/vnd.schemaregistry.v1+json' http://127.0.0.1:8081/subjects/test-simple/versions/1/referencedby ``` ```json [3] ``` ## [](#delete-a-schema)Delete a schema The Schema Registry API provides DELETE endpoints for deleting a single schema or all schemas of a subject: - `/subjects/{subject}/versions/{version}` - `/subjects/{subject}` Schemas cannot be deleted if any other schemas reference it. A schema can be soft deleted (impermanently) or hard deleted (permanently), based on the boolean query parameter `permanent`. A soft deleted schema can be retrieved and re-registered. A hard deleted schema cannot be recovered. ### [](#soft-delete-a-schema)Soft delete a schema To soft delete a schema, make a DELETE request with the subject and version ID (where `permanent=false` is the default parameter value): #### rpk ```bash rpk registry schema delete sensor-value --schema-version 1 ``` #### Curl ```bash curl -s \ -X DELETE \ "http://localhost:8081/subjects/sensor-value/versions/1" \ | jq . ``` #### Python ```python res = requests.delete(f'{base_uri}/subjects/sensor-value/versions/1').json() pretty(res) ``` This returns the ID of the soft deleted schema: #### rpk ```none Successfully deleted schema. Subject: "sensor-value", version: "1" ``` #### Curl ```none 1 ``` Doing a soft delete for an already deleted schema returns an error: #### rpk ```none Subject 'sensor-value' Version 1 was soft deleted. Set permanent=true to delete permanently ``` #### Curl ```json { "error_code": 40406, "message": "Subject 'sensor-value' Version 1 was soft deleted.Set permanent=true to delete permanently" } ``` To list subjects of soft-deleted schemas, make a GET request with the `deleted` parameter set to `true`, `/subjects?deleted=true`: #### rpk ```bash rpk registry subject list --deleted ``` #### Curl ```bash curl -s \ "http://localhost:8081/subjects?deleted=true" \ | jq . ``` #### Python ```python payload = { 'deleted' : 'true' } res = requests.get(f'{base_uri}/subjects', params=payload).json() pretty(res) ``` This returns all subjects, including deleted ones: ```json [ "sensor-value" ] ``` To undo a soft deletion, first follow the steps to [retrieve the schema](#retrieve-a-schema-of-a-subject), then [register the schema](#register-a-schema). ### [](#hard-delete-a-schema)Hard delete a schema > ⚠️ **CAUTION** > > Redpanda doesn’t recommend hard (permanently) deleting schemas in a production system. > > The DELETE APIs are primarily used during the development phase, when schemas are being iterated and revised. To hard delete a schema, use the `--permanent` flag with the `rpk registry schema delete` command, or for curl or Python, make two DELETE requests with the second request setting the `permanent` parameter to `true` (`/subjects/{subject}/versions/{version}?permanent=true`): #### rpk ```bash rpk registry schema delete sensor-value --schema-version 1 --permanent ``` #### Curl ```bash curl -s \ -X DELETE \ "http://localhost:8081/subjects/sensor-value/versions/1" \ | jq . curl -s \ -X DELETE \ "http://localhost:8081/subjects/sensor-value/versions/1?permanent=true" \ | jq . ``` #### Python ```python res = requests.delete(f'{base_uri}/subjects/sensor-value/versions/1').json() pretty(res) payload = { 'permanent' : 'true' } res = requests.delete(f'{base_uri}/subjects/sensor-value/versions/1', params=payload).json() pretty(res) ``` Each request returns the version ID of the deleted schema: #### rpk ```none Successfully deleted schema. Subject: "sensor-value", version: "1" ``` #### Curl ```json 1 1 ``` A request for a hard-deleted schema returns an error: #### rpk ```none Subject 'sensor-value' not found. ``` #### Curl ```json { "error_code": 40401, "message": "Subject 'sensor-value' not found." } ``` ## [](#set-schema-registry-mode)Set Schema Registry mode The `/mode` endpoint allows you to put Schema Registry in read-only, read-write, or import mode. - In read-write mode (the default), you can both register and look up schemas. - In [read-only mode](#use-readonly-mode-for-disaster-recovery), you can only look up schemas. This mode is most useful for standby clusters in a disaster recovery setup. - In [import mode](#use-import-mode-for-migration), you can only register schemas. This mode is most useful for target clusters in a migration setup. If authentication is enabled on Schema Registry, only superusers can change global and subject-level modes. > ⚠️ **CAUTION** > > **Breaking change in Redpanda 25.3:** In Redpanda versions before 25.3, you could specify a schema ID or version when registering a schema in read-write mode. > > Starting with 25.3, read-write mode returns an error when you try to register a schema with a specific ID or version. If you have custom scripts that rely on the ability to specify an ID or version with Redpanda 25.2 and earlier, you must do either of the following: > > - Omit the ID and version fields when registering a schema. The schema will be registered under a new ID and version. > > - Change the Schema Registry or the subject to import mode. ### [](#get-global-mode)Get global mode To [query the global mode](/api/doc/schema-registry/operation/operation-get_mode) for Schema Registry: #### rpk ```bash rpk registry mode get --global ``` #### Curl ```bash curl http://localhost:8081/mode ``` ### [](#set-global-mode)Set global mode Set the mode for Schema Registry at a global level. This mode applies to all subjects that do not have a specific mode set. #### rpk ```bash rpk registry mode set --mode --global ``` #### Curl ```bash curl -X PUT -H "Content-Type: application/vnd.schemaregistry.v1+json" --data '{"mode": }' http://localhost:8081/mode ``` Replace the `` placeholder with the desired mode: - `READONLY` - `READWRITE` - `IMPORT` ### [](#get-mode-for-a-subject)Get mode for a subject To look up the mode for a specific subject: #### rpk ```bash rpk registry mode get ``` #### Curl ```bash curl http://localhost:8081/mode/?defaultToGlobal=true ``` This request returns the mode that is enforced. If the subject is set to a specific mode (to override the global mode), it returns the override mode. Otherwise, it returns the global mode. To retrieve the subject-level override if it exists, use: ```bash curl http://localhost:8081/mode/ ``` This request returns an error if there is no specific mode set for the subject. ### [](#set-mode-for-a-subject)Set mode for a subject #### rpk ```bash rpk registry mode set --mode READONLY ``` #### Curl ```bash curl -X PUT -H "Content-Type: application/vnd.schemaregistry.v1+json" --data '{"mode": "READONLY"}' http://localhost:8081/mode/ ``` ### [](#use-readonly-mode-for-disaster-recovery)Use READONLY mode for disaster recovery A read-only Schema Registry does not accept direct writes. An active production cluster can replicate schemas to a read-only Schema Registry to keep it in sync, for example using Redpanda’s [Schema Migration tool](https://github.com/redpanda-data/schema-migration/). Users in the disaster recovery (DR) site cannot update schemas directly, so the DR cluster has an exact replica of the schemas in production. In a failover due to a disaster or outage, you can set Schema Registry to read-write mode, taking over for the failed cluster and ensuring availability. ### [](#use-import-mode-for-migration)Use IMPORT mode for migration Set the target Schema Registry to import mode to: - Bypass compatibility checks when registering schemas. - Specify a specific schema ID and version for the registered schema, so you can retain the same IDs and version from the original Schema Registry and keep topic data associated with the correct schema. To enable import mode, you must have: - Either superuser access, or a Schema Registry ACL with the `alter_configs` operation on the `registry` resource. See [Enable Schema Registry Authorization](../schema-reg-authorization/#enable-schema-registry-authorization) to learn how to enable schema registry authorization for your cluster. - An empty registry or subject. That is, either no schemas have ever been registered, or you must [hard-delete](#hard-delete-a-schema) all schemas that were registered. To bypass the check for an empty registry when setting the global mode to import: #### rpk ```bash rpk registry mode set --mode IMPORT --global --force ``` #### Curl ```bash curl -X PUT -H "Content-Type: application/vnd.schemaregistry.v1+json" --data '{"mode": "IMPORT"}' http://localhost:8081/mode?force=true ``` Use import mode to register a schema with a specific ID and version: #### rpk ```bash rpk registry schema create --schema order.proto --id 1 --schema-version 4 ``` #### Curl ```bash curl -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" --data '{"schema": "syntax = \"proto3\";\nmessage Order {\n string id = 1;\n}", "schemaType": "PROTOBUF", "id": 1, "version": 4}' http://localhost:8081/subjects//versions ``` ## [](#retrieve-serialized-schemas)Retrieve serialized schemas Starting in Redpanda version 25.2, the following endpoints return serialized schemas (Protobuf only) using the `format=serialized` query parameter: | Operation | Path | | --- | --- | | Retrieve a schema | GET /schemas/ids/{id}?format=serialized | | Check if a schema is already registered for a subject | POST /subjects/{subject}?format=serialized | | Retrieve a subject’s specific version of a schema | GET /subjects/{subject}/versions/{version}?format=serialized | | Get the unescaped schema only for a subject | GET /subjects/{subject}/versions/{version}/schema?format=serialized | The `serialized` format returns the Protobuf schema in its wire binary format in Base64. - Passing an empty string (`format=''`) returns the schema in the current (default) format. - For Avro, `resolved` is a valid value, but it is not currently supported and returns a 501 Not Implemented error. - For Protobuf, `serialized` and `ignore_extensions` are valid, but only `serialized` is currently supported; passing `ignore_extensions` returns a 501 Not Implemented error. - Cross-schema conditions such as `resolved` with Protobuf or `serialized` with Avro are ignored and the schema is returned in the default format. ## [](#generate-a-security-report-for-schema-registry)Generate a security report for Schema Registry Use the [`/v1/security/report`](/api/doc/admin/operation/operation-get_security_report) Admin API endpoint to generate a comprehensive security report for your cluster. This endpoint provides detailed information about TLS configuration, authentication methods, authorization status, and security alerts across all Redpanda interfaces, including Schema Registry. Input ```bash curl 'http://localhost:9644/v1/security/report' ``` View output ```bash { "interfaces": { "kafka": [ { "name": "test_kafka_listener", "host": "0.0.0.0", "port": 9092, "advertised_host": "0.0.0.0", "advertised_port": 9092, "tls_enabled": false, "mutual_tls_enabled": false, "authentication_method": "None", "authorization_enabled": false } ], "rpc": { "host": "0.0.0.0", "port": 33145, "advertised_host": "127.0.0.1", "advertised_port": 33145, "tls_enabled": false, "mutual_tls_enabled": false }, "admin": [ { "name": "test_admin_listener", "host": "0.0.0.0", "port": 9644, "tls_enabled": false, "mutual_tls_enabled": false, "authentication_methods": [], "authorization_enabled": false } ] }, "alerts": [ { "affected_interface": "kafka", "listener_name": "test_kafka_listener", "issue": "NO_TLS", "description": "\"kafka\" interface \"test_kafka_listener\" is not using TLS. This is insecure and not recommended." }, { "affected_interface": "kafka", "listener_name": "test_kafka_listener", "issue": "NO_AUTHN", "description": "\"kafka\" interface \"test_kafka_listener\" is not using authentication. This is insecure and not recommended." }, { "affected_interface": "kafka", "listener_name": "test_kafka_listener", "issue": "NO_AUTHZ", "description": "\"kafka\" interface \"test_kafka_listener\" is not using authorization. This is insecure and not recommended." }, { "affected_interface": "rpc", "issue": "NO_TLS", "description": "\"rpc\" interface is not using TLS. This is insecure and not recommended." }, { "affected_interface": "admin", "listener_name": "test_admin_listener", "issue": "NO_TLS", "description": "\"admin\" interface \"test_admin_listener\" is not using TLS. This is insecure and not recommended." }, { "affected_interface": "admin", "listener_name": "test_admin_listener", "issue": "NO_AUTHZ", "description": "\"admin\" interface \"test_admin_listener\" is not using authorization. This is insecure and not recommended." }, { "affected_interface": "admin", "listener_name": "test_admin_listener", "issue": "NO_AUTHN", "description": "\"admin\" interface \"test_admin_listener\" is not using authentication. This is insecure and not recommended." } ] } ``` ## [](#suggested-reading)Suggested reading - [Redpanda Schema Registry](../schema-reg-overview/) - [rpk registry](../../../reference/rpk/rpk-registry/rpk-registry/) - [Schema Registry API](/api/doc/schema-registry/) - [Broker Configuration Properties](../../../reference/properties/broker-properties/) (search for `schema_registry`) - [Monitor Schema Registry service-level metrics](../../monitoring/#service-level-queries) - [Configure broker properties for Schema Registry](../../cluster-maintenance/node-property-configuration/) - [Deserialization](../../../console/config/deserialization/#schema-registry) --- # Page 223: Schema Registry Authorization **URL**: https://docs.redpanda.com/current/manage/schema-reg/schema-reg-authorization.md --- # Schema Registry Authorization --- title: Schema Registry Authorization latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: schema-reg/schema-reg-authorization page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: schema-reg/schema-reg-authorization.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/schema-reg/schema-reg-authorization.adoc description: Learn how to set up and manage Schema Registry Authorization using ACL definitions that control user access to specific Schema Registry operations. page-git-created-date: "2025-07-30" page-git-modified-date: "2026-01-09" support-status: supported --- Schema Registry Authorization enables fine-grained restriction of operations to Schema Registry resources by user or role through access control lists (ACLs). > 📝 **NOTE** > > This feature requires an [enterprise license](../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../get-started/licensing/#self-managed) apply. ## [](#about-schema-registry-authorization)About Schema Registry Authorization Schema Registry Authorization allows you to control which users and applications can perform specific operations within the Redpanda Schema Registry. This ensures that only authorized entities can read, write, modify, delete, or configure schemas and their settings. Before v25.2, Schema Registry supported authentication, but once a user was authenticated, they had full access to all Schema Registry operations, including reading, modifying, and deleting schemas and configuration both per-subject and globally. Starting in v25.2, Schema Registry Authorization provides fine-grained access control through ACLs. You can now restrict access to specific subjects and operations. ### [](#how-to-manage-schema-registry-authorization)How to manage Schema Registry Authorization You can manage Schema Registry Authorization in the following ways: - **rpk**: Use the [`rpk security acl create`](../../../reference/rpk/rpk-security/rpk-security-acl-create/) command, just like you would for other Kafka ACLs. - **Schema Registry API**: Use the [Redpanda Schema Registry API](/api/doc/schema-registry/operation/operation-get_security_acls) endpoints. - **Redpanda Console**: After enabling Schema Registry Authorization for your cluster, you can use Redpanda Console to manage Schema Registry ACLs. See [Configure Access Control Lists](../../security/authorization/acl/). ### [](#schema-registry-acl-resource-types)Schema Registry ACL resource types Schema Registry Authorization introduces two new ACL resource types in addition to the standard Kafka ACL resources (`topic`, `group`, `cluster`, and `transactional_id`): - `registry`: Controls whether or not to grant ACL access to global, or top-level Schema Registry operations. Specify using the flag `registry-global`. - `subject`: Controls ACL access for specific Schema Registry subjects. Specify using the flag `registry-subject`. ## [](#supported-operations)Supported operations Redpanda Schema Registry ACLs support the following specific subset of Schema Registry endpoints and operations: > 📝 **NOTE** > > Not all Kafka operations are supported when using Redpanda Schema Registry ACLs. | Endpoint | HTTP method | Operation | Resource | | --- | --- | --- | --- | | /config | GET | describe_configs | registry | | /config | PUT | alter_configs | registry | | /config/{subject} | GET | describe_configs | subject | | /config/{subject} | PUT | alter_configs | subject | | /config/{subject} | DELETE | alter_configs | subject | | /mode | GET | describe_configs | registry | | /mode | PUT | alter_configs | registry | | /mode/{subject} | GET | describe_configs | subject | | /mode/{subject} | PUT | alter_configs | subject | | /mode/{subject} | DELETE | alter_configs | subject | | /schemas/types | GET | none/open | - | | /schemas/ids/{id} | GET | read | subject | | /schemas/ids/{id}/versions | GET | describe | registry | | /schemas/ids/{id}/subjects | GET | describe | registry | | /subjects | GET | describe | subject | | /subjects/{subject} | POST | read | subject | | /subjects/{subject} | DELETE | delete | subject | | /subjects/{subject}/versions | GET | describe | subject | | /subjects/{subject}/versions | POST | write | subject | | /subjects/{subject}/versions/{version} | GET | read | subject | | /subjects/{subject}/versions/{version} | DELETE | delete | subject | | /subjects/{subject}/versions/schema | GET | read | subject | | /subjects/{subject}/versions/referencedby | GET | describe | registry | | /compatibility/subjects/{subject}/versions/{version} | POST | read | subject | | /status/ready | GET | none/open | - | | /security/acls | GET | describe | cluster | | /security/acls | POST | alter | cluster | | /security/acls | DELETE | alter | cluster | For additional guidance on these operations, see the [Redpanda Schema Registry API](/api/doc/schema-registry/operation/operation-get_security_acls). ### [](#operation-definitions)Operation definitions You can use the following operations to control access to Schema Registry resources: - **`read`**: Allows user to read schemas and their content. Required for consuming messages that use Schema Registry, fetching specific schema versions, and reading schema content by ID. - **`write`**: Allows user to register new schemas and schema versions. Required for producing messages with new schemas and updating existing subjects with new schema versions. - **`delete`**: Allows user to delete schema versions and subjects. Required for cleanup operations and removing deprecated schemas. - **`describe`**: Allows user to list and describe Schema Registry resources. Required for discovering available subjects, listing schema versions, and viewing metadata. - **`describe_configs`**: Allows user to read configuration settings. Required for viewing compatibility settings, reading modes (IMPORT/READWRITE), and checking global or per-subject configurations. - **`alter_configs`**: Allows user to modify configuration settings. Required for changing compatibility levels, setting IMPORT mode for migrations, and updating global or per-subject configurations. ### [](#common-use-cases)Common use cases The following examples show which operations are required for common Schema Registry tasks: #### [](#schema-registry-migration)Schema Registry migration When migrating schemas between clusters, you must have **different ACLs for source and target clusters**. **Source cluster (read-only):** ```bash # Read schemas from source Schema Registry rpk security acl create \ --allow-principal User:migrator-user \ --operation read,describe \ --registry-global \ --brokers ``` This grants: - `read` - Read schemas by ID from source - `describe` - List all subjects in source > 📝 **NOTE** > > The `describe_configs` operation is required to read Schema Registry configuration settings, including compatibility modes and IMPORT mode status. **Target cluster (read-write):** ```bash # Write schemas to target Schema Registry and manage IMPORT mode rpk security acl create \ --allow-principal User:migrator-user \ --operation write,describe,alter_configs,describe_configs \ --registry-global \ --brokers ``` This grants: - `write` - Register schemas in target with preserved IDs - `describe` - List all subjects in target - `alter_configs` - Set IMPORT mode on target Schema Registry - `describe_configs` - Read compatibility settings and mode > ❗ **IMPORTANT** > > **Schema Registry ACLs are only for Schema Registry operations.** For complete data migration, you must also use Kafka ACLs: > > - **Topics:** READ (source), WRITE/CREATE/DESCRIBE/ALTER (target) > > - **Consumer groups:** READ (source), CREATE/READ (target) > > - **Cluster:** DESCRIBE (both), CREATE (target) > > > See [Configure Access Control Lists](../../security/authorization/acl/) for Kafka ACL configuration. > 📝 **NOTE** > > The target Schema Registry must be in IMPORT mode to preserve schema IDs during migration. Only superusers or principals with `alter_configs` permission on the `registry` resource can change the global mode. See [Set global mode](../schema-reg-api/#set-global-mode). #### [](#complete-migration-setup-workflow)Complete migration setup workflow For a complete migration setup, follow this workflow: 1. **Bootstrap superusers** - Configure superusers using `.bootstrap.yaml` before enabling authentication 2. **Create migration user** - Create dedicated migration user with minimal required permissions 3. **Configure Schema Registry ACLs** - Grant read access on source, read-write access on target 4. **Configure Kafka ACLs** - Grant topic read/write, consumer group, and cluster permissions 5. **Enable SASL authentication** - Enable SASL/SCRAM-SHA-256 on both clusters 6. **Enable ACL authorization** - Enable `kafka_enable_authorization` and `schema_registry_enable_authorization` 7. **Set target to IMPORT mode** - Enable IMPORT mode on target Schema Registry 8. **Start migration** - Begin data and schema migration 9. **Verify ACLs** - Test that permissions work correctly and restrictions are enforced 10. **Complete migration** - Disable IMPORT mode after migration completes For a complete working example with Docker Compose, see the [Redpanda Migrator Demo](https://github.com/redpanda-data/redpanda-labs/tree/main/docker-compose/redpanda-migrator-demo). > 📝 **NOTE** > > **Schema Registry Internal Client Authentication:** When SASL authentication is enabled on your Kafka cluster, the Schema Registry’s internal Kafka client must also be configured with SASL credentials. Configure these using node-level properties: > > ```bash > --set schema_registry_client.scram_username= > --set schema_registry_client.scram_password= > --set schema_registry_client.sasl_mechanism=SCRAM-SHA-256 > ``` > > Without these credentials, Schema Registry operations that interact with Kafka (like storing schema data) will fail with "broker\_not\_available" errors. #### [](#read-only-access-for-consumers)Read-only access for consumers Applications that only consume messages with schemas require: ```bash # For consuming with schema validation rpk security acl create \ --allow-principal consumer-app \ --operation read \ --registry-subject "orders-*" \ --resource-pattern-type prefixed ``` This allows: - Reading schema content by ID (embedded in messages) - Viewing specific schema versions This does _not_ allow listing all subjects or modifying schemas. #### [](#producer-access)Producer access Applications that produce messages with schemas require: ```bash # For producing with new schemas rpk security acl create \ --allow-principal producer-app \ --operation read,write,describe \ --registry-subject "orders-*" \ --resource-pattern-type prefixed ``` This allows: - Checking if schemas already exist (`describe`) - Reading existing schema versions (`read`) - Registering new schema versions (`write`) #### [](#schema-administrator-access)Schema administrator access Schema administrators who manage compatibility and cleanup require: ```bash # For full schema management rpk security acl create \ --allow-principal schema-admin \ --operation all \ --registry-global ``` This grants all operations, including: - Managing compatibility settings - Deleting deprecated schemas - Viewing and modifying configurations - Listing all subjects and schemas ### [](#pattern-based-acls-for-schema-registry)Pattern-based ACLs for Schema Registry When using subject name patterns (like `orders-*`), always specify `--resource-pattern-type prefixed`: ```bash # Correct - matches all subjects starting with "orders-" rpk security acl create \ --allow-principal User:app \ --operation read \ --registry-subject "orders-" \ --resource-pattern-type prefixed # Incorrect - treats "orders-*" as literal subject name rpk security acl create \ --allow-principal User:app \ --operation read \ --registry-subject "orders-*" ``` Pattern types: - **`prefixed`** - Matches subjects starting with the specified string (for example, `orders-` matches `orders-value`, `orders-key`) - **`literal`** - Matches exact subject name only (default if not specified) > 💡 **TIP** > > Redpanda recommends using the topic naming strategy where subjects follow the pattern `-key` or `-value`. With this strategy, you can use a single prefixed ACL to grant access to both key and value subjects for a topic. > > Example: `--registry-subject "orders-" --resource-pattern-type prefixed` grants access to both `orders-key` and `orders-value` subjects. ## [](#enable-schema-registry-authorization)Enable Schema Registry Authorization ### [](#prerequisites)Prerequisites Before you can enable Schema Registry Authorization, you must have: - A valid Redpanda Enterprise license. - `rpk` v25.2+ installed. For installation instructions, see [rpk installation](../../../get-started/rpk-install/). - Authentication enabled using `schema_registry_api.authn_method`, which specifies how clients must authenticate when accessing the Schema Registry API. See [Schema Registry broker properties](../../../reference/properties/broker-properties/#schema-registry). - If you have listeners configured for Schema Registry, ensure you [configure authentication](../../security/authentication/#basic-authentication) for them and that your configuration points to the correct Schema Registry address (correct scheme, host, and port) for the same cluster you are targeting with your Kafka brokers. - Cluster administrator permissions to modify cluster configurations. For example, to enable management of Schema Registry ACLs by the principal `schema_registry_admin`, run: + \[,bash\] ---- rpk security acl create --allow-principal schema\_registry\_admin --cluster --operation alter ---- ### [](#enable-authorization)Enable authorization To enable Schema Registry Authorization for your cluster, run: ```bash rpk cluster config set schema_registry_enable_authorization true ``` For details, see [`schema_registry_enable_authorization`](../../../reference/properties/cluster-properties/#schema_registry_enable_authorization). ## [](#create-and-manage-schema-registry-acls)Create and manage Schema Registry ACLs This section shows you how to create and manage ACLs for Schema Registry resources. ### [](#create-an-acl-for-a-topic-and-schema-registry-subject)Create an ACL for a topic and Schema Registry subject This example creates an ACL that allows the principal `panda` to read from both the topic `bar` and the Schema Registry subject `bar-value`. This pattern is common when you want to give a user or application access to both the Kafka topic and its associated schema. ```bash rpk security acl create --allow-principal panda --operation read --topic bar --registry-subject bar-value PRINCIPAL HOST RESOURCE-TYPE RESOURCE-NAME RESOURCE-PATTERN-TYPE OPERATION PERMISSION ERROR User:panda * SUBJECT bar-value LITERAL READ ALLOW User:panda * TOPIC bar LITERAL READ ALLOW ``` ### [](#create-an-acl-for-global-schema-registry-access)Create an ACL for global Schema Registry access This example grants the user `jane` global read and write access to the Schema Registry, plus read and write access to the topic `private`. The `--registry-global` flag creates ACLs for all [global Schema Registry operations](#supported-operations). ```bash rpk security acl create --allow-principal jane --operation read,write --topic private --registry-global PRINCIPAL HOST RESOURCE-TYPE RESOURCE-NAME RESOURCE-PATTERN-TYPE OPERATION PERMISSION ERROR User:jane * REGISTRY LITERAL READ ALLOW User:jane * REGISTRY LITERAL WRITE ALLOW User:jane * TOPIC private LITERAL READ ALLOW User:jane * TOPIC private LITERAL WRITE ALLOW ``` User `jane` now has global `read` and `write` access to the Schema Registry and to the topic `private`. ### [](#create-a-role-with-schema-registry-acls)Create a role with Schema Registry ACLs You can combine Schema Registry ACLs with [role-based access control (RBAC)](../../security/authorization/rbac/) to create reusable roles. This approach simplifies permission management when you need to assign the same set of permissions to multiple users. This example creates a role called `SoftwareEng` and assigns it ACLs for both topic and Schema Registry access: > 📝 **NOTE** > > Redpanda recommends using the topic naming strategy for Schema Registry subjects, where subjects follow the pattern `-key` or `-value`. For details, see [Set subject name strategy per topic](../schema-id-validation/#set-subject-name-strategy-per-topic). ```bash # Create the role rpk security role create SoftwareEng # Create ACLs for the role rpk security acl create \ --operation read,write \ --topic private \ --registry-subject private-key,private-value \ --allow-role SoftwareEng # You can add more ACLs to this role later rpk security acl create --allow-role "SoftwareEng" [additional-acl-flags] ``` After creating the role, assign it to users: ```bash rpk security role assign SoftwareEng --principal User:john,User:jane Successfully assigned role "SoftwareEng" to NAME PRINCIPAL-TYPE john User jane User ``` ### [](#troubleshooting-acl-creation)Troubleshooting ACL creation When creating ACLs that include Schema Registry subjects, you might encounter errors if the subject doesn’t exist or if there are configuration issues. #### [](#subject-not-found)Subject not found Sometimes an ACL for a Kafka topic is created successfully, but the Schema Registry subject ACL fails: ```bash rpk security acl create --allow-principal alice --operation read --topic bar --registry-subject bar-value PRINCIPAL HOST RESOURCE-TYPE RESOURCE-NAME RESOURCE-PATTERN-TYPE OPERATION PERMISSION ERROR User:alice * SUBJECT bar-value LITERAL READ ALLOW Not found User:alice * TOPIC bar LITERAL READ ALLOW ``` In this example, the ACL for topic `bar` was created successfully, but the ACL for Schema Registry subject `bar-value` failed with a "Not found" error. **Common causes:** - Incorrect Schema Registry URL configuration - Using the incorrect version of Redpanda #### [](#debugging-with-verbose-output)Debugging with verbose output To get more detailed information about ACL creation failures, use the `-v` flag for verbose logging. In this case, the user gets a `Not found` error after attempting to create two ACLs, one for the subject and one for the topic: ```bash rpk security acl create --allow-principal alice --operation read --topic bar --registry-subject bar-value -v 12:17:33.911 DEBUG opening connection to broker {"addr": "127.0.0.1:9092", "broker": "seed_0"} 12:17:33.912 DEBUG connection opened to broker {"addr": "127.0.0.1:9092", "broker": "seed_0"} 12:17:33.912 DEBUG issuing api versions request {"broker": "seed_0", "version": 4} 12:17:33.912 DEBUG wrote ApiVersions v4 {"broker": "seed_0", "bytes_written": 31, "write_wait": 13.416µs", "time_to_write": "17.75µs", "err": null} 12:17:33.912 DEBUG read ApiVersions v4 {"broker": "seed_0", "bytes_read": 266, "read_wait": 16.209µs", "time_to_read": "8.360666ms", "err": null} 12:17:33.920 DEBUG connection initialized successfully {"addr": "127.0.0.1:9092", "broker": "seed_0"} 12:17:33.920 DEBUG wrote CreateACLs v2 {"broker": "seed_0", "bytes_written": 43, "write_wait": 9.0985ms, "time_to_write": "14µs", "err": null} 12:17:33.935 DEBUG read CreateACLs v2 {"broker": "seed_0", "bytes_read": 19, "read_wait": 23.792µs, "time_to_read": "14.323041ms", "err": null} 12:17:33.935 DEBUG sending request {"method": "POST", "URL: "http://127.0.0.1:8081/security/acls", "has_bearer": false, "has_basic_auth": false} PRINCIPAL HOST RESOURCE-TYPE RESOURCE-NAME RESOURCE-PATTERN-TYPE OPERATION PERMISSION ERROR User:alice * SUBJECT bar-value LITERAL READ ALLOW Not found User:alice * TOPIC bar LITERAL READ ALLOW ``` The `Not found` error occurs in the request: `12:17:33.935 DEBUG sending request {"method": "POST", "URL: "http://127.0.0.1:8081/security/acls", "has_bearer": false, "has_basic_auth": false}`. This typically means the endpoint is unavailable. Verify: - You’re on Redpanda v25.2+. - `schema_registry_enable_authorization` is set to `true`. - Your rpk Schema Registry URL points to the correct host/scheme/port. Upgrade if needed and correct configuration before retrying. #### [](#inconsistent-listener-configuration)Inconsistent listener configuration This error occurs when the user tries to create an ACL for a principal: ```bash rpk security acl create --allow-principal "superuser" --operation "all" --registry-global -v 13:07:02.810 DEBUG opening connection to broker {"addr": "seed-036d6a67.d2hiu9c8ljef72usuu20.fmc.prd.cloud.redpanda.com:9092", "broker": "seed_0"} ... 13:07:03.304 DEBUG sending request {"method": "POST", "URL": "https://127.0.0.1:8080/security/acls", "has_bearer": false, "has_basic_auth": true} PRINCIPAL HOST RESOURCE-TYPE RESOURCE-NAME RESOURCE-PATTERN-TYPE OPERATION PERMISSION ERROR User:superuser * REGISTRY LITERAL ALL ALLOW unable to POST "https://127.0.0.1:8080/security/acls": Post "https://127.0.0.1:8080/security/acls": http: server gave HTTP response to HTTPS client ``` When using Schema Registry Authorization, ensure that your Kafka brokers and Schema Registry address target the same cluster and that the Schema Registry address uses the correct scheme/host/port. In the example above, `rpk` communicates with a remote broker (`…​:9092`) but posts to a local Schema Registry address over HTTPS (`[https://127.0.0.1:8080/security/acls](https://127.0.0.1:8080/security/acls)`), while the local Schema Registry appears to be HTTP-only. To align them: \* Set the correct Schema Registry address (host and scheme) for the target cluster. \* Ensure TLS settings match the Schema Registry endpoint (HTTP vs HTTPS). \* Avoid mixing remote broker addresses with a local Schema Registry address unless it is intentional and properly configured. See [rpk registry](../../../reference/rpk/rpk-registry/rpk-registry/) for Schema Registry configuration commands. #### [](#resource-names-do-not-appear)Resource names do not appear The following output appears to suggest that there are missing resource names for the registry resource types: ```bash rpk security acl create --allow-principal jane --operation read,write --topic private --registry-global PRINCIPAL HOST RESOURCE-TYPE RESOURCE-NAME RESOURCE-PATTERN-TYPE OPERATION PERMISSION ERROR User:jane * REGISTRY LITERAL READ ALLOW User:jane * REGISTRY LITERAL WRITE ALLOW User:jane * TOPIC private LITERAL READ ALLOW User:jane * TOPIC private LITERAL WRITE ALLOW ``` When using the `--registry-global` option, be aware that `REGISTRY` resource types are global and apply to all of Schema Registry. They do not have a resource name because they are not tied to a specific resource. There are no resource names missing here. #### [](#schema-registry-broker_not_available-errors)Schema Registry "broker\_not\_available" errors If Schema Registry operations fail with `broker_not_available` errors after enabling SASL: ```bash {"error_code":50302,"message":"{ node: -1 }, { error_code: broker_not_available [8] }"} ``` **Cause:** The Schema Registry’s internal Kafka client is not configured with SASL credentials. **Solution:** Configure the Schema Registry client credentials: ```bash rpk cluster config set schema_registry_client.scram_username rpk cluster config set schema_registry_client.scram_password rpk cluster config set schema_registry_client.sasl_mechanism SCRAM-SHA-256 ``` Then restart the Schema Registry service. #### [](#pattern-based-acl-not-working)Pattern-based ACL not working If a pattern-based ACL (like `orders-*`) is not matching expected subjects: **Cause:** Missing `--resource-pattern-type prefixed` flag. **Solution:** Recreate the ACL with the correct pattern type: ```bash # Delete incorrect ACL rpk security acl delete \ --allow-principal User:app \ --operation read \ --registry-subject "orders-*" # Create correct ACL with pattern type rpk security acl create \ --allow-principal User:app \ --operation read \ --registry-subject "orders-" \ --resource-pattern-type prefixed ``` > 📝 **NOTE** > > Pattern matching uses the string without the asterisk when using `prefixed` type. ## [](#suggested-reading)Suggested reading - [Redpanda Schema Registry](../schema-reg-overview/) - [rpk registry](../../../reference/rpk/rpk-registry/rpk-registry/) - [Schema Registry API](/api/doc/schema-registry/) - [Broker Configuration Properties](../../../reference/properties/broker-properties/) (search for `schema_registry`) - [Monitor Schema Registry service-level metrics](../../monitoring/#service-level-queries) - [Configure broker properties for Schema Registry](../../cluster-maintenance/node-property-configuration/) - [Deserialization](../../../console/config/deserialization/#schema-registry) --- # Page 224: Redpanda Schema Registry **URL**: https://docs.redpanda.com/current/manage/schema-reg/schema-reg-overview.md --- # Redpanda Schema Registry --- title: Redpanda Schema Registry latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: schema-reg/schema-reg-overview page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: schema-reg/schema-reg-overview.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/schema-reg/schema-reg-overview.adoc description: Redpanda's Schema Registry provides the interface to store and manage event schemas. page-git-created-date: "2023-11-16" page-git-modified-date: "2025-08-20" support-status: supported --- In Redpanda, the messages exchanged between producers and consumers contain raw bytes. Schemas enable producers and consumers to share the information needed to serialize and deserialize those messages. They register and retrieve the schemas they use in the Schema Registry to ensure data verification. Schemas are versioned, and the registry supports configurable compatibility modes between schema versions. When a producer or a consumer requests to register a schema change, the registry checks for schema compatibility and returns an error for an incompatible change. Compatibility modes can ensure that data flowing through a system is well-structured and easily evolves. > ❗ **IMPORTANT** > > **Schema size best practice**: Schema Registry works best with schemas of 128KB in size or less. Large schemas can consume significant memory resources and may cause system instability or crashes, particularly in memory-constrained environments. For Protobuf and Avro schemas, Redpanda recommends using schema [references](../schema-reg-api/#reference-a-schema) to break up large schemas into smaller constituent parts. > 📝 **NOTE** > > The Schema Registry is built directly into the Redpanda binary. It runs out of the box with Redpanda’s default configuration, and it requires no new binaries to install and no new services to deploy or maintain. You can use it with the [Schema Registry API](../schema-reg-api/) or [Redpanda Console](../../../console/ui/schema-reg/). ## [](#schema-terminology)Schema terminology **Schema**: A schema is an external mechanism to describe the structure of data and its encoding. Producer clients and consumer clients use a schema as an agreed-upon format for sending and receiving messages. Schemas enable a loosely coupled, data-centric architecture that minimizes dependencies in code, between teams, and between producers and consumers. **Subject**: A subject is a logical grouping for schemas. When data formats are updated, a new version of the schema can be registered under the same subject, allowing for backward and forward compatibility. A subject may have more than one schema version assigned to it, with each schema having a different numeric ID. **Serialization format**: A serialization format defines how data is converted into bytes that are transmitted and stored. Serialization, by producers, converts an event into bytes. Redpanda then stores these bytes in topics. Deserialization, by consumers, converts the bytes of arrays back into the desired data format. Redpanda’s Schema Registry supports Avro, Protobuf, and JSON serialization formats. **Normalization**: Normalization is the process of converting a schema into a canonical form. When a schema is normalized, it can be compared and considered equivalent to another schema that may contain minor syntactic differences. Schema normalization allows you to more easily manage schema versions and compatibility by prioritizing meaningful logical changes. Normalization is supported for Avro, JSON, and Protobuf formats during both schema registration and lookup for a subject. ## [](#redpanda-design-overview)Redpanda design overview Every broker allows mutating REST calls, so there’s no need to configure leadership or failover strategies. Schemas are stored in a compacted topic, and the registry uses optimistic concurrency control at the topic level to detect and avoid collisions. > ❗ **IMPORTANT** > > The Schema Registry publishes an internal topic, `_schemas`, as its backend store. This internal topic is reserved strictly for schema metadata and support purposes. **Do not directly edit or manipulate the `_schemas` topic unless directed to do so by Redpanda Support.** See the [kafka\_nodelete\_topics](../../../reference/properties/cluster-properties/#kafka_nodelete_topics) cluster property. Redpanda Schema Registry uses the default port 8081. ## [](#wire-format)Wire format With Schema Registry, producers and consumers can use a specific message format, called the wire format. The wire format facilitates a seamless transfer of data by ensuring that clients easily access the correct schema in the Schema Registry for a message. The wire format is a sequence of bytes consisting of the following: 1. The "magic byte," a single byte that always contains the value of 0. 2. A four-byte integer containing the schema ID. 3. The rest of the serialized message. ![Schema Registry wire format](../../../shared/_images/schema-registry-wire-format.png) In the serialization process, the producer hands over the message to a key/value serializer that is part of the respective language-specific SDK. The serializer first checks whether the schema ID for the given subject exists in the local schema cache. The serializer derives the subject name based on several [strategies](../schema-id-validation/#set-subject-name-strategy-per-topic), such as the topic name. You can also explicitly set the subject name. If the schema ID isn’t in the cache, the serializer registers the schema in the Schema Registry and collects the resulting schema ID in the response. In either case, when the serializer has the schema ID, it pads the beginning of the message with the magic byte and the encoded schema ID, and returns the byte sequence to the producer to write to the topic. In the deserialization process, the consumer fetches messages from the broker and hands them over to a deserializer. The deserializer first checks the presence of the magic byte and rejects the message if it doesn’t follow the wire format. The deserializer then reads the schema ID and checks whether that schema exists in its local cache. If it finds the schema, it deserializes the message according to that schema. Otherwise, the deserializer retrieves the schema from the Schema Registry using the schema ID, then the deserializer proceeds with deserialization. You can also configure brokers to validate that producers use the wire format and the schema exists (but brokers do not validate the full payload). See [Server-Side Schema ID Validation](../schema-id-validation/) for more information. ## [](#schema-examples)Schema examples To experiment with schemas from applications, see the clients in [redpanda-labs](https://github.com/redpanda-data/redpanda-labs/tree/main). For a basic end-to-end example, the following Protobuf schema contains information about products: a unique ID, name, price, and category. It has a schema ID of 1, and the Topic name strategy, with a topic of Orders. (The Topic strategy is suitable when you want to group schemas by the topics to which they are associated.) ```json syntax = "proto3"; message Product { int32 ProductID = 1; string ProductName = 2; double Price = 3; string Category = 4; } ``` The producer then does something like this: ```json from kafka import KafkaProducer from productpy import Product # This imports the prototyped schema # Create a Kafka producer producer = KafkaProducer(bootstrap_servers='your_kafka_brokers') # Create a Product message product_message = Product( ProductID=123, ProductName="Example Product", Price=45.99, Category="Electronics" ) # Produce the Product message to the "Orders" topic producer.send('Orders', key='product_key', value=product_message.SerializeToString()) ``` To add an additional field for product variants, like size or color, the new schema (version 2, ID 2) would look like this: ```json syntax = "proto3"; message Product { int32 ProductID = 1; string ProductName = 2; double Price = 3; string Category = 4; repeated string Variants = 5; } ``` You would want the compatibility setting to accommodate adding new fields without breakage. Adding an optional new field to a schema is inherently backward-compatible. New consumers can process events written with the new schema, and older consumers can ignore it. ## [](#json-schema)JSON Schema All CRUD operations are supported for the JSON Schema (`json-schema`), and Redpanda supports [all published JSON Schema specifications](https://json-schema.org/specification), which include: - draft-04 - draft-06 - draft-07 - 2019-09 - 2020-12 ### [](#limitations)Limitations Schemas are held in subjects. Subjects have a compatibility configuration associated with them, either directly specified by a user, or inherited by the default. See `PUT /config` and `PUT/config/{subject}` in the [Schema Registry API](/api/doc/schema-registry/). If you have inserted a second schema into a subject where the compatibility level is anything but `NONE`, then any JSON Schema containing the following items are rejected: - `$ref` - `$defs` (`definitions` prior to draft 2019-09) - `dependentSchemas` / `dependentRequired` (`dependencies` prior to draft 2019-09) - `prefixItems` Consequently, you cannot [structure a complex schema](https://json-schema.org/understanding-json-schema/structuring) using these features. Additionally, you cannot have [schema ID validation](../schema-id-validation/#about-schema-id-validation) with JSON schemas if the [subject name strategy](../schema-id-validation/#set-subject-name-strategy-per-topic) _is not_ `TopicNameStrategy`. ## [](#next-steps)Next steps - [Use the Schema Registry API](../schema-reg-api/) ## [](#suggested-reading)Suggested reading - [Schema Registry API](/api/doc/schema-registry/) - [Deserialization](../../../console/config/deserialization/) - [Broker Configuration Properties](../../../reference/properties/broker-properties/) (search for `schema_registry`) - [Monitor Schema Registry service-level metrics](../../monitoring/#service-level-queries) - [Configure broker properties for Schema Registry](../../cluster-maintenance/node-property-configuration/) --- # Page 225: Security **URL**: https://docs.redpanda.com/current/manage/security.md --- # Security --- title: Security latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: security/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: security/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/security/index.adoc description: Learn how to configure authentication, authorization, encryption, listeners, and other security features. page-git-created-date: "2023-06-02" page-git-modified-date: "2025-11-19" support-status: supported --- Learn how to configure authentication, authorization, encryption, listeners, and other security features. This section does not cover ways you can protect your Redpanda cluster externally; for example, through network ACLs or private networks. - [Configure Authentication](authentication/) Redpanda supports multiple forms of authentication including SASL/SCRAM, mTLS with principal mapping, and basic authentication. - [Configure Authorization](authorization/) Redpanda provides mechanisms for controlling user permissions, including ACLs, role-based access control, and group-based access control. - [Configure Redpanda for FIPS](fips-compliance/) Configure Redpanda to operate in FIPS-compliant mode. - [Configure Kafka TLS Encryption](encryption/) Enable encryption with TLS or mTLS. - [Configure Listeners](listener-configuration/) Use listeners to advertise the location of the broker, so other brokers in the cluster can be found. - [IAM Roles](iam-roles/) For Redpanda Self-Managed clusters deployed on a public cloud platform, cloud provider IAM roles and managed identities provide a safer alternative to the less secure static credential system, which is based on access keys. --- # Page 226: Configure Authentication **URL**: https://docs.redpanda.com/current/manage/security/authentication.md --- # Configure Authentication --- title: Configure Authentication latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: security/authentication page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: security/authentication.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/security/authentication.adoc description: Redpanda supports multiple forms of authentication including SASL/SCRAM, mTLS with principal mapping, and basic authentication. page-git-created-date: "2023-06-02" page-git-modified-date: "2025-07-31" support-status: supported --- Authentication verifies the identity of users and applications that connect to Redpanda clusters. Different Redpanda APIs support different authentication methods. You can configure multiple listeners for each API, and you can configure each listener with an authentication method. Redpanda APIs support these authentication methods: | API | Supported Authentication Methods | | --- | --- | | Kafka API | SASLSASL/SCRAMSASL/PLAINSASL/OAUTHBEARER (OIDC)SASL/GSSAPI (Kerberos)mTLS | | Admin API | Basic authenticationOIDC | | HTTP Proxy (PandaProxy) | Basic authenticationOIDC | | Schema Registry | Basic authenticationOIDC | ## [](#principals)Users, principals, and superusers When you configure authentication and authorization in Redpanda, it’s important to understand the distinction between **users**, **principals**, and **superusers**: - A user refers to a stored credential within Redpanda, typically a username and password stored in the internal SASL credential store. These are created using commands such as `rpk security user create`. - A principal is the authenticated identity string associated with a client session. It’s what Redpanda uses for access control, ACLs, and superuser assignment. - A superuser is a privileged principal who has unrestricted access to [all operations](../authorization/#operations) in a Redpanda cluster. Superusers can: - Grant or revoke permissions to other users through ACLs. - Access all Admin API endpoints. - Create, modify, or delete topics and consumer groups. - View and manage the cluster’s internal state. Depending on how a client authenticates, the principal might be: - The SCRAM username - A claim from a JWT - A certificate DN - A Kerberos identity You assign ACLs and superuser roles to principals, not users. Even if a user exists, they have no access unless its associated principal is granted permissions. For example, with OIDC: Configure superusers and ACL rules using the exact value from your OIDC token’s sub (subject) claim. For example, if your token’s sub claim is [example@company.com](mailto:example@company.com), use that exact value in your configuration. OIDC principals use the value extracted from the token’s claims according to your configured principal mapping. SASL users require the User: prefix, but OIDC principals do not use any prefix. ## [](#enable)Enable authentication To enable authentication in Redpanda, you must: - [Create at least one superuser](#create-superusers). - [Enable SASL authentication](#enable-sasl-authentication). ### [](#create-superusers)Create superusers Before enabling authorization in Redpanda, which can happen implicitly when you enable authentication, you must create a superuser. Without a superuser, you can create other users, but you can’t grant them permissions to the cluster. > ❗ **IMPORTANT** > > Enabling authorization without a superuser can result in being locked out of the cluster, as you would not have the necessary permissions to manage the cluster’s settings or users. A superuser can either be a SCRAM user or it can be provided by external authentication mechanisms, such as OIDC. However, `rpk` can only communicate with the Admin API using HTTP basic authentication, which requires a SCRAM user. This means that for administrative tasks executed through `rpk`, you must have a SCRAM user with superuser privileges. 1. Specify the username of a superuser. ```bash rpk cluster config set superusers '["superuser-username"]' ``` This can be a new user or an existing user. For example, if you use the superuser named `admin`, then Redpanda allows the `admin` user to do anything, but Redpanda does not create the `admin` user. 2. Create a SCRAM superuser: ```bash rpk security user create \ -p '' \ --mechanism= \ -X admin.hosts=localhost:9644 ``` Replace `` with a SCRAM authentication mechanism. Valid values are `SCRAM-SHA-256` or `SCRAM-SHA-512`. The Admin API defaults to `localhost:9644`. If you’ve configured the Admin API to use a different address/port, use the `-X admin.hosts=` flag. Now this user has full access to the cluster and can grant permissions to other users. For information about using `rpk` to manage ACL users, see [rpk security acl](../../../reference/rpk/rpk-security/rpk-security-acl/). > 📝 **NOTE** > > As a security best practice: > > - Don’t use the superuser to interact with the cluster. > > - Don’t delete the superuser (in case you need to grant permissions to new users later). > > When you create the superuser, you specify a password, which adds a level of security. If you delete the user, someone else could re-create the user with a different password. #### [](#edit-superusers)Edit superusers To edit a superuser, use the following command to apply the new value: ```bash rpk cluster config edit ``` ### [](#enable-sasl-authentication)Enable SASL authentication To enable authentication in your Redpanda cluster, you have the following options, depending on your requirements for SASL authentication and authorization. > 📝 **NOTE** > > You must [create at least one superuser](#create-superusers) before enabling authentication. Enabling authentication without a superuser can result in being locked out of the cluster. - Enable SASL authentication for all Kafka listeners: Use this method if you haven’t already enabled authentication and you want to apply SASL authentication to all Kafka listeners. This approach does not require you to restart the cluster. > 📝 **NOTE** > > This command implicitly enables authorization. If you want to disable authorization, you can use the `kafka_enable_authorization` cluster configuration property. ```bash rpk cluster config set enable_sasl true ``` - Explicitly enable authorization and define authentication method per listener: Choose this method if you require specific control over the authentication method for each Kafka listener, or if you need to enable authorization explicitly. This option requires a cluster restart. 1. Enable authorization: ```bash rpk cluster config set kafka_enable_authorization true ``` 2. Define the authentication method for each listener. See [Authentication for the Kafka API](#authentication-for-the-kafka-api) and [Authentication for the HTTP APIs](#authentication-for-the-http-apis). For detailed information about these and other cluster configurations, see [Configure Cluster Properties](../../cluster-maintenance/cluster-property-configuration/). ## [](#authentication-for-the-kafka-api)Authentication for the Kafka API Redpanda supports the following authentication methods for the Kafka API: - [SASL](#sasl) (Simple Authentication and Security Layer) - [mTLS](#mtls) (Mutual Transport Layer Security) ### [](#sasl)SASL SASL provides a flexible and adaptable framework for implementing various authentication mechanisms. Redpanda supports these SASL mechanisms: - [SASL/SCRAM](#scram) - [SASL/PLAIN](#plain) - [SASL/OAUTHBEARER](#oidc) (OpenID Connect, also known as OIDC) - [SASL/GSSAPI](#kerberos) (Kerberos) > 📝 **NOTE** > > Redpanda provides an option to configure different SASL authentication mechanisms for specific listeners. For example, you could specify SCRAM for internal traffic and OAUTHBEARER for external clients. For details, see [sasl\_mechanisms\_overrides](../../../reference/properties/cluster-properties/#sasl_mechanisms_overrides). #### [](#enable-sasl)Enable SASL To enable SASL authentication for the Kafka API, set the [`authentication_method`](../../../reference/properties/broker-properties/#kafka_api_auth_method) broker property of the Kafka listeners to `sasl`. If you [enabled authentication with `enable_sasl=true`](#enable-sasl-authentication), Redpanda implicitly sets [`authentication_method`](../../../reference/properties/broker-properties/#kafka_api_auth_method) to `sasl` for the Kafka listeners. If you [enabled authentication with `kafka_enable_authorization=true`](#enable-sasl-authentication), you must enable SASL for the Kafka listeners. In `redpanda.yaml`, enter: ```yaml redpanda: kafka_api: - address: 0.0.0.0 port: 9092 name: sasl_listener authentication_method: sasl ``` #### [](#enable-sasl-with-tls-encryption)Enable SASL with TLS encryption SASL provides authentication, but not encryption. To provide encryption, you can enable TLS in addition to SASL. See [Configure Kafka TLS Encryption](../encryption/). For example, to enable SASL authentication with TLS encryption for the Kafka API, in `redpanda.yaml`, enter: ```yaml redpanda: kafka_api: - address: 0.0.0.0 port: 9092 name: sasl_tls_listener authentication_method: sasl kafka_api_tls: - name: sasl_tls_listener key_file: broker.key cert_file: broker.crt truststore_file: ca.crt crl_file: ca.crl # Optional enabled: true require_client_auth: false ``` #### [](#scram)SASL/SCRAM SASL/SCRAM does not require sending passwords over the network, even in an encrypted form. It uses a challenge-response mechanism, ensuring that the password is not directly accessible to the server. It works with hashed passwords, providing additional security against dictionary attacks. ##### [](#enable-saslscram)Enable SASL/SCRAM SASL/SCRAM is enabled by default. To check if SASL/SCRAM is enabled: ```bash rpk cluster config get sasl_mechanisms ``` You should see `SCRAM` in the output. If SASL/SCRAM is not enabled, enable it by appending `SCRAM` to the list of SASL mechanisms: ```bash rpk cluster config set sasl_mechanisms '["SCRAM"]' ``` ##### [](#create-scram-users)Create SCRAM users When you have SASL authentication enabled for your Redpanda cluster, you can create SCRAM users. Redpanda supports the following SASL/SCRAM authentication mechanisms for the Kafka API: - `SCRAM-SHA-256` - `SCRAM-SHA-512` By default, SCRAM users don’t have any permissions in the cluster. Only superusers can grant permissions to new users through ACLs. 1. To create the SCRAM user `` with a password ``, run [`rpk security user create`](../../../reference/rpk/rpk-security/rpk-security-user-create/): ```bash rpk security user create \ -p '' \ --mechanism SCRAM-SHA-256 ``` > 💡 **TIP** > > Enclose passwords in single quotes to avoid conflicts with special characters. Enclosing characters in single quotes preserves the literal value of each character. 2. Use the [`rpk security acl create`](../../../reference/rpk/rpk-security/rpk-security-acl-create/) command to grant [`create` and `describe` permissions](../authorization/acl/) to `myuser` in the cluster: ```bash rpk security acl create --allow-principal User:myuser \ --operation create,describe \ --cluster \ -X user= \ -X pass='' \ -X sasl.mechanism= ``` 3. Grant the new user `describe` privileges for a topic called `myfirsttopic`: ```bash rpk security acl create --allow-principal User:myuser \ --operation describe \ --topic myfirsttopic \ -X user= \ -X pass='' \ -X sasl.mechanism= ``` > 📝 **NOTE** > > You must grant privileges for specific topics. Even if a user has `describe` privileges for a cluster, it does not mean that the user is granted `describe` privileges for topics. See also: [User create](../authorization/#user-create). ##### [](#connect-to-redpanda)Connect to Redpanda This section provides examples of connecting to Redpanda as a SCRAM user when SASL/SCRAM authentication is enabled. Create a topic as the `myuser` user by running [`rpk topic create`](../../../reference/rpk/rpk-topic/rpk-topic-create/): ```bash rpk topic create myfirsttopic \ -X user=myuser \ -X pass='changethispassword' \ -X sasl.mechanism=SCRAM-SHA-256 ``` To describe the topic, run [`rpk topic describe`](../../../reference/rpk/rpk-topic/rpk-topic-describe/): ```bash rpk topic describe myfirsttopic \ -X user=myuser \ -X pass='changethispassword' \ -X sasl.mechanism=SCRAM-SHA-256 ``` ##### [](#schema-and-http-to-redpanda)Configure Schema Registry and HTTP Proxy to connect to Redpanda with SASL Schema Registry and HTTP Proxy connect to Redpanda over the Kafka API. **Breaking change in Redpanda 25.2:** Ephemeral credentials for HTTP Proxy are removed. If your HTTP Proxy API listeners use [`authentication_method`](../../../reference/properties/broker-properties/#http_proxy_auth_method): `none`, you must configure explicit SASL credentials ([`scram_username`](../../../reference/properties/broker-properties/#scram_username), [`scram_password`](../../../reference/properties/broker-properties/#scram_password), and [`sasl_mechanism`](../../../reference/properties/broker-properties/#sasl_mechanism)) for HTTP Proxy to authenticate with the Kafka API. > ⚠️ **WARNING** > > This allows any HTTP API user to access Kafka using shared credentials. Redpanda Data recommends enabling [HTTP Proxy authentication](../../../develop/http-proxy/#authenticate-with-http-proxy) instead. For details about this breaking change, see [What’s new](../../../get-started/release-notes/redpanda/#http-proxy-authentication-changes). Schema Registry and HTTP Proxy support only the SASL/SCRAM mechanism. 1. [Create appropriate ACLs](../authorization/) for the Schema Registry and HTTP Proxy users to define and restrict their access rights within the Redpanda cluster. 2. Configure the listeners: For Schema Registry: ```yaml schema_registry_client: brokers: - address: 127.0.0.1 port: 9092 scram_username: scram_password: sasl_mechanism: SCRAM-SHA-256 ``` If TLS is enabled, additional configuration is required: ```yaml schema_registry_client: brokers: - address: 127.0.0.1 port: 9092 broker_tls: key_file: broker.key cert_file: broker.crt truststore_file: ca.crt crl_file: ca.crl # Optional enabled: true scram_username: scram_password: sasl_mechanism: SCRAM-SHA-256 ``` For HTTP Proxy: ```yaml pandaproxy_client: brokers: - address: 127.0.0.1 port: 9092 scram_username: scram_password: sasl_mechanism: SCRAM-SHA-256 ``` When HTTP Proxy API listeners use [`authentication_method`](../../../reference/properties/broker-properties/#http_proxy_auth_method): `none`, the HTTP Proxy client uses these credentials to authenticate with the Kafka API (required starting in Redpanda 25.2). The user specified in `scram_username` must have appropriate permissions to access the required Kafka resources. If TLS is enabled for the Kafka API, additional configuration is required: ```yaml pandaproxy_client: brokers: - address: 127.0.0.1 port: 9092 broker_tls: key_file: broker.key cert_file: broker.crt truststore_file: ca.crt crl_file: ca.crl # Optional enabled: true scram_username: scram_password: sasl_mechanism: SCRAM-SHA-256 ``` #### [](#plain)SASL/PLAIN You can configure Kafka clients to authenticate using either SASL/SCRAM or SASL/PLAIN with a single account using the same username and password. Unlike SASL/SCRAM, which uses a challenge response with hashed credentials, SASL/PLAIN transmits plaintext passwords. While not required, it is recommended that you use TLS for external encryption when using SASL/PLAIN authentication. If you have existing PLAIN Kafka clients and applications, you can migrate to Redpanda without updating your application by creating local Redpanda SCRAM accounts and enabling PLAIN as an authentication mechanism. > 📝 **NOTE** > > Clusters configured with _only_ a SASL/PLAIN mechanism are not supported. ##### [](#enable-saslplain)Enable SASL/PLAIN You must enable SASL/PLAIN explicitly by appending PLAIN to the list of SASL mechanisms: ```bash rpk cluster config get sasl_mechanisms - SCRAM rpk cluster config set sasl_mechanisms '["SCRAM","PLAIN"]' ``` To enable SASL/PLAIN authentication for the Kafka API, set the [`authentication_method`](../../../reference/properties/broker-properties/#kafka_api_auth_method) broker property of the Kafka listeners to `sasl`. In `redpanda.yaml`, enter: ```yaml redpanda: kafka_api: - address: 0.0.0.0 port: 9092 name: sasl_plain_listener authentication_method: sasl ``` #### [](#oidc)OAUTHBEARER (OIDC) > 📝 **NOTE** > > OpenID Connect (OIDC) authentication requires an [enterprise license](../../../get-started/licensing/). To upgrade, contact [Redpanda sales](https://redpanda.com/try-redpanda?section=enterprise-trial). When you enable [OIDC](https://openid.net/developers/how-connect-works/), Redpanda and Redpanda Console can delegate the authentication process to an external identity provider (IdP) such as Okta, Microsoft Entra ID, or on-premise Active Directory Federation Service (AD FS). With OIDC enabled, Redpanda does not need to manage user credentials directly, but can instead rely on the trusted authentication capabilities of established IdPs. Redpanda’s implementation of OIDC provides SASL/OAUTHBEARER support for the Kafka API, and supports standard OIDC authentication across all other HTTP APIs, including Schema Registry, HTTP Proxy, and the Admin API. > 💡 **TIP** > > With OIDC enabled, you can also use [group-based access control (GBAC)](../authorization/gbac/) to assign Redpanda permissions to OIDC groups instead of individual users. To use GBAC, configure your IdP to include group claims in the access token (for example, a `groups` claim). See your IdP’s documentation for how to add group claims to tokens. ##### [](#oidc-limitations)OIDC limitations - Redpanda requires JWT-formatted access tokens (not ID tokens) for Kafka API authentication using SASL/OAUTHBEARER. Access tokens issued by some IdPs, such as Google, are opaque and not supported. - The `rpk` CLI does not support OIDC login. - Redpanda requires OIDC principals to be set as superusers to access the Admin API. Granular authorization is not supported. - The `rpk` CLI does not support the SASL/OAUTHBEARER mechanism for deploying data transforms. Use SASL/SCRAM instead. ##### [](#oidc-credentials-flow-and-access-token-validation)OIDC credentials flow and access token validation Before configuring OIDC, you should understand the credentials flow, and in particular, the validation claims included in the access token, as you will need to provide them in the OIDC configuration. Redpanda’s implementation of OIDC adheres to the client credentials flow defined in [OAuth 2.0 RFC 6749, section 4.4](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) in which a client obtains an access token from the authorization server, and provides this access token to Redpanda, either using SASL/OAUTHBEARER for the Kafka API, or an HTTP Authorization (Bearer) header. The access token is a _bearer token_. A bearer token is used for authentication and authorization in web applications and APIs, and holds user credentials, usually in the form of random strings of characters. Bearer tokens are generated based on protocols and specifications such as JWT (JSON Web Token), which has a header, payload, and signature. The signature must be verified according to the JWK. Claims inside the token and the token signature must both be validated. After validation, a configurable claim from the token payload is extracted as the principal and attached to the connection, as with any other authentication method. Following is an example JWT header: ```json { "alg": "RS256", "typ": "JWT", "kid": "tMQzailSAdaW4nojXxES9" } ``` Following is an example JWT payload: ```json { "iss": "https://dev-ltxchcls4igzho78.us.auth0.com/", "sub": "3JJeI4tmMC6v8mCVCSDnAGVf2vrnJ0BT@clients", "aud": "localhost", "iat": 1694430088, "exp": 1694516488, "azp": "3JJeI4tmMC6v8mCVCSDnAGVf2vrnJ0BT", "scope": "email2", "gty": "client-credentials" } ``` Following are additional validation claims (JWT properties) that are included in the access token: - `alg`: The signature algorithm. The extension point in the JWT header is the signature algorithm used to sign the token, and cannot contain the value `none`. - `aud`: Audience. Must match the configuration specified in `oidc_token_audience`. Cannot contain the value `none`. - `kid`: Key identifier. Must match _any_ of the public JWK listed in the `jwks_uri` endpoint. - `exp`: Expiration. The timestamp listed is greater than current time. Must validate within acceptable bounds of the value specified in `oidc_clock_skew_tolerance`. A clock skew tolerance period may be configured by an Admin to account for clock drift between Redpanda and the OIDC Identity Provider (IdP). - `iss`: Issuer. Must exactly match the `issuer` property of the JSON returned from the URL specified in `oidc_discovery_url`. - `scope`: Scope. Must include the value `openid`. - `sub`: Subject. This default claim identifies the principal subject. While `sub` is the default mapping (`$.sub`) in Redpanda, any claim within the JWT can be mapped to a Redpanda principal. ##### [](#enable-oidc)Enable OIDC 1. Register a client application with your IdP. A client application, in this context, refers to any application or service that will authenticate against the Redpanda cluster using OIDC. This registration process involves creating a new entry in the IdP’s management console for the application, sometimes called a client. During this process, you’ll specify details about your application, such as the type of application, the callback URLs, and any other required information as per your IdP’s requirements. In an enterprise environment, OIDC integration typically requires coordination with your organization’s security team. 2. [Enable SASL authentication](#enable-authentication) if it’s not already enabled. 3. Configure [ACLs](../authorization/#acls) for your users so they can access Redpanda resources. 4. Enable the `OAUTHBEARER` SASL mechanism: ```bash rpk cluster config set sasl_mechanisms '["SCRAM","OAUTHBEARER"]' -X admin.hosts=localhost:9644 ``` Example output: Successfully updated configuration. New configuration version is 16. 5. Specify the discovery URL of your identity provider (IdP). The following IdP URL uses the default value: ```bash rpk cluster config set oidc_discovery_url 'https://auth.prd.cloud.redpanda.com/.well-known/openid-configuration' ``` 6. Specify the intended audience of the token: ```bash rpk cluster config set oidc_token_audience 'redpanda' ``` 7. Specify the principal mapping, which is a JSON path that extracts a principal from any claim in the bearer token payload. The mapping rules are as follows: - `rule = "$" segments [ mapping ]` - `segments = "." fieldname { "." fieldname }` - `mapping = "/" regex_pattern "/" replacement_pattern "/" [ case_modifier ]` - `replacement_pattern = replacement_element { replacement_element }` - `replacement_match = "$" digit` - `replacement_element = replacement_match | arbitrary_text` - `case_modifier = "L" | "U"` For example, consider a JWT with the following claims: ```json { "sub": "user", "user_info": { "name": "User", "email": "user@example.com" } } ``` - Default rule (`$.sub`): Extracts the `sub` claim, resulting in the principal `user`. - Extract principal from the email field (`$.user_info.email/([^@]+)@.*/$1/L`): This rule captures the username part of the email before the `@` symbol and converts it to lowercase. The resulting principal is `user`. - Extract principal with domain validation (`$.user_info.email/([^@]+)@example.com/$1/L`): This rule is similar to the previous one but only applies if the email domain matches `example.com`. The resulting principal is `user` if the domain matches, otherwise, the mapping fails. To apply a principal mapping rule in Redpanda, use the following command: ```bash rpk cluster config set oidc_principal_mapping '$.sub' rpk cluster config set oidc_principal_mapping '$.user_info.email/([^@]+)@.*/$1/L' ``` 8. Specify the amount of time (in seconds) to allow for when validating the expiration claim in the token: ```bash rpk cluster config set oidc_clock_skew_tolerance 30 ``` 9. Enable OIDC to disconnect clients when their token expires: ```bash rpk cluster config set oidc_token_expire_disconnect true ``` 10. Specify the amount of time keys from the `jwks_uri` are cached: ```bash rpk cluster config set oidc_keys_refresh_interval 3600 ``` #### [](#kerberos)GSSAPI (Kerberos) > 📝 **NOTE** > > Kerberos authentication requires an [enterprise license](../../../get-started/licensing/). To upgrade, contact [Redpanda sales](https://redpanda.com/try-redpanda?section=enterprise-trial). To configure Kerberos authentication, use a keytab, which contains credentials for the service. 1. Prepare the cluster: 1. Ensure that host names are fully qualified domain names (FQDN). 2. Ensure that each broker has a [Kerberos configuration file](http://web.mit.edu/Kerberos/krb5-latest/doc/admin/conf_files/krb5_conf.html) (`krb5.conf`) set to use Active Directory or another corporate key distribution center (KDC). The default is at `/etc/krb5.conf`. 3. Ensure that the KDC has a valid Kerberos service principal name (SPN) for each broker in the form `primary/@`. 4. Ensure that each broker has a keytab containing the SPN for that broker. This must be located at an identical file path on each Redpanda broker. The default is `/var/lib/redpanda/redpanda.keytab`. 2. [Enable SASL authentication](#enable-authentication) if it’s not already enabled. 3. Configure [ACLs](../authorization/#acls) for your users so they can access Redpanda resources. 4. If the keytab is not in the default location, then set its location: ```bash rpk cluster config set sasl_kerberos_keytab ``` 5. If the `krb5.conf` file is not in the default location, then set its location: ```bash rpk cluster config set sasl_kerberos_config ``` 6. Define the primary of the Kerberos SPN to be used by Redpanda with the given keytab. Default is `redpanda`. ```bash rpk cluster config set sasl_kerberos_principal ``` 7. Set `sasl_kerberos_principal_mapping`. This maps Kerberos user principal names (UPNs) onto Redpanda principals used in the ACLs. For example: ```bash rpk cluster config set sasl_kerberos_principal_mapping '["RULE:[1:$1@$0](.*@MYDOMAIN.COM)s/@.*//","DEFAULT"]' ``` By default, Redpanda matches the primary of the Kerberos UPN of the user. Each rule has the following format: - `RULE:[n:string](regexp)s/pattern/replacement/g/c` where: - `n` is an integer that indicates how many components the target principal should have. - If this matches, then a string is formed from `string`, substituting the realm of the principal for `$0` and the ``n`’th component of the principal for `$n``. (For example, if the principal is `johndoe/admin@realm.com`, then `[2:$2$1foo]` results in the string `adminjohndoefoo`.) - If this string matches `regexp`, then the `s//[g]` substitution command is run over the string. - `g` is optional. It causes the substitution to be global over the string, instead of replacing only the first match in the string. - `c` is optional. It can be either `/L` or `/U` to make the match lowercase or uppercase. - `DEFAULT` The principal name is used as the local user name. If the principal has more than one component or is not in the default realm, then the conversion fails. Examples of a Kerberos UPN without a host (`jdoe@EXAMPLE.COM`) and with a host (`jdoe/host@EXAMPLE.COM`): | Translation | jdoe@EXAMPLE.COM | jdoe/host@EXAMPLE.COM | | --- | --- | --- | | [1:$1@$0] | jdoe@EXAMPLE.COM | Rule does not match because there are two components in the principal name jdoe/host@EXAMPLE.COM. | | [1:$1] | jdoe | Rule does not match because there are two components in the principal name jdoe/host@EXAMPLE.COM. | | [1:$1.foo] | jdoe.foo | Rule does not match because there are two components in the principal name jdoe/host@EXAMPLE.COM. | | [2:$1/$2@$0] | Rule does not match because there is one component in the principal name jdoe@EXAMPLE.COM. | jdoe/host@EXAMPLE.COM | | [2:$1/$2] | Rule does not match because there is one component in the principal name jdoe@EXAMPLE.COM. | jdoe/host | | [2:$1@$0] | Rule does not match because there is one component in the principal name jdoe@EXAMPLE.COM. | jdoe@EXAMPLE.COM | | [2:$1] | Rule does not match because there is one component in the principal name jdoe@EXAMPLE.COM. | jdoe | | DEFAULT | jdoe | jdoe | The first rule that matches is used to extract a principal. 8. Append the list of allowed SASL mechanisms that clients can use to authenticate against the Kafka API. To get the list of all allowed SASL mechanisms, run: ```bash rpk cluster config get sasl_mechanisms ``` To add support for Kerberos, append the `sasl_mechanisms` property with the value `GSSAPI`: ```bash rpk cluster config set sasl_mechanisms '["SCRAM","GSSAPI"]' ``` For Kerberos authentication, Redpanda requires that SASL/SCRAM be enabled so that `rpk`, Redpanda Console, and other Redpanda products can connect to the cluster. Operating with Kerberos only is not a supported configuration. ### [](#mtls)mTLS When [mTLS is enabled](../encryption/), both the client and the server authenticate each other using TLS certificates. When mTLS authentication is enabled, Redpanda uses configurable rules to extract the principal from the Distinguished Name (DN) of an mTLS (X.509) certificate. It uses the principal as the identity or user name. To enable mTLS authentication, set [`authentication_method`](../../../reference/properties/broker-properties/#kafka_api_auth_method) broker property for a listener to `mtls_identity`. For example, to enable mTLS authentication for the internal Kafka API listener, in `redpanda.yaml`, enter: ```yaml redpanda: kafka_api: - address: 0.0.0.0 port: 9092 name: mtls_listener authentication_method: mtls_identity kafka_api_tls: - name: mtls_listener key_file: mtls_broker.key cert_file: mtls_broker.crt truststore_file: mtls_ca.crt enabled: true require_client_auth: true ``` By default, Redpanda matches the entire DN. To override the default, specify `kafka_mtls_principal_mapping_rules`. This is a list of rules that provide a mapping from DN to principal. Each rule has the following format: `RULE:pattern/replacement/[LU]`. Where: - `pattern` is a regular expression. For example, to extract the CN field: `.*CN=([^,]).*+`. - `replace` is used to adjust the match. For example, to use just the first match, use: `$1`. - `L` makes the match lowercase (optional). - `U` makes the match uppercase (optional). For example, with the DN: `CN=www.redpanda.com,O=Redpanda,OU=Engineering,L=London,S=England,C=UK` | Rule | Principal | | --- | --- | | RULE:.*CN=([^,]+).*/$1/ | www.redpanda.com | | RULE:.*O=([^,]+).*/$1/ | Redpanda | | RULE:.*O=([^,]+).*/$1/L | redpanda | | RULE:.*O=([^,]+),OU=([^,]+),.*,C=([^,]+)/$1-$2-$3/L | redpanda-engineering-uk | | DEFAULT | CN=www.redpanda.com,O=Redpanda,OU=Engineering,L=London,S=England,C=UK | The first rule that matches is used to extract a principal. To update the `kafka_mtls_principal_mapping_rules` property: ```bash rpk cluster config set kafka_mtls_principal_mapping_rules '["DEFAULT"]' ``` #### [](#configure-schema-registry-and-http-proxy-to-connect-to-redpanda-with-mtls)Configure Schema Registry and HTTP Proxy to connect to Redpanda with mTLS Schema Registry and HTTP Proxy require valid client certificates to secure the connection to Redpanda. Continuing with the previous example, where the certificate contains an identity for authentication (`kafka_api` listener set to `mtls_identity`), the following example shows how to connect Schema Registry and HTTP Proxy to Redpanda with mTLS certificate-based identity. For example: ```yaml schema_registry_client: brokers: - address: 127.0.0.1 port: 9092 broker_tls: key_file: schema_registry.key cert_file: schema_registry.crt truststore_file: ca.crt enabled: true pandaproxy_client: brokers: - address: 127.0.0.1 port: 9092 broker_tls: key_file: pandaproxy.key cert_file: pandaproxy.crt truststore_file: ca.crt enabled: true ``` ## [](#authentication-for-the-http-apis)Authentication for the HTTP APIs Redpanda provides the following HTTP APIs that support authentication: - Admin API: Management and monitoring of the Redpanda cluster - Schema Registry API: Management of schemas and schema evolution - HTTP Proxy API: RESTful interface for Kafka clients ### [](#permission-models)Permission models Each of the HTTP APIs implements its own permission model with different levels of access control. This section lists what permissions are available to different user types, and how to enable authentication. #### [](#admin-api-permissions)Admin API permissions The Admin API primarily requires superuser privileges, with a few exceptions for read-only status endpoints. For a complete list of all Admin API endpoints, see the [Admin API reference](/api/doc/admin/). #### [](#schema-registry-api-permissions)Schema Registry API permissions The Schema Registry implements a granular permission model. Most read operations require only user-level authentication, while write operations that affect the global state or mode typically require superuser privileges. #### [](#http-proxy-permissions)HTTP Proxy permissions The HTTP Proxy API impersonates the authenticated user when making Kafka API calls: Regular users are subject to the same ACL restrictions as they would be when using the Kafka API directly. ### [](#enable-authentication)Enable authentication Redpanda supports authentication for the HTTP APIs using either basic authentication or OIDC (OpenID Connect). #### [](#prerequisites)Prerequisites Before enabling authentication for the HTTP APIs, you must [enable SASL authentication for the Kafka API](#sasl). This creates the credential store that HTTP authentication will use. #### [](#basic-authentication)Basic authentication > 📝 **NOTE** > > Redpanda Data recommends that you use TLS when enabling HTTP Basic Auth. Basic authentication provides a method for securing HTTP endpoints. With basic authentication enabled, HTTP user agents, such as web browsers, must provide a username and password when making a request. To add users to the Redpanda credential store that HTTP basic authentication uses, create users with [`rpk security user create`](../../../reference/rpk/rpk-security/rpk-security-user-create/). The HTTP Proxy API and the Schema Registry API use the same credential store as the Kafka API, so you can use the same credentials for all three APIs. The Admin API uses the same credential store as the Kafka API, but it requires superuser credentials to access it. To enable basic authentication for the Admin API: 1. [create a SCRAM superuser](#create-superusers) so that you can use `rpk` to create ACLs. `rpk` supports only basic authentication for the Admin API. 2. Enable authentication for the Admin API: ```bash rpk cluster config set admin_api_require_auth true ``` 3. Enable basic authentication: ```bash rpk cluster config set http_authentication '["BASIC"]' ``` > 📝 **NOTE** > > Valid values for the cluster configuration property [`http_authentication`](../../../reference/properties/cluster-properties/#http_authentication) (cluster-wide) are `BASIC` and `OIDC`. The value `BASIC` here is different from the per-listener setting `http_basic`, which enables authentication on a listener using the broker property `authentication_method` (see [`authentication_method`](../../../reference/properties/broker-properties/#schema_registry_auth_method) for the Schema Registry listener and [`authentication_method`](../../../reference/properties/broker-properties/#http_proxy_auth_method) for the HTTP Proxy listener). To enable basic authentication for specific listeners, set [`authentication_method`](../../../reference/properties/broker-properties/#schema_registry_auth_method) broker property to `http_basic`. For example, in `redpanda.yaml`, enter: ```yaml pandaproxy: pandaproxy_api: address: "localhost" port: 8082 authentication_method: http_basic schema_registry: schema_registry_api: address: "localhost" port: 8081 authentication_method: http_basic ``` ##### [](#connect-to-the-http-api)Connect to the HTTP API To access the internal listener: ```bash curl http://localhost:8082/topics -u : -sS ``` If TLS is enabled, specify the HTTPS protocol and pass the path to the `ca.crt` file: ```bash curl https://localhost:8082/topics --cacert /ca.crt -u : -sS ``` > 📝 **NOTE** > > If the broker’s certificate is signed by a well-known, trusted CA, and you’re confident about the integrity of your system’s CA trust store, you don’t need the `--cacert` flag. For all available endpoints, see the [HTTP Proxy API reference](/api/doc/http-proxy/). ##### [](#connect-to-the-schema-registry-api)Connect to the Schema Registry API To access the internal listener: ```bash curl http://localhost:8081/subjects -u : -sS ``` If TLS is enabled, specify the HTTPS protocol and pass the path to the `ca.crt` file: ```bash curl https://localhost:8081/subjects --cacert /ca.crt -u : -sS ``` > 📝 **NOTE** > > If the broker’s certificate is signed by a well-known, trusted CA, and you’re confident about the integrity of your system’s CA trust store, you don’t need the `--cacert` flag. For all available endpoints, see the [Schema Registry API](/api/doc/schema-registry/). #### [](#oidc-http)OIDC You can configure the HTTP APIs to authenticate users with the OIDC bearer token. By using OIDC, you can centralize credentials and provide a password-free SSO experience. See [Enable OIDC](#enable-oidc) to configure the required OIDC cluster configuration properties before enabling OIDC for the HTTP APIs. You can configure OIDC without enabling it for the Kafka API. > 📝 **NOTE** > > If you enable OIDC authentication for the Admin API, you must also [create a SCRAM superuser](#create-superusers) so that you can use `rpk` to create ACLs. `rpk` supports only basic authentication for the Admin API. See [Authentication for the HTTP APIs](#authentication-for-the-http-apis). To enable OIDC for the HTTP API listeners as well as basic authentication, include OIDC in the `http_authentication` cluster property list: > 📝 **NOTE** > > Valid values for the cluster configuration property [`http_authentication`](../../../reference/properties/cluster-properties/#http_authentication) (cluster-wide) are `BASIC` and `OIDC`. The value `BASIC` here is different from the per-listener setting `http_basic`, which enables authentication on a listener using the broker property `authentication_method` (see [`authentication_method`](../../../reference/properties/broker-properties/#schema_registry_auth_method) for the Schema Registry listener and [`authentication_method`](../../../reference/properties/broker-properties/#http_proxy_auth_method) for the HTTP Proxy listener). ```bash rpk cluster config set http_authentication '["BASIC","OIDC"]' ``` To enable OIDC for HTTP API listeners, set [`authentication_method`](../../../reference/properties/broker-properties/#schema_registry_auth_method) to `http_basic` to require authentication on those listeners. For example, in `redpanda.yaml`, enter: ```yaml pandaproxy: pandaproxy_api: address: "localhost" port: 8082 authentication_method: http_basic # Requires authentication (Basic or OIDC) schema_registry: schema_registry_api: address: "localhost" port: 8081 authentication_method: http_basic # Requires authentication (Basic or OIDC) ``` > 📝 **NOTE** > > The `authentication_method` broker property controls whether a listener requires authentication (`http_basic`) or allows anonymous access (`none`). The actual choice between Basic authentication and OIDC authentication is determined by: - What authentication methods are enabled in the [`http_authentication`](../../../reference/properties/cluster-properties/#http_authentication) cluster property - What type of Authorization header the client sends (`Basic` for Basic auth, `Bearer` for OIDC) ##### [](#connect-to-the-http-api-2)Connect to the HTTP API To access the internal listener: ```bash curl http://localhost:8082/topics -H "Authorization: Bearer " -sS ``` If TLS is enabled, specify the HTTPS protocol and pass the path to the `ca.crt` file: ```bash curl https://localhost:8082/topics --cacert /ca.crt -H "Authorization: Bearer " -sS ``` > 📝 **NOTE** > > If the broker’s certificate is signed by a well-known, trusted CA, and you’re confident about the integrity of your system’s CA trust store, you don’t need the `--cacert` flag. For all available endpoints, see the [HTTP Proxy API reference](/api/doc/http-proxy/). ##### [](#connect-to-the-schema-registry-api-2)Connect to the Schema Registry API To access the internal listener: ```bash curl http://localhost:8081/subjects -H "Authorization: Bearer " -sS ``` If TLS is enabled, specify the HTTPS protocol and pass the path to the `ca.crt` file: ```bash curl https://localhost:8081/subjects --cacert /ca.crt -H "Authorization: Bearer " -sS ``` > 📝 **NOTE** > > If the broker’s certificate is signed by a well-known, trusted CA, and you’re confident about the integrity of your system’s CA trust store, you don’t need the `--cacert` flag. For all available endpoints, see the [Schema Registry API](/api/doc/schema-registry/). ## [](#disable-authentication)Disable authentication To disable authentication for a listener, set [`authentication_method`](../../../reference/properties/broker-properties/#kafka_api_auth_method) broker property to `none`: **Breaking change in Redpanda 25.2:** Ephemeral credentials for HTTP Proxy are removed. If your HTTP Proxy API listeners use [`authentication_method`](../../../reference/properties/broker-properties/#http_proxy_auth_method): `none`, you must configure explicit SASL credentials ([`scram_username`](../../../reference/properties/broker-properties/#scram_username), [`scram_password`](../../../reference/properties/broker-properties/#scram_password), and [`sasl_mechanism`](../../../reference/properties/broker-properties/#sasl_mechanism)) for HTTP Proxy to authenticate with the Kafka API. > ⚠️ **WARNING** > > This allows any HTTP API user to access Kafka using shared credentials. Redpanda Data recommends enabling [HTTP Proxy authentication](../../../develop/http-proxy/#authenticate-with-http-proxy) instead. For details about this breaking change, see [What’s new](../../../get-started/release-notes/redpanda/#http-proxy-authentication-changes). ```yaml pandaproxy: pandaproxy_api: address: "localhost" port: 8082 authentication_method: none schema_registry: schema_registry_api: address: "localhost" port: 8081 authentication_method: none ``` If authorization is disabled, connections to this listener use the anonymous user. To disable authentication on the Kafka API, run: ```bash rpk cluster config set enable_sasl false ``` Or, set the `authentication_method` of the Kafka listeners to `none`: ```yaml redpanda: kafka_api: - address: 0.0.0.0 port: 9092 name: sasl_listener authentication_method: none ``` ## [](#generate-security-report)Generate security report Use the [`/v1/security/report`](/api/doc/admin/operation/operation-get_security_report) endpoint to generate a comprehensive security report for your cluster. This endpoint provides detailed information about current TLS configuration, authentication methods, authorization status, and security alerts across all Redpanda interfaces (Kafka, RPC, Admin, Schema Registry, HTTP Proxy). To generate a security report for your Redpanda cluster, run: Input ```bash curl 'http://localhost:9644/v1/security/report' ``` View output ```bash { "interfaces": { "kafka": [ { "name": "test_kafka_listener", "host": "0.0.0.0", "port": 9092, "advertised_host": "0.0.0.0", "advertised_port": 9092, "tls_enabled": false, "mutual_tls_enabled": false, "authentication_method": "None", "authorization_enabled": false } ], "rpc": { "host": "0.0.0.0", "port": 33145, "advertised_host": "127.0.0.1", "advertised_port": 33145, "tls_enabled": false, "mutual_tls_enabled": false }, "admin": [ { "name": "test_admin_listener", "host": "0.0.0.0", "port": 9644, "tls_enabled": false, "mutual_tls_enabled": false, "authentication_methods": [], "authorization_enabled": false } ] }, "alerts": [ { "affected_interface": "kafka", "listener_name": "test_kafka_listener", "issue": "NO_TLS", "description": "\"kafka\" interface \"test_kafka_listener\" is not using TLS. This is insecure and not recommended." }, { "affected_interface": "kafka", "listener_name": "test_kafka_listener", "issue": "NO_AUTHN", "description": "\"kafka\" interface \"test_kafka_listener\" is not using authentication. This is insecure and not recommended." }, { "affected_interface": "kafka", "listener_name": "test_kafka_listener", "issue": "NO_AUTHZ", "description": "\"kafka\" interface \"test_kafka_listener\" is not using authorization. This is insecure and not recommended." }, { "affected_interface": "rpc", "issue": "NO_TLS", "description": "\"rpc\" interface is not using TLS. This is insecure and not recommended." }, { "affected_interface": "admin", "listener_name": "test_admin_listener", "issue": "NO_TLS", "description": "\"admin\" interface \"test_admin_listener\" is not using TLS. This is insecure and not recommended." }, { "affected_interface": "admin", "listener_name": "test_admin_listener", "issue": "NO_AUTHZ", "description": "\"admin\" interface \"test_admin_listener\" is not using authorization. This is insecure and not recommended." }, { "affected_interface": "admin", "listener_name": "test_admin_listener", "issue": "NO_AUTHN", "description": "\"admin\" interface \"test_admin_listener\" is not using authentication. This is insecure and not recommended." } ] } ``` ## [](#next-steps)Next steps - [Configure Authorization](../authorization/) ## [](#suggested-reading)Suggested reading - [`rpk security acl`](../../../reference/rpk/rpk-security/rpk-security-acl/) ## Suggested labs - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) [Search all labs](/redpanda-labs) --- # Page 227: Configure Authorization **URL**: https://docs.redpanda.com/current/manage/security/authorization.md --- # Configure Authorization --- title: Configure Authorization latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: security/authorization/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: security/authorization/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/security/authorization/index.adoc description: Redpanda provides mechanisms for controlling user permissions, including ACLs, role-based access control, and group-based access control. page-git-created-date: "2024-04-30" page-git-modified-date: "2026-03-31" support-status: supported --- Authorization works in tandem with [authentication](../authentication/). Authentication verifies who a principal is. Authorization controls what that principal can do once authenticated. - [Configure Role-Based Access Control](rbac/) Role-based access controls are an extension to access control lists for managing permissions at scale. - [Configure Group-Based Access Control](gbac/) Manage Redpanda permissions at scale using your identity provider's groups. Define access once per group and let your IdP control membership, with no per-user configuration in Redpanda. - [Configure Access Control Lists](acl/) Learn how to use ACLs to configure fine-grained access to Redpanda resources. --- # Page 228: Configure Access Control Lists **URL**: https://docs.redpanda.com/current/manage/security/authorization/acl.md --- # Configure Access Control Lists --- title: Configure Access Control Lists latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: security/authorization/acl page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: security/authorization/acl.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/security/authorization/acl.adoc description: Learn how to use ACLs to configure fine-grained access to Redpanda resources. page-git-created-date: "2024-04-30" page-git-modified-date: "2026-04-07" support-status: supported --- Access control lists (ACLs) provide a way to configure fine-grained access to Redpanda resources. ACLs are permission rules that determine which actions users or roles can perform on Redpanda resources. Redpanda stores ACLs internally, replicated with [Raft](https://raft.github.io/) to provide the same consensus guarantees as your data. After you enable authorization, access to Redpanda resources is limited to superusers. To follow [security best practices](#acls-best-practices), create standard users and use ACLs to grant only the permissions they need for specific resources. > 📝 **NOTE** > > For complex organizational hierarchies or large numbers of users, consider using [role-based access control](../rbac/) for a more flexible and efficient way to manage user permissions. ## [](#acls-overview)ACLs overview ACLs control access by defining: - **Who** can access resources (principals - users or roles) - **What** they can access (clusters, topics, consumer groups, transactional IDs, Schema Registry subjects, and Schema Registry operations) - **How** they can interact with those resources (operations like read, write, describe) - **Where** they can connect from (host restrictions) ACLs work with SASL/SCRAM and mTLS authentication methods to provide comprehensive security. ## [](#manage-acls)Manage ACLs You can create and manage ACLs in the following ways: - **Redpanda Console**: Select **Security** from the left navigation menu, select the **ACLs** tab. After the ACL is created, you can add users or roles to it. - **Command Line**: Use the `rpk` command-line tool for programmatic management. For example, suppose you want to create a user named `analytics-user` who can read from topics starting with `logs-` and write to a topic called `processed-data`: ```bash # 1. Create the user rpk security user create analytics-user --password 'secure-password' # 2. Grant read access to topics with "logs-" prefix rpk security acl create --allow-principal analytics-user \ --operation read,describe --topic 'logs-' \ --resource-pattern-type prefixed # 3. Grant write access to the processed-data topic rpk security acl create --allow-principal analytics-user \ --operation write,describe --topic processed-data ``` ## [](#acl-terminology)ACL terminology Understanding these terms helps you configure least-privilege access. | Term | Definition | Example | | --- | --- | --- | | Principal | The entity (user, role, or group) requesting access | User:analytics-user, RedpandaRole:data-engineers, Group:engineering | | Resource | The Redpanda component being accessed (cluster, topic, consumer group, transactional ID, Schema Registry subject, and Schema Registry operation) | Topic: sensor-data, Group: analytics-group, Cluster: kafka-cluster | | Operation | The action being performed on the resource | READ, WRITE, CREATE, DELETE, DESCRIBE | | Host | The IP address or hostname from which access is allowed/denied | 192.168.1.100, * (any host) | | Permission | Whether access is allowed or denied | ALLOW, DENY | An ACL rule combines these elements to create a permission statement: `ALLOW User:analytics-user to READ topic:sensor-data from host:192.168.1.100` ACL commands work on a multiplicative basis. If you specify two principals and two permissions, you create four ACLs: both permissions for each principal. ### [](#principals)Principals All ACLs require a principal. A principal is composed of two parts: the type, and the name. Redpanda supports the types "User", "RedpandaRole", and "Group". When you create user "bar", Redpanda expects you to add ACLs for "User:bar". To grant permissions to an OIDC group, use the `Group:` prefix (for example, `Group:engineering`). See [Configure Group-Based Access Control](../gbac/). The `--allow-principal` and `--deny-principal` flags add this prefix for you, if necessary. The special character \* matches any name, meaning an ACL with principal `User:*` grants or denies the permission for any user. > 💡 **TIP** > > To set multiple principals in a single comma-separated string, you must enclose the string with quotes. Otherwise, `rpk` splits the string on commas and fails to read the option correctly. > > For example, use double quotes: > > ```bash > rpk security acl create --allow-principal="\"C=UK,ST=London,L=London,O=Redpanda,OU=engineering,CN=__schema_registry\"" > ``` > > Alternatively, use single quotes: > > ```bash > rpk security acl create --allow-principal='"C=UK,ST=London,L=London,O=Redpanda,OU=engineering,CN=__schema_registry"' > ``` ### [](#hosts)Hosts Hosts can be seen as an extension of the principal and can effectively gate where the principal can connect from. When creating ACLs, unless otherwise specified, the default host is the wildcard `*`, which allows or denies the principal from all hosts. When specifying hosts, you must pair the `--allow-host` flag with the `--allow-principal` flag and the `--deny-host` flag with the `--deny-principal` flag. ### [](#resources)Resources A resource is what an ACL allows or denies access to. The following resources are available within Redpanda: - `cluster` - `topics` - `groups` - `transactionalid` Starting in v25.2, Redpanda also supports the following ACL resources for Schema Registry: - `subject`: Controls ACL access for specific Schema Registry subjects. Specify using the flag `--registry-subject`. - `registry`: Controls whether or not to grant ACL access to global, or top-level Schema Registry operations. Specify using the flag `--registry-global`. > ❗ **IMPORTANT** > > ACLs for Schema Registry must be enabled for each cluster. See [Schema Registry Authorization](../../../schema-reg/schema-reg-authorization/). Resources combine with the operation that is allowed or denied on that resource. By default, resources are specified on an exact name match (a "literal" match). Names for each of these resources can be specified with their respective flags. Use the `--resource-pattern-type` flag to specify that a resource name is "prefixed", meaning to allow anything with the given prefix. A literal name of "foo" matches only the topic "foo", while the prefixed name of "foo-" matches both "foo-bar" and "foo-jazz". The special wildcard resource name '\*' matches any name of the given resource type (`--topic` '\*' matches all topics). ### [](#operations)Operations Operations define what actions are allowed or denied on resources. Here are the available operations with common use cases: | Operation | Description | Common use case | | --- | --- | --- | | READ | Allows reading data from a resource | Consumers reading from topics, fetching consumer group offsets | | WRITE | Allows writing data to a resource | Producers publishing messages to topics | | CREATE | Allows creating new resources | Auto-creating topics, creating new consumer groups | | DELETE | Allows deleting resources | Removing topics, deleting consumer groups | | DESCRIBE | Allows querying resource metadata | Listing topics, getting topic configurations | | ALTER | Allows modifying resource properties | Changing topic partition counts, updating consumer group settings | | DESCRIBE_CONFIGS | Allows viewing resource configurations | Reading topic settings, broker configurations | | ALTER_CONFIGS | Allows modifying resource configurations | Changing topic retention policies, updating broker settings | | IDEMPOTENT_WRITE | Allows idempotent produce semantics initialization | Required for idempotent producers (InitProducerID) | | ALL | Grants all operations above | Administrative access to resources | Common combinations: - Producer: `WRITE` + `DESCRIBE` on topics - Consumer: `READ` + `DESCRIBE` on topics, `READ` on consumer groups - Admin: `ALL` on cluster and specific resources ### [](#producingconsuming)Producing/Consuming For quick reference, here are the ACL requirements for common client scenarios: | Client type | Required ACLs | | --- | --- | | Simple producer | WRITE + DESCRIBE on target topics | | Simple consumer | READ + DESCRIBE on target topicsREAD on consumer group | | Transactional producer | WRITE + DESCRIBE on target topicsWRITE on transactional ID | | Consumer group admin | READ + DESCRIBE on target topicsREAD + DESCRIBE + DELETE on consumer groups | Command examples: ```bash # Basic producer access rpk security acl create --allow-principal producer-user \ --operation write,describe --topic my-topic # Basic consumer access rpk security acl create --allow-principal consumer-user \ --operation read,describe --topic my-topic rpk security acl create --allow-principal consumer-user \ --operation read --group my-consumer-group ``` The following operations are necessary for each individual client request, where **resource** corresponds to the resource flag, and "for xyz" corresponds to the resource names in the request. Show operations PRODUCING/CONSUMING Produce WRITE on TOPIC for topics WRITE on TRANSACTIONAL\_ID for the transaction.id Fetch READ on TOPIC for topics ListOffsets DESCRIBE on TOPIC for topics Metadata DESCRIBE on TOPIC for topics CREATE on CLUSTER for kafka-cluster (if automatically creating topics) or, CREATE on TOPIC for topics (if automatically creating topics) InitProducerID IDEMPOTENT\_WRITE on CLUSTER or, WRITE on any TOPIC or, WRITE on TRANSACTIONAL\_ID for transactional.id (if using transactions) OffsetForLeaderEpoch DESCRIBE on TOPIC for topics GROUP CONSUMING FindCoordinator DESCRIBE on GROUP for group DESCRIBE on TRANSACTIONAL\_ID for transactional.id (transactions) OffsetCommit READ on GROUP for groups READ on TOPIC for topics OffsetFetch DESCRIBE on GROUP for groups DESCRIBE on TOPIC for topics OffsetDelete DELETE on GROUP for groups READ on TOPIC for topics JoinGroup READ on GROUP for group Heartbeat READ on GROUP for group LeaveGroup READ on GROUP for group SyncGroup READ on GROUP for group TRANSACTIONS (including FindCoordinator above) AddPartitionsToTxn WRITE on TRANSACTIONAL\_ID for transactional.id WRITE on TOPIC for topics AddOffsetsToTxn WRITE on TRANSACTIONAL\_ID for transactional.id READ on GROUP for group EndTxn WRITE on TRANSACTIONAL\_ID for transactional.id TxnOffsetCommit WRITE on TRANSACTIONAL\_ID for transactional.id READ on GROUP for group READ on TOPIC for topics ADMIN CreateTopics CREATE on CLUSTER for kafka-cluster CREATE on TOPIC for topics DESCRIBE\_CONFIGS on TOPIC for topics, for returning topic configs on create CreatePartitions ALTER on TOPIC for topics DeleteTopics DELETE on TOPIC for topics DESCRIBE on TOPIC for topics, if deleting by topic ID (in addition to prior ACL) DeleteRecords DELETE on TOPIC for topics DescribeGroup DESCRIBE on GROUP for groups ListGroups DESCRIBE on GROUP for groups or, DESCRIBE on CLUSTER for kafka-cluster DeleteGroups DELETE on GROUP for groups DescribeConfigs DESCRIBE\_CONFIGS on CLUSTER for cluster (broker describing) DESCRIBE\_CONFIGS on TOPIC for topics (topic describing) AlterConfigs ALTER\_CONFIGS on CLUSTER for cluster (broker altering) ALTER\_CONFIGS on TOPIC for topics (topic altering) AlterPartitionAssignments ALTER on CLUSTER for kafka-cluster ListPartitionReassignments DESCRIBE on CLUSTER for kafka-cluster AlterReplicaLogDirs ALTER on CLUSTER for kafka-cluster DescribeLogDirs DESCRIBE on CLUSTER for kafka-cluster AlterClientQuotas ALTER on CLUSTER for kafka-cluster DescribeClientQuotas DESCRIBE\_CONFIGS on CLUSTER for kafka-cluster AlterUserScramCreds ALTER on CLUSTER for kafka-cluster DescribeUserScramCreds DESCRIBE\_CONFIGS on CLUSTER for kafka-cluster DescribeProducers READ on TOPIC for topics DescribeTransactions DESCRIBE on TRANSACTIONAL\_ID for transactional.id DESCRIBE on TOPIC for topics ListTransactions DESCRIBE on TRANSACTIONAL\_ID for transactional.id REGISTRY GetGlobalConfig DESCRIBE\_CONFIGS on REGISTRY for schema registry UpdateGlobalConfig ALTER\_CONFIGS on REGISTRY for schema registry GetGlobalMode DESCRIBE\_CONFIGS on REGISTRY for schema registry UpdateGlobalMode ALTER\_CONFIGS on REGISTRY for schema registry GetReferencedBy DESCRIBE on REGISTRY for schema registry ListSchemasForId DESCRIBE on REGISTRY for schema registry ListSchemaTypes (no ACLs required) HealthCheck (no ACLs required) SUBJECT ListSubjects DESCRIBE on SUBJECT for subject CheckSchema READ on SUBJECT for subject RegisterSchema WRITE on SUBJECT for subject GetSchemaByVersion READ on SUBJECT for subject GetSchemaRaw READ on SUBJECT for subject ListSubjectVersions DESCRIBE on SUBJECT for subject DeleteSchemaVersion DELETE on SUBJECT for subject DeleteSubject DELETE on SUBJECT for subject GetSubjectConfig DESCRIBE\_CONFIGS on SUBJECT for subject UpdateSubjectConfig ALTER\_CONFIGS on SUBJECT for subject DeleteSubjectConfig ALTER\_CONFIGS on SUBJECT for subject GetSubjectMode DESCRIBE\_CONFIGS on SUBJECT for subject UpdateSubjectMode ALTER\_CONFIGS on SUBJECT for subject DeleteSubjectMode ALTER\_CONFIGS on SUBJECT for subject CheckCompatibility READ on SUBJECT for subject GetSchemaById READ on SUBJECT for subject To get this information with `rpk`, run: ```bash rpk security acl --help-operations ``` In flag form to set up a general producing/consuming client, you can invoke `rpk security acl create` up to three times with the following (including your `--allow-principal`): ```bash --operation write,read,describe --topic [topics] --operation describe,read --group [group.id] --operation describe,write --transactional-id [transactional.id] ``` ### [](#permissions)Permissions A client can be allowed access or denied access. By default, all permissions are denied. You only need to specifically deny a permission if you allow a wide set of permissions and then want to deny a specific permission in that set. You could allow all operations, and then specifically deny writing to topics. ### [](#management)Management Commands for managing users and ACLs work on a specific ACL basis, but listing and deleting ACLs works on filters. Filters allow matching many ACLs to be printed, listed, and deleted at the same time. Because this can be risky for deleting, the delete command prompts for confirmation by default. ## [](#acls-best-practices)ACLs best practices Follow these recommendations for secure and manageable ACL configurations. Security best practices: - Principle of least privilege: Grant only the minimum permissions required for each user or role - Avoid wildcards: Use specific resource names instead of `*` whenever possible - Separate environments: Use different principals for development, staging, and production - Regular audits: Periodically review and clean up unused ACLs Management best practices: - Use descriptive names: Choose clear user and topic names that indicate their purpose - Group related permissions: Create roles for users with similar access patterns - Document ACL decisions: Keep records of why specific permissions were granted Common pitfalls to avoid - Over-privileging: Granting `ALL` operations when specific ones would suffice - Forgetting consumer groups: Not granting necessary group permissions for consumers - Host restrictions: Accidentally blocking legitimate client connections with overly restrictive host rules - Pattern confusion: Mixing up literal vs. prefixed resource pattern types - Test ACLs: Verify permissions work as expected before deploying to production ## [](#manage-acls-with-rpk)Manage ACLs with rpk Use [`rpk security acl`](../../../../reference/rpk/rpk-security/rpk-security-acl/) to manage ACLs and SASL/SCRAM users from the command line. On Kubernetes, you can use `kubectl exec` to run `rpk` commands. ### [](#basic-workflow)Basic workflow Follow this typical workflow when setting up ACLs: 1. **Create a user**: `rpk security user create --password ''` 2. **Create ACLs**: `rpk security acl create --allow-principal --operation --topic ` 3. **Verify access**: `rpk security acl list --allow-principal ` Example setup: ```bash # 1. Create user rpk security user create data-processor \ --password 'secure-password' \ -X admin.hosts=localhost:9644 # 2. Grant topic access rpk security acl create --allow-principal data-processor \ --operation read,write,describe --topic 'data-*' \ --resource-pattern-type prefixed # 3. Grant consumer group access rpk security acl create --allow-principal data-processor \ --operation read,describe --group data-processing-group # 4. Verify the setup rpk security acl list --allow-principal data-processor ``` ### [](#command-overview)Command overview Here’s how `rpk` commands interact with Redpanda: | Command | Protocol | Default port | Purpose | | --- | --- | --- | --- | | user | Admin API | 9644 | Manage SASL/SCRAM users | | list | Kafka API | 9092 | View existing ACLs | | create | Kafka API | 9092 | Create new ACLs | | delete | Kafka API | 9092 | Remove ACLs | ### [](#global-flags)Global flags Every [`rpk security acl`](../../../../reference/rpk/rpk-security/rpk-security-acl/) command can use these flags: | Flag | Description | | --- | --- | | --admin-api-tls-cert | The certificate to be used for TLS authentication with the Admin API. | | --admin-api-tls-enabled | Enable TLS for the Admin API (not necessary if specifying custom certificates). This is assumed as true when passing other --admin-api-tls flags. | | --admin-api-tls-key | The certificate key to be used for TLS authentication with the Admin API. | | --admin-api-tls-truststore | The truststore to be used for TLS communication with the Admin API. | | -X brokers | Comma-separated list of broker ip:port pairs (for example, --brokers '192.168.78.34:9092,192.168.78.35:9092,192.179.23.54:9092' ). Alternatively, you can set the RPK_BROKERS environment variable with the comma-separated list of broker addresses. | | --config | Redpanda configuration file. If not set, the file is searched in the default locations. | | -h, --help | Help. | | --password | SASL password to be used for authentication. | | --sasl-mechanism | The authentication mechanism to use. Supported values: SCRAM-SHA-256, SCRAM-SHA-512. | | --tls-cert | The certificate to be used for TLS authentication with the broker. | | --tls-enabled | Enable TLS for the Kafka API (not necessary if specifying custom certificates). This is assumed to be true when passing other --tls flags. | | --tls-key | The certificate key to be used for TLS authentication with the broker. | | --tls-truststore | The truststore to be used for TLS communication with the broker. | | --user | SASL user to be used for authentication. | ### [](#create-acls)Create ACLs With the create command, every ACL combination is a created ACL. At least one principal, one host, one resource, and one operation are required to create a single ACL. ```bash rpk security acl create/delete [globalACLFlags] [localFlags] ``` You can use the global flags and some other local flags. Following are the available local flags: | Flag | Description | | --- | --- | | --allow-host | Host for which access will be granted (repeatable). | | --allow-principal | Principals to which permissions will be granted (repeatable). | | --allow-role | Role to which permissions will be granted (repeatable). | | --cluster | Whether to grant ACLs to the cluster. | | --deny-host | Host from which access will be denied (repeatable). | | --deny-principal | Principal to which permissions will be denied (repeatable). | | --deny-role | Role to which permissions will be denied (repeatable). | | --group | Group to grant ACLs for (repeatable). | | -h, --help | Help. | | --name-pattern | The name pattern type to be used when matching the resource names. | | --operation | Operation that the principal will be allowed or denied. Can be passed many times. | | --resource-pattern-type | Pattern to use when matching resource names (literal or prefixed) (default "literal"). | | --topic | Topic to grant ACLs for (repeatable). | | --transactional-id | Transactional IDs to grant ACLs for (repeatable). | | --registry-subject | Schema Registry subject to grant ACLs for (repeatable). | | --registry-global | Grants ACLs for global Schema Registry operations (no name required). | Examples: To allow all permissions to user bar on topic "foo" and group "g", run: ```bash rpk security acl create --allow-principal bar --operation all --topic foo --group g ``` To allow read permissions to all users on topics biz and baz, run: ```bash rpk security acl create --allow-principal '*' --operation read --topic biz,baz ``` To allow write permissions to user buzz to transactional id "txn", run: ```bash rpk security acl create --allow-principal User:buzz --operation write --transactional-id txn ``` ### [](#list-and-delete-acls)List and delete ACLs List and delete for ACLs have a multiplying effect (similar to create ACL), but delete is more advanced. List and delete work on a filter basis. Any unspecified flag defaults to matching everything (all operations, or all allowed principals, and so on). To ensure that you don’t accidentally delete more than you intend, this command prints everything that matches your input filters and prompts for a confirmation before the delete request is issued. Anything matching more than 10 ACLs also asks for confirmation. If no resources are specified, all resources are matched. If no operations are specified, all operations are matched. You can opt in to matching everything. For example, `--operation any` matches any operation. The `--resource-pattern-type`, defaulting to `any`, configures how to filter resource names: - `any` returns exact name matches of either prefixed or literal pattern type - `match` returns wildcard matches, prefix patterns that match your input, and literal matches - `prefix` returns prefix patterns that match your input (prefix "fo" matches "foo") - `literal` returns exact name matches To list or delete ACLs, run: ```bash rpk security acl list/delete [globalACLFlags] [localFlags] ``` You can use the global flags and some other local flags. Following are the available local flags: | Flag | Description | | --- | --- | | --allow-host | Allowed host ACLs to list/remove. (repeatable) | | --allow-principal | Allowed principal ACLs to list/remove. (repeatable) | | --cluster | Whether to list/remove ACLs to the cluster. | | --deny-host | Denied host ACLs to list/remove. (repeatable) | | --deny-principal | Denied principal ACLs to list/remove. (repeatable) | | -d, --dry | Dry run: validate what would be deleted. | | --group | Group to list/remove ACLs for. (repeatable) | | -h, --help | Help. | | --no-confirm | Disable confirmation prompt. | | --operation | Operation to list/remove. (repeatable) | | -f, --print-filters | Print the filters that were requested. (failed filters are always printed) | | --resource-pattern-type | Pattern to use when matching resource names. (any, match, literal, or prefixed) (default "any") | | --topic | Topic to list/remove ACLs for. (repeatable) | | --transactional-id | Transactional IDs to list/remove ACLs for. (repeatable) | | --registry-subject | Schema Registry subject(s) to list/remove ACLs for. (repeatable) | | --registry-global | Match ACLs for global Schema Registry operations. | ### [](#user)User This command manages the SCRAM users. If SASL is enabled, a SCRAM user talks to Redpanda, and ACLs control what your user has access to. Using SASL requires setting `kafka_enable_authorization: true` in the Redpanda section of your `redpanda.yaml`. ```bash rpk security user [command] [globalACLFlags] [globalUserFlags] ``` Following are the available global user flags: | Flag | Description | Supported Value | | --- | --- | --- | | -X admin.hosts | The comma-separated list of IP addresses (IP:port). You must specify one for each broker. | strings | | -h, --help | -h, --help | Help. | ### [](#user-create)User create This command creates a single SASL/SCRAM user with the given password, and optionally with a custom mechanism. The mechanism determines which authentication flow the client uses for this user/password. Redpanda `rpk` supports the following mechanisms: `SCRAM-SHA-256` (default) and `SCRAM-SHA-512`, which is the same flow but uses sha512. To use GSSAPI, see [Enable Kerberos](../../authentication/#kerberos). Before a created SASL account can be used, you must also create ACLs to grant the account access to certain resources in your cluster. To create a SASL/SCRAM user, run: ```bash rpk security user create [user] -p [password] [globalACLFlags] [globalUserFlags] [localFlags] ``` Here are the local flags: | Flag | Description | | --- | --- | | -h, --help | Help. | | --mechanism | SASL mechanism to use: scram-sha-256 or scram-sha-512. Default is scram-sha-256. | ### [](#user-delete)User delete This command deletes the specified SASL account from Redpanda. This does not delete any ACLs that may exist for this user. You may want to re-create the user later, as well, not all ACLs have users that they describe (instead they are for wildcard users). ```bash rpk security user delete [USER] [globalACLFlags] [globalUserFlags] ``` ### [](#user-list)User list This command lists SASL users. ```bash rpk security user list [globalACLFlags] [globalUserFlags] ``` You can also use the shortened version changing `list` to `ls`. ## [](#suggested-reading)Suggested reading - [How to use data security with ACLs](https://redpanda.com/blog/built-in-security-with-acls/) ## Suggested labs - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) [Search all labs](/redpanda-labs) --- # Page 229: Configure Group-Based Access Control **URL**: https://docs.redpanda.com/current/manage/security/authorization/gbac.md --- # Configure Group-Based Access Control --- title: Configure Group-Based Access Control latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: security/authorization/gbac page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: security/authorization/gbac.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/security/authorization/gbac.adoc description: Manage Redpanda permissions at scale using your identity provider's groups. Define access once per group and let your IdP control membership, with no per-user configuration in Redpanda. page-topic-type: how-to personas: security_engineer, platform_engineer learning-objective-1: Configure the cluster properties that enable GBAC learning-objective-2: Assign an OIDC group to an RBAC role learning-objective-3: "Create a group-based ACL using the Group: principal prefix" page-git-created-date: "2026-03-31" page-git-modified-date: "2026-03-31" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../../get-started/licensing/#self-managed) apply. Group-based access control (GBAC) lets you manage Redpanda permissions at scale using the groups that already exist in your identity provider (IdP). Instead of creating and maintaining per-user permissions in Redpanda, you define access once for a group and your IdP controls who belongs to it. When users join or leave a team, their Redpanda access updates automatically at next login with no changes needed in Redpanda. GBAC extends [OIDC authentication](../../authentication/#oidc) and supports two ways to grant permissions to groups: create [ACLs](../acl/) with `Group:` principals, or assign groups as members of [RBAC](../rbac/) roles. Both approaches can be used independently or together. After reading this page, you will be able to: - Configure the cluster properties that enable GBAC - Assign an OIDC group to an RBAC role - Create a group-based ACL using the Group: principal prefix ## [](#prerequisites)Prerequisites To use GBAC, you need: - An [Enterprise Edition](../../../../get-started/licensing/overview/) license applied to your cluster. - Superuser access to configure cluster properties and manage ACLs. - [OIDC authentication](../../authentication/#oidc) configured and enabled on your cluster. - Your IdP configured to include group claims in the OIDC access token (for example, a `groups` claim). ## [](#how-gbac-works)How GBAC works When a user authenticates with OIDC, Redpanda reads a configurable claim from the JWT access token (for example, `$.groups`) and extracts the list of groups the user belongs to. Redpanda then matches those group names against `Group:` principals in its ACLs and role assignments. Group membership is managed entirely by your IdP. Redpanda never stores or manages group membership directly. It reads group information from the OIDC token at authentication time. Changes you make in the IdP (adding or removing group memberships) take effect at the user’s next authentication, when a new token is issued. GBAC works across the following Redpanda APIs: - Kafka API - Schema Registry - HTTP Proxy ### [](#authorization-patterns)Authorization patterns GBAC supports two usage patterns: - Group as an ACL principal: Create an ACL with a `Group:` principal. Users in that group receive that permission directly. - Group assigned to a role: Assign a group as a member of a role-based access control (RBAC) role. All users in the group inherit the role’s ACLs. Both patterns can be used together. When a user belongs to multiple groups, they inherit the combined permissions of all groups. Redpanda evaluates all authorization sources (user ACLs, role ACLs, group ACLs, and group-to-role ACLs) in a single unified flow. Deny rules are checked first across all sources. If any source produces a deny, Redpanda rejects the request regardless of allows from other sources. If no deny is found, Redpanda checks for an allow across all sources. If no allow is found, Redpanda denies the request by default. flowchart LR A\[Request\] --> B{"Check all sources\\nfor deny"} B -- "Deny found" --> DENY\["❌ Deny"\] B -- "No deny found" --> C{"Check all sources\\nfor allow"} C -- "Allow found" --> ALLOW\["✅ Allow"\] C -- "No allow found" --> DEFAULT\["❌ Default deny"\] style DENY fill:#f44,color:#fff style ALLOW fill:#4a4,color:#fff style DEFAULT fill:#f44,color:#fff subgraph sources \[" "\] direction LR S1\["User ACLs"\] S2\["Role ACLs\\n(RBAC)"\] S3\["Group ACLs"\] S4\["Group→Role\\nACLs"\] end Figure 1. Authorization evaluation flow ## [](#supported-identity-providers)Supported identity providers GBAC works with any OIDC-compliant identity provider. These providers are commonly used with Redpanda: - [Auth0](https://auth0.com/docs/secure/tokens/json-web-tokens/create-custom-claims): Configure group claims in Auth0 Actions or Rules. - [Okta](https://developer.okta.com/docs/concepts/universal-directory/): Assign groups to applications and include them in token claims. - [Microsoft Entra ID (Azure AD)](https://learn.microsoft.com/en-us/entra/identity/hybrid/connect/how-to-connect-fed-group-claims): Configure group claims in the application manifest. For IdP-specific configuration steps, see your provider’s documentation. ## [](#limitations)Limitations - Azure AD group limit: Users with more than 200 group memberships in Azure AD receive a URL reference in their token instead of a list of group names. Redpanda does not follow that URL and cannot resolve groups in this case. Mitigation: Filter token claims to include only the groups relevant to Redpanda. - Nested groups: Redpanda does not recursively resolve nested group hierarchies. If group A contains group B, only the direct memberships reported in the token are used. Use [`nested_group_behavior: suffix`](../../../../reference/properties/cluster-properties/#nested_group_behavior) to extract the last path segment from hierarchical group names when needed. - No wildcard ACLs for groups: ACL matching for `Group:` principals uses literal string comparison only. Wildcard patterns are not supported. ## [](#customize-token-claim-extraction)Customize token claim extraction Different identity providers store group information in different locations within the JWT token. Two cluster properties control how Redpanda extracts group names: - [`oidc_group_claim_path`](../../../../reference/properties/cluster-properties/#oidc_group_claim_path): A [JSON path](https://goessner.net/articles/JsonPath/) expression that tells Redpanda where to find group information in the OIDC token. For example, Auth0 and Okta typically use a top-level `groups` claim (`$.groups`), while Keycloak nests roles inside `realm_access` (`$.realm_access.roles`). Default: `$.groups`. - [`nested_group_behavior`](../../../../reference/properties/cluster-properties/#nested_group_behavior): Controls how Redpanda handles group names that use path-style notation (for example, `/departments/eng/platform`). Set to `none` to use the full path as-is, or `suffix` to extract only the last segment. Default: `none`. > 📝 **NOTE** > > When `nested_group_behavior` is set to `suffix`, groups that share a leaf name (for example, `/departments/eng/groupA` and `/departments/sales/groupA`) both resolve to `Group:groupA`. ACLs or role assignments for that principal apply to members of both groups. Design your group naming conventions to avoid unintended collisions. To update these properties, use [any configuration method](../../../cluster-maintenance/cluster-property-configuration/) (`rpk cluster config set`, the Admin API, or Redpanda Console). Changes take effect immediately without a restart. ### [](#token-structure-examples)Token structure examples The following examples show how Redpanda extracts group principals from different token formats. #### [](#flat-group-values-default)Flat group values (default) With `oidc_group_claim_path: "$.groups"`, Redpanda extracts principals `Group:engineering` and `Group:analytics` from the token. ```json {"groups": ["engineering", "analytics"]} ``` #### [](#nested-claim)Nested claim With `oidc_group_claim_path: "$.realm_access.roles"`, Redpanda extracts principals `Group:eng` and `Group:fin` from the token. ```json {"realm_access": {"roles": ["eng", "fin"]}} ``` #### [](#path-style-group-names-with-no-suffix-extraction-default)Path-style group names with no suffix extraction (default) With `nested_group_behavior: "none"` (the default), Redpanda maps the full path to principals `Group:/departments/eng/platform` and `Group:/departments/eng/infra`. ```json {"groups": ["/departments/eng/platform", "/departments/eng/infra"]} ``` #### [](#path-style-group-names-with-suffix-extraction)Path-style group names with suffix extraction When [`nested_group_behavior`](../../../../reference/properties/cluster-properties/#nested_group_behavior) is set to `suffix`, Redpanda maps the last path segment to principals `Group:platform` and `Group:infra`. ```json {"groups": ["/departments/eng/platform", "/departments/eng/infra"]} ``` #### [](#csv-formatted-group-claim)CSV-formatted group claim Some identity providers return group claims as a single comma-separated string instead of an array. ```json {"groups": "engineering,analytics,finance"} ``` Redpanda automatically splits comma-separated values and extracts principals `Group:engineering`, `Group:analytics`, and `Group:finance`. ## [](#create-group-based-acls)Create group-based ACLs You can grant permissions directly to a group by creating an [ACL](../acl/) with a `Group:` principal. This works the same as creating an ACL for a user, but uses the `Group:` prefix instead of `User:`. ### rpk To grant cluster-level access to the `engineering` group: ```bash rpk security acl create --allow-principal Group:engineering --operation describe --cluster ``` To grant topic-level access: ```bash rpk security acl create \ --allow-principal Group:engineering \ --operation read,describe \ --topic 'analytics-' \ --resource-pattern-type prefixed ``` ### Redpanda Console In Redpanda Console, group-based ACLs are managed through roles. To create an ACL for an OIDC group: 1. From **Security** on the left navigation menu, select the **Roles** tab. 2. Click **Create role** to open the role creation form, or select an existing role and click **Edit**. 3. For **User/principal**, enter the group principal using the `Group:` format. For example, `Group:engineering`. 4. Define the permissions (ACLs) you want to grant to users in the group. You can configure ACLs for clusters, topics, consumer groups, transactional IDs, Schema Registry subjects, and Schema Registry operations. 5. Click **Create** (or **Update** if editing an existing role). > 📝 **NOTE** > > Redpanda Console assigns ACLs through roles. To grant permissions to a group, create a role for that group, add the group as a principal, and define the ACLs on the role. To create ACLs with a `Group:` principal directly (without creating a role), use `rpk`. ## [](#assign-groups-to-roles)Assign groups to roles To manage permissions at scale, assign a group to an [RBAC](../rbac/) role. All users in the group inherit the role’s ACLs automatically. ### rpk To assign a group to a role: ```bash rpk security role assign --principal Group: ``` For example, to assign the `engineering` group to the `DataEngineers` role: ```bash rpk security role assign DataEngineers --principal Group:engineering ``` To remove a group from a role: ```bash rpk security role unassign --principal Group: ``` For example: ```bash rpk security role unassign DataEngineers --principal Group:engineering ``` ### Redpanda Console To assign a group to a role in Redpanda Console: 1. From **Security** on the left navigation menu, select the **Roles** tab. 2. Select the role you want to assign the group to. 3. Click **Edit**. 4. For **User/principal**, enter the group name using the `Group:` format. For example, `Group:engineering`. 5. Click **Update**. To remove a group from a role: 1. From **Security** on the left navigation menu, select the **Roles** tab. 2. Select the role that has the group assignment you want to remove. 3. Click **Edit**. 4. For **User/principal**, remove the `Group:` entry. 5. Click **Update**. ### Admin API Use the Admin API [`SecurityService`](/api/doc/admin/v2/group/endpoint-securityservice) operations to manage group-to-role assignments. Send all requests as `POST` with a JSON body. For guidance on using the Admin API (ConnectRPC), see [Manage Redpanda using the Admin API](../../../use-admin-api/). To assign a group to a role, make a [`POST AddRoleMembers`](/api/doc/admin/v2/operation/operation-redpanda-core-admin-v2-securityservice-addrolemembers) request: ```bash curl -u : \ --request POST 'http://localhost:9644/redpanda.core.admin.v2.SecurityService/AddRoleMembers' \ --header 'Content-Type: application/json' \ --data '{ "roleName": "DataEngineers", "members": [{"group": {"name": "engineering"}}] }' ``` To remove a group from a role, make a [`POST RemoveRoleMembers`](/api/doc/admin/v2/operation/operation-redpanda-core-admin-v2-securityservice-removerolemembers) request: ```bash curl -u : \ --request POST 'http://localhost:9644/redpanda.core.admin.v2.SecurityService/RemoveRoleMembers' \ --header 'Content-Type: application/json' \ --data '{ "roleName": "DataEngineers", "members": [{"group": {"name": "engineering"}}] }' ``` ## [](#view-groups-and-roles)View groups and roles Use the following commands to inspect group assignments and role memberships. ### [](#list-groups-assigned-to-a-role)List groups assigned to a role #### rpk To see which groups are assigned to a role, use `--print-members`. Groups are listed alongside other principals such as `User:` and appear as `Group:` entries: ```bash rpk security role describe --print-members ``` For example: ```bash rpk security role describe DataEngineers --print-members ``` To list all roles assigned to a specific group: ```bash rpk security role list --principal Group: ``` For example: ```bash rpk security role list --principal Group:engineering ``` #### Redpanda Console To view groups assigned to a role in Redpanda Console: 1. From **Security** on the left navigation menu, select the **Roles** tab. 2. Select the role you want to inspect. 3. The role details page lists all principals, including any `Group:` entries. #### Admin API These operations use the [Admin API v2](/api/doc/admin/v2/group/endpoint-securityservice) `SecurityService`. Send all requests as `POST` with a JSON body. To retrieve a role’s details including all members (users and groups), make a [`POST GetRole`](/api/doc/admin/v2/operation/operation-redpanda-core-admin-v2-securityservice-getrole) request: ```bash curl -u : \ --request POST 'http://localhost:9644/redpanda.core.admin.v2.SecurityService/GetRole' \ --header 'Content-Type: application/json' \ --data '{"name": "DataEngineers"}' ``` The response includes a `members` array with both `user` and `group` entries. To list all roles, make a [`POST ListRoles`](/api/doc/admin/v2/operation/operation-redpanda-core-admin-v2-securityservice-listroles) request: ```bash curl -u : \ --request POST 'http://localhost:9644/redpanda.core.admin.v2.SecurityService/ListRoles' \ --header 'Content-Type: application/json' \ --data '{}' ``` To verify how Redpanda resolves groups from an OIDC token, make a [`POST ResolveOidcIdentity`](/api/doc/admin/v2/operation/operation-redpanda-core-admin-v2-securityservice-resolveoidcidentity) request. Pass the token in the `Authorization` header. The response includes the resolved `principal`, token expiry, and a `groups` field listing all groups extracted from the token: ```bash curl \ --request POST 'http://localhost:9644/redpanda.core.admin.v2.SecurityService/ResolveOidcIdentity' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{}' ``` ## [](#troubleshoot-gbac)Troubleshoot GBAC If group-based permissions are not working as expected: - Decode the JWT access token from your IdP and verify that the expected group claims are present: ```bash echo $ACCESS_TOKEN | cut -d. -f2 | base64 -d 2>/dev/null | jq . ``` Look for the claim that matches your [`oidc_group_claim_path`](../../../../reference/properties/cluster-properties/#oidc_group_claim_path) configuration (default: `$.groups`). - Use the `ResolveOidcIdentity` Admin API endpoint to verify which groups Redpanda extracts from a token. See [View groups and roles](#view-groups-and-roles). - Verify that your cluster configuration matches the token structure: ```bash rpk cluster config get oidc_group_claim_path rpk cluster config get nested_group_behavior ``` - Temporarily enable debug logging for the `security` logger to see all claims in the validated JWT: ```bash rpk redpanda admin config log-level set security --level debug ``` This helps diagnose incorrect claim paths, missing groups, or token content issues. The debug level reverts automatically after the expiry period (default: 300 seconds). ## [](#audit-logging)Audit logging When [audit logging](../../../audit-logging/) is enabled, Redpanda includes group information in the following event types: - Authentication events: Events across Kafka API, HTTP Proxy, Schema Registry, and Admin API include the user’s IdP group memberships in the `user.groups` field with type `idp_group`. - Authorization events: When an authorization decision matches a group ACL, the matched group appears in the `actor.user.groups` field with type `idp_group`. ## [](#next-steps)Next steps - [Set up audit logging](../../../audit-logging/) to monitor group-based access events. ## Suggested labs - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) [Search all labs](/redpanda-labs) --- # Page 230: Configure Role-Based Access Control **URL**: https://docs.redpanda.com/current/manage/security/authorization/rbac.md --- # Configure Role-Based Access Control --- title: Configure Role-Based Access Control latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: security/authorization/rbac page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: security/authorization/rbac.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/security/authorization/rbac.adoc description: Role-based access controls are an extension to access control lists for managing permissions at scale. page-git-created-date: "2024-04-30" page-git-modified-date: "2025-09-12" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../../get-started/licensing/#self-managed) apply. Role-based access control (RBAC) provides a way to configure permissions for provisioned users at scale, and provides a streamlined interface to manage user access to many resources. RBAC works in conjunction with all supported authentication methods. ## [](#rbac-overview)RBAC overview RBAC addresses the challenge of access management at scale. Instead of managing individual ACLs for each user, RBAC groups permissions into roles that you can assign to multiple users. Roles can reflect organizational structure or job duties. This approach decouples users and permissions, allowing a one-to-many mapping that reduces the number of custom ACLs needed. Benefits of RBAC: - Simplified management: Create roles once, assign to many users - Easier onboarding: New employees inherit permissions by role assignment - Faster audits: Review permissions by role rather than individual user - Better compliance: Roles align with organizational structure and job duties - Reduced errors: Fewer individual ACL assignments mean fewer mistakes ## [](#manage-roles)Manage roles Administrators can create and manage RBAC configurations with `rpk`, the Redpanda Admin API, or Redpanda Console. In Redpanda Console, select **Security** from the left navigation menu, and then select the **Roles** tab. After the role is created, you can add users/principals to it. For `rpk`, use [`rpk security`](../../../../reference/rpk/rpk-security/rpk-security/). For example, suppose you want to create a `DataAnalysts` role for users who need to read from analytics topics and write to reporting topics: ```bash # 1. Create the role rpk security role create DataAnalysts # 2. Grant read access to analytics topics rpk security acl create --operation read,describe \ --topic 'analytics-' --resource-pattern-type prefixed \ --allow-role DataAnalysts # 3. Grant write access to reporting topics rpk security acl create --operation write,describe \ --topic 'reports-' --resource-pattern-type prefixed \ --allow-role DataAnalysts # 4. Assign users to the role rpk security role assign DataAnalysts --principal alice,bob,charlie # 5. Verify the setup rpk security role describe DataAnalysts ``` All three users (`alice`, `bob`, `charlie`) now have identical permissions without managing individual ACLs for each user. ## [](#rbac-terminology)RBAC terminology Understanding RBAC terminology is essential for effective role management: | Term | Definition | Example | | --- | --- | --- | | Role | A named collection of ACLs that can be assigned to users | DataEngineers, ApplicationDevelopers, ReadOnlyUsers | | Principal | A user account in the system (same as ACL principals) | User:alice, User:bob, User:analytics-service | | Permission | An ACL rule that allows or denies specific operations | ALLOW READ on topic:sensor-data, DENY DELETE on cluster | | Assignment | The association between a user and one or more roles | User alice has roles DataEngineers and TopicAdmins | RBAC workflow: 1. **Create roles**: Define roles that match your organizational needs 2. **Grant permissions**: Create ACLs specifying the role as allowed/denied 3. **Assign users**: Associate users with appropriate roles 4. **Automatic inheritance**: Users gain all permissions from their assigned roles Under the RBAC framework, you create **roles**, grant **permissions** to those roles, and assign the roles to **users**. When you change the permissions for a given role, all users with that role automatically gain the modified permissions. You grant or deny permissions for a role by creating an ACL and specifying the RBAC role as either allowed or denied respectively. Redpanda treats all **users** as security principals and defines them with the `Type:Name` syntax (for example, `User:mike`). You can omit the `Type` when defining a principal and Redpanda will assume the `User:` type. All examples here use the full syntax for clarity. See [access control lists](../acl/) for more information on defining ACLs and working with principals. ### [](#roles)Roles You can assign any number of roles to a given user. When installing a new Redpanda cluster, no roles are provisioned by default. To use RBAC, you must create your first roles using your `superuser` account, which enables you to create additional roles and assign appropriate ACLs as necessary. See [configure authentication](../../authentication/#create_superusers) for more information on creating and managing superusers. When performing an upgrade from older versions of Redpanda, all existing SASL/SCRAM users are assigned to the placeholder `User` role to help you more readily migrate away from pure ACLs. As a security measure, this default role has no assigned ACLs. ### [](#policy-conflicts)Policy conflicts You can assign a combination of ACLs and roles to any given principal. ACLs allow permissions, deny permissions, or specify a combination of both. As a result, users may at times have role assignments with conflicting policies. Permission resolution rules: A user is permitted to perform an operation if and only if: 1. No `DENY` permission exists matching the operation 2. An `ALLOW` permission exists matching the operation Examples: | User’s direct ACLs | Role-based ACLs | Result | Explanation | | --- | --- | --- | --- | | ALLOW READ topic:logs | Role has DENY READ topic:logs | ❌ denied | DENY always takes precedence | | DENY WRITE topic:sensitive | Role has ALLOW WRITE topic:* | ❌ denied | Specific DENY blocks wildcard ALLOW | | No direct ACLs | Role has ALLOW READ topic:data | ✅ allowed | Role permission applies | | ALLOW READ topic:public | No role ACLs for this topic | ✅ allowed | Direct permission applies | ### [](#rbac-example)RBAC example Consider a scenario where your software engineers use a set of private topics to publish application update information to users. All your private topics begin with the prefix `private-`. You might create a new `SoftwareEng` role to represent the software engineers with write access to these private topics. You would then assign the `SoftwareEng` role as the allowed role for a new ACL specifying read and write permissions to `private-*`. Using a wildcard includes all existing private topics and any new ones you might create later. You then assign the new role to John and Jane, your two software engineers who will write messages to this topic. The `rpk` commands to accomplish this are: ```bash rpk security role create SoftwareEng && rpk security acl create --operation read --operation write --topic private-* --allow-role SoftwareEng && rpk security role assign SoftwareEng --principal User:john,User:jane ``` This diagram shows the relationships between users, roles, and ACLs: ![RBAC role assignments](../../../../shared/_images/rbac-roles.png) Consider the situation where you want to create a new topic, `private-software-versions`, where users self-report the version of a component they are using. If you were using the ACL authorization mechanism, you would need to assign this ACL to every user in your Redpanda installation. Using RBAC allows you to make one update and apply it to everyone with that role. Adding the write permissions for this topic to the `User` role means everyone with that role (all authenticated users in the diagram) gains the authorization immediately. For example: ```bash rpk security acl create --operation write --topic private-software-versions --allow-role User ``` ## [](#rbac-best-practices)RBAC best practices Follow these recommendations for effective role-based access control: Role design - Use descriptive names: Choose role names that clearly indicate their purpose (`DataEngineers`, `ReadOnlyAnalysts`) - Follow job functions: Align roles with actual job responsibilities and organizational structure - Keep roles focused: Create specific roles rather than overly broad ones (`TopicReaders` vs `SuperUsers`) - Plan for growth: Design roles that can accommodate new team members and evolving needs Permission management - Start with minimal permissions: Grant only the access required for the role’s function - Use wildcards carefully: Prefixed patterns like `analytics-*` are useful but review regularly - Avoid `DENY` rules: Prefer specific `ALLOW` rules over complex `DENY`/`ALLOW` combinations - Document role purpose: Maintain clear documentation about what each role is intended for Operational guidelines - Regular reviews: Audit roles and assignments quarterly to ensure they remain appropriate - Least privilege: Users should have the minimum roles needed for their current responsibilities - Temporary access: Create time-limited roles for contractors or temporary project access - Monitor usage: Track which roles and permissions are actively used vs. dormant ## [](#manage-users-and-roles)Manage users and roles Administrators can manage RBAC configurations with `rpk`, the Redpanda Admin API, or Redpanda Console. Common management tasks: - Create roles: Define new roles for organizational functions - Assign permissions: Add ACLs to roles to define what they can access - Assign users: Associate users with appropriate roles - Modify roles: Add or remove permissions from existing roles - Audit access: Review roles and assignments for compliance Typical workflow: 1. Create role 2. Add ACL permissions 3. Assign users 4. Test access 5. Monitor and adjust ### [](#create-a-role)Create a role Creating a new role is a two-step process. First you define the role, giving it a unique and descriptive name. Second, you assign one or more ACLs to allow or deny access for the new role. This defines the permissions that are inherited by all users assigned to the role. It is possible to have an empty role with no ACLs assigned. #### rpk To create a new role, run: ```bash rpk security role create ``` After the role is created, administrators create new ACLs and assign this role either allow or deny permissions. For example: ```bash rpk security acl create ... --allow-role ``` Example of creating a new role named `red`: ```bash rpk security role create red ``` ```bash Successfully created role "red" ``` #### Redpanda Console To create a new role: 1. From **Security** on the left navigation menu, select the **Roles** tab. 2. Click **Create role**. 3. Provide a name for the role and an optional origin host for users to connect from. 4. Define the permissions (ACLs) for the role. You can create ACLs for clusters, topics, consumer groups, transactional IDs, Schema Registry subjects, and Schema Registry operations. > 💡 **TIP** > > You can assign more than one user/principal to the role when creating it. 5. Click **Create**. ### [](#delete-a-role)Delete a role When a role is deleted, Redpanda carries out the following actions automatically: - All role ACLs are deleted. - All users' assignments to the role are removed. Redpanda lists all impacted ACLs and role assignments when running this command. You receive a prompt to confirm the deletion action. The delete operation is irreversible. #### rpk To delete a role, run: ```bash rpk security role delete ``` Example of deleting a role named `red`: ```bash rpk security role delete red ``` ```bash PERMISSIONS =========== PRINCIPAL HOST RESOURCE-TYPE RESOURCE-NAME RESOURCE-PATTERN-TYPE OPERATION PERMISSION ERROR RedpandaRole:red * TOPIC books LITERAL ALL ALLOW RedpandaRole:red * TOPIC videos LITERAL ALL ALLOW PRINCIPALS (1) ============== NAME TYPE panda User ? Confirm deletion of role "red"? This action will remove all associated ACLs and unassign role members Yes Successfully deleted role "red" ``` #### Redpanda Console To delete an existing role: 1. From **Security** on the left navigation menu, select the **Roles** tab. 2. Click the role you want to delete. This shows all currently assigned permissions (ACLs) and principals (users). 3. Click **Delete**. 4. Click **Delete**. ### [](#assign-a-role)Assign a role You can assign a role to any security principal. Principals are referred to using the format: `Type:Name`. Redpanda currently supports only the `User` type. If you omit the type, Redpanda assumes the `User` type by default. With this command, you can assign the role to multiple principals at the same time by using a comma separator between each principal. #### rpk To assign a role to a principal, run: ```bash rpk security role assign --principal ``` Example of assigning a role named `red`: ```bash rpk security role assign red --principal bear,panda ``` ```bash Successfully assigned role "red" to NAME PRINCIPAL-TYPE bear User panda User ``` #### Redpanda Console To assign a role to a principal, edit the role or edit the user. Option 1: Edit the role 1. From **Security** on the left navigation menu, select the **Roles** tab. 2. Select the role you want to assign to one or more users/principals. 3. Click **Edit**. 4. Below the list of permissions, find the Principals section. You can add any number of users/principals to the role. After listing all new users/principals, click **Update**. Option 2: Edit the user 1. From **Security** on the left navigation menu, select the **Users** tab. 2. Select the user you want to assign one or more roles to. 3. In the **Assign roles** input field, select the roles you want to add to this user. 4. After adding all roles, click **Update**. ### [](#unassign-a-role)Unassign a role You can remove a role assignment from a security principal without deleting the role. Principals are referred to using the format: `Type:Name`. Redpanda currently supports only the `User` type. If you omit the type, Redpanda assumes the `User` type by default. With this command, you can remove the role from multiple principals at the same time by using a comma separator between each principal. #### rpk To remove a role assignment from a principal, run: ```bash rpk security role unassign --principal ``` Example of unassigning a role named `red`: ```bash rpk security role unassign red --principal panda ``` ```bash Successfully unassigned role "red" from NAME PRINCIPAL-TYPE panda User ``` #### Redpanda Console There are two ways to remove a role from a principal: Option 1: Edit the role 1. From **Security** on the left navigation menu, select the **Roles** tab. 2. Select the role you want to remove from one or more principals. 3. Click **Edit**. 4. Below the list of permissions, find the Principals section. Click **x** beside the name of any principals you want to remove from the role. 5. After you have removed all needed principals, click **Update**. Option 2: Edit the user 1. From **Security** on the left navigation menu, select the **Users** tab. 2. Select the user you want to remove from one or more roles. 3. Click **x** beside the name of any roles you want to remove this user from. 4. After you have removed the user from all roles, click **Update**. ### [](#edit-role-permissions)Edit role permissions You can add or remove ACLs from any of the roles you have previously created. #### rpk To modify an existing role by adding additional ACLs to it, run: ```bash rpk security acl create ... --allow-role ``` ```bash rpk security acl create ... --deny-role ``` To use `rpk` to remove ACLs from a role, run: ```bash rpk security acl delete ... --allow-role rpk security acl delete ... --deny-role ``` When you run `rpk security acl delete`, Redpanda deletes all ACLs matching the parameters supplied. Make sure to match the exact ACL you want to delete. If you supply only the `--allow-role` flag, for example, Redpanda will delete every ACL granting that role authorization to a resource. To list all the ACLs associated with a role, run: ```bash rpk security acl list --allow-role --deny-role ``` See also: - [rpk security acl create](../../../../reference/rpk/rpk-security/rpk-security-acl-create/) - [rpk security acl delete](../../../../reference/rpk/rpk-security/rpk-security-acl-delete/) - [rpk security acl list](../../../../reference/rpk/rpk-security/rpk-security-acl-list/) #### Redpanda Console To edit the ACLs for an existing role: 1. From **Security** on the left navigation menu, select the **Roles** tab. 2. Select the role you want to edit and click **Edit**. 3. While editing the role, you can update the optional origin host for users to connect from. 4. You can add or remove ACLs for the role. As when creating a new role, you can create or modify ACLs for topics, consumer groups, transactional IDs, Schema Registry subjects, and Schema Registry operations. 5. After making all changes, click **Update**. ### [](#list-all-roles)List all roles Redpanda lets you view a list of all existing roles. #### rpk To view a list of all actives roles, run: ```bash rpk security role list ``` Example of listing all roles: ```bash rpk security role list ``` ```bash NAME red ``` #### Redpanda Console To view all existing roles: 1. From **Security** on the left navigation menu, select the **Roles** tab. All roles are listed in a paginated view. You can also filter the view using the input field at the top of the list. ### [](#describe-a-role)Describe a role When managing roles, you may need to review the ACLs the role grants or the list of principals assigned to the role. #### rpk To view the details of a given role, run: ```bash rpk security role describe ``` Example of describing a role named `red`: ```bash rpk security role describe red ``` ```bash PERMISSIONS =========== PRINCIPAL HOST RESOURCE-TYPE RESOURCE-NAME RESOURCE-PATTERN-TYPE OPERATION PERMISSION ERROR RedpandaRole:red * TOPIC books LITERAL ALL ALLOW RedpandaRole:red * TOPIC videos LITERAL ALL ALLOW PRINCIPALS (1) ============== NAME TYPE panda User ``` #### Redpanda Console To view details of an existing role: 1. From **Security** on the left navigation menu, select the **Roles** tab. 2. Find the role you want to view and click the role name. All roles are listed in a paginated view. You can also filter the view using the input field at the top of the list. ## [](#suggested-reading)Suggested reading - [`rpk security`](../../../../reference/rpk/rpk-security/rpk-security/) - Complete security command reference - [`rpk security acl`](../../../../reference/rpk/rpk-security/rpk-security-acl/) - ACL management commands - [Access Control Lists](../acl/) - Understanding the underlying ACL system - [Authentication](../../authentication/) - Setting up users and authentication methods ## Suggested labs - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) [Search all labs](/redpanda-labs) --- # Page 231: Configure Kafka TLS Encryption **URL**: https://docs.redpanda.com/current/manage/security/encryption.md --- # Configure Kafka TLS Encryption --- title: Configure Kafka TLS Encryption latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: security/encryption page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: security/encryption.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/security/encryption.adoc description: Enable encryption with TLS or mTLS. page-git-created-date: "2023-06-02" page-git-modified-date: "2025-08-14" support-status: supported --- By default, Redpanda data is sent unencrypted. A security best practice is to enable encryption with TLS or mTLS. - Transport Layer Security (TLS), previously SSL, provides encryption for client-server communication. A server certificate prevents third parties from accessing data transferred between the client and server. By default, Redpanda clusters accept connections from clients using TLS version 1.2 or later, but [this value is configurable](#manage-the-minimum-tls-version). - mTLS, or 2-way TLS, is a protocol that authenticates both the server and the client. In addition to the server certificate required in TLS, mTLS also requires the client to give a certificate. This involves more overhead to implement, but it can be useful for environments that require additional security and only have a small number of verified clients. ## [](#prerequisites)Prerequisites TLS certificates are required for encryption. You can use your own certificates, either self-signed or issued by a trusted CA. You’ll need the following files: - A private key file (`broker.key`) for each broker. - A certificate file (`broker.crt`) for each broker. - A truststore file (`ca.crt`). All brokers can have the same `ca.crt` file. Ensure these files are readable by Redpanda and protected against unauthorized access: ```bash chmod 400 broker.key broker.crt ca.crt chown redpanda:redpanda broker.key broker.crt ca.crt ``` For mTLS, client certificates signed by the same CA are also required. If you don’t already have these files, you can learn how to generate them in [Create a local CA for self-signed certificates](#create-a-local-ca-for-self-signed-certificates). If you enable TLS encryption, you can also specify a certificate revocation list (`ca.crl`) so that Redpanda can check and reject connections from entities using certificates already revoked by a certificate authority (CA). All brokers can have the same `ca.crl`. The file must contain a single, concatenated list of certificate revocation lists (CRLs) for all issuing certificates in the truststore file. ## [](#gen-certs)Generate certificate files This section shows you how to generate self-signed certificate files for your Redpanda brokers. If you already have your own, you can skip this step. > 📝 **NOTE** > > Self-signed certificates are useful if you want to generate multiple certificates all signed by the same root. For example, you want to use mTLS but issue different certificates to multiple Redpanda brokers and clients. ### [](#create-a-local-ca-for-self-signed-certificates)Create a local CA for self-signed certificates 1. Create a self-signed certificate and private key for the CA: ```bash openssl req -new -newkey rsa:4096 -days 365 -nodes -x509 -keyout broker.key -out broker.crt -subj "/CN=redpanda" -addext "subjectAltName = DNS:localhost, IP:127.0.0.1" ``` Ensure that `subjectAltName` is accurate for your setup. This command generates: - `broker.key`: Private key - `broker.crt`: Self-signed certificate 2. Create a configuration file for the CA, `ca.cnf`, and include your organization’s details. Ensure the `subjectAltName` extension is set correctly for broker certificates. ```ini [ ca ] default_ca = CA_default [ CA_default ] default_days = 365 database = index.txt serial = serial.txt default_md = sha256 copy_extensions = copy unique_subject = no policy = signing_policy [ req ] prompt = no distinguished_name = distinguished_name x509_extensions = extensions [ distinguished_name ] organizationName = commonName = [ extensions ] keyUsage = critical,digitalSignature,nonRepudiation,keyEncipherment,keyCertSign basicConstraints = critical,CA:true,pathlen:1 [ signing_policy ] organizationName = supplied commonName = optional ``` 3. Create a private key for the CA and set its permissions: ```bash openssl genrsa -out ca.key 2048 chmod 400 ca.key ``` 4. Use the CA configuration to generate a public certificate: ```bash openssl req -new -x509 -config ca.cnf -key ca.key -days 365 -batch -out ca.crt ``` where: | Inputs | Description | | --- | --- | | -new | New request. | | -x509 | Create an X.509 certificate, instead of a certificate signing request (CSR). | | -config ca.cnf | Configuration file to use when generating certificates (created above). | | -key ca.key | Private key of the CA (created above). | | -days 365 | Number of days signed certificates are valid. | | -batch | Batch mode, where certificates are certified automatically. | The output `ca.crt` is the CA’s public certificate, which you’ll use in the truststore. ### [](#create-broker-certificates-and-certificate-signing-requests-csrs)Create broker certificates and certificate signing requests (CSRs) To issue certificates for brokers, create a certificate signing request (CSR) and sign it with the CA. 1. Define the broker’s Subject Alternative Name (SAN) entries in `broker.cnf` under `alt_names`. A subject alternative name (SAN) indicates all domain names and IP addresses secured by the certificate. Depending on the address the client uses to connect to Redpanda, you might need to create a CNF file for each broker to modify the `alt_names` section with organizational details. For production usage, edit `alt_names` with DNS resolutions and/or the IP addresses. For example: `broker.cnf` ```ini [ req ] prompt = no distinguished_name = distinguished_name req_extensions = extensions [ distinguished_name ] organizationName = [ extensions ] subjectAltName = @alt_names [ alt_names ] DNS.1 = localhost DNS.2 = redpanda DNS.3 = console DNS.4 = connect DNS.5 = ec2-3-15-15-272.us-east-2.compute.amazonaws.com IP.1 = 10.0.8.1 ``` You could configure alternative names with a single version of `broker.key`/`broker.crt`, as long as you update the certificate for all brokers in the cluster any time you edit an entry. For example: ```ini [ alt_names ] DNS.1 = broker1.example.com DNS.2 = broker2.example.com DNS.3 = broker3.example.com ``` Additionally, you can configure alternative names using the public or private IP addresses of all your brokers. For example: ```ini [ alt_names ] IP.1 = 10.0.8.1 IP.2 = 10.0.8.2 IP.3 = 10.0.8.3 ``` 2. Create a 2048-bit private key for the broker: ```bash openssl genrsa -out broker.key 2048 ``` 3. Create the broker’s certificate signing request (CSR): ```bash openssl req -new -key broker.key -out broker.csr -nodes -config broker.cnf ``` where: | Inputs | Description | | --- | --- | | -req | Input is a certificate request. Sign and output. | | -signkey ca.key | Private key of the CA (created above). | | -days 365 | Number of days signed certificates are valid. | | -extfile broker.cnf | Configuration file for CA. | | -extensions extensions | Section in broker.cnf to use when applying extensions. | | -in broker.csr | Broker certificate signing request (CSR generated above). | The output `broker.crt` is the signed public key certificate for the broker. 4. Sign the CSR with the CA’s private key: ```bash touch index.txt echo '01' > serial.txt openssl ca -config ca.cnf -keyfile ca.key -cert ca.crt -extensions extensions -in broker.csr -out broker.crt -outdir . -batch ``` If generated by a corporate CA, these certificate signing requests must be signed with the following extensions: ```ini keyUsage = critical,digitalSignature,keyEncipherment extendedKeyUsage = serverAuth,clientAuth ``` 5. Set ownership and permissions: ```bash chown redpanda:redpanda broker.key broker.crt ca.crt chmod 400 broker.key broker.crt ca.crt ``` ## [](#configure-tls)Configure TLS To configure TLS, in `redpanda.yaml`, enter either the standard [PEM configuration files](#pem) or the [PKCS#12 bundle configuration](#pkcs). Choose PEM files when: - You are using FIPS mode compliance. - You prefer file-based configurations with a separate key, certificate, and truststore file. Choose PKCS#12 bundles when: - FIPS mode is not required in your environment. - You want a single, password-protected file that contains all certificates and keys. ### [](#pem)Configure TLS with PEM files If you have separate files for `key_file`, `cert_file`, and `truststore_file`, use the following configuration in `redpanda.yaml`: `redpanda.yaml` ```yaml redpanda: rpc_server_tls: {} kafka_api: - address: 0.0.0.0 port: 9092 name: tls_listener kafka_api_tls: - name: tls_listener key_file: broker.key cert_file: broker.crt truststore_file: ca.crt crl_file: ca.crl # Optional enabled: true require_client_auth: false admin_api_tls: [] pandaproxy: pandaproxy_api_tls: [] schema_registry: schema_registry_api_tls: [] ``` > ❗ **IMPORTANT** > > The following files must be readable by Redpanda, either through 444 permissions or `chown` to Redpanda with 400 permissions: > > - `broker.crt` > > - `broker.key` > > - `ca.crt` > > - `ca.crl` > > > Because the keys and certificates are only read at startup, you must restart Redpanda services after updating `redpanda.yaml`. TLS-related changes to `redpanda.yaml` will not be known to Redpanda until after this restart: > > systemctl restart redpanda > 📝 **NOTE** > > If you replace a working `ca.crl` file with a file that contains an invalid certificate revocation list, such as an unsigned list, Redpanda will reject all connections until you either: > > - Replace the file. > > - Remove the `crl_file: ca.crl` line from `redpanda.yaml` and restart Redpanda. To set the RPC port to encrypt replication, add: `redpanda.yaml` ```yaml redpanda: rpc_server_tls: enabled: true require_client_auth: false key_file: broker.key cert_file: broker.crt truststore_file: ca.crt crl_file: ca.crl # Optional ``` Schema Registry and HTTP Proxy connect to Redpanda over the Kafka API. If you configure a TLS listener for the Kafka API, you must add `schema_registry_client::broker_tls` and `pandaproxy_client::broker_tls`. All APIs, except the internal RPC port, support multiple listeners. See: - [Configure Schema Registry and HTTP Proxy to connect to Redpanda with SASL](../authentication/#configure-schema-registry-and-http-proxy-to-connect-to-redpanda-with-sasl) - [Configure Listeners](../listener-configuration/) ### [](#pkcs)Configure TLS with PKCS#12 bundles You can simplify certificate management by generating a password-protected PKCS#12 bundle from your `broker.key` and `broker.crt` files. > 📝 **NOTE** > > PKCS#12 keys are not supported when [FIPS mode](../fips-compliance/) is enabled in Redpanda. The PKCS12KDF algorithm used in PKCS#12 is not FIPS-compliant. To use Redpanda in FIPS mode, configure your certificates and keys in [PEM format](#pem) instead. 1. Run this command to create a PKCS#12 file from your `broker.key` and `broker.crt` files: ```bash openssl pkcs12 -export -inkey broker.key -certfile broker.crt -passout pass: -out broker.p12 ``` Replace `` with your own password. 2. Update `redpanda.yaml` with the path to the PKCS#12 bundle: ```yaml redpanda: kafka_api_tls: - name: tls_listener p12_path: p12_password: enabled: true require_client_auth: false ``` > ⚠️ **CAUTION** > > Do not configure both both `key_file`/`cert_file` and `p12_path`/`p12_password` together, as this will cause a startup error. ## [](#configure-mtls)Configure mTLS To enable mTLS, add `require_client_auth` set to `true`. Configure either the standard PEM files or the PKCS#12 bundle. ### [](#configure-mtls-with-pem-files)Configure mTLS with PEM files For the Kafka API, in `redpanda.yaml`, enter: `redpanda.yaml` ```yaml redpanda: kafka_api: - address: 0.0.0.0 port: 9092 name: mtls_listener kafka_api_tls: - name: mtls_listener key_file: mtls_broker.key cert_file: mtls_broker.crt truststore_file: mtls_ca.crt enabled: true require_client_auth: true ``` See also: [Configure Listeners](../listener-configuration/) ### [](#configure-mtls-for-a-kafka-api-listener)Configure mTLS for a Kafka API listener To enable mTLS for a Kafka API listener, edit `redpanda.yaml`: `redpanda.yaml` ```yaml redpanda: kafka_api: - name: internal address: 0.0.0.0 port: 9092 advertised_kafka_api: - name: internal address: port: 9092 kafka_api_tls: - name: internal enabled: true require_client_auth: true cert_file: key_file: truststore_file: ``` > 📝 **NOTE** > > - Remember to replace placeholders in brackets. > > - [`kafka_api`](../../../reference/properties/broker-properties/#kafka_api) is the listener declaration. This `name` can have any value. > > - [`advertised_kafka_api`](../../../reference/properties/broker-properties/#advertised_kafka_api) is the advertised listener. This `name` should match the name of a declared listener. This `address` is the host name clients use to connect to the broker. > > - [`kafka_api_tls`](../../../reference/properties/broker-properties/#kafka_api_tls) is the listener’s TLS configuration. This `name` must match the corresponding listener’s name. See also: [Configure Listeners](../listener-configuration/) ### [](#configure-mtls-with-pkcs12-bundles)Configure mTLS with PKCS#12 bundles 1. Update `redpanda.yaml` with the path to the PKCS#12 bundle: ```yaml redpanda: kafka_api_tls: - name: mtls_listener p12_path: p12_password: enabled: true require_client_auth: true ``` > ⚠️ **CAUTION** > > Do not configure both the `key_file`/`cert_file` and the `p12_path`/`p12_password` together, as this will cause a startup error. ## [](#manage-the-minimum-tls-version)Manage the minimum TLS version Redpanda sets the minimum TLS version for all clusters to 1.2, using the [`tls_min_version`](../../../reference/properties/cluster-properties/#tls_min_version) cluster configuration property. This prevents client applications from negotiating a downgrade to the TLS version when they make a connection to a Redpanda cluster. You can update the minimum TLS version of your clusters to `v1.0`, `v1.1` or `v1.3` using `rpk`. Replace the placeholder in brackets. ```bash rpk cluster config set tls_min_version ``` You must restart Redpanda for the new setting to take effect: ```bash systemctl restart redpanda ``` ## [](#use-rpk-with-tls)Use rpk with TLS If you’re using `rpk` to interact with the Kafka API using mTLS identity (for example, to manage topics or messages), pass the `--tls-key`, `--tls-cert`, and `--tls-truststore` flags to authenticate. To [create a new topic](../../../reference/rpk/rpk-topic/rpk-topic-create/) called `test-topic`, run: ```bash rpk topic create test-topic \ --tls-key \ --tls-cert \ --tls-truststore ``` Replace placeholders in brackets. To check the configuration of the topic, run: ```bash rpk topic describe test-topic ``` To interact with the Admin API (for example, to manage users), pass the `--admin-api-tls-key`, `--admin-api-tls-cert`, and `--admin-api-tls-truststore` flags. By default, `rpk` connects to `localhost:9092` for Kafka protocol commands. If you’re connecting to a remote broker or if you configured your local broker differently, use the `-X brokers=` flag. ## [](#monitor-tls-certificates)Monitor TLS certificates Redpanda exposes several metrics to help administrators manage their installed certificates. When queried, these metrics list details for all resources that have an installed certificate. This may include APIs, storage, or other assets. These metrics also support labels so that you can more readily report statistics on single resources. Configuring alerts on these metrics is a critical tool for managing certificate expiration and avoiding surprise outages. The [public metrics reference](../../../reference/public-metrics-reference/#tls_metrics) contains a full list of available TLS metrics. You can refer to the [monitor Redpanda](../../monitoring/) guide for full details on configuring Prometheus to monitor these metrics. This guide also explains how to create a Grafana dashboard for visualizations and alerting. Alternatively, you can choose to [specify a certificate revocation list](#configure-tls) to reject connections from entities using certificates already revoked by a certificate authority. ## [](#suggested-reading)Suggested reading - [TLS configuration for Redpanda and rpk](https://redpanda.com/blog/tls-config/) - [Work with Schema Registry](../../schema-reg/) ## Suggested labs - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) [Search all labs](/redpanda-labs) --- # Page 232: Configure Redpanda for FIPS **URL**: https://docs.redpanda.com/current/manage/security/fips-compliance.md --- # Configure Redpanda for FIPS --- title: Configure Redpanda for FIPS latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: security/fips-compliance page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: security/fips-compliance.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/security/fips-compliance.adoc description: Configure Redpanda to operate in FIPS-compliant mode. page-topic-type: how-to personas: platform_operator learning-objective-1: Configure a Redpanda broker to run in FIPS-compliant mode learning-objective-2: Set the required OpenSSL properties for FIPS mode learning-objective-3: Deploy Redpanda in FIPS-compliant mode using Docker page-git-created-date: "2024-07-31" page-git-modified-date: "2026-03-31" support-status: supported --- Redpanda provides Federal Information Processing Standards (FIPS)-compliant cipher enforcement for brokers using a [FIPS 140-3](https://csrc.nist.gov/pubs/fips/140-3/final)\-validated OpenSSL cryptographic module. Redpanda and `rpk` both use the OpenSSL library for security-related cryptographic operations. After reading this page, you will be able to: - Configure a Redpanda broker to run in FIPS-compliant mode - Set the required OpenSSL properties for FIPS mode - Deploy Redpanda in FIPS-compliant mode using Docker > 📝 **NOTE** > > This feature requires an [enterprise license](../../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../../get-started/licensing/#self-managed) apply. To check if you already have a license key applied to your cluster: ```bash rpk cluster license info ``` ## [](#prerequisites)Prerequisites Before configuring brokers to run in FIPS mode on Linux, install the `redpanda-rpk-fips` and `redpanda-fips` [packages](../../../deploy/redpanda/manual/production/production-deployment/#install-redpanda-for-fips-compliance). For Docker deployments, use the FIPS-specific image instead: `docker.redpanda.com/redpandadata/redpanda:-fips`. > ⚠️ **WARNING** > > Before upgrading to Redpanda 26.1 with FIPS mode enabled, change any SASL/SCRAM user passwords shorter than 14 characters to at least 14 characters. FIPS 140-3 enforces stricter HMAC key size requirements than FIPS 140-2. Because Redpanda stores passwords in encrypted form, it cannot check the length of existing passwords. Clients with passwords shorter than 14 characters will fail to authenticate after the upgrade. ## [](#limitations)Limitations - Redpanda FIPS mode requires a FIPS-enabled host when deployed with the Redpanda Helm chart or Operator. - Redpanda Console is not FIPS-compliant. - Redpanda does not support PKCS#12 keys for [TLS encryption](../encryption/) when FIPS mode is enabled. The PKCS12KDF algorithm used in PKCS#12 is not FIPS-compliant. To use Redpanda in FIPS mode with TLS enabled, configure your certificates and keys in PEM format instead. - When FIPS mode is `enabled` or `permissive`, SASL/SCRAM passwords must be at least 14 characters. ## [](#configure-fips-mode)Configure FIPS mode When you configure a broker to run in FIPS mode: - Redpanda enforces FIPS compliance _immediately_ on startup. - Redpanda and its dependencies only use FIPS-validated cryptographic modules for all cryptographic algorithms used in a security context. Redpanda logs an error and exits immediately if: - The underlying operating system and crypto module are not running in FIPS mode. - The underlying cryptography module enters into an error state. - It cannot detect a FIPS-validated library. To place a broker in FIPS-compliant mode, enable [`fips_mode`](../../../reference/properties/broker-properties/#fips_mode) in the Redpanda broker configuration file (typically located in `/etc/redpanda/redpanda.yaml`). All fields are within the `redpanda` object: ```yaml redpanda: # .... fips_mode: enabled ``` Available `fips_mode` values are: - `disabled`: Redpanda is not running in FIPS-compliant mode. - `enabled`: When Redpanda starts up, it looks for a value of `1` in the file `/proc/sys/crypto/fips_enabled`. If the file doesn’t exist or doesn’t contain `1`, Redpanda logs an error and exits immediately. - `permissive`: This setting is a safety value option only. Do not use it in a production environment. If specified, Redpanda logs a WARNING, but continues operations even if the underlying operating system is not configured for FIPS. If set, your Redpanda instance is _not_ running in FIPS-compliant mode. You must also configure OpenSSL properties for FIPS mode. ### [](#fips-openssl-configuration)FIPS OpenSSL configuration You must specify the following SSL configurations for brokers you want to run in FIPS-compliant mode: - [`openssl_config_file`](../../../reference/properties/broker-properties/#openssl_config_file): Specifies the path to the OpenSSL configuration file created during `redpanda-fips` package installation. OpenSSL uses this file during initialization to find the `fipsmodule.cnf` file that `openssl fipsinstall` creates. Typically, this value is `/opt/redpanda/openssl/openssl.cnf`. - [`openssl_module_directory`](../../../reference/properties/broker-properties/#openssl_module_directory): Specifies the path to the directory that contains the `fips.so` cryptographic provider. Typically, this value is: `/opt/redpanda/lib/ossl-modules/`. The following configuration starts Redpanda in FIPS mode: ```yaml redpanda: # .... fips_mode: enabled openssl_config_file: /opt/redpanda/openssl/openssl.cnf openssl_module_directory: /opt/redpanda/lib/ossl-modules/ ``` ## [](#configure-fips-mode-with-docker)Configure FIPS mode with Docker The Redpanda FIPS Docker image (`docker.redpanda.com/redpandadata/redpanda:-fips`) is available for `amd64` and `arm64` architectures. The image includes the required OpenSSL files, pre-configured. Pass the FIPS broker configuration to the container the same way as any other Redpanda Docker deployment: either by mounting a configuration file or by passing settings as flags. ### Mount a configuration file 1. Create a `redpanda.yaml` with the required FIPS settings: ```yaml redpanda: fips_mode: enabled openssl_config_file: /opt/redpanda/openssl/openssl.cnf openssl_module_directory: /opt/redpanda/lib/ossl-modules/ ``` 2. Mount the file when starting the container: ```bash docker run -d \ --name=redpanda \ -p 9092:9092 \ -p 9644:9644 \ -v /path/to/redpanda.yaml:/etc/redpanda/redpanda.yaml \ docker.redpanda.com/redpandadata/redpanda:-fips \ redpanda start --overprovisioned --smp 1 ``` ### Pass settings as flags Pass the FIPS settings directly to `redpanda start`: ```bash docker run -d \ --name=redpanda \ -p 9092:9092 \ -p 9644:9644 \ docker.redpanda.com/redpandadata/redpanda:-fips \ redpanda start --overprovisioned --smp 1 \ --set redpanda.fips_mode=enabled \ --set redpanda.openssl_config_file=/opt/redpanda/openssl/openssl.cnf \ --set redpanda.openssl_module_directory=/opt/redpanda/lib/ossl-modules/ ``` ## [](#next-steps)Next steps - [Install Redpanda for FIPS Compliance](../../../deploy/redpanda/manual/production/production-deployment/#install-redpanda-for-fips-compliance) - [OpenSSL FIPS Readme](https://github.com/openssl/openssl/blob/master/README-FIPS.md) --- # Page 233: IAM Roles **URL**: https://docs.redpanda.com/current/manage/security/iam-roles.md --- # IAM Roles --- title: IAM Roles latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: security/iam-roles page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: security/iam-roles.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/security/iam-roles.adoc description: For Redpanda Self-Managed clusters deployed on a public cloud platform, cloud provider IAM roles and managed identities provide a safer alternative to the less secure static credential system, which is based on access keys. page-git-created-date: "2023-06-02" page-git-modified-date: "2024-09-18" support-status: supported --- For Redpanda Self-Managed clusters deployed on a public cloud platform, cloud provider IAM roles (also known as managed identities) provide a safer alternative to the less secure static credential system, which is based on access keys. With static credentials, the access key and secret key are stored in plaintext in the configuration file. IAM roles are safer because they supply a role with temporary credentials that are dynamically sourced at runtime, and only last for the duration of a single session. These credentials allow you to access the data stored in an S3 bucket or Google Cloud Storage, as well as other resources. You can use IAM roles with any Redpanda feature that makes use of cloud storage, such as [Tiered Storage](../../tiered-storage/) or [Remote Read Replicas](../../remote-read-replicas/). > 📝 **NOTE** > > IAM roles and managed identities can only be configured for clusters deployed on a public cloud platform, such as Amazon Web Services (AWS), Google Cloud Platform (GCP) or Microsoft Azure. You cannot use IAM roles with on-premises clusters, even if you are using a feature that makes use of cloud storage. For on-premises clusters, you must use static access keys. ## [](#prerequisites)Prerequisites Before you can configure IAM roles in Redpanda, you must create a cloud storage bucket and create an IAM policy that will be used to access that bucket. An IAM policy specifies which operations can be performed, such as writing to and reading from a cloud storage bucket, and which resources can be accessed. ### [](#aws-prerequisites)AWS prerequisites If you are using Amazon Web Services (AWS) as your cloud provider, you must satisfy the following prerequisites: 1. [Create an S3 storage bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html). 2. [Create an IAM policy](https://aws.amazon.com/blogs/security/writing-iam-policies-how-to-grant-access-to-an-amazon-s3-bucket/). 3. [Create an IAM role and assign the policy to that role](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_job-functions_create-policies.html). 4. Tiered Storage with AWS requires that the user have the following permissions to read and create objects on the bucket to be used with the cluster (or on all buckets): `GetObject`, `DeleteObject`, `PutObject`, `PutObjectTagging`, `ListBucket`. 5. [Bind the VM](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html#attach-iam-role), or [Pod in the case of Kubernetes](https://docs.aws.amazon.com/eks/latest/userguide/specify-service-account-role.html), to the IAM role. > ⚠️ **CAUTION** > > `GetObject`, `DeleteObject`, `PutObject`, `PutObjectTagging`, and `ListBucket` are required to fully utilize cloud storage. If the bucket is dedicated to Redpanda, we recommend allowing all (\*) actions within the bucket. #### [](#sample-full-access-iam-policy)Sample full access IAM policy The following example policy grants full access to the `test` S3 bucket. ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:*" ], "Resource": [ "arn:aws:s3:::test", "arn:aws:s3:::test/*" ] } ] } ``` #### [](#sample-minimum-readwrite-iam-policy)Sample minimum read/write IAM policy This policy represents a minimum IAM policy for the `test` S3 buckets required when using Tiered Storage. ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:PutObject", "s3:PutObjectTagging", "s3:GetObject", "s3:DeleteObject" ], "Resource": "arn:aws:s3:::test/*" }, { "Effect": "Allow", "Action": [ "s3:ListBucket" ], "Resource": "arn:aws:s3:::test" } ] } ``` #### [](#sample-read-only-iam-policy)Sample read-only IAM policy A more restrictive "read-only" IAM policy is shown below. This policy only allows a user to get and list objects in the `test` S3 bucket. Such a policy could be used for a read replica topic on a remote cluster that hosts read replica topics, but not Tiered Storage topics. ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetObject" ], "Resource": [ "arn:aws:s3:::test/*" ] }, { "Effect": "Allow", "Action": [ "s3:ListBucket" ], "Resource": "arn:aws:s3:::test" } ] } ``` ### [](#gcp-prerequisites)GCP prerequisites If you are using Google Cloud Platform as your cloud provider, you must satisfy the following prerequisites: 1. [Create a storage bucket](https://cloud.google.com/storage/docs/creating-buckets). 2. [Create an IAM policy](https://cloud.google.com/iam/docs/policies) that specifies the principal, the role, and the role binding. For examples, see the [Google Cloud documentation](https://cloud.google.com/iam/docs/granting-changing-revoking-access#iam-grant-single-role-gcloud). > 📝 **NOTE** > > A full access policy with all storage bucket permissions is required for Tiered Storage. ### [](#azure-prerequisites)Azure prerequisites If you are using Microsoft Azure as your cloud provider, you must satisfy the following prerequisites: 1. [Create a user-assigned managed identity](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/how-manage-user-assigned-managed-identities?pivots=identity-mi-methods-azp#create-a-user-assigned-managed-identity)^. 2. [Create an Azure storage account](https://learn.microsoft.com/en-us/azure/storage/common/storage-account-create?tabs=azure-portal#create-a-storage-account-1)^. 3. [Create a container](https://learn.microsoft.com/en-us/azure/storage/blobs/blob-containers-portal#create-a-container)^ in the storage account. 4. Create a [custom role](https://learn.microsoft.com/en-us/azure/role-based-access-control/custom-roles) that only has the minimum permissions required for Tiered Storage, and assign the role to the identity. This helps prevent unauthorized actions on your data and minimize security risks. The custom role should have the following set of permissions: ```none "permissions": [ { "actions": [ ], "notActions": [], "dataActions": [ "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/delete", "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read", "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write", "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/add/action", "Microsoft.Storage/storageAccounts/fileServices/fileShares/files/write", "Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action" ], "notDataActions": [] } ] ``` Assign the identity either during the creation of the storage account, or for an existing storage account. See the [Azure Managed Identities](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/qs-configure-portal-windows-vm#user-assigned-managed-identity) documentation for more guidance. ## [](#configuring-iam-roles)Configuring IAM roles After satisfying the prerequisites for your cloud platform, edit the Redpanda cluster configuration by running `rpk cluster config edit`. Set the [`cloud_storage_credentials_source`](../../../reference/properties/object-storage-properties/#cloud_storage_credentials_source) property to the appropriate value for your use case. The following table shows all possible values and their descriptions. | Value | Description | | --- | --- | | config_file (default) | If IAM roles are not available, specify credentials in the cluster configuration file. | | aws_instance_metadata | For an AWS EC2 instance, use the instance metadata API from AWS. | | sts | For AWS on Kubernetes, use the Secure Token Service (STS). | | gcp_instance_metadata | For a VM running on GCP, or for Google Kubernetes Engine (GKE), use the instance metadata API from GCP. | | azure_vm_instance_metadata | For a VM running on Azure, use the Instance Metadata Service (IMDS) from Azure. | | azure_aks_oidc_federation | For Azure Kubernetes Service (AKS), use OIDC Issuer from Azure. | ## Suggested labs - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) [Search all labs](/redpanda-labs) --- # Page 234: Configure Listeners **URL**: https://docs.redpanda.com/current/manage/security/listener-configuration.md --- # Configure Listeners --- title: Configure Listeners latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: security/listener-configuration page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: security/listener-configuration.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/security/listener-configuration.adoc description: Use listeners to advertise the location of the broker, so other brokers in the cluster can be found. page-git-created-date: "2023-06-02" page-git-modified-date: "2025-10-14" support-status: supported --- Apache Kafka® client libraries must be able to connect to every Redpanda broker instance. If the client and broker are on different subnets, advertise the location of the broker in the Redpanda configuration file so other brokers in the cluster can be found. If not, clients connecting to brokers outside their local network experience connectivity issues. To try out Redpanda, see the [Redpanda quickstart](../../../get-started/quick-start/). ## [](#anatomy-of-a-listener)Anatomy of a listener Clients connect to Redpanda over TCP. A listener is defined by an interface address and port on the machine running Redpanda. For example: | Configuration | Description | | --- | --- | | address: 0.0.0.0 | Listens on all available interfaces. | | port: 9092 | TCP port for Kafka clients. | ```yaml redpanda: kafka_api: - address: 0.0.0.0 port: 9092 ``` ## [](#advertise-a-listener)Advertise a listener By default, the advertised address is the same as the bound address. For clients outside the local host or subnet, you must set an externally reachable address or hostname. Invalid settings, including `0.0.0.0`, will fail startup validation. ```yaml redpanda: advertised_kafka_api: - address: 192.168.4.1 # Broker’s routable IP or FQDN port: 9092 ``` > 📝 **NOTE** > > - Use a valid hostname or IP. Do not use `0.0.0.0`. > > - When using a DNS hostname, ensure that clients can resolve it and that it matches any TLS certificate Subject Alternative Name (SAN). ## [](#multiple-listeners)Multiple listeners You can define multiple Kafka API listeners to support different interfaces, ports, or authentication methods. Each listener must have a unique `name` property, and the same `name` property must be used in the corresponding [`advertised_kafka_api`](../../../reference/properties/broker-properties/#advertised_kafka_api) listener definition. For details about authentication methods, see the [`authentication_method`](../../../reference/properties/broker-properties/#kafka_api_auth_method) broker property. ```yaml redpanda: kafka_api: - name: local # Unique listener name address: 127.0.0.1 port: 9092 - name: subnet address: 192.168.4.1 port: 9093 advertised_kafka_api: - name: local # Must match the listener name address: 127.0.0.1 port: 9092 - name: subnet address: 192.168.4.1 port: 9093 ``` ## [](#tls-listeners-and-dns-hostnames)TLS listeners and DNS hostnames For encrypted connections, you typically advertise a DNS name matching your TLS certificate. Always include a `name` property for the TLS listener and use it in both [`kafka_api`](../../../reference/properties/broker-properties/#kafka_api) and [`advertised_kafka_api`](../../../reference/properties/broker-properties/#advertised_kafka_api). ```yaml redpanda: kafka_api: - name: tls_listener address: 0.0.0.0 port: 9094 authentication_method: mtls_identity advertised_kafka_api: - name: tls_listener address: redpanda.example.com port: 9094 kafka_api_tls: - name: tls_listener enabled: true key_file: /etc/redpanda/tls/broker.key cert_file: /etc/redpanda/tls/broker.crt truststore_file: /etc/redpanda/tls/ca.crt require_client_auth: true ``` Ensure `redpanda.example.com` matches the SAN in `broker.crt` and that clients trust the `ca.crt`. ## [](#mixed-mode-authentication-with-multiple-listeners)Mixed-mode authentication with multiple listeners Redpanda supports running multiple authentication schemes concurrently. Each listener can specify its [`authentication_method`](../../../reference/properties/broker-properties/#kafka_api_auth_method), and must define a `name` property. ```yaml redpanda: kafka_api: - name: sasl_listener address: 0.0.0.0 port: 9092 authentication_method: sasl - name: mtls_listener address: 0.0.0.0 port: 9192 authentication_method: mtls_identity kafka_api_tls: - name: mtls_listener key_file: mtls_broker.key cert_file: mtls_broker.crt truststore_file: mtls_ca.crt require_client_auth: true ``` ## [](#listeners-that-can-be-advertised)Listeners that can be advertised | Listener | Advertised Listener | Description | | --- | --- | --- | | kafka_api | advertised_kafka_api | Kafka clients connect here. | | rpc_server | advertised_rpc_api | Other Redpanda brokers connect here. | | pandaproxy_api | advertised_pandaproxy_api | HTTP proxy clients connect here. | For each advertised listener, match the `name` of the corresponding listener and provide a valid address and port. ## Suggested labs - [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](/redpanda-labs/docker-compose/oidc/) - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) [Search all labs](/redpanda-labs) --- # Page 235: Tiered Storage **URL**: https://docs.redpanda.com/current/manage/tiered-storage-linux.md --- # Tiered Storage --- title: Tiered Storage latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: tiered-storage-linux/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: tiered-storage-linux/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/tiered-storage-linux/index.adoc description: Tiered Storage helps to lower storage costs by offloading log segments to object storage. page-git-created-date: "2023-07-28" page-git-modified-date: "2024-08-15" support-status: supported --- With Tiered Storage, your cluster consists of two storage tiers, local and remote (using object storage with a cloud provider). Tiered Storage helps to lower storage costs by offloading log segments to object storage. Tiered Storage also provides simple data archiving that you can use for data recovery. Tiered Storage enables fast commission and decommission, remote read replicas, single topic recovery, and whole cluster restore, ensuring high availability of your Redpanda cluster. - [Use Tiered Storage](../tiered-storage/) Configure your Redpanda cluster to offload log segments to cloud storage and save storage costs. - [Fast Commission and Decommission Brokers](../fast-commission-decommission/) Configure fast partition movement during cluster resize for high availability. - [Mountable Topics](../mountable-topics/) Safely attach and detach Tiered Storage topics to and from a Redpanda cluster. --- # Page 236: Use Tiered Storage **URL**: https://docs.redpanda.com/current/manage/tiered-storage.md --- # Use Tiered Storage --- title: Use Tiered Storage latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: tiered-storage page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: tiered-storage.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/tiered-storage.adoc description: Configure your Redpanda cluster to offload log segments to cloud storage and save storage costs. page-git-created-date: "2023-05-30" page-git-modified-date: "2025-07-31" support-status: supported --- > 📝 **NOTE** > > This feature requires an [enterprise license](../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). > > If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../get-started/licensing/#self-managed) apply. Tiered Storage helps to lower storage costs by offloading log segments to object storage. You can specify the amount of storage you want to retain in local storage. You don’t need to specify which log segments you want to move, because Redpanda moves them automatically based on cluster-level configuration properties. Tiered Storage indexes where data is offloaded, so it can look up the data when you need it. The following image illustrates the Tiered Storage architecture: remote write uploads data from Redpanda to object storage, and remote read fetches data from object storage to Redpanda. ![Tiered Storage architecture](../../shared/_images/tiered_storage1.png) ## [](#prerequisites)Prerequisites This feature requires an [enterprise license](../../get-started/licensing/). To get a trial license key or extend your trial period, [generate a new trial license key](https://redpanda.com/try-enterprise). To purchase a license, contact [Redpanda Sales](https://redpanda.com/upgrade). If Redpanda has enterprise features enabled and it cannot find a valid license, [restrictions](../../get-started/licensing/#self-managed) apply. To check if you already have a license key applied to your cluster: ```bash rpk cluster license info ``` ## [](#limitations)Limitations - Migrating topics from one object storage provider to another is not supported. - Migrating topics from one bucket or container to another is not supported. - Multi-region buckets or containers are not supported. > ⚠️ **CAUTION** > > Redpanda Data recommends that you do not re-enable Tiered Storage after previously enabling and disabling it. Re-enabling Tiered Storage can result in inconsistent data and data gaps in Tiered Storage for a topic. ## [](#set-up-tiered-storage)Set up Tiered Storage To set up Tiered Storage: 1. [Configure object storage](#configure-object-storage). 2. [Enable Tiered Storage](#enable-tiered-storage). You can enable Tiered Storage for the cluster (all topics) or for specific topics. 3. [Set retention limits](#set-retention-limits). ### [](#configure-object-storage)Configure object storage Redpanda natively supports Tiered Storage with Amazon Simple Storage Service (S3), Google Cloud Storage (GCS, which uses the Google Cloud Platform S3 API), and Microsoft Azure Blob Storage (ABS) and Azure Data Lake Storage (ADLS). #### Amazon S3 > 💡 **TIP** > > If deploying Redpanda on an AWS Auto-Scaling group (ASG), keep in mind that the ASG controller terminates nodes and spins up replacements if the nodes saturate and are unable to heartbeat the controller (based on the EC2 health check). For more information, see the [AWS documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/monitoring-system-instance-status-check.html#types-of-instance-status-checks). Redpanda recommends deploying on Linux or Kubernetes. For more information, see [Deploy Redpanda](../../deploy/redpanda/). Configure access to Amazon S3 with either an IAM role attached to the instance, with access keys, or with customer-managed keys. > 💡 **TIP** > > If you need to manage and store encryption keys separately from your cloud provider, you can [configure access to an AWS S3 bucket that Redpanda Tiered Storage uses to leverage your AWS KMS key (SSE-KMS)](#configure-access-with-an-aws-kms-key) instead of the default AWS S3-managed key (SSE-S3). This option enables you to segregate data from different teams or departments and remove that data at will by removing the encryption keys. **Configure access with an IAM role** 1. Configure an [IAM role](../security/iam-roles/#configuring-iam-roles). 2. Run the `rpk cluster config edit` command, then edit the following required properties: ```properties cloud_storage_enabled: true cloud_storage_credentials_source: aws_instance_metadata cloud_storage_region: cloud_storage_bucket: ``` Replace `` with your own values. > ⚠️ **CAUTION** > > Do not set an object storage property to an empty string `""` or to `null` as a way to reset it to its default value. To reset a property to its default value, run `rpk cluster config force-reset ` or remove that line from the cluster configuration with `rpk cluster config edit`. **Configure access with access keys** 1. Grant a user the following permissions to read and create objects on the bucket to be used with the cluster (or on all buckets): `GetObject`, `DeleteObject`, `PutObject`, `PutObjectTagging`, `ListBucket`. 2. Copy the access key and secret key for the `cloud_storage_access_key` and `cloud_storage_secret_key` cluster properties. 3. Run the `rpk cluster config edit` command, then edit the following required properties: ```properties cloud_storage_enabled: true cloud_storage_access_key: cloud_storage_secret_key: cloud_storage_region: cloud_storage_bucket: ``` Replace `` with your own values. > ⚠️ **CAUTION** > > Do not set an object storage property to an empty string `""` or to `null` as a way to reset it to its default value. To reset a property to its default value, run `rpk cluster config force-reset ` or remove that line from the cluster configuration with `rpk cluster config edit`. #### **Configure access with an AWS KMS key** When there are strict data compliance requirements and you must manage and store encryption keys separate from your cloud provider, you can configure an Amazon S3 bucket that Tiered Storage can use to leverage your customer-provided key (SSE-KMS) instead of the default AWS-managed key (SSE-S3). To convert an existing S3 bucket and its contents, you must: 1. Create a new KMS key. 2. Configure the S3 bucket to use the new KMS key. 3. (Optional) Re-encrypt existing objects to use the new KMS key. > 📝 **NOTE** > > You cannot configure a cloud provider-managed encryption key at the topic level. > > For topic-level control, each CLI Get or Put for a partition must use the correct key as configured on the topic. ##### **Prerequisites** - The user configuring S3 bucket encryption must be assigned the Key admin permission. Without this permission, the user is unable to re-encrypt existing bucket objects to use the KMS key. - The S3 bucket must be assigned the Key user permission. Without this permission, Redpanda is unable to write new objects to Tiered Storage. - If you intend to retroactively re-encrypt existing data with the new KMS key, store the ARN identifier of the key upon creation. It is required for AWS CLI commands. To create a new KMS key in the AWS Console: 1. In AWS Console, search for “Key Management Service”. 2. Click **Create a key**. 3. On the Configure key page, select the **Symmetric** key type, then select **Encrypt and decrypt**. 4. Click the **Advanced options** tab and configure Key material origin and Regionality as needed. For example, if you are using [Remote Read Replicas](../remote-read-replicas/) or have Redpanda spanning across regions, select **Multi-Region key**. 5. Click **Next**. 6. On the Add labels page, specify an alias name and description for the key. Do not include sensitive information in these fields. 7. Click **Next**. 8. On the Define key administrative permissions page, specify a user who can administer this key through the KMS API. 9. Click **Next**. 10. On the Define key usage permissions page, assign the S3 bucket as a Key user. This is required for the S3 bucket to encrypt and decrypt. 11. Click **Next**. 12. Review your KMS key configuration and click **Finish**. For more information, see the [AWS documentation](https://docs.aws.amazon.com/kms/latest/developerguide/create-symmetric-cmk.html). To configure the S3 bucket to use the new KMS key (and reduce KMS costs through caching): 1. In AWS Console, search for "S3". 2. Select the bucket used by Redpanda. 3. Click the **Properties** tab. 4. In Default encryption, click **Edit**. 5. For Encryption type, select “Server-side encryption with AWS Key Management Service keys (SSE-KMS)”. 6. Locate and select your AWS KMS key ARN identifier. 7. Click **Save changes**. (Optional) To re-encrypt existing data using the new KMS key: Existing data in your S3 bucket continues to be read using the AWS-managed key, while new objects are encrypted using the new KMS key. If you wish to re-encrypt all S3 bucket data to use the KMS key, run: ```bash aws s3 cp s3://{BUCKET_NAME}/ s3://{BUCKET_NAME}/ --recursive --sse-kms-key-id {KMS_KEY_ARN} --sse aws:kms ``` For more information, see the [AWS documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/configuring-bucket-key.html). #### Google Cloud Storage Configure access to Google Cloud Storage with either an IAM role attached to the instance, with access keys, or with customer-managed keys. **Configure access with an IAM role** 1. Configure an [IAM role](../security/iam-roles/#configuring-iam-roles). 2. Run the `rpk cluster config edit` command, then edit the following required properties: ```properties cloud_storage_enabled: true cloud_storage_api_endpoint: storage.googleapis.com cloud_storage_credentials_source: gcp_instance_metadata cloud_storage_region: cloud_storage_bucket: ``` Replace `` with your own values. > ⚠️ **CAUTION** > > Do not set an object storage property to an empty string `""` or to `null` as a way to reset it to its default value. To reset a property to its default value, run `rpk cluster config force-reset ` or remove that line from the cluster configuration with `rpk cluster config edit`. **Configure access with access keys** 1. Choose a uniform access control when you create the bucket. 2. Use a Google-managed encryption key. 3. Set a [default project](https://cloud.google.com/storage/docs/migrating#defaultproj). 4. Create a service user with [HMAC keys](https://cloud.google.com/storage/docs/authentication/managing-hmackeys) and copy the access key and secret key for the `cloud_storage_access_key` and `cloud_storage_secret_key` cluster properties. 5. Run the `rpk cluster config edit` command, then edit the following required properties: ```properties cloud_storage_enabled: true cloud_storage_api_endpoint: storage.googleapis.com cloud_storage_access_key: cloud_storage_secret_key: cloud_storage_bucket: cloud_storage_region: ``` Replace `` with your own values. > ⚠️ **CAUTION** > > Do not set an object storage property to an empty string `""` or to `null` as a way to reset it to its default value. To reset a property to its default value, run `rpk cluster config force-reset ` or remove that line from the cluster configuration with `rpk cluster config edit`. #### **Configure access with a KMS key** To configure the Google Cloud bucket used by Redpanda Tiered Storage to leverage a customer-managed key using the Cloud Key Management Service API instead of the default Google-managed key, you must: 1. Create a KMS key. 2. Configure the bucket to use the KMS key. 3. Optionally, re-encrypt existing data with the new KMS key. To manage Google Cloud KMS using the command line, first install or upgrade to the latest version of [Google Cloud CLI](https://cloud.google.com/sdk/docs/install). To create a KMS key: 1. In Google Cloud Console, search for "Cloud Key Managment Service API". Click **Enable** if the service is not already enabled. 2. Using the Google Cloud CLI, create a new keyring in the [region](https://cloud.google.com/kms/docs/locations^) where the bucket used by Redpanda is located. Note that region is case sensitive. ```bash gcloud kms keyrings create "redpanda-keyring" --location="{REGION}" ``` 3. Create a new key for the keyring in the same region as the bucket: ```bash gcloud kms keys create "redpanda-key" \ --location="{REGION}" \ --keyring="redpanda-keyring" \ --purpose="encryption" ``` 4. Get the key identifier: ```bash gcloud kms keys list \ --location="REGION" \ --keyring="redpanda-keyring" ``` The result should look like the following. Be sure to store the name, as this is used to assign and manage the key. Use this as the {KEY\_RESOURCE} placeholder in subsequent commands. ```bash NAME PURPOSE ALGORITHM PROTECTION_LEVEL LABELS PRIMARY_ID PRIMARY_STATE projects/{PROJECT_NAME}/locations/us/keyRings/redpanda-keyring/cryptoKeys/redpanda-key ENCRYPT_DECRYPT GOOGLE_SYMMETRIC_ENCRYPTION SOFTWARE 1 ENABLED ``` To configure the GCP bucket to use the KMS key: 1. Assign the key to a service agent: ```bash gcloud storage service-agent \ --project={PROJECT_ID_STORING_OBJECTS} \ --authorize-cmek={KEY_RESOURCE} ``` 2. Set the bucket default encryption key to the KMS key: ```bash gcloud storage buckets update gs://{BUCKET_NAME} \ --default-encryption-key={KEY_RESOURCE} ``` (Optional) To re-encrypt existing data using the new KMS key: Existing data in the bucket continues to be read using the Google-managed key, while new objects are encrypted using the new KMS key. If you wish to re-encrypt all data in the bucket to use the KMS key, run: ```bash gcloud storage objects update gs://{BUCKET_NAME}/ --recursive \ --encryption-key={KEY_RESOURCE} ``` #### Microsoft ABS/ADLS > 📝 **NOTE** > > Starting in release 23.2.8, Redpanda supports storage accounts configured for ADLS Gen2 with [hierarchical namespaces](https://learn.microsoft.com/en-us/azure/storage/blobs/data-lake-storage-namespace) enabled. For hierarchical namespaces created with a custom endpoint, set `cloud_storage_azure_adls_endpoint` and `cloud_storage_azure_adls_port`. If you haven’t configured custom endpoints in Azure, there’s no need to edit these properties. **Configure access with managed identities** 1. Configure an [Azure managed identity](../security/iam-roles/#azure-prerequisites). Note the minimum set of permissions required for Tiered Storage: - Microsoft.Storage/storageAccounts/blobServices/containers/blobs/delete - Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read - Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write - Microsoft.Storage/storageAccounts/blobServices/containers/blobs/add/action - Microsoft.Storage/storageAccounts/fileServices/fileShares/files/write - Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action 2. Run the `rpk cluster config edit` command, then edit the following required properties: ```properties cloud_storage_enabled: true cloud_storage_credentials_source: azure_vm_instance_metadata cloud_storage_azure_managed_identity_id: cloud_storage_azure_storage_account: cloud_storage_azure_container: ``` Replace `` with your own values. **Configure access with account access keys** 1. Copy an account access key for the Azure container you want Redpanda to use and enter it in the `cloud_storage_azure_shared_key` property. For information on how to view your account access keys, see the [Azure documentation](https://learn.microsoft.com/en-us/azure/storage/common/storage-account-keys-manage?toc=%2Fazure%2Fstorage%2Fblobs%2Ftoc.json&bc=%2Fazure%2Fstorage%2Fblobs%2Fbreadcrumb%2Ftoc.json&tabs=azure-portal#view-account-access-keys). 2. Run the `rpk cluster config edit` command, then edit the following required properties: ```properties cloud_storage_enabled: true cloud_storage_azure_shared_key: cloud_storage_azure_storage_account: cloud_storage_azure_container: ``` Replace `` with your own values. For information about how to grant access from an internet IP range (if you need to open additional routes/ports between your broker nodes and ABS/ADLS; for example, in a hybrid cloud deployment), see the [Microsoft documentation](https://learn.microsoft.com/en-us/azure/storage/common/storage-network-security?toc=%2Fazure%2Fstorage%2Fblobs%2Ftoc.json&bc=%2Fazure%2Fstorage%2Fblobs%2Fbreadcrumb%2Ftoc.json&tabs=azure-portal#grant-access-from-an-internet-ip-range). For information about Shared Key authentication, see the [Microsoft documentation](https://learn.microsoft.com/en-us/rest/api/storageservices/authorize-with-shared-key). > ⚠️ **CAUTION** > > Do not set an object storage property to an empty string `""` or to `null` as a way to reset it to its default value. To reset a property to its default value, run `rpk cluster config force-reset ` or remove that line from the cluster configuration with `rpk cluster config edit`. For additional properties, see [Tiered Storage configuration properties](#tiered-storage-configuration-properties). ### [](#enable-tiered-storage)Enable Tiered Storage 1. To enable Tiered Storage, set `[cloud_storage_enabled](../../reference/properties/object-storage-properties/#cloud_storage_enabled)` to `true`. 2. Configure topics for Tiered Storage. You can configure either all topics in a cluster or only specific topics. - [Enable Tiered Storage for a cluster](#enable-tiered-storage-for-a-cluster) - [Enable Tiered Storage for specific topics](#enable-tiered-storage-for-specific-topics) When you enable Tiered Storage on a topic already containing data, Redpanda uploads any existing data in that topic on local storage to the object store bucket. It will start from the earliest offset available on local disk. Redpanda strongly recommends that you avoid repeatedly toggling remote write on and off, because this can result in inconsistent data and data gaps in Tiered Storage for a topic. #### [](#enable-tiered-storage-for-a-cluster)Enable Tiered Storage for a cluster To enable Tiered Storage for a cluster (in addition to setting `cloud_storage_enabled` to `true`), set the following cluster-level properties to `true`: - `[cloud_storage_enable_remote_write](../../reference/properties/object-storage-properties/#cloud_storage_enable_remote_write)` - `[cloud_storage_enable_remote_read](../../reference/properties/object-storage-properties/#cloud_storage_enable_remote_read)` When you enable Tiered Storage for a cluster, you enable it for all existing topics in the cluster. You must restart your cluster after enabling Tiered Storage. > 📝 **NOTE** > > `cloud_storage_enable_remote_write` and `cloud_storage_enable_remote_read` act as creation-time defaults only for topics with `redpanda.storage.mode=unset`. They have no effect on topics where `redpanda.storage.mode` is explicitly set to `local`, `tiered`, or `cloud`. To apply a default storage mode to all new topics, use the `[default_redpanda_storage_mode](../../reference/properties/cluster-properties/#default_redpanda_storage_mode)` cluster property instead. #### [](#enable-tiered-storage-for-specific-topics)Enable Tiered Storage for specific topics Starting in Redpanda v26.1, the recommended way to enable Tiered Storage for a topic is to set the `redpanda.storage.mode` topic property to `tiered`: ```bash rpk topic create -c redpanda.storage.mode=tiered ``` To enable Tiered Storage on an existing topic that was created in `local` mode: ```bash rpk topic alter-config --set redpanda.storage.mode=tiered ``` When `redpanda.storage.mode=tiered` is set, Tiered Storage is fully enabled for the topic. The `redpanda.remote.read` and `redpanda.remote.write` topic properties have no effect on a topic’s storage when `redpanda.storage.mode` is set to any value other than `unset`. #### [](#configure-tiered-storage-using-legacy-topic-properties)Configure Tiered Storage using legacy topic properties For topics with `redpanda.storage.mode=unset` (the default when `default_redpanda_storage_mode` is not configured), Tiered Storage is controlled by the `redpanda.remote.read` and `redpanda.remote.write` topic properties: - `redpanda.remote.write`: Uploads data from Redpanda to object storage. - `redpanda.remote.read`: Fetches data from object storage to Redpanda. For example, to create a topic using the legacy properties when the storage mode is `unset`: ```bash rpk topic create -c redpanda.remote.read=true -c redpanda.remote.write=true ``` To enable Tiered Storage on an existing topic where the storage mode is `unset`: ```bash rpk topic alter-config --set redpanda.remote.read=true --set redpanda.remote.write=true ``` For newly-created unset topics, the cluster-level `cloud_storage_enable_remote_write` and `cloud_storage_enable_remote_read` properties dictate the topic-level properties `redpanda.remote.write` and `redpanda.remote.read` at topic creation time, respectively. Altering the cluster properties has no effect on existing topics, only newly-created ones. To alter the permissions for existing topics, you can set these topic properties directly. For example, `redpanda.remote.write=false` to disable uploads for a specific topic. Tiered Storage topic-level properties: | Property | Description | | --- | --- | | redpanda.remote.write | Uploads data from Redpanda to object storage. For topics with redpanda.storage.mode=unset, overrides the cluster-level cloud_storage_enable_remote_write setting. Has no effect on topics with redpanda.storage.mode set to local, tiered, or cloud. | | redpanda.remote.read | Fetches data from object storage to Redpanda. For topics with redpanda.storage.mode=unset, overrides the cluster-level cloud_storage_enable_remote_read setting. Has no effect on topics with redpanda.storage.mode set to local, tiered, or cloud. | | redpanda.remote.recovery | Recovers or reproduces a topic from object storage. Use this property during topic creation. It does not apply to existing topics. | | redpanda.remote.delete | When set to true, deleting a topic also deletes its objects in object storage. Applies to both Tiered Storage topics and Cloud Topics.For Tiered Storage topics, the topic must not be a Remote Read Replica topic.When set to false, deleting a topic does not delete its objects in object storage.Default is true for new topics. | The following tables show outcomes for combinations of cluster-level and topic-level configurations for topics with `redpanda.storage.mode=unset` at topic creation time: | Cluster-level configuration with cloud_storage_enable_remote_write | Topic-level configuration with redpanda.remote.write | Outcome: whether remote write is enabled or disabled on the topic | | --- | --- | --- | | true | Not set | Enabled | | true | false | Disabled | | true | true | Enabled | | false | Not set | Disabled | | false | false | Disabled | | false | true | Enabled | | Cluster-level configuration with cloud_storage_enable_remote_read | Topic-level configuration with redpanda.remote.read | Outcome: whether remote read is enabled or disabled on the topic | | --- | --- | --- | | true | Not set | Enabled | | true | false | Disabled | | true | true | Enabled | | false | Not set | Disabled | | false | false | Disabled | | false | true | Enabled | ### [](#set-retention-limits)Set retention limits Redpanda supports retention limits and compaction for topics using Tiered Storage. Set retention limits to purge topic data after it reaches a specified age or size. Starting in Redpanda version 22.3, object storage is the default storage tier for all streaming data, and retention properties work the same for Tiered Storage topics and local storage topics. Data is retained in object storage until it reaches the configured time or size limit. Data becomes eligible for deletion from object storage following `retention.ms` or `retention.bytes`. For example, if `retention.bytes` is set to 10 GiB, then every partition in the topic has a limit of 10 GiB in object storage. When `retention.bytes` is exceeded by data in object storage, the data in object storage is trimmed. If neither `retention.ms` nor `retention.bytes` is specified, then cluster-level defaults are used. > 📝 **NOTE** > > - During upgrade, Redpanda preserves retention settings for existing topics. > > - Both size-based and time-based retention policies are applied simultaneously, so it’s possible for your size-based property to override your time-based property, or vice versa. For example, if your size-based property requires removing one segment, and your time-based property requires removing three segments, then three segments are removed. Size-based properties reclaim disk space as close as possible to the maximum size, without exceeding the limit. See also: [Configure message retention](../cluster-maintenance/disk-utilization/#configure-message-retention) and [Space management](../cluster-maintenance/disk-utilization/#space-management) #### [](#compacted-topics-in-tiered-storage)Compacted topics in Tiered Storage When you set [`cleanup.policy`](../../reference/properties/topic-properties/#cleanuppolicy) for a topic to `compact`, nothing gets deleted from object storage based on retention settings. When set to `compact,delete`, compacted segments are deleted from object storage based on `retention.ms` and `retention.bytes`. For compacted topics, Redpanda compacts segments after they have been uploaded to object storage. Redpanda initially uploads all uncompacted segments. It then re-uploads the segments with compaction applied. It’s likely that some segments in object storage are not compacted, but the Tiered Storage read path can manage this. #### [](#manage-local-capacity-for-tiered-storage-topics)Manage local capacity for Tiered Storage topics You can use properties to control retention of topic data in local storage. With Tiered Storage enabled, data in local storage expires after the topic-level properties `retention.local.target.ms` or `retention.local.target.bytes`. (These settings are equivalent to `retention.ms` and `retention.bytes` without Tiered Storage.) You can also use the cluster-level properties `retention_local_target_ms_default` and `retention_local_target_bytes_default`. Settings can depend on the size of your drive, how many partitions you have, and how much data you keep for each partition. When set, Redpanda keeps actively-used and sequential (next segment) data in local cache and targets to maintain this age of data in local storage. It purges data based on actual available local volume space, without forcing disk full situations when there is data skew. At topic creation with Tiered Storage enabled: - If `retention.ms` or `retention.bytes` is set, Redpanda initializes the `retention.local.target.*` properties. - If `retention.local.target.ms` or `retention.local.target.bytes` is set, Redpanda initializes the `min(retention.bytes, retention.local.target.bytes)` and `max(retention.ms, retention.local.target.ms)` properties. - If properties are not specified: - Starting in version 22.3, new topics use the default retention values of one day for local storage (`[retention_local_target_ms_default](../../reference/properties/cluster-properties/#retention_local_target_ms_default)`) and seven days for all storage, including object storage (`[log_retention_ms](../../reference/properties/cluster-properties/#log_retention_ms)`). - Upgraded topics retain their historical defaults of infinite retention. After topic configuration, if Tiered Storage was disabled and must be enabled, or was enabled and must be disabled, Redpanda uses the local retention properties set for the topic. It is strongly recommended that you do not re-enable Tiered Storage after previously enabling and disabling it. Re-enabling Tiered Storage can result in inconsistent data and data gaps in Tiered Storage for a topic. See also: [Space management](../cluster-maintenance/disk-utilization/#space-management) ## [](#view-space-usage)View space usage Use [`rpk cluster logdirs describe`](../../reference/rpk/rpk-cluster/rpk-cluster-logdirs-describe/) to get details about Tiered Storage space usage in both object storage and local disk. The directories for object storage start with `remote://`. For example: ```bash rpk cluster logdirs describe BROKER DIR TOPIC PARTITION SIZE ERROR 0 /home/redpanda/var/node0/data monday 0 18406863 0 remote://data monday 0 60051220 1 /home/redpanda/var/node1/data monday 0 22859882 1 remote://data monday 0 60051220 2 /home/redpanda/var/node2/data monday 0 17169935 2 remote://data monday 0 60051220 ``` ### [](#integration-with-space-utilization-tools)Integration with space utilization tools Third-party tools that query space utilization from the Redpanda cluster might not handle `remote://` entries properly. Redpanda space usage is reported from each broker, but object storage is shared between brokers. Third-party tools could over-count storage and show unexpectedly high disk usage for Tiered Storage topics. In this situation, you can disable output of `remote://` entries by setting `kafka_enable_describe_log_dirs_remote_storage` to `false`. ## [](#remote-write)Remote write Remote write is the process that constantly uploads log segments to object storage. The process is created for each partition and runs on the leader broker of the partition. It only uploads the segments that contain offsets that are smaller than the last stable offset. This is the latest offset that the client can read. To ensure all data is uploaded, you must enable remote write before any data is produced to the topic. If you enable remote write after data has been written to the topic, only the data that currently exists on disk based on local retention settings will be scheduled for uploading. Redpanda strongly recommends that you avoid repeatedly toggling remote write on and off, because this can result in inconsistent data and data gaps in Tiered Storage for a topic. To enable Tiered Storage, use both remote write and remote read. To create a topic with remote write enabled: ```bash rpk topic create -c redpanda.remote.write=true ``` To enable remote write on an existing topic: ```bash rpk topic alter-config --set redpanda.remote.write=true ``` If remote write is enabled, log segments are not deleted until they’re uploaded to object storage. Because of this, the log segments may exceed the configured retention period until they’re uploaded, so the topic might require more disk space. This prevents data loss if segments cannot be uploaded fast enough or if the retention period is very short. To see the object storage status for a given topic: ```bash rpk topic describe-storage --print-all ``` See the [reference](../../reference/rpk/rpk-topic/rpk-topic-describe-storage/) for a list of flags you can use to filter the command output. > 💡 **TIP** > > A constant stream of data is necessary to build up the log segments and roll them into object storage. This upload process is asynchronous. You can monitor its status with the [`/metrics/vectorized_ntp_archiver_pending`](../../reference/internal-metrics-reference/#vectorized_ntp_archiver_pending) metric. > > To see new log segments faster, you can edit the `segment.bytes` topic-level property. Or, you can edit the [`cloud_storage_segment_max_upload_interval_sec`](../../reference/properties/object-storage-properties/#cloud_storage_segment_max_upload_interval_sec) property, which sets the frequency with which new segments are generated in Tiered Storage, even if the local segment has not exceeded the `segment.bytes` size or the `segment.ms` age. > 📝 **NOTE** > > Starting in version 22.3, when you delete a topic in Redpanda, the data is also deleted in object storage. See [Enable Tiered Storage for specific topics](#enable-tiered-storage-for-specific-topics). ### [](#idle-timeout)Idle timeout You can configure Redpanda to start a remote write periodically. This is useful if the ingestion rate is low and the segments are kept open for long periods of time. You specify a number of seconds for the timeout, and if that time has passed since the previous write and the partition has new data, Redpanda starts a new write. This limits data loss in the event of catastrophic failure and adds a guarantee that you only lose the specified number of seconds of data. Setting idle timeout to a very short interval can create a lot of small files, which can affect throughput. If you decide to set a value for idle timeout, start with 600 seconds, which prevents the creation of so many small files that throughput is affected when you recover the files. Use the [`cloud_storage_segment_max_upload_interval_sec`](../../reference/properties/object-storage-properties/#cloud_storage_segment_max_upload_interval_sec) property to set the number of seconds for idle timeout. If this property is set to null, Redpanda uploads metadata to object storage, but the segment is not uploaded until it reaches the `segment.bytes` size. ### [](#reconciliation)Reconciliation Reconciliation is a Redpanda process that monitors partitions and decides which partitions are uploaded on each broker to guarantee that data is uploaded only once. It runs periodically on every broker. It also balances the workload evenly between brokers. > 📝 **NOTE** > > The broker uploading to object storage is always with the partition leader. Therefore, when partition leadership balancing occurs, Redpanda stops uploads to object storage from one broker and starts uploads on another broker. ### [](#upload-backlog-controller)Upload backlog controller Remote write uses a proportional derivative (PD) controller to minimize the backlog size for the write. The backlog consists of data that has not been uploaded to object storage but must be uploaded eventually. The upload backlog controller prevents Redpanda from running out of disk space. If `remote.write` is set to `true`, Redpanda cannot evict log segments that have not been uploaded to object storage. If the remote write process cannot keep up with the amount of data that needs to be uploaded to object storage, the upload backlog controller increases priority for the upload process. The upload backlog controller measures the size of the upload periodically and tunes the priority of the remote write process. ### [](#data-archiving)Data archiving If you only enable remote write on a topic, you have a simple backup to object storage that you can use for recovery. In the event of a data center failure, data corruption, or cluster migration, you can recover your archived data from the cloud back to your cluster. #### [](#configure-data-archiving)Configure data archiving Data archiving requires a [Tiered Storage configuration](#set-up-tiered-storage). To recover a topic from object storage, use [single topic recovery](../disaster-recovery/topic-recovery/). > ⚠️ **WARNING** > > While performing topic recovery, avoid adding additional load (such as produces, consumes, lists or additional recovery operations) to the target cluster. Doing so could destabilize the recovery process and result in either an unsuccessful or corrupted recovered topic. #### [](#stop-data-archiving)Stop data archiving To cancel archiving jobs, disable remote write. To delete archival data, adjust `retention.ms` or `retention.bytes`. ## [](#remote-read)Remote read Remote read fetches data from object storage using the Kafka API. Without Tiered Storage, when data is evicted locally, it is no longer available. If the consumer starts consuming the partition from the beginning, the first offset is the smallest offset available locally. However, when Tiered Storage is enabled with the `redpanda.remote.read` and `redpanda.remote.write` properties, data is always uploaded to object storage before it’s deleted. This guarantees that data is always available either locally or remotely. When data is available remotely and Tiered Storage is enabled, clients can consume data, even if the data is no longer stored locally. To create a topic with remote read enabled: ```bash rpk topic create -c redpanda.remote.read=true ``` To enable remote read on an existing topic: ```bash rpk topic alter-config --set redpanda.remote.read=true ``` See also: [Topic Recovery](../disaster-recovery/topic-recovery/), [Remote Read Replicas](../kubernetes/k-remote-read-replicas/) ## [](#pause-and-resume-uploads)Pause and resume uploads > ❗ **IMPORTANT** > > Redpanda strongly recommends using pause and resume only under the guidance of [Redpanda Support](https://support.redpanda.com/hc/en-us/requests/new) or a member of your account team. Starting in version 25.1, you can troubleshoot issues your cluster has interacting with object storage by pausing and resuming uploads. You can do this with no risk of data consistency or data loss. To pause or resume segment uploads to object storage, use the [`cloud_storage_enable_segment_uploads`](../../reference/properties/object-storage-properties/#cloud_storage_enable_segment_uploads) configuration property (default is `true`). This allows segment uploads to proceed after the pause completes and uploads resume. While uploads are paused, data accumulates locally, which can lead to full disks if the pause is prolonged. If the disks fill, Redpanda throttles produce requests and rejects new Kafka produce requests to prevent data from being written. Additionally, this pauses object storage housekeeping, meaning segments are neither uploaded nor removed from object storage. However, it is still possible to consume data from object storage while uploads are paused. When you set `cloud_storage_enable_segment_uploads` to `false`, all in-flight segment uploads complete, but no new segment uploads begin until the value is set back to `true`. During this pause, Tiered Storage enforces consistency by ensuring that no segment in local storage is deleted until it successfully uploads to object storage. This means that when uploads are resumed, no user intervention is needed, and no data gaps are created. Use the `redpanda_cloud_storage_paused_archivers` metric to monitor the status of paused uploads. It displays a non-zero value whenever uploads are paused. > ⚠️ **WARNING** > > Do not use `redpanda.remote.read` or `redpanda.remote.write` to pause and resume segment uploads. Doing so can lead to a gap between local data and data in object storage. In such cases, it is possible that the oldest segment is not aligned with the last uploaded segment. Given that these settings are unsafe, if you choose to set either `redpanda.remote.write` or the cluster configuration setting `cloud_storage_enable_remote_write` to `false`, you receive a warning: > > ```bash > Warning: disabling Tiered Storage may lead to data loss. If you only want to pause Tiered Storage temporarily, use the `cloud_storage_enable_segment_uploads` option. Abort? > # The default is Yes. > ``` The following example shows a simple pause and resume with no gaps allowed: ```bash rpk cluster config set cloud_storage_enable_segment_uploads false # Segments are not uploaded to cloud storage, and cloud storage housekeeping is not running. # The new data added to the topics with Tiered Storage is not deleted from disk # because it can't be uploaded. The disks may fill up eventually. # If the disks fill up, produce requests will be rejected. ... rpk cluster config set cloud_storage_enable_segment_uploads true # At this point the uploads should resume seamlessly and # there should not be any data loss. ``` For some applications, where the newest data is more valuable than historical data, data accumulation can be worse than data loss. In such cases, where you cannot afford to lose the most recently-produced data by rejecting produce requests after producers have filled the local disks during the period of paused uploads, there is a less safe pause and resume mechanism. This mechanism prioritizes the ability to receive new data over retaining data that cannot be uploaded when disks are full: - Set the [`cloud_storage_enable_remote_allow_gaps`](../../reference/properties/object-storage-properties/#cloud_storage_enable_remote_allow_gaps) cluster configuration property to `true`. This allows for gaps in the logs of all Tiered Storage topics in the cluster. When you pause uploads and set one of these properties to `true`, there may be gaps in the range of offsets stored in object storage. You can seamlessly resume uploads by setting `*allow_gaps` to `true` at either the cluster or topic level. If set to `false`, disk space could be depleted and produce requests would be throttled. The following example shows how to pause and resume Tiered Storage uploads while allowing for gaps: ```bash rpk cluster config set cloud_storage_enable_segment_uploads false # Segment uploads are paused and cloud storage housekeeping is not running. # New data is stored on the local volume, which may overflow. # To avoid overflow when allowing gaps in the log. # In this example, data that is not uploaded to cloud storage may be # deleted if a disk fills before uploads are resumed. ... rpk cluster config set cloud_storage_enable_segment_uploads true # Uploads are resumed but there could be gaps in the offsets. # Wait until you see that the `redpanda_cloud_storage_paused_archivers` # metric is equal to zero, indicating that uploads have resumed. ``` ## [](#caching)Caching When a consumer fetches an offset range that isn’t available locally in the Redpanda data directory, Redpanda downloads remote segments from object storage. These downloaded segments are stored in the object storage cache. ### [](#change-the-cache-directory)Change the cache directory By default, the cache directory is created in Redpanda’s data directory, but it can be placed anywhere in the system. For example, you might want to put the cache directory on a dedicated drive with cheaper storage. Use the [`cloud_storage_cache_directory`](../../reference/properties/broker-properties/#cloud_storage_cache_directory) broker property to specify a different location for the cache directory. You must specify the full path. ### [](#max-cache)Set a maximum cache size To ensure that the cache does not grow uncontrollably, which could lead to performance issues or disk space exhaustion, you can control the maximum size of the cache. Redpanda checks the cache periodically according to the interval set in `[cloud_storage_cache_check_interval_ms](../../reference/properties/object-storage-properties/#cloud_storage_cache_check_interval_ms)`. If the size of the stored data exceeds the configured limit, the eviction process starts. This process removes segments that haven’t been accessed recently until the cache size drops to the target level. **Related properties**: - `[cloud_storage_cache_size_percent](../../reference/properties/object-storage-properties/#cloud_storage_cache_size_percent)` - `[cloud_storage_cache_max_objects](../../reference/properties/object-storage-properties/#cloud_storage_cache_max_objects)` - `[cloud_storage_cache_size](../../reference/properties/object-storage-properties/#cloud_storage_cache_size)` **Recommendation**: By default, `cloud_storage_cache_size_percent` is tuned for a shared disk configuration. If you are using a dedicated cache disk, consider increasing this value. #### [](#cache-trimming)Cache trimming Cache trimming helps to balance optimal cache use with the need to avoid blocking reads due to a full cache. The trimming process is triggered when the cache exceeds certain thresholds relative to the [maximum cache size](#max-cache). **Related properties**: - `[cloud_storage_cache_trim_threshold_percent_objects](../../reference/properties/object-storage-properties/#cloud_storage_cache_trim_threshold_percent_objects)` - `[cloud_storage_cache_trim_threshold_percent_size](../../reference/properties/object-storage-properties/#cloud_storage_cache_trim_threshold_percent_size)` - `[cloud_storage_cache_trim_walk_concurrency](../../reference/properties/object-storage-properties/#cloud_storage_cache_trim_walk_concurrency)` **Recommendations**: - A threshold of 70% is recommended for most use cases. This percentage helps balance optimal cache use and ensures the cache has enough free space to handle sudden spikes in data without blocking reads. For example, setting `cloud_storage_cache_trim_threshold_percent_size` to 80% means that the cache trimming process starts when the cache takes up 80% of the maximum cache size. - Monitor the behavior of your cache and the performance of your Redpanda cluster. If reads are taking longer than expected or if you encounter timeout errors, your cache may be filling up too quickly. In these cases, consider lowering the thresholds to trigger trimming sooner. > 📝 **NOTE** > > The lower you set the threshold, the earlier the trimming starts, but it can also waste cache space. A higher threshold uses more cache space efficiently, but it risks blocking reads if the cache fills up too quickly. Adjust the settings based on your workload and monitor the cache performance to find the right balance for your environment. ### [](#chunk-remote-segments)Chunk remote segments To support more concurrent consumers of historical data with less local storage, Redpanda can download small chunks of remote segments to the cache directory. For example, when a client fetch request spans a subsection of a 1 GiB segment, instead of downloading the entire 1 GiB segment, Redpanda can download 16 MiB chunks that contain just enough data required to fulfill the fetch request. Use the `[cloud_storage_cache_chunk_size](../../reference/properties/object-storage-properties/#cloud_storage_cache_chunk_size)` property to define the size of the chunks. The paths on disk to a chunk are structured as `p_chunks/{chunk_start_offset}`, where `p` is the original path to the segment in the object storage cache. The `_chunks/` subdirectory holds chunk files identified by the chunk start offset. These files can be reclaimed by the cache eviction process during the normal eviction path. ### [](#chunk-eviction-strategies)Chunk eviction strategies Selecting an appropriate chunk eviction strategy helps manage cache space effectively. A chunk that isn’t shared with any data source can be evicted from the cache, so space is returned to disk. Use the `[cloud_storage_chunk_eviction_strategy](../../reference/properties/object-storage-properties/#cloud_storage_chunk_eviction_strategy)` property to change the eviction strategy. The strategies are: - `eager` (default): Evicts chunks that aren’t shared with other data sources. Eviction is fast, because no sorting is involved. - `capped`: Evicts chunks until the number of hydrated chunks is below or equal to the maximum hydrated chunks at a time. This limit is for each segment and calculated using `cloud_storage_hydrated_chunks_per_segment_ratio` by the remote segment. Eviction is fastest, because no sorting is involved, and the process stops after the cap is reached. - `predictive`: Uses statistics from readers to determine which chunks to evict. Chunks that aren’t in use are sorted by the count of readers that will use the chunk in the future. The counts are populated by readers using the chunk data source. The chunks that are least expensive to re-hydrate are then evicted, taking into account the maximum hydrated chunk count. Eviction is slowest, because chunks are sorted before evicting them. **Recommendation**: For general use, the `eager` strategy is recommended due to its speed. For workloads with specific access patterns, the `predictive` strategy may offer better cache efficiency. ### [](#caching-and-chunking-properties)Caching and chunking properties Use the following cluster-level properties to set the maximum cache size, the cache check interval, and chunking qualities. Edit them with the `rpk cluster config edit` command. | Property | Description | | --- | --- | | cloud_storage_cache_check_interval_ms | The time, in milliseconds, between cache checks. The size of the cache can grow quickly, so it’s important to have a small interval between checks. However, if the checks are too frequent, they consume a lot of resources. Default is 30000 ms (30 sec). | | cloud_storage_cache_chunk_size | The size of a chunk downloaded into object storage cache. Default is 16 MiB. | | cloud_storage_cache_directory | The directory where the cache archive is stored. | | cloud_storage_cache_max_objects | Maximum number of objects that may be held in the Tiered Storage cache. This applies simultaneously with cloud_storage_cache_size, and whichever limit is hit first will trigger trimming of the cache. | | cloud_storage_cache_num_buckets | Divide the object storage cache across the specified number of buckets. This only works for objects with randomized prefixes. The names are not changed when the value is set to zero. | | cloud_storage_cache_size_percent | Maximum size (as a percentage) of the disk cache used by Tiered Storage.If both this property and cloud_storage_cache_size are set, Redpanda uses the minimum of the two. | | cloud_storage_cache_size | Maximum size (in bytes) of the disk cache used by Tiered Storage.If both this property and cloud_storage_cache_size_percent are set, Redpanda uses the minimum of the two. | | cloud_storage_cache_trim_threshold_percent_objects | Trigger cache trimming when the number of objects in the cache reaches this percentage relative to its maximum object count. If unset, the default behavior is to start trimming when the cache is full. | | cloud_storage_cache_trim_threshold_percent_size | Trigger cache trimming when the cache size reaches this percentage relative to its maximum capacity. If unset, the default behavior is to start trimming when the cache is full. | | cloud_storage_cache_trim_walk_concurrency | The maximum number of concurrent tasks launched for traversing the directory structure during cache trimming. A higher number allows cache trimming to run faster but can cause latency spikes due to increased pressure on I/O subsystem and syscall threads. | | cloud_storage_chunk_eviction_strategy | Strategy for evicting unused cache chunks, either eager (default), capped, or predictive. | | cloud_storage_disable_chunk_reads | Flag to turn off chunk-based reads and enable full-segment downloads. Default is false. | | cloud_storage_hydrated_chunks_per_segment_ratio | The ratio of hydrated to non-hydrated chunks for each segment, where a current ratio above this value results in unused chunks being evicted. Default is 0.7. | | cloud_storage_min_chunks_per_segment_threshold | The threshold below which all chunks of a segment can be hydrated without eviction. If the number of chunks in a segment is below this threshold, the segment is small enough that all chunks in it can be hydrated at any given time. Default is 5. | ## [](#retries-and-backoff)Retries and backoff If the object storage provider replies with an error message that the server is busy, Redpanda retries the request. Redpanda may retry on other errors, depending on the object storage provider. Redpanda always uses exponential backoff with cloud connections. You can configure the `[cloud_storage_initial_backoff_ms](../../reference/properties/object-storage-properties/#cloud_storage_initial_backoff_ms)` property to set the time used as an initial backoff interval in the exponential backoff algorithm to handle an error. Default is 100 ms. ## [](#transport)Transport Tiered Storage creates a connection pool for each CPU that limits simultaneous connections to the object storage provider. It also uses persistent HTTP connections with a configurable maximum idle time. A custom S3 client is used to send and receive data. For normal usage, you do not need to configure the transport properties. The Redpanda defaults are sufficient, and the certificates used to connect to the object storage client are available through public key infrastructure. Redpanda detects the location of the CA certificates automatically. Redpanda uses the following properties to configure transport. Edit them with the `rpk cluster config edit` command. | Property | Description | | --- | --- | | cloud_storage_max_connections | The maximum number of connections to object storage on a broker for each CPU. Remote read and remote write share the same pool of connections. This means that if a connection is used to upload a segment, it cannot be used to download another segment. If this value is too small, some workloads might starve for connections, which results in delayed uploads and downloads. If this value is too large, Redpanda tries to upload a lot of files at the same time and might overwhelm the system. Default is 20. | | cloud_storage_segment_upload_timeout_ms | Timeout for segment upload. Redpanda retries the upload after the timeout. Default is 30000 ms. | | cloud_storage_manifest_upload_timeout_ms | Timeout for manifest upload. Redpanda retries the upload after the timeout. Default is 10000 ms. | | cloud_storage_max_connection_idle_time_ms | The maximum idle time for persistent HTTP connections. This differs depending on the object storage provider. Default is 5000 ms, which is sufficient for most providers. | | cloud_storage_segment_max_upload_interval_sec | The number of seconds for idle timeout. If this property is empty, Redpanda uploads metadata to the object storage, but the segment is not uploaded until it reaches the segment.bytes size. By default, the property is empty. | | cloud_storage_trust_file | The public certificate used to validate the TLS connection to object storage. If this is empty, Redpanda uses your operating system’s CA cert pool. | ## [](#object-storage-housekeeping)Object storage housekeeping To improve performance and scalability, Redpanda performs object storage housekeeping when the system is idle. This housekeeping includes adjacent segment merging, which analyzes the data layout of the partition in object storage. If it finds a run of small segments, it can merge and reupload the segment. To determine when the system is idle for housekeeping, Redpanda constantly calculates object storage utilization using the moving average with a sliding window algorithm. The width of the sliding window is defined by the `[cloud_storage_idle_timeout_ms](../../reference/properties/object-storage-properties/#cloud_storage_idle_timeout_ms)` property, which has a default of 10 seconds. If the utilization (requests per second) drops below the threshold, then object storage is considered idle, and object storage housekeeping begins. The threshold is defined by the `[cloud_storage_idle_threshold_rps](../../reference/properties/object-storage-properties/#cloud_storage_idle_threshold_rps)` property, which has a default of one request per second. Object storage is considered idle if, during the last 10 seconds, there were 10 or less object storage API requests. If the object storage API becomes active after housekeeping begins, then housekeeping is paused until it becomes idle again. If object storage is not idle for `[cloud_storage_housekeeping_interval_ms](../../reference/properties/object-storage-properties/#cloud_storage_housekeeping_interval_ms)`, then housekeeping is forced to run until it completes. This guarantees that all housekeeping jobs are run once for every `cloud_storage_housekeeping_interval_ms`. See also: [Space management](../cluster-maintenance/disk-utilization/#space-management) ### [](#adjacent-segment-merging)Adjacent segment merging By default, and as part of this object storage housekeeping, Redpanda runs adjacent segment merging on all segments in object storage that are smaller than the threshold. Two properties control the behavior of `[cloud_storage_enable_segment_merging](../../reference/properties/object-storage-properties/#cloud_storage_enable_segment_merging)`: - `[cloud_storage_segment_size_target](../../reference/properties/object-storage-properties/#cloud_storage_segment_size_target)`: The desired segment size in object storage. The default segment size is the local segment size for the topic, which is controlled by the `[log_segment_size](../../reference/properties/cluster-properties/#log_segment_size)` configuration property and the `segment.bytes` topic property. You can set the `cloud_storage_segment_size_target` property to a value larger than the default segment size, but because this triggers a lot of segment re-uploads, it’s not recommended. - `[cloud_storage_segment_size_min](../../reference/properties/object-storage-properties/#cloud_storage_segment_size_min)`: The smallest segment size that Redpanda keeps in object storage. The default is 50% of `[log_segment_size](../../reference/properties/cluster-properties/#log_segment_size)`. If the adjacent segment merging job finds a run of small segments, it can perform one of the following operations: - Merge and re-upload a segment with a size up to `cloud_storage_segment_size_target`. - Merge and re-upload a segment with a size less than `cloud_storage_segment_size_min` if there are no other options (the run of small segments is followed by the large segment). - Wait until new segments are added if the run is at the end of the partition. Suppose the `[cloud_storage_segment_max_upload_interval_sec](../../reference/properties/object-storage-properties/#cloud_storage_segment_max_upload_interval_sec)` property is set and the partition contains a large number of small segments. For example, if `sec` is set to 10 minutes and the produce rate is 1 MiB per minute, then Redpanda uploads a new 10 MiB segment every 10 minutes. If adjacent segment merging is enabled and `cloud_storage_segment_size_target` is set to 500 MiB, then every 50 segments are re-uploaded as one large 500 MiB segment. This doubles the amount of data that Redpanda uploads to object storage, but it also reduces the memory footprint of the partition, which results in better scalability because 98% less memory is needed to keep information about the uploaded segment. > 📝 **NOTE** > > Adjacent segment merging doesn’t work for compacted topics, because compacted segments are reuploaded after they’re compacted. The results are the same. ## [](#archived-metadata)Archived metadata As data in object storage grows, the metadata for it grows. Starting in version 23.2, Redpanda archives older metadata in object storage to support efficient long-term data retention. Only metadata for recently-updated segments is kept in memory or on local disk, while the rest is safely stored in object storage and cached locally as needed. Archived metadata is loaded only when historical data is accessed. This allows Tiered Storage to handle partitions of virtually any size or retention length. You can configure these object storage properties to control the metadata archiving behavior: | Property | Description | | --- | --- | | cloud_storage_spillover_manifest_size | When the in-memory manifest size for a partition exceeds double this value, Redpanda triggers metadata spillover. The oldest metadata is packaged into a new spillover manifest and uploaded to object storage, after which the in-memory manifest is truncated. This process continues until the in-memory manifest size falls below the threshold. (Default: 65536 bytes) | | cloud_storage_spillover_manifest_max_segments | Triggers the upload of metadata to object storage when the number of segments in the spillover manifest exceeds this value. Redpanda recommends using this property only in testing scenarios, and cloud_storage_spillover_manifest_size in production settings. (Default: null) | | cloud_storage_manifest_cache_size | Controls the amount of memory used by the cache for spilled manifests. (Default: 1048576 bytes) | ## [](#tiered-storage-configuration-properties)Tiered Storage configuration properties The following list contains cluster-level configuration properties for Tiered Storage. Configure or verify the following properties before you use Tiered Storage: | Property | Description | | --- | --- | | cloud_storage_enabled | Global property that enables Tiered Storage.Set to true to enable Tiered Storage. Default is false. | | cloud_storage_region | Object storage region.Required for AWS and GCS. | | cloud_storage_bucket | AWS or GCS bucket name.Required for AWS and GCS. | | cloud_storage_credentials_source | AWS or GCS instance metadata.Required for AWS and GCS authentication with IAM roles. | | cloud_storage_access_key | AWS or GCS access key.Required for AWS and GCS authentication with access keys. | | cloud_storage_secret_key | AWS or GCS secret key.Required for AWS and GCS authentication with access keys. | | cloud_storage_api_endpoint | AWS or GCS API endpoint.For AWS, this can be left blank. It’s generated automatically using the region and bucket.For GCS, you must use storage.googleapis.com. | | cloud_storage_azure_container | Azure container name.Required for ABS/ADLS. | | cloud_storage_azure_storage_account | Azure account name.Required for ABS/ADLS. | | cloud_storage_azure_shared_key | Azure storage account access key.Required for ABS/ADLS. | | cloud_storage_cache_size_percent | Maximum size (as a percentage) of the disk cache used by Tiered Storage.If both this property and cloud_storage_cache_size are set, Redpanda uses the minimum of the two. | | cloud_storage_cache_size | Maximum size of the disk cache used by Tiered Storage.If both this property and cloud_storage_cache_size_percent are set, Redpanda uses the minimum of the two. | | disk_reservation_percent | Amount of disk space (as a percentage) reserved for general system overhead.Default is 20%. | | retention_local_target_capacity_bytes | Target size (in bytes) of the log data.Default is not set (null). | | retention_local_target_capacity_percent | Target size (as a percentage) of the log data.Default is the amount of remaining disk space after deducting cloud_storage_cache_size_percent and disk_reservation_percent. | | retention_local_strict | Allows the housekeeping process to remove data above the configured consumable retention. This means that data usage is allowed to expand to occupy more of the log data reservation.Default is false. | | retention_local_trim_interval | Period at which disk usage is checked for disk pressure, where data is optionally trimmed to meet the target.Default is 30 seconds. | In addition, you might want to change the following property for each broker: | Property | Description | | --- | --- | | cloud_storage_cache_directory | The directory for the Tiered Storage cache. You must specify the full path. Default is: /cloud_storage_cache. | You may want to configure the following properties: | Property | Description | | --- | --- | | cloud_storage_max_connections | The maximum number of connections to object storage on a broker for each CPU. Remote read and remote write share the same pool of connections. This means that if a connection is used to upload a segment, it cannot be used to download another segment. If this value is too small, some workloads might starve for connections, which results in delayed uploads and downloads. If this value is too large, Redpanda tries to upload a lot of files at the same time and might overwhelm the system. Default is 20. | | initial_retention_local_target_bytes_default | The initial local retention size target for partitions of topics with Tiered Storage enabled. Default is null. | | initial_retention_local_target_ms_default | The initial local retention time target for partitions of topics with Tiered Storage enabled. Default is null. | | cloud_storage_initial_backoff_ms | The time, in milliseconds, for an initial backoff interval in the exponential backoff algorithm to handle an error. Default is 100 ms. | | cloud_storage_segment_upload_timeout_ms | Timeout for segment upload. Redpanda retries the upload after the timeout. Default is 30000 ms. | | cloud_storage_manifest_upload_timeout_ms | Timeout for manifest upload. Redpanda retries the upload after the timeout. Default is 10000 ms. | | cloud_storage_max_connection_idle_time_ms | The maximum idle time for persistent HTTP connections. Differs depending on the object storage provider. Default is 5000 ms, which is sufficient for most providers. | | cloud_storage_segment_max_upload_interval_sec | Sets the number of seconds for idle timeout. If this property is empty, Redpanda uploads metadata to the object storage, but the segment is not uploaded until it reaches the segment.bytes size. By default, the property is empty. | | cloud_storage_cache_check_interval_ms | The time, in milliseconds, between cache checks. The size of the cache can grow quickly, so it’s important to have a small interval between checks, but if the checks are too frequent, they consume a lot of resources. Default is 30000 ms. | | cloud_storage_idle_timeout_ms | The width of the sliding window for the moving average algorithm that calculates object storage utilization. Default is 10 seconds. | | cloud_storage_idle_threshold_rps | The utilization threshold for object storage housekeeping. Object storage is considered idle if, during the last 10 seconds, there were 10 or less object storage API requests. Default is 1 request per second. | | cloud_storage_enable_segment_merging | Enables adjacent segment merging on all segments in object storage that are smaller than the threshold. Two properties control this behavior: cloud_storage_segment_size_target and cloud_storage_segment_size_min. Default is enabled. | | cloud_storage_segment_size_target | The desired segment size in object storage. The default segment size is controlled by log_segment_size and the segment.bytes topic configuration property. This property can be set to a value larger than this default segment size, but because that triggers a lot of segment reuploads, it’s not recommended. | | cloud_storage_segment_size_min | The smallest segment size in object storage that Redpanda keeps. Default is 50% of log segment size. | Under normal circumstances, you should not need to configure the following tunable properties: | Property | Description | | --- | --- | | cloud_storage_upload_ctrl_update_interval_ms | The recompute interval for the upload controller. Default is 60000 ms. | | cloud_storage_upload_ctrl_p_coeff | The proportional coefficient for the upload controller. Default is -2. | | cloud_storage_upload_ctrl_d_coeff | The derivative coefficient for the upload controller. Default is 0. | | cloud_storage_upload_ctrl_min_shares | The minimum number of I/O and CPU shares that the remote write process can use. Default is 100. | | cloud_storage_upload_ctrl_max_shares | The maximum number of I/O and CPU shares that the remote write process can use. Default is 1000. | | cloud_storage_disable_tls | Disables TLS encryption. Set to true if TLS termination is done by the proxy, such as HAProxy. Default is false. | | cloud_storage_api_endpoint_port | Overrides the default API endpoint port. Default is 443. | | cloud_storage_trust_file | The public certificate used to validate the TLS connection to object storage. If this is empty, Redpanda uses your operating system’s CA cert pool. | | cloud_storage_reconciliation_interval_ms | Deprecated.The interval, in milliseconds, to reconcile partitions that need to be uploaded. A long reconciliation interval can result in a delayed reaction to topic creation, topic deletion, or leadership rebalancing events. A short reconciliation interval guarantees that new partitions are picked up quickly, but the process uses more resources. Default is 10000 ms. | ## [](#suggested-reading)Suggested reading - [How we built Tiered Storage to supercharge storage and data streaming](https://www.redpanda.com/blog/tiered-storage-architecture-deep-dive) ## Suggested labs - [Redpanda Iceberg Docker Compose Example](/redpanda-labs/docker-compose/iceberg/) - [Iceberg Streaming on Kubernetes with Redpanda, MinIO, and Spark](/redpanda-labs/kubernetes/iceberg/) [Search all labs](/redpanda-labs) --- # Page 237: Manage Redpanda using the Admin API **URL**: https://docs.redpanda.com/current/manage/use-admin-api.md --- # Manage Redpanda using the Admin API --- title: Manage Redpanda using the Admin API latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: use-admin-api page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: use-admin-api.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/use-admin-api.adoc description: Manage components of a Redpanda cluster, such as individual brokers and partition leadership. The Redpanda Admin API also allows you to perform operations that are specific to Redpanda Self-Managed and cannot be done using the standard Kafka API. page-git-created-date: "2025-11-19" page-git-modified-date: "2025-11-19" support-status: supported --- The Redpanda Admin API allows you to manage your cluster and perform operations specific to Redpanda Self-Managed that are not available through the standard Kafka API. You can call the Admin API using any HTTP client. Most Admin API operations are also available using [`rpk`](../../get-started/intro-to-rpk/), a CLI tool that interacts with the Admin API under the hood. Redpanda v25.3 introduces new endpoints to the Admin API that are served with [ConnectRPC](https://connectrpc.com/docs/introduction). New Redpanda features and operations available starting in v25.3 are accessible as RPC services through these new endpoints. Existing Admin API operations from versions earlier than 25.3 remain available at their current URLs and you can continue to use them as usual (including with rpk v25.3 and later). ## [](#prerequisites)Prerequisites - A running Redpanda Self-Managed cluster. - Superuser privileges, if [authentication](../security/authentication/#enable-authentication) is enabled on your cluster for the Admin API. For more information, see [Configure Authentication](../security/authentication/#create-superusers). (Some endpoints are read-only and do not require superuser access.) - A tool to make HTTP requests, such as `curl`, or client libraries for your programming language of choice. - For Admin API operations introduced in v25.3 and later, you can also make requests using a ConnectRPC client. You can install the Connect plugin for your preferred language and use the Protobuf compiler to generate an SDK. These RPC services are also available in a Buf module, which you can access through the [Buf Schema Registry](https://buf.build/redpandadata/core/docs/dev:redpanda.core.admin.v2). The [Buf CLI](https://buf.build/docs/cli/) provides an easy way to generate client SDKs. ## [](#use-the-admin-api)Use the Admin API Starting in Redpanda v25.3, in addition to RESTful HTTP endpoints, the Admin API serves new endpoints as ConnectRPC services. You can use either autogenerated Protobuf clients or HTTP requests to call ConnectRPC services. Both new and legacy (RESTful) endpoints are accessible on the same port (default: 9644), but they use different URL paths. > 📝 **NOTE** > > Legacy Admin API endpoints remain available and fully supported. Use them for operations not yet available as ConnectRPC services. ### [](#authentication)Authentication If authentication is enabled on your cluster, you must provide credentials with each request, either using HTTP Basic authentication or by including an `Authorization` header with a bearer token. For example: ```bash curl -u : -X GET "http://localhost:9644/v1/cluster_config" ``` ### [](#use-legacy-restful-endpoints)Use legacy (RESTful) endpoints The base URL for all requests to the legacy endpoints is: ```none http://:/v1/ ``` For a full list of available endpoints, see the [Admin API Reference](/api/doc/admin/v1/). Select "v1" in the version selector to view legacy endpoints. #### [](#example-request)Example request To use the Admin API to [decommission a broker](../cluster-maintenance/decommission-brokers/): ##### curl Send a PUT request to the [`/v1/brokers/{broker_id}/decommission`](/api/doc/admin/operation/operation-decommission) endpoint: ```bash curl \ -u : \ --request PUT 'http://:/v1/brokers//decommission' ``` ##### rpk For Linux deployments only, run [`rpk redpanda admin brokers decommission`](../../reference/rpk/rpk-redpanda/rpk-redpanda-admin-brokers-decommission/): ```bash rpk redpanda admin brokers decommission ``` ### [](#use-connectrpc-endpoints)Use ConnectRPC endpoints The new endpoints differ from the legacy endpoints in the following ways: - You can use a generated ConnectRPC client to call methods directly from your application code, or send `curl` requests with a JSON payload, as with legacy endpoints. - URL paths use the fully-qualified names of the ConnectRPC services. - ConnectRPC endpoints accept only POST requests. Use ConnectRPC endpoints with features introduced in v25.3 such as: - Shadowing - Connected client monitoring For a full list of available endpoints, see the [Admin API Reference](/api/doc/admin/v2/). Select "v2" in the version selector to view the ConnectRPC endpoints. #### [](#example-request-2)Example request To fail over a specific shadow topic from an existing shadow link: ##### curl Send a POST request to the [`redpanda.core.admin.v2.ShadowLinkService/FailOver`](/api/doc/admin/v2/operation/operation-redpanda-core-admin-v2-shadowlinkservice-failover) endpoint: ```bash curl \ -u : \ --request POST 'http://:/redpanda.core.admin.v2.ShadowLinkService/FailOver' \ --header "Content-Type: application/json" \ --data '{ "name": "", "shadowTopicName": "" }' ``` - Request headers `Connect-Protocol-Version` and `Connect-Timeout-Ms` are optional. - v2 endpoints also accept binary-encoded Protobuf request bodies. Use the `Content-Type: application/proto` header. ##### rpk Run `rpk shadow failover`: ```bash rpk shadow failover --topic ``` --- # Page 238: Migrate **URL**: https://docs.redpanda.com/current/migrate.md --- # Migrate --- title: Migrate latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/migrate/pages/index.adoc description: Find guidance on migrating to new features or from deprecated features to newer versions. page-git-created-date: "2025-05-07" page-git-modified-date: "2025-05-07" support-status: supported --- - [Migrate to Redpanda Console v3.0.0](console-v3/) - [Migrate Data to Redpanda with MirrorMaker 2](data-migration/) Use MirrorMaker 2 to replicate data between Redpanda clusters. - [Migrate from the Redpanda Helm chart](kubernetes/helm-to-operator/) If you are using the Redpanda Helm chart, you can migrate to the Redpanda Operator and use it to manage your deployment. - [Migrate from Strimzi to Redpanda Operator](kubernetes/strimzi/) This guide explores the migration from Strimzi to Redpanda Operator, highlighting key differences, deployment strategies, and how to leverage Kubernetes for managing Kafka clusters effectively. --- # Page 239: Migrate to Redpanda Console v3.0.0 **URL**: https://docs.redpanda.com/current/migrate/console-v3.md --- # Migrate to Redpanda Console v3.0.0 --- title: Migrate to Redpanda Console v3.0.0 latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: console-v3 page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: console-v3.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/migrate/pages/console-v3.adoc page-git-created-date: "2025-05-07" page-git-modified-date: "2025-12-04" support-status: supported --- 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](../../console/config/security/authentication/). For a list of breaking changes, see [What’s New in Redpanda](../../get-started/release-notes/redpanda/). > 💡 **TIP: Try the Redpanda Console migration tool** > > Use the [migration tool](#migrator) to convert your v2 configuration to v3 format. ## [](#choose-your-migration-path)Choose your migration path Your migration approach depends on how you deploy Redpanda Console. ### [](#kubernetes-with-redpanda-operator)Kubernetes with Redpanda Operator The operator automatically migrates most v2 configurations when you upgrade. Review the [Automatic migration in Kubernetes](#automatic-migration-in-kubernetes) section to understand what’s handled automatically and what requires manual intervention. ### [](#other-deployment-methods)Other deployment methods Manually migrate your configuration using this guide and the [migration tool](#migrator). Start with [Authentication and authorization migration](#authentication-and-authorization-migration). ## [](#pre-migration-checklist)Pre-migration checklist Review your v2 configuration and check which of these breaking changes apply to you: - Have you configured Console with authentication? You must choose a v3 strategy. See [Authentication decision](#authentication-decision). - Do you use OIDC groups for authorization? They are not supported in v3. See [OIDC groups and realms](#oidc-groups-and-realms). - Do you configure more than one OIDC provider? You can use only one provider in v3. See [Multiple OIDC providers](#multiple-oidc-providers). - Is your Schema Registry configured under `kafka.schemaRegistry`? Move the configuration to the top level in v3. See [Schema Registry moves to top level](#schema-registry-moves-to-top-level). - Are your role bindings in a separate file? Move role bindings to inline configuration in v3. See [Configuration location change](#configuration-location-change). ### [](#authentication-decision)Authentication decision You must decide on your v3 authentication strategy before migrating. #### [](#user-impersonation-recommended)User impersonation (recommended) 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)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. > 📝 **NOTE** > > For most deployments, user impersonation provides better security and auditability. ### [](#track-your-migration-progress)Track your migration progress Use this checklist to track your migration: - Reviewed [breaking changes and pre-migration checklist](#pre-migration-checklist) - Decided on [authentication strategy](#key-authentication-decision) (impersonation or static credentials) - Tested configuration with [migration tool](#migrator) - Updated [authentication configuration](#authentication-and-authorization-migration) - Migrated [role bindings](#role-bindings-migration) (if applicable) - Configured [ACLs in Redpanda](#migrate-redpanda-console-roles-to-redpanda-acls) (if using impersonation) - Updated [Schema Registry configuration location](#configuration-structure-changes) - Updated [serialization and Kafka Connect configuration](#configuration-structure-changes) - Deployed updated configuration - Validated [user login works](#validate-migration) - Validated [resource access works](#validate-migration) (topics, groups, Schema Registry) - Reviewed and resolved all [warnings](#manual-configuration-steps) (Kubernetes deployments) ## [](#automatic-migration-in-kubernetes)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. > ❗ **IMPORTANT** > > 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)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](#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)Check for migration warnings Before reviewing the migration details, check if your Console custom resource has warnings: ```bash kubectl get console -n -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](#unsupported-features). If you don’t see warnings, review the [Supported configuration mappings](#supported-configuration-mappings) to verify the automatic migration matches your expectations, especially around authentication strategy (impersonation vs static credentials). ### [](#supported-configuration-mappings)Supported configuration mappings The operator automatically migrates the following configuration fields: | 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. | | 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 | | 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 | | 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)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)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)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)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)Manual configuration steps After the operator completes automatic migration, review any warnings and complete the manual configuration steps: 1. Check for warnings: ```bash kubectl get console -n -o jsonpath='{.spec.warnings}' ``` 2. Review each warning against the [Unsupported features](#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](#validate-migration) For details on the `warnings` field structure, see [ConsoleSpec](../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-consolespec). ## [](#authentication-and-authorization-migration)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)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](../../console/config/security/authentication/). Here is an example of how to migrate from the plain login provider to user impersonation: V2 plain login with RBAC ```yaml 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 ```yaml 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](../../manage/security/authorization/). If you prefer to disable user impersonation so that static credentials are used instead, modify your configuration as follows: V3 static credentials ```yaml 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. | > ❗ **IMPORTANT** > > 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](../../manage/security/authorization/). ### [](#migrate-from-oidc-providers)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](../../console/config/security/authentication/). > 📝 **NOTE** > > 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 ```yaml 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 ```yaml 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)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)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 ```yaml 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 ```yaml authorization: roleBindings: - roleName: admin users: - loginType: basic name: alice ``` #### [](#group-subject-removal)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](#migrate-acls). During automatic migration in Kubernetes, group subjects are removed and warnings are generated. See [Group-based role bindings](#group-based-role-bindings). #### [](#migrate-acls)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 | ```bash # 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: - [Configure Access Control Lists](../../manage/security/authorization/acl/) - [Authorization in Redpanda Console](../../console/config/security/authorization/) ## [](#configuration-structure-changes)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)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 ```yaml 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 ```yaml 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)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)Kafka Connect renamed to kafkaConnect The `connect` configuration stanza is renamed to `kafkaConnect` for clarity. V2 serde and Kafka Connect ```yaml kafka: protobuf: enabled: false mappings: [] cbor: enabled: false messagePack: enabled: false console: maxDeserializationPayloadSize: 20480 connect: enabled: false clusters: [] ``` V3 serde and Kafka Connect ```yaml serde: maxDeserializationPayloadSize: 20480 protobuf: enabled: false mappings: [] cbor: enabled: false messagePack: enabled: false kafkaConnect: enabled: false clusters: [] ``` ## [](#validate-migration)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)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: ```bash kubectl get console -n -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](#automatic-migration-in-kubernetes). For details on the `warnings` field, see [ConsoleSpec](../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-consolespec). ## [](#troubleshooting)Troubleshooting ### [](#users-cannot-log-in-after-migration)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)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: ```bash rpk security user create alice -p ``` For more information, see [Configure Authentication](../../manage/security/authentication/). #### [](#oidc-provider-mismatch)OIDC provider mismatch If you had multiple OIDC providers in v2, only one was selected during migration. Check which provider was selected: ```bash kubectl get console -o jsonpath='{.spec.warnings}' ``` Review the warning message and ensure your users are authenticating with the selected provider. #### [](#jwt-token-requirement-not-met)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](#migrate-from-oidc-providers) for details. ### [](#users-can-log-in-but-cannot-access-resources)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)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: ```bash # 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\]](#migrate-redpanda-console-roles-to-redpanda-acls). #### [](#role-bindings-not-migrated-correctly)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](#role-bindings-migration). ### [](#schema-registry-or-kafka-connect-not-working)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)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](#configuration-structure-changes) for examples. #### [](#impersonation-settings-incorrect)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)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. ## [](#migrator)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. Load sample Clear Migrate 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. Copy output ## [](#suggested-reading)Suggested reading - [Authentication in Redpanda Console](../../console/config/security/authentication/) - [Redpanda Console Security](../../console/config/security/) - [Configure Authentication](../../manage/security/authentication/) - [Configure Authorization](../../manage/security/authorization/) --- # Page 240: Migrate Data to Redpanda with MirrorMaker 2 **URL**: https://docs.redpanda.com/current/migrate/data-migration.md --- # Migrate Data to Redpanda with MirrorMaker 2 --- title: Migrate Data to Redpanda with MirrorMaker 2 latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: data-migration page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: data-migration.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/migrate/pages/data-migration.adoc description: Use MirrorMaker 2 to replicate data between Redpanda clusters. page-git-created-date: "2025-05-07" page-git-modified-date: "2025-11-19" support-status: supported --- When you want to migrate data from Kafka or replicate data between Redpanda clusters, you can use the MirrorMaker 2 (MM2) tool bundled in the Kafka download package. This section describes the process of configuring MirrorMaker 2 to replicate data from one Redpanda cluster to another. MirrorMaker 2 reads a configuration file that specifies the connection details for the Redpanda clusters, as well as other options. After you start MirrorMaker 2, the data migration continues according to the configuration at launch time until you shutdown the MirrorMaker 2 process. See the [Kafka downloads page](https://kafka.apache.org/downloads) for download instructions, and the [Kafka documentation](https://kafka.apache.org/documentation/#georeplication) for details on cross-cluster data mirroring with MirrorMaker 2. ## [](#prerequisites)Prerequisites To set up the replication, you need: - 2 Redpanda clusters - Redpanda’s migration mechanism is independent of the underlying cluster version or cluster platform, so you can set up these clusters in any deployment you like, including [Kubernetes](../../deploy/redpanda/kubernetes/get-started-dev/), and [Linux](../../deploy/redpanda/manual/production/). - MirrorMaker 2 host - You install MirrorMaker 2 on a separate system or on one of the Redpanda clusters, as long as the IP addresses and ports on each cluster are accessible from the MirrorMaker 2 host. You must install the [Java Runtime Engine (JRE)](https://docs.oracle.com/javase/10/install/toc.htm) on the MirrorMaker 2 host. ## [](#install-mirrormaker-2)Install MirrorMaker 2 MirrorMaker 2 is run by a shell script that is part of the Kafka download package. To install MirrorMaker 2 on the machine that you want to run the replication between the clusters: 1. Download the latest [Kafka download package](https://kafka.apache.org/downloads). For example: ```bash curl -O https://dlcdn.apache.org/kafka/3.3.1/kafka_2.13-3.3.1.tgz ``` 2. Extract the files from the archive: ```bash tar -xvf kafka_2.13-3.3.1.tgz ``` ## [](#create-the-mirrormaker-2-configuration-files)Create the MirrorMaker 2 configuration files MirrorMaker 2 uses configuration files to get the connection details for the clusters. You can find the MirrorMaker 2 script and configuration files in the expanded Kafka directory. . └── kafka\_2.13-3.3.1 └── bin └── connect-mirror-maker.sh └── config └── connect-mirror-maker.properties The sample configuration describes a number of the settings for MirrorMaker 2. To create a basic configuration file, go to the `config` and run: ```bash cat << EOF > mm2.properties // Name the clusters clusters = , // Assign IP addresses to the cluster names .bootstrap.servers = :9092 .bootstrap.servers = :9092 // Set replication for all topics from Redpanda 1 to Redpanda 2 ->.enabled = true ->.topics = .* // Setting replication factor of newly created remote topics replication.factor = 1 //Make sure that your target cluster can accept larger message sizes. For example, 30MB messages .producer.max.request.size=31457280 //Set the frequency at which to check the source cluster for new topics (default is 10 minutes) refresh.topics.interval.seconds = 5 //Make sure topics are created without a prefix replication.policy.class=org.apache.kafka.connect.mirror.IdentityReplicationPolicy EOF ``` > 📝 **NOTE** > > Remember to edit the variable names on the examples for your environment. For example, `` can become `redpanda_1`. ## [](#run-mirrormaker-2-to-start-replication)Run MirrorMaker 2 to start replication To start MirrorMaker 2 in the `kafka_2.13-3.3.1/bin/` directory, run: ```bash ./kafka_2.13-3.3.1/bin/connect-mirror-maker.sh mm2.properties ``` With this command, MirrorMaker 2 consumes all topics from the `` cluster and replicates them into the `` cluster. MirrorMaker 2 adds the prefix `` to the names of replicated topics. ## [](#change-topic-replication-factor)Change topic replication factor The `replication.factor` property is a topic property set at topic creation. A replication factor of three generally provides a good balance between broker loss and replication overhead. You can increase or decrease the replication factor on an existing topic. For example, if topics were initially created in a test environment with a replication factor of `1` (no replication), to change the topic replication factor to `3`, run: ```bash rpk topic alter-config [TOPICS...] --set replication.factor=3 ``` ## [](#see-migration-in-action)See migration in action Here are the basic commands to produce and consume streams: 1. Create a topic in the source cluster called "twitch\_chat": ```bash rpk topic create twitch_chat -X brokers=: ``` 2. Produce messages to the topic: ```bash rpk topic produce twitch_chat -X brokers=: ``` Type text into the topic and press Ctrl + D to separate between messages. Press Ctrl + C to exit the produce command. 3. Consume (read) the messages from the destination cluster: ```bash rpk topic consume twitch_chat -X brokers=: ``` Each message is shown with its metadata like the following: ```json { "message": "How do you stream with Redpanda?\n", "partition": 0, "offset": 1, "timestamp": "2021-02-10T15:52:35.251+02:00" } ``` Now you know the replication is working. ## [](#stop-mirrormaker-2)Stop MirrorMaker 2 To stop the MirrorMaker 2 process, use `top` to find its process ID, and then run: `kill ` ## [](#message-size)Message size When replicating larger message sizes with MirrorMaker 2 on the target cluster, you may get blocked with an error: org.apache.kafka.common.errors.RecordTooLargeException: The message is xxxx bytes when serialized which is larger than 1048576, which is the value of the max.request.size configuration. To address this issue, make sure that your `mm2.properties` configuration file on the target cluster allows bigger messages sizes. For example, for 30MB messages, you’d have the following line in the configuration file: ```bash .producer.max.request.size=31457280 ``` ## [](#running-mirrormaker-2-as-a-service)Running MirrorMaker 2 as a service For production usage Redpanda recommends that you run MirrorMaker 2 as a systemd unit file. To run MirrorMaker 2 as a systemd unit file: 1. Edit `/etc/systemd/system/multi-user.target.wants/mm2.service` and add the following: ```ini [Unit] Description=Mirror Maker 2 service After=network.target #StartLimitIntervalSec=0 [Service] Type=simple Restart=always LimitNOFILE=49152 RestartSec=1 User=root Environment=JAVA_HOME=/usr/lib/jvm/java-11-amazon-corretto ExecStart=/home/ec2-user/kafka_2.13-3.3.1/bin/connect-mirror-maker.sh /home/ec2-user/mm2.properties # Output to syslog StandardOutput=syslog StandardError=syslog SyslogIdentifier=mm2 [Install] WantedBy=multi-user.target ``` > 📝 **NOTE** > > The home directory and where you are running MirrorMaker2 from may vary. Note the Kafka folder location, as it may vary by version. 2. Run: ```bash sudo systemctl daemon-reload ``` 3. Run: ```bash sudo systemctl start mm2.service ``` You can follow the progress with the `tail` command: ### Fedora/RedHat ```bash tail -f /var/log/messages | grep mm2 ``` ### Debian/Ubuntu ```bash tail -f /var/log/syslog | grep mm2 ``` ## [](#troubleshooting)Troubleshooting If you run into any difficulty with data migration, you can request help in the Redpanda [Slack](https://redpanda.com/slack) community. ## Suggested labs - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) [Search all labs](/redpanda-labs) --- # Page 241: Migrate from the Redpanda Helm chart **URL**: https://docs.redpanda.com/current/migrate/kubernetes/helm-to-operator.md --- # Migrate from the Redpanda Helm chart --- title: Migrate from the Redpanda Helm chart latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/helm-to-operator page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/helm-to-operator.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/migrate/pages/kubernetes/helm-to-operator.adoc description: If you are using the Redpanda Helm chart, you can migrate to the Redpanda Operator and use it to manage your deployment. page-git-created-date: "2025-05-07" page-git-modified-date: "2026-03-24" support-status: supported --- If you are using the Redpanda Helm chart, you can migrate to the Redpanda Operator and use it to manage your Helm deployment. The Redpanda Operator extends Kubernetes with custom resource definitions (CRDs), which allow Redpanda clusters to be treated as native Kubernetes resources. The primary resource that the Redpanda Operator uses to represent a Redpanda cluster is the Redpanda resource. Here is an example of a Redpanda custom resource: ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: spec: clusterSpec: image: tag: ``` - `metadata.name`: Name to assign the Redpanda cluster. This name is also assigned to the Helm release. - `spec.clusterSpec.image.tag`: The version of Redpanda to deploy (for example, `v25.2.1`). Starting from operator v25.1.1, the operator bundles Helm charts internally and automatically selects the appropriate chart version. - [`spec.clusterSpec`](../../../reference/k-crd/#redpandaclusterspec): This is where you can configure the Redpanda CRD with your values overrides from the Redpanda Helm chart. ## [](#supported-migration-paths)Supported migration paths The following table summarizes which Helm chart versions you can migrate from and which Redpanda Operator versions to install. | Helm Chart Version | Operator Version | Notes | | --- | --- | --- | | <5.9.x | - | You must first helm upgrade your Redpanda cluster to at least version 5.9.x before installing the Redpanda Operator. Migrating directly from 5.8.x or below is not supported. | | 5.9.x or 5.10.x | v2.4.x | After installing or upgrading to Helm chart 5.9.x or 5.10.x, you can install the Redpanda Operator v2.4.x. | ## [](#prerequisites)Prerequisites Before migrating to the Redpanda Operator, you must have: - The name of your existing Helm release and the latest version of the Redpanda Helm chart that you have deployed. ```bash helm list -A ``` In this example the chart version is 5.9.1 and the release name is `redpanda`. NAME CHART redpanda redpanda-5.9.1 Make a note of your name and version for the next steps. You’ll need to configure your Redpanda custom resource with these details. - Your values overrides. ```bash helm get values --namespace ``` You should see your overrides in YAML format. You’ll need to configure your Redpanda custom resource with these details. > 💡 **TIP** > > Before implementing any changes in your production environment, Redpanda Data recommends testing the migration in a non-production environment. ## [](#rolling-restart-during-migration)Rolling restart during migration When you apply the Redpanda custom resource, the operator triggers a rolling restart of all broker pods. The rolling restart is unavoidable during migration, regardless of how closely your `clusterSpec` values match the existing Helm values. ### [](#how-the-rolling-restart-works)How the rolling restart works The migration triggers the following sequence: 1. **Resource adoption**: The operator uses server-side apply to take ownership of the existing Helm-managed StatefulSet. It patches the StatefulSet with new labels (generation, config version, and ownership) and sets the Redpanda custom resource as the owner reference. 2. **StatefulSet spec update**: The operator re-renders the StatefulSet from its own templates. Any difference, even metadata or label changes, creates a new `ControllerRevision`. 3. **Pod rolling**: The operator compares each pod’s `StatefulSetRevisionLabel` against the latest `ControllerRevision`. Because the existing pods were created under the old Helm-managed revision, the operator flags every pod for rolling. 4. **One-at-a-time deletion**: The operator deletes pods one at a time: - Checks cluster health through the admin API. - Deletes the pod if the cluster is healthy, then requeues after 10 seconds. - Waits for the cluster to stabilize before rolling the next pod. - Skips deletion and requeues if the cluster is unhealthy. ### [](#impact-by-cluster-configuration)Impact by cluster configuration | Scenario | Impact | | --- | --- | | 3+ brokers, replication factor (RF) ≥ 3 | No data loss and no downtime for consumers or producers configured with acks=all. Individual broker restarts cause brief partition leader elections, typically a few seconds each. Redpanda uses Raft consensus, so writes require a majority quorum. With RF=3 and one broker restarting, the remaining two brokers maintain quorum and writes continue. | | 3 brokers, RF = 1 | Partitions on the restarting broker are unavailable for the duration of that broker’s restart. | | Single broker | Full outage for the duration of the restart. | ### [](#recommended-producer-settings)Recommended producer settings To avoid message loss during the rolling restart, configure producers with the following settings: - `acks=all` (or `-1`): Ensures the Raft quorum (majority of replicas) commits the write before acknowledging it. - `retries`: Handles `NOT_LEADER_FOR_PARTITION` errors during leader elections. Set this to a high value. - `enable.idempotence=true`: Prevents duplicate messages from retries. ## [](#migrate-to-the-redpanda-operator-and-helm)Migrate to the Redpanda Operator and Helm To migrate to the latest Redpanda Operator and use it to manage your Helm deployment, follow these steps. 1. Make sure that you have permission to install custom resource definitions (CRDs): ```bash kubectl auth can-i create CustomResourceDefinition --all-namespaces ``` You should see `yes` in the output. You need these cluster-level permissions to install the Redpanda Operator CRDs in the next steps. 2. Install the Redpanda Operator. Starting in v25.2, the Redpanda Operator can manage Redpanda clusters in any namespace: 1. To deploy in cluster scope, use: ```bash helm repo add redpanda https://charts.redpanda.com helm repo update helm upgrade --install redpanda-controller redpanda/operator \ --namespace \ --create-namespace \ --version v26.1.2 \ (1) --set crds.enabled=true (2) ``` | 1 | This flag specifies the exact version of the Redpanda Operator Helm chart to use for deployment. By setting this value, you pin the chart to a specific version, which prevents automatic updates that might introduce breaking changes or new features that have not been tested in your environment. | | --- | --- | | 2 | This flag ensures that the CRDs are installed as part of the Redpanda Operator deployment.This command deploys the Redpanda Operator in cluster scope (default in v25.2+), allowing it to manage Redpanda clusters across multiple namespaces. | 2. To deploy in namespace scope (managing only resources within its deployment namespace), use: ```bash helm upgrade --install redpanda-controller redpanda/operator \ --namespace \ --create-namespace \ --version v26.1.2 \ --set crds.enabled=true \ --set 'additionalCmdFlags=["--namespace="]' (1) ``` | 1 | This flag restricts the Redpanda Operator to manage resources only within the specified namespace. | | --- | --- | 3. Ensure that the Deployment is successfully rolled out: ```bash kubectl --namespace rollout status -w deployment/redpanda-controller-operator ``` deployment "redpanda-controller" successfully rolled out 4. Configure a Redpanda custom resource that Redpanda Operator will use to adopt your Redpanda cluster. Replace the placeholders with the values identified in the [Prerequisites](#prerequisites). `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: annotations: cluster.redpanda.com/managed: "true" creationTimestamp: null name: (1) spec: clusterSpec: image: tag: (2) (3) ``` > 📝 **NOTE** > > - Starting from operator v25.1.1, the `chartRef` fields (including `chartRef.chartVersion`) are deprecated. The operator bundles Helm charts internally. > > - If your existing Helm deployment is on an older version, verify compatibility in [Kubernetes Compatibility](../../../upgrade/k-compatibility/) before migrating. 5. Adopt the Redpanda cluster by creating an instance of the Redpanda custom resource: ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` 6. Wait for the Redpanda resource to successfully reach a `deployed` state: ```bash kubectl get redpanda --namespace --watch ``` Example output: NAME READY STATUS redpanda True Redpanda reconciliation succeeded ## [](#roll-back-from-redpanda-operator-to-helm)Roll back from Redpanda Operator to Helm If you migrated to the Redpanda Operator and want to revert to using only Helm, follow these steps to uninstall the Redpanda Operator: Follow the steps in **exact order** to avoid race conditions between the Redpanda Operator’s reconciliation loop and Kubernetes garbage collection. 1. Delete all Redpanda-related custom resources: ```bash kubectl delete users --namespace --all kubectl delete topics --namespace --all kubectl delete schemas --namespace --all kubectl delete redpanda --namespace --all ``` 2. Make sure requests for those resources return no results. For example, if you had a Redpanda cluster named `redpanda` in the namespace ``, run: ```bash kubectl get redpanda --namespace ``` 3. Uninstall the Redpanda Operator Helm release: ```bash helm uninstall redpanda-controller --namespace ``` Helm does not uninstall CRDs by default when using `helm uninstall` to avoid accidentally deleting existing custom resources. 4. Remove the CRDs. 1. List all Redpanda CRDs installed by the operator: ```bash kubectl api-resources --api-group='cluster.redpanda.com' ``` This command displays all CRDs defined by the Redpanda Operator. For example: ```bash NAME SHORTNAMES APIVERSION NAMESPACED KIND redpandas rp cluster.redpanda.com/v1alpha2 true Redpanda schemas sc cluster.redpanda.com/v1alpha2 true Schema topics cluster.redpanda.com/v1alpha2 true Topic users rpu cluster.redpanda.com/v1alpha2 true User ``` 2. Delete the CRDs: ```bash kubectl get crds -o name | grep cluster.redpanda.com | xargs kubectl delete ``` This command lists all CRDs with the `cluster.redpanda.com` domain suffix and deletes them, ensuring only Redpanda CRDs are removed. Helm does not delete CRDs automatically to prevent data loss, so you must run this step manually. 5. (Optional) Delete any leftover PVCs or Secrets in the namespace: > ⚠️ **CAUTION** > > The following command deletes all PVCs and Secrets in the namespace, which may remove unrelated resources if the namespace is shared with other applications. ```bash kubectl delete pvc,secret --all --namespace ``` After completing these steps, the Redpanda Operator is no longer managing your Helm deployment. ## [](#troubleshooting)Troubleshooting While the deployment process can sometimes take a few minutes, a prolonged 'not ready' status may indicate an issue. ### [](#helm-v3-18-0-is-not-supported-json-number-error)Helm v3.18.0 is not supported (json.Number error) If you are using Helm v3.18.0, you may encounter errors such as: Error: INSTALLATION FAILED: execution error at (redpanda/templates/entry-point.yaml:17:4): invalid Quantity expected string or float64 got: json.Number (1) This is due to a bug in Helm v3.18.0. To avoid similar errors, upgrade to a later version. For more details, see the [Helm GitHub issue](https://github.com/helm/helm/issues/30880). === StatefulSet never rolls out If the StatefulSet Pods remain in a pending state, they are waiting for resources to become available. To identify the Pods that are pending, use the following command: ```bash kubectl get pod --namespace ``` The response includes a list of Pods in the StatefulSet and their status. To view logs for a specific Pod, use the following command. ```bash kubectl logs -f --namespace ``` You can use the output to debug your deployment. ### [](#didnt-match-pod-anti-affinity-rules)Didn’t match pod anti-affinity rules If you see this error, your cluster does not have enough nodes to satisfy the anti-affinity rules: Warning FailedScheduling 18m default-scheduler 0/1 nodes are available: 1 node(s) didn't match pod anti-affinity rules. preemption: 0/1 nodes are available: 1 No preemption victims found for incoming pod. The Helm chart configures default `podAntiAffinity` rules to make sure that only one Pod running a Redpanda broker is scheduled on each worker node. To learn why, see [Number of workers](../../../deploy/redpanda/kubernetes/k-requirements/#number-of-workers). To resolve this issue, do one of the following: - Create additional worker nodes. - Modify the anti-affinity rules (for development purposes only). If adding nodes is not an option, you can modify the `podAntiAffinity` rules in your StatefulSet to be less strict. #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: statefulset: podAntiAffinity: type: soft ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `docker-repo.yaml` ```yaml statefulset: podAntiAffinity: type: soft ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values docker-repo.yaml ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set statefulset.podAntiAffinity.type=soft ``` ### [](#unable-to-mount-volume)Unable to mount volume If you see volume mounting errors in the Pod events or in the Redpanda logs, ensure that each of your Pods has a volume available in which to store data. - If you’re using StorageClasses with dynamic provisioners (default), ensure they exist: ```bash kubectl get storageclass ``` - If you’re using PersistentVolumes, ensure that you have one PersistentVolume available for each Redpanda broker, and that each one has the storage capacity that’s set in `storage.persistentVolume.size`: ```bash kubectl get persistentvolume --namespace ``` To learn how to configure different storage volumes, see [Configure Storage](../../../manage/kubernetes/storage/k-configure-storage/). ### [](#failed-to-pull-image)Failed to pull image When deploying the Redpanda Helm chart, you may encounter Docker rate limit issues because the default registry URL is not recognized as a Docker Hub URL. The domain `docker.redpanda.com` is used for statistical purposes, such as tracking the number of downloads. It mirrors Docker Hub’s content while providing specific analytics for Redpanda. Failed to pull image "docker.redpanda.com/redpandadata/redpanda:v": rpc error: code = Unknown desc = failed to pull and unpack image "docker.redpanda.com/redpandadata/redpanda:v": failed to copy: httpReadSeeker: failed open: unexpected status code 429 Too Many Requests - Server message: toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit To fix this error, do one of the following: - Replace the `image.repository` value in the Helm chart with `docker.io/redpandadata/redpanda`. Switching to Docker Hub avoids the rate limit issues associated with `docker.redpanda.com`. #### Operator `redpanda-cluster.yaml` ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: image: repository: docker.io/redpandadata/redpanda ``` ```bash kubectl apply -f redpanda-cluster.yaml --namespace ``` #### Helm ##### --values `docker-repo.yaml` ```yaml image: repository: docker.io/redpandadata/redpanda ``` ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --values docker-repo.yaml ``` ##### --set ```bash helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ --set image.repository=docker.io/redpandadata/redpanda ``` - Authenticate to Docker Hub by logging in with your Docker Hub credentials. The `docker.redpanda.com` site acts as a reflector for Docker Hub. As a result, when you log in with your Docker Hub credentials, you will bypass the rate limit issues. ### [](#dig-not-defined)Dig not defined This error means that you are using an unsupported version of [Helm](https://helm.sh/docs/intro/install/): Error: parse error at (redpanda/templates/statefulset.yaml:203): function "dig" not defined To fix this error, ensure that you are using the minimum required version: 3.10.0. ```bash helm version ``` ### [](#repository-name-already-exists)Repository name already exists If you see this error, remove the `redpanda` chart repository, then try installing it again. ```bash helm repo remove redpanda helm repo add redpanda https://charts.redpanda.com helm repo update ``` ### [](#fatal-error-during-checker-data-directory-is-writable-execution)Fatal error during checker "Data directory is writable" execution This error appears when Redpanda does not have write access to your configured storage volume under `storage` in the Helm chart. Error: fatal error during checker "Data directory is writable" execution: open /var/lib/redpanda/data/test\_file: permission denied To fix this error, set `statefulset.initContainers.setDataDirOwnership.enabled` to `true` so that the initContainer can set the correct permissions on the data directories. ### [](#cannot-patch-redpanda-with-kind-statefulset)Cannot patch "redpanda" with kind StatefulSet This error appears when you run `helm upgrade` with the `--values` flag but do not include all your previous overrides. Error: UPGRADE FAILED: cannot patch "redpanda" with kind StatefulSet: StatefulSet.apps "redpanda" is invalid: spec: Forbidden: updates to statefulset spec for fields other than 'replicas', 'template', 'updateStrategy', 'persistentVolumeClaimRetentionPolicy' and 'minReadySeconds' are forbidden To fix this error, include all the value overrides from the previous installation using either the `--set` or the `--values` flags. > ⚠️ **WARNING** > > Do not use the `--reuse-values` flag to upgrade from one version of the Helm chart to another. This flag stops Helm from using any new values in the upgraded chart. ### [](#cannot-patch-redpanda-console-with-kind-deployment)Cannot patch "redpanda-console" with kind Deployment This error appears if you try to upgrade your deployment and you already have `console.enabled` set to `true`. Error: UPGRADE FAILED: cannot patch "redpanda-console" with kind Deployment: Deployment.apps "redpanda-console" is invalid: spec.selector: Invalid value: v1.LabelSelector{MatchLabels:map\[string\]string{"app.kubernetes.io/instance":"redpanda", "app.kubernetes.io/name":"console"}, MatchExpressions:\[\]v1.LabelSelectorRequirement(nil)}: field is immutable To fix this error, set `console.enabled` to `false` so that Helm doesn’t try to deploy Redpanda Console again. ### [](#helm-is-in-a-pending-rollback-state)Helm is in a pending-rollback state An interrupted Helm upgrade process can leave your Helm release in a `pending-rollback` state. This state prevents further actions like upgrades, rollbacks, or deletions through standard Helm commands. To fix this: 1. Identify the Helm release that’s in a `pending-rollback` state: ```bash helm list --namespace --all ``` Look for releases with a status of `pending-rollback`. These are the ones that need intervention. 2. Verify the Secret’s status to avoid affecting the wrong resource: ```bash kubectl --namespace get secret --show-labels ``` Identify the Secret associated with your Helm release by its `pending-rollback` status in the labels. > ⚠️ **WARNING** > > Ensure you have correctly identified the Secret to avoid unintended consequences. Deleting the wrong Secret could impact other deployments or services. 3. Delete the Secret to clear the `pending-rollback` state: ```bash kubectl --namespace delete secret -l status=pending-rollback ``` After clearing the `pending-rollback` state: - **Retry the upgrade**: Restart the upgrade process. You should investigate the initial failure to avoid getting into the `pending-rollback` state again. - **Perform a rollback**: If you need to roll back to a previous release, use `helm rollback ` to revert to a specific, stable release version. ### [](#crash-loop-backoffs)Crash loop backoffs If a broker crashes after startup, or gets stuck in a crash loop, it can accumulate an increasing amount of stored state. This accumulated state not only consumes additional disk space but also prolongs the time required for each subsequent restart to process it. To prevent infinite crash loops, the Redpanda Helm chart sets the [`crash_loop_limit`](../../../reference/properties/broker-properties/#crash_loop_limit) broker configuration property to `5`. The crash loop limit is the number of consecutive crashes that can happen within one hour of each other. By default, the broker terminates immediately after hitting the `crash_loop_limit`. The Pod running Redpanda remains in a `CrashLoopBackoff` state until its internal consecutive crash counter is reset to zero. To facilitate debugging in environments where a broker is stuck in a crash loop, you can also set the [`crash_loop_sleep_sec`](../../../reference/properties/broker-properties/#crash_loop_sleep_sec) broker configuration property. This setting determines how long the broker sleeps before terminating the process after reaching the crash loop limit. By providing a window during which the Pod remains available, you can SSH into it and troubleshoot the issue. Example configuration: ```yaml config: node: crash_loop_limit: 5 crash_loop_sleep_sec: 60 ``` In this example, when the broker hits the `crash_loop_limit` of 5, it will sleep for 60 seconds before terminating the process. This delay allows administrators to access the Pod and troubleshoot. To troubleshoot a crash loop backoff: 1. Check the Redpanda logs from the most recent crashes: ```bash kubectl logs --namespace ``` > 📝 **NOTE** > > Kubernetes retains logs only for the current and the previous instance of a container. This limitation makes it difficult to access logs from earlier crashes, which may contain vital clues about the root cause of the issue. Given these log retention limitations, setting up a centralized logging system is crucial. Systems such as [Loki](https://grafana.com/docs/loki/latest/) or [Datadog](https://www.datadoghq.com/product/log-management/) can capture and store logs from all containers, ensuring you have access to historical data. 2. Resolve the issue that led to the crash loop backoff. 3. Reset the crash counter to zero to allow Redpanda to restart. You can do any of the following to reset the counter: - Make changes to any of the following sections in the Redpanda Helm chart to trigger an update: - `config.node` - `config.tunable` For example: ```yaml config: node: crash_loop_limit: ``` - Delete the `startup_log` file in the broker’s data directory. ```bash kubectl exec --namespace -- rm /var/lib/redpanda/data/startup_log ``` > 📝 **NOTE** > > It might be challenging to execute this command within a Pod that is in a `CrashLoopBackoff` state due to the limited time during which the Pod is available before it restarts. Wrapping the command in a loop might work. - Wait one hour since the last crash. The crash counter resets after one hour. To avoid future crash loop backoffs and manage the accumulation of small segments effectively: - [Monitor](../../../manage/kubernetes/monitoring/k-monitor-redpanda/) the size and number of segments regularly. - Optimize your Redpanda configuration for segment management. - Consider implementing [Tiered Storage](../../../manage/kubernetes/tiered-storage/k-tiered-storage/) to manage data more efficiently. ### [](#a-redpanda-enterprise-edition-license-is-required)A Redpanda Enterprise Edition license is required During a Redpanda upgrade, if enterprise features are enabled and a valid Enterprise Edition license is missing, Redpanda logs a warning and aborts the upgrade process on the first broker. This issue prevents a successful upgrade. A Redpanda Enterprise Edition license is required to use the currently enabled features. To apply your license, downgrade this broker to the pre-upgrade version and provide a valid license key via rpk using 'rpk cluster license set ', or via Redpanda Console. To request an enterprise license, please visit . To try Redpanda Enterprise for 30 days, visit . For more information, see . If you encounter this message, follow these steps to recover: 1. [Roll back the affected broker to the original version](../../../upgrade/k-rolling-upgrade/#roll-back). 2. Do one of the following: - [Apply a valid Redpanda Enterprise Edition license](../../../get-started/licensing/add-license-redpanda/) to the cluster. - Disable enterprise features. If you do not have a valid license and want to proceed without using enterprise features, you can disable the enterprise features in your Redpanda configuration. 3. Retry the upgrade. For more troubleshooting steps, see [Troubleshoot Redpanda in Kubernetes](../../../troubleshoot/errors-solutions/k-resolve-errors/). ### [](#open-an-issue)Open an issue If you cannot solve the issue or need assistance during the migration process, [open a GitHub issue](https://github.com/redpanda-data/redpanda-operator/issues/new/choose). Before opening a new issue, search the existing issues on GitHub to see if someone has already reported a similar problem or if any relevant discussions can help you. ## [](#next-steps)Next steps For information about the latest Redpanda Operator and the new Redpanda custom resource, see [Redpanda in Kubernetes](../../../deploy/redpanda/kubernetes/k-deployment-overview/). ## Suggested labs - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) [Search all labs](/redpanda-labs) --- # Page 242: Migrate from Strimzi to Redpanda Operator **URL**: https://docs.redpanda.com/current/migrate/kubernetes/strimzi.md --- # Migrate from Strimzi to Redpanda Operator --- title: Migrate from Strimzi to Redpanda Operator latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: kubernetes/strimzi page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: kubernetes/strimzi.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/migrate/pages/kubernetes/strimzi.adoc description: This guide explores the migration from Strimzi to Redpanda Operator, highlighting key differences, deployment strategies, and how to leverage Kubernetes for managing Kafka clusters effectively. page-git-created-date: "2025-05-07" page-git-modified-date: "2025-08-29" support-status: supported --- In this guide, you’ll explore the key differences between Strimzi and Redpanda Operator, and you’ll find examples for migrating Strimzi custom resources to Redpanda. The information in this guide is based on version [0.40.0](https://github.com/strimzi/strimzi-kafka-operator/releases/tag/0.40.0) of the Strimzi Operator. ## [](#why-redpanda)Why Redpanda? Redpanda is a Kafka-compatible event streaming platform that aims to simplify data streaming by eliminating external dependencies like ZooKeeper and offering a leaner architecture. See [When to choose Redpanda instead of Apache Kafka](https://redpanda.com/blog/when-to-choose-redpanda-vs-kafka). ## [](#about-strimzi-and-redpanda-operator-in-kubernetes)About Strimzi and Redpanda Operator in Kubernetes Both Strimzi and the Redpanda Operator harness the power of Kubernetes to provide tools for creating and managing Kafka clusters in Kubernetes environments: - Strimzi is an open-source project that simplifies the deployment and management of _Apache Kafka_ clusters on Kubernetes. - [The Redpanda Operator](../../../deploy/redpanda/kubernetes/k-deployment-overview/) simplifies the deployment and management of _Redpanda_ clusters on Kubernetes using custom resource definitions (CRDs). ## [](#notable-differences)Notable differences These are some notable differences between features and functionality in Strimzi and Redpanda in Kubernetes. ### [](#security)Security The Redpanda CRD, which defines Redpanda clusters, emphasizes security out of the box, with the following defaults: - TLS enabled for the Kafka API, HTTP Proxy, and inter-broker communication (RPC). - Certificate management through [cert-manager](https://cert-manager.io/docs/) by default. > 📝 **NOTE** > > Both [Strimzi](https://github.com/strimzi/strimzi-kafka-operator/issues/3088) and the Redpanda Operator currently do not support Kerberos for Kafka. See [Security for Redpanda in Kubernetes](../../../manage/kubernetes/security/). ### [](#storage)Storage Redpanda performs best with direct-attached storage (NVMe) to ensure high performance. To minimize latency, use of Kubernetes local PersistentVolumes. See [Kubernetes Cluster Requirements and Recommendations](../../../deploy/redpanda/kubernetes/k-requirements/). ### [](#jvm)JVM Redpanda does not require a JVM because it is written in C++. ### [](#zookeeper)Zookeeper Redpanda does not require ZooKeeper. Instead, Redpanda brokers run the [Raft](https://raft.github.io/) consensus algorithm for cluster coordination. ### [](#cruise-control)Cruise control Redpanda manages partition distribution and load balancing, eliminating the need for external tools like cruise control. See [Cluster Balancing](../../../manage/cluster-maintenance/cluster-balancing/). ### [](#networking)Networking The Redpanda CRD has built-in support for the following networking options: - **NodePort** for direct access to services from outside the cluster using ports on each node. - **Load Balancer** for distributing external traffic to the cluster nodes, typically managed by cloud providers. > 📝 **NOTE** > > Ingress and route configurations are not available in the Redpanda CRD. To use these Services, you can disable the default NodePort Service and deploy your own custom Service. See [Networking and Connectivity in Kubernetes](../../../manage/kubernetes/networking/). ### [](#observability)Observability Redpanda exposes metrics to an HTTP endpoint by default, facilitating straightforward integration with monitoring tools such as Prometheus. > 📝 **NOTE** > > Strimzi includes built-in support for [distributed tracing with OpenTelemetry](https://strimzi.io/docs/operators/latest/overview#metrics-overview-tracing_str). However, the Redpanda Helm chart lacks support for distributed tracing. See [Monitor Redpanda in Kubernetes](../../../manage/kubernetes/monitoring/k-monitor-redpanda/) and [Public Metrics](../../../reference/public-metrics-reference/). ### [](#custom-resources)Custom resources The deployment of Kafka components onto a Kubernetes cluster using both Strimzi and Redpanda Operator is configurable through custom resources. These resources are instances of APIs introduced by custom resource definitions (CRDs), which extend Kubernetes resources. CRDs act as configuration instructions to describe the custom resources in a Kubernetes cluster. CRDs also allow resources to benefit from native Kubernetes features like CLI accessibility and configuration validation. Both Strimzi and the Redpanda Operator offer CRDs for creating and managing components as Kubernetes resources. Some custom resources in Strimzi do not have an equivalent custom resource in Redpanda. | Strimzi custom resource | Redpanda equivalent | | --- | --- | | Kafka | Redpanda custom resource | | KafkaBridge | Built-in HTTP proxy | | KafkaConnect | Available as a Helm chart | | KafkaMirrorMaker2 | Included in the Connectors Helm chart | | KafkaNodePool | No support for heterogeneous brokers | | KafkaTopic | Topic custom resource | | KafkaUser | Users are managed through cluster configuration | ## [](#migrate-to-redpanda-operator)Migrate to Redpanda Operator To ensure a smooth migration: - [Plan data and topic migration](#plan-data-and-topic-migration). - [Migrate Strimzi resources to Redpanda](#migrate-strimzi-resources-to-redpanda). - [Adjust monitoring and alerting](#adjust-monitoring-and-alerting). - [Engage with the Redpanda community](#engage-with-the-redpanda-community). ### [](#plan-data-and-topic-migration)Plan data and topic migration When migrating from Strimzi to Redpanda Operator, plan your data and topic migration to ensure data integrity and minimal downtime: - **Back up data**: Before starting the migration, ensure that all data in Kafka topics is backed up. - **Migrate topics**: Review the configuration of your existing Kafka topics, including partition count, replication factor, and any custom configurations like retention policies. This information is essential for migrating these topics to Redpanda. See [Migrate the KafkaTopic resource](#migrate-kafkatopic). - **Transfer data**: Determine the most suitable method for data transfer. For example, you can use MirrorMaker2 to replicate data from Kafka to Redpanda in real-time. This method is useful if you need to keep the source system online during the migration. See [Migrate the KafkaMirrorMaker2 resource](#migrate-kafkamirrormaker). - **Connect clients**: Connect client applications to Redpanda. ### [](#migrate-strimzi-resources-to-redpanda)Migrate Strimzi resources to Redpanda Migrating from Strimzi to Redpanda involves converting Strimzi custom resources into their corresponding forms for the Redpanda Operator. This process ensures that your Kafka configurations and setups are correctly translated and optimized for Redpanda. These example Strimzi manifests are for version [0.40.0](https://github.com/strimzi/strimzi-kafka-operator/releases/tag/0.40.0) of the Strimzi Operator. #### [](#migrate-kafka)Migrate the Kafka resource This section provides an example of how to translate configuration from a Strimzi Kafka resource to a Redpanda resource. Strimzi ```yaml apiVersion: kafka.strimzi.io/v1beta2 kind: Kafka metadata: name: my-cluster spec: kafka: version: 3.7.0 (1) replicas: 1 (2) listeners: (3) - name: plain port: 9093 type: internal tls: false - name: tls port: 9094 type: internal tls: true config: (4) default.replication.factor: 1 storage: (5) type: ephemeral rack: (6) topologyKey: topology.kubernetes.io/zone config: replica.selector.class: org.apache.kafka.common.replica.RackAwareReplicaSelector zookeeper: (7) replicas: 3 storage: type: ephemeral entityOperator: (8) topicOperator: {} userOperator: {} ``` Redpanda ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Redpanda metadata: name: redpanda spec: chartRef: {} clusterSpec: image: tag: v23.3.11 (1) statefulset: replicas: 1 (2) listeners: (3) kafka: port: 9093 authenticationMethod: tls: enabled: false config: (4) cluster: default_topic_replications: 1 storage: (5) hostPath: "" persistentVolume: enabled: false rackAwareness: (6) enabled: true nodeAnnotation: 'topology.kubernetes.io/zone' serviceAccount: create: true rbac: enabled: true ``` | 1 | Versioning: Strimzi refers to Kafka versions, while Redpanda uses its own versioning scheme. | | --- | --- | | 2 | Replicas: Configures the number of cluster replicas to 1 in both resources, directly translating the desired number of broker nodes from Strimzi to Redpanda. | | 3 | Listeners: Strimzi allows defining multiple internal Kafka listeners, whereas Redpanda allows for only one internal listener with a singular port definition. | | 4 | Configuration: Strimzi’s default.replication.factor setting translates to default_topic_replications in Redpanda, aligning Kafka cluster configurations between the two. | | 5 | Storage: Both platforms support ephemeral storage for non-persistent environments, typically used for testing or development. See Storage for Redpanda in Kubernetes. | | 6 | Rack awareness: Both platforms support high availability and fault tolerance by spreading replicas across different physical locations. Strimzi uses topologyKey, and Redpanda uses rackAwareness with nodeAnnotation. See Enable Rack Awareness in Kubernetes. | | 7 | ZooKeeper: Necessary for cluster management in Strimzi but not used in Redpanda, which employs the Raft consensus algorithm for managing cluster state. | | 8 | Entity Operator: Manages Kafka topics and users through separate operators in Strimzi. Redpanda handles topic management through the Topic custom resource but does not support user management in CRDs. | #### [](#migrate-kafkatopic)Migrate the KafkaTopic resource In Strimzi, a single KafkaTopic resource is used to manage a single topic in a single Kafka cluster. In the following example, the resource has a label `strimzi.io/cluster` with the name of the target Kafka cluster. The Strimzi Operator communicates with this cluster and ensures that the specified topic is created or updated according to the desired configuration. In Redpanda, the Topic resource is also used to manage a single topic in a single Redpanda cluster. Like the [Strimzi Topic Operator](https://strimzi.io/docs/operators/latest/overview#overview-concepts-topic-operator-str), the Redpanda Topic Controller is unidirectional. The controller reconciles topic changes in only one direction: from Kubernetes to Redpanda. For more details, see [Manage Topics with the Redpanda Operator](../../../manage/kubernetes/k-manage-topics/). > 📝 **NOTE** > > Previous versions of the Strimzi Topic Operator supported bidirectional topic management. Redpanda Operator does not support bidirectional topic management. Strimzi ```yaml apiVersion: kafka.strimzi.io/v1beta2 kind: KafkaTopic metadata: name: my-topic (1) labels: strimzi.io/cluster: my-kafka-cluster (2) spec: partitions: 3 (3) replicas: 3 (4) ``` Redpanda ```yaml apiVersion: cluster.redpanda.com/v1alpha2 kind: Topic metadata: name: my-topic (1) spec: kafkaApiSpec: (2) brokers: - "redpanda-0.redpanda..svc.cluster.local:9093" - "redpanda-1.redpanda..svc.cluster.local:9093" - "redpanda-2.redpanda..svc.cluster.local:9093" tls: caCertSecretRef: name: "redpanda-default-cert" key: "ca.crt" partitions: 3 (3) replicationFactor: 3 (4) ``` | 1 | Topic name: Both configurations identify the Kafka topic by the same name, ensuring consistency across migration. | | --- | --- | | 2 | Cluster reference: Strimzi uses labels to link the topic to the specific Kafka cluster, whereas Redpanda uses a kafkaApiSpec block, explicitly defining the brokers and security settings. | | 3 | Partitions: Both platforms maintain the same number of partitions for the topic, facilitating a direct translation of partition configuration. | | 4 | Replicas: The number of replicas is set to 3 in both cases, ensuring high availability and data redundancy during and after migration. | ### [](#migrate-kafkauser)Migrate the KafkaUser resource The Redpanda Operator does not support a custom resource for Kafka users. For details on user authentication in Redpanda, see [Configure Authentication for Redpanda in Kubernetes](../../../manage/kubernetes/security/authentication/k-authentication/). #### [](#migrate-kafkaconnect)Migrate the KafkaConnect resource The Redpanda Operator does not support a custom resource to define Kafka Connect deployments. Redpanda provides support for Kafka Connect through a separate [Helm chart](../../../deploy/kafka-connect/k-deploy-kafka-connect/). > 💡 **TIP** > > You can use the [Redpanda Connect Helm chart](../../../../redpanda-connect/get-started/quickstarts/helm-chart/), which comes with hundreds of prebuilt connectors, change data capture (CDC) capabilities, and YAML-configurable workflows. #### [](#migrate-kafkabridge)Migrate the KafkaBridge resource Redpanda includes a built-in HTTP proxy on each broker, enabling direct HTTP-based interactions without the need for a separate bridge component. For details, see [Use Redpanda with the HTTP Proxy API](../../../develop/http-proxy/). For the complete API reference, see [HTTP Proxy API reference](/api/doc/http-proxy/). #### [](#migrate-kafkamirrormaker)Migrate the KafkaMirrorMaker2 resource The Redpanda Operator does not support a custom resource for MirrorMaker2. Redpanda offers a separate [Helm chart](https://github.com/redpanda-data/helm-charts/tree/main/charts/connectors) that includes Kafka Connect and MirrorMaker2. #### [](#migrate-kafkanodepool)Migrate the KafkaNodePool resource The Redpanda Operator does not have an equivalent for KafkaNodePool resources in Strimzi. The Redpanda Helm chart allows you to deploy only homogenous broker configuration in a single Redpanda cluster, unlike the heterogeneous configurations available in KafkaNodePools. Brokers in Redpanda are uniformly configured according to the specifications in [`RedpandaClusterSpec`](../../../reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaclusterspec). Given this difference, you must adapt your Kafka setup to a unified broker configuration model by standardizing the broker settings that were previously varied across different KafkaNodePool resources. ### [](#adjust-monitoring-and-alerting)Adjust monitoring and alerting Adjust your monitoring and alerting setup to ensure visibility into the Redpanda environment and maintain operational stability. - **Configure monitoring tools**: If you use tools like Prometheus for monitoring, reconfigure them to scrape metrics from Redpanda. Redpanda exposes metrics at an HTTP endpoint, which might require changes to your Prometheus scraping configurations. See [Monitor Redpanda in Kubernetes](../../../manage/kubernetes/monitoring/k-monitor-redpanda/) and [Public Metrics](../../../reference/public-metrics-reference/). - **Update dashboards**: Update or recreate Grafana dashboards to reflect the metrics provided by Redpanda. This might involve adjusting metric names and labels to align with those emitted by Redpanda. See [Generate Grafana dashboard](../../../manage/kubernetes/monitoring/k-monitor-redpanda/#generate-grafana-dashboard). - **Set up new alerts**: Review and revise alerting rules to ensure they are relevant for the Redpanda environment. This includes setting thresholds that are appropriate for the performance and behavior of Redpanda as compared to Kafka. - **Monitor logs**: Integrate Redpanda with your log management solutions. Ensure that logs emitted by Redpanda are collected, stored, and indexed effectively, allowing for easy querying and monitoring. ### [](#engage-with-the-redpanda-community)Engage with the Redpanda community Leverage the [Redpanda community Slack](https://redpanda.com/slack) for support during and after your migration. The community can offer insights, best practices, and assistance in optimizing your streaming platform. ## [](#next-steps)Next steps See the following resources: - [Redpanda in Kubernetes](../../../deploy/redpanda/kubernetes/k-deployment-overview/). - [Deploy Redpanda for Production in Kubernetes](../../../deploy/redpanda/kubernetes/k-production-deployment/). ## Suggested labs - [Migrate Data with Redpanda Migrator](/redpanda-labs/docker-compose/redpanda-migrator/) [Search all labs](/redpanda-labs) --- # Page 243: Reference **URL**: https://docs.redpanda.com/current/reference.md --- # Reference --- title: Reference latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/index.adoc description: Reference index page. page-git-created-date: "2023-05-05" page-git-modified-date: "2023-08-18" support-status: supported --- The following topics provide reference details about Redpanda commands and configuration properties, as well historical content: - [Properties](properties/) Learn about the Redpanda properties you can configure. - [Release Notes](releases/) This page provides a centralized index of release notes for Redpanda products. Use release notes to understand the enhancements, fixes, and important changes in each version of our products. - [API Reference](api-reference/) See the Schema Registry API, the HTTP Proxy API, and the Admin API. - [Data Transforms SDKs](data-transforms/sdks/) This page provides a link to all SDK reference docs for data transforms. - [Kubernetes Reference](k-index/) Reference topics for Redpanda in Kubernetes. - [Monitoring Metrics](monitor-metrics/) Reference of monitoring metrics provided by Redpanda. - [rpk Commands](rpk/) Index page of `rpk` commands in alphabetical order. - [Glossary](glossary/) --- # Page 244: API Reference **URL**: https://docs.redpanda.com/current/reference/api-reference.md --- # API Reference --- title: API Reference latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: api-reference page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: api-reference.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/api-reference.adoc description: See the Schema Registry API, the HTTP Proxy API, and the Admin API. page-git-created-date: "2023-05-17" page-git-modified-date: "2025-11-19" support-status: supported --- Use Redpanda’s API reference documentation to learn about and interact with API endpoints: - [Schema Registry API Reference](/api/doc/schema-registry/) Manage schemas within a Redpanda cluster. See also: [Schema Registry documentation](../../manage/schema-reg/). - [HTTP Proxy API Reference](/api/doc/http-proxy/) HTTP Proxy is an HTTP server that exposes operations you can perform directly on a Redpanda cluster. Use the Redpanda HTTP Proxy API to perform a subset of actions that are also available through the Kafka API, but using simpler REST operations. See also: [Use Redpanda with the HTTP Proxy API](../../develop/http-proxy/). - Admin API Reference Manage components of a Redpanda cluster, such as individual brokers and partition leadership. The Redpanda Admin API also allows you to perform operations that are specific to Redpanda Self-Managed and cannot be done using the standard Kafka API. See also: [Manage Redpanda using the Admin API](../../manage/use-admin-api/). - [Admin API (legacy)](/api/doc/admin/) endpoints are available on all supported versions of Redpanda. Select "v1" in the version selector to view these endpoints. - [Admin API (ConnectRPC)](/api/doc/admin/v2) endpoints are available on Redpanda version 25.3 and later. These endpoints provide access to new functionality introduced starting in Redpanda v25.3. Select "v2" in the version selector to view these endpoints. --- # Page 245: Golang SDK for Data Transforms **URL**: https://docs.redpanda.com/current/reference/data-transforms/golang-sdk.md --- # Golang SDK for Data Transforms --- title: Golang SDK for Data Transforms latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: data-transforms/golang-sdk page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: data-transforms/golang-sdk.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/data-transforms/golang-sdk.adoc description: Work with data transform APIs in Redpanda using Go. page-git-created-date: "2024-07-31" page-git-modified-date: "2025-04-08" support-status: supported --- The API reference is in the Go package documentation: - [Data transforms client library](https://pkg.go.dev/github.com/redpanda-data/redpanda/src/transform-sdk/go/transform#section-documentation): This library provides a framework for writing transforms. - [Schema Registry client library](https://pkg.go.dev/github.com/redpanda-data/redpanda/src/transform-sdk/go/transform/sr): This library provides data transforms with access to the Schema Registry built into Redpanda. ## [](#suggested-reading)Suggested reading - [Versioning and Compatibility for Data Transforms](../../../develop/data-transforms/versioning-compatibility/) - [Upgrade the Data Transforms SDK](../../../develop/data-transforms/upgrade/) ## Suggested labs - [Flatten JSON Messages](/redpanda-labs/data-transforms/flatten-go/) - [Convert JSON Messages into Avro](/redpanda-labs/data-transforms/issdemo-go/) - [Convert Timestamps using Rust](/redpanda-labs/data-transforms/ts-converter-rust/) - [Filter Messages into a New Topic using a Regex](/redpanda-labs/data-transforms/regex-go/) - [Redact Information in JSON Messages](/redpanda-labs/data-transforms/redaction-go/) [Search all labs](/redpanda-labs) --- # Page 246: JavaScript SDK for Data Transforms **URL**: https://docs.redpanda.com/current/reference/data-transforms/js.md --- # JavaScript SDK for Data Transforms --- title: JavaScript SDK for Data Transforms latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: data-transforms/js/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: data-transforms/js/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/data-transforms/js/index.adoc description: This page provides a list of API packages available in the JavaScript SDK for data transforms. Explore the functionalities and methods offered by each package to implement data transforms in your applications. page-git-created-date: "2024-07-31" page-git-modified-date: "2024-08-01" support-status: supported --- - [JavaScript API for Data Transforms](js-sdk/) Work with data transforms using JavaScript. - [JavaScript Schema Registry API for Data Transforms](js-sdk-sr/) Work with Schema Registry in data transforms using JavaScript. --- # Page 247: JavaScript Schema Registry API for Data Transforms **URL**: https://docs.redpanda.com/current/reference/data-transforms/js/js-sdk-sr.md --- # JavaScript Schema Registry API for Data Transforms --- title: JavaScript Schema Registry API for Data Transforms latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: data-transforms/js/js-sdk-sr page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: data-transforms/js/js-sdk-sr.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/data-transforms/js/js-sdk-sr.adoc description: Work with Schema Registry in data transforms using JavaScript. page-git-created-date: "2024-07-31" page-git-modified-date: "2025-04-08" support-status: supported --- This page contains the API reference for the Schema Registry client library of the data transforms JavaScript SDK. ## [](#functions)Functions ### [](#newClient)newClient() newClient (): <> Returns a client interface for interacting with Redpanda Schema Registry. #### [](#returns)Returns [`SchemaRegistryClient`](#SchemaRegistryClient) #### [](#example)Example ```js import { newClient, SchemaFormat } from "@redpanda-data/sr"; var sr_client = newClient(); const schema = { type: "record", name: "Example", fields: [ { "name": "a", "type": "long", "default": 0 }, { "name": "b", "type": "string", "default": "" } ] }; const subj_schema = sr_client.createSchema( "avro-value", { schema: JSON.stringify(schema), format: SchemaFormat.Avro, references: [], } ); ``` ### [](#decodeSchemaID)decodeSchemaID() decodeSchemaID (\`buf\`): <> #### [](#parameters)Parameters - `buf`: `string`, `ArrayBuffer`, or `Uint8Array` #### [](#returns-2)Returns [`DecodeResult`](#DecodeResult) in the same type as the given argument. ## [](#interfaces)Interfaces ### [](#DecodeResult)DecodeResult The result of a [`decodeSchemaID`](#decodeSchemaID) function. #### [](#properties)Properties - `id` (read only): The decoded schema ID - `rest` (read only): The remainder of the input buffer after stripping the encoded ID. ### [](#reference)Reference #### [](#properties-2)Properties - `name`: `string` - `subject`: `string` - `version`: `number` ### [](#schema)Schema #### [](#properties-3)Properties - `format` (read only): [`SchemaFormat`](#SchemaFormat) - `references` (read only): [`Reference`](#reference) - `schema` (read only): `string` ### [](#SchemaRegistryClient)SchemaRegistryClient Client interface for interacting with Redpanda Schema Registry. #### [](#methods)Methods - `createSchema(subject (string), [schema](#schema))`: [`SubjectSchema`](#SubjectSchema) - `lookupLatestSchema(subject (string))`: [`SubjectSchema`](#SubjectSchema) - `lookupSchemaById(id (number))`: [`Schema`](#schema) - `lookupSchemaByVersion(subject (string), version (number))`: [`SubjectSchema`](#SubjectSchema) ### [](#SubjectSchema)SubjectSchema #### [](#properties-4)Properties - `id` (read only): `number` - `schema` (read only): [`Schema`](#schema) - `subject` (read only): `string` - `version` (read only): `number` ## [](#enumerations)Enumerations ### [](#SchemaFormat)SchemaFormat #### [](#enumeration-members)Enumeration members - Avro: `0` - Protobuf: `1` - JSON: `2` ## [](#suggested-reading)Suggested reading [JavaScript API for Data Transforms](../js-sdk/) --- # Page 248: JavaScript API for Data Transforms **URL**: https://docs.redpanda.com/current/reference/data-transforms/js/js-sdk.md --- # JavaScript API for Data Transforms --- title: JavaScript API for Data Transforms latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: data-transforms/js/js-sdk page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: data-transforms/js/js-sdk.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/data-transforms/js/js-sdk.adoc description: Work with data transforms using JavaScript. page-git-created-date: "2024-07-31" page-git-modified-date: "2025-04-08" support-status: supported --- This page contains the API reference for the data transforms client library of the JavaScript SDK. ## [](#functions)Functions ### [](#OnRecordWritten)onRecordWritten() onRecordWritten (\`cb\`): \`void\` Registers a callback to be fired when a record is written to the input topic. This callback is triggered after the record has been written, fsynced to disk, and acknowledged by the producer. This method should be called in your script’s entry point. #### [](#parameters)Parameters - [`cb`](#OnRecordWrittenCallback) #### [](#returns)Returns `void` #### [](#example)Example ```ts import {onRecordWritten} from "@redpanda-data/transform-sdk"; // Copy the input data to the output topic. onRecordWritten((event, writer) => { writer.write(event.record); }); ``` ## [](#interfaces)Interfaces ### [](#OnRecordWrittenCallback)OnRecordWrittenCallback() OnRecordWrittenCallback : (\`event\`, \`writer\`) => \`void\` The callback type for [`OnRecordWritten`](#OnRecordWritten). #### [](#parameters-2)Parameters - [`event`](#OnRecordWrittenEvent): The event object representing the written record. - [`writer`](#RecordWriter): The writer object used to write transformed records to the output topics. #### [](#returns-2)Returns `void` ### [](#OnRecordWrittenEvent)OnRecordWrittenEvent An event generated after a write event within the broker. #### [](#properties)Properties - [`record`](#WrittenRecord) (read only): The record that was written as part of this event. ### [](#Record)Record A record within Redpanda, generated as a result of any transforms acting upon a written record. #### [](#properties-2)Properties - [`headers`](#RecordHeader) (optional, read only): The headers attached to this record. - `key` (optional, read only): The key for this record. The key can be `string`, `ArrayBuffer`, `Uint8Array`, or [`RecordData`](#RecordData). - `value` (optional, read only): The value for this record. The value can be `string`, `ArrayBuffer`, `Uint8Array`, or [`RecordData`](#RecordData). ### [](#RecordData)RecordData A wrapper around the underlying raw data in a record, similar to a JavaScript response object. #### [](#methods)Methods - `array()`: Returns the data as a raw byte array (`Uint8Array`). - `json()`: Parses the data as JSON. This is a more efficient version of `JSON.parse(text())`. Returns the parsed JSON. Throws an error if the payload is not valid JSON. - `text()`: Parses the data as a UTF-8 string. Returns the parsed string. Throws an error if the payload is not valid UTF-8. ### [](#RecordHeader)RecordHeader Records may have a collection of headers attached to them. Headers are opaque to the broker and are only a mechanism for the producer and consumers to pass information. #### [](#properties-3)Properties - `key` (optional, read only): The key for this header. The key can be `string`, `ArrayBuffer`, `Uint8Array`, or [`RecordData`](#RecordData). - `value` (optional, read only): The value for this header. The value can be `string`, `ArrayBuffer`, `Uint8Array`, or [`RecordData`](#RecordData). ### [](#RecordWriter)RecordWriter A writer for transformed records that are written to the output topics. ### [](#methods-2)Methods - `write([record](#Record))`: Write a record to the output topic. Returns `void`. Throws an error if there are errors writing the record. ### [](#WrittenRecord)WrittenRecord A persisted record written to a topic within Redpanda. It is similar to a `Record`, except that it only contains `RecordData` or `null`. #### [](#properties-4)Properties - [`headers`](#RecordHeader) (read only): The headers attached to this record. - `key` (read only): The key for this record. - [`value`](#RecordData) (optional, read only): The value for this record. ### [](#WrittenRecordHeader)WrittenRecordHeader Records may have a collection of headers attached to them. Headers are opaque to the broker and are only a mechanism for the producer and consumers to pass information. This interface is similar to a [`RecordHeader`](#RecordHeader), except that it only contains `RecordData` or `null`. #### [](#properties-5)Properties - `key` (optional, read only): The key for this header. - `value` (optional, read only): The value for this header. ## [](#suggested-reading)Suggested reading [JavaScript Schema Registry API for Data Transforms](../js-sdk-sr/) --- # Page 249: Rust SDK for Data Transforms **URL**: https://docs.redpanda.com/current/reference/data-transforms/rust-sdk.md --- # Rust SDK for Data Transforms --- title: Rust SDK for Data Transforms latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: data-transforms/rust-sdk page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: data-transforms/rust-sdk.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/data-transforms/rust-sdk.adoc description: Work with data transforms using Rust. page-git-created-date: "2024-07-31" page-git-modified-date: "2025-04-08" support-status: supported --- The API reference is in the crate documentation: - [Data transforms client library](https://docs.rs/redpanda-transform-sdk/latest/redpanda_transform_sdk/): This crate provides a framework for writing transforms. - [Schema Registry client library](https://docs.rs/redpanda-transform-sdk-sr/latest/redpanda_transform_sdk_sr/): This crate provides data transforms with access to the Schema Registry built into Redpanda. ## [](#suggested-reading)Suggested reading - [Versioning and Compatibility for Data Transforms](../../../develop/data-transforms/versioning-compatibility/) - [Upgrade the Data Transforms SDK](../../../develop/data-transforms/upgrade/) --- # Page 250: Data Transforms SDKs **URL**: https://docs.redpanda.com/current/reference/data-transforms/sdks.md --- # Data Transforms SDKs --- title: Data Transforms SDKs latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: data-transforms/sdks page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: data-transforms/sdks.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/data-transforms/sdks.adoc description: This page provides a link to all SDK reference docs for data transforms. page-git-created-date: "2024-07-31" page-git-modified-date: "2024-08-01" support-status: supported --- - [Golang SDK for Data Transforms](../golang-sdk/) Work with data transform APIs in Redpanda using Go. - [Rust SDK for Data Transforms](../rust-sdk/) Work with data transforms using Rust. - [JavaScript SDK for Data Transforms](../js/) This page provides a list of API packages available in the JavaScript SDK for data transforms. Explore the functionalities and methods offered by each package to implement data transforms in your applications. --- # Page 251: Glossary **URL**: https://docs.redpanda.com/current/reference/glossary.md --- # Glossary --- title: Glossary latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: glossary page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: glossary.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/glossary.adoc page-git-created-date: "2024-01-03" page-git-modified-date: "2026-02-04" support-status: supported --- Terms are organized into the following categories: - [Agentic Data Plane](#agentic-data-plane) - [Redpanda Cloud](#redpanda-cloud) - [Redpanda core](#redpanda-core) - [Redpanda features](#redpanda-features) - [Redpanda in Kubernetes](#redpanda-in-kubernetes) - [Redpanda licenses](#redpanda-licenses) - [Redpanda security](#redpanda-security) ## [](#agentic-data-plane)Agentic Data Plane ### [](#agent2agent-a2a-protocol)Agent2Agent (A2A) protocol Communication protocol that enables AI agents to discover, coordinate with, and delegate tasks to other agents in a distributed system. The A2A protocol allows agents to work together by sharing capabilities, coordinating workflows, and distributing complex tasks across multiple specialized agents. It provides standardized messaging, capability discovery, and task delegation mechanisms for multi-agent systems. ### [](#agentic-data-plane-adp)Agentic Data Plane (ADP) Infrastructure layer that enables AI agents to discover, connect to, and interact with data sources and tools through standardized protocols. The Agentic Data Plane provides the underlying infrastructure for AI agents to access streaming data, invoke tools, and coordinate operations across distributed systems using protocols like MCP and A2A. ### [](#ai-agent)AI agent An autonomous program that uses AI models to interpret requests, make decisions, and interact with tools and data sources. AI agents can understand natural language instructions, reason about tasks, invoke tools through MCP servers, and coordinate multiple operations to accomplish complex workflows. ### [](#ai-token)AI token A credential used specifically for authenticating AI agents and authorizing their access to resources in agentic systems. AI tokens are specialized authentication credentials for AI agents, distinct from bearer tokens used in traditional API authentication. They enable agents to authenticate with MCP servers and access data plane resources while maintaining audit trails of agent operations. ### [](#context-window)context window The maximum amount of text (measured in tokens) that an LLM can process in a single request. The context window determines how much information an agent can consider at once, including the system prompt, conversation history, tool outputs, and retrieved documents. Larger context windows enable more sophisticated reasoning but may increase latency and cost. Common sizes range from 8K to 200K+ tokens. ### [](#frontier-model)frontier model The most advanced and capable AI models available, representing the current state-of-the-art in language understanding and reasoning. Frontier models are cutting-edge large language models with exceptional reasoning, planning, and problem-solving capabilities. Examples include GPT-4, Claude 3, and Gemini Ultra. These models are commonly used to power sophisticated AI agents that require advanced decision-making and tool orchestration. ### [](#large-language-model-llm)large language model (LLM) An AI model trained on vast amounts of text data that can understand and generate human-like text, reason about tasks, and follow instructions. Large language models power AI agents by providing natural language understanding, reasoning capabilities, and the ability to plan and execute complex tasks. LLMs interpret user requests, decide which tools to invoke, and synthesize responses based on retrieved data. ### [](#mcp-client)MCP client An AI application or agent that connects to MCP servers to discover and invoke tools. MCP clients use the Model Context Protocol to communicate with MCP servers, discovering available tools, understanding their capabilities, and invoking them with appropriate parameters. The client handles authentication, request formatting, and response processing. ### [](#mcp-server)MCP server A service that exposes tools and resources using the Model Context Protocol, allowing AI agents to discover and invoke them. MCP servers act as bridges between AI agents and external systems, providing standardized interfaces for tool discovery, invocation, and resource access. ### [](#model-context-protocol-mcp)Model Context Protocol (MCP) A standardized protocol that enables AI agents to connect with external data sources and tools in Redpanda. MCP provides a consistent interface for AI applications to discover and interact with data sources, services, and computational tools through Redpanda infrastructure. ### [](#observability-o11y)observability (o11y) The ability to understand a system’s internal state by examining its external outputs, such as traces, metrics, and logs. In Redpanda’s agentic systems, observability enables debugging agent behavior, monitoring performance, analyzing execution flow, and identifying bottlenecks through transcripts captured in the `redpanda.otel_traces` topic. ### [](#opentelemetry)OpenTelemetry Open-source observability framework that provides standardized APIs, libraries, and tools for capturing and exporting telemetry data. OpenTelemetry provides standardized APIs for capturing traces, metrics, and logs from applications. Redpanda agents and MCP servers automatically emit OpenTelemetry traces to the `redpanda.otel_traces` topic to provide complete observability into agentic system operations. ### [](#otlp-opentelemetry-protocol)OTLP (OpenTelemetry Protocol) Standard protocol for encoding and transmitting telemetry data defined by the OpenTelemetry project. OTLP is the OpenTelemetry Protocol specification for encoding and transmitting telemetry data. Redpanda stores spans in the `redpanda.otel_traces` topic using a Protobuf schema that closely follows the OTLP specification. ### [](#prompt)prompt Natural language instructions or context provided to an LLM to guide its behavior and responses. Prompts are the primary way to communicate with LLMs and AI agents. They can include instructions, examples, context, and questions that guide the model’s reasoning and output. Effective prompt design is critical for agent performance and reliability. ### [](#span)span A single unit of work within a trace representing one operation, such as a data processing operation or an external API call. Spans are organized in the Redpanda UI as parent-child relationships that show how operations flow through the system. Each span captures details about a specific operation, including timing, status, and metadata. ### [](#subagent)subagent A specialized AI agent that handles specific tasks or domains as part of a larger multi-agent system. Subagents are autonomous components within a multi-agent architecture that have focused expertise in particular domains or operations. They communicate with a parent agent or other subagents to accomplish complex workflows that require coordination across multiple specializations. ### [](#system-prompt)system prompt Initial instructions that define an agent’s role, capabilities, and behavioral guidelines. The system prompt is provided at the start of an agent session and establishes the agent’s identity, available tools, operating constraints, and response style. It remains active throughout the conversation and shapes all subsequent agent behavior and decision-making. ### [](#tool-invocation)tool invocation The process of an AI agent executing an MCP tool to perform a specific operation. Tool invocation occurs when an agent determines that it needs to use a tool, formats the request with appropriate parameters, sends it to the MCP server, and processes the response. Each invocation is captured in transcripts as spans for observability and debugging. ### [](#trace)trace The complete lifecycle of a request captured as a collection of spans, showing how operations relate to each other. A trace represents the complete lifecycle of a request (for example, a tool invocation from start to finish). A trace contains one or more spans organized hierarchically, showing how operations relate to each other. ### [](#transcript)transcript Complete observability record of agent or MCP server operations captured as OpenTelemetry traces and stored in the redpanda.otel\_traces topic. Transcripts capture tool invocations, agent reasoning steps, data processing operations, external API calls, error conditions, and performance metrics. They provide a complete record of how agentic systems operate, enabling debugging, auditing, and performance analysis. ## [](#redpanda-cloud)Redpanda Cloud ### [](#beta)beta Features in beta are available for testing and feedback. They are not supported by Redpanda and should not be used in production environments. ### [](#byoc)BYOC Bring Your Own Cloud (BYOC) is a fully-managed Redpanda Cloud deployment where clusters run in your private cloud, so all data is contained in your own environment. Redpanda handles provisioning, operations, and maintenance. ### [](#byovnet)BYOVNet A Bring Your Own Virtual Network (BYOVNet) cluster allows you to deploy the Redpanda data plane into your existing Azure VNet to fully manage the networking lifecycle. Compared to standard BYOC, BYOVNet provides more security, but the configuration is more complex. ### [](#byovpc)BYOVPC A Bring Your Own Virtual Private Cloud (BYOVPC) cluster allows you to deploy the Redpanda data plane into your existing VPC on AWS or GCP to fully manage the networking lifecycle. Compared to standard BYOC, BYOVPC provides more security, but the configuration is more complex. ### [](#connector)connector Enables Redpanda to integrate with external systems, such as databases. ### [](#control-plane)control plane This part of Redpanda Cloud enforces rules in the data plane, including cluster management, operations, and maintenance. ### [](#data-plane)data plane This part of Redpanda Cloud contains Redpanda clusters and other components, such as Redpanda Console, Redpanda Operator, and `rpk`. It is managed by an agent that receives cluster specifications from the control plane. Sometimes used interchangeably with clusters. ### [](#data-sovereignty)data sovereignty Containing all your data in your environment. With BYOC, Redpanda handles provisioning, monitoring, and upgrades, but you manage your streaming data without Redpanda’s control plane ever seeing it. Additionally, with BYOVPC, the Redpanda Cloud agent doesn’t create any new resources or alter any settings in your account. ### [](#dedicated-cloud)Dedicated Cloud A fully-managed Redpanda Cloud deployment option where you host your data in Redpanda’s VPC, and Redpanda handles provisioning, operations, and maintenance. Dedicated clusters are single-tenant deployments that support private networking (for example, VPC peering to talk over private IPs) for better data isolation. ### [](#limited-availability)limited availability Features in limited availability (LA) are production-ready and are covered by Redpanda Support for early adopters. ### [](#pipeline)pipeline A single configuration file running in Redpanda Connect with an input connector, an output connector, and optional processors in between. A pipeline typically streams data into Redpanda from an operational source (like PostgreSQL) or streams data out of Redpanda into an analytical system (like Snowflake). ### [](#redpanda-cloud-2)Redpanda Cloud A fully-managed data streaming service deployed with Redpanda Console. It includes automated upgrades and patching, backup and recovery, data and partition balancing, and built-in connectors. Redpanda Cloud is available in Serverless, Dedicated, and Bring Your Own Cloud (BYOC) deployment options to suit different data sovereignty and infrastructure requirements. ### [](#redpanda-console)Redpanda Console The web-based UI for managing and monitoring Redpanda clusters and streaming workloads. You can also set up and manage connectors in Redpanda Console. Redpanda Console is an integral part of Redpanda Cloud, but it also can be used as a standalone program as part of a Redpanda Self-Managed deployment. ### [](#remote-mcp)Remote MCP An MCP server hosted in your Redpanda Cloud cluster. It exposes custom tools that AI assistants can call to access your data and workflows. ### [](#resource-group)resource group A container for Redpanda Cloud resources, including clusters and networks. You can rename your default resource group, and you can create more resource groups. For example, you may want different resource groups for production and testing. ### [](#serverless)Serverless Serverless is the fastest and easiest way to start data streaming. You host your data in Redpanda’s VPC, and Redpanda handles automatic scaling, provisioning, operations, and maintenance. ### [](#sink-connector)sink connector Exports data from a Redpanda cluster into a target system. ### [](#source-connector)source connector Imports data from a source system into a Redpanda cluster. ## [](#redpanda-connect)Redpanda Connect ### [](#mcp-tool)MCP tool A function that an AI assistant can call to perform a specific task, such as fetching data from an API, querying a database, or processing streaming data. Each tool is defined using Redpanda Connect components and annotated with MCP metadata. ### [](#processor)processor A Redpanda Connect component that transforms data, validates inputs, or calls external APIs within a processing pipeline. Processors are stateless components in Redpanda Connect that operate on individual messages or batches. When used as MCP tools, processors handle data transformations, validate parameters, and invoke external services. Each processor executes independently per request with no state maintained between invocations. ### [](#redpanda-connect-mcp-server)Redpanda Connect MCP server A process that exposes Redpanda Connect components to MCP clients. You write each tool’s logic using Redpanda Connect configurations and annotate them with MCP metadata so clients can discover and invoke them. ### [](#redpanda-connect-2)Redpanda Connect A framework for building data streaming applications using declarative YAML configurations. Redpanda Connect provides components such as inputs, processors, outputs, and caches to define data flows and transformations. ## [](#redpanda-core)Redpanda core ### [](#availability-zone-az)availability zone (AZ) One or more data centers served by high-bandwidth links with low latency, typically within a close distance of one another. ### [](#broker)broker An instance of Redpanda that stores and manages event streams. Multiple brokers join together to form a Redpanda cluster. Sometimes used interchangeably with node, but a node is typically a physical or virtual server. See also: node ### [](#client)client A producer application that writes events to Redpanda, or a consumer application that reads events from Redpanda. This could also be a client library, like librdkafka or franz-go. ### [](#cluster)cluster One or more brokers that work together to manage real-time data streaming, processing, and storage. ### [](#consumer-group)consumer group A set of consumers that cooperate to read data for better scalability. As group members arrive and leave, partitions are re-assigned so each member receives a proportional share. ### [](#consumer-offset)consumer offset The position of a consumer in a specific topic partition, to track which records they have read. A consumer offset of 3 means it has read messages 0-2 and will next read message 3. ### [](#consumer)consumer A client application that subscribes to Redpanda topics to asynchronously read events. ### [](#controller-broker)controller broker A broker that manages operational metadata for a Redpanda cluster and ensures replicas are distributed among brokers. At any given time, one active controller exists in a cluster. If the controller fails, another broker is automatically elected as the controller. ### [](#data-stream)data stream A continuous flow of events in real time that are produced and consumed by client applications. Redpanda is a data streaming platform. Also known as event stream. ### [](#event)event A record of something changing state at a specific time. Events can be generated by various sources, including sensors, applications, and devices. Producers write events to Redpanda, and consumers read events from Redpanda. ### [](#kafka-api)Kafka API Producers and consumers interact with Redpanda using the Kafka API. It uses the default port 9092. ### [](#learner)learner A broker that is a follower in a Raft group but is not part of quorum. In a Raft group, a broker can be in learner status. Learners are followers that cannot vote and so do not count towards quorum (the majority). They cannot be elected to leader nor can they trigger leader elections. Brokers can be promoted or demoted between learner and voter. New Raft group members start as learners. ### [](#listener)listener Configuration on a broker that defines how it should accept client or inter-broker connections. Each listener is associated with a specific protocol, hostname, and port combination. The listener defines where the broker should listen for incoming connections. ### [](#log)log An ordered, append-only, immutable sequence of records. The log is Redpanda’s core storage abstraction for event streams. At the conceptual level, topics represent replayable logs. Physically, each partition is implemented as a log file on disk, divided into segments. Redpanda uses the Raft consensus algorithm to coordinate writing data to log files and replicate them across brokers for fault tolerance. See also: topic, partition, segment ### [](#message)message One or more records representing individual events being transmitted. Redpanda transfers messages between producers and consumers. Sometimes used interchangeably with record. ### [](#node)node A machine, which could be a server, a virtual machine (instance), or a Docker container. Every node has its own disk. Partitions are stored locally on nodes. In Kubernetes, a Node is the machine that Redpanda runs on. Outside the context of Kubernetes, this term may be used interchangeably with broker, such as `node_id`. See also: broker ### [](#offset-commit)offset commit An acknowledgement that the event has been read. ### [](#offset)offset A unique integer assigned to each record to show its location in the partition. ### [](#pandaproxy)pandaproxy Original name for the subsystem of Redpanda that allows access to your data through a REST API. This name still appears in the HTTP Proxy API and the Schema Registry API. ### [](#partition-leader)partition leader Every Redpanda partition forms a Raft group with a single elected leader. This leader handles all writes, and it replicates data to followers to ensure that a majority of brokers store the data. ### [](#partition)partition A subset of events in a topic, like a log file. It is an ordered, immutable sequence of records. Partitions allow you to distribute a stream, which lets producers write messages in parallel and consumers read messages in parallel. Partitions are made up of segment files on disk. ### [](#producer)producer A client application that writes events to Redpanda. Redpanda stores these events in sequence and organizes them into topics. ### [](#rack)rack A failure zone that has one or more Redpanda brokers assigned to it. ### [](#raft)Raft The consensus algorithm Redpanda uses to coordinate writing data to log files and replicating that data across brokers. For more details, see [https://raft.github.io/](https://raft.github.io/) ### [](#record)record A self-contained data entity with a defined structure, representing a single event. Sometimes used interchangeably with message. ### [](#replicas)replicas Copies of partitions that are distributed across different brokers, so if one broker goes down, there is a copy of the data. ### [](#retention)retention The mechanism for determining how long Redpanda stores data on local disk or in object storage before purging it. ### [](#replication-factor)replication factor The number of partition copies in a cluster. This is set to 3 in Redpanda Cloud deployments and 1 (no replication) in Self-Managed deployments. A replication factor of at least 3 ensures that each partition has a copy of its data on at least one other broker. One replica acts as the leader, and the other replicas are followers. ### [](#schema)schema An external mechanism to describe the structure of data and its encoding. Schemas validate the structure and ensure that producers and consumers can connect with data in the same format. ### [](#seastar)Seastar An open-source thread-per-core C++ framework, which binds all work to physical cores. Redpanda is built on Seastar. For more details, see [https://seastar.io/](https://seastar.io/) ### [](#seed-server)seed server The initial set of brokers that a Redpanda broker contacts to join the cluster. Seed servers play a crucial role in cluster formation and recovery, acting as a point of reference for new or restarting brokers to understand the current topology of the cluster. ### [](#segment)segment Discrete part of a partition, used to break down a continuous stream into manageable chunks. You can set the maximum duration (`segment.ms`) or size (`segment.bytes`) for a segment to be open for writes. ### [](#serialization)serialization The process of converting a record into a format that can be stored. Deserialization is the process of converting a record back to the original state. Redpanda Schema Registry supports Avro and Protobuf serialization formats. ### [](#shard)shard A CPU core. ### [](#subject)subject A logical grouping or category for schemas. When data formats are updated, a new version of the schema can be registered under the same subject, allowing for backward and forward compatibility. ### [](#thread-per-core)thread-per-core Programming model that allows Redpanda to pin each of its application threads to a CPU core to avoid context switching and blocking. ### [](#topic-partition)topic partition A topic may be partitioned through multiple brokers. A "topic partition" represents this logical separation in Redpanda, which is managed natively by Raft. ### [](#topic)topic A logical stream of related events that are written to the same log. It can be divided into multiple partitions. A topic can have various clients writing events to it and reading events from it. ## [](#redpanda-features)Redpanda features ### [](#admin-api)Admin API A REST API used to manage and monitor Redpanda Self-Managed clusters. It uses the default port 9644. For more information about using this API with Self-Managed Redpanda, see [/api/doc/admin](/api/doc/admin). Note: The Redpanda Admin API is different from the [Kafka Admin API](https://kafka.apache.org/documentation/#adminapi). ### [](#cloud-topic)Cloud Topic A Redpanda topic type, Cloud Topics use object storage (S3, GCS, or MinIO) as the primary data store (rather than replicating data across brokers). Unlike standard Redpanda topics, Cloud Topics allow users with flexible latency requirements to lower or eliminate costs associated with cross-AZ networking. ### [](#compaction)compaction Feature that retains the latest value for each key within a partition while discarding older values. ### [](#controller-snapshot)controller snapshot Snapshot of the current cluster metadata state saved to disk, so broker startup is fast. ### [](#data-transforms)data transforms Framework to manipulate or enrich data written to Redpanda topics. You can develop custom data functions, which run asynchronously using a WebAssembly (Wasm) engine inside a Redpanda broker. ### [](#http-proxy)HTTP Proxy Redpanda HTTP Proxy (pandaproxy) allows access to your data through a REST API. It is built into the Redpanda binary and uses the default port 8082. ### [](#leader-pinning)Leader Pinning Feature that places a topic’s partition leaders in a preferred location, such as a cloud availability zone, to reduce networking costs and latency for nearby clients. ### [](#maintenance-mode)maintenance mode A state where a Redpanda broker temporarily doesn’t take any partition leaderships. It continues to store data as a follower. This is usually done for system maintenance or a rolling upgrade. ### [](#rack-awareness)rack awareness Feature that lets you distribute replicas of the same partition across different racks to minimize data loss and improve fault tolerance in the event of a rack failure. ### [](#rebalancing)rebalancing Process of moving partition replicas and transferring partition leadership for improved performance. Redpanda provides various topic-aware tools to balance clusters for best performance. - Leadership balancing changes where data is written to first, but it does not involve any data transfer. The partition leader regularly sends heartbeats to its followers. If a follower does not receive a heartbeat within a timeout, it triggers a new leader election. Redpanda also provides leadership balancing when brokers are added or decommissioned. - Partition replica balancing moves partition replicas to alleviate disk pressure and to honor the configured replication factor across brokers and the additional redundancy across failure domains (such as racks). Redpanda provides partition replica rebalancing when brokers are added or decommissioned. - With an Enterprise license, you can additionally enable Continuous Data Balancing to continuously monitor broker and rack availability and disk usage. ### [](#rolling-upgrade)rolling upgrade The process of upgrading each broker in a Redpanda cluster, one at a time, to minimize disruption and ensure continuous availability. ### [](#rpk)rpk Redpanda’s command-line interface tool for managing Redpanda clusters. ### [](#remote-read-replica)Remote Read Replica A read-only topic that mirrors a topic on a different cluster, using data from Tiered Storage. ### [](#schema-registry)Schema Registry Redpanda Schema Registry (pandaproxy) is the interface for storing and managing event schemas. Producers and consumers register and retrieve schemas they use from the registry. It is built into the Redpanda binary and uses the default port 8081. ### [](#tiered-storage)Tiered Storage Feature that lets you offload log segments to object storage in near real-time, providing long-term data retention and topic recovery. ## [](#redpanda-in-kubernetes)Redpanda in Kubernetes ### [](#cert-manager)cert-manager A Kubernetes controller that simplifies the process of obtaining, renewing, and using certificates. For more details, see [https://cert-manager.io/docs/](https://cert-manager.io/docs/) ### [](#redpanda-helm-chart)Redpanda Helm chart Generates and applies all the manifest files you need for deploying Redpanda in Kubernetes. ### [](#redpanda-operator)Redpanda Operator Extends Kubernetes with custom resource definitions (CRDs), which allow Redpanda clusters to be treated as native Kubernetes resources. ## [](#redpanda-licenses)Redpanda licenses ### [](#redpanda-community-edition)Redpanda Community Edition Redpanda software that is available under the Redpanda Business Source License (BSL). These core features are free and source-available. ### [](#redpanda-enterprise-edition)Redpanda Enterprise Edition Redpanda software that is available under the Redpanda Community License (RCL). It includes the free features licensed with the Redpanda Community Edition, as well enterprise features, such as Tiered Storage, Remote Read Replicas, and Continuous Data Balancing. ### [](#self-managed)Self-Managed Redpanda Self-Managed refers to the product offering that includes both the Enterprise Edition and the Community Edition of Redpanda. Sometimes used interchangeably with self-hosted. ## [](#redpanda-security)Redpanda security ### [](#access-control-list-acl)access control list (ACL) A security feature used to define and enforce granular permissions to resources, ensuring only authorized users or applications can perform specific operations. ACLs act on principals. ### [](#advertised-listener)advertised listener The address a Redpanda broker broadcasts to producers, consumers, and other brokers. It specifies the hostname and port for connections to different listeners. Clients and other brokers use advertised listeners to connect to services such as the Admin API, Kafka API, and HTTP Proxy API. The advertised address might differ from the listener address in scenarios where brokers are behind a NAT, in a Docker container, or in Kubernetes. Advertised addresses ensure clients can reach the Redpanda brokers even in complex network setups. ### [](#authentication)authentication The process of verifying the identity of a principal, user, or service account. Also known as AuthN. ### [](#authorization)authorization The process of specifying access rights to resources. Access rights are enforced through roles or access control lists (ACLs). Also known as AuthZ. ### [](#bearer-token)bearer token An access token used for authentication and authorization in web applications and APIs. It holds user credentials, usually in the form of random strings of characters. ### [](#gbac)GBAC Group-based access control lets you manage Redpanda permissions at scale by assigning them to OIDC groups instead of individual users. GBAC lets you manage Redpanda permissions at scale using the groups that already exist in your identity provider (IdP). You define access once for a group and your IdP controls who belongs to it. You can grant permissions to groups in two ways: create ACLs with `Group:` principals, or assign groups as members of RBAC roles. Both approaches can be used independently or together. ### [](#identity-provider-idp)identity provider (IdP) A service that creates, maintains, and manages identity information while providing authentication services to applications. Identity providers authenticate users and issue tokens that applications can use to verify identity and access permissions. Common IdPs include Okta, Auth0, Azure AD, and Google Identity Platform. ### [](#openid-connect-oidc)OpenID Connect (OIDC) Authentication layer built on OAuth 2.0 that allows clients to verify user identity and obtain basic profile information. OpenID Connect provides a standardized way for applications to authenticate users through identity providers. In Redpanda’s agentic systems, OIDC enables secure authentication for AI agents and MCP servers accessing cloud resources. ### [](#principal)principal An authenticated identity (user, service account, or group) that Redpanda evaluates when enforcing ACLs and role assignments. Redpanda supports `User:` and `Group:` principal types. Permissions are granted to principals through ACLs or RBAC role assignments. ### [](#rbac)RBAC Role-based access control lets you assign users access to specific resources. ### [](#service-account)service account An identity independent of the user who created it that can be used to authenticate and perform operations. This is especially useful for authentication of machines. --- # Page 252: Internal Metrics **URL**: https://docs.redpanda.com/current/reference/internal-metrics-reference.md --- # Internal Metrics --- title: Internal Metrics latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: internal-metrics-reference page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: internal-metrics-reference.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/internal-metrics-reference.adoc description: Redpanda internal metrics for detailed analysis, debugging, and troubleshooting. page-git-created-date: "2023-05-30" page-git-modified-date: "2025-07-24" support-status: supported --- This section provides reference descriptions about the internal metrics exported from Redpanda’s `/metrics` endpoint. > 💡 **TIP** > > Use [/public\_metrics](../public-metrics-reference/) for your primary dashboards for monitoring system health. These metrics have low cardinality and are designed for customer consumption, with aggregated labels for better performance. **Public metrics use the `redpanda_` prefix.** > > Use [/metrics](./) for detailed analysis and debugging. These metrics can have high cardinality with thousands of series, providing granular operational insights. **Internal metrics use the `vectorized_` prefix.** > ❗ **IMPORTANT** > > In a live system, Redpanda metrics are exported only for features that are in use. For example, a metric for consumer groups is not exported when no groups are registered. > > To see the available internal metrics in your system, query the `/metrics` endpoint: > > ```bash > curl http://:9644/metrics | grep "[HELP|TYPE]" > ``` Internal metrics (`/metrics`) can generate thousands of metric series in production environments, so use them judiciously in monitoring systems to avoid performance issues. For alerting and dashboards, public metrics are preferable (`/public_metrics`) because they are optimized for lower cardinality. The [aggregate\_metrics](../properties/cluster-properties/#aggregate_metrics) cluster property controls internal metrics cardinality. When you enable this property, internal metrics combine labels (like shard) to reduce the number of series. Public metrics always combine labels, regardless of this setting. ## [](#vectorized_alien_receive_batch_queue_length)vectorized\_alien\_receive\_batch\_queue\_length Indicates the current length of the alien receive batch queue. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_alien_total_received_messages)vectorized\_alien\_total\_received\_messages Tracks the cumulative number of alien messages that have been received. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_alien_total_sent_messages)vectorized\_alien\_total\_sent\_messages Tracks the cumulative number of alien messages that have been sent. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_application_build)vectorized\_application\_build Provides build details for Redpanda including the build revision, shard identifier, and version. **Type**: gauge **Labels**: - `revision` - `shard` - `version` * * * ## [](#vectorized_application_fips_mode)vectorized\_application\_fips\_mode Indicates whether Redpanda is running in FIPS (Federal Information Processing Standards) mode. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_application_uptime)vectorized\_application\_uptime Reports the uptime of the Redpanda application in milliseconds. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_archival_upload_backlog_controller_backlog_size)vectorized\_archival\_upload\_backlog\_controller\_backlog\_size Shows the current backlog size in the archival upload controller. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_archival_upload_backlog_controller_error)vectorized\_archival\_upload\_backlog\_controller\_error Reports the current error value (difference between set point and backlog size) in the archival upload controller. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_archival_upload_backlog_controller_shares)vectorized\_archival\_upload\_backlog\_controller\_shares Represents the number of shares (or work units) output by the archival upload controller. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_authorization_result)vectorized\_authorization\_result Counts the total number of authorization results, broken down by result type. **Type**: counter **Labels**: - `type` * * * ## [](#vectorized_chunk_cache_available_size_bytes)vectorized\_chunk\_cache\_available\_size\_bytes Measures the total size (in bytes) of all free segment appender chunks in the cache. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_chunk_cache_total_size_bytes)vectorized\_chunk\_cache\_total\_size\_bytes Reports the total size (in bytes) of all segment appender chunks regardless of state. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_chunk_cache_wait_count)vectorized\_chunk\_cache\_wait\_count Counts how many times a request had to wait for a segment appender chunk to become available. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cloud_client_active_downloads)vectorized\_cloud\_client\_active\_downloads Indicates the number of active GET requests to the object storage. **Type**: gauge **Labels**: - `endpoint` - `region` - `shard` * * * ## [](#vectorized_cloud_client_active_requests)vectorized\_cloud\_client\_active\_requests Reports the number of active HTTP requests (both PUT and GET) currently in progress. **Type**: gauge **Labels**: - `endpoint` - `region` - `shard` * * * ## [](#vectorized_cloud_client_active_uploads)vectorized\_cloud\_client\_active\_uploads Shows the number of active PUT requests currently executing. **Type**: gauge **Labels**: - `endpoint` - `region` - `shard` * * * ## [](#vectorized_cloud_client_all_requests)vectorized\_cloud\_client\_all\_requests Counts the total number of completed HTTP requests (includes both PUT and GET). **Type**: counter **Labels**: - `endpoint` - `region` - `shard` * * * ## [](#vectorized_cloud_client_client_pool_utilization)vectorized\_cloud\_client\_client\_pool\_utilization Measures the utilization of the object storage client pool as a percentage (0 means unused, 100 means fully utilized). **Type**: gauge **Labels**: - `endpoint` - `region` - `shard` * * * ## [](#vectorized_cloud_client_lease_duration)vectorized\_cloud\_client\_lease\_duration Provides a histogram of cloud client lease durations. **Type**: histogram * * * ## [](#vectorized_cloud_client_num_borrows)vectorized\_cloud\_client\_num\_borrows Counts how many times a shard has borrowed an object storage client from another shard. **Type**: counter **Labels**: - `endpoint` - `region` - `shard` * * * ## [](#vectorized_cloud_client_num_nosuchkey)vectorized\_cloud\_client\_num\_nosuchkey Counts the total number of NoSuchKey errors returned by the object storage provider. **Type**: counter **Labels**: - `endpoint` - `region` - `shard` * * * ## [](#vectorized_cloud_client_num_rpc_errors)vectorized\_cloud\_client\_num\_rpc\_errors Counts the total number of REST API errors encountered from the object storage provider. **Type**: counter **Labels**: - `endpoint` - `region` - `shard` * * * ## [](#vectorized_cloud_client_num_slowdowns)vectorized\_cloud\_client\_num\_slowdowns Counts the total number of SlowDown errors received from the object storage provider. **Type**: counter **Labels**: - `endpoint` - `region` - `shard` * * * ## [](#vectorized_cloud_client_num_transport_errors)vectorized\_cloud\_client\_num\_transport\_errors Counts the total number of transport errors (including TCP and TLS errors) from the object storage provider. **Type**: counter **Labels**: - `endpoint` - `region` - `shard` * * * ## [](#vectorized_cloud_client_total_downloads)vectorized\_cloud\_client\_total\_downloads Counts the total number of completed `GET` requests to object storage. **Type**: counter **Labels**: - `endpoint` - `region` - `shard` * * * ## [](#vectorized_cloud_client_total_inbound_bytes)vectorized\_cloud\_client\_total\_inbound\_bytes Reports the total number of bytes received from object storage. **Type**: counter **Labels**: - `endpoint` - `region` - `shard` * * * ## [](#vectorized_cloud_client_total_outbound_bytes)vectorized\_cloud\_client\_total\_outbound\_bytes Reports the total number of bytes sent to object storage. **Type**: counter **Labels**: - `endpoint` - `region` - `shard` * * * ## [](#vectorized_cloud_client_total_uploads)vectorized\_cloud\_client\_total\_uploads Counts the total number of completed PUT requests to object storage. **Type**: counter **Labels**: - `endpoint` - `region` - `shard` * * * ## [](#vectorized_cloud_storage_bytes_received)vectorized\_cloud\_storage\_bytes\_received Reports the total number of bytes received from object storage. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_bytes_sent)vectorized\_cloud\_storage\_bytes\_sent Reports the total number of bytes sent to object storage. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_cache_cached_gets)vectorized\_cloud\_storage\_cache\_cached\_gets Counts the number of cache get requests that were served from the cache. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_cache_files)vectorized\_cloud\_storage\_cache\_files Indicates the current number of files stored in the object storage cache. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_cache_gets)vectorized\_cloud\_storage\_cache\_gets Counts the total number of get requests directed at the object storage cache. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_cache_in_progress_files)vectorized\_cloud\_storage\_cache\_in\_progress\_files Shows the current number of files that are in the process of being cached. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_cache_puts)vectorized\_cloud\_storage\_cache\_puts Counts the total number of files successfully placed into the cache. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_cache_size_bytes)vectorized\_cloud\_storage\_cache\_size\_bytes Reports the current size of the object storage cache in bytes. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_client_acquisition_latency)vectorized\_cloud\_storage\_client\_acquisition\_latency Provides a histogram of the latency experienced when acquiring a object storage client. **Type**: histogram * * * ## [](#vectorized_cloud_storage_cluster_metadata_manifest_downloads)vectorized\_cloud\_storage\_cluster\_metadata\_manifest\_downloads Counts the number of partition manifest downloads initiated by the cluster. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_cluster_metadata_manifest_uploads)vectorized\_cloud\_storage\_cluster\_metadata\_manifest\_uploads Counts the number of partition manifest uploads initiated by the cluster. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_controller_snapshot_failed_uploads)vectorized\_cloud\_storage\_controller\_snapshot\_failed\_uploads Counts the number of controller snapshot uploads that have failed. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_controller_snapshot_successful_uploads)vectorized\_cloud\_storage\_controller\_snapshot\_successful\_uploads Counts the number of successful controller snapshot uploads. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_controller_snapshot_upload_backoff)vectorized\_cloud\_storage\_controller\_snapshot\_upload\_backoff Counts the number of times a backoff was applied during controller snapshot uploads. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_download_backoff)vectorized\_cloud\_storage\_download\_backoff Counts how many times backoff was applied during log-segment downloads. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_failed_downloads)vectorized\_cloud\_storage\_failed\_downloads Counts the number of failed log-segment download attempts. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_failed_index_downloads)vectorized\_cloud\_storage\_failed\_index\_downloads Counts the number of failed attempts to download segment indices. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_failed_index_uploads)vectorized\_cloud\_storage\_failed\_index\_uploads Counts the number of failed attempts to upload segment indices. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_failed_manifest_downloads)vectorized\_cloud\_storage\_failed\_manifest\_downloads Counts the number of manifest download failures. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_failed_manifest_uploads)vectorized\_cloud\_storage\_failed\_manifest\_uploads Counts the number of manifest upload failures. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_failed_uploads)vectorized\_cloud\_storage\_failed\_uploads Counts the total number of failed log-segment upload attempts. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_index_downloads)vectorized\_cloud\_storage\_index\_downloads Counts the total number of segment index downloads. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_index_uploads)vectorized\_cloud\_storage\_index\_uploads Counts the total number of segment index uploads. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_manifest_download_backoff)vectorized\_cloud\_storage\_manifest\_download\_backoff Counts how many times backoff was applied during manifest downloads. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_manifest_upload_backoff)vectorized\_cloud\_storage\_manifest\_upload\_backoff Counts how many times backoff was applied during manifest uploads. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_partition_chunk_size)vectorized\_cloud\_storage\_partition\_chunk\_size Reports the size (in bytes) of a chunk downloaded from object storage for a given partition. **Type**: gauge **Labels**: - `namespace` - `partition` - `topic` * * * ## [](#vectorized_cloud_storage_partition_manifest_downloads)vectorized\_cloud\_storage\_partition\_manifest\_downloads Counts the number of partition manifest downloads. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_partition_manifest_uploads)vectorized\_cloud\_storage\_partition\_manifest\_uploads Counts the number of (re)uploads for partition manifests. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_partition_read_bytes)vectorized\_cloud\_storage\_partition\_read\_bytes Reports the total number of bytes read from a remote partition. **Type**: counter **Labels**: - `namespace` - `partition` - `topic` * * * ## [](#vectorized_cloud_storage_partition_read_records)vectorized\_cloud\_storage\_partition\_read\_records Counts the total number of records read from a remote partition. **Type**: counter **Labels**: - `namespace` - `partition` - `topic` * * * ## [](#vectorized_cloud_storage_read_path_chunk_hydration_latency)vectorized\_cloud\_storage\_read\_path\_chunk\_hydration\_latency Provides a histogram of the latency for hydrating individual chunks. **Type**: histogram * * * ## [](#vectorized_cloud_storage_read_path_chunks_hydrated)vectorized\_cloud\_storage\_read\_path\_chunks\_hydrated Counts the total number of chunks hydrated (note: some may later be evicted from the cache). **Type**: counter * * * ## [](#vectorized_cloud_storage_read_path_downloads_throttled_sum)vectorized\_cloud\_storage\_read\_path\_downloads\_throttled\_sum Reports the cumulative time (in milliseconds) that downloads were throttled. **Type**: counter * * * ## [](#vectorized_cloud_storage_read_path_hydrations_in_progress)vectorized\_cloud\_storage\_read\_path\_hydrations\_in\_progress Indicates the number of chunk hydrations currently in progress. **Type**: counter * * * ## [](#vectorized_cloud_storage_read_path_materialized_segments)vectorized\_cloud\_storage\_read\_path\_materialized\_segments Shows the current number of remote segments that have been materialized. **Type**: gauge * * * ## [](#vectorized_cloud_storage_read_path_readers)vectorized\_cloud\_storage\_read\_path\_readers Indicates the current number of remote partition readers active. **Type**: gauge * * * ## [](#vectorized_cloud_storage_read_path_segment_readers)vectorized\_cloud\_storage\_read\_path\_segment\_readers Indicates the current number of remote segment readers active. **Type**: gauge * * * ## [](#vectorized_cloud_storage_read_path_spillover_manifest_bytes)vectorized\_cloud\_storage\_read\_path\_spillover\_manifest\_bytes Reports the total memory (in bytes) used by spillover manifests. **Type**: gauge * * * ## [](#vectorized_cloud_storage_read_path_spillover_manifest_hydrated)vectorized\_cloud\_storage\_read\_path\_spillover\_manifest\_hydrated Counts the number of times spillover manifests have been successfully cached. **Type**: counter * * * ## [](#vectorized_cloud_storage_read_path_spillover_manifest_instances)vectorized\_cloud\_storage\_read\_path\_spillover\_manifest\_instances Shows the current number of spillover manifest instances stored in memory. **Type**: gauge * * * ## [](#vectorized_cloud_storage_read_path_spillover_manifest_latency)vectorized\_cloud\_storage\_read\_path\_spillover\_manifest\_latency Provides a histogram of the latency for materializing spillover manifests. **Type**: histogram * * * ## [](#vectorized_cloud_storage_read_path_spillover_manifest_materialized)vectorized\_cloud\_storage\_read\_path\_spillover\_manifest\_materialized Counts the number of times spillover manifests were loaded from the cache. **Type**: counter * * * ## [](#vectorized_cloud_storage_segment_download_latency)vectorized\_cloud\_storage\_segment\_download\_latency Provides a histogram of the latency experienced during segment downloads. **Type**: histogram * * * ## [](#vectorized_cloud_storage_spillover_manifest_downloads)vectorized\_cloud\_storage\_spillover\_manifest\_downloads Counts the number of spillover manifest downloads. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_spillover_manifest_uploads)vectorized\_cloud\_storage\_spillover\_manifest\_uploads Counts the number of spillover manifest (re)uploads. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_successful_downloads)vectorized\_cloud\_storage\_successful\_downloads Counts the number of successful log-segment downloads. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_successful_uploads)vectorized\_cloud\_storage\_successful\_uploads Counts the number of successful log-segment uploads. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_topic_manifest_downloads)vectorized\_cloud\_storage\_topic\_manifest\_downloads Counts the number of topic manifest downloads. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_topic_manifest_uploads)vectorized\_cloud\_storage\_topic\_manifest\_uploads Counts the number of topic manifest uploads. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cloud_storage_upload_backoff)vectorized\_cloud\_storage\_upload\_backoff Counts the number of times backoff was applied during log-segment uploads. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cluster_controller_pending_partition_operations)vectorized\_cluster\_controller\_pending\_partition\_operations Indicates the number of partitions with pending or ongoing operations at the controller level. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_cluster_features_enterprise_license_expiry_sec)vectorized\_cluster\_features\_enterprise\_license\_expiry\_sec Reports the number of seconds remaining until the Enterprise Edition license expires. **Type**: gauge * * * ## [](#vectorized_cluster_partition_batches_produced)vectorized\_cluster\_partition\_batches\_produced Counts the total number of batches produced for a partition. **Type**: gauge **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_cluster_partition_bytes_fetched_from_follower_total)vectorized\_cluster\_partition\_bytes\_fetched\_from\_follower\_total Reports the total number of bytes fetched from follower replicas (may exceed client-returned values). **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_cluster_partition_bytes_fetched_total)vectorized\_cluster\_partition\_bytes\_fetched\_total Reports the total number of bytes fetched (some may not be returned to the client). **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_cluster_partition_bytes_produced_total)vectorized\_cluster\_partition\_bytes\_produced\_total Counts the total number of bytes produced for a partition. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_cluster_partition_cloud_storage_segments_metadata_bytes)vectorized\_cluster\_partition\_cloud\_storage\_segments\_metadata\_bytes Reports the total number of bytes consumed by remote segments metadata for a partition. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_cluster_partition_committed_offset)vectorized\_cluster\_partition\_committed\_offset Shows the committed offset for a partition (safely persisted across a majority of replicas). **Type**: gauge **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_cluster_partition_end_offset)vectorized\_cluster\_partition\_end\_offset Reports the last offset stored on the current broker for a partition. **Type**: gauge **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_cluster_partition_high_watermark)vectorized\_cluster\_partition\_high\_watermark Indicates the high watermark (highest consumable offset) for a partition. **Type**: gauge **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ### [](#vectorized_cluster_partition_iceberg_offsets_pending_commit)vectorized\_cluster\_partition\_iceberg\_offsets\_pending\_commit Reports the total number of offsets that are pending a commit to the Iceberg catalog. Lag is reported only on the leader, while followers report 0. -1 is reported if Iceberg is disabled. -2 indicates the lag is not yet computed. **Type**: gauge **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ### [](#vectorized_cluster_partition_iceberg_offsets_pending_translation)vectorized\_cluster\_partition\_iceberg\_offsets\_pending\_translation Reports the total number of offsets that are pending translation to Iceberg. Lag is reported only on leader replicas, while followers report 0. -1 is reported if Iceberg is disabled. -2 indicates the lag is not yet computed. **Type**: gauge **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_cluster_partition_last_stable_offset)vectorized\_cluster\_partition\_last\_stable\_offset Reports the last stable offset for a partition. A stable offset implies that the partition is fully caught up. **Type**: gauge **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_cluster_partition_leader)vectorized\_cluster\_partition\_leader A flag indicating whether the current instance is the leader for the partition. **Type**: gauge **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_cluster_partition_leader_id)vectorized\_cluster\_partition\_leader\_id Reports the identifier of the current partition leader. **Type**: gauge **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_cluster_partition_moving_from_node)vectorized\_cluster\_partition\_moving\_from\_node Indicates the number of partitions that are currently in the process of moving away from this broker. **Type**: gauge * * * ## [](#vectorized_cluster_partition_moving_to_node)vectorized\_cluster\_partition\_moving\_to\_node Indicates the number of partitions that are currently moving to this broker. **Type**: gauge * * * ## [](#vectorized_cluster_partition_node_cancelling_movements)vectorized\_cluster\_partition\_node\_cancelling\_movements Reports the number of partition movements being cancelled on this broker. **Type**: gauge * * * ## [](#vectorized_cluster_partition_num_with_broken_rack_constraint)vectorized\_cluster\_partition\_num\_with\_broken\_rack\_constraint Counts the number of partitions that do not meet rack awareness constraints. **Type**: gauge * * * ## [](#vectorized_cluster_partition_records_fetched)vectorized\_cluster\_partition\_records\_fetched Counts the total number of records fetched from a partition. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_cluster_partition_records_produced)vectorized\_cluster\_partition\_records\_produced Counts the total number of records produced to a partition. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_cluster_partition_start_offset)vectorized\_cluster\_partition\_start\_offset Indicates the starting offset (raft snapshot offset) for a partition. **Type**: gauge **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_cluster_partition_under_replicated_replicas)vectorized\_cluster\_partition\_under\_replicated\_replicas Reports the number of under-replicated replicas for a partition. **Type**: gauge **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_cluster_producer_state_manager_evicted_producers)vectorized\_cluster\_producer\_state\_manager\_evicted\_producers Counts the total number of producers that have been evicted. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_cluster_producer_state_manager_producer_manager_total_active_producers)vectorized\_cluster\_producer\_state\_manager\_producer\_manager\_total\_active\_producers Reports the total number of active idempotent and transactional producers. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_cluster_shard_placement_assigned_partitions)vectorized\_cluster\_shard\_placement\_assigned\_partitions Indicates the number of partitions assigned to a particular shard. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_cluster_shard_placement_hosted_partitions)vectorized\_cluster\_shard\_placement\_hosted\_partitions Indicates the number of partitions hosted on a specific shard. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_cluster_shard_placement_partitions_to_reconcile)vectorized\_cluster\_shard\_placement\_partitions\_to\_reconcile Counts the number of partitions that require reconciliation of shard-local state. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_data_transforms_log_manager_buffer_usage_ratio)vectorized\_data\_transforms\_log\_manager\_buffer\_usage\_ratio Reports the buffer usage ratio for the data transforms log manager. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_data_transforms_log_manager_write_errors_total)vectorized\_data\_transforms\_log\_manager\_write\_errors\_total Counts the total number of write errors encountered by the transform log manager. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_debug_bundle_failed_generation_count)vectorized\_debug\_bundle\_failed\_generation\_count Counts the total number of failed attempts to generate debug bundles. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_debug_bundle_last_failed_bundle_timestamp_seconds)vectorized\_debug\_bundle\_last\_failed\_bundle\_timestamp\_seconds Reports the timestamp (in seconds since the epoch) of the last failed debug bundle generation. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_debug_bundle_last_successful_bundle_timestamp_seconds)vectorized\_debug\_bundle\_last\_successful\_bundle\_timestamp\_seconds Reports the timestamp (in seconds since the epoch) of the last successful debug bundle generation. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_debug_bundle_successful_generation_count)vectorized\_debug\_bundle\_successful\_generation\_count Counts the total number of successfully generated debug bundles. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_host_diskstats_discards)vectorized\_host\_diskstats\_discards Reports the total number of discard operations initiated on the host disk. Discard operations free unused blocks and can affect disk longevity and performance. This metric is available only when the [`enable_host_metrics`](../properties/cluster-properties/#enable_host_metrics) cluster property is set to `true`. **Type**: gauge **Labels**: - `disk` - `shard` * * * ## [](#vectorized_host_diskstats_discards_merged)vectorized\_host\_diskstats\_discards\_merged Captures the number of discard operations that have been merged together, reducing overhead by consolidating multiple discard requests. This metric is available only when the [`enable_host_metrics`](../properties/cluster-properties/#enable_host_metrics) cluster property is set to `true`. **Type**: gauge **Labels**: - `disk` - `shard` * * * ## [](#vectorized_host_diskstats_discards_ms)vectorized\_host\_diskstats\_discards\_ms Measures the cumulative time in milliseconds spent on discard operations. This metric helps in understanding the performance impact of these operations on disk throughput. This metric is available only when the [`enable_host_metrics`](../properties/cluster-properties/#enable_host_metrics) cluster property is set to `true`. **Type**: gauge **Labels**: - `disk` - `shard` * * * ## [](#vectorized_host_diskstats_flushes)vectorized\_host\_diskstats\_flushes Counts the number of flush operations performed by the host disk. Flushes ensure that buffered data is written to disk, which is important for data integrity. This metric is available only when the [`enable_host_metrics`](../properties/cluster-properties/#enable_host_metrics) cluster property is set to `true`. **Type**: gauge **Labels**: - `disk` - `shard` * * * ## [](#vectorized_host_diskstats_flushes_ms)vectorized\_host\_diskstats\_flushes\_ms Measures the total time in milliseconds spent on flush operations. Monitoring flush duration can indicate disk performance under heavy I/O workloads. This metric is available only when the [`enable_host_metrics`](../properties/cluster-properties/#enable_host_metrics) cluster property is set to `true`. **Type**: gauge **Labels**: - `disk` - `shard` * * * ## [](#vectorized_host_diskstats_io_in_progress)vectorized\_host\_diskstats\_io\_in\_progress Shows the number of I/O operations currently in progress on the disk. This metric provides an insight into the active workload and concurrent operations. This metric is available only when the [`enable_host_metrics`](../properties/cluster-properties/#enable_host_metrics) cluster property is set to `true`. **Type**: gauge **Labels**: - `disk` - `shard` * * * ## [](#vectorized_host_diskstats_io_ms)vectorized\_host\_diskstats\_io\_ms Captures the cumulative time in milliseconds taken to complete I/O operations. This metric helps in assessing the responsiveness of disk operations under load. This metric is available only when the [`enable_host_metrics`](../properties/cluster-properties/#enable_host_metrics) cluster property is set to `true`. **Type**: gauge **Labels**: - `disk` - `shard` * * * ## [](#vectorized_host_diskstats_io_weighted_ms)vectorized\_host\_diskstats\_io\_weighted\_ms Reports the weighted average time in milliseconds for I/O operations. Weighting factors in the duration and frequency of operations, offering a refined perspective on disk performance. This metric is available only when the [`enable_host_metrics`](../properties/cluster-properties/#enable_host_metrics) cluster property is set to `true`. **Type**: gauge **Labels**: - `disk` - `shard` * * * ## [](#vectorized_host_diskstats_reads)vectorized\_host\_diskstats\_reads Counts the number of read operations executed by the host disk. Tracking read operations is useful for understanding disk usage patterns. This metric is available only when the [`enable_host_metrics`](../properties/cluster-properties/#enable_host_metrics) cluster property is set to `true`. **Type**: gauge **Labels**: - `disk` - `shard` * * * ## [](#vectorized_host_diskstats_reads_merged)vectorized\_host\_diskstats\_reads\_merged Indicates the number of merged read operations, where multiple reads are consolidated to optimize performance. This metric is available only when the [`enable_host_metrics`](../properties/cluster-properties/#enable_host_metrics) cluster property is set to `true`. **Type**: gauge **Labels**: - `disk` - `shard` * * * ## [](#vectorized_host_diskstats_reads_ms)vectorized\_host\_diskstats\_reads\_ms Measures the total time in milliseconds spent on read operations. This metric is useful for evaluating the efficiency of read processes under varying load conditions. This metric is available only when the [`enable_host_metrics`](../properties/cluster-properties/#enable_host_metrics) cluster property is set to `true`. **Type**: gauge **Labels**: - `disk` - `shard` * * * ## [](#vectorized_host_diskstats_sectors_discarded)vectorized\_host\_diskstats\_sectors\_discarded Reports the number of disk sectors discarded during discard operations. Monitoring this value can help in understanding the effectiveness and impact of discard commands on disk space. This metric is available only when the [`enable_host_metrics`](../properties/cluster-properties/#enable_host_metrics) cluster property is set to `true`. **Type**: gauge **Labels**: - `disk` - `shard` * * * ## [](#vectorized_host_diskstats_sectors_read)vectorized\_host\_diskstats\_sectors\_read Indicates the total number of sectors read from the disk. This metric is useful for assessing disk throughput and read performance. This metric is available only when the [`enable_host_metrics`](../properties/cluster-properties/#enable_host_metrics) cluster property is set to `true`. **Type**: gauge **Labels**: - `disk` - `shard` * * * ## [](#vectorized_host_diskstats_sectors_written)vectorized\_host\_diskstats\_sectors\_written Captures the total number of disk sectors written. This metric helps in monitoring the disk’s write activity and overall I/O load. This metric is available only when the [`enable_host_metrics`](../properties/cluster-properties/#enable_host_metrics) cluster property is set to `true`. **Type**: gauge **Labels**: - `disk` - `shard` * * * ## [](#vectorized_host_diskstats_writes)vectorized\_host\_diskstats\_writes Counts the number of write operations performed on the disk. Tracking this metric can be useful for analyzing write-intensive workloads. This metric is available only when the [`enable_host_metrics`](../properties/cluster-properties/#enable_host_metrics) cluster property is set to `true`. **Type**: gauge **Labels**: - `disk` - `shard` * * * ## [](#vectorized_host_diskstats_writes_merged)vectorized\_host\_diskstats\_writes\_merged Reflects the number of merged write operations, where individual writes are combined to optimize disk utilization. This metric is available only when the [`enable_host_metrics`](../properties/cluster-properties/#enable_host_metrics) cluster property is set to `true`. **Type**: gauge **Labels**: - `disk` - `shard` * * * ## [](#vectorized_host_diskstats_writes_ms)vectorized\_host\_diskstats\_writes\_ms Measures the total time in milliseconds taken by write operations. Monitoring this duration helps in evaluating the efficiency of disk writes. This metric is available only when the [`enable_host_metrics`](../properties/cluster-properties/#enable_host_metrics) cluster property is set to `true`. **Type**: gauge **Labels**: - `disk` - `shard` * * * ## [](#vectorized_host_netstat_bytes_received)vectorized\_host\_netstat\_bytes\_received Tracks the total number of bytes received on the host’s network interface. This metric helps in monitoring incoming network traffic for performance and capacity planning. This metric is available only when the [`enable_host_metrics`](../properties/cluster-properties/#enable_host_metrics) cluster property is set to `true`. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_host_netstat_bytes_sent)vectorized\_host\_netstat\_bytes\_sent Reports the total number of bytes sent from the host’s network interface. Monitoring outbound traffic can help in understanding network load and throughput. This metric is available only when the [`enable_host_metrics`](../properties/cluster-properties/#enable_host_metrics) cluster property is set to `true`. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_host_snmp_packets_received)vectorized\_host\_snmp\_packets\_received Indicates the number of SNMP packets received by the host. This metric is useful for tracking network management and monitoring activities. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_host_snmp_packets_sent)vectorized\_host\_snmp\_packets\_sent Counts the SNMP packets sent from the host, providing insight into outgoing SNMP communication which is useful for network monitoring systems. This metric is available only when the [`enable_host_metrics`](../properties/cluster-properties/#enable_host_metrics) cluster property is set to `true`. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_host_snmp_tcp_established)vectorized\_host\_snmp\_tcp\_established Measures the number of established TCP connections related to SNMP activity on the host. It aids in assessing the status and load of TCP-based SNMP communications. This metric is available only when the [`enable_host_metrics`](../properties/cluster-properties/#enable_host_metrics) cluster property is set to `true`. **Type**: gauge **Labels**: - `shard` ## [](#vectorized_httpd_connections_current)vectorized\_httpd\_connections\_current Indicates the current number of open HTTP connections. **Type**: gauge **Labels**: - `service` - `shard` * * * ## [](#vectorized_httpd_connections_total)vectorized\_httpd\_connections\_total Counts the total number of HTTP connections opened. **Type**: counter **Labels**: - `service` - `shard` * * * ## [](#vectorized_httpd_read_errors)vectorized\_httpd\_read\_errors Counts the total number of errors encountered while reading HTTP requests. **Type**: counter **Labels**: - `service` - `shard` * * * ## [](#vectorized_httpd_reply_errors)vectorized\_httpd\_reply\_errors Counts the total number of errors encountered while sending HTTP responses. **Type**: counter **Labels**: - `service` - `shard` * * * ## [](#vectorized_httpd_requests_served)vectorized\_httpd\_requests\_served Counts the total number of HTTP requests served. **Type**: counter **Labels**: - `service` - `shard` * * * ## [](#vectorized_internal_rpc_active_connections)vectorized\_internal\_rpc\_active\_connections Shows the current number of active internal RPC connections. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_internal_rpc_connection_close_errors)vectorized\_internal\_rpc\_connection\_close\_errors Counts the errors that occurred during the shutdown of internal RPC connections. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_internal_rpc_connections_rejected)vectorized\_internal\_rpc\_connections\_rejected Counts the number of internal RPC connection attempts rejected due to open connection limits. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_internal_rpc_connections_rejected_rate_limit)vectorized\_internal\_rpc\_connections\_rejected\_rate\_limit Counts the number of internal RPC connection attempts rejected due to rate limits. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_internal_rpc_connections_wait_rate)vectorized\_internal\_rpc\_connections\_wait\_rate Counts the number of internal RPC connections delayed due to rate limiting. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_internal_rpc_connects)vectorized\_internal\_rpc\_connects Counts the total number of accepted internal RPC connections. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_internal_rpc_consumed_mem_bytes)vectorized\_internal\_rpc\_consumed\_mem\_bytes Reports the memory consumed by internal RPC request processing. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_internal_rpc_corrupted_headers)vectorized\_internal\_rpc\_corrupted\_headers Counts the number of internal RPC requests with corrupted headers. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_internal_rpc_dispatch_handler_latency)vectorized\_internal\_rpc\_dispatch\_handler\_latency Provides a histogram of the latency experienced in internal RPC dispatch handlers. **Type**: histogram * * * ## [](#vectorized_internal_rpc_latency)vectorized\_internal\_rpc\_latency Reports the overall latency for internal RPC service requests. **Type**: histogram * * * ## [](#vectorized_internal_rpc_max_service_mem_bytes)vectorized\_internal\_rpc\_max\_service\_mem\_bytes Reports the maximum memory allocated for internal RPC services. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_internal_rpc_method_not_found_errors)vectorized\_internal\_rpc\_method\_not\_found\_errors Counts the number of internal RPC requests that referenced a non-existent method. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_internal_rpc_received_bytes)vectorized\_internal\_rpc\_received\_bytes Counts the total number of bytes received from internal RPC clients. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_internal_rpc_requests_blocked_memory)vectorized\_internal\_rpc\_requests\_blocked\_memory Counts the number of internal RPC requests blocked due to memory backpressure. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_internal_rpc_requests_completed)vectorized\_internal\_rpc\_requests\_completed Counts the total number of successfully completed internal RPC requests. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_internal_rpc_requests_pending)vectorized\_internal\_rpc\_requests\_pending Reports the number of internal RPC requests currently pending. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_internal_rpc_sent_bytes)vectorized\_internal\_rpc\_sent\_bytes Counts the total number of bytes sent in internal RPC responses. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_internal_rpc_service_errors)vectorized\_internal\_rpc\_service\_errors Counts the total number of service errors encountered by the internal RPC layer. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_io_queue_activations)vectorized\_io\_queue\_activations Counts the number of times the IO queue was activated from an idle state. **Type**: counter **Labels**: - `class` - `iogroup` - `mountpoint` - `shard` - `stream` * * * ## [](#vectorized_io_queue_adjusted_consumption)vectorized\_io\_queue\_adjusted\_consumption Reports the disk capacity units consumed by a class, adjusted for class shares and idling preemption. **Type**: counter **Labels**: - `class` - `iogroup` - `mountpoint` - `shard` - `stream` * * * ## [](#vectorized_io_queue_consumption)vectorized\_io\_queue\_consumption Indicates the total disk capacity units consumed by a class. A per-second increment suggests full utilization. **Type**: counter **Labels**: - `class` - `iogroup` - `mountpoint` - `shard` - `stream` * * * ## [](#vectorized_io_queue_delay)vectorized\_io\_queue\_delay Measures the random delay time experienced in the IO queue. **Type**: gauge **Labels**: - `class` - `iogroup` - `mountpoint` - `shard` * * * ## [](#vectorized_io_queue_disk_queue_length)vectorized\_io\_queue\_disk\_queue\_length Reports the current number of requests waiting in the disk queue. **Type**: gauge **Labels**: - `class` - `iogroup` - `mountpoint` - `shard` * * * ## [](#vectorized_io_queue_flow_ratio)vectorized\_io\_queue\_flow\_ratio Indicates the ratio of the dispatch rate to the completion rate in the IO queue. Values greater than 1.0 may indicate stalls or disk issues. **Type**: gauge **Labels**: - `iogroup` - `mountpoint` - `shard` * * * ## [](#vectorized_io_queue_queue_length)vectorized\_io\_queue\_queue\_length Reports the current number of requests in the general IO queue. **Type**: gauge **Labels**: - `class` - `iogroup` - `mountpoint` - `shard` * * * ## [](#vectorized_io_queue_shares)vectorized\_io\_queue\_shares Indicates the current share allocation for the IO queue. **Type**: gauge **Labels**: - `class` - `iogroup` - `mountpoint` - `shard` * * * ## [](#vectorized_io_queue_starvation_time_sec)vectorized\_io\_queue\_starvation\_time\_sec Reports the total time (in seconds) the IO queue has experienced starvation. **Type**: counter **Labels**: - `class` - `iogroup` - `mountpoint` - `shard` * * * ## [](#vectorized_io_queue_total_bytes)vectorized\_io\_queue\_total\_bytes Reports the total number of bytes processed by the IO queue. **Type**: counter **Labels**: - `class` - `iogroup` - `mountpoint` - `shard` * * * ## [](#vectorized_io_queue_total_delay_sec)vectorized\_io\_queue\_total\_delay\_sec Counts the total delay time (in seconds) experienced within the IO queue. **Type**: counter **Labels**: - `class` - `iogroup` - `mountpoint` - `shard` * * * ## [](#vectorized_io_queue_total_exec_sec)vectorized\_io\_queue\_total\_exec\_sec Reports the total time (in seconds) spent executing IO operations. **Type**: counter **Labels**: - `class` - `iogroup` - `mountpoint` - `shard` * * * ## [](#vectorized_io_queue_total_operations)vectorized\_io\_queue\_total\_operations Counts the total number of operations that have passed through the IO queue. **Type**: counter **Labels**: - `class` - `iogroup` - `mountpoint` - `shard` * * * ## [](#vectorized_io_queue_total_read_bytes)vectorized\_io\_queue\_total\_read\_bytes Reports the total number of bytes read through the IO queue. **Type**: counter **Labels**: - `class` - `iogroup` - `mountpoint` - `shard` * * * ## [](#vectorized_io_queue_total_read_ops)vectorized\_io\_queue\_total\_read\_ops Counts the total number of read operations processed by the IO queue. **Type**: counter **Labels**: - `class` - `iogroup` - `mountpoint` - `shard` * * * ## [](#vectorized_io_queue_total_split_bytes)vectorized\_io\_queue\_total\_split\_bytes Reports the total number of bytes that have been split by IO operations. **Type**: counter **Labels**: - `class` - `iogroup` - `mountpoint` - `shard` * * * ## [](#vectorized_io_queue_total_split_ops)vectorized\_io\_queue\_total\_split\_ops Counts the total number of IO requests that were split. **Type**: counter **Labels**: - `class` - `iogroup` - `mountpoint` - `shard` * * * ## [](#vectorized_io_queue_total_write_bytes)vectorized\_io\_queue\_total\_write\_bytes Reports the total number of bytes written through the IO queue. **Type**: counter **Labels**: - `class` - `iogroup` - `mountpoint` - `shard` * * * ## [](#vectorized_io_queue_total_write_ops)vectorized\_io\_queue\_total\_write\_ops Counts the total number of write operations processed by the IO queue. **Type**: counter **Labels**: - `class` - `iogroup` - `mountpoint` - `shard` * * * ## [](#vectorized_kafka_batch_size)vectorized\_kafka\_batch\_size Provides a histogram of the batch sizes across all topics at the Kafka layer. **Type**: histogram * * * ## [](#vectorized_kafka_fetch_pid_delay_seconds_total)vectorized\_kafka\_fetch\_pid\_delay\_seconds\_total Reports the cumulative fetch delay (in seconds) set by the PID controller. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_kafka_fetch_pid_error_total)vectorized\_kafka\_fetch\_pid\_error\_total Reports the cumulative error in the fetch PID controller. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_kafka_fetch_read_distribution)vectorized\_kafka\_fetch\_read\_distribution Provides a histogram distribution of read path timings at the Kafka layer. **Type**: histogram * * * ## [](#vectorized_kafka_fetch_sessions_cache_mem_usage_bytes)vectorized\_kafka\_fetch\_sessions\_cache\_mem\_usage\_bytes Reports the memory usage (in bytes) of the Kafka fetch sessions cache. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_kafka_fetch_sessions_cache_sessions_count)vectorized\_kafka\_fetch\_sessions\_cache\_sessions\_count Indicates the total number of active Kafka fetch sessions. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_kafka_group_offset)vectorized\_kafka\_group\_offset Displays the offset for a given group, partition, and topic. **Type**: gauge **Labels**: - `group` - `partition` - `shard` - `topic` * * * ## [](#vectorized_kafka_handler_latency_microseconds)vectorized\_kafka\_handler\_latency\_microseconds Provides a histogram of Kafka request latencies (in microseconds). **Type**: histogram * * * ## [](#vectorized_kafka_handler_received_bytes_total)vectorized\_kafka\_handler\_received\_bytes\_total Counts the total number of bytes received by the Kafka request handler. **Type**: counter **Labels**: - `handler` - `shard` * * * ## [](#vectorized_kafka_handler_requests_completed_total)vectorized\_kafka\_handler\_requests\_completed\_total Counts the total number of successfully completed Kafka requests. **Type**: counter **Labels**: - `handler` - `shard` * * * ## [](#vectorized_kafka_handler_requests_errored_total)vectorized\_kafka\_handler\_requests\_errored\_total Counts the total number of Kafka requests that resulted in an error. **Type**: counter **Labels**: - `handler` - `shard` * * * ## [](#vectorized_kafka_handler_requests_in_progress_total)vectorized\_kafka\_handler\_requests\_in\_progress\_total Reports the current number of Kafka requests in progress. **Type**: counter **Labels**: - `handler` - `shard` * * * ## [](#vectorized_kafka_handler_sent_bytes_total)vectorized\_kafka\_handler\_sent\_bytes\_total Counts the total number of bytes sent in Kafka responses. **Type**: counter **Labels**: - `handler` - `shard` * * * ## [](#vectorized_kafka_latency_fetch_latency_us)vectorized\_kafka\_latency\_fetch\_latency\_us Provides a histogram of fetch latencies (in microseconds) at the Kafka layer. **Type**: histogram * * * ## [](#vectorized_kafka_latency_produce_latency_us)vectorized\_kafka\_latency\_produce\_latency\_us Provides a histogram of produce latencies (in microseconds) at the Kafka layer. **Type**: histogram * * * ## [](#vectorized_kafka_produced_bytes)vectorized\_kafka\_produced\_bytes Counts the total number of bytes produced, segmented by compression type. **Type**: counter **Labels**: - `compression_type` - `shard` * * * ## [](#vectorized_kafka_quotas_client_quota_throttle_time)vectorized\_kafka\_quotas\_client\_quota\_throttle\_time Provides a histogram of client quota throttling delays (in seconds) per rule and quota type based on [client throughput limits](../../manage/cluster-maintenance/manage-throughput/#client-throughput-limits). **Type**: histogram * * * ## [](#vectorized_kafka_quotas_client_quota_throughput)vectorized\_kafka\_quotas\_client\_quota\_throughput Provides a histogram of client quota throughput per rule and quota type. **Type**: histogram * * * ## [](#vectorized_kafka_quotas_quota_effective)vectorized\_kafka\_quotas\_quota\_effective Reports the currently effective quota in bytes per second. **Type**: counter **Labels**: - `direction` - `shard` * * * ## [](#vectorized_kafka_quotas_throttle_time)vectorized\_kafka\_quotas\_throttle\_time Provides a histogram of throttling times (in seconds) based on [broker-wide throughput limits](../../manage/cluster-maintenance/manage-throughput/#broker-wide-throughput-limits) across the Kafka layer. **Type**: histogram * * * ## [](#vectorized_kafka_quotas_traffic_egress)vectorized\_kafka\_quotas\_traffic\_egress Counts the total amount of Kafka traffic (in bytes) sent to clients. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_kafka_quotas_traffic_intake)vectorized\_kafka\_quotas\_traffic\_intake Counts the total amount of Kafka traffic (in bytes) received from clients. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_kafka_rpc_active_connections)vectorized\_kafka\_rpc\_active\_connections Reports the number of active Kafka RPC connections. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_kafka_rpc_connection_close_errors)vectorized\_kafka\_rpc\_connection\_close\_errors Counts the number of errors encountered while closing Kafka RPC connections. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_kafka_rpc_connections_rejected)vectorized\_kafka\_rpc\_connections\_rejected Counts the number of Kafka RPC connection attempts rejected due to connection limits. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_kafka_rpc_connections_rejected_rate_limit)vectorized\_kafka\_rpc\_connections\_rejected\_rate\_limit Counts the number of Kafka RPC connection attempts rejected due to rate limits. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_kafka_rpc_connections_wait_rate)vectorized\_kafka\_rpc\_connections\_wait\_rate Counts the number of Kafka RPC connections delayed due to rate limiting. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_kafka_rpc_connects)vectorized\_kafka\_rpc\_connects Counts the total number of accepted Kafka RPC connections. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_kafka_rpc_consumed_mem_bytes)vectorized\_kafka\_rpc\_consumed\_mem\_bytes Reports the memory (in bytes) consumed by Kafka RPC request processing. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_kafka_rpc_corrupted_headers)vectorized\_kafka\_rpc\_corrupted\_headers Counts the number of Kafka RPC requests with corrupted headers. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_kafka_rpc_dispatch_handler_latency)vectorized\_kafka\_rpc\_dispatch\_handler\_latency Provides a histogram of latencies (in seconds) in Kafka RPC dispatch handlers. **Type**: histogram * * * ## [](#vectorized_kafka_rpc_fetch_avail_mem_bytes)vectorized\_kafka\_rpc\_fetch\_avail\_mem\_bytes Reports the available memory for processing Kafka RPC fetch requests. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_kafka_rpc_max_service_mem_bytes)vectorized\_kafka\_rpc\_max\_service\_mem\_bytes Reports the maximum memory allocated for Kafka RPC services. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_kafka_rpc_method_not_found_errors)vectorized\_kafka\_rpc\_method\_not\_found\_errors Counts the number of Kafka RPC requests for methods that do not exist. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_kafka_rpc_produce_bad_create_time)vectorized\_kafka\_rpc\_produce\_bad\_create\_time An incrementing counter for the number of times a producer created a message with a timestamp skewed from the broker’s date and time. This metric is related to the following properties: - [`log_message_timestamp_alert_before_ms`](../properties/cluster-properties/#log_message_timestamp_alert_before_ms): Increment this gauge when the create\_timestamp on a message is too far in the past as compared to the broker’s time. - [`log_message_timestamp_alert_after_ms`](../properties/cluster-properties/#log_message_timestamp_alert_after_ms): Increment this gauge when the create\_timestamp on a message is too far in the future as compared to the broker’s time. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_kafka_rpc_received_bytes)vectorized\_kafka\_rpc\_received\_bytes Counts the total number of bytes received by the Kafka RPC layer. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_kafka_rpc_requests_blocked_memory)vectorized\_kafka\_rpc\_requests\_blocked\_memory Counts the number of Kafka RPC requests blocked due to insufficient memory. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_kafka_rpc_requests_completed)vectorized\_kafka\_rpc\_requests\_completed Counts the total number of successfully completed Kafka RPC requests. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_kafka_rpc_requests_pending)vectorized\_kafka\_rpc\_requests\_pending Reports the number of Kafka RPC requests that are currently pending. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_kafka_rpc_sasl_session_expiration_total)vectorized\_kafka\_rpc\_sasl\_session\_expiration\_total Counts the total number of SASL session expirations in Kafka RPC. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_kafka_rpc_sasl_session_reauth_attempts_total)vectorized\_kafka\_rpc\_sasl\_session\_reauth\_attempts\_total Counts the total number of SASL reauthentication attempts in Kafka RPC. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_kafka_rpc_sasl_session_revoked_total)vectorized\_kafka\_rpc\_sasl\_session\_revoked\_total Counts the total number of revoked SASL sessions in Kafka RPC. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_kafka_rpc_sent_bytes)vectorized\_kafka\_rpc\_sent\_bytes Counts the total number of bytes sent by the Kafka RPC layer. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_kafka_rpc_service_errors)vectorized\_kafka\_rpc\_service\_errors Counts the total number of service errors encountered in Kafka RPC. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_kafka_schema_id_cache_batches_decompressed)vectorized\_kafka\_schema\_id\_cache\_batches\_decompressed Counts the number of batches decompressed for server-side schema ID validation. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_kafka_schema_id_cache_hits)vectorized\_kafka\_schema\_id\_cache\_hits Counts the number of cache hits in the server-side schema ID validation cache. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_kafka_schema_id_cache_misses)vectorized\_kafka\_schema\_id\_cache\_misses Counts the number of cache misses in the server-side schema ID validation cache. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_leader_balancer_leader_transfer_error)vectorized\_leader\_balancer\_leader\_transfer\_error Counts the number of errors encountered during leader transfer attempts. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_leader_balancer_leader_transfer_no_improvement)vectorized\_leader\_balancer\_leader\_transfer\_no\_improvement Counts the number of leader transfer attempts that did not result in improved balance. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_leader_balancer_leader_transfer_succeeded)vectorized\_leader\_balancer\_leader\_transfer\_succeeded Counts the total number of successful leader transfers. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_leader_balancer_leader_transfer_timeout)vectorized\_leader\_balancer\_leader\_transfer\_timeout Counts the number of leader transfer attempts that timed out. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_memory_allocated_memory)vectorized\_memory\_allocated\_memory Reports the total amount of memory allocated (in bytes) by the process. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_memory_available_memory)vectorized\_memory\_available\_memory Reports the total amount of potentially available memory (free plus reclaimable) per shard. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_memory_available_memory_low_water_mark)vectorized\_memory\_available\_memory\_low\_water\_mark Reports the low-water mark for available memory since process start. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_memory_cross_cpu_free_operations)vectorized\_memory\_cross\_cpu\_free\_operations Counts the number of cross-CPU free operations executed. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_memory_free_memory)vectorized\_memory\_free\_memory Reports the current free memory (in bytes) per shard. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_memory_free_operations)vectorized\_memory\_free\_operations Counts the total number of free operations performed. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_memory_malloc_failed)vectorized\_memory\_malloc\_failed Counts the total number of failed memory allocation attempts. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_memory_malloc_live_objects)vectorized\_memory\_malloc\_live\_objects Reports the current number of live objects allocated via malloc. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_memory_malloc_operations)vectorized\_memory\_malloc\_operations Counts the total number of malloc operations performed. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_memory_reclaims_operations)vectorized\_memory\_reclaims\_operations Counts the total number of memory reclaim operations performed. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_memory_total_memory)vectorized\_memory\_total\_memory Reports the total memory size (in bytes) available per shard. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_network_bytes_received)vectorized\_network\_bytes\_received Counts the total number of bytes received over network sockets. **Type**: counter **Labels**: - `group` - `shard` * * * ## [](#vectorized_network_bytes_sent)vectorized\_network\_bytes\_sent Counts the total number of bytes sent over network sockets. **Type**: counter **Labels**: - `group` - `shard` * * * ## [](#vectorized_node_status_rpcs_received)vectorized\_node\_status\_rpcs\_received Reports the number of broker status RPCs received by this broker. **Type**: gauge * * * ## [](#vectorized_node_status_rpcs_sent)vectorized\_node\_status\_rpcs\_sent Reports the number of broker status RPCs sent by this broker. **Type**: gauge * * * ## [](#vectorized_node_status_rpcs_timed_out)vectorized\_node\_status\_rpcs\_timed\_out Reports the number of broker status RPCs that have timed out. **Type**: gauge * * * ## [](#vectorized_ntp_archiver_compacted_replaced_bytes)vectorized\_ntp\_archiver\_compacted\_replaced\_bytes Number of bytes removed from object storage by compaction operations. This is tracked on a per-topic and per-partition basis. This metric resets every time partition leadership changes. It tracks whether or not compaction is performing operations on object storage. The `namespace` label supports the following options for this metric: - `kafka` - User topics - `kafka_internal` - Internal Kafka topic, such as consumer groups - `redpanda` - Redpanda-only internal data **Type**: gauge **Labels**: - `namespace=("kafka" | "kafka_internal" | "redpanda")` - `topic` - `partition` * * * ### [](#vectorized_ntp_archiver_missing)vectorized\_ntp\_archiver\_missing Counts the number of missing offsets due to gaps. This metric is tracked on a per-topic and per-partition basis. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_ntp_archiver_pending)vectorized\_ntp\_archiver\_pending Reports the difference between the last committed offset and the last offset uploaded to Tiered Storage for each partition. A value of zero for this metric indicates that all data for a partition is uploaded to Tiered Storage. This metric is impacted by the [`cloud_storage_segment_max_upload_interval_sec`](../properties/object-storage-properties/#cloud_storage_segment_max_upload_interval_sec) property. If this interval is set to 5 minutes, the archiver uploads committed segments to Tiered Storage every 5 minutes or less. If this metric continues growing for longer than the configured interval, it can indicate a potential network issue with the upload path for that partition. The `namespace` label supports the following options for this metric: - `kafka` - User topics - `kafka_internal` - Internal Kafka topic, such as consumer groups - `redpanda` - Redpanda-only internal data **Type**: gauge **Labels**: - `namespace=("kafka" | "kafka_internal" | "redpanda")` - `topic` - `partition` * * * ### [](#vectorized_ntp_archiver_uploaded)vectorized\_ntp\_archiver\_uploaded Counts the number of offsets uploaded to object storage. This metric is tracked on a per-topic and per-partition basis. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ### [](#vectorized_ntp_archiver_uploaded_bytes)vectorized\_ntp\_archiver\_uploaded\_bytes Counts the number of bytes uploaded to object storage. This metric is tracked on a per-topic and per-partition basis. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_pandaproxy_request_errors_total)vectorized\_pandaproxy\_request\_errors\_total Counts the total number of REST proxy server errors, segmented by operation and status. **Type**: counter **Labels**: - `operation` - `shard` - `status` * * * ## [](#vectorized_pandaproxy_request_latency)vectorized\_pandaproxy\_request\_latency Provides a histogram of REST proxy request latencies. **Type**: histogram * * * ## [](#vectorized_raft_append_entries_buffer_flushes)vectorized\_raft\_append\_entries\_buffer\_flushes Counts the number of flushes performed on the append entries buffer. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_raft_buffered_protocol_buffered_bytes)vectorized\_raft\_buffered\_protocol\_buffered\_bytes Reports the total size (in bytes) of append entries requests currently buffered. **Type**: gauge **Labels**: - `shard` - `target_node_id` * * * ## [](#vectorized_raft_buffered_protocol_buffered_requests)vectorized\_raft\_buffered\_protocol\_buffered\_requests Counts the number of append entries requests currently buffered. **Type**: gauge **Labels**: - `shard` - `target_node_id` * * * ## [](#vectorized_raft_buffered_protocol_inflight_requests)vectorized\_raft\_buffered\_protocol\_inflight\_requests Counts the number of append entries requests sent to a target broker that are awaiting responses. **Type**: gauge **Labels**: - `shard` - `target_node_id` * * * ## [](#vectorized_raft_configuration_change_in_progress)vectorized\_raft\_configuration\_change\_in\_progress Indicates if the current raft group configuration is in a joint state (i.e. undergoing change). **Type**: gauge **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_raft_done_replicate_requests)vectorized\_raft\_done\_replicate\_requests Counts the total number of replicate requests that have completed. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_raft_full_heartbeat_requests)vectorized\_raft\_full\_heartbeat\_requests Counts the number of full heartbeat messages sent by the raft leader. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_raft_group_configuration_updates)vectorized\_raft\_group\_configuration\_updates Counts the total number of raft group configuration updates. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_raft_group_count)vectorized\_raft\_group\_count Reports the total number of raft groups present. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_raft_heartbeat_requests_errors)vectorized\_raft\_heartbeat\_requests\_errors Counts the number of failed heartbeat requests within a raft group. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_raft_leader_for)vectorized\_raft\_leader\_for Indicates the number of raft groups for which this broker is the leader. **Type**: gauge **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_raft_leadership_changes)vectorized\_raft\_leadership\_changes Counts the number of leader elections won by this broker. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_raft_learners_gap_bytes)vectorized\_raft\_learners\_gap\_bytes Reports the total number of bytes that must be sent to learners to catch up. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_raft_lightweight_heartbeat_requests)vectorized\_raft\_lightweight\_heartbeat\_requests Counts the number of lightweight heartbeat messages sent by the raft leader. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_raft_log_flushes)vectorized\_raft\_log\_flushes Counts the number of log flush operations performed. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_raft_log_truncations)vectorized\_raft\_log\_truncations Counts the number of log truncations performed. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_raft_offset_translator_inconsistency_errors)vectorized\_raft\_offset\_translator\_inconsistency\_errors Counts the number of append entries requests that failed the offset translator consistency check. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_raft_received_append_requests)vectorized\_raft\_received\_append\_requests Counts the total number of append requests received. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_raft_received_vote_requests)vectorized\_raft\_received\_vote\_requests Counts the total number of vote requests received. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_raft_recovery_offsets_pending)vectorized\_raft\_recovery\_offsets\_pending Reports the sum of offsets that need recovery on this broker. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_raft_recovery_partition_movement_assigned_bandwidth)vectorized\_raft\_recovery\_partition\_movement\_assigned\_bandwidth Reports the bandwidth (bytes/sec) assigned for partition movement in the last tick. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_raft_recovery_partition_movement_available_bandwidth)vectorized\_raft\_recovery\_partition\_movement\_available\_bandwidth Reports the available bandwidth (bytes/sec) for partition movement. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_raft_recovery_partitions_active)vectorized\_raft\_recovery\_partitions\_active Counts the number of partition replicas currently in recovery on this broker. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_raft_recovery_partitions_to_recover)vectorized\_raft\_recovery\_partitions\_to\_recover Counts the number of partition replicas that still require recovery on this broker. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_raft_recovery_requests)vectorized\_raft\_recovery\_requests Counts the total number of recovery requests issued. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_raft_recovery_requests_errors)vectorized\_raft\_recovery\_requests\_errors Counts the total number of failed recovery requests. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_raft_replicate_ack_all_requests)vectorized\_raft\_replicate\_ack\_all\_requests Counts replicate requests that required quorum acknowledgments with an explicit flush. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_raft_replicate_ack_all_requests_no_flush)vectorized\_raft\_replicate\_ack\_all\_requests\_no\_flush Counts replicate requests that required quorum acknowledgments but did not use an explicit flush. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_raft_replicate_ack_leader_requests)vectorized\_raft\_replicate\_ack\_leader\_requests Counts replicate requests that acknowledged only the leader. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_raft_replicate_ack_none_requests)vectorized\_raft\_replicate\_ack\_none\_requests Counts replicate requests that did not require any acknowledgment. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_raft_replicate_batch_flush_requests)vectorized\_raft\_replicate\_batch\_flush\_requests Counts the number of batch flush operations in replicate requests. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_raft_replicate_request_errors)vectorized\_raft\_replicate\_request\_errors Counts the number of failed replicate requests. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_raft_sent_vote_requests)vectorized\_raft\_sent\_vote\_requests Counts the total number of vote requests sent. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_reactor_abandoned_failed_futures)vectorized\_reactor\_abandoned\_failed\_futures Counts the total number of futures that were abandoned while still containing an exception. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_reactor_aio_bytes_read)vectorized\_reactor\_aio\_bytes\_read Counts the total number of bytes read via asynchronous IO. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_reactor_aio_bytes_write)vectorized\_reactor\_aio\_bytes\_write Counts the total number of bytes written via asynchronous IO. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_reactor_aio_errors)vectorized\_reactor\_aio\_errors Counts the total number of asynchronous IO errors. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_reactor_aio_outsizes)vectorized\_reactor\_aio\_outsizes Counts the total number of AIO operations that exceeded configured IO limits. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_reactor_aio_reads)vectorized\_reactor\_aio\_reads Counts the total number of AIO read operations. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_reactor_aio_writes)vectorized\_reactor\_aio\_writes Counts the total number of AIO write operations. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_reactor_awake_time_ms_total)vectorized\_reactor\_awake\_time\_ms\_total Reports the total wall-clock time (in milliseconds) the reactor was awake. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_reactor_cpp_exceptions)vectorized\_reactor\_cpp\_exceptions Counts the total number of C++ exceptions thrown by the reactor. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_reactor_cpu_busy_ms)vectorized\_reactor\_cpu\_busy\_ms Reports the total CPU busy time (in milliseconds) for the reactor thread. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_reactor_cpu_steal_time_ms)vectorized\_reactor\_cpu\_steal\_time\_ms Reports the total amount of time (in milliseconds) the reactor was runnable but was not scheduled (steal time). **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_reactor_cpu_used_time_ms)vectorized\_reactor\_cpu\_used\_time\_ms Reports the total CPU time used by the reactor thread (from CLOCK\_THREAD\_CPUTIME). **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_reactor_fstream_read_bytes)vectorized\_reactor\_fstream\_read\_bytes Counts the total number of bytes read from disk file streams. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_reactor_fstream_read_bytes_blocked)vectorized\_reactor\_fstream\_read\_bytes\_blocked Counts the number of bytes read from disk that had to block due to insufficient read-ahead buffers. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_reactor_fstream_reads)vectorized\_reactor\_fstream\_reads Counts the total number of read operations from disk file streams. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_reactor_fstream_reads_ahead_bytes_discarded)vectorized\_reactor\_fstream\_reads\_ahead\_bytes\_discarded Counts the number of buffered bytes that were discarded after being read ahead but not used. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_reactor_fstream_reads_aheads_discarded)vectorized\_reactor\_fstream\_reads\_aheads\_discarded Counts the number of times that pre-read buffers were discarded due to being unnecessary. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_reactor_fstream_reads_blocked)vectorized\_reactor\_fstream\_reads\_blocked Counts the number of times a disk read had to block because pre-read buffers were insufficient. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_reactor_fsyncs)vectorized\_reactor\_fsyncs Counts the total number of fsync operations performed by the reactor. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_reactor_io_threaded_fallbacks)vectorized\_reactor\_io\_threaded\_fallbacks Counts the number of times the reactor fell back to an IO-threaded path. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_reactor_logging_failures)vectorized\_reactor\_logging\_failures Counts the total number of logging failures encountered by the reactor. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_reactor_polls)vectorized\_reactor\_polls Counts the total number of poll cycles executed by the reactor. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_reactor_sleep_time_ms_total)vectorized\_reactor\_sleep\_time\_ms\_total Reports the total wall-clock sleep time (in milliseconds) of the reactor. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_reactor_stalls)vectorized\_reactor\_stalls Provides a histogram of durations for which the reactor experienced stalls. **Type**: histogram * * * ## [](#vectorized_reactor_tasks_pending)vectorized\_reactor\_tasks\_pending Reports the current number of pending tasks in the reactor’s task queue. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_reactor_tasks_processed)vectorized\_reactor\_tasks\_processed Counts the total number of tasks processed by the reactor. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_reactor_timers_pending)vectorized\_reactor\_timers\_pending Reports the current number of pending timer tasks in the reactor. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_reactor_utilization)vectorized\_reactor\_utilization Indicates the CPU utilization of the reactor thread. Shows the true utilization of the CPU by a Redpanda process. This metric has per-broker and per-shard granularity. If a shard (CPU core) is at 100% utilization for a continuous period of real-time processing, for example more than a few seconds, you will likely observe high latency for partitions assigned to that shard. Use topic-aware [intra-broker partition balancing](../../manage/cluster-maintenance/cluster-balancing/#intra-broker-partition-balancing) to balance partition assignments and alleviate load on individual shards. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_rest_proxy_inflight_requests_memory_usage_ratio)vectorized\_rest\_proxy\_inflight\_requests\_memory\_usage\_ratio Reports the memory usage ratio for in-flight REST proxy requests. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_rest_proxy_inflight_requests_usage_ratio)vectorized\_rest\_proxy\_inflight\_requests\_usage\_ratio Reports the overall usage ratio of in-flight REST proxy requests. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_rest_proxy_queued_requests_memory_blocked)vectorized\_rest\_proxy\_queued\_requests\_memory\_blocked Reports the number of REST proxy requests that are queued due to memory limitations. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_rpc_client_active_connections)vectorized\_rpc\_client\_active\_connections Indicates the number of currently active RPC client connections. **Type**: gauge **Labels**: - `connection_cache_label` - `shard` - `target` * * * ## [](#vectorized_rpc_client_client_correlation_errors)vectorized\_rpc\_client\_client\_correlation\_errors Counts errors in client correlation IDs within RPC responses. **Type**: counter **Labels**: - `connection_cache_label` - `shard` - `target` * * * ## [](#vectorized_rpc_client_connection_errors)vectorized\_rpc\_client\_connection\_errors Counts the number of connection errors encountered by the RPC client. **Type**: counter **Labels**: - `connection_cache_label` - `shard` - `target` * * * ## [](#vectorized_rpc_client_connects)vectorized\_rpc\_client\_connects Counts the total number of RPC client connection attempts. **Type**: counter **Labels**: - `connection_cache_label` - `shard` - `target` * * * ## [](#vectorized_rpc_client_corrupted_headers)vectorized\_rpc\_client\_corrupted\_headers Counts the number of RPC responses received with corrupted headers. **Type**: counter **Labels**: - `connection_cache_label` - `shard` - `target` * * * ## [](#vectorized_rpc_client_in_bytes)vectorized\_rpc\_client\_in\_bytes Reports the total number of bytes received by the RPC client. **Type**: counter **Labels**: - `connection_cache_label` - `shard` - `target` * * * ## [](#vectorized_rpc_client_out_bytes)vectorized\_rpc\_client\_out\_bytes Reports the total number of bytes sent (including headers) by the RPC client. **Type**: counter **Labels**: - `connection_cache_label` - `shard` - `target` * * * ## [](#vectorized_rpc_client_read_dispatch_errors)vectorized\_rpc\_client\_read\_dispatch\_errors Counts the number of errors encountered while dispatching RPC responses. **Type**: counter **Labels**: - `connection_cache_label` - `shard` - `target` * * * ## [](#vectorized_rpc_client_request_errors)vectorized\_rpc\_client\_request\_errors Counts the total number of request errors encountered by the RPC client. **Type**: counter **Labels**: - `connection_cache_label` - `shard` - `target` * * * ## [](#vectorized_rpc_client_request_timeouts)vectorized\_rpc\_client\_request\_timeouts Counts the number of RPC client request timeouts. **Type**: counter **Labels**: - `connection_cache_label` - `shard` - `target` * * * ## [](#vectorized_rpc_client_requests)vectorized\_rpc\_client\_requests Counts the total number of RPC client requests made. **Type**: counter **Labels**: - `connection_cache_label` - `shard` - `target` * * * ## [](#vectorized_rpc_client_requests_blocked_memory)vectorized\_rpc\_client\_requests\_blocked\_memory Counts the number of RPC client requests that were blocked due to insufficient memory. **Type**: counter **Labels**: - `connection_cache_label` - `shard` - `target` * * * ## [](#vectorized_rpc_client_requests_pending)vectorized\_rpc\_client\_requests\_pending Reports the current number of pending RPC client requests. **Type**: gauge **Labels**: - `connection_cache_label` - `shard` - `target` * * * ## [](#vectorized_rpc_client_server_correlation_errors)vectorized\_rpc\_client\_server\_correlation\_errors Counts the number of RPC responses with mismatched server correlation IDs. **Type**: counter **Labels**: - `connection_cache_label` - `shard` - `target` * * * ## [](#vectorized_scheduler_queue_length)vectorized\_scheduler\_queue\_length Reports the current size of the scheduler queue (in tasks), indicating backlog. **Type**: gauge **Labels**: - `group` - `shard` * * * ## [](#vectorized_scheduler_runtime_ms)vectorized\_scheduler\_runtime\_ms Reports the accumulated runtime (in milliseconds) of a scheduler queue. A rate of 1000ms per second suggests full utilization. **Type**: counter **Labels**: - `group` - `shard` * * * ## [](#vectorized_scheduler_shares)vectorized\_scheduler\_shares Indicates the share allocation for a scheduler queue. **Type**: gauge **Labels**: - `group` - `shard` * * * ## [](#vectorized_scheduler_starvetime_ms)vectorized\_scheduler\_starvetime\_ms Reports the accumulated starvation time (in milliseconds) for a scheduler queue. **Type**: counter **Labels**: - `group` - `shard` * * * ## [](#vectorized_scheduler_tasks_processed)vectorized\_scheduler\_tasks\_processed Counts the total number of tasks processed by the scheduler. **Type**: counter **Labels**: - `group` - `shard` * * * ## [](#vectorized_scheduler_time_spent_on_task_quota_violations_ms)vectorized\_scheduler\_time\_spent\_on\_task\_quota\_violations\_ms Reports the total time (in milliseconds) that the scheduler has violated task quotas. **Type**: counter **Labels**: - `group` - `shard` * * * ## [](#vectorized_scheduler_waittime_ms)vectorized\_scheduler\_waittime\_ms Reports the accumulated wait time (in milliseconds) for a scheduler queue. **Type**: counter **Labels**: - `group` - `shard` * * * ## [](#vectorized_schema_registry_cache_schema_count)vectorized\_schema\_registry\_cache\_schema\_count Reports the total number of schemas stored in the schema registry cache. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_schema_registry_cache_schema_memory_bytes)vectorized\_schema\_registry\_cache\_schema\_memory\_bytes Reports the memory usage (in bytes) of schemas stored in the registry. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_schema_registry_cache_subject_count)vectorized\_schema\_registry\_cache\_subject\_count Reports the total number of subjects in the schema registry. **Type**: gauge **Labels**: - `deleted` - `shard` * * * ## [](#vectorized_schema_registry_cache_subject_version_count)vectorized\_schema\_registry\_cache\_subject\_version\_count Reports the number of versions for a given subject in the schema registry. **Type**: gauge **Labels**: - `deleted` - `shard` - `subject` * * * ## [](#vectorized_schema_registry_inflight_requests_memory_usage_ratio)vectorized\_schema\_registry\_inflight\_requests\_memory\_usage\_ratio Reports the memory usage ratio for in-flight schema registry requests. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_schema_registry_inflight_requests_usage_ratio)vectorized\_schema\_registry\_inflight\_requests\_usage\_ratio Reports the usage ratio for in-flight schema registry requests. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_schema_registry_queued_requests_memory_blocked)vectorized\_schema\_registry\_queued\_requests\_memory\_blocked Reports the number of schema registry requests queued due to memory constraints. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_security_audit_buffer_usage_ratio)vectorized\_security\_audit\_buffer\_usage\_ratio Reports the usage ratio of the audit event buffer. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_security_audit_client_buffer_usage_ratio)vectorized\_security\_audit\_client\_buffer\_usage\_ratio Reports the usage ratio of the audit client’s send buffer. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_security_audit_errors_total)vectorized\_security\_audit\_errors\_total Counts the total number of errors encountered while creating or publishing audit log entries. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_security_audit_last_event_timestamp_seconds)vectorized\_security\_audit\_last\_event\_timestamp\_seconds Reports the timestamp (in seconds since the epoch) of the last successful audit log event. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_space_management_available_reclaimable_bytes)vectorized\_space\_management\_available\_reclaimable\_bytes Reports the total amount of reclaimable data available under space management. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_space_management_disk_usage_bytes)vectorized\_space\_management\_disk\_usage\_bytes Reports the total disk usage (in bytes) managed by space management. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_space_management_local_retention_reclaimable_bytes)vectorized\_space\_management\_local\_retention\_reclaimable\_bytes Reports the amount of data above the local retention target that is reclaimable. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_space_management_reclaim_active_segment_bytes)vectorized\_space\_management\_reclaim\_active\_segment\_bytes Estimates the amount of data above the active segment that can be reclaimed. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_space_management_reclaim_estimate_bytes)vectorized\_space\_management\_reclaim\_estimate\_bytes Provides an estimate of the data (in bytes) to be reclaimed in the last space management schedule. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_space_management_reclaim_local_bytes)vectorized\_space\_management\_reclaim\_local\_bytes Estimates the amount of data above local retention that will be reclaimed. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_space_management_reclaim_low_hinted_bytes)vectorized\_space\_management\_reclaim\_low\_hinted\_bytes Estimates the amount of data above the low-space threshold (with hints) to be reclaimed. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_space_management_reclaim_low_non_hinted_bytes)vectorized\_space\_management\_reclaim\_low\_non\_hinted\_bytes Estimates the amount of data above the low-space threshold (without hints) to be reclaimed. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_space_management_retention_reclaimable_bytes)vectorized\_space\_management\_retention\_reclaimable\_bytes Reports the total reclaimable data as per the standard retention policy. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_space_management_target_disk_size_bytes)vectorized\_space\_management\_target\_disk\_size\_bytes Specifies the target maximum disk usage (in bytes) for space management. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_space_management_target_excess_bytes)vectorized\_space\_management\_target\_excess\_bytes Reports the amount of disk usage exceeding the target threshold. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_stall_detector_reported)vectorized\_stall\_detector\_reported Counts the total number of stalls reported (see detailed traces for context). **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_storage_compaction_backlog_controller_backlog_size)vectorized\_storage\_compaction\_backlog\_controller\_backlog\_size Reports the current backlog size for the storage compaction controller. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_storage_compaction_backlog_controller_error)vectorized\_storage\_compaction\_backlog\_controller\_error Reports the error (difference between target and current backlog) in the compaction controller. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_storage_compaction_backlog_controller_shares)vectorized\_storage\_compaction\_backlog\_controller\_shares Reports the number of shares output by the storage compaction controller. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_storage_kvstore_cached_bytes)vectorized\_storage\_kvstore\_cached\_bytes Reports the size (in bytes) of the in-memory key-value store cache. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_storage_kvstore_entries_fetched)vectorized\_storage\_kvstore\_entries\_fetched Counts the number of key-value entries fetched from the store. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_storage_kvstore_entries_removed)vectorized\_storage\_kvstore\_entries\_removed Counts the number of key-value entries removed from the store. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_storage_kvstore_entries_written)vectorized\_storage\_kvstore\_entries\_written Counts the number of key-value entries written to the store. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_storage_kvstore_key_count)vectorized\_storage\_kvstore\_key\_count Reports the total number of keys currently stored in the key-value store. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_storage_kvstore_segments_rolled)vectorized\_storage\_kvstore\_segments\_rolled Counts the number of segments that have been rolled in the key-value store. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_storage_log_batch_parse_errors)vectorized\_storage\_log\_batch\_parse\_errors Counts the number of errors encountered while parsing log batches. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_storage_log_batch_write_errors)vectorized\_storage\_log\_batch\_write\_errors Counts the number of errors encountered while writing log batches. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_storage_log_batches_read)vectorized\_storage\_log\_batches\_read Counts the total number of log batches read. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_storage_log_batches_written)vectorized\_storage\_log\_batches\_written Counts the total number of log batches written. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_storage_log_bytes_prefix_truncated)vectorized\_storage\_log\_bytes\_prefix\_truncated Counts the number of bytes removed due to prefix truncation of log segments. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_storage_log_cache_hits)vectorized\_storage\_log\_cache\_hits Counts the number of cache hits in the log reader cache. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_storage_log_cache_misses)vectorized\_storage\_log\_cache\_misses Counts the number of cache misses in the log reader cache. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_storage_log_cached_batches_read)vectorized\_storage\_log\_cached\_batches\_read Counts the total number of log batches read from cache. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_storage_log_cached_read_bytes)vectorized\_storage\_log\_cached\_read\_bytes Counts the total number of bytes read from the log cache. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_storage_log_chunked_compaction_runs)vectorized\_storage\_log\_chunked\_compaction\_runs Counts the number of times chunked compaction has been executed, which can also indicate failures in building key–offset maps. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_storage_log_cleanly_compacted_segment)vectorized\_storage\_log\_cleanly\_compacted\_segment Counts the number of segments that were successfully compacted with proper deduplication. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_storage_log_closed_segment_bytes)vectorized\_storage\_log\_closed\_segment\_bytes Reports the total number of bytes contained in closed log segments. **Type**: gauge **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_storage_log_compacted_segment)vectorized\_storage\_log\_compacted\_segment Counts the total number of compacted log segments. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_storage_log_compaction_ratio)vectorized\_storage\_log\_compaction\_ratio Reports the average compaction ratio for log segments. **Type**: counter **Labels**: - `namespace` - `partition` - `topic` * * * ## [](#vectorized_storage_log_compaction_removed_bytes)vectorized\_storage\_log\_compaction\_removed\_bytes Counts the total number of bytes removed from local storage by compaction operations. This is tracked on a per-topic and per-partition basis. It tracks whether compaction is performing operations on local storage. The namespace label supports the following options for this metric: - `kafka`: User topics - `kafka_internal`: Internal Kafka topic, such as consumer groups - `redpanda`: Redpanda-only internal data **Type**: counter **Labels**: - `namespace=("kafka" | "kafka_internal" | "redpanda")` - `partition` - `shard` - `topic` * * * ## [](#vectorized_storage_log_complete_sliding_window_rounds)vectorized\_storage\_log\_complete\_sliding\_window\_rounds Counts the number of complete rounds executed in sliding window compaction. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_storage_log_corrupted_compaction_indices)vectorized\_storage\_log\_corrupted\_compaction\_indices Counts the number of times the compaction index had to be reconstructed due to corruption. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_storage_log_dirty_segment_bytes)vectorized\_storage\_log\_dirty\_segment\_bytes Reports the total number of bytes contained in dirty (non-compacted) log segments. **Type**: gauge **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_storage_log_log_segments_active)vectorized\_storage\_log\_log\_segments\_active Counts the current number of active local log segments. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_storage_log_log_segments_created)vectorized\_storage\_log\_log\_segments\_created Counts the total number of local log segments created since broker startup. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_storage_log_log_segments_removed)vectorized\_storage\_log\_log\_segments\_removed Counts the total number of local log segments removed since broker startup. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_storage_log_partition_size)vectorized\_storage\_log\_partition\_size Reports the current size (in bytes) of a partition’s log. **Type**: gauge **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_storage_log_read_bytes)vectorized\_storage\_log\_read\_bytes Counts the total number of bytes read from log segments. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_storage_log_readers_added)vectorized\_storage\_log\_readers\_added Counts the total number of log readers that have been added to the cache. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_storage_log_readers_evicted)vectorized\_storage\_log\_readers\_evicted Counts the total number of log readers evicted from the cache. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_storage_log_segments_marked_tombstone_free)vectorized\_storage\_log\_segments\_marked\_tombstone\_free Counts the number of log segments verified to be free of tombstones via compaction. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_storage_log_tombstones_removed)vectorized\_storage\_log\_tombstones\_removed Counts the number of tombstone records removed during compaction (per retention policy). **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_storage_log_written_bytes)vectorized\_storage\_log\_written\_bytes Counts the total number of bytes written to log segments. **Type**: counter **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_storage_manager_housekeeping_log_processed)vectorized\_storage\_manager\_housekeeping\_log\_processed Counts the number of logs processed by the storage housekeeping routine. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_storage_manager_logs)vectorized\_storage\_manager\_logs Reports the number of logs currently managed by the storage manager. **Type**: gauge **Labels**: - `shard` * * * ## [](#vectorized_storage_manager_urgent_gc_runs)vectorized\_storage\_manager\_urgent\_gc\_runs Counts the number of urgent garbage collection runs executed by the storage manager. **Type**: counter **Labels**: - `shard` * * * ## [](#vectorized_tx_partition_idempotency_pid_cache_size)vectorized\_tx\_partition\_idempotency\_pid\_cache\_size Reports the number of active producer ID–sequence pairs used for idempotency in transactions. **Type**: gauge **Labels**: - `namespace` - `partition` - `shard` - `topic` * * * ## [](#vectorized_tx_partition_tx_num_inflight_requests)vectorized\_tx\_partition\_tx\_num\_inflight\_requests Reports the number of ongoing transactional requests for a partition. **Type**: gauge **Labels**: - `namespace` - `partition` - `shard` - `topic` --- # Page 253: Redpanda Connectors Helm Chart Specification **URL**: https://docs.redpanda.com/current/reference/k-connector-helm-spec.md --- # Redpanda Connectors Helm Chart Specification --- title: Redpanda Connectors Helm Chart Specification latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: k-connector-helm-spec page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: k-connector-helm-spec.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/k-connector-helm-spec.adoc page-git-created-date: "2024-01-04" page-git-modified-date: "2025-07-31" support-status: supported --- ![Version: 0.1.14](https://img.shields.io/badge/Version-0.1.14-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: v1.0.31](https://img.shields.io/badge/AppVersion-v1.0.31-informational?style=flat-square) This page describes the official Redpanda Connectors Helm Chart. In particular, this page describes the contents of the chart’s [`values.yaml` file](https://github.com/redpanda-data/helm-charts/blob/main/charts/connectors/values.yaml). Each of the settings is listed and described on this page, along with any default values. For instructions on how to install and use the chart, including how to override and customize the chart’s values, refer to the [deployment documentation](https://docs.redpanda.com/current/deploy/deployment-option/self-hosted/kubernetes/k-deploy-connectors/). * * * Autogenerated from chart metadata using [helm-docs v1.11.0](https://github.com/norwoodj/helm-docs/releases/v1.11.0) ## [](#source-code)Source Code - [https://github.com/redpanda-data/redpanda-operator/tree/main/charts/connectors](https://github.com/redpanda-data/redpanda-operator/tree/main/charts/connectors) ## [](#requirements)Requirements Kubernetes: `^1.21.0-0` ## [](#settings)Settings ### [](#auth)[auth](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=auth) Authentication settings. For details, see the [SASL documentation](https://docs.redpanda.com/docs/manage/kubernetes/security/sasl-kubernetes/). The first line of the secret file is used. So the first superuser is used to authenticate to the Redpanda cluster. **Default:** {"sasl":{"enabled":false,"mechanism":"scram-sha-512","secretRef":"","userName":""}} ### [](#auth-sasl-mechanism)[auth.sasl.mechanism](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=auth.sasl.mechanism) The authentication mechanism to use for the superuser. Options are `scram-sha-256` and `scram-sha-512`. **Default:** `"scram-sha-512"` ### [](#auth-sasl-secretref)[auth.sasl.secretRef](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=auth.sasl.secretRef) A Secret that contains your SASL user password. **Default:** `""` ### [](#commonlabels)[commonLabels](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=commonLabels) Additional labels to add to all Kubernetes objects. For example, `my.k8s.service: redpanda`. **Default:** `{}` ### [](#connectors-additionalconfiguration)[connectors.additionalConfiguration](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=connectors.additionalConfiguration) A placeholder for any Java configuration settings for Kafka Connect that are not explicitly defined in this Helm chart. Java configuration settings are passed to the Kafka Connect startup script. **Default:** `""` ### [](#connectors-bootstrapservers)[connectors.bootstrapServers](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=connectors.bootstrapServers) A comma-separated list of Redpanda broker addresses in the format of IP:Port or DNS:Port. Kafka Connect uses this to connect to the Redpanda/Kafka cluster. **Default:** `""` ### [](#connectors-brokertls-ca-secretnameoverwrite)[connectors.brokerTLS.ca.secretNameOverwrite](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=connectors.brokerTLS.ca.secretNameOverwrite) If `secretRef` points to a Secret where the certificate authority (CA) is not under the `ca.crt` key, use `secretNameOverwrite` to overwrite it e.g. `corp-ca.crt`. **Default:** `""` ### [](#connectors-brokertls-ca-secretref)[connectors.brokerTLS.ca.secretRef](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=connectors.brokerTLS.ca.secretRef) The name of the Secret where the ca.crt file content is located. **Default:** `""` ### [](#connectors-brokertls-cert-secretnameoverwrite)[connectors.brokerTLS.cert.secretNameOverwrite](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=connectors.brokerTLS.cert.secretNameOverwrite) If secretRef points to secret where client signed certificate is not under tls.crt key then please use secretNameOverwrite to overwrite it e.g. corp-tls.crt **Default:** `""` ### [](#connectors-brokertls-cert-secretref)[connectors.brokerTLS.cert.secretRef](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=connectors.brokerTLS.cert.secretRef) The name of the secret where client signed certificate is located **Default:** `""` ### [](#connectors-brokertls-enabled)[connectors.brokerTLS.enabled](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=connectors.brokerTLS.enabled) **Default:** `false` ### [](#connectors-brokertls-key-secretnameoverwrite)[connectors.brokerTLS.key.secretNameOverwrite](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=connectors.brokerTLS.key.secretNameOverwrite) If secretRef points to secret where client private key is not under tls.key key then please use secretNameOverwrite to overwrite it e.g. corp-tls.key **Default:** `""` ### [](#connectors-brokertls-key-secretref)[connectors.brokerTLS.key.secretRef](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=connectors.brokerTLS.key.secretRef) The name of the secret where client private key is located **Default:** `""` ### [](#connectors-groupid)[connectors.groupID](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=connectors.groupID) A unique string that identifies the Kafka Connect cluster. It’s used in the formation of the internal topic names, ensuring that multiple Kafka Connect clusters can connect to the same Redpanda cluster without interfering with each other. **Default:** `"connectors-cluster"` ### [](#connectors-producerbatchsize)[connectors.producerBatchSize](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=connectors.producerBatchSize) The number of bytes of records a producer will attempt to batch together before sending to Redpanda. Batching improves throughput. **Default:** `131072` ### [](#connectors-producerlingerms)[connectors.producerLingerMS](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=connectors.producerLingerMS) The time, in milliseconds, that a producer will wait before sending a batch of records. Waiting allows the producer to gather more records in the same batch and improve throughput. **Default:** `1` ### [](#connectors-restport)[connectors.restPort](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=connectors.restPort) The port on which the Kafka Connect REST API listens. The API is used for administrative tasks. **Default:** `8083` ### [](#connectors-schemaregistryurl)[connectors.schemaRegistryURL](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=connectors.schemaRegistryURL) **Default:** `""` ### [](#connectors-secretmanager-connectorsprefix)[connectors.secretManager.connectorsPrefix](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=connectors.secretManager.connectorsPrefix) **Default:** `""` ### [](#connectors-secretmanager-consoleprefix)[connectors.secretManager.consolePrefix](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=connectors.secretManager.consolePrefix) **Default:** `""` ### [](#connectors-secretmanager-enabled)[connectors.secretManager.enabled](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=connectors.secretManager.enabled) **Default:** `false` ### [](#connectors-secretmanager-region)[connectors.secretManager.region](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=connectors.secretManager.region) **Default:** `""` ### [](#connectors-storage-remote)[connectors.storage.remote](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=connectors.storage.remote) Indicates if read and write operations for the respective topics are allowed remotely. **Default:** {"read":{"config":false,"offset":false,"status":false},"write":{"config":false,"offset":false,"status":false}} ### [](#connectors-storage-replicationfactor)[connectors.storage.replicationFactor](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=connectors.storage.replicationFactor) The number of replicas for each of the internal topics that Kafka Connect uses. **Default:** {"config":-1,"offset":-1,"status":-1} ### [](#connectors-storage-replicationfactor-config)[connectors.storage.replicationFactor.config](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=connectors.storage.replicationFactor.config) Replication factor for the configuration topic. **Default:** `-1` ### [](#connectors-storage-replicationfactor-offset)[connectors.storage.replicationFactor.offset](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=connectors.storage.replicationFactor.offset) Replication factor for the offset topic. **Default:** `-1` ### [](#connectors-storage-replicationfactor-status)[connectors.storage.replicationFactor.status](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=connectors.storage.replicationFactor.status) Replication factor for the status topic. **Default:** `-1` ### [](#connectors-storage-topic-config)[connectors.storage.topic.config](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=connectors.storage.topic.config) The name of the internal topic that Kafka Connect uses to store connector and task configurations. **Default:** "\_internal\_connectors\_configs" ### [](#connectors-storage-topic-offset)[connectors.storage.topic.offset](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=connectors.storage.topic.offset) The name of the internal topic that Kafka Connect uses to store source connector offsets. **Default:** "\_internal\_connectors\_offsets" ### [](#connectors-storage-topic-status)[connectors.storage.topic.status](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=connectors.storage.topic.status) The name of the internal topic that Kafka Connect uses to store connector and task status updates. **Default:** "\_internal\_connectors\_status" ### [](#container-javagclogenabled)[container.javaGCLogEnabled](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=container.javaGCLogEnabled) **Default:** `"false"` ### [](#container-resources)[container.resources](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=container.resources) Pod resource management. **Default:** {"javaMaxHeapSize":"2G","limits":{"cpu":"1","memory":"2350Mi"},"request":{"cpu":"1","memory":"2350Mi"}} ### [](#container-resources-javamaxheapsize)[container.resources.javaMaxHeapSize](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=container.resources.javaMaxHeapSize) Java maximum heap size must not be greater than `container.resources.limits.memory`. **Default:** `"2G"` ### [](#container-securitycontext)[container.securityContext](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=container.securityContext) Security context for the Redpanda Connectors container. See also `deployment.securityContext` for Pod-level settings. **Default:** {"allowPrivilegeEscalation":false} ### [](#deployment-annotations)[deployment.annotations](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.annotations) Additional annotations to apply to the Pods of this Deployment. **Default:** `{}` ### [](#deployment-budget-maxunavailable)[deployment.budget.maxUnavailable](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.budget.maxUnavailable) **Default:** `1` ### [](#deployment-create)[deployment.create](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.create) **Default:** `true` ### [](#deployment-extraenv)[deployment.extraEnv](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.extraEnv) Additional environment variables for the Pods. **Default:** `[]` ### [](#deployment-extraenvfrom)[deployment.extraEnvFrom](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.extraEnvFrom) Configure extra environment variables from Secrets and ConfigMaps. **Default:** `[]` ### [](#deployment-livenessprobe)[deployment.livenessProbe](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.livenessProbe) Adjust the period for your probes to meet your needs. For details, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#container-probes). **Default:** {"failureThreshold":3,"initialDelaySeconds":10,"periodSeconds":10,"successThreshold":1,"timeoutSeconds":1} ### [](#deployment-nodeaffinity)[deployment.nodeAffinity](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.nodeAffinity) Node Affinity rules for scheduling Pods of this Deployment. The suggestion would be to spread Pods according to topology zone. For details, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity). **Default:** `{}` ### [](#deployment-nodeselector)[deployment.nodeSelector](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.nodeSelector) Node selection constraints for scheduling Pods of this Deployment. These constraints override the global `nodeSelector` value. For details, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#nodeselector). **Default:** `{}` ### [](#deployment-podaffinity)[deployment.podAffinity](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.podAffinity) Inter-Pod Affinity rules for scheduling Pods of this Deployment. For details, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#inter-pod-affinity-and-anti-affinity). **Default:** `{}` ### [](#deployment-podantiaffinity)[deployment.podAntiAffinity](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.podAntiAffinity) Anti-affinity rules for scheduling Pods of this Deployment. For details, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#inter-pod-affinity-and-anti-affinity). You may either edit the default settings for anti-affinity rules, or specify new anti-affinity rules to use instead of the defaults. **Default:** {"custom":{},"topologyKey":"kubernetes.io/hostname","type":"hard","weight":100} ### [](#deployment-podantiaffinity-custom)[deployment.podAntiAffinity.custom](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.podAntiAffinity.custom) Change `podAntiAffinity.type` to `custom` and provide your own podAntiAffinity rules here. **Default:** `{}` ### [](#deployment-podantiaffinity-topologykey)[deployment.podAntiAffinity.topologyKey](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.podAntiAffinity.topologyKey) The `topologyKey` to be used. Can be used to spread across different nodes, AZs, regions etc. **Default:** `"kubernetes.io/hostname"` ### [](#deployment-podantiaffinity-type)[deployment.podAntiAffinity.type](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.podAntiAffinity.type) Valid anti-affinity types are `soft`, `hard`, or `custom`. Use `custom` if you want to supply your own anti-affinity rules in the `podAntiAffinity.custom` object. **Default:** `"hard"` ### [](#deployment-podantiaffinity-weight)[deployment.podAntiAffinity.weight](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.podAntiAffinity.weight) Weight for `soft` anti-affinity rules. Does not apply for other anti-affinity types. **Default:** `100` ### [](#deployment-priorityclassname)[deployment.priorityClassName](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.priorityClassName) PriorityClassName given to Pods of this Deployment. For details, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/pod-priority-preemption/#priorityclass). **Default:** `""` ### [](#deployment-progressdeadlineseconds)[deployment.progressDeadlineSeconds](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.progressDeadlineSeconds) The maximum time in seconds for a deployment to make progress before it is considered to be failed. The deployment controller will continue to process failed deployments and a condition with a ProgressDeadlineExceeded reason will be surfaced in the deployment status. Note that progress will not be estimated during the time a deployment is paused. **Default:** `600` ### [](#deployment-readinessprobe-failurethreshold)[deployment.readinessProbe.failureThreshold](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.readinessProbe.failureThreshold) **Default:** `2` ### [](#deployment-readinessprobe-initialdelayseconds)[deployment.readinessProbe.initialDelaySeconds](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.readinessProbe.initialDelaySeconds) **Default:** `60` ### [](#deployment-readinessprobe-periodseconds)[deployment.readinessProbe.periodSeconds](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.readinessProbe.periodSeconds) **Default:** `10` ### [](#deployment-readinessprobe-successthreshold)[deployment.readinessProbe.successThreshold](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.readinessProbe.successThreshold) **Default:** `3` ### [](#deployment-readinessprobe-timeoutseconds)[deployment.readinessProbe.timeoutSeconds](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.readinessProbe.timeoutSeconds) **Default:** `5` ### [](#deployment-restartpolicy)[deployment.restartPolicy](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.restartPolicy) **Default:** `"Always"` ### [](#deployment-revisionhistorylimit)[deployment.revisionHistoryLimit](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.revisionHistoryLimit) The number of old ReplicaSets to retain to allow rollback. This is a pointer to distinguish between explicit zero and not specified. **Default:** `10` ### [](#deployment-schedulername)[deployment.schedulerName](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.schedulerName) **Default:** `""` ### [](#deployment-securitycontext-fsgroup)[deployment.securityContext.fsGroup](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.securityContext.fsGroup) **Default:** `101` ### [](#deployment-securitycontext-fsgroupchangepolicy)[deployment.securityContext.fsGroupChangePolicy](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.securityContext.fsGroupChangePolicy) **Default:** `"OnRootMismatch"` ### [](#deployment-securitycontext-runasuser)[deployment.securityContext.runAsUser](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.securityContext.runAsUser) **Default:** `101` ### [](#deployment-strategy-type)[deployment.strategy.type](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.strategy.type) **Default:** `"RollingUpdate"` ### [](#deployment-terminationgraceperiodseconds)[deployment.terminationGracePeriodSeconds](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.terminationGracePeriodSeconds) **Default:** `30` ### [](#deployment-tolerations)[deployment.tolerations](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.tolerations) Taints to be tolerated by Pods of this Deployment. These tolerations override the global tolerations value. For details, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/). **Default:** `[]` ### [](#deployment-topologyspreadconstraints0-maxskew)[deployment.topologySpreadConstraints\[0\].maxSkew](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.topologySpreadConstraints%5B0%5D.maxSkew) **Default:** `1` ### [](#deployment-topologyspreadconstraints0-topologykey)[deployment.topologySpreadConstraints\[0\].topologyKey](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.topologySpreadConstraints%5B0%5D.topologyKey) **Default:** "topology.kubernetes.io/zone" ### [](#deployment-topologyspreadconstraints0-whenunsatisfiable)[deployment.topologySpreadConstraints\[0\].whenUnsatisfiable](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=deployment.topologySpreadConstraints%5B0%5D.whenUnsatisfiable) **Default:** `"ScheduleAnyway"` ### [](#fullnameoverride)[fullnameOverride](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=fullnameOverride) Override `connectors.fullname` template. **Default:** `""` ### [](#image)[image](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=image) Redpanda Docker image settings. **Default:** {"pullPolicy":"IfNotPresent","repository":"docker.redpanda.com/redpandadata/connectors","tag":""} ### [](#image-pullpolicy)[image.pullPolicy](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=image.pullPolicy) The imagePullPolicy. If `image.tag` is ``latest', the default is `Always``. **Default:** `"IfNotPresent"` ### [](#image-repository)[image.repository](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=image.repository) Docker repository from which to pull the Redpanda Docker image. **Default:** "docker.redpanda.com/redpandadata/connectors" ### [](#image-tag)[image.tag](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=image.tag) The Redpanda version. See DockerHub for: [All stable versions](https://hub.docker.com/r/redpandadata/redpanda/tags) and [all unstable versions](https://hub.docker.com/r/redpandadata/redpanda-unstable/tags). **Default:** `Chart.appVersion`. ### [](#imagepullsecrets)[imagePullSecrets](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=imagePullSecrets) Pull secrets may be used to provide credentials to image repositories See [https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) **Default:** `[]` ### [](#logging)[logging](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=logging) Log-level settings. **Default:** `{"level":"warn"}` ### [](#logging-level)[logging.level](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=logging.level) Log level Valid values (from least to most verbose) are: `error`, `warn`, `info` and `debug`. **Default:** `"warn"` ### [](#monitoring)[monitoring](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=monitoring) Monitoring. When set to `true`, the Helm chart creates a PodMonitor that can be used by Prometheus-Operator or VictoriaMetrics-Operator to scrape the metrics. **Default:** {"annotations":{},"enabled":false,"labels":{},"namespaceSelector":{"any":true},"scrapeInterval":"30s"} ### [](#nameoverride)[nameOverride](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=nameOverride) Override `connectors.name` template. **Default:** `""` ### [](#service)[service](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=service) Service management. **Default:** {"annotations":{},"name":"","ports":\[{"name":"prometheus","port":9404}\]} ### [](#service-annotations)[service.annotations](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=service.annotations) Annotations to add to the Service. **Default:** `{}` ### [](#service-name)[service.name](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=service.name) The name of the service to use. If not set, a name is generated using the `connectors.fullname` template. **Default:** `""` ### [](#serviceaccount)[serviceAccount](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=serviceAccount) ServiceAccount management. **Default:** {"annotations":{},"automountServiceAccountToken":false,"create":false,"name":""} ### [](#serviceaccount-annotations)[serviceAccount.annotations](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=serviceAccount.annotations) Annotations to add to the ServiceAccount. **Default:** `{}` ### [](#serviceaccount-automountserviceaccounttoken)[serviceAccount.automountServiceAccountToken](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=serviceAccount.automountServiceAccountToken) Specifies whether a service account should automount API-Credentials **Default:** `false` ### [](#serviceaccount-create)[serviceAccount.create](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=serviceAccount.create) Specifies whether a ServiceAccount should be created. **Default:** `false` ### [](#serviceaccount-name)[serviceAccount.name](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=serviceAccount.name) The name of the ServiceAccount to use. If not set and `serviceAccount.create` is `true`, a name is generated using the `connectors.fullname` template. **Default:** `""` ### [](#storage-volumemounts0-mountpath)[storage.volumeMounts\[0\].mountPath](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=storage.volumeMounts%5B0%5D.mountPath) **Default:** `"/tmp"` ### [](#storage-volumemounts0-name)[storage.volumeMounts\[0\].name](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=storage.volumeMounts%5B0%5D.name) **Default:** `"rp-connect-tmp"` ### [](#storage-volume0-emptydir-medium)[storage.volume\[0\].emptyDir.medium](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=storage.volume%5B0%5D.emptyDir.medium) **Default:** `"Memory"` ### [](#storage-volume0-emptydir-sizelimit)[storage.volume\[0\].emptyDir.sizeLimit](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=storage.volume%5B0%5D.emptyDir.sizeLimit) **Default:** `"5Mi"` ### [](#storage-volume0-name)[storage.volume\[0\].name](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=storage.volume%5B0%5D.name) **Default:** `"rp-connect-tmp"` ### [](#test-create)[test.create](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=test.create) **Default:** `true` ### [](#tolerations)[tolerations](https://artifacthub.io/packages/helm/redpanda-data/connectors?modal=values&path=tolerations) Taints to be tolerated by Pods. For details, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/). **Default:** `[]` --- # Page 254: Redpanda Console Helm Chart Specification **URL**: https://docs.redpanda.com/current/reference/k-console-helm-spec.md --- # Redpanda Console Helm Chart Specification --- title: Redpanda Console Helm Chart Specification latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: k-console-helm-spec page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: k-console-helm-spec.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/k-console-helm-spec.adoc page-git-created-date: "2024-01-04" page-git-modified-date: "2025-12-04" support-status: supported --- ![Version: 3.3.0](https://img.shields.io/badge/Version-3.3.0-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: v3.3.2](https://img.shields.io/badge/AppVersion-v3.3.2-informational?style=flat-square) This page describes the official Redpanda Console Helm Chart. In particular, this page describes the contents of the chart’s [`values.yaml` file](https://github.com/redpanda-data/helm-charts/blob/main/charts/console/values.yaml). Each of the settings is listed and described on this page, along with any default values. The Redpanda Console Helm chart is included as a subchart in the Redpanda Helm chart so that you can deploy and configure Redpanda and Redpanda Console together. For instructions on how to install and use the chart, refer to the [deployment documentation](https://docs.redpanda.com/docs/deploy/deployment-option/self-hosted/kubernetes/kubernetes-deploy/). For instructions on how to override and customize the chart’s values, see [Configure Redpanda Console](https://docs.redpanda.com/docs/manage/kubernetes/configure-helm-chart/#configure-redpanda-console). * * * Autogenerated from chart metadata using [helm-docs v1.11.0](https://github.com/norwoodj/helm-docs/releases/v1.11.0) ## [](#source-code)Source Code - [https://github.com/redpanda-data/redpanda-operator/tree/main/charts/console](https://github.com/redpanda-data/redpanda-operator/tree/main/charts/console) ## [](#requirements)Requirements Kubernetes: `>= 1.25.0-0` ## [](#settings)Settings ### [](#affinity)[affinity](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=affinity) **Default:** `{}` ### [](#annotations)[annotations](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=annotations) Annotations to add to the deployment. **Default:** `{}` ### [](#automountserviceaccounttoken)[automountServiceAccountToken](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=automountServiceAccountToken) Automount API credentials for the Service Account into the pod. Console does not communicate with Kubernetes API. **Default:** `false` ### [](#autoscaling-enabled)[autoscaling.enabled](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=autoscaling.enabled) **Default:** `false` ### [](#autoscaling-maxreplicas)[autoscaling.maxReplicas](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=autoscaling.maxReplicas) **Default:** `100` ### [](#autoscaling-minreplicas)[autoscaling.minReplicas](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=autoscaling.minReplicas) **Default:** `1` ### [](#autoscaling-targetcpuutilizationpercentage)[autoscaling.targetCPUUtilizationPercentage](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=autoscaling.targetCPUUtilizationPercentage) **Default:** `80` ### [](#commonlabels)[commonLabels](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=commonLabels) **Default:** `{}` ### [](#config)[config](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=config) Settings for the `Config.yaml` (required). For a reference of configuration settings, see the [Redpanda Console documentation](https://docs.redpanda.com/docs/reference/console/config/). **Default:** `{}` ### [](#configmap-create)[configmap.create](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=configmap.create) **Default:** `true` ### [](#deployment-create)[deployment.create](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=deployment.create) **Default:** `true` ### [](#extracontainerports)[extraContainerPorts](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=extraContainerPorts) Add additional container ports to the console container. Useful when using multi-listener configuration. **Default:** `[]` ### [](#extracontainers)[extraContainers](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=extraContainers) Add additional containers, such as for oauth2-proxy. **Default:** `[]` ### [](#extraenv)[extraEnv](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=extraEnv) Additional environment variables for the Redpanda Console Deployment. **Default:** `[]` ### [](#extraenvfrom)[extraEnvFrom](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=extraEnvFrom) Additional environment variables for Redpanda Console mapped from Secret or ConfigMap. **Default:** `[]` ### [](#extravolumemounts)[extraVolumeMounts](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=extraVolumeMounts) Add additional volume mounts, such as for TLS keys. **Default:** `[]` ### [](#extravolumes)[extraVolumes](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=extraVolumes) Add additional volumes, such as for TLS keys. **Default:** `[]` ### [](#fullnameoverride)[fullnameOverride](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=fullnameOverride) Override `console.fullname` template. **Default:** `""` ### [](#image)[image](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=image) Redpanda Console Docker image settings. **Default:** {"pullPolicy":"IfNotPresent","registry":"docker.redpanda.com","repository":"redpandadata/console","tag":""} ### [](#image-pullpolicy)[image.pullPolicy](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=image.pullPolicy) The imagePullPolicy. **Default:** `"IfNotPresent"` ### [](#image-repository)[image.repository](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=image.repository) Docker repository from which to pull the Redpanda Docker image. **Default:** `"redpandadata/console"` ### [](#image-tag)[image.tag](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=image.tag) The Redpanda Console version. See DockerHub for: [All stable versions](https://hub.docker.com/r/redpandadata/console/tags) and [all unstable versions](https://hub.docker.com/r/redpandadata/console-unstable/tags). **Default:** `Chart.appVersion` ### [](#imagepullsecrets)[imagePullSecrets](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=imagePullSecrets) Pull secrets may be used to provide credentials to image repositories See [https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) **Default:** `[]` ### [](#ingress-annotations)[ingress.annotations](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=ingress.annotations) **Default:** `{}` ### [](#ingress-enabled)[ingress.enabled](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=ingress.enabled) **Default:** `false` ### [](#ingress-hosts0-host)[ingress.hosts\[0\].host](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=ingress.hosts%5B0%5D.host) **Default:** `"chart-example.local"` ### [](#ingress-hosts0-paths0-path)[ingress.hosts\[0\].paths\[0\].path](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=ingress.hosts%5B0%5D.paths%5B0%5D.path) **Default:** `"/"` ### [](#ingress-hosts0-paths0-pathtype)[ingress.hosts\[0\].paths\[0\].pathType](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=ingress.hosts%5B0%5D.paths%5B0%5D.pathType) **Default:** `"ImplementationSpecific"` ### [](#ingress-tls)[ingress.tls](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=ingress.tls) **Default:** `[]` ### [](#initcontainers)[initContainers](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=initContainers) Any initContainers defined should be written here **Default:** `{"extraInitContainers":""}` ### [](#initcontainers-extrainitcontainers)[initContainers.extraInitContainers](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=initContainers.extraInitContainers) Additional set of init containers **Default:** `""` ### [](#livenessprobe)[livenessProbe](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=livenessProbe) Settings for liveness and readiness probes. For details, see the [Kubernetes documentation](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/#configure-probes). **Default:** {"failureThreshold":3,"periodSeconds":10,"successThreshold":1,"timeoutSeconds":1} ### [](#nameoverride)[nameOverride](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=nameOverride) Override `console.name` template. **Default:** `""` ### [](#nodeselector)[nodeSelector](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=nodeSelector) **Default:** `{}` ### [](#podannotations)[podAnnotations](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=podAnnotations) **Default:** `{}` ### [](#podlabels)[podLabels](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=podLabels) **Default:** `{}` ### [](#podsecuritycontext-fsgroup)[podSecurityContext.fsGroup](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=podSecurityContext.fsGroup) **Default:** `99` ### [](#podsecuritycontext-fsgroupchangepolicy)[podSecurityContext.fsGroupChangePolicy](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=podSecurityContext.fsGroupChangePolicy) **Default:** `"Always"` ### [](#podsecuritycontext-runasuser)[podSecurityContext.runAsUser](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=podSecurityContext.runAsUser) **Default:** `99` ### [](#priorityclassname)[priorityClassName](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=priorityClassName) PriorityClassName given to Pods. For details, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/pod-priority-preemption/#priorityclass). **Default:** `""` ### [](#readinessprobe-failurethreshold)[readinessProbe.failureThreshold](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=readinessProbe.failureThreshold) **Default:** `3` ### [](#readinessprobe-initialdelayseconds)[readinessProbe.initialDelaySeconds](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=readinessProbe.initialDelaySeconds) Grant time to test connectivity to upstream services such as Kafka and Schema Registry. **Default:** `10` ### [](#readinessprobe-periodseconds)[readinessProbe.periodSeconds](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=readinessProbe.periodSeconds) **Default:** `10` ### [](#readinessprobe-successthreshold)[readinessProbe.successThreshold](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=readinessProbe.successThreshold) **Default:** `1` ### [](#readinessprobe-timeoutseconds)[readinessProbe.timeoutSeconds](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=readinessProbe.timeoutSeconds) **Default:** `1` ### [](#replicacount)[replicaCount](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=replicaCount) **Default:** `1` ### [](#resources)[resources](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=resources) **Default:** `{}` ### [](#secret)[secret](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=secret) Create a new Kubernetes Secret for all sensitive configuration inputs. Each provided Secret is mounted automatically and made available to the Pod. If you want to use one or more existing Secrets, you can use the `extraEnvFrom` list to mount environment variables from string and secretMounts to mount files such as Certificates from Secrets. **Default:** {"authentication":{"jwtSigningKey":"","oidc":{}},"create":true,"kafka":{},"license":"","redpanda":{"adminApi":{}},"schemaRegistry":{},"serde":{}} ### [](#secret-kafka)[secret.kafka](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=secret.kafka) Kafka Secrets. **Default:** `{}` ### [](#secretmounts)[secretMounts](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=secretMounts) SecretMounts is an abstraction to make a Secret available in the container’s filesystem. Under the hood it creates a volume and a volume mount for the Redpanda Console container. **Default:** `[]` ### [](#securitycontext-runasnonroot)[securityContext.runAsNonRoot](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=securityContext.runAsNonRoot) **Default:** `true` ### [](#service-annotations)[service.annotations](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=service.annotations) Override the value in `console.config.server.listenPort` if not `nil` targetPort: **Default:** `{}` ### [](#service-port)[service.port](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=service.port) **Default:** `8080` ### [](#service-type)[service.type](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=service.type) **Default:** `"ClusterIP"` ### [](#serviceaccount-annotations)[serviceAccount.annotations](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=serviceAccount.annotations) Annotations to add to the service account. **Default:** `{}` ### [](#serviceaccount-automountserviceaccounttoken)[serviceAccount.automountServiceAccountToken](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=serviceAccount.automountServiceAccountToken) Specifies whether a service account should automount API-Credentials. Console does not communicate with Kubernetes API. The ServiceAccount could be used for workload identity. **Default:** `false` ### [](#serviceaccount-create)[serviceAccount.create](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=serviceAccount.create) Specifies whether a service account should be created. **Default:** `true` ### [](#serviceaccount-name)[serviceAccount.name](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=serviceAccount.name) The name of the service account to use. If not set and `serviceAccount.create` is `true`, a name is generated using the `console.fullname` template **Default:** `""` ### [](#strategy)[strategy](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=strategy) **Default:** `{}` ### [](#tests-enabled)[tests.enabled](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=tests.enabled) **Default:** `true` ### [](#tolerations)[tolerations](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=tolerations) **Default:** `[]` ### [](#topologyspreadconstraints)[topologySpreadConstraints](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values&path=topologySpreadConstraints) **Default:** `[]` --- # Page 255: Kubernetes Custom Resource Definitions **URL**: https://docs.redpanda.com/current/reference/k-crd-index.md --- # Kubernetes Custom Resource Definitions --- title: Kubernetes Custom Resource Definitions latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: k-crd-index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: k-crd-index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/k-crd-index.adoc description: Explore all custom resource definitions (CRDs) that are supported by the Redpanda Operator. page-git-created-date: "2024-01-04" page-git-modified-date: "2026-03-26" support-status: supported --- The Redpanda Operator uses custom resource definitions (CRDs) to manage Redpanda clusters, topics, users, and other resources declaratively in Kubernetes. ## [](#crd-source-files)CRD source files The CRD source definitions are maintained in the [Redpanda Operator repository](https://github.com/redpanda-data/redpanda-operator) under [`operator/config/crd/bases`](https://github.com/redpanda-data/redpanda-operator/tree/main/operator/config/crd/bases): | CRD | File | Description | | --- | --- | --- | | Redpanda | cluster.redpanda.com_redpandas.yaml | Defines Redpanda cluster resources. | | Topic | cluster.redpanda.com_topics.yaml | Defines Kafka topic resources. | | User | cluster.redpanda.com_users.yaml | Defines SASL user resources. | | Console | cluster.redpanda.com_consoles.yaml | Defines Redpanda Console resources. | | Schema | cluster.redpanda.com_schemas.yaml | Defines Schema Registry resources. | | RedpandaRole | cluster.redpanda.com_redpandaroles.yaml | Defines role-based access control resources. | All CRDs belong to the `cluster.redpanda.com` API group. The CRDs are installed automatically when you deploy the Redpanda Operator using Helm with `crds.enabled=true`. For the full API reference of supported fields, see [cluster.redpanda.com/v1alpha2](../k-crd/). --- # Page 256: cluster.redpanda.com/v1alpha2 **URL**: https://docs.redpanda.com/current/reference/k-crd.md --- # cluster.redpanda.com/v1alpha2 --- title: cluster.redpanda.com/v1alpha2 latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: k-crd page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: k-crd.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/k-crd.adoc description: Custom resource definitions for Redpanda resources. Use the Redpanda resources to create and manage Redpanda clusters, users and topics with the Redpanda Operator. page-git-created-date: "2024-01-04" page-git-modified-date: "2025-12-16" support-status: supported --- Resource Types - [Console](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-console) - [Redpanda](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpanda) - [RedpandaRole](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandarole) - [Schema](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-schema) - [ShadowLink](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-shadowlink) - [Topic](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-topic) - [User](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-user) ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-aclaccessfilter)ACLAccessFilter Filter an ACL based on its access Appears in: - [ACLFilter](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-aclfilter) | Field | Description | | --- | --- | | host string | The host to match. If not set, will default to match all hostswith the specified operation and permissionType. Note thatthe asterisk is literal and matches hosts that are set to | | operation ACLOperation | The ACL operation to match | | permissionType ACLType | The permission type | | principal string | The name of the principal, if not set will default to matchall principals with the specified operation and permissionType | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-aclfilter)ACLFilter A filter for ACLs Appears in: - [ShadowLinkSecuritySettingsSyncOptions](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-shadowlinksecuritysettingssyncoptions) | Field | Description | | --- | --- | | accessFilter ACLAccessFilter | The access filter | | resourceFilter ACLResourceFilter | The resource filter | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-acloperation)ACLOperation (string) ACLOperation specifies the type of operation for an ACL. Appears in: - [ACLAccessFilter](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-aclaccessfilter) - [ACLRule](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-aclrule) ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-aclresourcefilter)ACLResourceFilter Appears in: - [ACLFilter](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-aclfilter) | Field | Description | | --- | --- | | name string | | | patternType PatternType | | | resourceType ResourceType | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-aclresourcespec)ACLResourceSpec ACLResourceSpec indicates the resource for which given ACL rule applies. Appears in: - [ACLRule](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-aclrule) | Field | Description | | --- | --- | | type ResourceType | Type specifies the type of resource an ACL is applied to. Valid values:- topic- group- cluster- transactionalId | | name string | Name of resource for which given ACL rule applies. If using type cluster this must not be specified.Can be combined with patternType field to use prefix pattern. | | patternType PatternType | Describes the pattern used in the resource field. The supported types are literaland prefixed. With literal pattern type, the resource field will be used as a definitionof a full topic name. With prefix pattern type, the resource name will be used only asa prefix. Prefixed patterns can only be specified when using types topic, group, ortransactionalId. Default value is literal. Valid values:- literal- prefixed | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-aclrule)ACLRule ACLRule defines an ACL rule applied to the given user. Validations taken from [https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=75978240](https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=75978240) Appears in: - [RoleAuthorizationSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-roleauthorizationspec) - [UserAuthorizationSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-userauthorizationspec) | Field | Description | | --- | --- | | type ACLType | Type specifies the type of ACL rule to create. Valid values are:- allow- deny | | resource ACLResourceSpec | Indicates the resource for which given ACL rule applies. | | host string | The host from which the action described in the ACL rule is allowed or denied.If not set, it defaults to *, allowing or denying the action from any host. | | operations ACLOperation array | List of operations which will be allowed or denied. Valid values are resource type dependent, but include:- Read- Write- Delete- Alter- Describe- IdempotentWrite- ClusterAction- Create- AlterConfigs- DescribeConfigs | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-acltype)ACLType (string) ACLType specifies the type, either allow or deny of an ACL rule. Appears in: - [ACLAccessFilter](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-aclaccessfilter) - [ACLRule](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-aclrule) ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-admin)Admin Admin configures settings for the Admin API listeners. Appears in: - [Listeners](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-listeners) | Field | Description | | --- | --- | | enabled boolean | Specifies whether this Listener is enabled. | | authenticationMethod string | Specifies the authentication method for this listener. For example, 'mtls_identity', sasl or http_basic. | | appProtocol string | | | port integer | Specifies the container port number for this listener. | | tls ListenerTLS | Configures TLS settings for the internal listener. | | prefixTemplate string | Specifies the template used for generating the advertised addresses ofServices. This field accepts a string template that dynamicallyconstructs Service addresses based on various parameters such as Servicename and port number.For historical backwards compatibility, this field is present on bothinternal and external listeners. However, it is ignored when specifiedon internal listeners. | | external object (keys:string, values:ExternalListener) | Defines settings for the external listeners. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-adminapispec)AdminAPISpec AdminAPISpec defines client configuration for connecting to Redpanda’s admin API. Appears in: - [StaticConfigurationSource](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-staticconfigurationsource) | Field | Description | | --- | --- | | urls string array | Specifies a list of broker addresses in the format : | | tls CommonTLS | Defines TLS configuration settings for Redpanda clusters that have TLS enabled. | | sasl AdminSASL | Defines authentication configuration settings for Redpanda clusters that have authentication enabled. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-adminsasl)AdminSASL AdminSASL configures credentials to connect to Redpanda cluster that has authentication enabled. Appears in: - [AdminAPISpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-adminapispec) | Field | Description | | --- | --- | | username string | Specifies the username. | | mechanism SASLMechanism | Specifies the SASL/SCRAM authentication mechanism. | | password ValueSource | Specifies the password. | | authToken ValueSource | Specifies token for token-based authentication (only used if no username/password are provided). | | passwordSecretRef SecretKeyRef | Deprecated: use password instead | | token SecretKeyRef | Deprecated: use authToken instead | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-auditlogging)AuditLogging AuditLogging configures how to perform audit logging for a redpanda cluster Appears in: - [RedpandaClusterSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaclusterspec) | Field | Description | | --- | --- | | enabled boolean | Specifies whether to enable audit logging or not | | listener string | Kafka external listener name, note that it must have authenticationMethod set to sasl | | partitions integer | Integer value defining the number of partitions used by a newly created audit topic | | enabledEventTypes string array | Event types that should be captured by audit logs | | excludedTopics string array | List of topics to exclude from auditing | | excludedPrincipals string array | List of principals to exclude from auditing | | clientMaxBufferSize integer | Defines the number of bytes (in bytes) allocated by the internal audit client for audit messages. | | queueDrainIntervalMs integer | In ms, frequency in which per shard audit logs are batched to client for write to audit log. | | queueMaxBufferSizePerShard integer | Defines the maximum amount of memory used (in bytes) by the audit buffer in each shard | | replicationFactor integer | Defines the replication factor for a newly created audit log topic. This configuration appliesonly to the audit log topic and may be different from the cluster or other topic configurations.This cannot be altered for existing audit log topics. Setting this value is optional. If a value is not provided,Redpanda will use the internal_topic_replication_factor cluster config value. Default is null | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-auth)Auth Auth configures authentication in the Helm values. See [Authentication and Authorization for Redpanda in Kubernetes](../../manage/kubernetes/security/authentication/) Appears in: - [RedpandaClusterSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaclusterspec) | Field | Description | | --- | --- | | sasl SASL | Configures SASL authentication in the Helm values. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-authenticationsecrets)AuthenticationSecrets Appears in: - [SecretConfig](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-secretconfig) | Field | Description | | --- | --- | | jwtSigningKey string | | | oidc OIDCLoginSecrets | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-authorizationtype)AuthorizationType (string) AuthorizationType specifies the type of authorization to use in creating a user. Appears in: - [UserAuthorizationSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-userauthorizationspec) ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-autoscaling)AutoScaling Appears in: - [ConsoleSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-consolespec) - [ConsoleValues](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-consolevalues) | Field | Description | | --- | --- | | enabled boolean | | | minReplicas integer | | | maxReplicas integer | | | targetCPUUtilizationPercentage integer | | | targetMemoryUtilizationPercentage integer | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-bootstrapuser)BootstrapUser BootstrapUser configures the user used to bootstrap Redpanda when SASL is enabled. Appears in: - [SASL](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-sasl) | Field | Description | | --- | --- | | name string | Name specifies the name of the bootstrap user created for the cluster, if unspecifieddefaults to "kubernetes-controller". | | secretKeyRef SecretKeySelector | Specifies the location where the generated password will be written or a pre-existingpassword will be read from. | | mechanism string | Specifies the authentication mechanism to use for the bootstrap user. Options are SCRAM-SHA-256 and SCRAM-SHA-512. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-budget)Budget Budget configures the management of disruptions affecting the Pods in the StatefulSet. Appears in: - [Statefulset](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-statefulset) | Field | Description | | --- | --- | | maxUnavailable integer | Defines the maximum number of Pods that can be unavailable during a voluntary disruption. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-cpu)CPU CPU configures CPU resources for containers. See [Manage Pod Resources in Kubernetes](../../manage/kubernetes/k-manage-resources/) Appears in: - [Resources](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-resources) | Field | Description | | --- | --- | | cores Quantity | Specifies the number of CPU cores available to the application. Redpanda makes use of a thread per core model. For details, see How Redpanda Works For this reason, Redpanda should only be given full cores. Note: You can increase cores, but decreasing cores is not currently supported. See the GitHub issue:https://github.com/redpanda-data/redpanda/issues/350. This setting is equivalent to --smp, resources.requests.cpu, and resources.limits.cpu. For production, use 4 or greater. | | overprovisioned boolean | Specifies whether Redpanda assumes it has all of the provisioned CPU. This should be true unless the container has CPU affinity. Equivalent to: --idle-poll-time-us 0, --thread-affinity 0, and --poll-aio 0. If the value of full cores in resources.cpu.cores is less than 1, this setting is set to true. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-certificate)Certificate Certificate configures TLS certificates. Appears in: - [TLS](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-tls) | Field | Description | | --- | --- | | issuerRef IssuerRef | Specify the name of an existing Issuer or ClusterIssuer resource to use to generate certificates. Requires cert-manager. See https://cert-manager.io/v1.1-docs. | | secretRef SecretRef | Specify the name of an existing Secret resource that contains your TLS certificate. | | clientSecretRef SecretRef | Specify the name of an existing Secret resource that contains your client TLS certificate. | | duration Duration | Specifies the validity duration of certificates generated with issuerRef. | | caEnabled boolean | Specifies whether to include the ca.crt file in the trust stores of all listeners. Set to true only for certificates that are not authenticated using public certificate authorities (CAs). | | applyInternalDNSNames boolean | Specifies you wish to have Kubernetes internal dns names (IE the headless service of the redpanda StatefulSet) included in dnsNames of the certificate even, when supplying an issuer. | | enabled boolean | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-chartref)ChartRef Appears in: - [RedpandaSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaspec) | Field | Description | | --- | --- | | chartName string | Specifies the name of the chart to deploy. | | chartVersion string | Defines the version of the Redpanda Helm chart to deploy. | | helmRepositoryName string | Defines the chart repository to use. Defaults to redpanda if not defined. | | timeout Duration | Specifies the time to wait for any individual Kubernetes operation (like Jobsfor hooks) during Helm actions. Defaults to 15m0s. | | upgrade RawExtension | Defines how to handle upgrades, including failures. | | useFlux boolean | Setting the useFlux flag to false disables the Helm controller’s reconciliation of the Helm chart.This ties the operator to a specific version of the Go-based Redpanda Helm chart, causing all otherChartRef fields to be ignored.Before disabling useFlux, ensure that your chartVersion is aligned with 5.9.21 or the correspondingversion of the Redpanda chart.Note: When useFlux is set to false, RedpandaStatus may become inaccurate if the HelmRelease ismanually deleted.To dynamically switch Flux controllers (HelmRelease and HelmRepository), setting useFlux to falsewill suspend these resources instead of removing them.References:- https://fluxcd.io/flux/components/helm/helmreleases/#suspend- https://fluxcd.io/flux/components/source/helmrepositories/#suspend | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-clusterconfiguration)ClusterConfiguration (ClusterConfiguration) Appears in: - [Config](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-config) ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-clusterref)ClusterRef ClusterRef represents a reference to a cluster that is being targeted. Appears in: - [ClusterSource](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-clustersource) | Field | Description | | --- | --- | | group string | Group is used to override the object group that this reference points to.If unspecified, defaults to "cluster.redpanda.com". | | kind string | Kind is used to override the object kind that this reference points to.If unspecified, defaults to "Redpanda". | | name string | Name specifies the name of the cluster being referenced. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-clustersource)ClusterSource ClusterSource defines how to connect to a particular Redpanda cluster. Appears in: - [ConsoleSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-consolespec) - [RoleSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-rolespec) - [SchemaSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-schemaspec) - [ShadowLinkSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-shadowlinkspec) - [TopicSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-topicspec) - [UserSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-userspec) | Field | Description | | --- | --- | | clusterRef ClusterRef | ClusterRef is a reference to the cluster where the object should be created.It is used in constructing the client created to configure a cluster.This takes precedence over StaticConfigurationSource. | | staticConfiguration StaticConfigurationSource | StaticConfiguration holds connection parameters to Kafka and Admin APIs. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-commontls)CommonTLS CommonTLS specifies TLS configuration settings for Redpanda clusters that have authentication enabled. Appears in: - [AdminAPISpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-adminapispec) - [KafkaAPISpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-kafkaapispec) - [SchemaRegistrySpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-schemaregistryspec) | Field | Description | | --- | --- | | enabled boolean | Enabled tells any connections derived from this configuration to leverage TLS even if nocertificate configuration is specified. It only is relevant if no other field is specifiedin the TLS configuration block, as, for backwards compatibility reasons, any CA/Cert/Key-specificationresults in attempting to create a connection using TLS - specifying "false" in such a case doesnot disable TLS from being used. Leveraging this option is to support the use-case where aconnection is served by publically issued TLS certificates that don’t require any additional certificatespecification. | | caCert ValueSource | CaCert is the reference for certificate authority used to establish TLS connection to Redpanda | | cert ValueSource | Cert is the reference for client public certificate to establish mTLS connection to Redpanda | | key ValueSource | Key is the reference for client private certificate to establish mTLS connection to Redpanda | | caCertSecretRef SecretKeyRef | Deprecated: replaced by "caCert". | | certSecretRef SecretKeyRef | Deprecated: replaced by "cert". | | keySecretRef SecretKeyRef | Deprecated: replaced by "key". | | insecureSkipTlsVerify boolean | InsecureSkipTLSVerify can skip verifying Redpanda self-signed certificate when establish TLS connection to Redpanda | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-compatibilitylevel)CompatibilityLevel (string) Appears in: - [SchemaSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-schemaspec) ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-config)Config Config configures Redpanda config properties supported by Redpanda that may not work correctly in a Kubernetes cluster. Changing these values from the defaults comes with some risk. Use these properties to customize various Redpanda configurations that are not available in the `RedpandaClusterSpec`. These values have no impact on the configuration or behavior of the Kubernetes objects deployed by Helm, and therefore should not be modified for the purpose of configuring those objects. Instead, these settings get passed directly to the Redpanda binary at startup. Appears in: - [RedpandaClusterSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaclusterspec) | Field | Description | | --- | --- | | rpk RawExtension | Specifies cluster configuration properties. See Cluster Configuration Properties | | cluster RawExtension | Specifies cluster configuration properties. See Cluster Configuration Properties | | extraClusterConfiguration ClusterConfiguration | Holds values (or references to values) that should be used to configure the cluster; theseare resolved late in order to avoid embedding secrets directly into bootstrap configurationsexposed as Kubernetes configmaps. | | node RawExtension | Specifies broker configuration properties. See Broker Configuration Properties | | tunable RawExtension | Specifies tunable configuration properties. See Cluster Configuration Properties | | schema_registry_client RawExtension | Specifies tunable configuration properties. See Cluster Configuration Properties | | pandaproxy_client RawExtension | Specifies tunable configuration properties. See Cluster Configuration Properties | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-configsynonyms)ConfigSynonyms ConfigSynonyms was copied from [https://github.com/twmb/franz-go/blob/01651affd204d4a3577a341e748c5d09b52587f8/pkg/kmsg/generated.go#L24569-L24578](https://github.com/twmb/franz-go/blob/01651affd204d4a3577a341e748c5d09b52587f8/pkg/kmsg/generated.go#L24569-L24578) Appears in: - [Configuration](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-configuration) | Field | Description | | --- | --- | | name string | | | value string | | | source string | | | unknownTags object (keys:string, values:string) | UnknownTags are tags Kafka sent that we do not know the purpose of. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-configwatcher)ConfigWatcher ConfigWatcher configures a sidecar that watches for changes to the Secret in `auth.sasl.secretRef` and applies the changes to the Redpanda cluster. Appears in: - [SideCars](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-sidecars) | Field | Description | | --- | --- | | enabled boolean | Specifies whether the sidecar is enabled. | | extraVolumeMounts string | Specifies additional volumes to mount to the sidecar.DEPRECATED: Use sideCars.extraVolumeMounts | | resources ResourceRequirements | Specifies resource requests for the sidecar container.DEPRECATED: Use sideCars.resources | | securityContext SecurityContext | Specifies the container’s security context, including privileges and access levels of the container and its processes.DEPRECATED: Use sideCars.securityContext | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-configuration)Configuration Configuration was copied from [https://github.com/twmb/franz-go/blob/01651affd204d4a3577a341e748c5d09b52587f8/pkg/kmsg/generated.go#L24593-L24634](https://github.com/twmb/franz-go/blob/01651affd204d4a3577a341e748c5d09b52587f8/pkg/kmsg/generated.go#L24593-L24634) Appears in: - [TopicStatus](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-topicstatus) | Field | Description | | --- | --- | | name string | Name is a key this entry corresponds to (e.g. segment.bytes). | | value string | Value is the value for this config key. If the key is sensitive,the value will be null. | | readOnly boolean | ReadOnly signifies whether this is not a dynamic config option.Note that this field is not always correct, and you may need to checkwhether the Source is any dynamic enum. See franz-go#91 for more details. | | isDefault boolean | IsDefault is whether this is a default config option. This has beenreplaced in favor of Source. | | source string | Source is where this config entry is from.This field has a default of -1. | | isSensitive boolean | IsSensitive signifies whether this is a sensitive config key, whichis either a password or an unknown type. | | configSynonyms ConfigSynonyms array | ConfigSynonyms contains fallback key/value pairs for this configentry, in order of preference. That is, if a config entry is bothdynamically configured and has a default, the top level return will bethe dynamic configuration, while its "synonym" will be the default. | | configType string | ConfigType specifies the configuration data type. | | documentation string | Documentation is optional documentation for the config entry. | | unknownTags object (keys:string, values:string) | UnknownTags are tags Kafka sent that we do not know the purpose of. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-configurator)Configurator Appears in: - [InitContainers](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-initcontainers) | Field | Description | | --- | --- | | extraVolumeMounts string | | | resources ResourceRequirements | | | additionalCLIArgs string array | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-connectormonitoring)ConnectorMonitoring ConnectorMonitoring configures monitoring resources for Connectors. See [Monitor Redpanda in Kubernetes](../../manage/kubernetes/monitoring/k-monitor-redpanda/) Appears in: - [RedpandaConnectors](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaconnectors) | Field | Description | | --- | --- | | enabled boolean | Specifies whether to create a ServiceMonitor that can be used by Prometheus Operator or VictoriaMetrics Operator to scrape the metrics. | | labels object (keys:string, values:string) | Adds custom labels to the ServiceMonitor resource. | | scrapeInterval string | Specifies how often to scrape metrics. | | annotations object (keys:string, values:string) | Adds custom Annotations to the ServiceMonitor resource. | | namespaceSelector NamespaceSelector | Adds custom namespaceSelector to monitoring resources | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-connectorscreateobj)ConnectorsCreateObj ConnectorsCreateObj configures Kubernetes resources for Redpanda Connectors. Appears in: - [RedpandaConnectors](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaconnectors) | Field | Description | | --- | --- | | create boolean | Specifies whether to create the resource. | | enabled boolean | Deprecated: this field exists for storage backwards compatibility and isnever used. Prefer Create. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-console)Console Console defines the CRD for Redpanda Console instances. | Field | Description | | --- | --- | | apiVersion string | cluster.redpanda.com/v1alpha2 | | kind string | Console | | kind string | Kind is a string value representing the REST resource this object represents.Servers may infer this from the endpoint the client submits requests to.Cannot be updated.In CamelCase.More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | apiVersion string | APIVersion defines the versioned schema of this representation of an object.Servers should convert recognized schemas to the latest internal value, andmay reject unrecognized values.More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | metadata ObjectMeta | Refer to the Kubernetes API documentation for fields of metadata. | | spec ConsoleSpec | | | status ConsoleStatus | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-consolecreateobj)ConsoleCreateObj ConsoleCreateObj represents configuration options for creating Kubernetes objects such as ConfigMaps, Secrets, and Deployments. Appears in: - [RedpandaConsole](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaconsole) | Field | Description | | --- | --- | | create boolean | Indicates whether the corresponding Kubernetes object (ConfigMap, Secret, or Deployment) should be created. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-consolespec)ConsoleSpec Appears in: - [Console](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-console) | Field | Description | | --- | --- | | replicaCount integer | | | image Image | | | imagePullSecrets LocalObjectReference array | | | automountServiceAccountToken boolean | | | serviceAccount ServiceAccountConfig | | | commonLabels object (keys:string, values:string) | | | annotations object (keys:string, values:string) | | | podAnnotations object (keys:string, values:string) | | | podLabels object (keys:string, values:string) | | | podSecurityContext PodSecurityContext | | | securityContext SecurityContext | | | service ServiceConfig | | | ingress IngressConfig | | | resources ResourceRequirements | | | autoscaling AutoScaling | | | nodeSelector object (keys:string, values:string) | | | tolerations Toleration array | | | affinity Affinity | | | topologySpreadConstraints TopologySpreadConstraint array | | | priorityClassName string | | | config RawExtension | | | extraEnv EnvVar array | | | extraEnvFrom EnvFromSource array | | | extraVolumes Volume array | | | extraVolumeMounts VolumeMount array | | | extraContainers Container array | | | extraContainerPorts ContainerPort array | | | secretMounts SecretMount array | | | secret SecretConfig | | | licenseSecretRef SecretKeySelector | | | livenessProbe ProbeApplyConfiguration | LivenessProbe describes a health check to be performed against a container to determine whether it isalive. | | readinessProbe ProbeApplyConfiguration | ReadinessProbe describes a health check to be performed against a container to determine whether it isready to receive traffic. | | deployment DeploymentConfig | | | strategy DeploymentStrategy | | | warnings string array | Warnings is a slice of human readable warnings generated by the automaticmigration of a Console V2 config to a Console V3 config. If warnings arepresent, they will describe which fields from the original config havebeen dropped and why.Setting this field has no effect. | | cluster ClusterSource | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-consolestatus)ConsoleStatus Appears in: - [Console](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-console) | Field | Description | | --- | --- | | observedGeneration integer | The generation observed by the Console controller. | | replicas integer | Total number of non-terminating Pods targeted by this Console’s Deployment. | | updatedReplicas integer | Total number of non-terminating pods targeted by this Console’s Deployment that have the desired template spec. | | readyReplicas integer | Total number of non-terminating pods targeted by this Console’s Deployment with a Ready Condition. | | availableReplicas integer | Total number of available non-terminating pods (ready for at least minReadySeconds) targeted by this Console’s Deployment. | | unavailableReplicas integer | Total number of unavailable pods targeted by this deployment. This is the total number ofpods that are still required for the deployment to have 100% available capacity. They mayeither be pods that are running but not yet available or pods that still have not been created. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-consolevalues)ConsoleValues ConsoleValues is a CRD friendly equivalent of \[console.PartialValues\]. Any member that is optional at the top level, either by being a pointer, map, or slice, is NOT further partial-ized. This allows us to enforce validation constraints without accidentally polluting the defaults of the chart. Appears in: - [ConsoleSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-consolespec) | Field | Description | | --- | --- | | replicaCount integer | | | image Image | | | imagePullSecrets LocalObjectReference array | | | automountServiceAccountToken boolean | | | serviceAccount ServiceAccountConfig | | | commonLabels object (keys:string, values:string) | | | annotations object (keys:string, values:string) | | | podAnnotations object (keys:string, values:string) | | | podLabels object (keys:string, values:string) | | | podSecurityContext PodSecurityContext | | | securityContext SecurityContext | | | service ServiceConfig | | | ingress IngressConfig | | | resources ResourceRequirements | | | autoscaling AutoScaling | | | nodeSelector object (keys:string, values:string) | | | tolerations Toleration array | | | affinity Affinity | | | topologySpreadConstraints TopologySpreadConstraint array | | | priorityClassName string | | | config RawExtension | | | extraEnv EnvVar array | | | extraEnvFrom EnvFromSource array | | | extraVolumes Volume array | | | extraVolumeMounts VolumeMount array | | | extraContainers Container array | | | extraContainerPorts ContainerPort array | | | secretMounts SecretMount array | | | secret SecretConfig | | | licenseSecretRef SecretKeySelector | | | livenessProbe ProbeApplyConfiguration | LivenessProbe describes a health check to be performed against a container to determine whether it isalive. | | readinessProbe ProbeApplyConfiguration | ReadinessProbe describes a health check to be performed against a container to determine whether it isready to receive traffic. | | deployment DeploymentConfig | | | strategy DeploymentStrategy | | | warnings string array | Warnings is a slice of human readable warnings generated by the automaticmigration of a Console V2 config to a Console V3 config. If warnings arepresent, they will describe which fields from the original config havebeen dropped and why.Setting this field has no effect. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-containerresources)ContainerResources ContainerResources defines resource limits for containers. Appears in: - [Memory](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-memory) | Field | Description | | --- | --- | | max Quantity | Specifies the maximum resources that can be allocated to a container. | | min Quantity | Specifies the minimum resources required for a container. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-credentialsecretref)CredentialSecretRef CredentialSecretRef can be used to set cloud\_storage\_secret\_key from referenced Kubernetes Secret Appears in: - [Tiered](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-tiered) | Field | Description | | --- | --- | | accessKey SecretWithConfigField | | | secretKey SecretWithConfigField | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-deploymentconfig)DeploymentConfig Appears in: - [ConsoleSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-consolespec) - [ConsoleValues](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-consolevalues) | Field | Description | | --- | --- | | command string array | | | extraArgs string array | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-enterprise)Enterprise Enterprise configures an Enterprise license key to enable Redpanda Enterprise features. Requires the post-install job to be enabled (default). See [Redpanda Licenses and Enterprise Features](../../get-started/licensing/overview/) Appears in: - [RedpandaClusterSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaclusterspec) | Field | Description | | --- | --- | | license string | Specifies the Enterprise license key. | | licenseSecretRef EnterpriseLicenseSecretRef | Defines a reference to a Secret resource that contains the Enterprise license key. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-enterpriselicensesecretref)EnterpriseLicenseSecretRef EnterpriseLicenseSecretRef configures a reference to a Secret resource that contains the Enterprise license key. Appears in: - [Enterprise](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-enterprise) | Field | Description | | --- | --- | | key string | Specifies the key that is contains the Enterprise license in the Secret. | | name string | Specifies the name of the Secret resource to use. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-external)External External defines external connectivity settings in the Helm values. Appears in: - [RedpandaClusterSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaclusterspec) | Field | Description | | --- | --- | | addresses string array | Specifies addresses for the external listeners to advertise.Provide one entry for each broker in order of StatefulSet replicas. The number of brokers is defined in statefulset.replicas. The values can be IP addresses or DNS names. If external.domain is set, the domain is appended to these values. | | annotations object (keys:string, values:string) | Adds custom annotations to the external Service. | | domain string | Specifies the domain to advertise to external clients. If specified, then it will be appended to the external.addresses values as each broker’s advertised address. | | enabled boolean | Specifies whether the external access is enabled. | | service ExternalService | Configures the external Service resource. | | sourceRanges string array | Source range for external access. Only applicable when external.type is LoadBalancer. | | type string | Specifies the external Service type. Only NodePort and LoadBalancer are supported. If undefined, then advertised listeners will be configured in Redpanda, but the Helm chart will not create a Service. NodePort is recommended in cases where latency is a priority. | | externalDns ExternalDNS | Defines externalDNS configurations. | | prefixTemplate string | Specifies a naming prefix template for external Services. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-externaldns)ExternalDNS ExternalDNS configures externalDNS. Appears in: - [External](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-external) | Field | Description | | --- | --- | | enabled boolean | Specifies whether externalDNS annotations are added to LoadBalancer Services. If you enable externalDns, each LoadBalancer Service defined in external.type will be annotated with an external-dns hostname that matches external.addresses[i].external.domain. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-externallistener)ExternalListener ExternalListener configures settings for the external listeners. Appears in: - [Admin](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-admin) - [HTTP](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-http) - [Kafka](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-kafka) - [SchemaRegistry](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-schemaregistry) | Field | Description | | --- | --- | | enabled boolean | Specifies whether this Listener is enabled. | | authenticationMethod string | Specifies the authentication method for this listener. For example, 'mtls_identity', sasl or http_basic. | | appProtocol string | | | port integer | Specifies the container port number for this listener. | | tls ListenerTLS | Configures TLS settings for the internal listener. | | prefixTemplate string | Specifies the template used for generating the advertised addresses ofServices. This field accepts a string template that dynamicallyconstructs Service addresses based on various parameters such as Servicename and port number.For historical backwards compatibility, this field is present on bothinternal and external listeners. However, it is ignored when specifiedon internal listeners. | | advertisedPorts integer array | Specifies the network port that the external Service listens on. | | nodePort integer | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-externalsecretkeyselector)ExternalSecretKeySelector ExternalSecretKeySelector selects a key of an external Secret. Appears in: - [ValueSource](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-valuesource) | Field | Description | | --- | --- | | name string | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-externalservice)ExternalService ExternalService allows you to enable or disable the creation of an external Service type. Appears in: - [External](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-external) | Field | Description | | --- | --- | | enabled boolean | Specifies whether to create the external Service. If set to false, the external Service type is not created. You can still set your cluster with external access but not create the supporting Service. Set this to false to manage your own Service. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-filtertype)FilterType (string) FilterType specifies the type, either include or exclude of a consumer group filter. Appears in: - [NameFilter](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-namefilter) ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-fsvalidator)FsValidator Appears in: - [InitContainers](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-initcontainers) | Field | Description | | --- | --- | | enabled boolean | | | expectedFS string | | | extraVolumeMounts string | Adds extra volume mounts. | | resources ResourceRequirements | Specifies the resource requirements. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-http)HTTP HTTP configures settings for the HTTP Proxy listeners. Appears in: - [Listeners](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-listeners) | Field | Description | | --- | --- | | enabled boolean | Specifies whether this Listener is enabled. | | authenticationMethod string | Specifies the authentication method for this listener. For example, 'mtls_identity', sasl or http_basic. | | appProtocol string | | | port integer | Specifies the container port number for this listener. | | tls ListenerTLS | Configures TLS settings for the internal listener. | | prefixTemplate string | Specifies the template used for generating the advertised addresses ofServices. This field accepts a string template that dynamicallyconstructs Service addresses based on various parameters such as Servicename and port number.For historical backwards compatibility, this field is present on bothinternal and external listeners. However, it is ignored when specifiedon internal listeners. | | external object (keys:string, values:ExternalListener) | Defines settings for the external listeners. | | kafkaEndpoint string | Configures the listener to use for HTTP connections. For example default for the internal listener.deprecated and not respected. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-image)Image Appears in: - [ConsoleSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-consolespec) - [ConsoleValues](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-consolevalues) | Field | Description | | --- | --- | | registry string | | | repository string | | | pullPolicy PullPolicy | | | tag string | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-ingressconfig)IngressConfig Appears in: - [ConsoleSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-consolespec) - [ConsoleValues](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-consolevalues) | Field | Description | | --- | --- | | enabled boolean | | | className string | | | annotations object (keys:string, values:string) | | | hosts IngressHost array | | | tls IngressTLS array | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-ingresshost)IngressHost Appears in: - [IngressConfig](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-ingressconfig) | Field | Description | | --- | --- | | host string | | | paths IngressPath array | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-ingresspath)IngressPath Appears in: - [IngressHost](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-ingresshost) | Field | Description | | --- | --- | | path string | | | pathType PathType | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-initcontainerimage)InitContainerImage InitContainerImage configures the init container image used to perform initial setup tasks before the main containers start. Appears in: - [Statefulset](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-statefulset) | Field | Description | | --- | --- | | repository string | | | tag string | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-initcontainers)InitContainers InitContainers configures the init container used to perform initial setup tasks before the main containers start. Appears in: - [Statefulset](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-statefulset) | Field | Description | | --- | --- | | configurator Configurator | | | extraInitContainers string | | | setDataDirOwnership SetDataDirOwnership | Defines the settings related to ownership of the Redpanda data directory in environments where root access is restricted. | | setTieredStorageCacheDirOwnership SetTieredStorageCacheDirOwnership | Defines the settings related to ownership of the Tiered Storage cache in environments where root access is restricted. | | fsValidator FsValidator | Defines the setting for init container that not allow to start Redpanda until filesystem matches | | tuning Tuning | Defines settings for the autotuner tool in Redpanda. The autotuner identifies the hardware configuration in the container and optimizes the Linux kernel to give you the best performance. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-issuerref)IssuerRef IssuerRef configures the Issuer or ClusterIssuer resource to use to generate certificates. Requires cert-manager. See [https://cert-manager.io/v1.1-docs](https://cert-manager.io/v1.1-docs). Appears in: - [Certificate](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-certificate) | Field | Description | | --- | --- | | name string | Specifies the name of the resource. | | kind string | Specifies the kind of resource. One of Issuer or ClusterIssuer. | | group string | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-kafka)Kafka Kafka configures settings for the Kafka API listeners. Appears in: - [Listeners](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-listeners) | Field | Description | | --- | --- | | enabled boolean | Specifies whether this Listener is enabled. | | authenticationMethod string | Specifies the authentication method for this listener. For example, 'mtls_identity', sasl or http_basic. | | appProtocol string | | | port integer | Specifies the container port number for this listener. | | tls ListenerTLS | Configures TLS settings for the internal listener. | | prefixTemplate string | Specifies the template used for generating the advertised addresses ofServices. This field accepts a string template that dynamicallyconstructs Service addresses based on various parameters such as Servicename and port number.For historical backwards compatibility, this field is present on bothinternal and external listeners. However, it is ignored when specifiedon internal listeners. | | external object (keys:string, values:ExternalListener) | Defines settings for the external listeners. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-kafkaapispec)KafkaAPISpec KafkaAPISpec configures client configuration settings for connecting to Redpanda brokers. Appears in: - [StaticConfigurationSource](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-staticconfigurationsource) - [TopicSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-topicspec) | Field | Description | | --- | --- | | brokers string array | Specifies a list of broker addresses in the format : | | tls CommonTLS | Defines TLS configuration settings for Redpanda clusters that have TLS enabled. | | sasl KafkaSASL | Defines authentication configuration settings for Redpanda clusters that have authentication enabled. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-kafkasasl)KafkaSASL KafkaSASL configures credentials to connect to Redpanda cluster that has authentication enabled. Appears in: - [KafkaAPISpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-kafkaapispec) | Field | Description | | --- | --- | | username string | Specifies the username. | | password ValueSource | Specifies the password. | | mechanism SASLMechanism | Specifies the SASL/SCRAM authentication mechanism. | | oauth KafkaSASLOAuthBearer | | | gssapi KafkaSASLGSSAPI | | | awsMskIam KafkaSASLAWSMskIam | | | passwordSecretRef SecretKeyRef | Deprecated: use password instead | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-kafkasaslawsmskiam)KafkaSASLAWSMskIam KafkaSASLAWSMskIam is the config for AWS IAM SASL mechanism, see: [https://docs.aws.amazon.com/msk/latest/developerguide/iam-access-control.html](https://docs.aws.amazon.com/msk/latest/developerguide/iam-access-control.html) Appears in: - [KafkaSASL](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-kafkasasl) | Field | Description | | --- | --- | | accessKey string | | | secretKey ValueSource | | | secretKeySecretRef SecretKeyRef | Deprecated: use secretKey instead | | sessionToken ValueSource | SessionToken, if non-empty, is a session / security token to use for authentication.See: https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html | | sessionTokenSecretRef SecretKeyRef | Deprecated: use sessionToken instead | | userAgent string | UserAgent is the user agent to for the client to use when connectingto Kafka, overriding the default "franz-go//".Setting a UserAgent allows authorizing based on the aws:UserAgentcondition key; see the following link for more details:https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-useragent | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-kafkasaslgssapi)KafkaSASLGSSAPI KafkaSASLGSSAPI represents the Kafka Kerberos config. Appears in: - [KafkaSASL](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-kafkasasl) | Field | Description | | --- | --- | | authType string | | | keyTabPath string | | | kerberosConfigPath string | | | serviceName string | | | username string | | | password ValueSource | | | passwordSecretRef SecretKeyRef | Deprecated: use password instead | | realm string | | | enableFast boolean | EnableFAST enables FAST, which is a pre-authentication framework for Kerberos.It includes a mechanism for tunneling pre-authentication exchanges using armored KDC messages.FAST provides increased resistance to passive password guessing attacks. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-kafkasasloauthbearer)KafkaSASLOAuthBearer KafkaSASLOAuthBearer is the config struct for the SASL OAuthBearer mechanism Appears in: - [KafkaSASL](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-kafkasasl) | Field | Description | | --- | --- | | token ValueSource | | | tokenSecretRef SecretKeyRef | Deprecated: use token instead | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-kafkasecrets)KafkaSecrets Appears in: - [SecretConfig](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-secretconfig) | Field | Description | | --- | --- | | saslPassword string | | | awsMskIamSecretKey string | | | tlsCa string | | | tlsCert string | | | tlsKey string | | | tlsPassphrase string | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-licensesecretref)LicenseSecretRef LicenseSecretRef is deprecated. Use `EnterpriseLicenseSecretRef` instead. Appears in: - [RedpandaClusterSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaclusterspec) | Field | Description | | --- | --- | | secret_key string | Specifies the key that is contains the Enterprise license in the Secret. | | secret_name string | Specifies the name of the Secret. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-listener)Listener Appears in: - [Admin](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-admin) - [ExternalListener](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-externallistener) - [HTTP](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-http) - [Kafka](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-kafka) - [SchemaRegistry](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-schemaregistry) | Field | Description | | --- | --- | | enabled boolean | Specifies whether this Listener is enabled. | | authenticationMethod string | Specifies the authentication method for this listener. For example, 'mtls_identity', sasl or http_basic. | | appProtocol string | | | port integer | Specifies the container port number for this listener. | | tls ListenerTLS | Configures TLS settings for the internal listener. | | prefixTemplate string | Specifies the template used for generating the advertised addresses ofServices. This field accepts a string template that dynamicallyconstructs Service addresses based on various parameters such as Servicename and port number.For historical backwards compatibility, this field is present on bothinternal and external listeners. However, it is ignored when specifiedon internal listeners. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-listenertls)ListenerTLS ListenerTLS configures TLS configuration for each listener in the Helm values. Appears in: - [Admin](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-admin) - [ExternalListener](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-externallistener) - [HTTP](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-http) - [Kafka](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-kafka) - [Listener](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-listener) - [RPC](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-rpc) - [SchemaRegistry](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-schemaregistry) | Field | Description | | --- | --- | | cert string | References a specific certificate for the listener. | | enabled boolean | Specifies whether TLS is enabled for the listener. | | secretRef string | References a Secret resource containing TLS credentials for the listener.Deprecated: Setting SecretRef has no affect and will be removed infuture releases. | | requireClientAuth boolean | Indicates whether client authentication (mTLS) is required. | | trustStore TrustStore | TrustStore allows setting the truststore_path on this listener. Ifspecified, this field takes precedence over [Certificate.CAEnabled]. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-listeners)Listeners Listeners configures settings for listeners, including HTTP Proxy, Schema Registry, the Admin API and the Kafka API. See [Configure Listeners in Kubernetes](../../manage/kubernetes/networking/k-configure-listeners/) Appears in: - [RedpandaClusterSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaclusterspec) | Field | Description | | --- | --- | | admin Admin | Configures settings for the Admin API listeners. | | http HTTP | Configures settings for the HTTP Proxy listeners. | | kafka Kafka | Configures settings for the Kafka API listeners. | | rpc RPC | Configures settings for the RPC API listener. | | schemaRegistry SchemaRegistry | Configures settings for the Schema Registry listeners. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-livenessprobe)LivenessProbe LivenessProbe configures liveness probes to monitor the health of the Pods and restart them if necessary. Appears in: - [RedpandaConsole](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaconsole) - [Statefulset](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-statefulset) | Field | Description | | --- | --- | | failureThreshold integer | Sets the number of consecutive failures required to consider a Pod as not live. | | initialDelaySeconds integer | Specifies the time in seconds to wait before the first probe is initiated. | | periodSeconds integer | Determines the frequency in seconds of performing the probe. | | timeoutSeconds integer | | | successThreshold integer | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-logging)Logging Logging configures logging settings in the Helm values. See [Resolve Errors in Kubernetes](../../troubleshoot/errors-solutions/k-resolve-errors/) Appears in: - [RedpandaClusterSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaclusterspec) | Field | Description | | --- | --- | | logLevel string | Sets the verbosity level of logs. | | usageStats UsageStats | Specifies whether to send usage statistics to Redpanda Data. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-memory)Memory Memory configures memory resources. Appears in: - [Resources](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-resources) | Field | Description | | --- | --- | | container ContainerResources | Defines resource limits for containers. | | enable_memory_locking boolean | Enables memory locking. For production, set to true. | | redpanda RedpandaMemory | Allows you to optionally specify the memory size for both the Redpanda process and the underlying reserved memory used by Seastar. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-metadatatemplate)MetadataTemplate MetadataTemplate defines additional metadata to associate with a resource. Appears in: - [ResourceTemplate](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-resourcetemplate) | Field | Description | | --- | --- | | labels object (keys:string, values:string) | Labels specifies the Kubernetes labels to apply to a managed resource. | | annotations object (keys:string, values:string) | Annotations specifies the Kubernetes annotations to apply to a managed resource. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-monitoring)Monitoring Monitoring configures monitoring resources for Redpanda. See [Monitor Redpanda in Kubernetes](../../manage/kubernetes/monitoring/k-monitor-redpanda/) Appears in: - [RedpandaClusterSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaclusterspec) | Field | Description | | --- | --- | | enabled boolean | Specifies whether to create a ServiceMonitor that can be used by Prometheus Operator or VictoriaMetrics Operator to scrape the metrics. | | labels object (keys:string, values:string) | Adds custom labels to the ServiceMonitor resource. | | scrapeInterval string | Specifies how often to scrape metrics. | | tlsConfig RawExtension | Specifies tls configuration properties. | | enableHttp2 boolean | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-namefilter)NameFilter A filter based on the name of a resource Appears in: - [ShadowLinkConsumerOffsetSyncOptions](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-shadowlinkconsumeroffsetsyncoptions) - [ShadowLinkTopicMetadataSyncOptions](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-shadowlinktopicmetadatasyncoptions) | Field | Description | | --- | --- | | name string | The resource name, or ""Note if the wildcar "" is used it must be the only characterand patternType must be literal | | filterType FilterType | Valid values:- include- exclude | | patternType PatternType | Default value is literal. Valid values:- literal- prefixed | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-oidcloginsecrets)OIDCLoginSecrets Appears in: - [AuthenticationSecrets](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-authenticationsecrets) | Field | Description | | --- | --- | | clientSecret string | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-password)Password Password specifies a password for the user. Appears in: - [UserAuthenticationSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-userauthenticationspec) | Field | Description | | --- | --- | | value string | Value is a hardcoded value to use for the given password. It should only be used for testing purposes.In production, use ValueFrom. | | valueFrom PasswordSource | ValueFrom specifies a source for a password to be fetched from when specifying or generating user credentials. | | noGenerate boolean | NoGenerate when set to true does not create kubernetes secret when ValueFrom points to none-existent secret. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-passwordsource)PasswordSource PasswordSource contains the source for a password. Appears in: - [Password](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-password) | Field | Description | | --- | --- | | secretKeyRef SecretKeySelector | SecretKeyRef specifies the secret used in reading a User password.If the Secret exists and has a value in it, then that value is used.If the Secret does not exist, or is empty, a password is generated andstored based on this configuration. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-patterntype)PatternType (string) PatternType specifies the type of pattern applied for ACL resource matching. Appears in: - [ACLResourceFilter](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-aclresourcefilter) - [ACLResourceSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-aclresourcespec) - [NameFilter](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-namefilter) ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-persistentvolume)PersistentVolume PersistentVolume configures configurations for a PersistentVolumeClaim to use to store the Redpanda data directory. Appears in: - [Storage](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-storage) - [Tiered](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-tiered) | Field | Description | | --- | --- | | annotations object (keys:string, values:string) | Adds annotations to the PersistentVolumeClaims to provide additional information or metadata that can be used by other tools or libraries. | | enabled boolean | Specifies whether to enable the Helm chart to create PersistentVolumeClaims for Pods. | | labels object (keys:string, values:string) | Applies labels to the PersistentVolumeClaims to facilitate identification and selection based on custom criteria. | | size Quantity | Specifies the storage capacity required. | | storageClass string | Specifies the StorageClass for the PersistentVolumeClaims to determine how PersistentVolumes are provisioned and managed. | | nameOverwrite string | Option to change volume claim template name for tiered storage persistent volume if tiered.mountType is set to persistentVolume | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-podantiaffinity)PodAntiAffinity PodAntiAffinity configures Pod anti-affinity rules to prevent Pods from being scheduled together on the same node. Appears in: - [Statefulset](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-statefulset) | Field | Description | | --- | --- | | topologyKey string | TopologyKey specifies the topology key used to spread Pods across different nodes or other topologies. | | type string | Type defines the type of anti-affinity, such as soft or hard. | | weight integer | Weight sets the weight associated with the soft anti-affinity rule. | | custom RawExtension | Custom configures additional custom anti-affinity rules. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-podspecapplyconfiguration)PodSpecApplyConfiguration PodSpecApplyConfiguration is a wrapper around \[applycorev1.PodSpecApplyConfiguration\] that adds support for DeepCopying. Appears in: - [PodTemplate](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-podtemplate) ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-podtemplate)PodTemplate PodTemplate will pass label and annotation to Statefulset Pod template. Appears in: - [PostInstallJob](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-postinstalljob) - [PostUpgradeJob](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-postupgradejob) - [Statefulset](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-statefulset) | Field | Description | | --- | --- | | labels object (keys:string, values:string) | | | annotations object (keys:string, values:string) | | | spec PodSpecApplyConfiguration | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-poolconfigurator)PoolConfigurator Appears in: - [PoolInitContainers](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-poolinitcontainers) | Field | Description | | --- | --- | | additionalCLIArgs string array | Chart default: [] | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-poolfsvalidator)PoolFSValidator Appears in: - [PoolInitContainers](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-poolinitcontainers) | Field | Description | | --- | --- | | enabled boolean | Chart default: false | | expectedFS string | Chart default: xfs | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-poolsetdatadirownership)PoolSetDataDirOwnership Appears in: - [PoolInitContainers](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-poolinitcontainers) | Field | Description | | --- | --- | | enabled boolean | Chart default: false | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-postinstalljob)PostInstallJob PostInstallJob configures configurations for the post-install job that run after installation of the Helm chart. Appears in: - [RedpandaClusterSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaclusterspec) | Field | Description | | --- | --- | | resources ResourceRequirements | Sets resource requirements (CPU, memory) for the job to ensure proper allocation and limit resource usage. | | annotations object (keys:string, values:string) | Adds annotations to the job to provide additional information or metadata that can be used by other tools or libraries. | | enabled boolean | Specifies whether the job is deployed. | | labels object (keys:string, values:string) | Applies labels to the job to facilitate identification and selection based on custom criteria. | | affinity Affinity | Affinity constraints for scheduling Pods. For details, see theKubernetes' documentation. | | securityContext SecurityContext | SecurityContext is deprecated. Prefer [PodTemplate.Spec.SecurityContext]or [PodTemplate.Spec.Containers[*].SecurityContext]. | | podTemplate PodTemplate | PodTemplate is a subset of Kubernetes' PodTemplate that will be mergedinto this Job’s PodTemplate. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-postupgradejob)PostUpgradeJob PostUpgradeJob configures configurations for the post-upgrade job that run after each upgrade of the Helm chart. Appears in: - [RedpandaClusterSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaclusterspec) | Field | Description | | --- | --- | | annotations object (keys:string, values:string) | Adds annotations to the job to provide additional information or metadata that can be used by other tools or libraries. | | enabled boolean | Specifies whether the job is deployed. | | labels object (keys:string, values:string) | Applies labels to the job to facilitate identification and selection based on custom criteria. | | extraEnv EnvVar array | Adds environment variables to the job container to configure its runtime behavior. | | extraEnvFrom EnvFromSource array | Specifies environment variables from external sources, such as ConfigMap resources, or Secret resources, to dynamically configure the job. | | resources ResourceRequirements | Sets resource requirements (CPU, memory) for the job to ensure proper allocation and limit resource usage. | | backoffLimit integer | | | affinity Affinity | Affinity constraints for scheduling Pods. For details, see theKubernetes' documentation. | | securityContext SecurityContext | SecurityContext is deprecated. Prefer [PodTemplate.Spec.SecurityContext]or [PodTemplate.Spec.Containers[*].SecurityContext]. | | podTemplate PodTemplate | PodTemplate is a subset of Kubernetes' PodTemplate that will be mergedinto this Job’s PodTemplate. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-probeapplyconfiguration)ProbeApplyConfiguration ProbeApplyConfiguration is a wrapper type that allows including a partial \[corev1.Probe\] in a CRD. Appears in: - [ConsoleSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-consolespec) - [ConsoleValues](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-consolevalues) ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-rbac)RBAC RBAC configures role-based access control (RBAC). Appears in: - [RedpandaClusterSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaclusterspec) | Field | Description | | --- | --- | | annotations object (keys:string, values:string) | Adds custom annotations to the RBAC resources. | | enabled boolean | Whether RBAC is enabled. Enable for features that need extra privileges, such as rack awareness. If you use the Redpanda Operator, you must deploy it with the --set rbac.createRPKBundleCRs=true flag to give it the required ClusterRoles. | | rpkDebugBundle boolean | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-rpc)RPC RPC configures settings for the RPC API listeners. Appears in: - [Listeners](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-listeners) | Field | Description | | --- | --- | | port integer | Specifies the container port number for the internal listener. | | tls ListenerTLS | Configures TLS settings for the internal listener. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-rpcontrollers)RPControllers RPControllers configures additional controllers that can be deployed as sidecars in rp helm Appears in: - [SideCars](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-sidecars) | Field | Description | | --- | --- | | enabled boolean | Specifies whether the Controllers are enabled. | | resources ResourceRequirements | Specifies resource requests for the sidecar container.DEPRECATED: Use sideCars.resources | | securityContext SecurityContext | Specifies the container’s security context, including privileges and access levels of the container and its processes.DEPRECATED: Use sideCars.securityContext | | image RedpandaImage | | | healthProbeAddress string | | | metricsAddress string | | | pprofAddress string | | | run string array | | | createRBAC boolean | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-rackawareness)RackAwareness RackAwareness configures rack awareness in the Helm values. See [Enable Rack Awareness in Kubernetes](../../manage/kubernetes/k-rack-awareness/) Appears in: - [RedpandaClusterSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaclusterspec) | Field | Description | | --- | --- | | enabled boolean | Specifies whether rack awareness is enabled. When enabled, Kubernetes failure zones are treated as racks. Redpanda maps each rack to a failure zone and places partition replicas across them. Requires rbac.enabled set to true. | | nodeAnnotation string | Specifies the key in Node labels or annotations to use to denote failure zones. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-readinessprobe)ReadinessProbe ReadinessProbe configures readiness probes to determine when a Pod is ready to handle traffic. Appears in: - [RedpandaConsole](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaconsole) - [Statefulset](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-statefulset) | Field | Description | | --- | --- | | failureThreshold integer | Defines the threshold for how many times the probe can fail before the Pod is marked Unready. | | initialDelaySeconds integer | Sets the initial delay before the readiness probe is initiated, in seconds. | | periodSeconds integer | Configures the period, in seconds, between each readiness check. | | timeoutSeconds integer | | | successThreshold integer | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpanda)Redpanda Redpanda defines the CRD for Redpanda clusters. | Field | Description | | --- | --- | | apiVersion string | cluster.redpanda.com/v1alpha2 | | kind string | Redpanda | | kind string | Kind is a string value representing the REST resource this object represents.Servers may infer this from the endpoint the client submits requests to.Cannot be updated.In CamelCase.More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | apiVersion string | APIVersion defines the versioned schema of this representation of an object.Servers should convert recognized schemas to the latest internal value, andmay reject unrecognized values.More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | metadata ObjectMeta | Refer to the Kubernetes API documentation for fields of metadata. | | spec RedpandaSpec | Defines the desired state of the Redpanda cluster. | | status RedpandaStatus | Represents the current status of the Redpanda cluster. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaadminapisecrets)RedpandaAdminAPISecrets Appears in: - [RedpandaSecrets](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandasecrets) | Field | Description | | --- | --- | | password string | | | tlsCa string | | | tlsCert string | | | tlsKey string | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaclusterspec)RedpandaClusterSpec RedpandaClusterSpec defines the desired state of a Redpanda cluster. These settings are the same as those defined in the Redpanda Helm chart. The values in these settings are passed to the Redpanda Helm chart through Flux. For all default values and links to more documentation, see [Kubernetes Helm Chart Specifications](../k-helm-index/) For descriptions and default values, see [Redpanda Helm Chart Specification](../k-redpanda-helm-spec/). Appears in: - [RedpandaSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaspec) | Field | Description | | --- | --- | | nameOverride string | Customizes the labels app.kubernetes.io/component=-statefulset and app.kubernetes.io/name= on the StatefulSet Pods. The default is redpanda. | | fullNameOverride string | Deprecated: use FullnameOverride (fullnameOverride). | | fullnameOverride string | Customizes the name of the StatefulSet and Services. The default is redpanda. | | clusterDomain string | Customizes the Kubernetes cluster domain. This domain is used to generate the internal domains of the StatefulSet Pods. For details, see https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#stable-network-id. The default is the cluster.local domain. | | commonLabels object (keys:string, values:string) | Assigns custom labels to all resources generated by the Redpanda Helm chart. Specify labels as key/value pairs. | | nodeSelector object (keys:string, values:string) | Specifies on which nodes a Pod should be scheduled. These key/value pairs ensure that Pods are scheduled onto nodes with the specified labels. | | tolerations Toleration array | Specifies tolerations to allow Pods to be scheduled onto nodes where they otherwise wouldn’t. | | image RedpandaImage | Defines the container image settings to use for the Redpanda cluster. | | imagePullSecrets LocalObjectReference array | Specifies credentials for a private image repository. For details, see https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/. | | enterprise Enterprise | Defines an Enterprise license. | | rackAwareness RackAwareness | Defines rack awareness settings. | | console RedpandaConsole | Defines Redpanda Console settings.Deprecated: Use the dedicated Console CRD. | | connectors RedpandaConnectors | Defines Redpanda Connector settings.Deprecated, ignored, and unused as of v25.1.1 | | auth Auth | Defines authentication settings for listeners. | | tls TLS | Defines TLS settings for listeners. | | external External | Defines external access settings. | | logging Logging | Defines the log level settings. | | auditLogging AuditLogging | Defines the log level settings. | | resources Resources | Defines container resource settings. | | service Service | Defines settings for the headless ClusterIP Service. | | storage Storage | Defines storage settings for the Redpanda data directory and the Tiered Storage cache. | | post_install_job PostInstallJob | Defines settings for the post-install hook, which runs after each install or upgrade. For example, this job is responsible for setting the Enterprise license, if specified. | | post_upgrade_job PostUpgradeJob | Defines settings for the post-upgrade hook, which runs after each update. For example, this job is responsible for setting cluster configuration properties and restarting services such as Schema Registry, if required. | | statefulset Statefulset | Defines settings for the StatefulSet that manages Redpanda brokers. | | tuning Tuning | Defines settings for the autotuner tool in Redpanda. The autotuner identifies the hardware configuration in the container and optimizes the Linux kernel to give you the best performance. | | listeners Listeners | Defines settings for listeners, including HTTP Proxy, Schema Registry, the Admin API and the Kafka API. | | config Config | Defines configuration properties supported by Redpanda that may not work correctly in a Kubernetes cluster. Changing these values from the defaults comes with some risk. Use these properties to customize various Redpanda configurations that are not available in the RedpandaClusterSpec. These values have no impact on the configuration or behavior of the Kubernetes objects deployed by Helm, and therefore should not be modified for the purpose of configuring those objects. Instead, these settings get passed directly to the Redpanda binary at startup. | | rbac RBAC | Defines Role Based Access Control (RBAC) settings. | | serviceAccount ServiceAccount | Defines Service account settings. | | monitoring Monitoring | Defines settings for monitoring Redpanda. | | force boolean | Adds the --force flag in helm upgrade commands. Used for allowing a change of TLS configuration for the RPC listener.Setting force to true will result in a short period of downtime. | | affinity Affinity | Affinity constraints for scheduling Pods, can override this forStatefulSets and Jobs. For details, see the [Kubernetesdocumentation](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity). | | license_key string | Deprecated: Use enterprise.license instead. | | license_secret_ref LicenseSecretRef | Deprecated: Use enterprise.licenseSecretRef instead. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaconnectors)RedpandaConnectors RedpandaConnectors configures Redpanda Connectors. Redpanda Connectors is a package that includes Kafka Connect and built-in connectors, sometimes known as plugins. See [Deploy Kafka Connect in Kubernetes](../../deploy/kafka-connect/k-deploy-kafka-connect/) Appears in: - [RedpandaClusterSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaclusterspec) | Field | Description | | --- | --- | | enabled boolean | | | test ConnectorsCreateObj | Specifies whether to create Helm tests. | | monitoring ConnectorMonitoring | Specifies monitoring resources | | connectors RawExtension | Connectors specified manual configurations | | deployment RawExtension | Connectors specified manual configurations | | nameOverride string | Specifies a custom name for the Redpanda Console resources, overriding the default naming convention. | | fullnameOverride string | Specifies a full custom name, which overrides the entire naming convention including release name and chart name. | | commonLabels object (keys:string, values:string) | Assigns custom labels to all resources generated by the Connector Helm chart. Specify labels as key/value pairs. | | tolerations Toleration array | Applies tolerations to allow Pods to be scheduled on nodes with matching taints, enabling control over where Pods can run. | | image RedpandaImage | Defines the container image settings to use for the Redpanda cluster. | | imagePullSecrets LocalObjectReference array | Specifies credentials for a private image repository. For details, see https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/. | | auth RawExtension | Specifies superuser credentials | | container RawExtension | Specifies container information | | storage RawExtension | Specifies storage information | | logging RawExtension | Specifies logging details | | service RawExtension | Specifies service details | | serviceAccount RawExtension | Specifies service account details | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaconsole)RedpandaConsole RedpandaConsole is the union of console.PartialValues (earlier or equal to v0.7.31 Console version) and consolev3.PartialValues (after v0.7.31 Console version). Use these settings to configure the subchart. For more details on each setting, see the Helm values for the Redpanda Console chart: [https://artifacthub.io/packages/helm/redpanda-data/console?modal=values](https://artifacthub.io/packages/helm/redpanda-data/console?modal=values) Appears in: - [RedpandaClusterSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaclusterspec) | Field | Description | | --- | --- | | enabled boolean | Specifies whether the Redpanda Console subchart should be deployed. | | replicaCount integer | Sets the number of replicas for the Redpanda Console Deployment resource. | | nameOverride string | Specifies a custom name for the Redpanda Console resources, overriding the default naming convention. | | fullnameOverride string | Specifies a full custom name, which overrides the entire naming convention including release name and chart name. | | commonLabels object (keys:string, values:string) | | | priorityClassName string | Specifies the priority class name for the Pods that run Redpanda Console. | | image RawExtension | Defines the container image for the Redpanda Console, including the repository, name, and tag. | | imagePullSecrets RawExtension array | Defines Secrets used to pull the container images from a private registry. | | serviceAccount RawExtension | Configures the ServiceAccount used by the Pods that run Redpanda Console. | | annotations RawExtension | | | podAnnotations RawExtension | Adds custom annotations to the Pods that run Redpanda Console. | | podLabels RawExtension | Adds custom labels to the Pods that run Redpanda Console. | | podSecurityContext RawExtension | | | securityContext RawExtension | Sets the security context for the Pods that run Redpanda Console. | | service RawExtension | Configures the Kubernetes Service for Redpanda Console. | | ingress RawExtension | Configures the Kubernetes Ingress resource for Redpanda Console. | | resources RawExtension | Configures resource requests and limits for the Pods that run Redpanda Console. | | autoscaling RawExtension | Configures Horizontal Pod Autoscaling (HPA) for Redpanda Console. | | nodeSelector RawExtension | Specifies Node labels for Pod assignment. | | tolerations RawExtension array | Specifies tolerations for scheduling Pods onto Nodes with taints. | | affinity RawExtension | Defines affinity rules for Pod assignment. | | topologySpreadConstraints RawExtension | Specifies topology spread constraints for Pod placement. | | extraEnv RawExtension array | Adds extra environment variables to the Pods that run Redpanda Console. | | extraEnvFrom RawExtension array | Allows you to add extra environment variables from external resources to the Pods that run Redpanda Console. | | extraVolumes RawExtension array | Adds extra volumes to the Pods that run Redpanda Console. | | extraVolumeMounts RawExtension array | Mounts additional volumes inside the containers that run Redpanda Console. | | extraContainers RawExtension array | Adds extra containers to the Pods that run Redpanda Console. | | initContainers RawExtension | Specifies init containers for the Pods that run Redpanda Console. | | secretMounts RawExtension array | Mounts additional Secret resources inside the containers that run Redpanda Console. | | configmap ConsoleCreateObj | Deprecated: this field exists for storage backwards compatibility and isnever used. Prefer ConfigMap (configmap). | | configMap ConsoleCreateObj | Specifies whether a ConfigMap should be created for Redpanda Console. | | secret RawExtension | Specifies whether a Secret should be created for Redpanda Console. | | deployment RawExtension | Specifies whether a Deployment should be created for Redpanda Console. | | config RawExtension | Configures custom settings for Redpanda Console.config is available in Console chart version after v0.7.31 semver | | strategy RawExtension | Configures console’s Deployment’s update strategy. | | licenseSecretRef SecretKeySelector | Defines a reference to Kubernetes Secret that points to a Redpanda Enterprise license.Please consider use Enterprise in RedpandaClusterSpec type.licenseSecretRef is available in Console chart version after v0.7.31 semver | | automountServiceAccountToken boolean | Automount API credentials for the Service Account into the pod. | | readinessProbe ReadinessProbe | Settings for console’s Deployment’s readiness probe. | | livenessProbe LivenessProbe | Settings for console’s Deployment’s liveness probe. | | console RawExtension | Deprecated: Use config insteadconsole is available in Console chart version earlier or equal to v0.7.31 | | enterprise RawExtension | Deprecated: Use licenseSecretRef instead.enterprise is available in Console chart version earlier or equal to v0.7.31 | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaimage)RedpandaImage RedpandaImage configures the Redpanda container image settings in the Helm values. Appears in: - [RPControllers](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-rpcontrollers) - [RedpandaClusterSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaclusterspec) - [RedpandaConnectors](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaconnectors) - [SideCars](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-sidecars) | Field | Description | | --- | --- | | repository string | Specifies the image repository to pull from. | | tag string | Specifies the image tag. | | pullPolicy string | Specifies the strategy used for pulling images from the repository. For available values, see https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandalicensestatus)RedpandaLicenseStatus Appears in: - [RedpandaStatus](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandastatus) | Field | Description | | --- | --- | | violation boolean | | | inUseFeatures string array | | | expired boolean | | | type string | | | organization string | | | expiration Time | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandamemory)RedpandaMemory RedpandaMemory allows you to optionally specify the memory size for the Redpanda process, including the Seastar subsystem. By default, this section is omitted, and memory sizes are calculated automatically based on the container’s total memory allocation. When you configure this section and manually set the memory and reserveMemory values, the automatic calculation is disabled. If you are setting these values manually, follow these guidelines carefully. Incorrect settings can lead to performance degradation, instability, or even data loss. The total memory allocated to a container is determined as the sum of the following two areas: - Redpanda (including Seastar): Defined by the `--memory` parameter. Includes the memory used by the Redpanda process and the reserved memory allocated for Seastar. A minimum of 2Gi per core is required, and this value typically accounts for ~80% of the container’s total memory. For production, allocate at least 8Gi. - Operating system (OS): Defined by the `--reserve-memory` parameter. Represents the memory available for the operating system and other processes within the container. Appears in: - [Memory](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-memory) | Field | Description | | --- | --- | | memory Quantity | Memory for the Redpanda process. This must be lower than the container’s memory (resources.memory.container.min if provided, otherwise resources.memory.container.max). Equivalent to --memory. For production, use 8Gi or greater. | | reserveMemory Quantity | Memory reserved for the OS. Any value above 1Gi will provide diminishing performance benefits. Equivalent to --reserve-memory. For production, use 1Gi. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandarole)RedpandaRole RedpandaRole defines the CRD for a Redpanda role. | Field | Description | | --- | --- | | apiVersion string | cluster.redpanda.com/v1alpha2 | | kind string | RedpandaRole | | kind string | Kind is a string value representing the REST resource this object represents.Servers may infer this from the endpoint the client submits requests to.Cannot be updated.In CamelCase.More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | apiVersion string | APIVersion defines the versioned schema of this representation of an object.Servers should convert recognized schemas to the latest internal value, andmay reject unrecognized values.More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | metadata ObjectMeta | Refer to the Kubernetes API documentation for fields of metadata. | | spec RoleSpec | Defines the desired state of the Redpanda role. | | status RoleStatus | Represents the current status of the Redpanda role. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandasecrets)RedpandaSecrets Appears in: - [SecretConfig](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-secretconfig) | Field | Description | | --- | --- | | adminApi RedpandaAdminAPISecrets | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaspec)RedpandaSpec RedpandaSpec defines the desired state of the Redpanda cluster. Appears in: - [Redpanda](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpanda) | Field | Description | | --- | --- | | chartRef ChartRef | Defines chart details, including the version and repository. | | clusterSpec RedpandaClusterSpec | Defines the Helm values to use to deploy the cluster. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandastatus)RedpandaStatus RedpandaStatus defines the observed state of Redpanda Appears in: - [Redpanda](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpanda) | Field | Description | | --- | --- | | conditions Condition array | Conditions holds the conditions for the Redpanda. | | license RedpandaLicenseStatus | LicenseStatus contains information about the current state of anyinstalled license in the Redpanda cluster. | | configVersion string | ConfigVersion contains the configuration version written inRedpanda used for restarting broker nodes as necessary. | | observedGeneration integer | Deprecated | | lastHandledReconcileAt string | Deprecated | | lastAppliedRevision string | Deprecated | | lastAttemptedRevision string | Deprecated | | helmRelease string | Deprecated | | helmReleaseReady boolean | Deprecated | | helmRepository string | Deprecated | | helmRepositoryReady boolean | Deprecated | | upgradeFailures integer | Deprecated | | failures integer | Failures is the reconciliation failure count against the latest desiredstate. It is reset after a successful reconciliation.deprecated | | installFailures integer | Deprecated | | decommissioningNode integer | Deprecated | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-resourcetemplate)ResourceTemplate ResourceTemplate specifies additional configuration for a resource. Appears in: - [UserTemplateSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-usertemplatespec) | Field | Description | | --- | --- | | metadata MetadataTemplate | Refer to the Kubernetes API documentation for fields of metadata. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-resourcetype)ResourceType (string) ResourceType specifies the type of resource an ACL is applied to. Appears in: - [ACLResourceFilter](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-aclresourcefilter) - [ACLResourceSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-aclresourcespec) ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-resources)Resources RedpandaResources encapsulates the calculation of the redpanda container’s [corev1.ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#resourcerequirements-v1-core) and parameters such as `--memory`, `--reserve-memory`, and `--smp`. This calculation supports two modes: - Explicit mode (recommended): Activated when `Limits` and `Requests` are set. In this mode, the CLI flags are calculated directly based on the provided `Limits` and `Requests`. This mode ensures predictable resource allocation and is recommended for production environments. If additional tuning is required, the CLI flags can be manually overridden using `statefulset.additionalRedpandaCmdFlags`. - Legacy mode (default): Used when `Limits` and `Requests` are not set. In this mode, the container resources and CLI flags are calculated using built-in default logic, where 80% of the container’s memory is allocated to Redpanda and the rest is reserved for system overhead. Legacy mode is intended for backward compatibility and less controlled environments. Explicit mode offers better control and aligns with Kubernetes best practices. Legacy mode is a fallback for users who have not defined `Limits` and `Requests`. Appears in: - [RedpandaClusterSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaclusterspec) | Field | Description | | --- | --- | | limits Quantity | | | requests Quantity | | | cpu CPU | Specifies the number of CPU cores. | | memory Memory | Specifies the amount of memory. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-roleauthorizationspec)RoleAuthorizationSpec RoleAuthorizationSpec defines authorization rules for this role. Appears in: - [RoleSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-rolespec) | Field | Description | | --- | --- | | acls ACLRule array | List of ACL rules which should be applied to this role. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-rolespec)RoleSpec RoleSpec defines the configuration of a Redpanda role. Appears in: - [RedpandaRole](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandarole) | Field | Description | | --- | --- | | cluster ClusterSource | ClusterSource is a reference to the cluster where the role should be created.It is used in constructing the client created to configure a cluster. | | principals string array | Principals defines the list of users assigned to this role.Format: Type:Name (e.g., User:john, User:jane). If type is omitted, defaults to User. | | authorization RoleAuthorizationSpec | Authorization rules defined for this role. If specified, the operator will manage ACLs for this role.If omitted, ACLs should be managed separately using Redpanda’s ACL management. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-rolestatus)RoleStatus RoleStatus defines the observed state of a Redpanda role Appears in: - [RedpandaRole](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandarole) | Field | Description | | --- | --- | | observedGeneration integer | Specifies the last observed generation. | | conditions Condition array | Conditions holds the conditions for the Redpanda role. | | managedAcls boolean | ManagedACLs returns whether the role has managed ACLs that needto be cleaned up. | | managedRole boolean | ManagedRole returns whether the role has been created in Redpanda and needsto be cleaned up. | | managedPrincipals boolean | ManagedPrincipals returns whether the role has managed principals (membership)that are being reconciled by the operator. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-sasl)SASL SASL configures SASL authentication in the Helm values. Appears in: - [Auth](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-auth) | Field | Description | | --- | --- | | enabled boolean | Enables SASL authentication. If you enable SASL authentication, you must provide a Secret name in secretRef. | | mechanism string | Specifies the default authentication mechanism to use for superusers. Options are SCRAM-SHA-256 and SCRAM-SHA-512. | | secretRef string | If users is empty, secretRef specifies the name of the Secret that contains your superuser credentials in the format ::. Otherwise, secretRef specifies the name of the Secret that the chart creates to store the credentials in users. | | users UsersItems array | Specifies a list of superuser credentials. | | bootstrapUser BootstrapUser | Specifies configuration about the bootstrap user. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-saslmechanism)SASLMechanism (string) SASLMechanism specifies a SASL auth mechanism. Appears in: - [AdminSASL](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-adminsasl) - [KafkaSASL](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-kafkasasl) - [SchemaRegistrySASL](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-schemaregistrysasl) - [UserAuthenticationSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-userauthenticationspec) ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-schema)Schema Schema defines the CRD for a Redpanda schema. | Field | Description | | --- | --- | | apiVersion string | cluster.redpanda.com/v1alpha2 | | kind string | Schema | | kind string | Kind is a string value representing the REST resource this object represents.Servers may infer this from the endpoint the client submits requests to.Cannot be updated.In CamelCase.More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | apiVersion string | APIVersion defines the versioned schema of this representation of an object.Servers should convert recognized schemas to the latest internal value, andmay reject unrecognized values.More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | metadata ObjectMeta | Refer to the Kubernetes API documentation for fields of metadata. | | spec SchemaSpec | Defines the desired state of the Redpanda schema. | | status SchemaStatus | Represents the current status of the Redpanda schema. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-schemareference)SchemaReference SchemaReference is a way for a one schema to reference another. The details for how referencing is done are type specific; for example, JSON objects that use the key "$ref" can refer to another schema via URL. Appears in: - [SchemaSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-schemaspec) | Field | Description | | --- | --- | | name string | | | subject string | | | version integer | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-schemaregistry)SchemaRegistry SchemaRegistry configures settings for the Schema Registry listeners. Appears in: - [Listeners](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-listeners) | Field | Description | | --- | --- | | enabled boolean | Specifies whether this Listener is enabled. | | authenticationMethod string | Specifies the authentication method for this listener. For example, 'mtls_identity', sasl or http_basic. | | appProtocol string | | | port integer | Specifies the container port number for this listener. | | tls ListenerTLS | Configures TLS settings for the internal listener. | | prefixTemplate string | Specifies the template used for generating the advertised addresses ofServices. This field accepts a string template that dynamicallyconstructs Service addresses based on various parameters such as Servicename and port number.For historical backwards compatibility, this field is present on bothinternal and external listeners. However, it is ignored when specifiedon internal listeners. | | external object (keys:string, values:ExternalListener) | Defines settings for the external listeners. | | kafkaEndpoint string | Configures the listener to use for HTTP connections. For example default for the internal listener.deprecated and not respected. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-schemaregistrysasl)SchemaRegistrySASL SchemaRegistrySASL configures credentials to connect to Redpanda cluster that has authentication enabled. Appears in: - [SchemaRegistrySpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-schemaregistryspec) | Field | Description | | --- | --- | | username string | Specifies the username. | | password ValueSource | Specifies the password. | | authToken ValueSource | | | mechanism SASLMechanism | Specifies the SASL/SCRAM authentication mechanism. | | passwordSecretRef SecretKeyRef | Deprecated: use password instead | | token SecretKeyRef | Deprecated: use authToken instead | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-schemaregistrysecrets)SchemaRegistrySecrets Appears in: - [SecretConfig](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-secretconfig) | Field | Description | | --- | --- | | bearerToken string | | | password string | | | tlsCa string | | | tlsCert string | | | tlsKey string | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-schemaregistryspec)SchemaRegistrySpec SchemaRegistrySpec defines client configuration for connecting to Redpanda’s admin API. Appears in: - [StaticConfigurationSource](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-staticconfigurationsource) | Field | Description | | --- | --- | | urls string array | Specifies a list of broker addresses in the format : | | tls CommonTLS | Defines TLS configuration settings for Redpanda clusters that have TLS enabled. | | sasl SchemaRegistrySASL | Defines authentication configuration settings for Redpanda clusters that have authentication enabled. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-schemaspec)SchemaSpec SchemaSpec defines the configuration of a Redpanda schema. Appears in: - [Schema](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-schema) | Field | Description | | --- | --- | | cluster ClusterSource | ClusterSource is a reference to the cluster hosting the schema registry.It is used in constructing the client created to configure a cluster. | | text string | Text is the actual unescaped text of a schema. | | schemaType SchemaType | Type is the type of a schema. The default type is avro. | | references SchemaReference array | References declares other schemas this schema references. See thedocs on SchemaReference for more details. | | compatibilityLevel CompatibilityLevel | CompatibilityLevel sets the compatibility level for the given schema | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-schemastatus)SchemaStatus SchemaStatus defines the observed state of a Redpanda schema. Appears in: - [Schema](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-schema) | Field | Description | | --- | --- | | observedGeneration integer | Specifies the last observed generation. | | conditions Condition array | Conditions holds the conditions for the Redpanda schema. | | versions integer array | Versions shows the versions of a given schema | | schemaHash string | SchemaHash is the hashed value of the schema synced to the cluster | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-schematype)SchemaType (string) SchemaType specifies the type of the given schema. Appears in: - [SchemaSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-schemaspec) ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-secretconfig)SecretConfig Appears in: - [ConsoleSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-consolespec) - [ConsoleValues](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-consolevalues) | Field | Description | | --- | --- | | create boolean | | | kafka KafkaSecrets | | | authentication AuthenticationSecrets | | | license string | | | redpanda RedpandaSecrets | | | serde SerdeSecrets | | | schemaRegistry SchemaRegistrySecrets | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-secretkeyref)SecretKeyRef Deprecated: SecretKeyRef contains enough information to inspect or modify the referred Secret data See [https://pkg.go.dev/k8s.io/api/core/v1#ObjectReference](https://pkg.go.dev/k8s.io/api/core/v1#ObjectReference). Appears in: - [AdminSASL](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-adminsasl) - [CommonTLS](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-commontls) - [KafkaSASL](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-kafkasasl) - [KafkaSASLAWSMskIam](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-kafkasaslawsmskiam) - [KafkaSASLGSSAPI](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-kafkasaslgssapi) - [KafkaSASLOAuthBearer](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-kafkasasloauthbearer) - [SchemaRegistrySASL](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-schemaregistrysasl) | Field | Description | | --- | --- | | name string | Name of the referent.More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names | | key string | Key in Secret data to get value from | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-secretmount)SecretMount Appears in: - [ConsoleSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-consolespec) - [ConsoleValues](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-consolevalues) | Field | Description | | --- | --- | | name string | | | secretName string | | | path string | | | subPath string | | | defaultMode integer | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-secretref)SecretRef SecretRef configures the Secret resource that contains existing TLS certificates. Appears in: - [Certificate](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-certificate) | Field | Description | | --- | --- | | name string | Specifies the name of the Secret resource. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-secretwithconfigfield)SecretWithConfigField Appears in: - [CredentialSecretRef](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-credentialsecretref) | Field | Description | | --- | --- | | key string | | | name string | | | configurationKey string | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-serdesecrets)SerdeSecrets Appears in: - [SecretConfig](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-secretconfig) | Field | Description | | --- | --- | | protobufGitBasicAuthPassword string | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-service)Service Appears in: - [RedpandaClusterSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaclusterspec) | Field | Description | | --- | --- | | name string | | | internal ServiceInternal | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-serviceaccount)ServiceAccount ServiceAccount configures Service Accounts. Appears in: - [RedpandaClusterSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaclusterspec) | Field | Description | | --- | --- | | automountServiceAccountToken boolean | Specifies whether a service account should automount API-Credentials | | annotations object (keys:string, values:string) | Adds custom annotations to the ServiceAccount resources. | | create boolean | Specifies whether a ServiceAccount should be created. | | name string | Specifies the name of the ServiceAccount. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-serviceaccountconfig)ServiceAccountConfig Appears in: - [ConsoleSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-consolespec) - [ConsoleValues](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-consolevalues) | Field | Description | | --- | --- | | automountServiceAccountToken boolean | | | annotations object (keys:string, values:string) | | | name string | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-serviceconfig)ServiceConfig Appears in: - [ConsoleSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-consolespec) - [ConsoleValues](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-consolevalues) | Field | Description | | --- | --- | | type ServiceType | | | port integer | | | nodePort integer | | | targetPort integer | | | annotations object (keys:string, values:string) | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-serviceinternal)ServiceInternal Appears in: - [Service](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-service) | Field | Description | | --- | --- | | annotations object (keys:string, values:string) | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-setdatadirownership)SetDataDirOwnership SetDataDirOwnership defines the settings related to ownership of the Redpanda data directory in environments where root access is restricted. Appears in: - [InitContainers](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-initcontainers) | Field | Description | | --- | --- | | enabled boolean | Specifies whether to enable root access. Enable only in environments where root access is not allowed, such as minikube. | | extraVolumeMounts string | Adds extra volume mounts. | | resources ResourceRequirements | Specifies the resource requirements. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-settieredstoragecachedirownership)SetTieredStorageCacheDirOwnership SetTieredStorageCacheDirOwnership configures the settings related to ownership of the Tiered Storage cache in environments where root access is restricted. Appears in: - [InitContainers](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-initcontainers) | Field | Description | | --- | --- | | extraVolumeMounts string | | | resources ResourceRequirements | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-shadowlink)ShadowLink ShadowLink defines the CRD for ShadowLink cluster configuration. | Field | Description | | --- | --- | | apiVersion string | cluster.redpanda.com/v1alpha2 | | kind string | ShadowLink | | kind string | Kind is a string value representing the REST resource this object represents.Servers may infer this from the endpoint the client submits requests to.Cannot be updated.In CamelCase.More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | apiVersion string | APIVersion defines the versioned schema of this representation of an object.Servers should convert recognized schemas to the latest internal value, andmay reject unrecognized values.More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | metadata ObjectMeta | Refer to the Kubernetes API documentation for fields of metadata. | | spec ShadowLinkSpec | | | status ShadowLinkStatus | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-shadowlinkconsumeroffsetsyncoptions)ShadowLinkConsumerOffsetSyncOptions Options for syncing consumer offsets Appears in: - [ShadowLinkSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-shadowlinkspec) | Field | Description | | --- | --- | | interval Duration | Sync intervalIf 0 provided, defaults to 30 seconds | | paused boolean | Allows user to pause the consumer offset sync task. If paused, thenthe task will enter the 'paused' state and not sync consumer offsets fromthe source cluster | | groupFilters NameFilter array | The filters | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-shadowlinkschemaregistrysyncoptions)ShadowLinkSchemaRegistrySyncOptions Options for syncing schema registry settings Appears in: - [ShadowLinkSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-shadowlinkspec) | Field | Description | | --- | --- | | schema_registry_shadowing_mode ShadowLinkSchemaRegistrySyncOptionsMode | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-shadowlinkschemaregistrysyncoptionsmode)ShadowLinkSchemaRegistrySyncOptionsMode (string) Appears in: - [ShadowLinkSchemaRegistrySyncOptions](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-shadowlinkschemaregistrysyncoptions) ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-shadowlinksecuritysettingssyncoptions)ShadowLinkSecuritySettingsSyncOptions Options for syncing security settings Appears in: - [ShadowLinkSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-shadowlinkspec) | Field | Description | | --- | --- | | interval Duration | Sync intervalIf 0 provided, defaults to 30 seconds | | paused boolean | Allows user to pause the security settings sync task. If paused,then the task will enter the 'paused' state and will not sync securitysettings from the source cluster | | aclFilters ACLFilter array | ACL filters | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-shadowlinkspec)ShadowLinkSpec Appears in: - [ShadowLink](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-shadowlink) | Field | Description | | --- | --- | | shadowCluster ClusterSource | | | sourceCluster ClusterSource | | | topicMetadataSyncOptions ShadowLinkTopicMetadataSyncOptions | Topic metadata sync options | | consumerOffsetSyncOptions ShadowLinkConsumerOffsetSyncOptions | Consumer offset sync options | | securitySyncOptions ShadowLinkSecuritySettingsSyncOptions | Security settings sync options | | schemaRegistrySyncOptions ShadowLinkSchemaRegistrySyncOptions | options for schema registry | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-shadowlinkstate)ShadowLinkState (string) State of the shadow link Appears in: - [ShadowLinkStatus](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-shadowlinkstatus) ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-shadowlinkstatus)ShadowLinkStatus ShadowLinkStatus defines the observed state of any node pools tied to this cluster Appears in: - [ShadowLink](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-shadowlink) | Field | Description | | --- | --- | | state ShadowLinkState | State of the shadow link | | taskStatuses ShadowLinkTaskStatus array | Statuses of the running tasks | | shadowTopicStatuses ShadowTopicStatus array | Status of shadow topics | | conditions Condition array | Conditions holds the conditions for the ShadowLink. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-shadowlinktaskstatus)ShadowLinkTaskStatus Appears in: - [ShadowLinkStatus](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-shadowlinkstatus) | Field | Description | | --- | --- | | lastTransitionTime Time | | | name string | Name of the task | | state TaskState | State of the task | | reason string | Reason for task being in state | | brokerId integer | The broker the task is running on | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-shadowlinktopicmetadatasyncoptions)ShadowLinkTopicMetadataSyncOptions Options for syncing topic metadata Appears in: - [ShadowLinkSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-shadowlinkspec) | Field | Description | | --- | --- | | interval Duration | How often to sync metadataIf 0 provided, defaults to 30 seconds | | autoCreateShadowTopicFilters NameFilter array | List of filters that indicate which topics should be automaticallycreated as shadow topics on the shadow cluster. This only controlsautomatic creation of shadow topics and does not effect the state of themirror topic once it is created.Literal filters for consumer_offsets and redpanda.audit_log will berejected as well as prefix filters to match topics prefixed with_redpanda or redpanda.Wildcard * is permitted only for literal filters and will _not matchany topics that start with _redpanda or redpanda. If users wish toshadow topics that start with _redpanda or redpanda, they shouldprovide a literal filter for those topics. | | syncedShadowTopicProperties string array | List of topic properties that should be synced from the source topic.The following properties will always be replicated- Partition count- max.message.bytes- cleanup.policy- timestamp.typeThe following properties are not allowed to be replicated and adding themto this list will result in an error:- redpanda.remote.readreplica- redpanda.remote.recovery- redpanda.remote.allowgaps- redpanda.virtual.cluster.id- redpanda.leaders.preference- redpanda.cloud_topic.enabledThis list is a list of properties in addition to the default propertiesthat will be synced. See excludeDefault. | | excludeDefault boolean | If false, then the following topic properties will be synced by default:- compression.type- retention.bytes- retention.ms- delete.retention.ms- Replication Factor- min.compaction.lag.ms- max.compaction.lag.msIf this is true, then only the properties listed insynced_shadow_topic_properties will be synced. | | startOffset TopicMetadataSyncOffset | The starting offset for new shadow topic partitions.Defaults to earliest.Only applies if the shadow partition is empty. | | startOffsetTimestamp Time | The timestamp to start at if startOffset` is set to "timestamp".Not providing this when setting startOffset to "timestamp" isan error. | | paused boolean | Allows user to pause the topic sync task. If paused, thenthe task will enter the 'paused' state and not sync topics or theirproperties from the source cluster | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-shadowtopicstate)ShadowTopicState (string) State of a shadow topic Appears in: - [ShadowTopicStatus](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-shadowtopicstatus) ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-shadowtopicstatus)ShadowTopicStatus Status of a ShadowTopic Appears in: - [ShadowLinkStatus](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-shadowlinkstatus) | Field | Description | | --- | --- | | lastTransitionTime Time | | | name string | Name of the shadow topic | | topicId string | Topic ID of the shadow topic | | state ShadowTopicState | State of the shadow topic | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-sidecarobj)SideCarObj SideCarObj represents a generic sidecar object. This is a placeholder for now. Appears in: - [SideCars](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-sidecars) | Field | Description | | --- | --- | | enabled boolean | | | resources ResourceRequirements | Specifies resource requests for the sidecar container.DEPRECATED: Use sideCars.resources | | securityContext SecurityContext | Specifies the container’s security context, including privileges and access levels of the container and its processes.DEPRECATED: Use sideCars.securityContext | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-sidecars)SideCars SideCars configures the additional sidecar containers that run alongside the main Redpanda container in the Pod. Appears in: - [Statefulset](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-statefulset) | Field | Description | | --- | --- | | image RedpandaImage | | | extraVolumeMounts string | Specifies additional volumes to mount to the sidecar. | | resources ResourceRequirements | Specifies resource requests for the sidecar container. | | securityContext SecurityContext | Specifies the container’s security context, including privileges and access levels of the container and its processes. | | args string array | | | configWatcher ConfigWatcher | Configures the config-watcher sidecar. The config-watcher sidecar polls the Secret resource in auth.sasl.secretRef for changes and triggers a rolling upgrade to add the new superusers to the Redpanda cluster. | | rpkStatus SideCarObj | | | controllers RPControllers | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-startupprobe)StartupProbe StartupProbe configures the startup probe to determine when the Redpanda application within the Pod has started successfully. Appears in: - [Statefulset](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-statefulset) | Field | Description | | --- | --- | | failureThreshold integer | Determines the failure threshold to mark the application in the Pod as not started. | | initialDelaySeconds integer | Specifies the delay in seconds before the startup probe begins. | | periodSeconds integer | Sets the period in seconds for conducting subsequent probes. | | timeoutSeconds integer | | | successThreshold integer | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-statefulset)Statefulset Statefulset defines configurations for the StatefulSet in Helm values. Appears in: - [RedpandaClusterSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaclusterspec) | Field | Description | | --- | --- | | additionalSelectorLabels object (keys:string, values:string) | | | additionalRedpandaCmdFlags string array | Includes additional command flags for Redpanda at startup to customize its runtime behavior. | | annotations object (keys:string, values:string) | Adds annotations to the StatefulSet to provide additional information or metadata.Please use PodTemplate to add additional annotation or labels for Pods managed by Statefulset. | | podTemplate PodTemplate | PodTemplate is a subset of Kubernetes' PodTemplate that will be mergedinto this StatefulSet’s PodTemplate. | | budget Budget | Defines the management of disruptions affecting the Pods in the StatefulSet. | | extraVolumeMounts string | Specifies extra volume mounts for the Pods. | | extraVolumes string | Defines additional volumes for the Pods. | | initContainerImage InitContainerImage | Defines the init container image used to perform initial setup tasks before the main containers start. | | initContainers InitContainers | Configures the init container used to perform initial setup tasks before the main containers start. | | livenessProbe LivenessProbe | Defines liveness probes to monitor the health of the Pods and restart them if necessary. | | nodeSelector object (keys:string, values:string) | Applies node selectors to schedule Pods on specific nodes based on labels. | | podAffinity PodAffinity | Defines Pod affinity rules to influence the scheduling and placement of Pods relative to other Pods. | | podAntiAffinity PodAntiAffinity | Defines Pod anti-affinity rules to prevent Pods from being scheduled together on the same node. | | priorityClassName string | Defines the priority class name to assign priority levels to the Pods, influencing their scheduling order. | | readinessProbe ReadinessProbe | Defines readiness probes to determine when a Pod is ready to handle traffic. | | replicas integer | Specifies the number of replicas to determine the desired number of Pods (Redpanda brokers) in the StatefulSet. | | securityContext SecurityContext | Sets a security context for the Pods to define privilege and access control settings. | | sideCars SideCars | Defines the additional sidecar containers that run alongside the main Redpanda container in the Pod. | | skipChown boolean | Specifies whether to skip the changing of file ownership (chown) during Pod initialization. | | startupProbe StartupProbe | Configures the startup probe to determine when the Redpanda application within the Pod has started successfully. | | tolerations Toleration array | Applies tolerations to allow Pods to be scheduled on nodes with matching taints, enabling control over where Pods can run. | | topologySpreadConstraints TopologySpreadConstraints array | Defines topology spread constraints to control how Pods are spread across different topology domains. | | updateStrategy UpdateStrategy | Defines the update strategy for the StatefulSet to manage how updates are rolled out to the Pods. | | terminationGracePeriodSeconds integer | Specifies the termination grace period in seconds to control the time delay before forcefully terminating a Pod. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-staticconfigurationsource)StaticConfigurationSource StaticConfigurationSource configures connections to a Redpanda cluster via hard-coded connection strings and manually configured TLS and authentication parameters. Appears in: - [ClusterSource](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-clustersource) | Field | Description | | --- | --- | | kafka KafkaAPISpec | Kafka is the configuration information for communicating with the KafkaAPI of a Redpanda cluster where the object should be created. | | admin AdminAPISpec | AdminAPISpec is the configuration information for communicating with the AdminAPI of a Redpanda cluster where the object should be created. | | schemaRegistry SchemaRegistrySpec | SchemaRegistry is the configuration information for communicating with the Schema RegistryAPI of a Redpanda cluster where the object should be created. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-storage)Storage Storage configures storage-related settings in the Helm values. See [Storage for Redpanda in Kubernetes](../../manage/kubernetes/storage/) Appears in: - [RedpandaClusterSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaclusterspec) | Field | Description | | --- | --- | | hostPath string | Specifies the absolute path on the worker node to store the Redpanda data directory. If unspecified, then an emptyDir volume is used. If specified but persistentVolume.enabled is true, storage.hostPath has no effect. | | persistentVolume PersistentVolume | Configures a PersistentVolumeClaim (PVC) template to create for each Pod. This PVC is used to store the Redpanda data directory. | | tiered Tiered | Configures storage for the Tiered Storage cache. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-tls)TLS TLS configures TLS in the Helm values. See [TLS for Redpanda in Kubernetes](../../manage/kubernetes/security/tls/) Appears in: - [RedpandaClusterSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaclusterspec) | Field | Description | | --- | --- | | certs object (keys:string, values:Certificate) | Lists all available certificates in the cluster. You can reference a specific certificate’s name in each listener’s listeners..tls.cert setting. | | enabled boolean | Enables TLS globally for all listeners. Each listener must include a certificate name in its .tls object. To allow you to enable TLS for individual listeners, certificates are always loaded, even if TLS is disabled. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-taskstate)TaskState (string) Task states Appears in: - [ShadowLinkTaskStatus](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-shadowlinktaskstatus) ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-tiered)Tiered Tiered configures storage for the Tiered Storage cache. See [Tiered Storage in Kubernetes](../../manage/kubernetes/tiered-storage/) Appears in: - [Storage](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-storage) | Field | Description | | --- | --- | | mountType string | mountType can be one of:none: Does not mount a volume. Tiered storage will use the same volume as the one defined for the Redpanda data directory.hostPath: Uses the path specified in hostPath on the worker node that the Pod is running on.emptyDir: Mounts an empty directory every time the Pod starts.persistentVolume: Creates and mounts a PersistentVolumeClaim using the template defined in persistentVolume. | | hostPath string | Specifies the absolute path on the worker node to store the Tiered Storage cache. | | persistentVolume PersistentVolume | Configures a PersistentVolumeClaim (PVC) template to create for each Pod. This PVC is used to store the Tiered Storage cache. | | config TieredConfig | Configures Tiered Storage, which requires an Enterprise license configured in enterprise.licenseKey or enterprised.licenseSecretRef. | | credentialsSecretRef CredentialSecretRef | CredentialSecretRef can be used to set cloud_storage_secret_key and/or cloud_storage_access_key from referenced Kubernetes Secret | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-tieredconfig)TieredConfig TieredConfig configures Tiered Storage, which requires an Enterprise license configured in `enterprise.licenseKey` or `enterprise.licenseSecretRef`.TieredConfig is a top-level field of the Helm values. Appears in: - [Tiered](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-tiered) | Field | Description | | --- | --- | | cloud_storage_enabled JSONBoolean | Enables Tiered Storage, if a license key is provided. See Cluster Configuration Properties | | cloud_storage_api_endpoint string | See Cluster Configuration Properties | | cloud_storage_api_endpoint_port integer | See Cluster Configuration Properties | | cloud_storage_bucket string | See Cluster Configuration Properties | | cloud_storage_azure_container string | See Cluster Configuration Properties | | cloud_storage_azure_managed_identity_id string | See Cluster Configuration Properties | | cloud_storage_azure_storage_account string | See Cluster Configuration Properties | | cloud_storage_azure_shared_key string | See Cluster Configuration Properties | | cloud_storage_azure_adls_endpoint string | See Cluster Configuration Properties | | cloud_storage_azure_adls_port integer | See Cluster Configuration Properties | | cloud_storage_cache_check_interval integer | See Cluster Configuration Properties | | cloud_storage_cache_directory string | See Broker Configuration Properties | | cloud_storage_cache_size string | See Cluster Configuration Properties | | cloud_storage_credentials_source string | See Cluster Configuration Properties | | cloud_storage_disable_tls boolean | See Cluster Configuration Properties | | cloud_storage_enable_remote_read boolean | See Cluster Configuration Properties | | cloud_storage_enable_remote_write boolean | See Cluster Configuration Properties | | cloud_storage_initial_backoff_ms integer | See Cluster Configuration Properties | | cloud_storage_manifest_upload_timeout_ms integer | See Cluster Configuration Properties | | cloud_storage_max_connection_idle_time_ms integer | See Cluster Configuration Properties | | cloud_storage_max_connections integer | See Cluster Configuration Properties | | cloud_storage_reconciliation_interval_ms integer | Deprecated: See Cluster Configuration Properties | | cloud_storage_region string | See Cluster Configuration Properties | | cloud_storage_segment_max_upload_interval_sec integer | See Cluster Configuration Properties | | cloud_storage_segment_upload_timeout_ms integer | See Cluster Configuration Properties | | cloud_storage_trust_file string | See Cluster Configuration Properties | | cloud_storage_upload_ctrl_d_coeff integer | See Cluster Configuration Properties | | cloud_storage_upload_ctrl_max_shares integer | See Cluster Configuration Properties | | cloud_storage_upload_ctrl_min_shares integer | See Cluster Configuration Properties | | cloud_storage_upload_ctrl_p_coeff integer | See Cluster Configuration Properties | | cloud_storage_upload_ctrl_update_interval_ms integer | See Cluster Configuration Properties | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-topic)Topic Topic defines the CRD for Topic resources. See [Manage Topics with the Redpanda Operator](../../manage/kubernetes/k-manage-topics/) | Field | Description | | --- | --- | | apiVersion string | cluster.redpanda.com/v1alpha2 | | kind string | Topic | | kind string | Kind is a string value representing the REST resource this object represents.Servers may infer this from the endpoint the client submits requests to.Cannot be updated.In CamelCase.More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | apiVersion string | APIVersion defines the versioned schema of this representation of an object.Servers should convert recognized schemas to the latest internal value, andmay reject unrecognized values.More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | metadata ObjectMeta | Refer to the Kubernetes API documentation for fields of metadata. | | spec TopicSpec | Defines the desired state of the Topic resource. | | status TopicStatus | Represents the current status of the Topic resource. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-topicmetadatasyncoffset)TopicMetadataSyncOffset (string) Appears in: - [ShadowLinkTopicMetadataSyncOptions](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-shadowlinktopicmetadatasyncoptions) ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-topicspec)TopicSpec TopicSpec defines the desired state of the topic. See [Manage Topics with the Redpanda Operator](../../manage/kubernetes/k-manage-topics/) Appears in: - [Topic](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-topic) | Field | Description | | --- | --- | | partitions integer | Specifies the number of topic shards that are distributed across the brokers in a cluster.This number cannot be decreased after topic creation.It can be increased after topic creation, but it isimportant to understand the consequences that has, especially fortopics with semantic partitioning. When absent this will default tothe Redpanda cluster configuration default_topic_partitions.See Cluster Configuration Properties andHow Redpanda Works | | replicationFactor integer | Specifies the number of replicas the topic should have. Must be odd value.When absent this will default to the Redpanda cluster configuration default_topic_replications.See Cluster Configuration Properties | | overwriteTopicName string | Changes the topic name from the value of metadata.name. | | additionalConfig object (keys:string, values:string) | Adds extra topic configurations. This is a free-form map of any configuration options that topics can have.Examples:cleanup.policy=compactredpanda.remote.write=trueredpanda.remote.read=trueredpanda.remote.recovery=trueredpanda.remote.delete=true | | cluster ClusterSource | ClusterSource is a reference to the cluster where the user should be created.It is used in constructing the client created to configure a cluster. | | kafkaApiSpec KafkaAPISpec | Defines client configuration for connecting to Redpanda brokers.Deprecated: Use cluster.staticConfiguration.kafkaApiSpec if explicit connectionconfiguration is required. Otherwise, prefer cluster.clusterRef. | | metricsNamespace string | Overwrites the fully-qualifiedname of the metric. This should be easier to identify ifmultiple operator instances runs inside the same Kubernetes cluster.By default, it is set to redpanda-operator. | | interval Duration | Defines when the topic controller will schedule the next reconciliation.Default is 3 seconds. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-topicstatus)TopicStatus TopicStatus defines the observed state of the Topic resource. Appears in: - [Topic](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-topic) | Field | Description | | --- | --- | | observedGeneration integer | ObservedGeneration is the last observed generation of the Topic. | | conditions Condition array | Conditions holds the conditions for the Topic. | | topicConfiguration Configuration array | TopicConfiguration is the last snapshot of the topic configuration during successful reconciliation. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-topologyspreadconstraints)TopologySpreadConstraints TopologySpreadConstraints configures topology spread constraints to control how Pods are spread across different topology domains. Appears in: - [Statefulset](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-statefulset) | Field | Description | | --- | --- | | maxSkew integer | Defines the maximum skew between the number of Pods in any two topology domains. | | topologyKey string | Specifies the topology key to use for spreading Pods. | | whenUnsatisfiable string | Sets the policy for how to handle unsatisfiable constraints, such as DoNotSchedule or ScheduleAnyway. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-truststore)TrustStore TrustStore is a mapping from a value on either a Secret or ConfigMap to the `truststore_path` field of a listener. Appears in: - [ListenerTLS](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-listenertls) | Field | Description | | --- | --- | | configMapKeyRef ConfigMapKeySelector | | | secretKeyRef SecretKeySelector | | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-tuning)Tuning Tuning configures settings for the autotuner tool in Redpanda. The autotuner identifies the hardware configuration in the container and optimizes the Linux kernel to give you the best performance. Appears in: - [InitContainers](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-initcontainers) - [RedpandaClusterSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-redpandaclusterspec) | Field | Description | | --- | --- | | extraVolumeMounts string | Configures additional volume mounts for the Pod. | | resources ResourceRequirements | Sets resource requirements such as CPU and memory limits. | | ballast_file_path string | Specifies the file path for ballast file. A ballast file is an empty file that takes up disk space. If Redpanda runs out of disk space and becomes unavailable, you can delete the ballast file as a last resort. This clears up some space and gives you time to delete topics or records and change your retention properties. | | ballast_file_size string | Defines the size of the ballast file. | | tune_aio_events boolean | Specifies whether to increase the number of allowed asynchronous IO events. | | tune_ballast_file boolean | Specifies whether to create the ballast file. | | tune_clocksource boolean | Specifies whether to synchronize NTP. | | well_known_io string | Specifies the vendor, VM type, and storage device type that Redpanda runs on, in the format ::. This hints to Redpanda which configuration values it should use for the Redpanda IO scheduler. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-updatestrategy)UpdateStrategy UpdateStrategy configures the update strategy for the StatefulSet to manage how updates are rolled out to the Pods. Appears in: - [Statefulset](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-statefulset) | Field | Description | | --- | --- | | type string | Defines the strategy type for updating the StatefulSet, such as RollingUpdate or OnDelete. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-usagestats)UsageStats UsageStats configures the reporting of usage statistics. Redpanda Data uses these metrics to learn how the software is used, which can guide future improvements. Appears in: - [Logging](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-logging) | Field | Description | | --- | --- | | enabled boolean | Specifies whether usage reporting is enabled. | | organization string | Specifies the name of the organization using the software. This can be useful for identifying and segmenting usage data by organization, if usage reporting is enabled.Deprecated: This value is no longer respected in the redpanda helm chartand will be removed in a future version. | | clusterId string | Specifies the ID of your Redpanda cluster. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-user)User User defines the CRD for a Redpanda user. | Field | Description | | --- | --- | | apiVersion string | cluster.redpanda.com/v1alpha2 | | kind string | User | | kind string | Kind is a string value representing the REST resource this object represents.Servers may infer this from the endpoint the client submits requests to.Cannot be updated.In CamelCase.More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | apiVersion string | APIVersion defines the versioned schema of this representation of an object.Servers should convert recognized schemas to the latest internal value, andmay reject unrecognized values.More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | metadata ObjectMeta | Refer to the Kubernetes API documentation for fields of metadata. | | spec UserSpec | Defines the desired state of the Redpanda user. | | status UserStatus | Represents the current status of the Redpanda user. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-userauthenticationspec)UserAuthenticationSpec UserAuthenticationSpec defines the authentication mechanism enabled for this Redpanda user. Appears in: - [UserSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-userspec) | Field | Description | | --- | --- | | type SASLMechanism | SASL mechanism to use for the user credentials. Valid values are:- scram-sha-512- scram-sha-256 | | password Password | Password specifies where a password is read from. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-userauthorizationspec)UserAuthorizationSpec UserAuthorizationSpec defines authorization rules for this user. Appears in: - [UserSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-userspec) | Field | Description | | --- | --- | | type AuthorizationType | Type specifies the type of authorization to use for User ACLs. If unspecified, defaults to simple. Valid values are:- simple | | acls ACLRule array | List of ACL rules which should be applied to this user. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-userspec)UserSpec UserSpec defines the configuration of a Redpanda user. Appears in: - [User](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-user) | Field | Description | | --- | --- | | cluster ClusterSource | ClusterSource is a reference to the cluster where the user should be created.It is used in constructing the client created to configure a cluster. | | authentication UserAuthenticationSpec | Authentication defines the authentication information for a user. If noAuthentication credentials are specified, then no user will be created.This is useful when wanting to manage ACLs for an already-existing user. | | authorization UserAuthorizationSpec | Authorization rules defined for this user. | | template UserTemplateSpec | Template to specify how user secrets are generated. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-userstatus)UserStatus UserStatus defines the observed state of a Redpanda user Appears in: - [User](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-user) | Field | Description | | --- | --- | | observedGeneration integer | Specifies the last observed generation. | | conditions Condition array | Conditions holds the conditions for the Redpanda user. | | managedAcls boolean | ManagedACLs returns whether the user has managed ACLs that needto be cleaned up. | | managedUser boolean | ManagedUser returns whether the user has a managed SCRAM user that needto be cleaned up. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-usertemplatespec)UserTemplateSpec UserTemplateSpec defines the template metadata (labels and annotations) for any subresources, such as Secrets, created by a User object. Appears in: - [UserSpec](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-userspec) | Field | Description | | --- | --- | | secret ResourceTemplate | Specifies how the Secret with a user password is generated. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-usersitems)UsersItems UsersItems configures a list of superusers in the Helm values. Appears in: - [SASL](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-sasl) | Field | Description | | --- | --- | | mechanism string | Specifies the authentication mechanism to use for superusers. Overrides the default in SASL. Options are SCRAM-SHA-256 and SCRAM-SHA-512. | | name string | Specifies the name of the superuser. | | password string | Specifies the superuser password. | ## [](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-valuesource)ValueSource ValueSource represents where a value can be pulled from Appears in: - [AdminSASL](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-adminsasl) - [CommonTLS](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-commontls) - [KafkaSASL](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-kafkasasl) - [KafkaSASLAWSMskIam](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-kafkasaslawsmskiam) - [KafkaSASLGSSAPI](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-kafkasaslgssapi) - [KafkaSASLOAuthBearer](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-kafkasasloauthbearer) - [SchemaRegistrySASL](#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-schemaregistrysasl) | Field | Description | | --- | --- | | inline string | Inline is the raw value specified inline. | | configMapKeyRef ConfigMapKeySelector | If the value is supplied by a kubernetes object reference, coordinates are embedded here.For target values, the string value fetched from the source will be treated asa raw string. | | secretKeyRef SecretKeySelector | Should the value be contained in a k8s secret rather than configmap, we can referto it here. | | externalSecretRef ExternalSecretKeySelector | If the value is supplied by an external source, coordinates are embedded here.Note: we interpret all fetched external secrets as raw string values | --- # Page 257: Kubernetes Helm Chart Specifications **URL**: https://docs.redpanda.com/current/reference/k-helm-index.md --- # Kubernetes Helm Chart Specifications --- title: Kubernetes Helm Chart Specifications latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: k-helm-index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: k-helm-index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/k-helm-index.adoc description: Explore the properties and values of all Helm charts that are supported by Redpanda. page-git-created-date: "2024-01-04" page-git-modified-date: "2024-01-04" support-status: supported --- - [Redpanda Helm Chart Specification](../k-redpanda-helm-spec/) - [Redpanda Operator Helm Chart Specification](../k-operator-helm-spec/) - [Redpanda Console Helm Chart Specification](../k-console-helm-spec/) - [Redpanda Connectors Helm Chart Specification](../k-connector-helm-spec/) - [Redpanda Connect Chart Specification](../../../redpanda-connect/reference/k-connect-helm-spec/) --- # Page 258: Kubernetes Reference **URL**: https://docs.redpanda.com/current/reference/k-index.md --- # Kubernetes Reference --- title: Kubernetes Reference latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: k-index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: k-index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/k-index.adoc description: Reference topics for Redpanda in Kubernetes. page-git-created-date: "2024-01-04" page-git-modified-date: "2024-01-04" support-status: supported --- - [Kubernetes Helm Chart Specifications](../k-helm-index/) Explore the properties and values of all Helm charts that are supported by Redpanda. - [Kubernetes Custom Resource Definitions](../k-crd-index/) Explore all custom resource definitions (CRDs) that are supported by the Redpanda Operator. --- # Page 259: Redpanda Operator Helm Chart Specification **URL**: https://docs.redpanda.com/current/reference/k-operator-helm-spec.md --- # Redpanda Operator Helm Chart Specification --- title: Redpanda Operator Helm Chart Specification latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: k-operator-helm-spec page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: k-operator-helm-spec.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/k-operator-helm-spec.adoc page-git-created-date: "2024-01-19" page-git-modified-date: "2025-12-04" support-status: supported --- ![Version: 25.2.1](https://img.shields.io/badge/Version-25.2.1-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: v25.2.1](https://img.shields.io/badge/AppVersion-v25.2.1-informational?style=flat-square) This page describes the official Redpanda Operator Helm Chart. In particular, this page describes the contents of the chart’s [`values.yaml` file](./values.yaml). Each of the settings is listed and described on this page, along with any default values. For instructions on how to install and use the chart, including how to override and customize the chart’s values, refer to the [deployment documentation](https://docs.redpanda.com/docs/deploy/deployment-option/self-hosted/kubernetes/kubernetes-deploy/). * * * Autogenerated from chart metadata using [helm-docs v1.11.0](https://github.com/norwoodj/helm-docs/releases/v1.11.0) ## [](#source-code)Source Code - [https://github.com/redpanda-data/redpanda-operator/tree/main/operator/chart](https://github.com/redpanda-data/redpanda-operator/tree/main/operator/chart) ## [](#requirements)Requirements Kubernetes: `>= 1.25.0-0` ## [](#settings)Settings ### [](#additionalcmdflags)[additionalCmdFlags](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=additionalCmdFlags) Passes additional flags to the Redpanda Operator at startup. Additional flags include: - `--additional-controllers`: Additional controllers to deploy. Valid values are nodeWatcher or decommission. For more information about the Nodewatcher controller, see [Install the Nodewatcher controller](https://docs.redpanda.com/current/manage/kubernetes/k-scale-redpanda/#node-pvc). For more information about the Decommission controller, see [Use the Decommission controller](https://docs.redpanda.com/current/manage/kubernetes/k-decommission-brokers/#Automated). **Default:** `[]` ### [](#affinity)[affinity](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=affinity) Sets affinity constraints for scheduling Pods that run the Redpanda Operator. For details, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity). **Default:** `{}` ### [](#clusterdomain)[clusterDomain](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=clusterDomain) Sets the Kubernetes cluster domain. **Default:** `"cluster.local"` ### [](#commonlabels)[commonLabels](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=commonLabels) Additional labels to add to all Kubernetes objects. For example, `my.k8s.service: redpanda-operator`. **Default:** `{}` ### [](#config)[config](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=config) Configuration for the Kubernetes Controller Manager used by Redpanda Operator. The Controller Manager is a component of the Kubernetes control plane that runs controller processes. These controllers are background threads that handle the orchestration and operational logic of Kubernetes, ensuring the desired state of the cluster matches the observed state. **Default:** {"apiVersion":"controller-runtime.sigs.k8s.io/v1alpha1","health":{"healthProbeBindAddress":":8081"},"kind":"ControllerManagerConfig","leaderElection":{"leaderElect":true,"resourceName":"aa9fc693.vectorized.io"},"metrics":{"bindAddress":"127.0.0.1:8080"},"webhook":{"port":9443}} ### [](#config-health)[config.health](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=config.health) Configuration for health checking. **Default:** {"healthProbeBindAddress":":8081"} ### [](#config-health-healthprobebindaddress)[config.health.healthProbeBindAddress](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=config.health.healthProbeBindAddress) Sets the address for the health probe server to listen on. **Default:** `":8081"` ### [](#config-leaderelection)[config.leaderElection](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=config.leaderElection) Configuration for leader election, which is a process that ensures only one instance of the controller manager is active at a time. This is critical for high availability and to prevent split-brain scenarios in a distributed system. **Default:** {"leaderElect":true,"resourceName":"aa9fc693.vectorized.io"} ### [](#config-leaderelection-leaderelect)[config.leaderElection.leaderElect](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=config.leaderElection.leaderElect) Enables leader election. **Default:** `true` ### [](#config-leaderelection-resourcename)[config.leaderElection.resourceName](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=config.leaderElection.resourceName) Sets the name of the resource lock for the leader election process. **Default:** `"aa9fc693.vectorized.io"` ### [](#config-metrics)[config.metrics](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=config.metrics) Configuration for the metrics endpoint. **Default:** {"bindAddress":"127.0.0.1:8080"} ### [](#config-metrics-bindaddress)[config.metrics.bindAddress](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=config.metrics.bindAddress) Sets the address for the metrics server to bind to. **Default:** `"127.0.0.1:8080"` ### [](#config-webhook)[config.webhook](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=config.webhook) Configuration for webhooks, such as the port they listen on. Webhooks are HTTP callbacks that receive and process data in response to events. **Default:** `{"port":9443}` ### [](#config-webhook-port)[config.webhook.port](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=config.webhook.port) Sets the port for the webhook server to listen on. **Default:** `9443` ### [](#crds)[crds](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=crds) Flags to control CRD installation. **Default:** {"enabled":false,"experimental":false} ### [](#crds-enabled)[crds.enabled](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=crds.enabled) Specifies whether to install stable CRDs. **Default:** `false` ### [](#crds-experimental)[crds.experimental](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=crds.experimental) Specifies whether to install experimental CRDs. If this is true both experimental and stable CRDs will be installed. **Default:** `false` ### [](#fullnameoverride)[fullnameOverride](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=fullnameOverride) Overrides the `redpanda-operator.fullname` template. **Default:** `""` ### [](#image)[image](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=image) Container image settings. **Default:** {"pullPolicy":"IfNotPresent","repository":"docker.redpanda.com/redpandadata/redpanda-operator"} ### [](#image-pullpolicy)[image.pullPolicy](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=image.pullPolicy) Sets the `pullPolicy` for the `redpanda-operator` image. **Default:** `"IfNotPresent"` ### [](#image-repository)[image.repository](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=image.repository) Sets the repository from which to pull the `redpanda-operator` image. **Default:** "docker.redpanda.com/redpandadata/redpanda-operator" ### [](#imagepullsecrets)[imagePullSecrets](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=imagePullSecrets) Pull secrets may be used to provide credentials to image repositories See the [Kubernetes documentation](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/). **Default:** `[]` ### [](#loglevel)[logLevel](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=logLevel) Log level Valid values (from least to most verbose) are: `warn`, `info`, `debug`, and `trace`. **Default:** `"info"` ### [](#monitoring)[monitoring](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=monitoring) Configuration for monitoring. **Default:** `{"enabled":false}` ### [](#monitoring-enabled)[monitoring.enabled](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=monitoring.enabled) Creates a ServiceMonitor that can be used by Prometheus-Operator or VictoriaMetrics-Operator to scrape the metrics. **Default:** `false` ### [](#nameoverride)[nameOverride](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=nameOverride) Overrides the `redpanda-operator.name` template. **Default:** `""` ### [](#nodeselector)[nodeSelector](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=nodeSelector) Node selection constraints for scheduling Pods on specific nodes. For details, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#nodeselector). **Default:** `{}` ### [](#podannotations)[podAnnotations](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=podAnnotations) **Default:** `{}` ### [](#podlabels)[podLabels](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=podLabels) **Default:** `{}` ### [](#podtemplate)[podTemplate](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=podTemplate) Sets almost all fields of operator Deployment PodTemplate For details, see the [Kubernetes documentation](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-template-v1/#PodTemplateSpec). **Default:** {"metadata":{},"spec":{"containers":\[{"name":"manager","resources":{}}\],"securityContext":{"runAsUser":65532}}} ### [](#podtemplate-spec)[podTemplate.spec](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=podTemplate.spec) A subset of Kubernetes’ PodSpec type that will be merged into the final PodSpec. See [Merge Semantics](#merging-semantics) for details. **Default:** {"containers":\[{"name":"manager","resources":{}}\],"securityContext":{"runAsUser":65532}} ### [](#rbac)[rbac](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=rbac) Role-based Access Control (RBAC) configuration for the Redpanda Operator. **Default:** {"create":true,"createAdditionalControllerCRs":true} ### [](#rbac-create)[rbac.create](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=rbac.create) Enables the creation of additional RBAC roles. **Default:** `true` ### [](#rbac-createadditionalcontrollercrs)[rbac.createAdditionalControllerCRs](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=rbac.createAdditionalControllerCRs) Create RBAC cluster roles needed for the Redpanda Helm chart’s \`rbac.enabled' feature. WARNING: Disabling this value may prevent the operator from deploying certain configurations of redpanda. **Default:** `true` ### [](#replicacount)[replicaCount](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=replicaCount) Sets the number of instances of the Redpanda Operator to deploy. Each instance is deployed as a Pod. All instances are managed by a Deployment resource. **Default:** `1` ### [](#resources)[resources](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=resources) Sets resources requests/limits for Redpanda Operator Pods. By default requests and limits are not set to increase the chances that the charts run on environments with few resources, such as Minikube. To specify resources, uncomment the following lines, adjust them as necessary, and remove the curly braces after `resources`. **Default:** `{}` ### [](#serviceaccount)[serviceAccount](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=serviceAccount) Service account management. **Default:** {"automountServiceAccountToken":false,"create":true} ### [](#serviceaccount-automountserviceaccounttoken)[serviceAccount.automountServiceAccountToken](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=serviceAccount.automountServiceAccountToken) Specifies whether a service account should automount API-Credentials. The token is used in sidecars.controllers **Default:** `false` ### [](#serviceaccount-create)[serviceAccount.create](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=serviceAccount.create) Specifies whether a service account should be created. **Default:** `true` ### [](#strategy)[strategy](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=strategy) Sets deployment strategy. For details, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#strategy). **Default:** `{"type":"RollingUpdate"}` ### [](#tolerations)[tolerations](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=tolerations) Taints to be tolerated by Pods. For details, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/). **Default:** `[]` ### [](#webhook)[webhook](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=webhook) Specifies whether to create Webhook resources both to intercept and potentially modify or reject Kubernetes API requests as well as authenticate requests to the Kubernetes API. Only valid when `scope` is set to Cluster. **Default:** `{"enabled":false}` ### [](#webhook-enabled)[webhook.enabled](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=webhook.enabled) Creates the Webhook resources. **Default:** `false` ### [](#webhooksecretname)[webhookSecretName](https://artifacthub.io/packages/helm/redpanda-data/operator?modal=values&path=webhookSecretName) **Default:** `"webhook-server-cert"` --- # Page 260: Redpanda Helm Chart Specification **URL**: https://docs.redpanda.com/current/reference/k-redpanda-helm-spec.md --- # Redpanda Helm Chart Specification --- title: Redpanda Helm Chart Specification latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: k-redpanda-helm-spec page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: k-redpanda-helm-spec.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/k-redpanda-helm-spec.adoc page-git-created-date: "2024-01-04" page-git-modified-date: "2025-12-04" support-status: supported --- ![Version: 25.2.1](https://img.shields.io/badge/Version-25.2.1-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: v25.2.11](https://img.shields.io/badge/AppVersion-v25.2.11-informational?style=flat-square) This page describes the official Redpanda Helm Chart. In particular, this page describes the contents of the chart’s [`values.yaml` file](https://github.com/redpanda-data/helm-charts/blob/main/charts/redpanda/chart/values.yaml). Each of the settings is listed and described on this page, along with any default values. For instructions on how to install and use the chart, including how to override and customize the chart’s values, refer to the [deployment documentation](https://docs.redpanda.com/docs/deploy/deployment-option/self-hosted/kubernetes/kubernetes-deploy/). * * * Autogenerated from chart metadata using [helm-docs v1.11.0](https://github.com/norwoodj/helm-docs/releases/v1.11.0) ## [](#source-code)Source Code - [https://github.com/redpanda-data/redpanda-operator/tree/main/charts/redpanda](https://github.com/redpanda-data/redpanda-operator/tree/main/charts/redpanda) ## [](#requirements)Requirements Kubernetes: `>= 1.25.0-0` | Repository | Name | Version | | --- | --- | --- | | file://../../console/chart | console | >=3.3.0-0 | ## [](#settings)Settings ### [](#auditlogging)[auditLogging](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=auditLogging) Audit logging for a redpanda cluster, must have enabled sasl and have one kafka listener supporting sasl authentication for audit logging to work. Note this feature is only available for redpanda versions >= v23.3.0. **Default:** {"clientMaxBufferSize":16777216,"enabled":false,"enabledEventTypes":null,"excludedPrincipals":null,"excludedTopics":null,"listener":"internal","partitions":12,"queueDrainIntervalMs":500,"queueMaxBufferSizePerShard":1048576,"replicationFactor":null} ### [](#auditlogging-clientmaxbuffersize)[auditLogging.clientMaxBufferSize](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=auditLogging.clientMaxBufferSize) Defines the number of bytes (in bytes) allocated by the internal audit client for audit messages. **Default:** `16777216` ### [](#auditlogging-enabled)[auditLogging.enabled](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=auditLogging.enabled) Enable or disable audit logging, for production clusters we suggest you enable, however, this will only work if you also enable sasl and a listener with sasl enabled. **Default:** `false` ### [](#auditlogging-enabledeventtypes)[auditLogging.enabledEventTypes](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=auditLogging.enabledEventTypes) Event types that should be captured by audit logs, default is \[`admin`, `authenticate`, `management`\]. **Default:** `nil` ### [](#auditlogging-excludedprincipals)[auditLogging.excludedPrincipals](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=auditLogging.excludedPrincipals) List of principals to exclude from auditing, default is null. **Default:** `nil` ### [](#auditlogging-excludedtopics)[auditLogging.excludedTopics](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=auditLogging.excludedTopics) List of topics to exclude from auditing, default is null. **Default:** `nil` ### [](#auditlogging-listener)[auditLogging.listener](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=auditLogging.listener) Kafka listener name, note that it must have `authenticationMethod` set to `sasl`. For external listeners, use the external listener name, such as `default`. **Default:** `"internal"` ### [](#auditlogging-partitions)[auditLogging.partitions](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=auditLogging.partitions) Integer value defining the number of partitions used by a newly created audit topic. **Default:** `12` ### [](#auditlogging-queuedrainintervalms)[auditLogging.queueDrainIntervalMs](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=auditLogging.queueDrainIntervalMs) In ms, frequency in which per shard audit logs are batched to client for write to audit log. **Default:** `500` ### [](#auditlogging-queuemaxbuffersizepershard)[auditLogging.queueMaxBufferSizePerShard](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=auditLogging.queueMaxBufferSizePerShard) Defines the maximum amount of memory used (in bytes) by the audit buffer in each shard. **Default:** `1048576` ### [](#auditlogging-replicationfactor)[auditLogging.replicationFactor](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=auditLogging.replicationFactor) Defines the replication factor for a newly created audit log topic. This configuration applies only to the audit log topic and may be different from the cluster or other topic configurations. This cannot be altered for existing audit log topics. Setting this value is optional. If a value is not provided, Redpanda will use the `internal_topic_replication_factor cluster` config value. Default is `null` **Default:** `nil` ### [](#auth)[auth](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=auth) Authentication settings. For details, see the [SASL documentation](https://docs.redpanda.com/docs/manage/kubernetes/security/sasl-kubernetes/). **Default:** {"sasl":{"bootstrapUser":{"mechanism":"SCRAM-SHA-256"},"enabled":false,"mechanism":"SCRAM-SHA-512","secretRef":"redpanda-users","users":\[\]}} ### [](#auth-sasl-bootstrapuser)[auth.sasl.bootstrapUser](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=auth.sasl.bootstrapUser) Details about how to create the bootstrap user for the cluster. The secretKeyRef is optionally specified. If it is specified, the chart will use a password written to that secret when creating the `kubernetes-controller'' bootstrap user. If it is unspecified, then the secret will be generated and stored in the secret` releasename''-bootstrap-user, with the key \`\`password''. **Default:** {"mechanism":"SCRAM-SHA-256"} ### [](#auth-sasl-bootstrapuser-mechanism)[auth.sasl.bootstrapUser.mechanism](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=auth.sasl.bootstrapUser.mechanism) The authentication mechanism to use for the bootstrap user. Options are `SCRAM-SHA-256` and `SCRAM-SHA-512`. **Default:** `"SCRAM-SHA-256"` ### [](#auth-sasl-enabled)[auth.sasl.enabled](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=auth.sasl.enabled) Enable SASL authentication. If you enable SASL authentication, you must provide a Secret in `auth.sasl.secretRef`. **Default:** `false` ### [](#auth-sasl-mechanism)[auth.sasl.mechanism](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=auth.sasl.mechanism) The authentication mechanism to use for the superuser. Options are `SCRAM-SHA-256` and `SCRAM-SHA-512`. **Default:** `"SCRAM-SHA-512"` ### [](#auth-sasl-secretref)[auth.sasl.secretRef](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=auth.sasl.secretRef) A Secret that contains your superuser credentials. For details, see the [SASL documentation](https://docs.redpanda.com/docs/manage/kubernetes/security/sasl-kubernetes/#use-secrets). **Default:** `"redpanda-users"` ### [](#auth-sasl-users)[auth.sasl.users](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=auth.sasl.users) Optional list of superusers. These superusers will be created in the Secret whose name is defined in `auth.sasl.secretRef`. If this list is empty, the Secret in `auth.sasl.secretRef` must already exist in the cluster before you deploy the chart. Uncomment the sample list if you wish to try adding sample sasl users or override to use your own. **Default:** `[]` ### [](#clusterdomain)[clusterDomain](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=clusterDomain) Default Kubernetes cluster domain. **Default:** `"cluster.local."` ### [](#commonlabels)[commonLabels](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=commonLabels) Additional labels to add to all Kubernetes objects. For example, `my.k8s.service: redpanda`. **Default:** `{}` ### [](#config)[config](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=config) This section contains various settings supported by Redpanda that may not work correctly in a Kubernetes cluster. Changing these settings comes with some risk. Use these settings to customize various Redpanda configurations that are not covered in other sections. These values have no impact on the configuration or behavior of the Kubernetes objects deployed by Helm, and therefore should not be modified for the purpose of configuring those objects. Instead, these settings get passed directly to the Redpanda binary at startup. For descriptions of these properties, see the [configuration documentation](https://docs.redpanda.com/docs/cluster-administration/configuration/). **Default:** {"cluster":{},"extraClusterConfiguration":{},"node":{"crash\_loop\_limit":5},"pandaproxy\_client":{},"rpk":{},"schema\_registry\_client":{},"tunable":{"compacted\_log\_segment\_size":67108864,"kafka\_connection\_rate\_limit":1000,"log\_segment\_size\_max":268435456,"log\_segment\_size\_min":16777216,"max\_compacted\_log\_segment\_size":536870912}} ### [](#config-cluster)[config.cluster](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=config.cluster) [Cluster Configuration Properties](https://docs.redpanda.com/current/reference/properties/cluster-properties/) **Default:** `{}` ### [](#config-node)[config.node](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=config.node) [Broker (node) Configuration Properties](https://docs.redpanda.com/docs/reference/broker-properties/). **Default:** `{"crash_loop_limit":5}` ### [](#config-node-crash_loop_limit)[config.node.crash\_loop\_limit](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=config.node.crash_loop_limit) Crash loop limit A limit on the number of consecutive times a broker can crash within one hour before its crash-tracking logic is reset. This limit prevents a broker from getting stuck in an infinite cycle of crashes. User can disable this crash loop limit check by the following action: \* One hour elapses since the last crash \* The node configuration file, redpanda.yaml, is updated via config.cluster or config.node or config.tunable objects \* The startup\_log file in the node’s data\_directory is manually deleted Default to 5 REF: [https://docs.redpanda.com/current/reference/broker-properties/#crash\_loop\_limit](https://docs.redpanda.com/current/reference/broker-properties/#crash_loop_limit) **Default:** `5` ### [](#config-tunable)[config.tunable](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=config.tunable) Tunable cluster properties. Deprecated: all settings here may be specified via `config.cluster`. **Default:** {"compacted\_log\_segment\_size":67108864,"kafka\_connection\_rate\_limit":1000,"log\_segment\_size\_max":268435456,"log\_segment\_size\_min":16777216,"max\_compacted\_log\_segment\_size":536870912} ### [](#config-tunable-compacted_log_segment_size)[config.tunable.compacted\_log\_segment\_size](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=config.tunable.compacted_log_segment_size) See the [property reference documentation](https://docs.redpanda.com/docs/reference/cluster-properties/#compacted_log_segment_size). **Default:** `67108864` ### [](#config-tunable-kafka_connection_rate_limit)[config.tunable.kafka\_connection\_rate\_limit](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=config.tunable.kafka_connection_rate_limit) See the [property reference documentation](https://docs.redpanda.com/docs/reference/cluster-properties/#kafka_connection_rate_limit). **Default:** `1000` ### [](#config-tunable-log_segment_size_max)[config.tunable.log\_segment\_size\_max](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=config.tunable.log_segment_size_max) See the [property reference documentation](https://docs.redpanda.com/docs/reference/cluster-properties/#log_segment_size_max). **Default:** `268435456` ### [](#config-tunable-log_segment_size_min)[config.tunable.log\_segment\_size\_min](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=config.tunable.log_segment_size_min) See the [property reference documentation](https://docs.redpanda.com/docs/reference/cluster-properties/#log_segment_size_min). **Default:** `16777216` ### [](#config-tunable-max_compacted_log_segment_size)[config.tunable.max\_compacted\_log\_segment\_size](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=config.tunable.max_compacted_log_segment_size) See the [property reference documentation](https://docs.redpanda.com/docs/reference/cluster-properties/#max_compacted_log_segment_size). **Default:** `536870912` ### [](#console)[console](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=console) Redpanda Console settings. For a reference of configuration settings, see the [Redpanda Console documentation](https://docs.redpanda.com/docs/reference/console/config/). **Default:** {"config":{},"configmap":{"create":false},"deployment":{"create":false},"enabled":true,"secret":{"create":false}} ### [](#enterprise)[enterprise](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=enterprise) Enterprise (optional) For details, see the [License documentation](https://docs.redpanda.com/docs/get-started/licenses/?platform=kubernetes#redpanda-enterprise-edition). **Default:** {"license":"","licenseSecretRef":null} ### [](#enterprise-license)[enterprise.license](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=enterprise.license) license (optional). **Default:** `""` ### [](#enterprise-licensesecretref)[enterprise.licenseSecretRef](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=enterprise.licenseSecretRef) Secret name and key where the license key is stored. **Default:** `nil` ### [](#external)[external](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=external) External access settings. For details, see the [Networking and Connectivity documentation](https://docs.redpanda.com/docs/manage/kubernetes/networking/networking-and-connectivity/). **Default:** {"enabled":true,"service":{"enabled":true},"type":"NodePort"} ### [](#external-enabled)[external.enabled](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=external.enabled) Enable external access for each Service. You can toggle external access for each listener in `listeners..external..enabled`. **Default:** `true` ### [](#external-service)[external.service](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=external.service) Service allows you to manage the creation of an external kubernetes service object **Default:** `{"enabled":true}` ### [](#external-service-enabled)[external.service.enabled](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=external.service.enabled) Enabled if set to false will not create the external service type You can still set your cluster with external access but not create the supporting service (NodePort/LoadBalander). Set this to false if you rather manage your own service. **Default:** `true` ### [](#external-type)[external.type](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=external.type) External access type. Only `NodePort` and `LoadBalancer` are supported. If undefined, then advertised listeners will be configured in Redpanda, but the helm chart will not create a Service. You must create a Service manually. Warning: If you use LoadBalancers, you will likely experience higher latency and increased packet loss. NodePort is recommended in cases where latency is a priority. **Default:** `"NodePort"` ### [](#fullnameoverride)[fullnameOverride](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=fullnameOverride) Override `redpanda.fullname` template. **Default:** `""` ### [](#image)[image](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=image) Redpanda Docker image settings. **Default:** {"repository":"docker.redpanda.com/redpandadata/redpanda","tag":""} ### [](#image-repository)[image.repository](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=image.repository) Docker repository from which to pull the Redpanda Docker image. **Default:** "docker.redpanda.com/redpandadata/redpanda" ### [](#image-tag)[image.tag](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=image.tag) The Redpanda version. See DockerHub for: [All stable versions](https://hub.docker.com/r/redpandadata/redpanda/tags) and [all unstable versions](https://hub.docker.com/r/redpandadata/redpanda-unstable/tags). **Default:** `Chart.appVersion`. ### [](#listeners)[listeners](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=listeners) Listener settings. Override global settings configured above for individual listeners. For details, see the [listeners documentation](https://docs.redpanda.com/docs/manage/kubernetes/networking/configure-listeners/). **Default:** {"admin":{"external":{"default":{"advertisedPorts":\[31644\],"port":9645,"tls":{"cert":"external"}}},"port":9644,"tls":{"cert":"default","requireClientAuth":false}},"http":{"authenticationMethod":null,"enabled":true,"external":{"default":{"advertisedPorts":\[30082\],"authenticationMethod":null,"port":8083,"tls":{"cert":"external","requireClientAuth":false}}},"port":8082,"tls":{"cert":"default","requireClientAuth":false}},"kafka":{"authenticationMethod":null,"external":{"default":{"advertisedPorts":\[31092\],"authenticationMethod":null,"port":9094,"tls":{"cert":"external"}}},"port":9093,"tls":{"cert":"default","requireClientAuth":false}},"rpc":{"port":33145,"tls":{"cert":"default","requireClientAuth":false}},"schemaRegistry":{"authenticationMethod":null,"enabled":true,"external":{"default":{"advertisedPorts":\[30081\],"authenticationMethod":null,"port":8084,"tls":{"cert":"external","requireClientAuth":false}}},"port":8081,"tls":{"cert":"default","requireClientAuth":false}}} ### [](#listeners-admin)[listeners.admin](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=listeners.admin) Admin API listener (only one). **Default:** {"external":{"default":{"advertisedPorts":\[31644\],"port":9645,"tls":{"cert":"external"}}},"port":9644,"tls":{"cert":"default","requireClientAuth":false}} ### [](#listeners-admin-external)[listeners.admin.external](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=listeners.admin.external) Optional external access settings. **Default:** {"default":{"advertisedPorts":\[31644\],"port":9645,"tls":{"cert":"external"}}} ### [](#listeners-admin-external-default)[listeners.admin.external.default](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=listeners.admin.external.default) Name of the external listener. **Default:** {"advertisedPorts":\[31644\],"port":9645,"tls":{"cert":"external"}} ### [](#listeners-admin-external-default-tls)[listeners.admin.external.default.tls](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=listeners.admin.external.default.tls) The port advertised to this listener’s external clients. List one port if you want to use the same port for each broker (would be the case when using NodePort service). Otherwise, list the port you want to use for each broker in order of StatefulSet replicas. If undefined, `listeners.admin.port` is used. **Default:** `{"cert":"external"}` ### [](#listeners-admin-port)[listeners.admin.port](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=listeners.admin.port) The port for both internal and external connections to the Admin API. **Default:** `9644` ### [](#listeners-admin-tls)[listeners.admin.tls](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=listeners.admin.tls) Optional TLS section (required if global TLS is enabled) **Default:** {"cert":"default","requireClientAuth":false} ### [](#listeners-admin-tls-cert)[listeners.admin.tls.cert](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=listeners.admin.tls.cert) Name of the Certificate used for TLS (must match a Certificate name that is registered in tls.certs). **Default:** `"default"` ### [](#listeners-admin-tls-requireclientauth)[listeners.admin.tls.requireClientAuth](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=listeners.admin.tls.requireClientAuth) If true, the truststore file for this listener is included in the ConfigMap. **Default:** `false` ### [](#listeners-http)[listeners.http](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=listeners.http) HTTP API listeners (aka PandaProxy). **Default:** {"authenticationMethod":null,"enabled":true,"external":{"default":{"advertisedPorts":\[30082\],"authenticationMethod":null,"port":8083,"tls":{"cert":"external","requireClientAuth":false}}},"port":8082,"tls":{"cert":"default","requireClientAuth":false}} ### [](#listeners-kafka)[listeners.kafka](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=listeners.kafka) Kafka API listeners. **Default:** {"authenticationMethod":null,"external":{"default":{"advertisedPorts":\[31092\],"authenticationMethod":null,"port":9094,"tls":{"cert":"external"}}},"port":9093,"tls":{"cert":"default","requireClientAuth":false}} ### [](#listeners-kafka-external-default-advertisedports)[listeners.kafka.external.default.advertisedPorts](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=listeners.kafka.external.default.advertisedPorts) If undefined, `listeners.kafka.external.default.port` is used. **Default:** `[31092]` ### [](#listeners-kafka-external-default-port)[listeners.kafka.external.default.port](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=listeners.kafka.external.default.port) The port used for external client connections. **Default:** `9094` ### [](#listeners-kafka-port)[listeners.kafka.port](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=listeners.kafka.port) The port for internal client connections. **Default:** `9093` ### [](#listeners-rpc)[listeners.rpc](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=listeners.rpc) RPC listener (this is never externally accessible). **Default:** {"port":33145,"tls":{"cert":"default","requireClientAuth":false}} ### [](#listeners-schemaregistry)[listeners.schemaRegistry](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=listeners.schemaRegistry) Schema registry listeners. **Default:** {"authenticationMethod":null,"enabled":true,"external":{"default":{"advertisedPorts":\[30081\],"authenticationMethod":null,"port":8084,"tls":{"cert":"external","requireClientAuth":false}}},"port":8081,"tls":{"cert":"default","requireClientAuth":false}} ### [](#logging)[logging](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=logging) Log-level settings. **Default:** {"logLevel":"info","usageStats":{"enabled":true}} ### [](#logging-loglevel)[logging.logLevel](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=logging.logLevel) Log level Valid values (from least to most verbose) are: `warn`, `info`, `debug`, and `trace`. **Default:** `"info"` ### [](#logging-usagestats)[logging.usageStats](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=logging.usageStats) Send usage statistics back to Redpanda Data. For details, see the [stats reporting documentation](https://docs.redpanda.com/docs/cluster-administration/monitoring/#stats-reporting). **Default:** `{"enabled":true}` ### [](#monitoring)[monitoring](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=monitoring) Monitoring. This will create a ServiceMonitor that can be used by Prometheus-Operator or VictoriaMetrics-Operator to scrape the metrics. **Default:** {"enabled":false,"labels":{},"scrapeInterval":"30s"} ### [](#nameoverride)[nameOverride](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=nameOverride) Override `redpanda.name` template. **Default:** `""` ### [](#podtemplate-annotations)[podTemplate.annotations](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=podTemplate.annotations) Annotations to apply (or overwrite the default) to all Pods of this Chart. **Default:** `{}` ### [](#podtemplate-labels)[podTemplate.labels](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=podTemplate.labels) Labels to apply (or overwrite the default) to all Pods of this Chart. **Default:** `{}` ### [](#podtemplate-spec)[podTemplate.spec](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=podTemplate.spec) A subset of Kubernetes’ PodSpec type that will be merged into the PodSpec of all Pods for this Chart. See [Merge Semantics](#merging-semantics) for details. **Default:** {"imagePullSecrets":\[\],"securityContext":{"fsGroup":101,"fsGroupChangePolicy":"OnRootMismatch","runAsUser":101}} ### [](#podtemplate-spec-imagepullsecrets)[podTemplate.spec.imagePullSecrets](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=podTemplate.spec.imagePullSecrets) Pull secrets may be used to provide credentials to image repositories See the [Kubernetes documentation](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/). **Default:** `[]` ### [](#post_install_job-enabled)[post\_install\_job.enabled](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=post_install_job.enabled) **Default:** `true` ### [](#post_install_job-podtemplate-annotations)[post\_install\_job.podTemplate.annotations](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=post_install_job.podTemplate.annotations) Annotations to apply (or overwrite the default) to the Pods of this Job. **Default:** `{}` ### [](#post_install_job-podtemplate-labels)[post\_install\_job.podTemplate.labels](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=post_install_job.podTemplate.labels) Labels to apply (or overwrite the default) to the Pods of this Job. **Default:** `{}` ### [](#post_install_job-podtemplate-spec)[post\_install\_job.podTemplate.spec](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=post_install_job.podTemplate.spec) A subset of Kubernetes’ PodSpec type that will be merged into the final PodSpec. See [Merge Semantics](#merging-semantics) for details. **Default:** {"containers":\[{"env":\[\],"name":"post-install","securityContext":{}}\],"securityContext":{}} ### [](#rackawareness)[rackAwareness](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=rackAwareness) Rack Awareness settings. For details, see the [Rack Awareness documentation](https://docs.redpanda.com/docs/manage/kubernetes/kubernetes-rack-awareness/). **Default:** {"enabled":false,"nodeAnnotation":"topology.kubernetes.io/zone"} ### [](#rackawareness-enabled)[rackAwareness.enabled](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=rackAwareness.enabled) When running in multiple racks or availability zones, use a Kubernetes Node annotation value as the Redpanda rack value. Enabling this requires running with a service account with `` `get'' Node permissions. To have the Helm chart configure these permissions, set `serviceAccount.create=true `` and `rbac.enabled=true`. **Default:** `false` ### [](#rackawareness-nodeannotation)[rackAwareness.nodeAnnotation](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=rackAwareness.nodeAnnotation) The common well-known annotation to use as the rack ID. Override this only if you use a custom Node annotation. **Default:** "topology.kubernetes.io/zone" ### [](#rbac)[rbac](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=rbac) Role Based Access Control. **Default:** {"annotations":{},"enabled":true,"rpkDebugBundle":true} ### [](#rbac-annotations)[rbac.annotations](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=rbac.annotations) Annotations to add to the `rbac` resources. **Default:** `{}` ### [](#rbac-enabled)[rbac.enabled](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=rbac.enabled) Controls whether or not Roles, ClusterRoles, and bindings thereof will be generated. Disabling this very likely result in a non-functional deployment. **Default:** `true` ### [](#rbac-rpkdebugbundle)[rbac.rpkDebugBundle](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=rbac.rpkDebugBundle) Controls whether or not a Role and RoleBinding will be generated for the permissions required by `rpk debug bundle`. Disabling will not affect the redpanda deployment itself but a bundle is required to engage with our support. **Default:** `true` ### [](#resources)[resources](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=resources) Pod resource management. This section simplifies resource allocation for the redpanda container by providing a single location where resources are defined. Resources may be specified by either setting `resources.cpu` and `resources.memory` (the default) or by setting `resources.requests` and `resources.limits`. For details on `resources.cpu` and `resources.memory`, see their respective documentation below. When `resources.limits` and `resources.requests` are set, the redpanda container’s resources will be set to exactly the provided values. This allows users to granularly control limits and requests to best suit their use case. For example: `resources.requests.cpu` may be set without setting `resources.limits.cpu` to avoid the potential of CPU throttling. Redpanda’s resource related CLI flags will then be calculated as follows: \* `--smp max(1, floor(coalesce(resources.requests.cpu, resources.limits.cpu)))` \* `--memory coalesce(resources.requests.memory, resources.limits.memory) * 90%` \* `--reserve-memory 0` \* `--overprovisioned coalesce(resources.requests.cpu, resources.limits.cpu) < 1000m` If neither a request nor a limit is provided for cpu or memory, the corresponding flag will be omitted. As a result, setting `resources.limits` and `resources.requests` to `{}` will result in redpanda being run without `--smp` or `--memory`. (This is not recommended). If the computed CLI flags are undesirable, they may be overridden by specifying the desired value through `statefulset.additionalRedpandaCmdFlags`. The default values are for a development environment. Production-level values and other considerations are documented, where those values are different from the default. For details, see the [Pod resources documentation](https://docs.redpanda.com/docs/manage/kubernetes/manage-resources/). **Default:** {"cpu":{"cores":1},"memory":{"container":{"max":"2.5Gi"}}} ### [](#resources-cpu)[resources.cpu](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=resources.cpu) CPU resources. For details, see the [Pod resources documentation](https://docs.redpanda.com/docs/manage/kubernetes/manage-resources/#configure-cpu-resources). **Default:** `{"cores":1}` ### [](#resources-cpu-cores)[resources.cpu.cores](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=resources.cpu.cores) Redpanda makes use of a thread per core model. For details, see this [blog](https://redpanda.com/blog/tpc-buffers). For this reason, Redpanda should only be given full cores. Note: You can increase cores, but decreasing cores is supported only from 24.3 Redpanda version. This setting is equivalent to `--smp`, `resources.requests.cpu`, and `resources.limits.cpu`. For production, use `4` or greater. To maximize efficiency, use the `static` CPU manager policy by specifying an even integer for CPU resource requests and limits. This policy gives the Pods running Redpanda brokers access to exclusive CPUs on the node. See [https://kubernetes.io/docs/tasks/administer-cluster/cpu-management-policies/#static-policy](https://kubernetes.io/docs/tasks/administer-cluster/cpu-management-policies/#static-policy). **Default:** `1` ### [](#resources-memory)[resources.memory](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=resources.memory) Memory resources For details, see the [Pod resources documentation](https://docs.redpanda.com/docs/manage/kubernetes/manage-resources/#configure-memory-resources). **Default:** {"container":{"max":"2.5Gi"}} ### [](#resources-memory-container)[resources.memory.container](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=resources.memory.container) Enables memory locking. For production, set to `true`. enable\_memory\_locking: false It is recommended to have at least 2Gi of memory per core for the Redpanda binary. This memory is taken from the total memory given to each container. The Helm chart allocates 80% of the container’s memory to Redpanda, leaving the rest for other container processes. So at least 2.5Gi per core is recommended in order to ensure Redpanda has a full 2Gi. These values affect `--memory` and `--reserve-memory` flags passed to Redpanda and the memory requests/limits in the StatefulSet. Valid suffixes: k, M, G, T, P, Ki, Mi, Gi, Ti, Pi To create `Guaranteed` Pod QoS for Redpanda brokers, provide both container max and min values for the container. For details, see [https://kubernetes.io/docs/tasks/configure-pod-container/quality-service-pod/#create-a-pod-that-gets-assigned-a-qos-class-of-guaranteed](https://kubernetes.io/docs/tasks/configure-pod-container/quality-service-pod/#create-a-pod-that-gets-assigned-a-qos-class-of-guaranteed) \* Every container in the Pod must have a memory limit and a memory request. \* For every container in the Pod, the memory limit must equal the memory request. **Default:** `{"max":"2.5Gi"}` ### [](#resources-memory-container-max)[resources.memory.container.max](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=resources.memory.container.max) Maximum memory count for each Redpanda broker. Equivalent to `resources.limits.memory`. For production, use `10Gi` or greater. **Default:** `"2.5Gi"` ### [](#serviceaccount)[serviceAccount](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=serviceAccount) Service account management. **Default:** {"annotations":{},"create":true,"name":""} ### [](#serviceaccount-annotations)[serviceAccount.annotations](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=serviceAccount.annotations) Annotations to add to the service account. **Default:** `{}` ### [](#serviceaccount-create)[serviceAccount.create](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=serviceAccount.create) Specifies whether a service account should be created. **Default:** `true` ### [](#serviceaccount-name)[serviceAccount.name](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=serviceAccount.name) The name of the service account to use. If not set and `serviceAccount.create` is `true`, a name is generated using the `redpanda.fullname` template. **Default:** `""` ### [](#statefulset-additionalredpandacmdflags)[statefulset.additionalRedpandaCmdFlags](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.additionalRedpandaCmdFlags) Additional flags to pass to redpanda, **Default:** `[]` ### [](#statefulset-additionalselectorlabels)[statefulset.additionalSelectorLabels](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.additionalSelectorLabels) Additional labels to be added to statefulset label selector. For example, `my.k8s.service: redpanda`. **Default:** `{}` ### [](#statefulset-budget-maxunavailable)[statefulset.budget.maxUnavailable](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.budget.maxUnavailable) **Default:** `1` ### [](#statefulset-initcontainerimage-repository)[statefulset.initContainerImage.repository](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.initContainerImage.repository) **Default:** `"busybox"` ### [](#statefulset-initcontainerimage-tag)[statefulset.initContainerImage.tag](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.initContainerImage.tag) **Default:** `"latest"` ### [](#statefulset-initcontainers-configurator-additionalcliargs)[statefulset.initContainers.configurator.additionalCLIArgs](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.initContainers.configurator.additionalCLIArgs) **Default:** `[]` ### [](#statefulset-initcontainers-fsvalidator-enabled)[statefulset.initContainers.fsValidator.enabled](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.initContainers.fsValidator.enabled) **Default:** `false` ### [](#statefulset-initcontainers-fsvalidator-expectedfs)[statefulset.initContainers.fsValidator.expectedFS](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.initContainers.fsValidator.expectedFS) **Default:** `"xfs"` ### [](#statefulset-initcontainers-setdatadirownership-enabled)[statefulset.initContainers.setDataDirOwnership.enabled](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.initContainers.setDataDirOwnership.enabled) In environments where root is not allowed, you cannot change the ownership of files and directories. Enable `setDataDirOwnership` when using default minikube cluster configuration. **Default:** `false` ### [](#statefulset-podantiaffinity-custom)[statefulset.podAntiAffinity.custom](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.podAntiAffinity.custom) Change `podAntiAffinity.type` to `custom` and provide your own podAntiAffinity rules here. **Default:** `{}` ### [](#statefulset-podantiaffinity-topologykey)[statefulset.podAntiAffinity.topologyKey](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.podAntiAffinity.topologyKey) The topologyKey to be used. Can be used to spread across different nodes, AZs, regions etc. **Default:** `"kubernetes.io/hostname"` ### [](#statefulset-podantiaffinity-type)[statefulset.podAntiAffinity.type](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.podAntiAffinity.type) Valid anti-affinity types are `soft`, `hard`, or `custom`. Use `custom` if you want to supply your own anti-affinity rules in the `podAntiAffinity.custom` object. **Default:** `"hard"` ### [](#statefulset-podantiaffinity-weight)[statefulset.podAntiAffinity.weight](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.podAntiAffinity.weight) Weight for `soft` anti-affinity rules. Does not apply to other anti-affinity types. **Default:** `100` ### [](#statefulset-podtemplate-annotations)[statefulset.podTemplate.annotations](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.podTemplate.annotations) Additional annotations to apply to the Pods of the StatefulSet. **Default:** `{}` ### [](#statefulset-podtemplate-labels)[statefulset.podTemplate.labels](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.podTemplate.labels) Additional labels to apply to the Pods of the StatefulSet. **Default:** `{}` ### [](#statefulset-podtemplate-spec)[statefulset.podTemplate.spec](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.podTemplate.spec) A subset of Kubernetes’ PodSpec type that will be merged into the final PodSpec. See [Merge Semantics](#merging-semantics) for details. **Default:** {"affinity":{"podAntiAffinity":{"requiredDuringSchedulingIgnoredDuringExecution":\[{"labelSelector":{"matchLabels":{"app.kubernetes.io/component":"{{ include \\"redpanda.name\\" . }}-statefulset","app.kubernetes.io/instance":"{{ .Release.Name }}","app.kubernetes.io/name":"{{ include \\"redpanda.name\\" . }}"}},"topologyKey":"kubernetes.io/hostname"}\]}},"nodeSelector":{},"priorityClassName":"","securityContext":{},"terminationGracePeriodSeconds":90,"tolerations":\[\],"topologySpreadConstraints":\[{"labelSelector":{"matchLabels":{"app.kubernetes.io/component":"{{ include \\"redpanda.name\\" . }}-statefulset","app.kubernetes.io/instance":"{{ .Release.Name }}","app.kubernetes.io/name":"{{ include \\"redpanda.name\\" . }}"}},"maxSkew":1,"topologyKey":"topology.kubernetes.io/zone","whenUnsatisfiable":"ScheduleAnyway"}\]} ### [](#statefulset-podtemplate-spec-nodeselector)[statefulset.podTemplate.spec.nodeSelector](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.podTemplate.spec.nodeSelector) Node selection constraints for scheduling Pods of this StatefulSet. These constraints override the global `nodeSelector` value. For details, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#nodeselector). **Default:** `{}` ### [](#statefulset-podtemplate-spec-priorityclassname)[statefulset.podTemplate.spec.priorityClassName](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.podTemplate.spec.priorityClassName) PriorityClassName given to Pods of this StatefulSet. For details, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/pod-priority-preemption/#priorityclass). **Default:** `""` ### [](#statefulset-podtemplate-spec-terminationgraceperiodseconds)[statefulset.podTemplate.spec.terminationGracePeriodSeconds](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.podTemplate.spec.terminationGracePeriodSeconds) Termination grace period in seconds is time required to execute preStop hook which puts particular Redpanda Pod (process/container) into maintenance mode. Before settle down on particular value please put Redpanda under load and perform rolling upgrade or rolling restart. That value needs to accommodate two processes: \* preStop hook needs to put Redpanda into maintenance mode \* after preStop hook Redpanda needs to handle gracefully SIGTERM signal Both processes are executed sequentially where preStop hook has hard deadline in the middle of terminationGracePeriodSeconds. REF: [https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#hook-handler-execution](https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#hook-handler-execution) [https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-termination](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-termination) **Default:** `90` ### [](#statefulset-podtemplate-spec-tolerations)[statefulset.podTemplate.spec.tolerations](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.podTemplate.spec.tolerations) Taints to be tolerated by Pods of this StatefulSet. These tolerations override the global tolerations value. For details, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/). **Default:** `[]` ### [](#statefulset-replicas)[statefulset.replicas](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.replicas) Number of Redpanda brokers (Redpanda Data recommends setting this to the number of worker nodes in the cluster) **Default:** `3` ### [](#statefulset-sidecars-brokerdecommissioner-decommissionafter)[statefulset.sideCars.brokerDecommissioner.decommissionAfter](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.sideCars.brokerDecommissioner.decommissionAfter) **Default:** `"60s"` ### [](#statefulset-sidecars-brokerdecommissioner-decommissionrequeuetimeout)[statefulset.sideCars.brokerDecommissioner.decommissionRequeueTimeout](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.sideCars.brokerDecommissioner.decommissionRequeueTimeout) **Default:** `"10s"` ### [](#statefulset-sidecars-brokerdecommissioner-enabled)[statefulset.sideCars.brokerDecommissioner.enabled](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.sideCars.brokerDecommissioner.enabled) **Default:** `false` ### [](#statefulset-sidecars-configwatcher-enabled)[statefulset.sideCars.configWatcher.enabled](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.sideCars.configWatcher.enabled) **Default:** `true` ### [](#statefulset-sidecars-controllers-createrbac)[statefulset.sideCars.controllers.createRBAC](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.sideCars.controllers.createRBAC) DEPRECATED: Use `rbac.enabled` to control RBAC chart wide or control RBAC by selectively enabling/disabling specific sidecar controllers. Setting this field has no effect. **Default:** `true` ### [](#statefulset-sidecars-controllers-enabled)[statefulset.sideCars.controllers.enabled](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.sideCars.controllers.enabled) **Default:** `false` ### [](#statefulset-sidecars-controllers-healthprobeaddress)[statefulset.sideCars.controllers.healthProbeAddress](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.sideCars.controllers.healthProbeAddress) **Default:** `":8085"` ### [](#statefulset-sidecars-controllers-metricsaddress)[statefulset.sideCars.controllers.metricsAddress](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.sideCars.controllers.metricsAddress) **Default:** `":9082"` ### [](#statefulset-sidecars-controllers-pprofaddress)[statefulset.sideCars.controllers.pprofAddress](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.sideCars.controllers.pprofAddress) **Default:** `":9083"` ### [](#statefulset-sidecars-controllers-run)[statefulset.sideCars.controllers.run](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.sideCars.controllers.run) DEPRECATED: Please use statefulset.sideCars.brokerDecommissioner and statefulset.sideCars.pvcUnbinder Setting this field has no effect. **Default:** `["all"]` ### [](#statefulset-sidecars-image-repository)[statefulset.sideCars.image.repository](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.sideCars.image.repository) **Default:** "docker.redpanda.com/redpandadata/redpanda-operator" ### [](#statefulset-sidecars-image-tag)[statefulset.sideCars.image.tag](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.sideCars.image.tag) **Default:** `"v25.2.1"` ### [](#statefulset-sidecars-pvcunbinder-enabled)[statefulset.sideCars.pvcUnbinder.enabled](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.sideCars.pvcUnbinder.enabled) **Default:** `false` ### [](#statefulset-sidecars-pvcunbinder-unbindafter)[statefulset.sideCars.pvcUnbinder.unbindAfter](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.sideCars.pvcUnbinder.unbindAfter) **Default:** `"60s"` ### [](#statefulset-updatestrategy-type)[statefulset.updateStrategy.type](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=statefulset.updateStrategy.type) **Default:** `"RollingUpdate"` ### [](#storage)[storage](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=storage) Persistence settings. For details, see the [storage documentation](https://docs.redpanda.com/docs/manage/kubernetes/configure-storage/). **Default:** {"hostPath":"","persistentVolume":{"annotations":{},"enabled":true,"labels":{},"nameOverwrite":"","size":"20Gi","storageClass":""},"tiered":{"config":{"cloud\_storage\_cache\_size":5368709120,"cloud\_storage\_enable\_remote\_read":true,"cloud\_storage\_enable\_remote\_write":true,"cloud\_storage\_enabled":false},"credentialsSecretRef":{"accessKey":{"configurationKey":"cloud\_storage\_access\_key"},"secretKey":{"configurationKey":"cloud\_storage\_secret\_key"}},"hostPath":"","mountType":"none","persistentVolume":{"annotations":{},"labels":{},"storageClass":""}}} ### [](#storage-hostpath)[storage.hostPath](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=storage.hostPath) Absolute path on the host to store Redpanda’s data. If unspecified, then an `emptyDir` volume is used. If specified but `persistentVolume.enabled` is true, `storage.hostPath` has no effect. **Default:** `""` ### [](#storage-persistentvolume)[storage.persistentVolume](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=storage.persistentVolume) If `persistentVolume.enabled` is true, a PersistentVolumeClaim is created and used to store Redpanda’s data. Otherwise, `storage.hostPath` is used. **Default:** {"annotations":{},"enabled":true,"labels":{},"nameOverwrite":"","size":"20Gi","storageClass":""} ### [](#storage-persistentvolume-annotations)[storage.persistentVolume.annotations](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=storage.persistentVolume.annotations) Additional annotations to apply to the created PersistentVolumeClaims. **Default:** `{}` ### [](#storage-persistentvolume-labels)[storage.persistentVolume.labels](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=storage.persistentVolume.labels) Additional labels to apply to the created PersistentVolumeClaims. **Default:** `{}` ### [](#storage-persistentvolume-nameoverwrite)[storage.persistentVolume.nameOverwrite](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=storage.persistentVolume.nameOverwrite) Option to change volume claim template name for tiered storage persistent volume if tiered.mountType is set to `persistentVolume` **Default:** `""` ### [](#storage-persistentvolume-storageclass)[storage.persistentVolume.storageClass](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=storage.persistentVolume.storageClass) To disable dynamic provisioning, set to `-`. If undefined or empty (default), then no storageClassName spec is set, and the default dynamic provisioner is chosen (gp2 on AWS, standard on GKE, AWS & OpenStack). **Default:** `""` ### [](#storage-tiered-config)[storage.tiered.config](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=storage.tiered.config) Tiered Storage settings Requires `enterprise.licenseKey` or `enterprised.licenseSecretRef` For details, see the [Tiered Storage documentation](https://docs.redpanda.com/docs/manage/kubernetes/tiered-storage/). For a list of properties, see [Object Storage Properties](https://docs.redpanda.com/current/reference/properties/object-storage-properties/). **Default:** {"cloud\_storage\_cache\_size":5368709120,"cloud\_storage\_enable\_remote\_read":true,"cloud\_storage\_enable\_remote\_write":true,"cloud\_storage\_enabled":false} ### [](#storage-tiered-config-cloud_storage_cache_size)[storage.tiered.config.cloud\_storage\_cache\_size](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=storage.tiered.config.cloud_storage_cache_size) Maximum size of the disk cache used by Tiered Storage. Default is 20 GiB. See the [property reference documentation](https://docs.redpanda.com/docs/reference/object-storage-properties/#cloud_storage_cache_size). **Default:** `5368709120` ### [](#storage-tiered-config-cloud_storage_enable_remote_read)[storage.tiered.config.cloud\_storage\_enable\_remote\_read](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=storage.tiered.config.cloud_storage_enable_remote_read) Cluster level default remote read configuration for new topics. See the [property reference documentation](https://docs.redpanda.com/docs/reference/object-storage-properties/#cloud_storage_enable_remote_read). **Default:** `true` ### [](#storage-tiered-config-cloud_storage_enable_remote_write)[storage.tiered.config.cloud\_storage\_enable\_remote\_write](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=storage.tiered.config.cloud_storage_enable_remote_write) Cluster level default remote write configuration for new topics. See the [property reference documentation](https://docs.redpanda.com/docs/reference/object-storage-properties/#cloud_storage_enable_remote_write). **Default:** `true` ### [](#storage-tiered-config-cloud_storage_enabled)[storage.tiered.config.cloud\_storage\_enabled](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=storage.tiered.config.cloud_storage_enabled) Global flag that enables Tiered Storage if a license key is provided. See the [property reference documentation](https://docs.redpanda.com/docs/reference/object-storage-properties/#cloud_storage_enabled). **Default:** `false` ### [](#storage-tiered-hostpath)[storage.tiered.hostPath](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=storage.tiered.hostPath) Absolute path on the host to store Redpanda’s Tiered Storage cache. **Default:** `""` ### [](#storage-tiered-persistentvolume-annotations)[storage.tiered.persistentVolume.annotations](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=storage.tiered.persistentVolume.annotations) Additional annotations to apply to the created PersistentVolumeClaims. **Default:** `{}` ### [](#storage-tiered-persistentvolume-labels)[storage.tiered.persistentVolume.labels](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=storage.tiered.persistentVolume.labels) Additional labels to apply to the created PersistentVolumeClaims. **Default:** `{}` ### [](#storage-tiered-persistentvolume-storageclass)[storage.tiered.persistentVolume.storageClass](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=storage.tiered.persistentVolume.storageClass) To disable dynamic provisioning, set to \`\`-''. If undefined or empty (default), then no storageClassName spec is set, and the default dynamic provisioner is chosen (gp2 on AWS, standard on GKE, AWS & OpenStack). **Default:** `""` ### [](#tests-enabled)[tests.enabled](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=tests.enabled) **Default:** `true` ### [](#tls)[tls](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=tls) TLS settings. For details, see the [TLS documentation](https://docs.redpanda.com/docs/manage/kubernetes/security/kubernetes-tls/). **Default:** {"certs":{"default":{"caEnabled":true},"external":{"caEnabled":true}},"enabled":true} ### [](#tls-certs)[tls.certs](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=tls.certs) List all Certificates here, then you can reference a specific Certificate’s name in each listener’s `listeners..tls.cert` setting. **Default:** {"default":{"caEnabled":true},"external":{"caEnabled":true}} ### [](#tls-certs-default)[tls.certs.default](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=tls.certs.default) This key is the Certificate name. To apply the Certificate to a specific listener, reference the Certificate’s name in `listeners..tls.cert`. **Default:** `{"caEnabled":true}` ### [](#tls-certs-default-caenabled)[tls.certs.default.caEnabled](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=tls.certs.default.caEnabled) Indicates whether or not the Secret holding this certificate includes a `ca.crt` key. When `true`, chart managed clients, such as rpk, will use `ca.crt` for certificate verification and listeners with `require_client_auth` and no explicit `truststore` will use `ca.crt` as their `truststore_file` for verification of client certificates. When `false`, chart managed clients will use `tls.crt` for certificate verification and listeners with `require_client_auth` and no explicit `truststore` will use the container’s CA certificates. **Default:** `true` ### [](#tls-certs-external)[tls.certs.external](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=tls.certs.external) Example external tls configuration uncomment and set the right key to the listeners that require them also enable the tls setting for those listeners. **Default:** `{"caEnabled":true}` ### [](#tls-certs-external-caenabled)[tls.certs.external.caEnabled](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=tls.certs.external.caEnabled) Indicates whether or not the Secret holding this certificate includes a `ca.crt` key. When `true`, chart managed clients, such as rpk, will use `ca.crt` for certificate verification and listeners with `require_client_auth` and no explicit `truststore` will use `ca.crt` as their `truststore_file` for verification of client certificates. When `false`, chart managed clients will use `tls.crt` for certificate verification and listeners with `require_client_auth` and no explicit `truststore` will use the container’s CA certificates. **Default:** `true` ### [](#tls-enabled)[tls.enabled](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=tls.enabled) Enable TLS globally for all listeners. Each listener must include a Certificate name in its `.tls` object. To allow you to enable TLS for individual listeners, Certificates in `auth.tls.certs` are always loaded, even if `tls.enabled` is `false`. See `listeners..tls.enabled`. **Default:** `true` ### [](#tuning)[tuning](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=tuning) Redpanda tuning settings. Each is set to their default values in Redpanda. **Default:** `{"tune_aio_events":true}` ### [](#tuning-tune_aio_events)[tuning.tune\_aio\_events](https://artifacthub.io/packages/helm/redpanda-data/redpanda?modal=values&path=tuning.tune_aio_events) Increase the maximum number of outstanding asynchronous IO operations if the current value is below a certain threshold. This allows Redpanda to make as many simultaneous IO requests as possible, increasing throughput. When this option is enabled, Helm creates a privileged container. If your security profile does not allow this, you can disable this container by setting `tune_aio_events` to `false`. For more details, see the [tuning documentation](https://docs.redpanda.com/docs/deploy/deployment-option/self-hosted/kubernetes/kubernetes-tune-workers/). **Default:** `true` ## [](#merging-semantics)Merging Semantics The redpanda chart implements a form of object merging that’s roughly a middleground of [JSON Merge Patch](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/update-api-object-kubectl-patch/#use-a-json-merge-patch-to-update-a-deployment) and [Kubernetes’ Strategic Merge Patch](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/update-api-object-kubectl-patch/#use-a-strategic-merge-patch-to-update-a-deployment). This is done to aid end users in setting or overriding fields that are not directly exposed via the chart. - Directives are not supported. - List fields that are merged by a unique key in Kubernetes’ SMP (e.g. `containers`, `env`) will be merged in a similar awy. - Only fields explicitly allowed by the chart’s JSON schema will be merged. - Additional containers that are not present in the original value will NOT be added. --- # Page 261: Monitoring Metrics **URL**: https://docs.redpanda.com/current/reference/monitor-metrics.md --- # Monitoring Metrics --- title: Monitoring Metrics latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: monitor-metrics page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: monitor-metrics.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/monitor-metrics.adoc description: Reference of monitoring metrics provided by Redpanda. page-git-created-date: "2023-05-30" page-git-modified-date: "2024-12-03" support-status: supported --- Redpanda exports metrics through Prometheus endpoints, `/public_metrics` and `/metrics`. To learn how to monitor Redpanda, see [Monitor Redpanda](../../manage/monitoring/) or [Monitor in Kubernetes](../../manage/kubernetes/monitoring/). > 💡 **TIP** > > Use [/public\_metrics](../public-metrics-reference/) for your primary dashboards for monitoring system health. These metrics have low cardinality and are designed for customer consumption, with aggregated labels for better performance. **Public metrics use the `redpanda_` prefix.** > > Use [/metrics](../internal-metrics-reference/) for detailed analysis and debugging. These metrics can have high cardinality with thousands of series, providing granular operational insights. **Internal metrics use the `vectorized_` prefix.** - [Public Metrics](../public-metrics-reference/) Public metrics to create your system dashboard. - [Internal Metrics](../internal-metrics-reference/) Redpanda internal metrics for detailed analysis, debugging, and troubleshooting. --- # Page 262: Properties **URL**: https://docs.redpanda.com/current/reference/properties.md --- # Properties --- title: Properties latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: properties/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: properties/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/properties/index.adoc description: Learn about the Redpanda properties you can configure. page-git-created-date: "2024-05-23" page-git-modified-date: "2024-05-23" support-status: supported --- - [Broker Configuration Properties](broker-properties/) Reference of broker configuration properties. - [Cluster Configuration Properties](cluster-properties/) Reference of cluster configuration properties. - [Object Storage Properties](object-storage-properties/) Reference of object storage properties. - [Topic Configuration Properties](topic-properties/) Reference of topic configuration properties. --- # Page 263: Broker Configuration Properties **URL**: https://docs.redpanda.com/current/reference/properties/broker-properties.md --- # Broker Configuration Properties --- title: Broker Configuration Properties latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: properties/broker-properties page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: properties/broker-properties.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/properties/broker-properties.adoc description: Reference of broker configuration properties. page-git-created-date: "2024-05-23" page-git-modified-date: "2026-03-18" support-status: supported --- Broker configuration properties are applied individually to each broker in a cluster. You can find and modify these properties in the `redpanda.yaml` configuration file. Broker properties are organized under different top-level sections in your configuration file: - `redpanda` - `pandaproxy` - `pandaproxy_client` - `schema_registry` - `schema_registry_client` - `audit_log_client` Simple properties are shown as a single key-value pair. Complex properties, such as listeners and TLS configurations, include configuration examples. For information on how to edit broker properties, see [Configure Broker Properties](../../../manage/cluster-maintenance/node-property-configuration/). > 📝 **NOTE** > > All broker properties require that you restart Redpanda for any update to take effect. ## [](#redpanda)Redpanda Configuration properties for the core Redpanda broker. Example ```yaml redpanda: data_directory: /var/lib/redpanda/data kafka_api: - address: 0.0.0.0 port: 9092 authentication_method: sasl admin: - address: 0.0.0.0 port: 9644 rpc_server: address: 0.0.0.0 port: 33145 seed_servers: - host: address: redpanda-1 port: 33145 ``` ### [](#admin)admin Network address for the [Admin API](https://docs.redpanda.com/current/reference/glossary/#admin-api) server. | Property | Value | | --- | --- | | Type | object | | Default | {address: "127.0.0.1", port: 9644} | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | redpanda: admin: - name: address: port: Replace the following placeholders with your values:: Name for the Admin API listener (TLS configuration is handled separately in the admin_api_tls broker property): The externally accessible hostname or IP address that clients use to connect to this broker: The port number for the Admin API endpoint | ### [](#admin_api_doc_dir)admin\_api\_doc\_dir Path to the API specifications for the Admin API. | Property | Value | | --- | --- | | Type | string | | Default | /usr/share/redpanda/admin-api-doc | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#admin_api_tls)admin\_api\_tls Specifies the TLS configuration for the HTTP Admin API. | Property | Value | | --- | --- | | Type | array | | Default | [] | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | redpanda: admin_api_tls: - name: enabled: true cert_file: key_file: truststore_file: require_client_auth: trueReplace the following placeholders with your values:: Name that matches your Admin API listener (defined in the admin broker property): Full path to the TLS certificate file: Full path to the TLS private key file: Full path to the Certificate Authority file | ### [](#advertised_kafka_api)advertised\_kafka\_api Address of the Kafka API published to the clients. If not set, the [`kafka_api`](#kafka_api) broker property is used. When behind a load balancer or in containerized environments, this should be the externally-accessible address that clients use to connect. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | redpanda: advertised_kafka_api: - name: address: port: Replace the following placeholders with your values:: Name that matches your Kafka API listener (defined in the kafka_api broker property): The externally accessible hostname or IP address that clients use to connect to this broker: The port number for the Kafka API endpoint | ### [](#advertised_rpc_api)advertised\_rpc\_api Address of RPC endpoint published to other cluster members. If not set, the [`rpc_server`](#rpc_server) broker property is used. This should be the address other brokers can use to communicate with this broker. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | redpanda: advertised_rpc_api: address: port: Replace the following placeholders with your values:: The externally accessible hostname or IP address that other brokers use to communicate with this broker: The port number for the RPC endpoint (default is 33145) | ### [](#cloud_storage_cache_directory)cloud\_storage\_cache\_directory Directory for archival cache. Set when the [`cloud_storage_enabled`](../cluster-properties/#cloud_storage_enabled) cluster property is enabled. If not specified, Redpanda uses a default path within the data directory. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | redpanda: cloud_storage_cache_directory: Replace with the full path to your desired cache directory. | | Related topics | cloud_storage_enabled | ### [](#cloud_storage_inventory_hash_store)cloud\_storage\_inventory\_hash\_store Directory to store inventory report hashes for use by cloud storage scrubber. If not specified, Redpanda uses a default path within the data directory. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | redpanda: cloud_storage_inventory_hash_store: | ### [](#crash_loop_limit)crash\_loop\_limit A limit on the number of consecutive times a broker can crash within one hour before its crash-tracking logic is reset. This limit prevents a broker from getting stuck in an infinite cycle of crashes. If `null`, the property is disabled and no limit is applied. The crash-tracking logic is reset (to zero consecutive crashes) by any of the following conditions: - The broker shuts down cleanly. - One hour passes since the last crash. - The `redpanda.yaml` broker configuration file is updated. - The `startup_log` file in the broker’s [`data_directory`](#data_directory) broker property is manually deleted. | Property | Value | | --- | --- | | Type | integer | | Maximum | 4294967295 | | Default | 5 | | Nullable | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#crash_loop_sleep_sec)crash\_loop\_sleep\_sec **Introduced in v24.3.4** The amount of time the broker sleeps before terminating when the limit on consecutive broker crashes ([`crash_loop_limit`](#crash_loop_limit)) is reached. This property provides a debugging window for you to access the broker before it terminates, and is particularly useful in Kubernetes environments. If `null`, the property is disabled, and the broker terminates immediately after reaching the crash loop limit. For information about how to reset the crash loop limit, see the [`crash_loop_limit`](#crash_loop_limit) broker property. | Property | Value | | --- | --- | | Type | integer | | Range | [-17179869184, 17179869183] | | Default | null | | Nullable | Yes | | Unit | Seconds | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#data_directory)data\_directory Path to the directory for storing Redpanda’s streaming data files. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#developer_mode)developer\_mode > ⚠️ **CAUTION** > > Enabling `developer_mode` isn’t recommended for production use. Enable developer mode, which skips most of the checks performed at startup. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#emergency_disable_data_transforms)emergency\_disable\_data\_transforms Override the cluster property [`data_transforms_enabled`](../cluster-properties/#data_transforms_enabled) and disable Wasm-powered data transforms. This is an emergency shutoff button. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | data_transforms_enabled | ### [](#empty_seed_starts_cluster)empty\_seed\_starts\_cluster Controls how a new cluster is formed. All brokers in a cluster must have the same value. [See how the `empty_seed_starts_cluster` broker property works with the `seed_servers` broker property](#seed_servers) to form a cluster. > 💡 **TIP** > > For backward compatibility, `true` is the default. Redpanda recommends using `false` in production environments to prevent accidental cluster formation. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#fips_mode)fips\_mode Controls whether Redpanda starts in FIPS mode. This property allows for three values: - Disabled - Redpanda does not start in FIPS mode. - Permissive - Redpanda performs the same check as enabled, but a warning is logged, and Redpanda continues to run. Redpanda loads the OpenSSL FIPS provider into the OpenSSL library. After this completes, Redpanda is operating in FIPS mode, which means that the TLS cipher suites available to users are limited to the TLSv1.2 and TLSv1.3 NIST-approved cryptographic methods. - Enabled - Redpanda verifies that the operating system is enabled for FIPS by checking `/proc/sys/crypto/fips_enabled`. If the file does not exist or does not return `1`, Redpanda immediately exits. | Property | Value | | --- | --- | | Type | string (enum) | | Accepted values | disabled, permissive, enabled | | Default | disabled | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#kafka_api)kafka\_api IP address and port of the Kafka API endpoint that handles requests. Supports multiple listeners with different configurations. | Property | Value | | --- | --- | | Type | array | | Default | [127.0.0.1:9092, null] | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | Basic exampleredpanda: kafka_api: - address: port: authentication_method: saslMultiple listeners example (for different networks or authentication methods)redpanda: kafka_api: - name: address: port: authentication_method: none - name: address: port: authentication_method: sasl - name: address: port: authentication_method: mtls_identityReplace the following placeholders with your values:: The IP address to bind the listener to (typically 0.0.0.0 for all interfaces): The port number for the Kafka API endpoint: Name for internal network connections (for example, internal): Name for external network connections (for example, external): Name for mTLS connections (for example, mtls): The IP address for internal connections: The port number for internal Kafka API connections: The IP address for external connections: The port number for external Kafka API connections: The IP address for mTLS connections: The port number for mTLS Kafka API connections | | Related topics | sasl_mechanisms | ### [](#kafka_api_tls)kafka\_api\_tls Transport Layer Security (TLS) configuration for the Kafka API endpoint. > 📝 **NOTE** > > Set `require_client_auth: true` for mutual TLS (mTLS) authentication, or `false` for server-side TLS only. ### [](#memory_allocation_warning_threshold)memory\_allocation\_warning\_threshold Threshold for log messages that contain a larger memory allocation than specified. | Property | Value | | --- | --- | | Type | integer | | Default | 131072 | | Nullable | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#node_id)node\_id A number that uniquely identifies the broker within the cluster. If `null` (the default value), Redpanda automatically assigns an ID. If set, it must be non-negative value. > ⚠️ **WARNING: Do not set node_id manually.** > > Do not set `node_id` manually. > > Redpanda assigns unique IDs automatically to prevent issues such as: > > - Brokers with empty disks rejoining the cluster. > > - Conflicts during recovery or scaling. > > > Manually setting or reusing `node_id` values, even for decommissioned brokers, can cause cluster inconsistencies and operational failures. Broker IDs are immutable. After a broker joins the cluster, its `node_id` **cannot** be changed. | Property | Value | | --- | --- | | Type | integer | | Default | null | | Nullable | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#node_id_overrides)node\_id\_overrides List of node ID and UUID overrides applied at broker startup. Each entry includes the current UUID, the desired new ID and UUID, and an ignore flag. An entry applies only if `current_uuid` matches the broker’s actual UUID. Remove this property after the cluster restarts successfully and operates normally. This prevents reapplication and maintains consistent configuration across brokers. | Property | Value | | --- | --- | | Type | array | | Default | [] | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | redpanda: node_id_overrides: - current_uuid: "" new_id: new_uuid: "" ignore_existing_node_id: - current_uuid: "" new_id: new_uuid: "" ignore_existing_node_id: Replace the following placeholders with your values:: The current UUID of the broker to override: The new broker ID to assign: The new UUID to assign to the broker: Set to true to force override on brokers that already have a node ID, or false to apply override only to brokers without existing node IDs: Additional broker UUID for multiple overrides: Additional new broker ID: Additional new UUID: Additional ignore existing node ID flag | ### [](#openssl_config_file)openssl\_config\_file Path to the configuration file used by OpenSSL to properly load the FIPS-compliant module. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#openssl_module_directory)openssl\_module\_directory Path to the directory that contains the OpenSSL FIPS-compliant module. The filename that Redpanda looks for is `fips.so`. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#rack)rack A label that identifies a failure zone. Apply the same label to all brokers in the same failure zone. When [enable\_rack\_awareness](../cluster-properties/#enable_rack_awareness) is set to `true` at the cluster level, the system uses the rack labels to spread partition replicas across different failure zones. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | enable_rack_awareness | ### [](#recovery_mode_enabled)recovery\_mode\_enabled If `true`, start Redpanda in [recovery mode](../../../manage/recovery-mode/), where user partitions are not loaded and only administrative operations are allowed. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | recovery mode | ### [](#rpc_server)rpc\_server IP address and port for the Remote Procedure Call (RPC) server. | Property | Value | | --- | --- | | Type | object | | Default | {address: "127.0.0.1", port: 33145} | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#rpc_server_tls)rpc\_server\_tls TLS configuration for the RPC server. | Property | Value | | --- | --- | | Type | object | | Default | {crl_file: null, enable_renegotiation: null, enabled: null, key_cert: null, min_tls_version: null, require_client_auth: null, tls_v1_2_cipher_suites: null, tls_v1_3_cipher_suites: null, truststore_file: null} | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | redpanda: rpc_server_tls: enabled: true cert_file: "" key_file: "" truststore_file: "" require_client_auth: trueReplace the following placeholders with your values:: Full path to the RPC TLS certificate file: Full path to the RPC TLS private key file: Full path to the certificate authority file | ### [](#seed_servers)seed\_servers List of the seed servers used to join current cluster. If the `seed_servers` list is empty the broker will be a cluster root and it will form a new cluster. - When `empty_seed_starts_cluster` is `true`, Redpanda enables one broker with an empty `seed_servers` list to initiate a new cluster. The broker with an empty `seed_servers` becomes the cluster root, to which other brokers must connect to join the cluster. Brokers looking to join the cluster should have their `seed_servers` populated with the cluster root’s address, facilitating their connection to the cluster. > ❗ **IMPORTANT** > > Only one broker, the designated cluster root, should have an empty `seed_servers` list during the initial cluster bootstrapping. This ensures a single initiation point for cluster formation. - When `empty_seed_starts_cluster` is `false`, Redpanda requires all brokers to start with a known set of brokers listed in `seed_servers`. The `seed_servers` list must not be empty and should be identical across these initial seed brokers, containing the addresses of all seed brokers. Brokers not included in the `seed_servers` list use it to discover and join the cluster, allowing for expansion beyond the foundational members. > 📝 **NOTE** > > The `seed_servers` list must be consistent across all seed brokers to prevent cluster fragmentation and ensure stable cluster formation. | Property | Value | | --- | --- | | Type | array | | Default | [] | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | Example with empty_seed_starts_cluster: true# Cluster root broker (seed starter) redpanda: empty_seed_starts_cluster: true seed_servers: []# Additional brokers joining the cluster redpanda: empty_seed_starts_cluster: true seed_servers: - host: address: port: Example with empty_seed_starts_cluster: false# All initial seed brokers use the same configuration redpanda: empty_seed_starts_cluster: false seed_servers: - host: address: port: - host: address: port: - host: address: port: Replace the following placeholders with your values:: IP address of the cluster root broker: IP addresses of each seed broker in the cluster: RPC port for brokers (default: 33145) | ### [](#storage_failure_injection_config_path)storage\_failure\_injection\_config\_path Path to the configuration file used for low level storage failure injection. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#storage_failure_injection_enabled)storage\_failure\_injection\_enabled If `true`, inject low level storage failures on the write path. Do _not_ use for production instances. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#upgrade_override_checks)upgrade\_override\_checks Whether to violate safety checks when starting a Redpanda version newer than the cluster’s consensus version. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#verbose_logging_timeout_sec_max)verbose\_logging\_timeout\_sec\_max Maximum duration in seconds for verbose (`TRACE` or `DEBUG`) logging. Values configured above this will be clamped. If null (the default) there is no limit. Can be overridden in the Admin API on a per-request basis. | Property | Value | | --- | --- | | Type | integer | | Range | [-17179869184, 17179869183] | | Default | null | | Nullable | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | schema_registry: schema_registry_api: address: 0.0.0.0 port: 8081 authentication_method: http_basic schema_registry_replication_factor: 3 mode_mutability: true | | Related topics | http_authentication | ## [](#http_based_auth_method)HTTP-based authentication The `authentication_method` property configures authentication for HTTP-based API listeners (Schema Registry and HTTP Proxy). **Accepted values:** - `none` - No authentication required (allows anonymous access). - `http_basic` - Authentication required. The specific authentication method (Basic vs OIDC) depends on the [`http_authentication`](../cluster-properties/#http_authentication) cluster property and the client’s Authorization header type. **Default:** `none` This property works together with the cluster property [`http_authentication`](../cluster-properties/#http_authentication): - `authentication_method` (broker property): Controls whether a specific listener requires authentication (`http_basic`) or allows anonymous access (`none`) - `http_authentication` (cluster property): Controls which authentication methods are available globally (`["BASIC"]`, `["OIDC"]`, or `["BASIC", "OIDC"]`) When `authentication_method: http_basic` is set on a listener, clients can use any authentication method that is enabled in the `http_authentication` cluster property. For detailed authentication configuration, see [Configure Authentication](../../../manage/security/authentication/). ## [](#schema-registry)Schema Registry The Schema Registry provides configuration properties to help you enable producers and consumers to share information needed to serialize and deserialize producer and consumer messages. For information on how to edit broker properties for the Schema Registry, see [Configure Broker Properties](../../../manage/cluster-maintenance/node-property-configuration/). Schema Registry shares some configuration property patterns with HTTP Proxy (such as API listeners and authentication methods), but also has additional schema-specific properties like managing schema storage and validation behavior. **Shared properties:** - [`api_doc_dir`](#api_doc_dir) - API documentation directory (independent from HTTP Proxy’s same-named property) - [`schema_registry_api`](#schema_registry_api) - API listener configuration (similar to HTTP Proxy’s [`pandaproxy_api`](#pandaproxy_api)) - [`schema_registry_api_tls`](#schema_registry_api_tls) - TLS configuration (similar to HTTP Proxy’s [`pandaproxy_api_tls`](#pandaproxy_api_tls)) Example ```yaml schema_registry: schema_registry_api: address: 0.0.0.0 port: 8081 authentication_method: http_basic schema_registry_replication_factor: 3 mode_mutability: true ``` * * * ### [](#mode_mutability)mode\_mutability Enable modifications to the read-only `mode` of the Schema Registry. When set to `true`, the entire Schema Registry or its subjects can be switched to `READONLY` or `READWRITE`. This property is useful for preventing unwanted changes to the entire Schema Registry or specific subjects. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | ### [](#schema_registry_api)schema\_registry\_api Schema Registry API listener address and port | Property | Value | | --- | --- | | Type | array | | Default | [0.0.0.0:8081, null] | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Example | schema_registry: schema_registry_api: address: 0.0.0.0 port: 8081 authentication_method: http_basic | ### [](#schema_registry_api_tls)schema\_registry\_api\_tls TLS configuration for Schema Registry API. | Property | Value | | --- | --- | | Type | array | | Default | [] | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | ### [](#schema_registry_replication_factor)schema\_registry\_replication\_factor Replication factor for internal `_schemas` topic. If unset, defaults to the [`default_topic_replication`](../cluster-properties/#default_topic_replication) cluster property. | Property | Value | | --- | --- | | Type | integer | | Range | [-32768, 32767] | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Example | pandaproxy: pandaproxy_api: address: 0.0.0.0 port: 8082 authentication_method: http_basic client_cache_max_size: 10 client_keep_alive: 300000 consumer_instance_timeout_ms: 300000 | | Related topics | default_topic_replicationdefault_topic_replication | ## [](#http-proxy-client)HTTP Proxy client Configuration options for how the HTTP Proxy **connects to Kafka brokers**. The HTTP Proxy acts as a bridge: external clients make REST API calls to the HTTP Proxy server (configured in the [`pandaproxy`](#HTTP Proxy \(pandaproxy\)) section), and the HTTP Proxy uses these client settings to connect to your Kafka cluster. Example ```yaml pandaproxy_client: brokers: - address: port: - address: port: sasl_mechanism: scram_username: scram_password: produce_ack_level: -1 retries: 5 ``` Replace the following placeholders with your values: - ``, ``: IP addresses or hostnames of your Kafka brokers - ``: Port number for the Kafka API (default `9092`) - ``: SCRAM authentication mechanism (`SCRAM-SHA-256` or `SCRAM-SHA-512`) - ``: SCRAM username for authentication - ``: SCRAM password for authentication ### [](#broker_tls)broker\_tls TLS configuration for the Kafka API servers to which the HTTP Proxy client should connect. | Property | Value | | --- | --- | | Type | object | | Default | {crl_file: null, enable_renegotiation: null, enabled: null, key_cert: null, min_tls_version: null, require_client_auth: null, tls_v1_2_cipher_suites: null, tls_v1_3_cipher_suites: null, truststore_file: null} | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | ### [](#brokers)brokers Network addresses of the Kafka API servers to which the HTTP Proxy client should connect. | Property | Value | | --- | --- | | Type | array | | Default | [] | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | ### [](#client_identifier)client\_identifier Custom identifier to include in the Kafka request header for the HTTP Proxy client. This identifier can help debug or monitor client activities. | Property | Value | | --- | --- | | Type | string | | Default | test_client | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | ### [](#consumer_heartbeat_interval_ms)consumer\_heartbeat\_interval\_ms Interval (in milliseconds) for consumer heartbeats. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | No | | Unit | Milliseconds | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#consumer_rebalance_timeout_ms)consumer\_rebalance\_timeout\_ms Timeout (in milliseconds) for consumer rebalance. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | No | | Unit | Milliseconds | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#consumer_request_max_bytes)consumer\_request\_max\_bytes Maximum bytes to fetch per request. | Property | Value | | --- | --- | | Type | integer | | Range | [-2147483648, 2147483647] | | Default | 1048576 | | Nullable | No | | Unit | Bytes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | ### [](#consumer_request_min_bytes)consumer\_request\_min\_bytes Minimum bytes to fetch per request. | Property | Value | | --- | --- | | Type | integer | | Range | [-2147483648, 2147483647] | | Default | 1 | | Nullable | No | | Unit | Bytes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | ### [](#consumer_request_timeout_ms)consumer\_request\_timeout\_ms Interval (in milliseconds) for consumer request timeout. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | No | | Unit | Milliseconds | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#consumer_session_timeout_ms)consumer\_session\_timeout\_ms Timeout (in milliseconds) for consumer session. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | No | | Unit | Milliseconds | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#produce_ack_level)produce\_ack\_level Number of acknowledgments the producer requires the leader to have received before considering a request complete. | Property | Value | | --- | --- | | Type | integer | | Range | [-32768, 32767] | | Default | -1 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | ### [](#produce_batch_delay_ms)produce\_batch\_delay\_ms Delay (in milliseconds) to wait before sending batch. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | No | | Unit | Milliseconds | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#produce_batch_record_count)produce\_batch\_record\_count Number of records to batch before sending to broker. | Property | Value | | --- | --- | | Type | integer | | Range | [-2147483648, 2147483647] | | Default | 1000 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | ### [](#produce_batch_size_bytes)produce\_batch\_size\_bytes Number of bytes to batch before sending to broker. | Property | Value | | --- | --- | | Type | integer | | Range | [-2147483648, 2147483647] | | Default | 1048576 | | Nullable | No | | Unit | Bytes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | ### [](#produce_compression_type)produce\_compression\_type Enable or disable compression by the Kafka client. Specify `none` to disable compression or one of the supported types \[gzip, snappy, lz4, zstd\]. | Property | Value | | --- | --- | | Type | string | | Default | none | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | ### [](#produce_shutdown_delay_ms)produce\_shutdown\_delay\_ms Delay (in milliseconds) to allow for final flush of buffers before shutting down. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | No | | Unit | Milliseconds | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#retries)retries Number of times to retry a request to a broker. | Property | Value | | --- | --- | | Type | integer | | Default | 5 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | ### [](#retry_base_backoff_ms)retry\_base\_backoff\_ms Delay (in milliseconds) for initial retry backoff. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | No | | Unit | Milliseconds | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#sasl_mechanism)sasl\_mechanism The SASL mechanism to use when the HTTP Proxy client connects to the Kafka API. These credentials are used when the HTTP Proxy API listener has [`authentication_method`](#http_proxy_auth_method): `none` but the cluster requires authenticated access to the Kafka API. This property specifies which individual SASL mechanism the HTTP Proxy client should use, while the cluster-wide available mechanisms are configured using the [`sasl_mechanisms`](../cluster-properties/#sasl_mechanisms) cluster property. **Breaking change in Redpanda 25.2:** Ephemeral credentials for HTTP Proxy are removed. If your HTTP Proxy API listeners use [`authentication_method`](#http_proxy_auth_method): `none`, you must configure explicit SASL credentials ([`scram_username`](#scram_username), [`scram_password`](#scram_password), and [`sasl_mechanism`](#sasl_mechanism)) for HTTP Proxy to authenticate with the Kafka API. > ⚠️ **WARNING** > > This allows any HTTP API user to access Kafka using shared credentials. Redpanda Data recommends enabling [HTTP Proxy authentication](../../../develop/http-proxy/#authenticate-with-http-proxy) instead. For configuration instructions, see [Configure HTTP Proxy to connect to Redpanda with SASL](../../../manage/security/authentication/#schema-and-http-to-redpanda). For details about this breaking change, see [What’s new](../../../get-started/release-notes/redpanda/#http-proxy-authentication-changes). > 📝 **NOTE** > > While the cluster-wide [`sasl_mechanisms`](../cluster-properties/#sasl_mechanisms) property may support additional mechanisms (PLAIN, GSSAPI, OAUTHBEARER), HTTP Proxy client connections only support SCRAM mechanisms. | Property | Value | | --- | --- | | Type | string (enum) | | Accepted values | SCRAM-SHA-256, SCRAM-SHA-512, OAUTHBEARER (Enterprise) | | Default | null | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Related topics | sasl_mechanisms | ### [](#scram_password)scram\_password Password to use for SCRAM authentication mechanisms when the HTTP Proxy client connects to the Kafka API. This property is required when the HTTP Proxy API listener has [`authentication_method`](#http_proxy_auth_method): `none` but the cluster requires authenticated access to the Kafka API. **Breaking change in Redpanda 25.2:** Ephemeral credentials for HTTP Proxy are removed. If your HTTP Proxy API listeners use [`authentication_method`](#http_proxy_auth_method): `none`, you must configure explicit SASL credentials ([`scram_username`](#scram_username), [`scram_password`](#scram_password), and [`sasl_mechanism`](#sasl_mechanism)) for HTTP Proxy to authenticate with the Kafka API. > ⚠️ **WARNING** > > This allows any HTTP API user to access Kafka using shared credentials. Redpanda Data recommends enabling [HTTP Proxy authentication](../../../develop/http-proxy/#authenticate-with-http-proxy) instead. For configuration instructions, see [Configure HTTP Proxy to connect to Redpanda with SASL](../../../manage/security/authentication/#schema-and-http-to-redpanda). For details about this breaking change, see [What’s new](../../../get-started/release-notes/redpanda/#http-proxy-authentication-changes). | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | ### [](#scram_username)scram\_username Username to use for SCRAM authentication mechanisms when the HTTP Proxy client connects to the Kafka API. This property is required when the HTTP Proxy API listener has [`authentication_method`](#http_proxy_auth_method): `none` but the cluster requires authenticated access to the Kafka API. **Breaking change in Redpanda 25.2:** Ephemeral credentials for HTTP Proxy are removed. If your HTTP Proxy API listeners use [`authentication_method`](#http_proxy_auth_method): `none`, you must configure explicit SASL credentials ([`scram_username`](#scram_username), [`scram_password`](#scram_password), and [`sasl_mechanism`](#sasl_mechanism)) for HTTP Proxy to authenticate with the Kafka API. > ⚠️ **WARNING** > > This allows any HTTP API user to access Kafka using shared credentials. Redpanda Data recommends enabling [HTTP Proxy authentication](../../../develop/http-proxy/#authenticate-with-http-proxy) instead. For configuration instructions, see [Configure HTTP Proxy to connect to Redpanda with SASL](../../../manage/security/authentication/#schema-and-http-to-redpanda). For details about this breaking change, see [What’s new](../../../get-started/release-notes/redpanda/#http-proxy-authentication-changes). | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Example | schema_registry_client: brokers: - address: port: - address: port: sasl_mechanism: scram_username: scram_password: produce_batch_delay_ms: 0 produce_batch_record_count: 0 client_identifier: schema_registry_clientaudit_log_client: brokers: - address: port: - address: port: produce_batch_delay_ms: 0 produce_batch_record_count: 0 produce_batch_size_bytes: 0 produce_compression_type: zstd produce_ack_level: 1 produce_shutdown_delay_ms: 3000 client_identifier: audit_log_client | ## [](#schema-registry-client)Schema Registry client Configuration options for Schema Registry client connections to Kafka brokers. Example ```yaml schema_registry_client: brokers: - address: port: - address: port: sasl_mechanism: scram_username: scram_password: produce_batch_delay_ms: 0 produce_batch_record_count: 0 client_identifier: schema_registry_client ``` Replace the following placeholders with your values: - ``, ``: IP addresses or hostnames of your Kafka brokers - ``: Port number for the Kafka API (typically 9092) - ``: SCRAM authentication mechanism (`SCRAM-SHA-256` or `SCRAM-SHA-512`) - ``: SCRAM username for authentication - ``: SCRAM password for authentication > 📝 **NOTE** > > Schema Registry client uses the same configuration properties as HTTP Proxy client but with different defaults optimized for Schema Registry operations. The client uses immediate batching (0 ms delay, 0 record count) for low-latency schema operations. * * * ## [](#audit-log-client)Audit log client Configuration options for audit log client connections to Kafka brokers. Example ```yaml audit_log_client: brokers: - address: port: - address: port: produce_batch_delay_ms: 0 produce_batch_record_count: 0 produce_batch_size_bytes: 0 produce_compression_type: zstd produce_ack_level: 1 produce_shutdown_delay_ms: 3000 client_identifier: audit_log_client ``` Replace the following placeholders with your values: - ``, ``: IP addresses or hostnames of your Kafka brokers - ``: Port number for the Kafka API (typically 9092) > 📝 **NOTE** > > Audit log client uses the same configuration properties as HTTP Proxy client but with different defaults optimized for audit logging operations. The client uses immediate batching (0 ms delay, 0 record count) with compression enabled (zstd) and acknowledgment level 1 for reliable audit log delivery. --- # Page 264: Cluster Configuration Properties **URL**: https://docs.redpanda.com/current/reference/properties/cluster-properties.md --- # Cluster Configuration Properties --- title: Cluster Configuration Properties latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: properties/cluster-properties page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: properties/cluster-properties.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/properties/cluster-properties.adoc description: Reference of cluster configuration properties. page-git-created-date: "2024-05-23" page-git-modified-date: "2026-03-31" support-status: supported --- Cluster properties are configuration settings that control the behavior of a Redpanda cluster at a global level. Configuring cluster properties allows you to adapt Redpanda to specific workloads, optimize resource usage, and enable or disable features. For information on how to edit cluster properties, see [Configure Cluster Properties](../../../manage/cluster-maintenance/cluster-property-configuration/) or [Configure Redpanda in Kubernetes](../../../manage/kubernetes/k-configure-helm-chart/). > 📝 **NOTE** > > Some cluster properties require that you restart the cluster for any updates to take effect. See the specific property details to identify whether or not a restart is required. ## [](#cluster-configuration)Cluster configuration ### [](#abort_index_segment_size)abort\_index\_segment\_size Capacity (in number of txns) of an abort index segment. Each partition tracks the aborted transaction offset ranges to help service client requests. If the number of transactions increases beyond this threshold, they are flushed to disk to ease memory pressure. Then they’re loaded on demand. This configuration controls the maximum number of aborted transactions before they are flushed to disk. | Property | Value | | --- | --- | | Type | integer | | Maximum | 4294967295 | | Default | 50000 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#abort_timed_out_transactions_interval_ms)abort\_timed\_out\_transactions\_interval\_ms Interval, in milliseconds, at which Redpanda looks for inactive transactions and aborts them. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 10000 (10 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#admin_api_require_auth)admin\_api\_require\_auth Whether Admin API clients must provide HTTP basic authentication headers. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#aggregate_metrics)aggregate\_metrics Enable aggregation of metrics returned by the [`/metrics`](../../internal-metrics-reference/) endpoint. Aggregation can simplify monitoring by providing summarized data instead of raw, per-instance metrics. Metric aggregation is performed by summing the values of samples by labels and is done when it makes sense by the shard and/or partition labels. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Related topics | /metrics | ### [](#alive_timeout_ms)alive\_timeout\_ms The amount of time since the last broker status heartbeat. After this time, a broker is considered offline and not alive. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 5000 (5 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#append_chunk_size)append\_chunk\_size Size of direct write operations to disk in bytes. A larger chunk size can improve performance for write-heavy workloads, but increase latency for these writes as more data is collected before each write operation. A smaller chunk size can decrease write latency, but potentially increase the number of disk I/O operations. | Property | Value | | --- | --- | | Type | integer | | Default | 16384 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 32768 | ### [](#audit_client_max_buffer_size)audit\_client\_max\_buffer\_size Defines the number of bytes allocated by the internal audit client for audit messages. When changing this, you must disable audit logging and then re-enable it for the change to take effect. Consider increasing this if your system generates a very large number of audit records in a short amount of time. | Property | Value | | --- | --- | | Type | integer | | Default | 16777216 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#audit_enabled)audit\_enabled Enables or disables audit logging. When you set this to true, Redpanda checks for an existing topic named `_redpanda.audit_log`. If none is found, Redpanda automatically creates one for you. > 📝 **NOTE: Enterprise license required** > > Enterprise license required > > The following values require an Enterprise license: `true` > > For license details, see [Redpanda Licensing](../../../get-started/licensing/). | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#audit_enabled_event_types)audit\_enabled\_event\_types List of strings in JSON style identifying the event types to include in the audit log. This may include any of the following: `management, produce, consume, describe, heartbeat, authenticate, schema_registry, admin`. | Property | Value | | --- | --- | | Type | array | | Default | [management, authenticate, admin] | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | ["management", "describe"] | ### [](#audit_excluded_principals)audit\_excluded\_principals List of user principals to exclude from auditing. | Property | Value | | --- | --- | | Type | array | | Default | [] | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | ["User:principal1","User:principal2"] | ### [](#audit_excluded_topics)audit\_excluded\_topics List of topics to exclude from auditing. | Property | Value | | --- | --- | | Type | array | | Default | [] | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | ["topic1","topic2"] | ### [](#audit_failure_policy)audit\_failure\_policy Defines the policy for rejecting audit log messages when the audit log queue is full. If set to 'permit', then new audit messages are dropped and the operation is permitted. If set to 'reject', then the operation is rejected. | Property | Value | | --- | --- | | Type | string (enum) | | Accepted values | reject, permit | | Default | reject | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#audit_log_num_partitions)audit\_log\_num\_partitions Defines the number of partitions used by a newly-created audit topic. This configuration applies only to the audit log topic and may be different from the cluster or other topic configurations. This cannot be altered for existing audit log topics. | Property | Value | | --- | --- | | Type | integer | | Range | [-2147483648, 2147483647] | | Default | 12 | | Nullable | No | | Unit | Number of partitions per topic | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#audit_log_replication_factor)audit\_log\_replication\_factor Defines the replication factor for a newly-created audit log topic. This configuration applies only to the audit log topic and may be different from the cluster or other topic configurations. This cannot be altered for existing audit log topics. Setting this value is optional. If a value is not provided, Redpanda will use the value specified for `internal_topic_replication_factor`. | Property | Value | | --- | --- | | Type | integer | | Range | [-32768, 32767] | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#audit_queue_drain_interval_ms)audit\_queue\_drain\_interval\_ms Interval, in milliseconds, at which Redpanda flushes the queued audit log messages to the audit log topic. Longer intervals may help prevent duplicate messages, especially in high throughput scenarios, but they also increase the risk of data loss during shutdowns where the queue is lost. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 500 (500 milliseconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#audit_queue_max_buffer_size_per_shard)audit\_queue\_max\_buffer\_size\_per\_shard Defines the maximum amount of memory in bytes used by the audit buffer in each shard. Once this size is reached, requests to log additional audit messages will return a non-retryable error. Limiting the buffer size per shard helps prevent any single shard from consuming excessive memory due to audit log messages. | Property | Value | | --- | --- | | Type | integer | | Default | 1048576 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#audit_use_rpc)audit\_use\_rpc Use Redpanda’s internal communication system to write audit logs. When disabled, Redpanda uses a Kafka client to write audit logs instead. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#auto_create_topics_enabled)auto\_create\_topics\_enabled Allow automatic topic creation. To prevent excess topics, this property is not supported on Redpanda Cloud BYOC and Dedicated clusters. You should explicitly manage topic creation for these Redpanda Cloud clusters. If you produce to a topic that doesn’t exist, the topic will be created with defaults if this property is enabled. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#cloud_topics_allow_materialization_failure)cloud\_topics\_allow\_materialization\_failure **Introduced in v26.1.1** When enabled, the reconciler tolerates missing L0 extent objects (404 errors) during materialization. Failed extents are skipped, producing L1 state with empty offset ranges where deleted data was. Use this to recover partitions after accidental deletion of live extent objects. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_topics_compaction_interval_ms)cloud\_topics\_compaction\_interval\_ms **Introduced in v26.1.1** How often to trigger background compaction for cloud topics. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 30000 (30 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_topics_compaction_key_map_memory)cloud\_topics\_compaction\_key\_map\_memory **Introduced in v26.1.1** Maximum number of bytes that may be used on each shard by cloud topics compaction key-offset maps. | Property | Value | | --- | --- | | Type | integer | | Maximum | 18446744073709552000 | | Default | 134217728 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 134217728 | ### [](#cloud_topics_compaction_max_object_size)cloud\_topics\_compaction\_max\_object\_size **Introduced in v26.1.1** Maximum size in bytes for L1 objects produced by cloud topics compaction. | Property | Value | | --- | --- | | Type | integer | | Default | 134217728 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_topics_disable_level_zero_gc_for_tests)cloud\_topics\_disable\_level\_zero\_gc\_for\_tests **Introduced in v26.1.1** Disables the level-zero garbage collector in cloud topics. This property exists to simplify testing and shouldn’t be set in production. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_topics_disable_metastore_flush_loop_for_tests)cloud\_topics\_disable\_metastore\_flush\_loop\_for\_tests **Introduced in v26.1.1** Disables the metastore flush loop in cloud topics. The property exists to simplify testing of read replicas and shouldn’t be set in production. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_topics_disable_reconciliation_loop)cloud\_topics\_disable\_reconciliation\_loop Disables the cloud topics reconciliation loop. Disabling the loop can negatively impact performance and stability of the cluster. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_topics_enabled)cloud\_topics\_enabled Enable Cloud Topics for the cluster. Cloud Topics are optimized for high-throughput, cost-sensitive workloads that can tolerate higher latencies compared to standard Kafka topics. > 📝 **NOTE: Enterprise license required** > > Enterprise license required > > The following values require an Enterprise license: `true` > > For license details, see [Redpanda Licensing](../../../get-started/licensing/). | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | Cloud Topics | ### [](#cloud_topics_epoch_service_epoch_increment_interval)cloud\_topics\_epoch\_service\_epoch\_increment\_interval **Introduced in v25.3.3** The interval, in milliseconds, at which the cluster epoch is incremented. The cluster epoch is a frozen point in time of the committed offset of the controller log, used to coordinate partition creation and track changes in Tiered Storage. This property controls how frequently the epoch is refreshed. More frequent updates provide finer-grained coordination but may increase overhead. Decrease this interval if you need more frequent epoch updates for faster coordination in Tiered Storage operations, or increase it to reduce coordination overhead in stable clusters. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 600000 (10 minutes) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_topics_epoch_service_local_epoch_cache_duration)cloud\_topics\_epoch\_service\_local\_epoch\_cache\_duration **Introduced in v25.3.3** The duration, in milliseconds, for which a cluster-wide epoch is cached locally on each broker. Caching the epoch locally reduces the need for frequent coordination with the controller. This property controls how long each broker can use a cached epoch value before fetching the latest value. Increase this value to reduce coordination overhead in clusters with stable workloads. Decrease it if you need brokers to react more quickly to epoch changes in Tiered Storage. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 60000 (1 minute) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_topics_epoch_service_max_same_epoch_duration)cloud\_topics\_epoch\_service\_max\_same\_epoch\_duration **Introduced in v26.1.1** The duration of time that a node can use the exact same epoch. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 86400000 (1 day) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_topics_fetch_debounce_enabled)cloud\_topics\_fetch\_debounce\_enabled **Introduced in v26.1.1** Enables fetch debouncing in cloud topics. This mechanism guarantees that the broker fetches every object only once improving the performance and lowering the cost. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#cloud_topics_gc_health_check_interval)cloud\_topics\_gc\_health\_check\_interval **Introduced in v26.1.1** The interval at which the L0 garbage collector checks cluster health. GC will not proceed while the cluster is unhealthy. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 10000 (10 seconds) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_topics_l1_indexing_interval)cloud\_topics\_l1\_indexing\_interval **Introduced in v26.1.1** The byte interval at which index entries are created within long term storage objects for cloud topics. Index entries are stored in the object metadata and enable efficient seeking by offset or timestamp within a partition. Lower values produce more index entries (better seek granularity) at the cost of a larger footer. | Property | Value | | --- | --- | | Type | integer | | Default | 4194304 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_topics_long_term_file_deletion_delay)cloud\_topics\_long\_term\_file\_deletion\_delay **Introduced in v26.1.1** Delay before deleting stale long term files, allowing concurrent readers (e.g. read replica topics) to finish reading them before removal. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 3600000 (1 hour) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_topics_long_term_flush_interval)cloud\_topics\_long\_term\_flush\_interval **Introduced in v26.1.1** Time interval at which long term storage metadata is flushed to object storage. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 600000 (10 minutes) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_topics_long_term_garbage_collection_interval)cloud\_topics\_long\_term\_garbage\_collection\_interval Time interval after which data is garbage collected from long term storage. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 300000 (5 minutes) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_topics_metastore_lsm_apply_timeout_ms)cloud\_topics\_metastore\_lsm\_apply\_timeout\_ms **Introduced in v26.1.1** Timeout for applying a replicated write batch to the local LSM database. This may take longer than usual when L0 compaction is behind and writes are being throttled. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 300000 (5 minutes) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_topics_metastore_replication_timeout_ms)cloud\_topics\_metastore\_replication\_timeout\_ms **Introduced in v26.1.1** Timeout for L1 metastore Raft replication and waiting for the STM to apply the replicated write batch. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 30000 (30 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_topics_num_metastore_partitions)cloud\_topics\_num\_metastore\_partitions **Introduced in v26.1.1** Number of partitions for the cloud topics metastore topic, used to spread metastore load across the cluster. Higher values allow more parallel metadata operations but reduce the amount of work each partition can batch together. Only takes effect when the metastore topic is first created. | Property | Value | | --- | --- | | Type | integer | | Range | [-2147483648, 2147483647] | | Default | 3 | | Nullable | No | | Unit | Number of partitions per topic | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_topics_parallel_fetch_enabled)cloud\_topics\_parallel\_fetch\_enabled **Introduced in v26.1.1** Enable parallel fetching in cloud topics. This mechanism improves the throughput by allowing the broker to download data needed by the fetch request using multiple shards. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#cloud_topics_preregistered_object_ttl)cloud\_topics\_preregistered\_object\_ttl **Introduced in v26.1.1** Time-to-live for pre-registered L1 objects before they are expired. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 3600000 (1 hour) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_topics_produce_batching_size_threshold)cloud\_topics\_produce\_batching\_size\_threshold The size limit for the object size in cloud topics. When the amount of data on a shard reaches this limit, an upload is triggered. | Property | Value | | --- | --- | | Type | integer | | Default | 4194304 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#cloud_topics_produce_cardinality_threshold)cloud\_topics\_produce\_cardinality\_threshold Threshold for the object cardinality in cloud topics. When the number of partitions in waiting for the upload reach this limit, an upload is triggered. | Property | Value | | --- | --- | | Type | integer | | Default | 1000 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#cloud_topics_produce_no_pid_concurrency)cloud\_topics\_produce\_no\_pid\_concurrency **Introduced in v26.1.1** Maximum number of concurrent raft replication requests for producers without a producer ID (idempotency disabled). Limits how many no-PID writes can proceed past the producer queue into raft simultaneously. | Property | Value | | --- | --- | | Type | integer | | Default | 32 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_topics_produce_upload_interval)cloud\_topics\_produce\_upload\_interval Time interval after which the upload is triggered. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 250 (250 milliseconds) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#cloud_topics_produce_write_inflight_limit)cloud\_topics\_produce\_write\_inflight\_limit **Introduced in v26.1.1** Maximum number of in-flight write requests per shard in the cloud topics write pipeline. Requests that exceed this limit are queued until a slot becomes available. | Property | Value | | --- | --- | | Type | integer | | Default | 1024 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_topics_reconciliation_interval)cloud\_topics\_reconciliation\_interval Configuration property: cloud\_topics\_reconciliation\_interval | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#cloud_topics_reconciliation_max_interval)cloud\_topics\_reconciliation\_max\_interval **Introduced in v26.1.1** Maximum reconciliation interval for adaptive scheduling. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 10000 (10 seconds) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_topics_reconciliation_max_object_size)cloud\_topics\_reconciliation\_max\_object\_size **Introduced in v26.1.1** Maximum size in bytes for L1 objects produced by the reconciler. With the default target fill ratio of 0.8, this gives an effective target object size of 64 MiB. | Property | Value | | --- | --- | | Type | integer | | Default | 83886080 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_topics_reconciliation_min_interval)cloud\_topics\_reconciliation\_min\_interval **Introduced in v26.1.1** Minimum reconciliation interval for adaptive scheduling. The reconciler will not run more frequently than this. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 250 (250 milliseconds) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_topics_reconciliation_parallelism)cloud\_topics\_reconciliation\_parallelism **Introduced in v26.1.1** Maximum number, per shard, of concurrent objects built by reconciliation | Property | Value | | --- | --- | | Type | integer | | Default | 8 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_topics_reconciliation_slowdown_blend)cloud\_topics\_reconciliation\_slowdown\_blend **Introduced in v26.1.1** Blend factor for slowing down reconciliation (0.0 to 1.0). Higher values mean reconciliation lowers its frequency faster when trying to find a frequency that produces well-sized objects. Generally this should be lower than the speedup blend, because reconciliation has less opportunities to adapt its frequency when it runs less frequently. | Property | Value | | --- | --- | | Type | number | | Default | 0.4 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_topics_reconciliation_speedup_blend)cloud\_topics\_reconciliation\_speedup\_blend **Introduced in v26.1.1** Blend factor for speeding up reconciliation (0.0 to 1.0). Higher values mean reconciliation increases its frequency faster when trying to find a frequency that produces well-sized objects. | Property | Value | | --- | --- | | Type | number | | Default | 0.9 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_topics_reconciliation_target_fill_ratio)cloud\_topics\_reconciliation\_target\_fill\_ratio **Introduced in v26.1.1** Target fill ratio for L1 objects. The reconciler adapts its interval to produce objects at approximately this fill level (0.0 to 1.0). | Property | Value | | --- | --- | | Type | number | | Default | 0.8 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_topics_short_term_gc_backoff_interval)cloud\_topics\_short\_term\_gc\_backoff\_interval **Introduced in v25.3.3** The interval, in milliseconds, between invocations of the L0 garbage collection work loop when no progress is being made or errors are occurring. L0 (level-zero) objects are short-term data objects in Tiered Storage that are periodically garbage collected. When GC encounters errors or cannot make progress (for example, if there are no objects eligible for deletion), this backoff interval prevents excessive retries. Increase this value to reduce system load when GC cannot make progress. Decrease it if you need faster retry attempts after transient errors. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 60000 (1 minute) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_topics_short_term_gc_interval)cloud\_topics\_short\_term\_gc\_interval **Introduced in v25.3.3** The interval, in milliseconds, between invocations of the L0 (level-zero) garbage collection work loop when progress is being made. L0 objects are short-term data objects in Tiered Storage associated with global epochs. This property controls how frequently GC runs when it successfully deletes objects. Lower values increase GC frequency, which can help maintain lower object counts but may increase S3 API usage. Decrease this value if L0 object counts are growing too quickly and you need more aggressive garbage collection. Increase it to reduce S3 API costs in clusters with lower ingestion rates. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 10000 (10 seconds) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_topics_short_term_gc_minimum_object_age)cloud\_topics\_short\_term\_gc\_minimum\_object\_age **Introduced in v25.3.3** The minimum age, in milliseconds, of an L0 (level-zero) object before it becomes eligible for garbage collection. This grace period delays deletion of L0 objects even after they become eligible based on epoch. The delay provides a safety buffer that can support recovery in cases involving accidental deletion or other operational issues. Increase this value to extend the retention window for L0 objects, providing more time for recovery from operational errors. Decrease it to free up object storage space more quickly, but with less protection against accidental deletion. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 43200000 (12 hours) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_topics_upload_part_size)cloud\_topics\_upload\_part\_size **Introduced in v26.1.1** The part size in bytes used for multipart uploads. The minimum of 5 MiB is the smallest non-terminal part size allowed by cloud object storage providers. | Property | Value | | --- | --- | | Type | integer | | Default | 16777216 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cluster_id)cluster\_id Cluster identifier. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | No | ### [](#compacted_log_segment_size)compacted\_log\_segment\_size Size (in bytes) for each compacted log segment. | Property | Value | | --- | --- | | Type | integer | | Maximum | 18446744073709552000 | | Default | 268435456 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 268435456 | ### [](#compaction_ctrl_backlog_size)compaction\_ctrl\_backlog\_size Target backlog size for compaction controller. If not set the max backlog size is configured to 80% of total disk space available. | Property | Value | | --- | --- | | Type | integer | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#compaction_ctrl_d_coeff)compaction\_ctrl\_d\_coeff Derivative coefficient for compaction PID controller. | Property | Value | | --- | --- | | Type | number | | Default | 0.2 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#compaction_ctrl_i_coeff)compaction\_ctrl\_i\_coeff Integral coefficient for compaction PID controller. | Property | Value | | --- | --- | | Type | number | | Default | 0 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#compaction_ctrl_max_shares)compaction\_ctrl\_max\_shares Maximum number of I/O and CPU shares that compaction process can use. | Property | Value | | --- | --- | | Type | integer | | Range | [-32768, 32767] | | Default | 1000 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#compaction_ctrl_min_shares)compaction\_ctrl\_min\_shares Minimum number of I/O and CPU shares that compaction process can use. | Property | Value | | --- | --- | | Type | integer | | Range | [-32768, 32767] | | Default | 10 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#compaction_ctrl_p_coeff)compaction\_ctrl\_p\_coeff Proportional coefficient for compaction PID controller. This must be negative, because the compaction backlog should decrease when the number of compaction shares increases. | Property | Value | | --- | --- | | Type | number | | Default | -12.5 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#compaction_ctrl_update_interval_ms)compaction\_ctrl\_update\_interval\_ms The interval (in milliseconds) for updating the controller responsible for compaction tasks. The controller uses this interval to decide how to prioritize background compaction work, which is essential for maintaining efficient storage use. This is an internal-only configuration and should be enabled only after consulting with Redpanda support. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 30000 (30 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#consumer_group_lag_collection_interval)consumer\_group\_lag\_collection\_interval How often Redpanda runs the collection loop when `enable_consumer_group_metrics` is set to `consumer_lag`. Updates will not be more frequent than `health_monitor_max_metadata_age`. | Property | Value | | --- | --- | | Type | integer | | Range | [-17179869184, 17179869183] | | Default | 60 (1 minute) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#consumer_group_lag_collection_interval_sec)consumer\_group\_lag\_collection\_interval\_sec How often to run the collection loop when [`enable_consumer_group_metrics`](#enable_consumer_group_metrics) contains `consumer_lag`. Reducing the value of `consumer_group_lag_collection_interval_sec` increases the metric collection frequency, which may raise resource utilization. In most environments, this impact is minimal, but it’s best practice to monitor broker resource usage in high-scale settings. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | No | | Unit | Seconds | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#consumer_offsets_topic_batch_cache_enabled)consumer\_offsets\_topic\_batch\_cache\_enabled This property lets you enable the batch cache for the consumer offsets topic. By default, the cache for consumer offsets topic is disabled. Changing this property is not recommended in production systems, as it may affect performance. The change is applied only after the restart. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#controller_backend_housekeeping_interval_ms)controller\_backend\_housekeeping\_interval\_ms Interval between iterations of controller backend housekeeping loop. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 1000 (1 second) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#controller_backend_reconciliation_concurrency)controller\_backend\_reconciliation\_concurrency The maximum number of cluster updates the controller can process at the same time. Higher values speed up cluster changes but use more resources. | Property | Value | | --- | --- | | Type | integer | | Maximum | 4294967295 | | Default | 1024 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#controller_log_accummulation_rps_capacity_acls_and_users_operations)controller\_log\_accummulation\_rps\_capacity\_acls\_and\_users\_operations Maximum capacity of rate limit accumulation in controller ACLs and users operations limit. | Property | Value | | --- | --- | | Type | integer | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#controller_log_accummulation_rps_capacity_configuration_operations)controller\_log\_accummulation\_rps\_capacity\_configuration\_operations Maximum capacity of rate limit accumulation in controller configuration operations limit. | Property | Value | | --- | --- | | Type | integer | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#controller_log_accummulation_rps_capacity_move_operations)controller\_log\_accummulation\_rps\_capacity\_move\_operations Maximum capacity of rate limit accumulation in controller move operations limit. | Property | Value | | --- | --- | | Type | integer | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#controller_log_accummulation_rps_capacity_node_management_operations)controller\_log\_accummulation\_rps\_capacity\_node\_management\_operations Maximum capacity of rate limit accumulation in controller node management operations limit. | Property | Value | | --- | --- | | Type | integer | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#controller_log_accummulation_rps_capacity_topic_operations)controller\_log\_accummulation\_rps\_capacity\_topic\_operations Maximum capacity of rate limit accumulation in controller topic operations limit. | Property | Value | | --- | --- | | Type | integer | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#controller_snapshot_max_age_sec)controller\_snapshot\_max\_age\_sec Maximum amount of time before Redpanda attempts to create a controller snapshot after a new controller command appears. | Property | Value | | --- | --- | | Type | integer | | Range | [-17179869184, 17179869183] | | Default | 60 (1 minute) | | Nullable | No | | Unit | Seconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#core_balancing_continuous)core\_balancing\_continuous If set to `true`, move partitions between cores in runtime to maintain balanced partition distribution. > 📝 **NOTE: Enterprise license required** > > Enterprise license required > > **License-based defaults:** > > - **Community:** `false` (if no Enterprise license is present) > > - **Enterprise:** `true` (if an Enterprise license is present) > > > For license details, see [Redpanda Licensing](../../../get-started/licensing/). | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#core_balancing_debounce_timeout)core\_balancing\_debounce\_timeout Interval, in milliseconds, between trigger and invocation of core balancing. **Unit**: milliseconds | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 10000 (10 seconds) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#core_balancing_on_core_count_change)core\_balancing\_on\_core\_count\_change If set to `true`, and if after a restart the number of cores changes, Redpanda will move partitions between cores to maintain balanced partition distribution. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#cpu_profiler_enabled)cpu\_profiler\_enabled Enables CPU profiling for Redpanda. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#cpu_profiler_sample_period_ms)cpu\_profiler\_sample\_period\_ms The sample period for the CPU profiler. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 100 (100 milliseconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#data_transforms_binary_max_size)data\_transforms\_binary\_max\_size The maximum size for a deployable WebAssembly binary that the broker can store. | Property | Value | | --- | --- | | Type | integer | | Default | 10485760 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#data_transforms_commit_interval_ms)data\_transforms\_commit\_interval\_ms The commit interval at which data transforms progress. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 3000 (3 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#data_transforms_enabled)data\_transforms\_enabled Enables WebAssembly-powered data transforms directly in the broker. When `data_transforms_enabled` is set to `true`, Redpanda reserves memory for data transforms, even if no transform functions are currently deployed. This memory reservation ensures that adequate resources are available for transform functions when they are needed, but it also means that some memory is allocated regardless of usage. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#data_transforms_logging_buffer_capacity_bytes)data\_transforms\_logging\_buffer\_capacity\_bytes Buffer capacity for transform logs, per shard. Buffer occupancy is calculated as the total size of buffered log messages; that is, logs emitted but not yet produced. | Property | Value | | --- | --- | | Type | integer | | Default | 512000 | | Nullable | No | | Unit | Bytes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#data_transforms_logging_flush_interval_ms)data\_transforms\_logging\_flush\_interval\_ms Flush interval for transform logs. When a timer expires, pending logs are collected and published to the `transform_logs` topic. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 500 (500 milliseconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#data_transforms_logging_line_max_bytes)data\_transforms\_logging\_line\_max\_bytes Transform log lines truncate to this length. Truncation occurs after any character escaping. | Property | Value | | --- | --- | | Type | integer | | Default | 1024 | | Nullable | No | | Unit | Bytes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#data_transforms_per_core_memory_reservation)data\_transforms\_per\_core\_memory\_reservation The amount of memory to reserve per core for data transform (Wasm) virtual machines. Memory is reserved on boot. The maximum number of functions that can be deployed to a cluster is equal to `data_transforms_per_core_memory_reservation` / `data_transforms_per_function_memory_limit`. | Property | Value | | --- | --- | | Type | integer | | Default | 20971520 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Aliases | wasm_per_core_memory_reservation | | Example | 26214400 | ### [](#data_transforms_per_function_memory_limit)data\_transforms\_per\_function\_memory\_limit The amount of memory to give an instance of a data transform (Wasm) virtual machine. The maximum number of functions that can be deployed to a cluster is equal to `data_transforms_per_core_memory_reservation` / `data_transforms_per_function_memory_limit`. | Property | Value | | --- | --- | | Type | integer | | Default | 2097152 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Aliases | wasm_per_function_memory_limit | | Example | 5242880 | ### [](#data_transforms_read_buffer_memory_percentage)data\_transforms\_read\_buffer\_memory\_percentage > ⚠️ **WARNING** > > This property is for Redpanda internal use only. Do not use or modify this property unless specifically instructed to do so by [Redpanda Support](https://support.redpanda.com/hc/en-us). Using this property without explicit guidance from Redpanda Support could result in data loss. The percentage of available memory in the transform subsystem to use for read buffers. | Property | Value | | --- | --- | | Type | integer | | Default | 45 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 25 | ### [](#data_transforms_runtime_limit_ms)data\_transforms\_runtime\_limit\_ms The maximum amount of runtime to start up a data transform, and the time it takes for a single record to be transformed. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 3000 (3 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#data_transforms_write_buffer_memory_percentage)data\_transforms\_write\_buffer\_memory\_percentage > ⚠️ **WARNING** > > This property is for Redpanda internal use only. Do not use or modify this property unless specifically instructed to do so by [Redpanda Support](https://support.redpanda.com/hc/en-us). Using this property without explicit guidance from Redpanda Support could result in data loss. The percentage of available memory in the transform subsystem to use for write buffers. | Property | Value | | --- | --- | | Type | integer | | Default | 45 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 25 | ### [](#datalake_coordinator_snapshot_max_delay_secs)datalake\_coordinator\_snapshot\_max\_delay\_secs Maximum amount of time the coordinator waits to snapshot after a command appears in the log. | Property | Value | | --- | --- | | Type | integer | | Range | [-17179869184, 17179869183] | | Default | 15 minutes | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#datalake_disk_space_monitor_enable)datalake\_disk\_space\_monitor\_enable Option to explicitly disable enforcement of datalake disk space usage. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#datalake_disk_usage_overage_coeff)datalake\_disk\_usage\_overage\_coeff The datalake disk usage monitor reclaims the overage multiplied by this this coefficient to compensate for data that is written during the idle period between control loop invocations. | Property | Value | | --- | --- | | Type | number | | Default | 2 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 1.8 | ### [](#datalake_scheduler_block_size_bytes)datalake\_scheduler\_block\_size\_bytes Size, in bytes, of each memory block reserved for record translation, as tracked by the datalake scheduler. | Property | Value | | --- | --- | | Type | integer | | Default | 4194304 | | Nullable | No | | Unit | Bytes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#datalake_scheduler_disk_reservation_block_size)datalake\_scheduler\_disk\_reservation\_block\_size The size, in bytes, of the block of disk reservation that the datalake manager will assign to each datalake scheduler when it runs out of local reservation. | Property | Value | | --- | --- | | Type | integer | | Default | 52428800 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 10000000 | ### [](#datalake_scheduler_max_concurrent_translations)datalake\_scheduler\_max\_concurrent\_translations The maximum number of translations that the datalake scheduler will allow to run at a given time. If a translation is requested, but the number of running translations exceeds this value, the request will be put to sleep temporarily, polling until capacity becomes available. | Property | Value | | --- | --- | | Type | integer | | Default | 4 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#datalake_scheduler_time_slice_ms)datalake\_scheduler\_time\_slice\_ms Time, in milliseconds, for a datalake translation as scheduled by the datalake scheduler. After a translation is scheduled, it will run until either the time specified has elapsed or all pending records on its source partition have been translated. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 30000 (30 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#datalake_scratch_space_size_bytes)datalake\_scratch\_space\_size\_bytes Size, in bytes, of the amount of scratch space datalake should use. | Property | Value | | --- | --- | | Type | integer | | Default | 5368709120 | | Nullable | No | | Unit | Bytes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#datalake_scratch_space_soft_limit_size_percent)datalake\_scratch\_space\_soft\_limit\_size\_percent Size of the scratch space datalake soft limit expressed as a percentage of the `datalake_scratch_space_size_bytes` configuration value. | Property | Value | | --- | --- | | Type | number | | Default | 80 | | Nullable | No | | Unit | Percent | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | 80.0 | ### [](#datalake_translator_flush_bytes)datalake\_translator\_flush\_bytes Size, in bytes, of the amount of per translator data that may be flushed to disk before the translator will upload and remove its current on disk data. | Property | Value | | --- | --- | | Type | integer | | Default | 33554432 | | Nullable | No | | Unit | Bytes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#debug_bundle_auto_removal_seconds)debug\_bundle\_auto\_removal\_seconds If set, how long debug bundles are kept in the debug bundle storage directory after they are created. If not set, debug bundles are kept indefinitely. | Property | Value | | --- | --- | | Type | integer | | Range | [-17179869184, 17179869183] | | Default | null | | Nullable | Yes | | Unit | Seconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#debug_bundle_storage_dir)debug\_bundle\_storage\_dir Path to the debug bundle storage directory. Note: Changing this path does not clean up existing debug bundles. If not set, the debug bundle is stored in the Redpanda data directory specified in the redpanda.yaml broker configuration file. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#debug_load_slice_warning_depth)debug\_load\_slice\_warning\_depth The recursion depth after which debug logging is enabled automatically for the log reader. | Property | Value | | --- | --- | | Type | integer | | Maximum | 4294967295 | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#default_leaders_preference)default\_leaders\_preference Default settings for preferred location of topic partition leaders. It can be either "none" (no preference), or "racks:,,…​" (prefer brokers with rack ID from the list). The list can contain one or more rack IDs. If you specify multiple IDs, Redpanda tries to distribute the partition leader locations equally across brokers in these racks. If `[enable_rack_awareness](#enable_rack_awareness)` is set to `false`, leader pinning is disabled across the cluster. > 📝 **NOTE: Enterprise license required** > > Enterprise license required > > This property requires an Enterprise license to use. > > For license details, see [Redpanda Licensing](../../../get-started/licensing/). | Property | Value | | --- | --- | | Type | object | | Default | none | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | Leader pinning | ### [](#default_num_windows)default\_num\_windows Default number of quota tracking windows. | Property | Value | | --- | --- | | Type | integer | | Range | [-32768, 32767] | | Default | 10 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#default_redpanda_storage_mode)default\_redpanda\_storage\_mode **Introduced in v26.1.1** Set the default storage mode for new topics. This value applies to any topic created without an explicit [`redpanda.storage.mode`](#redpandastoragemode) setting (that is, when the topic’s `redpanda.storage.mode` is `unset`). Accepted values: - `unset`: Defer to the legacy [`redpanda.remote.read`](#cloud_storage_enable_remote_read) and [`redpanda.remote.write`](#cloud_storage_enable_remote_write) topic properties for Tiered Storage configuration. - `local`: Store data only on local disks, with no object storage involvement. - `tiered`: Store data on local disks and replicate it to object storage using [Tiered Storage](../../../manage/tiered-storage/). Equivalent to setting `redpanda.remote.read` and `redpanda.remote.write` to `true`. - `cloud`: Store data primarily in object storage using [Cloud Topics](../../../develop/manage-topics/cloud-topics/). | Property | Value | | --- | --- | | Type | string (enum) | | Accepted values | local, tiered, cloud, unset | | Default | unset | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | tiered | | Related topics | Tiered StorageManage Cloud Topics | ### [](#default_topic_partitions)default\_topic\_partitions Default number of partitions per topic. | Property | Value | | --- | --- | | Type | integer | | Range | [-2147483648, 2147483647] | | Default | 1 | | Nullable | No | | Unit | Number of partitions per topic | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#default_topic_replication)default\_topic\_replication Default replication factor for new topics. | Property | Value | | --- | --- | | Type | integer | | Range | [-32768, 32767] | | Default | 1 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#default_window_sec)default\_window\_sec Default quota tracking window size in milliseconds. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 1000 milliseconds | | Nullable | No | | Unit | Seconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#delete_topic_enable)delete\_topic\_enable **Introduced in v26.1.1** Enable or disable topic deletion via the Kafka DeleteTopics API. When set to false, all topic deletion requests are rejected with error code 73 (TOPIC\_DELETION\_DISABLED). This is a cluster-wide safety setting that cannot be overridden by superusers. Topics in kafka\_nodelete\_topics are always protected regardless of this setting. > 📝 **NOTE: Enterprise license required** > > Enterprise license required > > The following values require an Enterprise license: `false` > > For license details, see [Redpanda Licensing](../../../get-started/licensing/). | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#disable_batch_cache)disable\_batch\_cache Disable batch cache in log manager. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#disable_cluster_recovery_loop_for_tests)disable\_cluster\_recovery\_loop\_for\_tests > ⚠️ **WARNING** > > This property is for Redpanda internal use only. Do not use or modify this property unless specifically instructed to do so by [Redpanda Support](https://support.redpanda.com/hc/en-us). Using this property without explicit guidance from Redpanda Support could result in data loss. Disables the cluster recovery loop. This property is used to simplify testing and should not be set in production. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#disable_metrics)disable\_metrics Disable registering the metrics exposed on the internal `/metrics` endpoint. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | ### [](#disable_public_metrics)disable\_public\_metrics Disable registering the metrics exposed on the `/public_metrics` endpoint. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | ### [](#disk_reservation_percent)disk\_reservation\_percent The percentage of total disk capacity that Redpanda will avoid using. This applies both when cloud cache and log data share a disk, as well as when cloud cache uses a dedicated disk. It is recommended to not run disks near capacity to avoid blocking I/O due to low disk space, as well as avoiding performance issues associated with SSD garbage collection. | Property | Value | | --- | --- | | Type | number | | Default | 25 | | Nullable | No | | Unit | Percent | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 25.0 | ### [](#election_timeout_ms)election\_timeout\_ms Raft election timeout expressed in milliseconds. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | No | | Unit | Milliseconds | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#enable_cluster_metadata_upload_loop)enable\_cluster\_metadata\_upload\_loop Enables cluster metadata uploads. Required for [whole cluster restore](../../../manage/disaster-recovery/whole-cluster-restore/). | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Related topics | whole cluster restore | ### [](#enable_consumer_group_metrics)enable\_consumer\_group\_metrics List of enabled consumer group metrics. Accepted values include: - `group`: Enables the [`redpanda_kafka_consumer_group_consumers`](../../public-metrics-reference/#redpanda_kafka_consumer_group_consumers) and [`redpanda_kafka_consumer_group_topics`](../../public-metrics-reference/#redpanda_kafka_consumer_group_topics) metrics. - `partition`: Enables the [`redpanda_kafka_consumer_group_committed_offset`](../../public-metrics-reference/#redpanda_kafka_consumer_group_committed_offset) metric. - `consumer_lag`: Enables the [`redpanda_kafka_consumer_group_lag_max`](../../public-metrics-reference/#redpanda_kafka_consumer_group_lag_max) and [`redpanda_kafka_consumer_group_lag_sum`](../../public-metrics-reference/#redpanda_kafka_consumer_group_lag_sum) metrics Enabling `consumer_lag` may add a small amount of additional processing overhead to the brokers, especially in environments with a high number of consumer groups or partitions. | Property | Value | | --- | --- | | Type | array | | Default | [group, partition] | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Related topics | redpanda_kafka_consumer_group_consumersredpanda_kafka_consumer_group_topicsredpanda_kafka_consumer_group_committed_offsetredpanda_kafka_consumer_group_lag_maxredpanda_kafka_consumer_group_lag_sumconsumer_group_lag_collection_interval_secMonitor consumer group lag | ### [](#enable_controller_log_rate_limiting)enable\_controller\_log\_rate\_limiting Limits the write rate for the controller log. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#enable_host_metrics)enable\_host\_metrics Enable exporting of some host metrics like `/proc/diskstats`, `/proc/snmp` and `/proc/net/netstat`. Host metrics are prefixed with [`vectorized_host`](../../internal-metrics-reference/#vectorized_host_diskstats_discards) and are available on the `/metrics` endpoint. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Related topics | vectorized_host | ### [](#enable_idempotence)enable\_idempotence Enable idempotent producers. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#enable_leader_balancer)enable\_leader\_balancer Enable automatic leadership rebalancing. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#enable_metrics_reporter)enable\_metrics\_reporter Enable the cluster metrics reporter. If `true`, the metrics reporter collects and exports to Redpanda Data a set of customer usage metrics at the interval set by [`metrics_reporter_report_interval`](#metrics_reporter_report_interval). > 📝 **NOTE** > > The cluster metrics of the metrics reporter are different from [monitoring metrics](../../../manage/monitoring/). > > - The metrics reporter exports customer usage metrics for consumption by Redpanda Data. > > - Monitoring metrics are exported for consumption by Redpanda users. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | monitoring metrics | ### [](#enable_mpx_extensions)enable\_mpx\_extensions Enable Redpanda extensions for MPX. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#enable_pid_file)enable\_pid\_file Enable PID file. You should not need to change. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#enable_rack_awareness)enable\_rack\_awareness Enable rack-aware replica assignment. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#enable_sasl)enable\_sasl Enable SASL authentication for Kafka connections. Authorization is required to modify this property. See also [`kafka_enable_authorization`](#kafka_enable_authorization). | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#enable_schema_id_validation)enable\_schema\_id\_validation Controls whether Redpanda validates schema IDs in records and which topic properties are enforced. Values: - `none`: Schema validation is disabled (no schema ID checks are done). Associated topic properties cannot be modified. - `redpanda`: Schema validation is enabled. Only Redpanda topic properties are accepted. - `compat`: Schema validation is enabled. Both Redpanda and compatible topic properties are accepted. > 📝 **NOTE: Enterprise license required** > > Enterprise license required > > The following values require an Enterprise license: `compat`, `redpanda` > > For license details, see [Redpanda Licensing](../../../get-started/licensing/). | Property | Value | | --- | --- | | Type | string | | Default | none | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | Server-Side Schema ID Validation | ### [](#enable_shadow_linking)enable\_shadow\_linking Enable creating shadow links from this cluster to a remote source cluster for data replication. > 📝 **NOTE: Enterprise license required** > > Enterprise license required > > The following values require an Enterprise license: `true` > > For license details, see [Redpanda Licensing](../../../get-started/licensing/). | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#enable_transactions)enable\_transactions Enable transactions (atomic writes). | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#enable_usage)enable\_usage Enables the usage tracking mechanism, storing windowed history of kafka/cloud\_storage metrics over time. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#features_auto_enable)features\_auto\_enable Whether new feature flags auto-activate after upgrades (true) or must wait for manual activation via the Admin API (false). | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#fetch_max_bytes)fetch\_max\_bytes Maximum number of bytes returned in a fetch request. | Property | Value | | --- | --- | | Type | integer | | Default | 57671680 | | Nullable | No | | Unit | Bytes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#fetch_max_read_concurrency)fetch\_max\_read\_concurrency **Introduced in v25.3.3** The maximum number of concurrent partition reads per fetch request on each shard. Setting this higher than the default can lead to partition starvation and unneeded memory usage. | Property | Value | | --- | --- | | Type | integer | | Default | 1 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 1 | ### [](#fetch_pid_d_coeff)fetch\_pid\_d\_coeff Derivative coefficient for fetch PID controller. | Property | Value | | --- | --- | | Type | number | | Default | 0 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#fetch_pid_i_coeff)fetch\_pid\_i\_coeff Integral coefficient for fetch PID controller. | Property | Value | | --- | --- | | Type | number | | Default | 0.01 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#fetch_pid_max_debounce_ms)fetch\_pid\_max\_debounce\_ms The maximum debounce time the fetch PID controller will apply, in milliseconds. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 100 (100 milliseconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#fetch_pid_p_coeff)fetch\_pid\_p\_coeff Proportional coefficient for fetch PID controller. | Property | Value | | --- | --- | | Type | number | | Default | 100 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#fetch_pid_target_utilization_fraction)fetch\_pid\_target\_utilization\_fraction A fraction, between 0 and 1, for the target reactor utilization of the fetch scheduling group. | Property | Value | | --- | --- | | Type | number | | Default | 0.2 | | Nullable | No | | Unit | Fraction | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#fetch_read_strategy)fetch\_read\_strategy The strategy used to fulfill fetch requests. - `polling`: If `fetch_reads_debounce_timeout` is set to its default value, then this acts exactly like `non_polling`; otherwise, it acts like `non_polling_with_debounce` (deprecated). - `non_polling`: The backend is signaled when a partition has new data, so Redpanda does not need to repeatedly read from every partition in the fetch. Redpanda Data recommends using this value for most workloads, because it can improve fetch latency and CPU utilization. - `non_polling_with_debounce`: This option behaves like `non_polling`, but it includes a debounce mechanism with a fixed delay specified by `fetch_reads_debounce_timeout` at the start of each fetch. By introducing this delay, Redpanda can accumulate more data before processing, leading to fewer fetch operations and returning larger amounts of data. Enabling this option reduces reactor utilization, but it may also increase end-to-end latency. | Property | Value | | --- | --- | | Type | string (enum) | | Accepted values | polling, non_polling, non_polling_with_debounce, non_polling_with_pid | | Default | non_polling | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | model::fetch_read_strategy_to_string( model::fetch_read_strategy::non_polling) | ### [](#fetch_reads_debounce_timeout)fetch\_reads\_debounce\_timeout Time to wait for the next read in fetch requests when the requested minimum bytes was not reached. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 1 (1 millisecond) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#fetch_session_eviction_timeout_ms)fetch\_session\_eviction\_timeout\_ms Time duration after which the inactive fetch session is removed from the fetch session cache. Fetch sessions are used to implement the incremental fetch requests where a consumer does not send all requested partitions to the server but the server tracks them for the consumer. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 60000 (1 minute) | | Nullable | No | | Unit | Milliseconds | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#group_initial_rebalance_delay)group\_initial\_rebalance\_delay Delay added to the rebalance phase to wait for new members. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 3000 (3 seconds) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#group_max_session_timeout_ms)group\_max\_session\_timeout\_ms The maximum allowed session timeout for registered consumers. Longer timeouts give consumers more time to process messages in between heartbeats at the cost of a longer time to detect failures. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 300000 (5 minutes) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | ### [](#group_min_session_timeout_ms)group\_min\_session\_timeout\_ms The minimum allowed session timeout for registered consumers. Shorter timeouts result in quicker failure detection at the cost of more frequent consumer heartbeating, which can overwhelm broker resources. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 6000 (6 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | ### [](#group_new_member_join_timeout)group\_new\_member\_join\_timeout Timeout for new member joins. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 30000 (30 seconds) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#group_offset_retention_check_ms)group\_offset\_retention\_check\_ms Frequency rate at which the system should check for expired group offsets. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 600000 (10 minutes) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#group_offset_retention_sec)group\_offset\_retention\_sec Consumer group offset retention seconds. To disable offset retention, set this to null. | Property | Value | | --- | --- | | Type | integer | | Range | [-17179869184, 17179869183] | | Default | 604800 (1 week) | | Nullable | Yes | | Unit | Seconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#group_topic_partitions)group\_topic\_partitions Number of partitions in the internal group membership topic. | Property | Value | | --- | --- | | Type | integer | | Range | [-2147483648, 2147483647] | | Default | 16 | | Nullable | No | | Unit | Number of partitions per topic | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#health_manager_tick_interval)health\_manager\_tick\_interval How often the health manager runs. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 180000 (3 minutes) | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#health_monitor_max_metadata_age)health\_monitor\_max\_metadata\_age Maximum age of the metadata cached in the health monitor of a non-controller broker. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 10000 (10 seconds) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#http_authentication)http\_authentication A list of supported HTTP authentication mechanisms. Accepted Values: `BASIC`, `OIDC`. > 📝 **NOTE: Enterprise license required** > > Enterprise license required > > The following values require an Enterprise license: `OIDC` > > For license details, see [Redpanda Licensing](../../../get-started/licensing/). | Property | Value | | --- | --- | | Type | array | | Default | [BASIC] | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#iceberg_backlog_controller_i_coeff)iceberg\_backlog\_controller\_i\_coeff Controls how much past backlog (unprocessed work) affects the priority of processing new data in the Iceberg system. The system accumulates backlog errors over time, and this coefficient determines how much that accumulated backlog influences the urgency of data translation. | Property | Value | | --- | --- | | Type | number | | Default | 0.005 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#iceberg_backlog_controller_p_coeff)iceberg\_backlog\_controller\_p\_coeff Proportional coefficient for the Iceberg backlog controller. Number of shares assigned to the datalake scheduling group will be proportional to the backlog size error. A negative value means larger and faster changes in the number of shares in the datalake scheduling group. | Property | Value | | --- | --- | | Type | number | | Default | 0.00001 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#iceberg_catalog_base_location)iceberg\_catalog\_base\_location Base path for the object-storage-backed Iceberg catalog. After Iceberg is enabled, do not change this value. | Property | Value | | --- | --- | | Type | string | | Default | redpanda-iceberg-catalog | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#iceberg_catalog_commit_interval_ms)iceberg\_catalog\_commit\_interval\_ms The frequency at which the Iceberg coordinator commits topic files to the catalog. This is the interval between commit transactions across all topics monitored by the coordinator, not the interval between individual commits. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 1 minute | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#iceberg_catalog_type)iceberg\_catalog\_type Iceberg catalog type that Redpanda will use to commit table metadata updates. Supported types: `rest`, `object_storage`. NOTE: You must set [`iceberg_rest_catalog_endpoint`](#iceberg_rest_catalog_endpoint) at the same time that you set `iceberg_catalog_type` to `rest`. | Property | Value | | --- | --- | | Type | string (enum) | | Accepted values | object_storage, rest | | Default | object_storage | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#iceberg_default_catalog_namespace)iceberg\_default\_catalog\_namespace **Introduced in v25.3.5** The default namespace (database name) for Iceberg tables. All tables created by Redpanda will be placed in this namespace within the Iceberg catalog. Supports nested namespaces as an array of strings. > ❗ **IMPORTANT** > > This value must be configured before enabling Iceberg and must not be changed afterward. Changing it will cause Redpanda to lose track of existing tables. | Property | Value | | --- | --- | | Type | array | | Default | [redpanda] | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#iceberg_default_partition_spec)iceberg\_default\_partition\_spec Default value for the `redpanda.iceberg.partition.spec` topic property that determines the partition spec for the Iceberg table corresponding to the topic. | Property | Value | | --- | --- | | Type | string | | Default | (hour(redpanda.timestamp)) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | redpanda.iceberg.partition.specEnable Iceberg integration | ### [](#iceberg_delete)iceberg\_delete Default value for the `redpanda.iceberg.delete` topic property that determines if the corresponding Iceberg table is deleted upon deleting the topic. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#iceberg_disable_automatic_snapshot_expiry)iceberg\_disable\_automatic\_snapshot\_expiry Whether to disable automatic Iceberg snapshot expiry. This property may be useful if the Iceberg catalog expects to perform snapshot expiry on its own. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#iceberg_disable_snapshot_tagging)iceberg\_disable\_snapshot\_tagging Whether to disable tagging of Iceberg snapshots. These tags are used to ensure that the snapshots that Redpanda writes are retained during snapshot removal, which in turn, helps Redpanda ensure exactly-once delivery of records. Disabling tags is therefore not recommended, but it may be useful if the Iceberg catalog does not support tags. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#iceberg_dlq_table_suffix)iceberg\_dlq\_table\_suffix The suffix added to Iceberg table names when creating dead-letter queue (DLQ) tables for invalid records. Choose a suffix that won’t conflict with existing table names. This is especially important for catalogs that don’t support the tilde (~) character in table names. Don’t change this value after creating DLQ tables. | Property | Value | | --- | --- | | Type | string | | Default | ~dlq | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#iceberg_enabled)iceberg\_enabled Enables the translation of topic data into Iceberg tables. Setting `iceberg_enabled` to `true` activates the feature at the cluster level, but each topic must also set the `redpanda.iceberg.enabled` topic-level property to `true` to use it. If `iceberg_enabled` is set to `false`, then the feature is disabled for all topics in the cluster, overriding any topic-level settings. > 📝 **NOTE: Enterprise license required** > > Enterprise license required > > The following values require an Enterprise license: `true` > > For license details, see [Redpanda Licensing](../../../get-started/licensing/). | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | redpanda.iceberg.enabled | ### [](#iceberg_invalid_record_action)iceberg\_invalid\_record\_action Default value for the `redpanda.iceberg.invalid.record.action` topic property. | Property | Value | | --- | --- | | Type | string (enum) | | Accepted values | drop, dlq_table | | Default | dlq_table | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | redpanda.iceberg.invalid.record.actionTroubleshoot errors | ### [](#iceberg_latest_schema_cache_ttl_ms)iceberg\_latest\_schema\_cache\_ttl\_ms The TTL for caching the latest schema during translation when using the [`value_schema_latest`](../../../manage/iceberg/specify-iceberg-schema/#value_schema_latest) iceberg mode. This setting controls how long the latest schema remains cached during translation, which affects schema refresh behavior and performance. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 5 minutes | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Related topics | value_schema_latest | ### [](#iceberg_rest_catalog_authentication_mode)iceberg\_rest\_catalog\_authentication\_mode The authentication mode for client requests made to the Iceberg catalog. Choose from: `none`, `bearer`, `oauth2`, and `aws_sigv4`. In `bearer` mode, the token specified in `iceberg_rest_catalog_token` is used unconditonally, and no attempts are made to refresh the token. In `oauth2` mode, the credentials specified in `iceberg_rest_catalog_client_id` and `iceberg_rest_catalog_client_secret` are used to obtain a bearer token from the URI defined by `iceberg_rest_catalog_oauth2_server_uri`. In `aws_sigv4` mode, the same AWS credentials used for cloud storage (see `cloud_storage_region`, `cloud_storage_access_key`, `cloud_storage_secret_key`, and `cloud_storage_credentials_source`) are used to sign requests to AWS Glue catalog with SigV4. | Property | Value | | --- | --- | | Type | string (enum) | | Accepted values | none, bearer, oauth2, aws_sigv4, gcp | | Default | none | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | none | ### [](#iceberg_rest_catalog_aws_access_key)iceberg\_rest\_catalog\_aws\_access\_key AWS access key for Iceberg REST catalog SigV4 authentication. If not set, falls back to [`cloud_storage_access_key`](../object-storage-properties/#cloud_storage_access_key) when using aws\_sigv4 authentication mode. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | cloud_storage_access_key | ### [](#iceberg_rest_catalog_aws_credentials_source)iceberg\_rest\_catalog\_aws\_credentials\_source **Accepted values**: `aws_instance_metadata`, `azure_aks_oidc_federation`, `azure_vm_instance_metadata`, `config_file`, `gcp_instance_metadata`, `sts`. | Property | Value | | --- | --- | | Type | string (enum) | | Accepted values | config_file, aws_instance_metadata, sts, gcp_instance_metadata, azure_aks_oidc_federation, azure_vm_instance_metadata | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Aliases | iceberg_rest_catalog_aws_credentials_source | | Example | config_file | | Related topics | cloud_storage_credentials_source | ### [](#iceberg_rest_catalog_aws_region)iceberg\_rest\_catalog\_aws\_region AWS region for Iceberg REST catalog SigV4 authentication. If not set, falls back to [`cloud_storage_region`](../object-storage-properties/#cloud_storage_region) when using aws\_sigv4 authentication mode. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | cloud_storage_region | ### [](#iceberg_rest_catalog_aws_secret_key)iceberg\_rest\_catalog\_aws\_secret\_key AWS secret key for Iceberg REST catalog SigV4 authentication. If not set, falls back to [`cloud_storage_secret_key`](../object-storage-properties/#cloud_storage_secret_key) when using aws\_sigv4 authentication mode. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | cloud_storage_secret_key | ### [](#iceberg_rest_catalog_aws_service_name)iceberg\_rest\_catalog\_aws\_service\_name AWS service name for SigV4 signing when using aws\_sigv4 authentication mode. Defaults to 'glue' for AWS Glue Data Catalog. Can be changed to support other AWS services that provide Iceberg REST catalog APIs. | Property | Value | | --- | --- | | Type | string | | Default | glue | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#iceberg_rest_catalog_base_location)iceberg\_rest\_catalog\_base\_location Base URI for the Iceberg REST catalog. If unset, the REST catalog server determines the location. Some REST catalogs, like AWS Glue, require the client to set this. After Iceberg is enabled, do not change this value. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#iceberg_rest_catalog_client_id)iceberg\_rest\_catalog\_client\_id Iceberg REST catalog user ID. This ID is used to query the catalog API for the OAuth token. Required if catalog type is set to `rest` and `iceberg_rest_catalog_authentication_mode` is set to `oauth2`. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#iceberg_rest_catalog_client_secret)iceberg\_rest\_catalog\_client\_secret Secret used with the client ID to query the OAuth token endpoint for Iceberg REST catalog authentication. Required if catalog type is set to `rest` and `iceberg_rest_catalog_authentication_mode` is set to `oauth2`. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#iceberg_rest_catalog_crl)iceberg\_rest\_catalog\_crl The contents of a certificate revocation list for `iceberg_rest_catalog_trust`. Takes precedence over `iceberg_rest_catalog_crl_file`. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#iceberg_rest_catalog_crl_file)iceberg\_rest\_catalog\_crl\_file Path to certificate revocation list for `iceberg_rest_catalog_trust_file`. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#iceberg_rest_catalog_endpoint)iceberg\_rest\_catalog\_endpoint URL of Iceberg REST catalog endpoint. NOTE: If you set [`iceberg_catalog_type`](#iceberg_catalog_type) to `rest`, you must also set this property at the same time. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | http://hostname:8181 | ### [](#iceberg_rest_catalog_gcp_user_project)iceberg\_rest\_catalog\_gcp\_user\_project The GCP project that is billed for charges associated with Iceberg REST Catalog requests. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#iceberg_rest_catalog_oauth2_scope)iceberg\_rest\_catalog\_oauth2\_scope The OAuth scope used to retrieve access tokens for Iceberg catalog authentication. Only meaningful when `iceberg_rest_catalog_authentication_mode` is set to `oauth2` | Property | Value | | --- | --- | | Type | string | | Default | PRINCIPAL_ROLE:ALL | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#iceberg_rest_catalog_oauth2_server_uri)iceberg\_rest\_catalog\_oauth2\_server\_uri The OAuth URI used to retrieve access tokens for Iceberg catalog authentication. If left undefined, the deprecated Iceberg catalog endpoint `/v1/oauth/tokens` is used instead. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#iceberg_rest_catalog_request_timeout_ms)iceberg\_rest\_catalog\_request\_timeout\_ms Maximum length of time that Redpanda waits for a response from the REST catalog before aborting the request | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 10000 (10 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#iceberg_rest_catalog_token)iceberg\_rest\_catalog\_token Token used to access the REST Iceberg catalog. If the token is present, Redpanda ignores credentials stored in the properties [`iceberg_rest_catalog_client_id`](#iceberg_rest_catalog_client_id) and [`iceberg_rest_catalog_client_secret`](#iceberg_rest_catalog_client_secret). Required if [`iceberg_rest_catalog_authentication_mode`](#iceberg_rest_catalog_authentication_mode) is set to `bearer`. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#iceberg_rest_catalog_trust)iceberg\_rest\_catalog\_trust The contents of a certificate chain to trust for the REST Iceberg catalog. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#iceberg_rest_catalog_trust_file)iceberg\_rest\_catalog\_trust\_file Path to a file containing a certificate chain to trust for the REST Iceberg catalog. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#iceberg_rest_catalog_warehouse)iceberg\_rest\_catalog\_warehouse Warehouse to use for the Iceberg REST catalog. Redpanda queries the catalog to retrieve warehouse-specific configurations and automatically configures settings like the appropriate prefix. The prefix is appended to the catalog path (for example, `/v1/{prefix}/namespaces`). | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Aliases | iceberg_rest_catalog_prefix | ### [](#iceberg_target_backlog_size)iceberg\_target\_backlog\_size Average size per partition of the datalake translation backlog that the backlog controller tries to maintain. When the backlog size is larger than the set point, the backlog controller will increase the translation scheduling group priority. | Property | Value | | --- | --- | | Type | integer | | Maximum | 4294967295 | | Default | 104857600 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#iceberg_target_lag_ms)iceberg\_target\_lag\_ms Default value for the `redpanda.iceberg.target.lag.ms` topic property, which controls how often the data in an Iceberg table is refreshed with new data from the corresponding Redpanda topic. Redpanda attempts to commit all data produced to the topic within the lag target, subject to resource availability. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 1 minute | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | redpanda.iceberg.target.lag.ms | ### [](#iceberg_throttle_backlog_size_ratio)iceberg\_throttle\_backlog\_size\_ratio Ration of the total backlog size to the disk space at which the throttle to iceberg producers is applied. | Property | Value | | --- | --- | | Type | number | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#iceberg_topic_name_dot_replacement)iceberg\_topic\_name\_dot\_replacement A replacement string for dots in topic names when creating Iceberg table names. Use this when your downstream systems don’t allow dots in table names. The replacement string cannot contain dots. Be careful to avoid table name collisions. Don’t change this value after creating any Iceberg topics with dots in their names. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#id_allocator_batch_size)id\_allocator\_batch\_size The ID allocator allocates messages in batches (each batch is a one log record) and then serves requests from memory without touching the log until the batch is exhausted. | Property | Value | | --- | --- | | Type | integer | | Range | [-32768, 32767] | | Default | 1000 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#id_allocator_log_capacity)id\_allocator\_log\_capacity Capacity of the `id_allocator` log in number of batches. After it reaches `id_allocator_stm`, it truncates the log’s prefix. | Property | Value | | --- | --- | | Type | integer | | Range | [-32768, 32767] | | Default | 100 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#initial_retention_local_target_bytes_default)initial\_retention\_local\_target\_bytes\_default Initial local retention size target for partitions of topics with [Tiered Storage](../../../manage/tiered-storage/) enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to the learner when joining the partition replica set. | Property | Value | | --- | --- | | Type | integer | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | Tiered Storage | ### [](#initial_retention_local_target_ms_default)initial\_retention\_local\_target\_ms\_default Initial local retention time target for partitions of topics with [Tiered Storage](../../../manage/tiered-storage/) enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to the learner when joining the partition replica set. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | Tiered Storage | ### [](#internal_rpc_request_timeout_ms)internal\_rpc\_request\_timeout\_ms **Introduced in v26.1.1** Default timeout for RPC requests between Redpanda nodes. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 10000 (10 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#internal_topic_replication_factor)internal\_topic\_replication\_factor Target replication factor for internal topics. **Unit**: number of replicas per topic. | Property | Value | | --- | --- | | Type | integer | | Range | [-2147483648, 2147483647] | | Default | 3 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#join_retry_timeout_ms)join\_retry\_timeout\_ms Time between cluster join retries in milliseconds. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 5000 (5 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#kafka_batch_max_bytes)kafka\_batch\_max\_bytes The default maximum batch size for topics if the topic property [`message.max.bytes`](../topic-properties/) is not set. If the batch is compressed, the limit applies to the compressed batch size. | Property | Value | | --- | --- | | Type | integer | | Maximum | 4294967295 | | Default | 1048576 | | Nullable | No | | Unit | Bytes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Related topics | message.max.bytes | ### [](#kafka_connection_rate_limit)kafka\_connection\_rate\_limit Maximum connections per second for one core. If `null` (the default), then the number of connections per second is unlimited. | Property | Value | | --- | --- | | Type | integer | | Range | [-9223372036854776000, 9223372036854776000] | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#kafka_connection_rate_limit_overrides)kafka\_connection\_rate\_limit\_overrides Overrides the maximum connections per second for one core for the specified IP addresses (for example, `['127.0.0.1:90', '50.20.1.1:40']`) | Property | Value | | --- | --- | | Type | array | | Default | [] | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | ['127.0.0.1:90', '50.20.1.1:40'] | | Related topics | Limit client connectionsLimit client connections | ### [](#kafka_connections_max)kafka\_connections\_max Maximum number of Kafka client connections per broker. If `null`, the property is disabled. **Unit**: number of Kafka client connections per broker **Default**: null | Property | Value | | --- | --- | | Type | integer | | Maximum | 4294967295 | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | Limit client connectionsLimit client connections | ### [](#kafka_connections_max_overrides)kafka\_connections\_max\_overrides A list of IP addresses for which Kafka client connection limits are overridden and don’t apply. For example, `(['127.0.0.1:90', '50.20.1.1:40']).`. | Property | Value | | --- | --- | | Type | array | | Default | [] | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | ['127.0.0.1:90', '50.20.1.1:40'] | | Related topics | Limit client connectionsLimit client connections | ### [](#kafka_connections_max_per_ip)kafka\_connections\_max\_per\_ip Maximum number of Kafka client connections per IP address, per broker. If `null`, the property is disabled. | Property | Value | | --- | --- | | Type | integer | | Maximum | 4294967295 | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | Limit client connectionsLimit client connections | ### [](#kafka_enable_authorization)kafka\_enable\_authorization Flag to require authorization for Kafka connections. If `null`, the property is disabled, and authorization is instead enabled by [`enable_sasl`](#enable_sasl). - `null`: Ignored. Authorization is enabled with `enable_sasl`: `true` - `true`: authorization is required. - `false`: authorization is disabled. | Property | Value | | --- | --- | | Type | boolean | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#kafka_enable_partition_reassignment)kafka\_enable\_partition\_reassignment Enable the Kafka partition reassignment API. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#kafka_fetch_request_timeout_ms)kafka\_fetch\_request\_timeout\_ms **Introduced in v25.3.7** Broker-side target for the duration of a single fetch request. The broker will try to complete fetches within the specified duration, even if it means returning less bytes in the fetch than are available. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 5000 (5 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#kafka_group_recovery_timeout_ms)kafka\_group\_recovery\_timeout\_ms Kafka group recovery timeout. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 30000 (30 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#kafka_max_bytes_per_fetch)kafka\_max\_bytes\_per\_fetch Limit fetch responses to this many bytes, even if the total of partition bytes limits is higher. | Property | Value | | --- | --- | | Type | integer | | Default | 67108864 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#kafka_max_message_size_upper_limit_bytes)kafka\_max\_message\_size\_upper\_limit\_bytes The maximum value you can set for the [`max.message.bytes`](../topic-properties/#maxmessagebytes) topic property. When set to `null`, no limit is enforced. | Property | Value | | --- | --- | | Type | integer | | Range | [-2147483648, 2147483647] | | Default | 104857600 | | Nullable | Yes | | Unit | Bytes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Related topics | max.message.bytes | ### [](#kafka_memory_share_for_fetch)kafka\_memory\_share\_for\_fetch The share of Kafka subsystem memory that can be used for fetch read buffers, as a fraction of the Kafka subsystem memory amount. | Property | Value | | --- | --- | | Type | number | | Default | 0.5 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#kafka_mtls_principal_mapping_rules)kafka\_mtls\_principal\_mapping\_rules Principal mapping rules for mTLS authentication on the Kafka API. If `null`, the property is disabled. | Property | Value | | --- | --- | | Type | array | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#kafka_nodelete_topics)kafka\_nodelete\_topics A list of topics that are protected from deletion and configuration changes by Kafka clients. Set by default to a list of Redpanda internal topics. | Property | Value | | --- | --- | | Type | array | | Default | [_redpanda.audit_log, __consumer_offsets, _schemas] | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | Consumer OffsetsSchema Registry | ### [](#kafka_noproduce_topics)kafka\_noproduce\_topics A list of topics that are protected from being produced to by Kafka clients. Set by default to a list of Redpanda internal topics. | Property | Value | | --- | --- | | Type | array | | Default | [] | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#kafka_produce_batch_validation)kafka\_produce\_batch\_validation Controls the level of validation performed on batches produced to Redpanda. When set to `legacy`, there is minimal validation performed on the produce path. When set to `relaxed`, full validation is performed on uncompressed batches and on compressed batches with the `max_timestamp` value left unset. When set to `strict`, full validation of uncompressed and compressed batches is performed. This should be the default in environments where producing clients are not trusted. | Property | Value | | --- | --- | | Type | string (enum) | | Accepted values | legacy, relaxed, strict | | Default | relaxed | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#kafka_qdc_depth_alpha)kafka\_qdc\_depth\_alpha Smoothing factor for Kafka queue depth control depth tracking. | Property | Value | | --- | --- | | Type | number | | Default | 0.8 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#kafka_qdc_depth_update_ms)kafka\_qdc\_depth\_update\_ms Update frequency for Kafka queue depth control. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 7000 (7 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#kafka_qdc_enable)kafka\_qdc\_enable Enable kafka queue depth control. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#kafka_qdc_idle_depth)kafka\_qdc\_idle\_depth Queue depth when idleness is detected in Kafka queue depth control. | Property | Value | | --- | --- | | Type | integer | | Default | 10 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#kafka_qdc_latency_alpha)kafka\_qdc\_latency\_alpha Smoothing parameter for Kafka queue depth control latency tracking. | Property | Value | | --- | --- | | Type | number | | Default | 0.002 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#kafka_qdc_max_depth)kafka\_qdc\_max\_depth Maximum queue depth used in Kafka queue depth control. | Property | Value | | --- | --- | | Type | integer | | Default | 100 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#kafka_qdc_max_latency_ms)kafka\_qdc\_max\_latency\_ms Maximum latency threshold for Kafka queue depth control depth tracking. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 80 (80 milliseconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#kafka_qdc_min_depth)kafka\_qdc\_min\_depth Minimum queue depth used in Kafka queue depth control. | Property | Value | | --- | --- | | Type | integer | | Default | 1 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#kafka_qdc_window_count)kafka\_qdc\_window\_count Number of windows used in Kafka queue depth control latency tracking. | Property | Value | | --- | --- | | Type | integer | | Default | 12 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#kafka_qdc_window_size_ms)kafka\_qdc\_window\_size\_ms Window size for Kafka queue depth control latency tracking. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 1500 (1500 milliseconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#kafka_request_max_bytes)kafka\_request\_max\_bytes Maximum size of a single request processed using the Kafka API. | Property | Value | | --- | --- | | Type | integer | | Maximum | 4294967295 | | Default | 104857600 | | Nullable | No | | Unit | Bytes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#kafka_rpc_server_stream_recv_buf)kafka\_rpc\_server\_stream\_recv\_buf Maximum size of the user-space receive buffer. If `null`, this limit is not applied. | Property | Value | | --- | --- | | Type | integer | | Default | null | | Nullable | Yes | | Unit | Bytes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 65536 | ### [](#kafka_rpc_server_tcp_recv_buf)kafka\_rpc\_server\_tcp\_recv\_buf Size of the Kafka server TCP receive buffer. If `null`, the property is disabled. | Property | Value | | --- | --- | | Type | integer | | Range | [-2147483648, 2147483647] | | Default | null | | Nullable | Yes | | Unit | Bytes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Example | 65536 | ### [](#kafka_rpc_server_tcp_send_buf)kafka\_rpc\_server\_tcp\_send\_buf Size of the Kafka server TCP transmit buffer. If `null`, the property is disabled. | Property | Value | | --- | --- | | Type | integer | | Range | [-2147483648, 2147483647] | | Default | null | | Nullable | Yes | | Unit | Bytes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Example | 65536 | ### [](#kafka_sasl_max_reauth_ms)kafka\_sasl\_max\_reauth\_ms The maximum time between Kafka client reauthentications. If a client has not reauthenticated a connection within this time frame, that connection is torn down. > ❗ **IMPORTANT** > > If this property is not set (or set to `null`), session expiry is disabled, and a connection could live long after the client’s credentials are expired or revoked. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | null | | Nullable | Yes | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | 1000 | ### [](#kafka_schema_id_validation_cache_capacity)kafka\_schema\_id\_validation\_cache\_capacity Per-shard capacity of the cache for validating schema IDs. | Property | Value | | --- | --- | | Type | integer | | Default | 128 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#kafka_tcp_keepalive_idle_timeout_seconds)kafka\_tcp\_keepalive\_idle\_timeout\_seconds TCP keepalive idle timeout in seconds for Kafka connections. This describes the timeout between TCP keepalive probes that the remote site successfully acknowledged. Refers to the TCP\_KEEPIDLE socket option. When changed, applies to new connections only. | Property | Value | | --- | --- | | Type | integer | | Range | [-17179869184, 17179869183] | | Default | 120 (2 minutes) | | Nullable | No | | Unit | Seconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#kafka_tcp_keepalive_probe_interval_seconds)kafka\_tcp\_keepalive\_probe\_interval\_seconds TCP keepalive probe interval in seconds for Kafka connections. This describes the timeout between unacknowledged TCP keepalives. Refers to the TCP\_KEEPINTVL socket option. When changed, applies to new connections only. | Property | Value | | --- | --- | | Type | integer | | Range | [-17179869184, 17179869183] | | Default | 60 (1 minute) | | Nullable | No | | Unit | Seconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#kafka_tcp_keepalive_probes)kafka\_tcp\_keepalive\_probes TCP keepalive unacknowledged probes until the connection is considered dead for Kafka connections. Refers to the TCP\_KEEPCNT socket option. When changed, applies to new connections only. | Property | Value | | --- | --- | | Type | integer | | Maximum | 4294967295 | | Default | 3 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#kafka_throughput_control)kafka\_throughput\_control List of throughput control groups that define exclusions from broker-wide throughput limits. Clients excluded from broker-wide throughput limits are still potentially subject to client-specific throughput limits. Each throughput control group consists of: - `name` (optional) - any unique group name - `client_id` - regex to match client\_id Example values: - `[{'name': 'first_group','client_id': 'client1'}, {'client_id': 'consumer-\d+'}]` - `[{'name': 'catch all'}]` - `[{'name': 'missing_id', 'client_id': '+empty'}]` A connection is assigned the first matching group and is then excluded from throughput control. A `name` is not required, but can help you categorize the exclusions. Specifying `+empty` for the `client_id` will match on clients that opt not to send a `client_id`. You can also optionally omit the `client_id` and specify only a `name`, as shown. In this situation, all clients will match the rule and Redpanda will exclude them from all from broker-wide throughput control. | Property | Value | | --- | --- | | Type | array | | Default | [] | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | [{'name': 'first_group','client_id': 'client1'}, {'client_id': 'consumer-\d+'}, {'name': 'catch all'}] | | Related topics | Manage throughput | ### [](#kafka_throughput_controlled_api_keys)kafka\_throughput\_controlled\_api\_keys List of Kafka API keys that are subject to cluster-wide and node-wide throughput limit control. | Property | Value | | --- | --- | | Type | array | | Default | [produce, fetch] | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#kafka_throughput_limit_node_in_bps)kafka\_throughput\_limit\_node\_in\_bps The maximum rate of all ingress Kafka API traffic for a node. Includes all Kafka API traffic (requests, responses, headers, fetched data, produced data, etc.). If `null`, the property is disabled, and traffic is not limited. | Property | Value | | --- | --- | | Type | integer | | Range | [-9223372036854776000, 9223372036854776000] | | Default | null | | Nullable | Yes | | Unit | Bytes per second | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | Node-wide throughput limits | ### [](#kafka_throughput_limit_node_out_bps)kafka\_throughput\_limit\_node\_out\_bps The maximum rate of all egress Kafka traffic for a node. Includes all Kafka API traffic (requests, responses, headers, fetched data, produced data, etc.). If `null`, the property is disabled, and traffic is not limited. | Property | Value | | --- | --- | | Type | integer | | Range | [-9223372036854776000, 9223372036854776000] | | Default | null | | Nullable | Yes | | Unit | Bytes per second | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | Node-wide throughput limits | ### [](#kafka_throughput_replenish_threshold)kafka\_throughput\_replenish\_threshold Threshold for refilling the token bucket as part of enforcing throughput limits. This threshold is evaluated with each request for data. When the number of tokens to replenish exceeds this threshold, then tokens are added to the token bucket. This ensures that the atomic is not being updated for the token count with each request. The range for this threshold is automatically clamped to the corresponding throughput limit for ingress and egress. | Property | Value | | --- | --- | | Type | integer | | Range | [-9223372036854776000, 9223372036854776000] | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Related topics | kafka_throughput_limit_node_in_bpskafka_throughput_limit_node_out_bpsManage Throughput | ### [](#kafka_topics_max)kafka\_topics\_max Maximum number of Kafka user topics that can be created. If `null`, then no limit is enforced. | Property | Value | | --- | --- | | Type | integer | | Maximum | 4294967295 | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#kvstore_flush_interval)kvstore\_flush\_interval Key-value store flush interval (in milliseconds). | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 10 milliseconds | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#kvstore_max_segment_size)kvstore\_max\_segment\_size Key-value maximum segment size (in bytes). | Property | Value | | --- | --- | | Type | integer | | Default | 16777216 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#leader_balancer_idle_timeout)leader\_balancer\_idle\_timeout Leadership rebalancing idle timeout. **Unit**: milliseconds | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 120000 (2 minutes) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#leader_balancer_mode)leader\_balancer\_mode Mode of the leader balancer optimization strategy. Accepted values: - `calibrated` (default): An adaptive strategy that samples potential moves and prioritizes high-impact transfers. Minimizes unnecessary leader movement while achieving balance over time. Best for most production workloads. - `random`: Accepts the first random move that improves balance. Less efficient than `calibrated` because it doesn’t prioritize high-impact moves. Available as a fallback if `calibrated` causes unexpected behavior. Legacy values `greedy_balanced_shards` and `random_hill_climbing` are treated as `calibrated`. | Property | Value | | --- | --- | | Type | string (enum) | | Accepted values | calibrated, random | | Default | calibrated | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | model::leader_balancer_mode_to_string( model::leader_balancer_mode::calibrated) | ### [](#leader_balancer_mute_timeout)leader\_balancer\_mute\_timeout The length of time that a [Raft](https://raft.github.io/) group is muted after a leadership rebalance operation. Any group that has been moved, regardless of whether the move succeeded or failed, undergoes a cooling-off period. This prevents Raft groups from repeatedly experiencing leadership rebalance operations in a short time frame, which can lead to instability in the cluster. The leader balancer maintains a list of muted groups and reevaluates muted status at the start of each balancing iteration. Muted groups still contribute to overall cluster balance calculations although they can’t themselves be moved until the mute period is over. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 300000 (5 minutes) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#leader_balancer_node_mute_timeout)leader\_balancer\_node\_mute\_timeout The duration after which a broker that hasn’t sent a heartbeat is considered muted. This timeout sets a threshold for identifying brokers that shouldn’t be targeted for leadership transfers when the cluster rebalances, for example, because of unreliable network connectivity. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 20000 (20 seconds) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#leader_balancer_transfer_limit_per_shard)leader\_balancer\_transfer\_limit\_per\_shard Per shard limit for in-progress leadership transfers. | Property | Value | | --- | --- | | Type | integer | | Default | 512 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#legacy_group_offset_retention_enabled)legacy\_group\_offset\_retention\_enabled Group offset retention is enabled by default starting in Redpanda version 23.1. To enable offset retention after upgrading from an older version, set this option to true. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#legacy_permit_unsafe_log_operation)legacy\_permit\_unsafe\_log\_operation Flag to enable a Redpanda cluster operator to use unsafe control characters within strings, such as consumer group names or user names. This flag applies only for Redpanda clusters that were originally on version 23.1 or earlier and have been upgraded to version 23.2 or later. Starting in version 23.2, newly-created Redpanda clusters ignore this property. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#legacy_unsafe_log_warning_interval_sec)legacy\_unsafe\_log\_warning\_interval\_sec Period at which to log a warning about using unsafe strings containing control characters. If unsafe strings are permitted by `legacy_permit_unsafe_log_operation`, a warning will be logged at an interval specified by this property. | Property | Value | | --- | --- | | Type | integer | | Range | [-17179869184, 17179869183] | | Default | 300 (5 minutes) | | Nullable | No | | Unit | Seconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#log_cleanup_policy)log\_cleanup\_policy Default cleanup policy for topic logs. The topic property [`cleanup.policy`](../topic-properties/#cleanuppolicy) overrides the value of `log_cleanup_policy` at the topic level. | Property | Value | | --- | --- | | Type | string (enum) | | Accepted values | none, delete, compact | | Default | delete | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | compact,delete | | Related topics | cleanup.policy | ### [](#log_compaction_disable_tx_batch_removal)log\_compaction\_disable\_tx\_batch\_removal Prevents log compaction from removing transaction metadata. Only set this to `true` if you experience stability issues related to transaction cleanup during compaction. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#log_compaction_interval_ms)log\_compaction\_interval\_ms How often to trigger background compaction. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 10000 (10 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#log_compaction_max_priority_wait_ms)log\_compaction\_max\_priority\_wait\_ms **Introduced in v25.3.8** Maximum time a priority partition (for example, `__consumer_offsets`) can wait for compaction before preempting regular compaction. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 3600000 (1 hour) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#log_compaction_merge_max_ranges)log\_compaction\_merge\_max\_ranges The maximum range of segments that can be processed in a single round of adjacent segment compaction. If `null` (the default value), no maximum is imposed on the number of ranges that can be processed at once. A value below 1 effectively disables adjacent merge compaction. | Property | Value | | --- | --- | | Type | integer | | Maximum | 4294967295 | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#log_compaction_merge_max_segments_per_range)log\_compaction\_merge\_max\_segments\_per\_range The maximum number of segments that can be combined into a single segment during an adjacent merge operation. If `null` (the default value), no maximum is imposed on the number of segments that can be combined at once. A value below 2 effectively disables adjacent merge compaction. | Property | Value | | --- | --- | | Type | integer | | Maximum | 4294967295 | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#log_compaction_pause_use_sliding_window)log\_compaction\_pause\_use\_sliding\_window Pause use of sliding window compaction. Toggle to `true` _only_ when you want to force adjacent segment compaction. The memory reserved by `storage_compaction_key_map_memory` is not freed when this is set to `true`. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#log_compaction_tx_batch_removal_enabled)log\_compaction\_tx\_batch\_removal\_enabled Enables removal of transactional control batches during compaction. These batches are removed according to a topic’s configured delete.retention.ms, and only if the topic’s cleanup.policy allows compaction. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#log_compaction_use_sliding_window)log\_compaction\_use\_sliding\_window Use sliding window compaction. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#log_compression_type)log\_compression\_type > ❗ **IMPORTANT** > > This property is ignored regardless of the value specified. The behavior is always the same as the `producer` value. Redpanda brokers do not compress or recompress data based on this property. If producers send compressed data, Redpanda stores it as-is; if producers send uncompressed data, Redpanda stores it uncompressed. Other listed values are accepted for Apache Kafka compatibility but are ignored by the broker. This property may appear in Admin API and `rpk topic describe` outputs for compatibility. Default for the Kafka-compatible compression.type property. Redpanda does not recompress data. The topic property [`compression.type`](../topic-properties/#compressiontype) overrides the value of `log_compression_type` at the topic level. | Property | Value | | --- | --- | | Type | string (enum) | | Accepted values | none, gzip, snappy, lz4, zstd, count, producer | | Default | producer | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | snappy | | Related topics | compression.type | ### [](#log_disable_housekeeping_for_tests)log\_disable\_housekeeping\_for\_tests Disables the housekeeping loop for local storage. This property is used to simplify testing, and should not be set in production. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#log_message_timestamp_after_max_ms)log\_message\_timestamp\_after\_max\_ms The maximum allowed time difference when a record’s timestamp is in the future compared to the broker’s clock. For topics using [`CreateTime`](#log_message_timestamp_type) timestamps, Redpanda rejects records with timestamps that are too far in the future. This property has no effect on topics using [`AppendTime`](#log_message_timestamp_type) timestamps. The topic property [`message.timestamp.after.max.ms`](../topic-properties/#messagetimestampaftermaxms) overrides this cluster-level setting. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 3600000 (1 hour) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | message.timestamp.after.max.ms | ### [](#log_message_timestamp_before_max_ms)log\_message\_timestamp\_before\_max\_ms The maximum allowed time difference when a record’s timestamp is in the past compared to the broker’s clock. For topics using [`CreateTime`](#log_message_timestamp_type) timestamps, Redpanda rejects records with timestamps that are too far in the past. This property has no effect on topics using [`AppendTime`](#log_message_timestamp_type) timestamps. The topic property [`message.timestamp.before.max.ms`](../topic-properties/#messagetimestampbeforemaxms) overrides this cluster-level setting. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 9223372036854 | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | message.timestamp.before.max.ms | ### [](#log_message_timestamp_type)log\_message\_timestamp\_type Default timestamp type for topic messages (CreateTime or LogAppendTime). The topic property [`message.timestamp.type`](../topic-properties/#messagetimestamptype) overrides the value of `log_message_timestamp_type` at the topic level. | Property | Value | | --- | --- | | Type | string (enum) | | Accepted values | CreateTime, LogAppendTime | | Default | CreateTime | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | LogAppendTime | | Related topics | message.timestamp.type | ### [](#log_retention_ms)log\_retention\_ms The amount of time to keep a log file before deleting it (in milliseconds). If set to `-1`, no time limit is applied. This is a cluster-wide default when a topic does not set or disable [`retention.ms`](../topic-properties/#retentionms). | Property | Value | | --- | --- | | Type | retention_duration_property | | Default | 604800000 (1 week) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Aliases | delete_retention_ms | | Related topics | retention.ms | ### [](#log_segment_ms)log\_segment\_ms Default lifetime of log segments. If `null`, the property is disabled, and no default lifetime is set. Any value under 60 seconds (60000 ms) is rejected. This property can also be set in the Kafka API using the Kafka-compatible alias, `log.roll.ms`. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 2 weeks | | Nullable | Yes | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | 3600000 | | Related topics | segment.ms | ### [](#log_segment_ms_max)log\_segment\_ms\_max Upper bound on topic `segment.ms`: higher values will be clamped to this value. **Unit**: milliseconds | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 31536000000 (1 year) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 31536000000 | ### [](#log_segment_ms_min)log\_segment\_ms\_min Lower bound on topic `segment.ms`: lower values will be clamped to this value. **Unit**: milliseconds | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 600000 (10 minutes) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 600000 | ### [](#log_segment_size)log\_segment\_size Default log segment size in bytes for topics which do not set `segment.bytes`. | Property | Value | | --- | --- | | Type | integer | | Maximum | 18446744073709552000 | | Default | 134217728 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 2147483648 | ### [](#log_segment_size_jitter_percent)log\_segment\_size\_jitter\_percent Random variation to the segment size limit used for each partition. | Property | Value | | --- | --- | | Type | integer | | Maximum | 65535 | | Default | 5 | | Nullable | No | | Unit | Percent | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 2 | ### [](#log_segment_size_max)log\_segment\_size\_max Upper bound on topic `segment.bytes`: higher values will be clamped to this limit. | Property | Value | | --- | --- | | Type | integer | | Maximum | 18446744073709552000 | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 268435456 | ### [](#log_segment_size_min)log\_segment\_size\_min Lower bound on topic `segment.bytes`: lower values will be clamped to this limit. | Property | Value | | --- | --- | | Type | integer | | Maximum | 18446744073709552000 | | Default | 1048576 | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 16777216 | ### [](#lz4_decompress_reusable_buffers_disabled)lz4\_decompress\_reusable\_buffers\_disabled Disable reusable preallocated buffers for LZ4 decompression. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#max_compacted_log_segment_size)max\_compacted\_log\_segment\_size Maximum compacted segment size after consolidation. | Property | Value | | --- | --- | | Type | integer | | Default | 536870912 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 10737418240 | ### [](#max_compaction_lag_ms)max\_compaction\_lag\_ms For a compacted topic, the maximum time a message remains ineligible for compaction. The topic property `max.compaction.lag.ms` overrides this property. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 9223372036854 | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | max.compaction.lag.ms | ### [](#max_concurrent_producer_ids)max\_concurrent\_producer\_ids Maximum number of active producer sessions per shard. Each shard tracks producer IDs using an LRU (Least Recently Used) eviction policy. When the configured limit is exceeded, the least recently used producer IDs are evicted from the cache. If you upgrade from 23.2.x to 23.3.x and encounter `OUT_OF_SEQUENCE` errors, consider increasing this value. In 23.3.x, the configuration changed from a per-partition basis to a per-shard basis. > ❗ **IMPORTANT** > > The default value is unlimited, which can lead to unbounded memory growth and out-of-memory (OOM) crashes in production environments with heavy producer usage, especially when using transactions or idempotent producers. Set a reasonable limit in production deployments. | Property | Value | | --- | --- | | Type | integer | | Maximum | 18446744073709552000 | | Default | Maximum value | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Related topics | Tune producer ID limitstransactional_id_expiration_msMonitor Redpanda | ### [](#max_in_flight_pandaproxy_requests_per_shard)max\_in\_flight\_pandaproxy\_requests\_per\_shard Maximum number of in-flight HTTP requests to HTTP Proxy permitted per shard. Any additional requests above this limit will be rejected with a 429 error. | Property | Value | | --- | --- | | Type | integer | | Default | 500 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#max_in_flight_schema_registry_requests_per_shard)max\_in\_flight\_schema\_registry\_requests\_per\_shard Maximum number of in-flight HTTP requests to Schema Registry permitted per shard. Any additional requests above this limit will be rejected with a 429 error. | Property | Value | | --- | --- | | Type | integer | | Default | 500 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#max_kafka_throttle_delay_ms)max\_kafka\_throttle\_delay\_ms Fail-safe maximum throttle delay on Kafka requests. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 30000 (30 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#max_transactions_per_coordinator)max\_transactions\_per\_coordinator Specifies the maximum number of active transaction sessions per coordinator. When the threshold is passed Redpanda terminates old sessions. When an idle producer corresponding to the terminated session wakes up and produces, it leads to its batches being rejected with invalid producer epoch or invalid\_producer\_id\_mapping error (depends on the transaction execution phase). For details, see [Transaction usage tips](../../../develop/transactions/#transaction-usage-tips). | Property | Value | | --- | --- | | Type | integer | | Maximum | 18446744073709552000 | | Default | Maximum value | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Related topics | Transaction usage tips | ### [](#members_backend_retry_ms)members\_backend\_retry\_ms Time between members backend reconciliation loop retries. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 5000 (5 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#memory_abort_on_alloc_failure)memory\_abort\_on\_alloc\_failure If `true`, the Redpanda process will terminate immediately when an allocation cannot be satisfied due to memory exhaustion. If false, an exception is thrown. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#metadata_dissemination_interval_ms)metadata\_dissemination\_interval\_ms Interval for metadata dissemination batching. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 3000 (3 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 5000 | ### [](#metadata_dissemination_retries)metadata\_dissemination\_retries Number of attempts to look up a topic’s metadata-like shard before a request fails. This configuration controls the number of retries that request handlers perform when internal topic metadata (for topics like tx, consumer offsets, etc) is missing. These topics are usually created on demand when users try to use the cluster for the first time and it may take some time for the creation to happen and the metadata to propagate to all the brokers (particularly the broker handling the request). In the meantime Redpanda waits and retries. This configuration controls the number retries. | Property | Value | | --- | --- | | Type | integer | | Range | [-32768, 32767] | | Default | 30 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#metadata_dissemination_retry_delay_ms)metadata\_dissemination\_retry\_delay\_ms Delay before retrying a topic lookup in a shard or other meta tables. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 500 (500 milliseconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#metrics_reporter_report_interval)metrics\_reporter\_report\_interval Cluster metrics reporter report interval. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 86400000 (1 day) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#metrics_reporter_tick_interval)metrics\_reporter\_tick\_interval Cluster metrics reporter tick interval. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 60000 (1 minute) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#metrics_reporter_url)metrics\_reporter\_url URL of the cluster metrics reporter. | Property | Value | | --- | --- | | Type | string | | Default | https://m.rp.vectorized.io/v2 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#min_cleanable_dirty_ratio)min\_cleanable\_dirty\_ratio The minimum ratio between the number of bytes in dirty segments and the total number of bytes in closed segments that must be reached before a partition’s log is eligible for compaction in a compact topic. The topic property `min.cleanable.dirty.ratio` overrides this value at the topic level. | Property | Value | | --- | --- | | Type | number | | Default | 0.2 | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | 0.2 | ### [](#min_compaction_lag_ms)min\_compaction\_lag\_ms The minimum amount of time (in ms) that a log segment must remain unaltered before it can be compacted in a compact topic. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 0 (0 milliseconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | min.compaction.lag.ms | ### [](#minimum_topic_replication)minimum\_topic\_replication Minimum allowable replication factor for topics in this cluster. The set value must be positive, odd, and equal to or less than the number of available brokers. Changing this parameter only restricts newly-created topics. Redpanda returns an `INVALID_REPLICATION_FACTOR` error on any attempt to create a topic with a replication factor less than this property. If you change the `minimum_topic_replications` setting, the replication factor of existing topics remains unchanged. However, Redpanda will log a warning on start-up with a list of any topics that have fewer replicas than this minimum. For example, you might see a message such as `Topic X has a replication factor less than specified minimum: 1 < 3`. | Property | Value | | --- | --- | | Type | integer | | Range | [-32768, 32767] | | Default | 1 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#nested_group_behavior)nested\_group\_behavior **Introduced in v26.1.1** Behavior for handling nested groups when extracting groups from authentication tokens. Two options are available - none and suffix. With none, the group is left alone (e.g. '/group/child/grandchild'). Suffix will extract the final component from the nested group (e.g. '/group' → 'group' and '/group/child/grandchild' → 'grandchild'). | Property | Value | | --- | --- | | Type | string | | Default | none | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#node_isolation_heartbeat_timeout)node\_isolation\_heartbeat\_timeout How long after the last heartbeat request a node will wait before considering itself to be isolated. | Property | Value | | --- | --- | | Type | integer | | Range | [-9223372036854776000, 9223372036854776000] | | Default | 3000 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#node_status_interval)node\_status\_interval Time interval between two node status messages. Node status messages establish liveness status outside of the Raft protocol. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 100 (100 milliseconds) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#node_status_reconnect_max_backoff_ms)node\_status\_reconnect\_max\_backoff\_ms Maximum backoff (in milliseconds) to reconnect to an unresponsive peer during node status liveness checks. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 15000 (15 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#oidc_clock_skew_tolerance)oidc\_clock\_skew\_tolerance The amount of time (in seconds) to allow for when validating the expiry claim in the token. | Property | Value | | --- | --- | | Type | integer | | Range | [-17179869184, 17179869183] | | Default | null | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#oidc_discovery_url)oidc\_discovery\_url The URL pointing to the well-known discovery endpoint for the OIDC provider. | Property | Value | | --- | --- | | Type | string | | Default | https://auth.prd.cloud.redpanda.com/.well-known/openid-configuration | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#oidc_group_claim_path)oidc\_group\_claim\_path **Introduced in v26.1.1** JSON path to extract groups from the JWT payload. | Property | Value | | --- | --- | | Type | string | | Default | $.groups | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#oidc_keys_refresh_interval)oidc\_keys\_refresh\_interval The frequency of refreshing the JSON Web Keys (JWKS) used to validate access tokens. | Property | Value | | --- | --- | | Type | integer | | Range | [-17179869184, 17179869183] | | Default | 3600 (1 hour) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#oidc_principal_mapping)oidc\_principal\_mapping Rule for mapping JWT payload claim to a Redpanda user principal. | Property | Value | | --- | --- | | Type | string | | Default | $.sub | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | OpenID Connect authenticationOpenID Connect authentication in Kubernetes | ### [](#oidc_token_audience)oidc\_token\_audience A string representing the intended recipient of the token. | Property | Value | | --- | --- | | Type | string | | Default | redpanda | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#partition_autobalancing_concurrent_moves)partition\_autobalancing\_concurrent\_moves Number of partitions that can be reassigned at once. | Property | Value | | --- | --- | | Type | integer | | Default | 50 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#partition_autobalancing_max_disk_usage_percent)partition\_autobalancing\_max\_disk\_usage\_percent > 📝 **NOTE** > > This property applies only when [`partition_autobalancing_mode`](#partition_autobalancing_mode) is set to `continuous`. When the disk usage of a node exceeds this threshold, it triggers Redpanda to move partitions off of the node. **Unit**: percent of disk used | Property | Value | | --- | --- | | Type | integer | | Maximum | 4294967295 | | Default | 80 | | Nullable | No | | Unit | Percent | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | Configure Continuous Data Balancing | ### [](#partition_autobalancing_min_size_threshold)partition\_autobalancing\_min\_size\_threshold Minimum size of partition that is going to be prioritized when rebalancing a cluster due to the disk size threshold being breached. This value is calculated automatically by default. | Property | Value | | --- | --- | | Type | integer | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#partition_autobalancing_mode)partition\_autobalancing\_mode Controls when and how Redpanda automatically rebalances partition replicas across brokers. For more information, see [partition balancing](../../../manage/cluster-maintenance/cluster-balancing/). Values: - `continuous`: Partition balancing happens automatically to maintain optimal performance and availability, based on continuous monitoring for node changes (same as `node_add`) and also high disk usage. This option requires an enterprise license, and it is customized by [`partition_autobalancing_node_availability_timeout_sec`](#partition_autobalancing_node_availability_timeout_sec) and [`partition_autobalancing_max_disk_usage_percent`](#partition_autobalancing_max_disk_usage_percent) properties. - `node_add`: Partition balancing happens when a node is added. - `off`: Partition balancing is disabled. This option is not recommended for production clusters. > 📝 **NOTE: Enterprise license required** > > Enterprise license required > > **License-based defaults:** > > - **Community:** `node_add` (if no Enterprise license is present) > > - **Enterprise:** `continuous` (if an Enterprise license is present) > > > For license details, see [Redpanda Licensing](../../../get-started/licensing/). | Property | Value | | --- | --- | | Type | string (enum) | | Accepted values | off, node_add, continuous (Enterprise) | | Default | continuous | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | node_add | | Related topics | partition balancingConfigure Continuous Data Balancingenterprise license | ### [](#partition_autobalancing_node_autodecommission_timeout_sec)partition\_autobalancing\_node\_autodecommission\_timeout\_sec **Introduced in v26.1.1** When a node is unavailable for at least this timeout duration, it triggers Redpanda to decommission the node. This property applies only when `partition_autobalancing_mode` is set to `continuous`. | Property | Value | | --- | --- | | Type | integer | | Range | [-17179869184, 17179869183] | | Default | null | | Nullable | Yes | | Unit | Seconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#partition_autobalancing_node_availability_timeout_sec)partition\_autobalancing\_node\_availability\_timeout\_sec When a node is unavailable for at least this timeout duration, it triggers Redpanda to move partitions off of the node. This property applies only when `partition_autobalancing_mode` is set to `continuous`. | Property | Value | | --- | --- | | Type | integer | | Range | [-17179869184, 17179869183] | | Default | 900 (15 minutes) | | Nullable | No | | Unit | Seconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | Configure Continuous Data Balancing | ### [](#partition_autobalancing_tick_interval_ms)partition\_autobalancing\_tick\_interval\_ms Partition autobalancer tick interval. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 30000 (30 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#partition_autobalancing_tick_moves_drop_threshold)partition\_autobalancing\_tick\_moves\_drop\_threshold If the number of scheduled tick moves drops by this ratio, a new tick is scheduled immediately. Valid values are (0, 1\]. For example, with a value of 0.2 and 100 scheduled moves in a tick, a new tick is scheduled when the in-progress moves are fewer than 80. | Property | Value | | --- | --- | | Type | number | | Default | 0.2 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#partition_autobalancing_topic_aware)partition\_autobalancing\_topic\_aware If `true`, Redpanda prioritizes balancing a topic’s partition replica count evenly across all brokers while it’s balancing the cluster’s overall partition count. Because different topics in a cluster can have vastly different load profiles, this better distributes the workload of the most heavily-used topics evenly across brokers. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#partition_manager_shutdown_watchdog_timeout)partition\_manager\_shutdown\_watchdog\_timeout A threshold value to detect partitions which might have been stuck while shutting down. After this threshold, a watchdog in partition manager will log information about partition shutdown not making progress. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 30000 (30 seconds) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#pp_sr_smp_max_non_local_requests)pp\_sr\_smp\_max\_non\_local\_requests Maximum number of Cross-core(Inter-shard communication) requests pending in HTTP Proxy and Schema Registry seastar::smp group. (For more details, see the `seastar::smp_service_group` documentation). See [Seastar documentation](https://docs.seastar.io/master/) | Property | Value | | --- | --- | | Type | integer | | Maximum | 4294967295 | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#quota_manager_gc_sec)quota\_manager\_gc\_sec Quota manager GC frequency in milliseconds. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 30000 milliseconds | | Nullable | No | | Unit | Seconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#raft_election_timeout_ms)raft\_election\_timeout\_ms Election timeout expressed in milliseconds. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 1500 (1500 milliseconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#raft_enable_longest_log_detection)raft\_enable\_longest\_log\_detection Enables an additional step in leader election where a candidate is allowed to wait for all the replies from the broker it requested votes from. This may introduce a small delay when recovering from failure, but it prevents truncation if any of the replicas have more data than the majority. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#raft_enable_lw_heartbeat)raft\_enable\_lw\_heartbeat Enables Raft optimization of heartbeats. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#raft_heartbeat_disconnect_failures)raft\_heartbeat\_disconnect\_failures The number of failed heartbeats after which an unresponsive TCP connection is forcibly closed. To disable forced disconnection, set to 0. | Property | Value | | --- | --- | | Type | integer | | Default | 3 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#raft_heartbeat_interval_ms)raft\_heartbeat\_interval\_ms Number of milliseconds for Raft leader heartbeats. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 150 milliseconds | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#raft_heartbeat_timeout_ms)raft\_heartbeat\_timeout\_ms Raft heartbeat RPC (remote procedure call) timeout. Raft uses a heartbeat mechanism to maintain leadership authority and to trigger leader elections. The `raft_heartbeat_interval_ms` is a periodic heartbeat sent by the partition leader to all followers to declare its leadership. If a follower does not receive a heartbeat within the `raft_heartbeat_timeout_ms`, then it triggers an election to choose a new partition leader. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 3000 (3 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#raft_io_timeout_ms)raft\_io\_timeout\_ms Raft I/O timeout. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 10000 (10 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#raft_learner_recovery_rate)raft\_learner\_recovery\_rate Raft learner recovery rate limit. Throttles the rate of data communicated to nodes (learners) that need to catch up to leaders. This rate limit is placed on a node sending data to a recovering node. Each sending node is limited to this rate. The recovering node accepts data as fast as possible according to the combined limits of all healthy nodes in the cluster. For example, if two nodes are sending data to the recovering node, and `raft_learner_recovery_rate` is 100 MB/sec, then the recovering node will recover at a rate of 200 MB/sec. | Property | Value | | --- | --- | | Type | integer | | Default | 104857600 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#raft_max_buffered_follower_append_entries_bytes_per_shard)raft\_max\_buffered\_follower\_append\_entries\_bytes\_per\_shard The total size of append entry requests that may be cached per shard, using the Raft-buffered protocol. When an entry is cached, the leader can continue serving requests because the ordering of the cached requests cannot change. When the total size of cached requests reaches the set limit, back pressure is applied to throttle producers. | Property | Value | | --- | --- | | Type | integer | | Default | 0 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#raft_max_inflight_follower_append_entries_requests_per_shard)raft\_max\_inflight\_follower\_append\_entries\_requests\_per\_shard The maximum number of append entry requests that may be sent from Raft groups on a Seastar shard to the current node, and are awaiting a reply. This property replaces `raft_max_concurrent_append_requests_per_follower`. | Property | Value | | --- | --- | | Type | integer | | Default | 1024 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#raft_max_recovery_memory)raft\_max\_recovery\_memory Maximum memory that can be used for reads in Raft recovery process by default 15% of total memory. | Property | Value | | --- | --- | | Type | integer | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 41943040 | ### [](#raft_recovery_concurrency_per_shard)raft\_recovery\_concurrency\_per\_shard Number of partitions that may simultaneously recover data to a particular shard. This number is limited to avoid overwhelming nodes when they come back online after an outage. | Property | Value | | --- | --- | | Type | integer | | Default | 64 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#raft_recovery_throttle_disable_dynamic_mode)raft\_recovery\_throttle\_disable\_dynamic\_mode > ⚠️ **WARNING** > > This property is for Redpanda internal use only. Do not use or modify this property unless specifically instructed to do so by [Redpanda Support](https://support.redpanda.com/hc/en-us). Using this property without explicit guidance from Redpanda Support could result in data loss. Disables cross shard sharing used to throttle recovery traffic. Should only be used to debug unexpected problems. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#raft_replica_max_flush_delay_ms)raft\_replica\_max\_flush\_delay\_ms Maximum delay between two subsequent flushes. After this delay, the log is automatically force flushed. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 100 (100 milliseconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#raft_replica_max_pending_flush_bytes)raft\_replica\_max\_pending\_flush\_bytes Maximum number of bytes that are not flushed per partition. If the configured threshold is reached, the log is automatically flushed even if it has not been explicitly requested. | Property | Value | | --- | --- | | Type | integer | | Default | 262144 | | Nullable | Yes | | Unit | Bytes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#raft_replicate_batch_window_size)raft\_replicate\_batch\_window\_size Maximum size of requests cached for replication. | Property | Value | | --- | --- | | Type | integer | | Default | 1048576 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#raft_smp_max_non_local_requests)raft\_smp\_max\_non\_local\_requests Maximum number of Cross-core(Inter-shard communication) requests pending in Raft seastar::smp group. For details, refer to the `seastar::smp_service_group` documentation). See [Seastar documentation](https://docs.seastar.io/master/) | Property | Value | | --- | --- | | Type | integer | | Maximum | 4294967295 | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#raft_timeout_now_timeout_ms)raft\_timeout\_now\_timeout\_ms Timeout for Raft’s timeout\_now RPC. This RPC is used to force a follower to dispatch a round of votes immediately. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 1000 (1 second) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#raft_transfer_leader_recovery_timeout_ms)raft\_transfer\_leader\_recovery\_timeout\_ms Follower recovery timeout waiting period when transferring leadership. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 10000 (10 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#readers_cache_eviction_timeout_ms)readers\_cache\_eviction\_timeout\_ms Duration after which inactive readers are evicted from cache. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 30000 (30 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#readers_cache_target_max_size)readers\_cache\_target\_max\_size Maximum desired number of readers cached per NTP. This a soft limit, meaning that a number of readers in cache may temporarily increase as cleanup is performed in the background. | Property | Value | | --- | --- | | Type | integer | | Default | 200 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#reclaim_batch_cache_min_free)reclaim\_batch\_cache\_min\_free Minimum amount of free memory maintained by the batch cache background reclaimer. | Property | Value | | --- | --- | | Type | integer | | Default | 67108864 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#reclaim_growth_window)reclaim\_growth\_window Starting from the last point in time when memory was reclaimed from the batch cache, this is the duration during which the amount of memory to reclaim grows at a significant rate, based on heuristics about the amount of available memory. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 3000 (3 seconds) | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#reclaim_max_size)reclaim\_max\_size Maximum batch cache reclaim size. | Property | Value | | --- | --- | | Type | integer | | Default | 4194304 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#reclaim_min_size)reclaim\_min\_size Minimum batch cache reclaim size. | Property | Value | | --- | --- | | Type | integer | | Default | 131072 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#reclaim_stable_window)reclaim\_stable\_window If the duration since the last time memory was reclaimed is longer than the amount of time specified in this property, the memory usage of the batch cache is considered stable, so only the minimum size ([`reclaim_min_size`](#reclaim_min_size)) is set to be reclaimed. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 10000 (10 seconds) | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#release_cache_on_segment_roll)release\_cache\_on\_segment\_roll Flag for specifying whether or not to release cache when a full segment is rolled. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#replicate_append_timeout_ms)replicate\_append\_timeout\_ms Timeout for append entry requests issued while replicating entries. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 3000 (3 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#retention_bytes)retention\_bytes Default maximum number of bytes per partition on disk before triggering deletion of the oldest messages. If `null` (the default value), no limit is applied. The topic property [`retention.bytes`](../topic-properties/#retentionbytes) overrides the value of `retention_bytes` at the topic level. | Property | Value | | --- | --- | | Type | integer | | Default | null | | Nullable | Yes | | Unit | Bytes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | retention.bytes | ### [](#retention_local_strict)retention\_local\_strict Flag to allow Tiered Storage topics to expand to consumable retention policy limits. When this flag is enabled, non-local retention settings are used, and local retention settings are used to inform data removal policies in low-disk space scenarios. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#retention_local_strict_override)retention\_local\_strict\_override Trim log data when a cloud topic reaches its local retention limit. When this option is disabled Redpanda will allow partitions to grow past the local retention limit, and will be trimmed automatically as storage reaches the configured target size. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#retention_local_target_bytes_default)retention\_local\_target\_bytes\_default Local retention size target for partitions of topics with object storage write enabled. If `null`, the property is disabled. This property can be overridden on a per-topic basis by setting `retention.local.target.bytes` in each topic enabled for Tiered Storage. See [Configure message retention](../../../manage/cluster-maintenance/disk-utilization/#configure-message-retention). > 📝 **NOTE** > > Both `retention_local_target_bytes_default` and `retention_local_target_ms_default` can be set. The limit that is reached earlier is applied. | Property | Value | | --- | --- | | Type | integer | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | Configure message retention | ### [](#retention_local_target_capacity_bytes)retention\_local\_target\_capacity\_bytes The target capacity (in bytes) that log storage will try to use before additional retention rules take over to trim data to meet the target. When no target is specified, storage usage is unbounded. > 📝 **NOTE** > > Redpanda Data recommends setting only one of [`retention_local_target_capacity_bytes`](#retention_local_target_capacity_bytes) or [`retention_local_target_capacity_percent`](#retention_local_target_capacity_percent). If both are set, the minimum of the two is used as the effective target capacity. | Property | Value | | --- | --- | | Type | integer | | Maximum | 18446744073709552000 | | Default | null | | Nullable | Yes | | Unit | Bytes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | 2147483648000 | ### [](#retention_local_target_capacity_percent)retention\_local\_target\_capacity\_percent The target capacity in percent of unreserved space ([`disk_reservation_percent`](#disk_reservation_percent)) that log storage will try to use before additional retention rules will take over to trim data in order to meet the target. When no target is specified storage usage is unbounded. > 📝 **NOTE** > > Redpanda Data recommends setting only one of [`retention_local_target_capacity_bytes`](#retention_local_target_capacity_bytes) or [`retention_local_target_capacity_percent`](#retention_local_target_capacity_percent). If both are set, the minimum of the two is used as the effective target capacity. | Property | Value | | --- | --- | | Type | number | | Default | 80 | | Nullable | Yes | | Unit | Percent | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | 80.0 | ### [](#retention_local_target_ms_default)retention\_local\_target\_ms\_default Local retention time target for partitions of topics with object storage write enabled. This property can be overridden on a per-topic basis by setting `retention.local.target.ms` in each topic enabled for Tiered Storage. See [Configure message retention](../../../manage/cluster-maintenance/disk-utilization/#configure-message-retention). > 📝 **NOTE** > > Both [`retention_local_target_bytes_default`](#retention_local_target_bytes_default) and [`retention_local_target_ms_default`](#retention_local_target_ms_default) can be set. The limit that is reached first is applied. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 86400000 (1 day) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | Configure message retention | ### [](#retention_local_trim_interval)retention\_local\_trim\_interval The period during which disk usage is checked for disk pressure, and data is optionally trimmed to meet the target. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 30000 (30 seconds) | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 31536000000 | ### [](#retention_local_trim_overage_coeff)retention\_local\_trim\_overage\_coeff The space management control loop reclaims the overage multiplied by this this coefficient to compensate for data that is written during the idle period between control loop invocations. | Property | Value | | --- | --- | | Type | number | | Default | 2 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 1.8 | ### [](#rpc_client_connections_per_peer)rpc\_client\_connections\_per\_peer The maximum number of connections a broker will open to each of its peers. | Property | Value | | --- | --- | | Type | integer | | Range | [-2147483648, 2147483647] | | Default | 128 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Example | 8 | ### [](#rpc_server_compress_replies)rpc\_server\_compress\_replies Enable compression for internal RPC (remote procedure call) server replies. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#rpc_server_listen_backlog)rpc\_server\_listen\_backlog Maximum TCP connection queue length for Kafka server and internal RPC server. If `null` (the default value), no queue length is set. **Unit**: number of queue entries | Property | Value | | --- | --- | | Type | integer | | Range | [-2147483648, 2147483647] | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#rpc_server_tcp_recv_buf)rpc\_server\_tcp\_recv\_buf Internal RPC TCP receive buffer size. If `null` (the default value), no buffer size is set by Redpanda. | Property | Value | | --- | --- | | Type | integer | | Range | [-2147483648, 2147483647] | | Default | null | | Nullable | Yes | | Unit | Bytes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Example | 65536 | ### [](#rpc_server_tcp_send_buf)rpc\_server\_tcp\_send\_buf Internal RPC TCP send buffer size. If `null` (the default value), then no buffer size is set by Redpanda. | Property | Value | | --- | --- | | Type | integer | | Range | [-2147483648, 2147483647] | | Default | null | | Nullable | Yes | | Unit | Bytes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Example | 65536 | ### [](#rpk_path)rpk\_path Path to RPK binary. | Property | Value | | --- | --- | | Type | string | | Default | /usr/bin/rpk | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#rps_limit_acls_and_users_operations)rps\_limit\_acls\_and\_users\_operations Rate limit, in requests per second, for ACL and user operations on the controller. The controller processes cluster management requests (such as creating, deleting, and updating ACLs and users) through the controller log (raft0). | Property | Value | | --- | --- | | Type | integer | | Default | 1000 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#rps_limit_configuration_operations)rps\_limit\_configuration\_operations Rate limit, in requests per second, for configuration operations on the controller. The controller processes cluster management requests (such as cluster configuration updates, feature activations, and data policy changes) through the controller log (raft0). | Property | Value | | --- | --- | | Type | integer | | Default | 1000 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#rps_limit_move_operations)rps\_limit\_move\_operations Rate limit, in requests per second, for move operations on the controller. The controller processes cluster management requests (such as moving and canceling partition replica reassignments) through the controller log (raft0). | Property | Value | | --- | --- | | Type | integer | | Default | 1000 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#rps_limit_node_management_operations)rps\_limit\_node\_management\_operations Rate limit, in requests per second, for node management operations on the controller. The controller processes cluster management requests (such as decommissioning, recommissioning, and setting brokers to maintenance mode) through the controller log (raft0). | Property | Value | | --- | --- | | Type | integer | | Default | 1000 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#rps_limit_topic_operations)rps\_limit\_topic\_operations Rate limit, in requests per second, for topic operations on the controller. The controller processes cluster management requests (such as creating, deleting, and updating topics and partition counts) through the controller log (raft0). | Property | Value | | --- | --- | | Type | integer | | Default | 1000 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#sampled_memory_profile)sampled\_memory\_profile When `true`, memory allocations are sampled and tracked. A sampled live set of allocations can then be retrieved from the Admin API. Additionally, Redpanda will periodically log the top-n allocation sites. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#sasl_kerberos_config)sasl\_kerberos\_config The location of the Kerberos `krb5.conf` file for Redpanda. | Property | Value | | --- | --- | | Type | string | | Default | /etc/krb5.conf | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#sasl_kerberos_keytab)sasl\_kerberos\_keytab The location of the Kerberos keytab file for Redpanda. | Property | Value | | --- | --- | | Type | string | | Default | /var/lib/redpanda/redpanda.keytab | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#sasl_kerberos_principal)sasl\_kerberos\_principal The primary of the Kerberos Service Principal Name (SPN) for Redpanda. | Property | Value | | --- | --- | | Type | string | | Default | redpanda | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#sasl_kerberos_principal_mapping)sasl\_kerberos\_principal\_mapping Rules for mapping Kerberos principal names to Redpanda user principals. | Property | Value | | --- | --- | | Type | array | | Default | [DEFAULT] | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#sasl_mechanisms)sasl\_mechanisms A list of supported SASL mechanisms. Accepted values: `SCRAM`, `GSSAPI`, `OAUTHBEARER`, `PLAIN`. Note that in order to enable PLAIN, you must also enable SCRAM. > 📝 **NOTE: Enterprise license required** > > Enterprise license required > > This property requires an Enterprise license to use. > > For license details, see [Redpanda Licensing](../../../get-started/licensing/). | Property | Value | | --- | --- | | Type | array (enum) | | Accepted values | GSSAPI (Enterprise), SCRAM, OAUTHBEARER (Enterprise), PLAIN | | Default | SCRAM | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#sasl_mechanisms_overrides)sasl\_mechanisms\_overrides Configure different SASL authentication mechanisms for specific listeners. This overrides the cluster-wide [`sasl_mechanisms`](#sasl_mechanisms) setting for the specified listener. Use this when you need different authentication methods on different listeners, such as SCRAM for internal traffic and OAUTHBEARER for external clients. The same requirements from `sasl_mechanisms` apply. > 📝 **NOTE: Enterprise license required** > > Enterprise license required > > This property requires an Enterprise license to use. > > For license details, see [Redpanda Licensing](../../../get-started/licensing/). | Property | Value | | --- | --- | | Type | array | | Default | [] | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | [{'listener':'kafka_listener', 'sasl_mechanisms':['SCRAM']}] | ### [](#schema_registry_always_normalize)schema\_registry\_always\_normalize Always normalize schemas. If set, this overrides the `normalize` parameter in requests to the Schema Registry API. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Aliases | schema_registry_normalize_on_startup | ### [](#schema_registry_enable_authorization)schema\_registry\_enable\_authorization Enables ACL-based authorization for Schema Registry requests. When `true`, Schema Registry uses ACL-based authorization instead of the default `public/user/superuser` authorization model. > 📝 **NOTE: Enterprise license required** > > Enterprise license required > > The following values require an Enterprise license: `true` > > For license details, see [Redpanda Licensing](../../../get-started/licensing/). | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#schema_registry_enable_qualified_subjects)schema\_registry\_enable\_qualified\_subjects **Introduced in v26.1.1** Enable parsing of qualified subject syntax (:.context:subject). When false, subjects are treated literally, as subjects in the default context. When true, qualified syntax is parsed to extract context and subject. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#segment_appender_flush_timeout_ms)segment\_appender\_flush\_timeout\_ms Maximum delay until buffered data is written. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 1 second | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#segment_fallocation_step)segment\_fallocation\_step Size for segments fallocation. | Property | Value | | --- | --- | | Type | integer | | Default | 33554432 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 32768 | ### [](#space_management_enable)space\_management\_enable Option to explicitly disable automatic disk space management. If this property was explicitly disabled while using v23.2, it will remain disabled following an upgrade. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#space_management_enable_override)space\_management\_enable\_override Enable automatic space management. This option is ignored and deprecated in versions >= v23.3. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#space_management_max_log_concurrency)space\_management\_max\_log\_concurrency Maximum parallel logs inspected during space management process. | Property | Value | | --- | --- | | Type | integer | | Maximum | 65535 | | Default | 20 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 20 | ### [](#space_management_max_segment_concurrency)space\_management\_max\_segment\_concurrency Maximum parallel segments inspected during space management process. | Property | Value | | --- | --- | | Type | integer | | Maximum | 65535 | | Default | 10 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 10 | ### [](#storage_compaction_index_memory)storage\_compaction\_index\_memory Maximum number of bytes that may be used on each shard by compaction index writers. | Property | Value | | --- | --- | | Type | integer | | Maximum | 18446744073709552000 | | Default | 134217728 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 1073741824 | ### [](#storage_compaction_key_map_memory)storage\_compaction\_key\_map\_memory Maximum number of bytes that may be used on each shard by compaction key-offset maps. Only applies when [`log_compaction_use_sliding_window`](#log_compaction_use_sliding_window) is set to `true`. | Property | Value | | --- | --- | | Type | integer | | Maximum | 18446744073709552000 | | Default | 134217728 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 1073741824 | ### [](#storage_compaction_key_map_memory_limit_percent)storage\_compaction\_key\_map\_memory\_limit\_percent Limit on [`storage_compaction_key_map_memory`](#storage_compaction_key_map_memory), expressed as a percentage of memory per shard, that bounds the amount of memory used by compaction key-offset maps. > 📝 **NOTE** > > Memory per shard is computed after [`data_transforms_per_core_memory_reservation`](#data_transforms_per_core_memory_reservation), and only applies when [`log_compaction_use_sliding_window`](#log_compaction_use_sliding_window) is set to `true`. | Property | Value | | --- | --- | | Type | number | | Default | 12 | | Nullable | No | | Unit | Percent | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 12.0 | ### [](#storage_ignore_cstore_hints)storage\_ignore\_cstore\_hints When set, cstore hints are ignored and not used for data access (but are otherwise generated). | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#storage_ignore_timestamps_in_future_sec)storage\_ignore\_timestamps\_in\_future\_sec The maximum number of seconds that a record’s timestamp can be ahead of a Redpanda broker’s clock and still be used when deciding whether to clean up the record for data retention. This property makes possible the timely cleanup of records from clients with clocks that are drastically unsynchronized relative to Redpanda. When determining whether to clean up a record with timestamp more than `storage_ignore_timestamps_in_future_sec` seconds ahead of the broker, Redpanda ignores the record’s timestamp and instead uses a valid timestamp of another record in the same segment, or (if another record’s valid timestamp is unavailable) the timestamp of when the segment file was last modified (mtime). By default, `storage_ignore_timestamps_in_future_sec` is disabled (null). > 💡 **TIP** > > To figure out whether to set `storage_ignore_timestamps_in_future_sec` for your system: > > 1. Look for logs with segments that are unexpectedly large and not being cleaned up. > > 2. In the logs, search for records with unsynchronized timestamps that are further into the future than tolerable by your data retention and storage settings. For example, timestamps 60 seconds or more into the future can be considered to be too unsynchronized. > > 3. If you find unsynchronized timestamps throughout your logs, determine the number of seconds that the timestamps are ahead of their actual time, and set `storage_ignore_timestamps_in_future_sec` to that value so data retention can proceed. > > 4. If you only find unsynchronized timestamps that are the result of transient behavior, you can disable `storage_ignore_timestamps_in_future_sec`. | Property | Value | | --- | --- | | Type | integer | | Range | [-17179869184, 17179869183] | | Default | null | | Nullable | Yes | | Unit | Seconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 3600 | ### [](#storage_max_concurrent_replay)storage\_max\_concurrent\_replay Maximum number of partitions' logs that will be replayed concurrently at startup, or flushed concurrently on shutdown. | Property | Value | | --- | --- | | Type | integer | | Maximum | 18446744073709552000 | | Default | 1024 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 2048 | ### [](#storage_min_free_bytes)storage\_min\_free\_bytes Threshold of minimum bytes free space before rejecting producers. | Property | Value | | --- | --- | | Type | integer | | Default | 5368709120 | | Nullable | No | | Unit | Bytes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#storage_read_buffer_size)storage\_read\_buffer\_size Size of each read buffer (one per in-flight read, per log segment). | Property | Value | | --- | --- | | Type | integer | | Default | 131072 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 31768 | ### [](#storage_read_readahead_count)storage\_read\_readahead\_count How many additional reads to issue ahead of current read location. | Property | Value | | --- | --- | | Type | integer | | Range | [-32768, 32767] | | Default | 1 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 1 | ### [](#storage_reserve_min_segments)storage\_reserve\_min\_segments The number of segments per partition that the system will attempt to reserve disk capacity for. For example, if the maximum segment size is configured to be 100 MB, and the value of this option is 2, then in a system with 10 partitions Redpanda will attempt to reserve at least 2 GB of disk space. | Property | Value | | --- | --- | | Type | integer | | Range | [-32768, 32767] | | Default | 2 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 4 | ### [](#storage_space_alert_free_threshold_bytes)storage\_space\_alert\_free\_threshold\_bytes Threshold of minimum bytes free space before setting storage space alert. | Property | Value | | --- | --- | | Type | integer | | Default | 0 | | Nullable | No | | Unit | Bytes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#storage_space_alert_free_threshold_percent)storage\_space\_alert\_free\_threshold\_percent Threshold of minimum percent free space before setting storage space alert. | Property | Value | | --- | --- | | Type | integer | | Maximum | 4294967295 | | Default | 5 | | Nullable | No | | Unit | Percent | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#storage_strict_data_init)storage\_strict\_data\_init Requires that an empty file named `.redpanda_data_dir` be present in the [`data_ directory`](../broker-properties/#data_directory). If set to `true`, Redpanda will refuse to start if the file is not found in the data directory. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | data_ directory | ### [](#storage_target_replay_bytes)storage\_target\_replay\_bytes Target bytes to replay from disk on startup after clean shutdown: controls frequency of snapshots and checkpoints. | Property | Value | | --- | --- | | Type | integer | | Maximum | 18446744073709552000 | | Default | 10737418240 | | Nullable | No | | Unit | Bytes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 2147483648 | ### [](#superusers)superusers List of superuser usernames. | Property | Value | | --- | --- | | Type | array | | Default | [] | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#tls_certificate_name_format)tls\_certificate\_name\_format The format of the certificates’s distinguished name to use for mTLS principal mapping. The `legacy` format would appear as 'C=US,ST=California,L=San Francisco,O=Redpanda,CN=redpanda', while the `rfc2253` format would appear as 'CN=redpanda,O=Redpanda,L=San Francisco,ST=California,C=US'. | Property | Value | | --- | --- | | Type | string (enum) | | Accepted values | legacy, rfc2253 | | Default | legacy | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#tls_enable_renegotiation)tls\_enable\_renegotiation TLS client-initiated renegotiation is considered unsafe and is disabled by default . Only re-enable it if you are experiencing issues with your TLS-enabled client. This option has no effect on TLSv1.3 connections as client-initiated renegotiation was removed. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#tls_min_version)tls\_min\_version The minimum TLS version that Redpanda clusters support. This property prevents client applications from negotiating a downgrade to the TLS version when they make a connection to a Redpanda cluster. | Property | Value | | --- | --- | | Type | string (enum) | | Accepted values | v1.0, v1.1, v1.2, v1.3 | | Default | v1.2 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#tls_v1_2_cipher_suites)tls\_v1\_2\_cipher\_suites The encryption algorithms available for TLS 1.2 client connections, specified as a colon-separated list in OpenSSL format. Use this to support older clients that require specific encryption methods. | Property | Value | | --- | --- | | Type | string | | Default | TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256:TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256:TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384:TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384:TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256:TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#tls_v1_3_cipher_suites)tls\_v1\_3\_cipher\_suites The encryption algorithms available for TLS 1.3 client connections, specified as a colon-separated list in OpenSSL format. Most deployments don’t need to change this. Only modify it to meet specific organizational security requirements. | Property | Value | | --- | --- | | Type | string | | Default | TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_CCM_SHA256 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#tombstone_retention_ms)tombstone\_retention\_ms The retention time for tombstone records in a compacted topic. Cannot be enabled at the same time as any of `cloud_storage_enabled`, `cloud_storage_enable_remote_read`, or `cloud_storage_enable_remote_write`. A typical default setting is `86400000`, or 24 hours. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | null | | Nullable | Yes | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | Tombstone record removal | ### [](#topic_fds_per_partition)topic\_fds\_per\_partition File descriptors required per partition replica. If topic creation results in the ratio of file descriptor limit to partition replicas being lower than this value, creation of new topics is fails. | Property | Value | | --- | --- | | Type | integer | | Range | [-2147483648, 2147483647] | | Default | 5 | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#topic_label_aggregation_limit)topic\_label\_aggregation\_limit When the number of topics exceeds this limit, the topic label in generated metrics will be aggregated. If `null`, then there is no limit. | Property | Value | | --- | --- | | Type | integer | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#topic_memory_per_partition)topic\_memory\_per\_partition Required memory in bytes per partition replica when creating or altering topics. The total size of the memory pool for partitions is the total memory available to Redpanda times `topic_partitions_memory_allocation_percent`. Each partition created requires `topic_memory_per_partition` bytes from that pool. If insufficient memory is available, creating or altering topics fails. | Property | Value | | --- | --- | | Type | integer | | Default | DEFAULT_TOPIC_MEMORY_PER_PARTITION | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#topic_partitions_memory_allocation_percent)topic\_partitions\_memory\_allocation\_percent Percentage of total memory to reserve for topic partitions. See [`topic_memory_per_partition`](#topic_memory_per_partition) for details. | Property | Value | | --- | --- | | Type | integer | | Maximum | 4294967295 | | Default | 10 | | Nullable | No | | Unit | Percent | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#topic_partitions_per_shard)topic\_partitions\_per\_shard Maximum number of partition replicas per shard. If topic creation results in the ratio of partition replicas to shards being higher than this value, creation of new topics fails. | Property | Value | | --- | --- | | Type | integer | | Maximum | 4294967295 | | Default | 5000 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#topic_partitions_reserve_shard0)topic\_partitions\_reserve\_shard0 Reserved partition slots on shard (CPU core) 0 on each node. If this is greater than or equal to [`topic_partitions_per_core`](#topic_partitions_per_core), no data partitions will be scheduled on shard 0. | Property | Value | | --- | --- | | Type | integer | | Maximum | 4294967295 | | Default | 0 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#transaction_coordinator_cleanup_policy)transaction\_coordinator\_cleanup\_policy Cleanup policy for a transaction coordinator topic. **Accepted values:** - `compact` - `delete` - `["compact","delete"]` - `none` | Property | Value | | --- | --- | | Type | string (enum) | | Accepted values | none, delete, compact | | Default | delete | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | compact,delete | ### [](#transaction_coordinator_delete_retention_ms)transaction\_coordinator\_delete\_retention\_ms Delete segments older than this age. To ensure transaction state is retained for as long as the longest-running transaction, make sure this is greater than or equal to [`transactional_id_expiration_ms`](#transactional_id_expiration_ms). For example, if your typical transactions run for one hour, consider setting both `transaction_coordinator_delete_retention_ms` and `transactional_id_expiration_ms` to at least 3600000 (one hour), or a little over. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 604800000 (1 week) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#transaction_coordinator_log_segment_size)transaction\_coordinator\_log\_segment\_size The size (in bytes) each log segment should be. | Property | Value | | --- | --- | | Type | integer | | Maximum | 18446744073709552000 | | Default | 1073741824 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#transaction_coordinator_partitions)transaction\_coordinator\_partitions Number of partitions for transactions coordinator. | Property | Value | | --- | --- | | Type | integer | | Range | [-2147483648, 2147483647] | | Default | 50 | | Nullable | No | | Unit | Number of partitions per topic | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#transaction_max_timeout_ms)transaction\_max\_timeout\_ms The maximum allowed timeout for transactions. If a client-requested transaction timeout exceeds this configuration, the broker returns an error during transactional producer initialization. This guardrail prevents hanging transactions from blocking consumer progress. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 900000 (15 minutes) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#transactional_id_expiration_ms)transactional\_id\_expiration\_ms Expiration time of producer IDs for both transactional and idempotent producers. Despite the name, this setting applies to all producer types. Measured starting from the time of the last write until now for a given ID. Producer IDs are automatically removed from memory when they expire, which helps manage memory usage. However, this natural cleanup may not be sufficient for workloads with high producer churn rates. Tune this value based on your application’s producer session and transaction lifetimes. Consider your longest-running transaction duration plus a buffer to avoid premature expiration. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 604800000 (1 week) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | Tune producer ID limitsmax_concurrent_producer_ids | ### [](#tx_timeout_delay_ms)tx\_timeout\_delay\_ms Delay before scheduling the next check for timed out transactions. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 1000 (1 second) | | Nullable | No | | Unit | Milliseconds | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#unsafe_enable_consumer_offsets_delete_retention)unsafe\_enable\_consumer\_offsets\_delete\_retention Enables delete retention of consumer offsets topic. This is an internal-only configuration and should be enabled only after consulting with Redpanda support. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#usage_disk_persistance_interval_sec)usage\_disk\_persistance\_interval\_sec The interval in which all usage stats are written to disk. | Property | Value | | --- | --- | | Type | integer | | Range | [-17179869184, 17179869183] | | Default | 300 seconds | | Nullable | No | | Unit | Seconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 300 | ### [](#usage_num_windows)usage\_num\_windows The number of windows to persist in memory and disk. | Property | Value | | --- | --- | | Type | integer | | Default | 24 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 24 | ### [](#usage_window_width_interval_sec)usage\_window\_width\_interval\_sec The width of a usage window, tracking cloud and kafka ingress/egress traffic each interval. | Property | Value | | --- | --- | | Type | integer | | Range | [-17179869184, 17179869183] | | Default | 3600 seconds | | Nullable | No | | Unit | Seconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | 3600 | ### [](#use_fetch_scheduler_group)use\_fetch\_scheduler\_group Use a separate scheduler group for fetch processing. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#use_kafka_handler_scheduler_group)use\_kafka\_handler\_scheduler\_group Use a separate scheduler group to handle parsing Kafka protocol requests. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#use_produce_scheduler_group)use\_produce\_scheduler\_group Use a separate scheduler group to process Kafka produce requests. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#virtual_cluster_min_producer_ids)virtual\_cluster\_min\_producer\_ids Minimum number of active producers per virtual cluster. | Property | Value | | --- | --- | | Type | integer | | Maximum | 18446744073709552000 | | Default | Maximum value | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#write_caching_default)write\_caching\_default The default write caching mode to apply to user topics. Write caching acknowledges a message as soon as it is received and acknowledged on a majority of brokers, without waiting for it to be written to disk. With `acks=all`, this provides lower latency while still ensuring that a majority of brokers acknowledge the write. Fsyncs follow [`raft_replica_max_pending_flush_bytes`](#raft_replica_max_pending_flush_bytes) and [`raft_replica_max_flush_delay_ms`](#raft_replica_max_flush_delay_ms), whichever is reached first. The `write_caching_default` cluster property can be overridden with the [`write.caching`](../topic-properties/#writecaching) topic property. | Property | Value | | --- | --- | | Type | string (enum) | | Accepted values | true, false, disabled | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | true | | Related topics | write.cachingWrite caching | ### [](#zstd_decompress_workspace_bytes)zstd\_decompress\_workspace\_bytes Size of the zstd decompression workspace. | Property | Value | | --- | --- | | Type | integer | | Default | 8388608 | | Nullable | No | | Unit | Bytes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | --- # Page 265: Object Storage Properties **URL**: https://docs.redpanda.com/current/reference/properties/object-storage-properties.md --- # Object Storage Properties --- title: Object Storage Properties latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: properties/object-storage-properties page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: properties/object-storage-properties.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/properties/object-storage-properties.adoc description: Reference of object storage properties. page-git-created-date: "2024-05-23" page-git-modified-date: "2025-11-25" support-status: supported --- Object storage properties are a type of cluster property. Cluster properties are configuration settings that control the behavior of a Redpanda cluster at a global level. Configuring cluster properties allows you to adapt Redpanda to specific workloads, optimize resource usage, and enable or disable features. For information on how to edit cluster properties, see [Configure Cluster Properties](../../../manage/cluster-maintenance/cluster-property-configuration/). > 📝 **NOTE** > > Some object storage properties require that you restart the cluster for any updates to take effect. See the specific property details to identify whether or not a restart is required. ## [](#cluster-configuration)Cluster configuration Object storage properties should only be set if you enable [Tiered Storage](../../../manage/tiered-storage/). ### [](#cloud_storage_access_key)cloud\_storage\_access\_key AWS or GCP access key. This access key is part of the credentials that Redpanda requires to authenticate with object storage services for Tiered Storage. This access key is used with the [`cloud_storage_secret_key`](#cloud_storage_secret_key) to form the complete credentials required for authentication. To authenticate using IAM roles, see [`cloud_storage_credentials_source`](#cloud_storage_credentials_source). | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | No | | Visibility | User | ### [](#cloud_storage_api_endpoint)cloud\_storage\_api\_endpoint Optional API endpoint. The only instance in which you must set this value is when using a custom domain with your object storage service. - AWS: If not set, this is automatically generated using [region](#cloud_storage_region) and [bucket](#cloud_storage_bucket). Otherwise, this uses the value assigned. - GCP: If not set, this is automatically generated using `storage.googleapis.com` and [bucket](#cloud_storage_bucket). - Azure: If not set, this is automatically generated using `blob.core.windows.net` and [`cloud_storage_azure_storage_account`](#cloud_storage_azure_storage_account). If you have enabled hierarchical namespaces for your storage account and use a custom endpoint, use [`cloud_storage_azure_adls_endpoint`](#cloud_storage_azure_adls_endpoint). | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | No | | Visibility | User | ### [](#cloud_storage_api_endpoint_port)cloud\_storage\_api\_endpoint\_port TLS port override. | Property | Value | | --- | --- | | Type | integer | | Range | [-32768, 32767] | | Default | 443 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#cloud_storage_attempt_cluster_restore_on_bootstrap)cloud\_storage\_attempt\_cluster\_restore\_on\_bootstrap When set to `true`, Redpanda automatically retrieves cluster metadata from a specified object storage bucket at the cluster’s first startup. This option is ideal for orchestrated deployments, such as Kubernetes. Ensure any previous cluster linked to the bucket is fully decommissioned to prevent conflicts between Tiered Storage subsystems. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_azure_adls_endpoint)cloud\_storage\_azure\_adls\_endpoint Azure Data Lake Storage v2 endpoint override. Use when hierarchical namespaces are enabled on your storage account and you have set up a custom endpoint. If not set, this is automatically generated using `dfs.core.windows.net` and [`cloud_storage_azure_storage_account`](#cloud_storage_azure_storage_account). | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | No | | Visibility | User | ### [](#cloud_storage_azure_adls_port)cloud\_storage\_azure\_adls\_port Azure Data Lake Storage v2 port override. See also: [`cloud_storage_azure_adls_endpoint`](#cloud_storage_azure_adls_endpoint). Use when hierarchical namespaces are enabled on your storage account and you have set up a custom endpoint. | Property | Value | | --- | --- | | Type | integer | | Maximum | 65535 | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | No | | Visibility | User | ### [](#cloud_storage_azure_container)cloud\_storage\_azure\_container The name of the Azure container to use with Tiered Storage. If `null`, the property is disabled. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | No | | Visibility | User | ### [](#cloud_storage_azure_hierarchical_namespace_enabled)cloud\_storage\_azure\_hierarchical\_namespace\_enabled Force Redpanda to use or not use an Azure Data Lake Storage (ADLS) Gen2 hierarchical namespace-compliant client in [`cloud_storage_azure_storage_account`](#cloud_storage_azure_storage_account). When this property is not set, [`cloud_storage_azure_shared_key`](#cloud_storage_azure_shared_key) must be set, and each broker checks at startup if a hierarchical namespace is enabled. When set to `true`, this property disables the check and assumes a hierarchical namespace is enabled. When set to `false`, this property disables the check and assumes a hierarchical namespace is not enabled. This setting should be used only in emergencies where Redpanda fails to detect the correct a hierarchical namespace status. | Property | Value | | --- | --- | | Type | boolean | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_azure_managed_identity_id)cloud\_storage\_azure\_managed\_identity\_id The managed identity ID to use for access to the Azure storage account. To use Azure managed identities, you must set [`cloud_storage_credentials_source`](#cloud_storage_credentials_source) to `azure_vm_instance_metadata`. See [IAM Roles](../../../manage/security/iam-roles/) for more information on managed identities. **Type**: string **Default**: null **Requires restart**: No **Supported versions**: Redpanda v24.1 or later * * * | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Related topics | IAM Roles | ### [](#cloud_storage_azure_shared_key)cloud\_storage\_azure\_shared\_key The account access key to be used for Azure Shared Key authentication with the Azure storage account configured by [`cloud_storage_azure_storage_account`](#cloud_storage_azure_storage_account). If `null`, the property is disabled. > 📝 **NOTE** > > Redpanda expects this key string to be Base64 encoded. **Requires restart**: Yes | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | No | | Visibility | User | ### [](#cloud_storage_azure_storage_account)cloud\_storage\_azure\_storage\_account The name of the Azure storage account to use with Tiered Storage. If `null`, the property is disabled. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | No | | Visibility | User | ### [](#cloud_storage_backend)cloud\_storage\_backend Optional object storage backend variant used to select API capabilities. If not supplied, this will be inferred from other configuration properties. | Property | Value | | --- | --- | | Type | string (enum) | | Accepted values | aws, google_s3_compat, azure, minio, oracle_s3_compat, linode_s3_compat, unknown | | Default | unknown | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | No | | Visibility | User | | Example | aws | ### [](#cloud_storage_background_jobs_quota)cloud\_storage\_background\_jobs\_quota The total number of requests the object storage background jobs can make during one background housekeeping run. This is a per-shard limit. Adjusting this limit can optimize object storage traffic and impact shard performance. | Property | Value | | --- | --- | | Type | integer | | Range | [-2147483648, 2147483647] | | Default | 5000 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_bucket)cloud\_storage\_bucket AWS or GCP bucket that should be used to store data. > ⚠️ **WARNING** > > Modifying this property after writing data to a bucket could cause data loss. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | No | | Visibility | User | ### [](#cloud_storage_cache_check_interval_ms)cloud\_storage\_cache\_check\_interval\_ms Minimum interval between Tiered Storage cache trims, measured in milliseconds. This setting dictates the cooldown period after a cache trim operation before another trim can occur. If a cache fetch operation requests a trim but the interval since the last trim has not yet passed, the trim will be postponed until this cooldown expires. Adjusting this interval helps manage the balance between cache size and retrieval performance. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 5000 (5 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_cache_chunk_size)cloud\_storage\_cache\_chunk\_size Size of chunks of segments downloaded into object storage cache. Reduces space usage by only downloading the necessary chunk from a segment. | Property | Value | | --- | --- | | Type | integer | | Maximum | 18446744073709552000 | | Default | 16777216 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_cache_max_objects)cloud\_storage\_cache\_max\_objects Maximum number of objects that may be held in the Tiered Storage cache. This applies simultaneously with [`cloud_storage_cache_size`](#cloud_storage_cache_size), and whichever limit is hit first will trigger trimming of the cache. | Property | Value | | --- | --- | | Type | integer | | Maximum | 4294967295 | | Default | 100000 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_cache_num_buckets)cloud\_storage\_cache\_num\_buckets Divide the object storage cache across the specified number of buckets. This only works for objects with randomized prefixes. The names are not changed when the value is set to zero. | Property | Value | | --- | --- | | Type | integer | | Maximum | 4294967295 | | Default | 0 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_cache_size)cloud\_storage\_cache\_size Maximum size of the object storage cache, in bytes. This property works together with [`cloud_storage_cache_size_percent`](#cloud_storage_cache_size_percent) to define cache behavior: - When both properties are set, Redpanda uses the smaller calculated value of the two, in bytes. - If one of these properties is set to `0`, Redpanda uses the non-zero value. - These properties cannot both be `0`. - `cloud_storage_cache_size` cannot be `0` while `cloud_storage_cache_size_percent` is `null`. | Property | Value | | --- | --- | | Type | integer | | Maximum | 18446744073709552000 | | Default | 0 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | No | | Visibility | User | ### [](#cloud_storage_cache_size_percent)cloud\_storage\_cache\_size\_percent Maximum size of the cache as a percentage, minus the space that Redpanda avoids using defined by the [`disk_reservation_percent`](../cluster-properties/#disk_reservation_percent) cluster property. This is calculated at startup and dynamically updated if either this property, `disk_reservation_percent`, or [`cloud_storage_cache_size`](#cloud_storage_cache_size) changes. This property works together with [`cloud_storage_cache_size`](#cloud_storage_cache_size) to define cache behavior: - When both properties are set, Redpanda uses the smaller calculated value of the two, in bytes. - If one of these properties is set to `0`, Redpanda uses the non-zero value. - These properties cannot both be `0`. - `cloud_storage_cache_size` cannot be `0` while `cloud_storage_cache_size_percent` is `null`. | Property | Value | | --- | --- | | Type | number | | Default | 20 | | Nullable | Yes | | Unit | Percent | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | 20.0 | | Related topics | disk_reservation_percent | ### [](#cloud_storage_cache_trim_threshold_percent_objects)cloud\_storage\_cache\_trim\_threshold\_percent\_objects **Introduced in 24.1.10** Cache trimming is triggered when the number of objects in the cache reaches this percentage relative to its maximum object count. If unset, the default behavior is to start trimming when the cache is full. | Property | Value | | --- | --- | | Type | number | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_cache_trim_threshold_percent_size)cloud\_storage\_cache\_trim\_threshold\_percent\_size **Introduced in 24.1.10** Cache trimming is triggered when the cache size reaches this percentage relative to its maximum capacity. If unset, the default behavior is to start trimming when the cache is full. | Property | Value | | --- | --- | | Type | number | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_cache_trim_walk_concurrency)cloud\_storage\_cache\_trim\_walk\_concurrency The maximum number of concurrent tasks launched for traversing the directory structure during cache trimming. A higher number allows cache trimming to run faster but can cause latency spikes due to increased pressure on I/O subsystem and syscall threads. | Property | Value | | --- | --- | | Type | integer | | Maximum | 65535 | | Default | 1 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_chunk_eviction_strategy)cloud\_storage\_chunk\_eviction\_strategy Selects a strategy for evicting unused cache chunks. | Property | Value | | --- | --- | | Type | string (enum) | | Accepted values | eager, capped, predictive | | Default | eager | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | eager | ### [](#cloud_storage_chunk_prefetch)cloud\_storage\_chunk\_prefetch Number of chunks to prefetch ahead of every downloaded chunk. Prefetching additional chunks can enhance read performance by reducing wait times for sequential data access. A value of `0` disables prefetching, relying solely on on-demand downloads. Adjusting this property allows for tuning the balance between improved read performance and increased network and storage I/O. | Property | Value | | --- | --- | | Type | integer | | Maximum | 65535 | | Default | 0 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_client_lease_timeout_ms)cloud\_storage\_client\_lease\_timeout\_ms The maximum time Redpanda holds a connection to object storage before closing it. After this timeout, any active connection is immediately closed and must be re-established for subsequent operations. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 900000 (15 minutes) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_cluster_metadata_num_consumer_groups_per_upload)cloud\_storage\_cluster\_metadata\_num\_consumer\_groups\_per\_upload Number of groups to upload in a single snapshot object during consumer offsets upload. Setting a lower value will mean a larger number of smaller snapshots are uploaded. | Property | Value | | --- | --- | | Type | integer | | Default | 1000 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_cluster_metadata_retries)cloud\_storage\_cluster\_metadata\_retries Number of attempts metadata operations may be retried. | Property | Value | | --- | --- | | Type | integer | | Range | [-32768, 32767] | | Default | 5 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_cluster_metadata_upload_interval_ms)cloud\_storage\_cluster\_metadata\_upload\_interval\_ms Time interval to wait between cluster metadata uploads. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 3600000 (1 hour) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_cluster_metadata_upload_timeout_ms)cloud\_storage\_cluster\_metadata\_upload\_timeout\_ms Timeout for cluster metadata uploads. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 60000 (1 minute) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_cluster_name)cloud\_storage\_cluster\_name A unique name for this cluster’s metadata in object storage. Use this when multiple clusters share the same storage bucket (for example, for [Whole Cluster Restore](../../../manage/disaster-recovery/whole-cluster-restore/)). The name must be unique within the bucket, 1-64 characters, and use only letters, numbers, underscores, and hyphens. Don’t change this value once set. This is an internal-only configuration and should be enabled only after consulting with Redpanda support. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | No | | Visibility | User | | Related topics | Whole Cluster Restore | ### [](#cloud_storage_credentials_host)cloud\_storage\_credentials\_host The hostname to connect to for retrieving role based credentials. Derived from [`cloud_storage_credentials_source`](#cloud_storage_credentials_source) if not set. Only required when using IAM role based access. To authenticate using access keys, see [`cloud_storage_access_key`](#cloud_storage_access_key). | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | No | | Visibility | Tunable | ### [](#cloud_storage_credentials_source)cloud\_storage\_credentials\_source The source of credentials used to authenticate to object storage services. Required for AWS or GCP authentication with IAM roles. To authenticate using access keys, see [`cloud_storage_access_key`](#cloud_storage_access_key). | Property | Value | | --- | --- | | Type | string (enum) | | Accepted values | config_file, aws_instance_metadata, sts, gcp_instance_metadata, azure_aks_oidc_federation, azure_vm_instance_metadata | | Default | config_file | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | No | | Visibility | User | | Example | config_file | ### [](#cloud_storage_crl_file)cloud\_storage\_crl\_file Path to certificate revocation list for [`cloud_storage_trust_file`](#cloud_storage_trust_file). | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#cloud_storage_disable_archival_stm_rw_fence)cloud\_storage\_disable\_archival\_stm\_rw\_fence Disables the concurrency control mechanism in Tiered Storage. This safety feature keeps data organized and correct when multiple processes access it simultaneously. Disabling it can cause data consistency problems, so use this setting only for testing, never in production systems. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_disable_archiver_manager)cloud\_storage\_disable\_archiver\_manager Use legacy upload mode and do not start archiver\_manager. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#cloud_storage_disable_chunk_reads)cloud\_storage\_disable\_chunk\_reads Disable chunk reads and switch back to legacy mode where full segments are downloaded. When set to `true`, this option disables the more efficient chunk-based reads, causing Redpanda to download entire segments. This legacy behavior might be useful in specific scenarios where chunk-based fetching is not optimal. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_disable_read_replica_loop_for_tests)cloud\_storage\_disable\_read\_replica\_loop\_for\_tests Begins the read replica sync loop in topic partitions with Tiered Storage enabled. The property exists to simplify testing and shouldn’t be set in production. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_disable_remote_labels_for_tests)cloud\_storage\_disable\_remote\_labels\_for\_tests If `true`, Redpanda disables remote labels and falls back on the hash-based object naming scheme for new topics. > ⚠️ **CAUTION** > > This property exists to simplify testing and shouldn’t be set in production. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_disable_tls)cloud\_storage\_disable\_tls Disable TLS for all object storage connections. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#cloud_storage_disable_upload_consistency_checks)cloud\_storage\_disable\_upload\_consistency\_checks Disable all upload consistency checks to allow Redpanda to upload logs with gaps and replicate metadata with consistency violations. Do not change the default value unless requested by Redpanda Support. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_disable_upload_loop_for_tests)cloud\_storage\_disable\_upload\_loop\_for\_tests Begins the upload loop in topic partitions with Tiered Storage enabled. The property exists to simplify testing and shouldn’t be set in production. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_enable_compacted_topic_reupload)cloud\_storage\_enable\_compacted\_topic\_reupload Enable re-uploading data for compacted topics. When set to `true`, Redpanda can re-upload data for compacted topics to object storage, ensuring that the most current state of compacted topics is available in the cloud. Disabling this property (`false`) may reduce storage and network overhead but at the risk of not having the latest compacted data state in object storage. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_enable_remote_allow_gaps)cloud\_storage\_enable\_remote\_allow\_gaps Controls the eviction of locally stored log segments when Tiered Storage uploads are paused. Set to `false` to only evict data that has already been uploaded to object storage. If the retained data fills the local volume, Redpanda throttles producers. Set to `true` to allow the eviction of locally stored log segments, which may create gaps in offsets. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_enable_remote_read)cloud\_storage\_enable\_remote\_read Default remote read config value for new topics. When set to `true`, new topics are by default configured to allow reading data directly from object storage, facilitating access to older data that might have been offloaded as part of Tiered Storage. With the default set to `false`, remote reads must be explicitly enabled at the topic level. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_enable_remote_write)cloud\_storage\_enable\_remote\_write Default remote write value for new topics. When set to `true`, new topics are by default configured to upload data to object storage. With the default set to `false`, remote write must be explicitly enabled at the topic level. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_enable_scrubbing)cloud\_storage\_enable\_scrubbing Enable routine checks (scrubbing) of object storage partitions. The scrubber validates the integrity of data and metadata uploaded to object storage. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_enable_segment_merging)cloud\_storage\_enable\_segment\_merging Enables adjacent segment merging. The segments are reuploaded if there is an opportunity for that and if it will improve the tiered-storage performance | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Related topics | Object storage housekeeping | ### [](#cloud_storage_enable_segment_uploads)cloud\_storage\_enable\_segment\_uploads Controls the upload of log segments to Tiered Storage. If set to `false`, this property temporarily pauses all log segment uploads from the Redpanda cluster. When the uploads are paused, the [`cloud_storage_enable_remote_allow_gaps`](#cloud_storage_enable_remote_allow_gaps) cluster configuration and `redpanda.remote.allowgaps` topic properties control local retention behavior. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Related topics | redpanda.remote.allowgaps | ### [](#cloud_storage_enabled)cloud\_storage\_enabled Enable object storage. Must be set to `true` to use Tiered Storage or Remote Read Replicas. > 📝 **NOTE: Enterprise license required** > > Enterprise license required > > The following values require an Enterprise license: `true` > > For license details, see [Redpanda Licensing](../../../get-started/licensing/). | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#cloud_storage_full_scrub_interval_ms)cloud\_storage\_full\_scrub\_interval\_ms Interval, in milliseconds, between a final scrub and the next scrub. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 43200000 (12 hours) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_garbage_collect_timeout_ms)cloud\_storage\_garbage\_collect\_timeout\_ms Timeout for running the cloud storage garbage collection, in milliseconds. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 30000 (30 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_gc_max_segments_per_run)cloud\_storage\_gc\_max\_segments\_per\_run **Introduced in v25.3.11** Maximum number of log segments to delete from object storage during each housekeeping run. This limits the rate of object deletions to prevent overwhelming the object storage API. Each segment requires 2-3 object storage delete operations (for the data file, index file, and optionally a transaction manifest), so this value directly controls API request rate. See [Object storage housekeeping](../../../manage/tiered-storage/#object-storage-housekeeping). | Property | Value | | --- | --- | | Type | integer | | Default | 300 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_graceful_transfer_timeout_ms)cloud\_storage\_graceful\_transfer\_timeout\_ms Time limit on waiting for uploads to complete before a leadership transfer. If this is `null`, leadership transfers proceed without waiting. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 5000 (5 seconds) | | Nullable | Yes | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Aliases | cloud_storage_graceful_transfer_timeout | ### [](#cloud_storage_housekeeping_interval_ms)cloud\_storage\_housekeeping\_interval\_ms Interval, in milliseconds, between object storage housekeeping tasks. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 300000 (5 minutes) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_hydrated_chunks_per_segment_ratio)cloud\_storage\_hydrated\_chunks\_per\_segment\_ratio The maximum number of chunks per segment that can be hydrated at a time. Above this number, unused chunks are trimmed. A segment is divided into chunks. Chunk hydration means downloading the chunk (which is a small part of a full segment) from cloud storage and placing it in the local disk cache. Redpanda periodically removes old, unused chunks from your local disk. This process is called chunk eviction. This property controls how many chunks can be present for a given segment in local disk at a time, before eviction is triggered, removing the oldest ones from disk. Note that this property is not used for the default eviction strategy which simply removes all unused chunks. | Property | Value | | --- | --- | | Type | number | | Default | 0.7 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_hydration_timeout_ms)cloud\_storage\_hydration\_timeout\_ms Time to wait for a hydration request to be fulfilled. If hydration is not completed within this time, the consumer is notified with a timeout error. Negative doesn’t make sense, but it may not be checked-for/enforced. Large is subjective, but a huge timeout also doesn’t make sense. This particular config doesn’t have a min/max bounds control, but it probably should to avoid mistakes. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 600000 (10 minutes) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_idle_threshold_rps)cloud\_storage\_idle\_threshold\_rps The object storage request rate threshold for idle state detection. If the average request rate for the configured period is lower than this threshold, the object storage is considered idle. | Property | Value | | --- | --- | | Type | number | | Default | 10 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_idle_timeout_ms)cloud\_storage\_idle\_timeout\_ms The timeout, in milliseconds, used to detect the idle state of the object storage API. If the average object storage request rate is below this threshold for a configured amount of time, the object storage is considered idle and the housekeeping jobs are started. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 10000 (10 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_initial_backoff_ms)cloud\_storage\_initial\_backoff\_ms Initial backoff time for exponential backoff algorithm (ms). | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 100 (100 milliseconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_inventory_based_scrub_enabled)cloud\_storage\_inventory\_based\_scrub\_enabled Scrubber uses the latest cloud storage inventory report, if available, to check if the required objects exist in the bucket or container. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_inventory_id)cloud\_storage\_inventory\_id The name of the scheduled inventory job created by Redpanda to generate bucket or container inventory reports. | Property | Value | | --- | --- | | Type | string | | Default | redpanda_scrubber_inventory | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_inventory_max_hash_size_during_parse)cloud\_storage\_inventory\_max\_hash\_size\_during\_parse Maximum bytes of hashes held in memory before writing data to disk during inventory report parsing. This affects the number of files written to disk during inventory report parsing. When this limit is reached, new files are written to disk. | Property | Value | | --- | --- | | Type | integer | | Maximum | 18446744073709552000 | | Default | 67108864 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_inventory_report_check_interval_ms)cloud\_storage\_inventory\_report\_check\_interval\_ms Time interval between checks for a new inventory report in the cloud storage bucket or container. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 21600000 (6 hours) | | Nullable | No | | Unit | Milliseconds | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_inventory_reports_prefix)cloud\_storage\_inventory\_reports\_prefix The prefix to the path in the cloud storage bucket or container where inventory reports will be placed. | Property | Value | | --- | --- | | Type | string | | Default | redpanda_scrubber_inventory | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_inventory_self_managed_report_config)cloud\_storage\_inventory\_self\_managed\_report\_config If enabled, Redpanda will not attempt to create the scheduled report configuration using cloud storage APIs. The scrubbing process will look for reports in the expected paths in the bucket or container, and use the latest report found. Primarily intended for use in testing and on backends where scheduled inventory reports are not supported. | Property | Value | | --- | --- | | Type | boolean | | Default | false | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_manifest_cache_size)cloud\_storage\_manifest\_cache\_size Amount of memory that can be used to handle Tiered Storage metadata. | Property | Value | | --- | --- | | Type | integer | | Default | 1048576 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_manifest_cache_ttl_ms)cloud\_storage\_manifest\_cache\_ttl\_ms The time interval that determines how long the materialized manifest can stay in cache under contention. This parameter is used for performance tuning. When the spillover manifest is materialized and stored in cache and the cache needs to evict it it will use 'cloud\_storage\_materialized\_manifest\_ttl\_ms' value as a timeout. The cursor that uses the spillover manifest uses this value as a TTL interval after which it stops referencing the manifest making it available for eviction. This only affects spillover manifests under contention. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 10000 (10 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_manifest_max_upload_interval_sec)cloud\_storage\_manifest\_max\_upload\_interval\_sec Minimum interval, in seconds, between partition manifest uploads. Actual time between uploads may be greater than this interval. If this is `null`, metadata is updated after each segment upload. | Property | Value | | --- | --- | | Type | integer | | Range | [-17179869184, 17179869183] | | Default | 60 (1 minute) | | Nullable | Yes | | Unit | Seconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_manifest_upload_timeout_ms)cloud\_storage\_manifest\_upload\_timeout\_ms Manifest upload timeout, in milliseconds. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 30000 (30 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_materialized_manifest_ttl_ms)cloud\_storage\_materialized\_manifest\_ttl\_ms The interval, in milliseconds, determines how long the materialized manifest can stay in the cache under contention. This setting is used for performance tuning. When the spillover manifest is materialized and stored in the cache, and the cache needs to evict it, it uses this value as a timeout. The cursor that uses the spillover manifest uses this value as a TTL interval, after which it stops referencing the manifest making it available for eviction. This only affects spillover manifests under contention. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | No | | Unit | Milliseconds | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#cloud_storage_max_concurrent_hydrations_per_shard)cloud\_storage\_max\_concurrent\_hydrations\_per\_shard Maximum concurrent segment hydrations of remote data per CPU core. If unset, value of `cloud_storage_max_connections / 2` is used, which means that half of available object storage bandwidth could be used to download data from object storage. If the cloud storage cache is empty every new segment reader will require a download. This will lead to 1:1 mapping between number of partitions scanned by the fetch request and number of parallel downloads. If this value is too large the downloads can affect other workloads. In case of any problem caused by the tiered-storage reads this value can be lowered. This will only affect segment hydrations (downloads) but won’t affect cached segments. If fetch request is reading from the tiered-storage cache its concurrency will only be limited by available memory. | Property | Value | | --- | --- | | Type | integer | | Maximum | 4294967295 | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_max_connection_idle_time_ms)cloud\_storage\_max\_connection\_idle\_time\_ms Defines the maximum duration an HTTPS connection to object storage can stay idle, in milliseconds, before being terminated. This setting reduces resource utilization by closing inactive connections. Adjust this property to balance keeping connections ready for subsequent requests and freeing resources associated with idle connections. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 5000 (5 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_max_connections)cloud\_storage\_max\_connections Maximum simultaneous object storage connections per shard, applicable to upload and download activities. | Property | Value | | --- | --- | | Type | integer | | Range | [-32768, 32767] | | Default | 20 | | Nullable | No | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | ### [](#cloud_storage_max_segment_readers_per_shard)cloud\_storage\_max\_segment\_readers\_per\_shard Maximum concurrent I/O cursors of materialized remote segments per CPU core. If unset, the value of `topic_partitions_per_shard` is used, where one segment reader per partition is used if the shard is at its maximum partition capacity. These readers are cached across Kafka consume requests and store a readahead buffer. | Property | Value | | --- | --- | | Type | integer | | Maximum | 4294967295 | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Aliases | cloud_storage_max_readers_per_shard | ### [](#cloud_storage_max_segments_pending_deletion_per_partition)cloud\_storage\_max\_segments\_pending\_deletion\_per\_partition The per-partition limit for the number of segments pending deletion from the cloud. Segments can be deleted due to retention or compaction. If this limit is breached and deletion fails, then segments are orphaned in the cloud and must be removed manually. | Property | Value | | --- | --- | | Type | integer | | Default | 5000 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_max_throughput_per_shard)cloud\_storage\_max\_throughput\_per\_shard Maximum bandwidth allocated to Tiered Storage operations per shard, in bytes per second. This setting limits the Tiered Storage subsystem’s throughput per shard, facilitating precise control over bandwidth usage in testing scenarios. In production environments, use `cloud_storage_throughput_limit_percent` for more dynamic throughput management based on actual storage capabilities. | Property | Value | | --- | --- | | Type | integer | | Default | 1073741824 | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_metadata_sync_timeout_ms)cloud\_storage\_metadata\_sync\_timeout\_ms Timeout for [Use Tiered Storage](../../../manage/tiered-storage/) metadata synchronization. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 10000 (10 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_min_chunks_per_segment_threshold)cloud\_storage\_min\_chunks\_per\_segment\_threshold The minimum number of chunks per segment for trimming to be enabled. If the number of chunks in a segment is below this threshold, the segment is small enough that all chunks in it can be hydrated at any given time. | Property | Value | | --- | --- | | Type | integer | | Maximum | 18446744073709552000 | | Default | 5 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_partial_scrub_interval_ms)cloud\_storage\_partial\_scrub\_interval\_ms Time interval between two partial scrubs of the same partition. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 3600000 (1 hour) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_prefetch_segments_max)cloud\_storage\_prefetch\_segments\_max **Introduced in v26.1.1** Maximum number of small segments (size ⇐ chunk size) to prefetch ahead during sequential reads. Set to 0 to disable cross-segment prefetch. | Property | Value | | --- | --- | | Type | integer | | Maximum | 65535 | | Default | 3 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_readreplica_manifest_sync_timeout_ms)cloud\_storage\_readreplica\_manifest\_sync\_timeout\_ms Timeout to check if new data is available for partitions in object storage for read replicas. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 30000 (30 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_recovery_temporary_retention_bytes_default)cloud\_storage\_recovery\_temporary\_retention\_bytes\_default Retention in bytes for topics created during automated recovery. | Property | Value | | --- | --- | | Type | integer | | Default | 1073741824 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_recovery_topic_validation_depth)cloud\_storage\_recovery\_topic\_validation\_depth Number of metadata segments to validate, from newest to oldest, when [`cloud_storage_recovery_topic_validation_mode`](#cloud_storage_recovery_topic_validation_mode) is set to `check_manifest_and_segment_metadata`. | Property | Value | | --- | --- | | Type | integer | | Maximum | 4294967295 | | Default | 10 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_recovery_topic_validation_mode)cloud\_storage\_recovery\_topic\_validation\_mode Validation performed before recovering a topic from object storage. In case of failure, the reason for the failure appears as `ERROR` lines in the Redpanda application log. For each topic, this reports errors for all partitions, but for each partition, only the first error is reported. This property accepts the following parameters: - `no_check`: Skips the checks for topic recovery. - `check_manifest_existence`: Runs an existence check on each `partition_manifest`. Fails if there are connection issues to the object storage. - `check_manifest_and_segment_metadata`: Downloads the manifest and runs a consistency check, comparing the metadata with the cloud storage objects. The process fails if metadata references any missing cloud storage objects. Example: Redpanda validates the topic `kafka/panda-topic-recovery-NOT-OK` and stops due to a fatal error on partition 0: ```bash ERROR 2024-04-24 21:29:08,166 [shard 1:main] cluster - [fiber11|0|299996ms recovery validation of {kafka/panda-topic-recovery-NOT-OK/0}/24] - manifest metadata check: missing segment, validation not ok ERROR 2024-04-24 21:29:08,166 [shard 1:main] cluster - topics_frontend.cc:519 - Stopping recovery of {kafka/panda-topic-recovery-NOT-OK} due to validation error ``` Each failing partition error message has the following format: ```bash ERROR .... [... recovery validation of {}...] - , validation not ok ``` At the end of the process, Redpanda outputs a final ERROR message: ```bash ERROR ... ... - Stopping recovery of {} due to validation error ``` | Property | Value | | --- | --- | | Type | string (enum) | | Accepted values | check_manifest_existence, check_manifest_and_segment_metadata, no_check | | Default | check_manifest_existence | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | | Example | check_manifest_existence | ### [](#cloud_storage_region)cloud\_storage\_region Cloud provider region that houses the bucket or container used for storage. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | No | | Visibility | User | ### [](#cloud_storage_roles_operation_timeout_ms)cloud\_storage\_roles\_operation\_timeout\_ms Timeout for IAM role related operations (ms). | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 30000 (30 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_scrubbing_interval_jitter_ms)cloud\_storage\_scrubbing\_interval\_jitter\_ms Jitter applied to the object storage scrubbing interval. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 600000 (10 minutes) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_secret_key)cloud\_storage\_secret\_key Cloud provider secret key. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | No | | Visibility | User | ### [](#cloud_storage_segment_max_upload_interval_sec)cloud\_storage\_segment\_max\_upload\_interval\_sec Time that a segment can be kept locally without uploading it to the object storage, in seconds. | Property | Value | | --- | --- | | Type | integer | | Range | [-17179869184, 17179869183] | | Default | 3600 (1 hour) | | Nullable | Yes | | Unit | Seconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_segment_size_min)cloud\_storage\_segment\_size\_min Smallest acceptable segment size in the object storage. Default: `cloud_storage_segment_size_target`/2. | Property | Value | | --- | --- | | Type | integer | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_segment_size_target)cloud\_storage\_segment\_size\_target Desired segment size in the object storage. The default is set in the topic-level `segment.bytes` property. | Property | Value | | --- | --- | | Type | integer | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_segment_upload_timeout_ms)cloud\_storage\_segment\_upload\_timeout\_ms Log segment upload timeout, in milliseconds. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 90000 (90 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_spillover_manifest_max_segments)cloud\_storage\_spillover\_manifest\_max\_segments Maximum number of segments in the spillover manifest that can be offloaded to the object storage. This setting serves as a threshold for triggering data offload based on the number of segments, rather than the total size of the manifest. It is designed for use in testing environments to control the offload behavior more granularly. In production settings, manage offloads based on the manifest size through `cloud_storage_spillover_manifest_size` for more predictable outcomes. | Property | Value | | --- | --- | | Type | integer | | Default | null | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_spillover_manifest_size)cloud\_storage\_spillover\_manifest\_size The size of the manifest which can be offloaded to the cloud. If the size of the local manifest stored in Redpanda exceeds `cloud_storage_spillover_manifest_size` by two times the spillover mechanism will split the manifest into two parts and one will be uploaded to object storage. | Property | Value | | --- | --- | | Type | integer | | Default | 65536 | | Nullable | Yes | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_throughput_limit_percent)cloud\_storage\_throughput\_limit\_percent Maximum throughput used by Tiered Storage per broker expressed as a percentage of the disk bandwidth. If the server has several disks, Redpanda uses the one that stores the Tiered Storage cache. Even if Tiered Storage is allowed to use the full bandwidth of the disk (100%), it won’t necessarily use it in full. The actual usage depends on your workload and the state of the Tiered Storage cache. This setting is a safeguard that prevents Tiered Storage from using too many system resources: it is not a performance tuning knob. | Property | Value | | --- | --- | | Type | integer | | Default | 50 | | Nullable | Yes | | Unit | Percent | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_topic_purge_grace_period_ms)cloud\_storage\_topic\_purge\_grace\_period\_ms Grace period during which the purger refuses to purge the topic. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 30000 (30 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_trust_file)cloud\_storage\_trust\_file Path to certificate that should be used to validate server certificate during TLS handshake. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | No | | Visibility | User | ### [](#cloud_storage_upload_ctrl_d_coeff)cloud\_storage\_upload\_ctrl\_d\_coeff Derivative coefficient for upload PID controller. | Property | Value | | --- | --- | | Type | number | | Default | 0 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_upload_ctrl_max_shares)cloud\_storage\_upload\_ctrl\_max\_shares Maximum number of I/O and CPU shares that archival upload can use. | Property | Value | | --- | --- | | Type | integer | | Range | [-32768, 32767] | | Default | 1000 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_upload_ctrl_min_shares)cloud\_storage\_upload\_ctrl\_min\_shares Minimum number of I/O and CPU shares that archival upload can use. | Property | Value | | --- | --- | | Type | integer | | Range | [-32768, 32767] | | Default | 100 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_upload_ctrl_p_coeff)cloud\_storage\_upload\_ctrl\_p\_coeff Proportional coefficient for upload PID controller. | Property | Value | | --- | --- | | Type | number | | Default | -2 | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_upload_ctrl_update_interval_ms)cloud\_storage\_upload\_ctrl\_update\_interval\_ms The interval (in milliseconds) for updating the controller that manages the priority of Tiered Storage uploads. This property determines how frequently the system recalculates and adjusts the work scheduling for uploads to object storage. This is an internal-only configuration and should be enabled only after consulting with Redpanda support. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 60000 (1 minute) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_upload_loop_initial_backoff_ms)cloud\_storage\_upload\_loop\_initial\_backoff\_ms Initial backoff interval when there is nothing to upload for a partition, in milliseconds. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 100 (100 milliseconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_upload_loop_max_backoff_ms)cloud\_storage\_upload\_loop\_max\_backoff\_ms Maximum backoff interval when there is nothing to upload for a partition, in milliseconds. | Property | Value | | --- | --- | | Type | integer | | Range | [-17592186044416, 17592186044415] | | Default | 10000 (10 seconds) | | Nullable | No | | Unit | Milliseconds | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | Tunable | ### [](#cloud_storage_url_style)cloud\_storage\_url\_style Configure the addressing style that controls how Redpanda formats bucket URLs for S3-compatible object storage. Leave this property unset (`null`) to use automatic configuration: - For AWS S3: Redpanda attempts `virtual_host` addressing first, then falls back to `path` style if needed - For MinIO: Redpanda automatically uses `path` style regardless of `MINIO_DOMAIN` configuration Set this property explicitly to override automatic configuration, ensure consistent behavior across deployments, or when using S3-compatible storage that requires a specific URL format. > ⚠️ **CAUTION** > > AWS requires virtual-hosted addressing for buckets created after September 30, 2020. If you use AWS S3 with buckets created after this date, use `virtual_host` addressing. > 📝 **NOTE** > > For MinIO deployments, Redpanda defaults to `path` style when this property is unset. To use `virtual_host` addressing with a configured `MINIO_DOMAIN`, set this property explicitly to `virtual_host`. For other S3-compatible storage backends, consult your provider’s documentation to determine the required URL style. | Property | Value | | --- | --- | | Type | string (enum) | | Accepted values | virtual_host, path | | Default | null | | Nullable | Yes | | Requires restart | Yes | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | virtual_host | ### [](#kafka_enable_describe_log_dirs_remote_storage)kafka\_enable\_describe\_log\_dirs\_remote\_storage Whether to include Tiered Storage as a special remote:// directory in `DescribeLogDirs Kafka` API requests. | Property | Value | | --- | --- | | Type | boolean | | Default | true | | Nullable | No | | Requires restart | No | | Restored on Whole Cluster Restore | Yes | | Visibility | User | | Example | false | --- # Page 266: Topic Configuration Properties **URL**: https://docs.redpanda.com/current/reference/properties/topic-properties.md --- # Topic Configuration Properties --- title: Topic Configuration Properties latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: properties/topic-properties page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: properties/topic-properties.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/properties/topic-properties.adoc description: Reference of topic configuration properties. page-git-created-date: "2024-05-23" page-git-modified-date: "2026-03-31" support-status: supported --- A topic-level property sets a Redpanda or Kafka configuration for a particular topic. Many topic-level properties have corresponding [cluster properties](../../../manage/cluster-maintenance/cluster-property-configuration/) that set a default value for all topics of a cluster. To customize the value for a topic, you can set a topic-level property that overrides the value of the corresponding cluster property. For information on how to configure topic properties, see [Configure Topic Properties](../../../manage/cluster-maintenance/topic-property-configuration/). > ⚠️ **WARNING** > > All topic properties take effect immediately after being set. Do not modify properties on internal Redpanda topics (such as `__consumer_offsets`, `_schemas`, or other system topics) as this can cause cluster instability. ## [](#topic-property-mappings)Topic property mappings | Topic Property | Corresponding Cluster Property | | --- | --- | | cleanup.policy | log_cleanup_policy | | compression.type | log_compression_type | | delete.retention.ms | tombstone_retention_ms | | flush.bytes | raft_replica_max_pending_flush_bytes | | flush.ms | raft_replica_max_flush_delay_ms | | initial.retention.local.target.bytes | initial_retention_local_target_bytes_default | | initial.retention.local.target.ms | initial_retention_local_target_ms_default | | max.compaction.lag.ms | max_compaction_lag_ms | | max.message.bytes | kafka_batch_max_bytes | | message.timestamp.after.max.ms | log_message_timestamp_after_max_ms | | message.timestamp.before.max.ms | log_message_timestamp_before_max_ms | | message.timestamp.type | log_message_timestamp_type | | min.cleanable.dirty.ratio | min_cleanable_dirty_ratio | | min.compaction.lag.ms | min_compaction_lag_ms | | redpanda.iceberg.delete | iceberg_delete | | redpanda.iceberg.invalid.record.action | iceberg_invalid_record_action | | redpanda.iceberg.partition.spec | iceberg_default_partition_spec | | redpanda.leaders.preference | default_leaders_preference | | redpanda.remote.read | cloud_storage_enable_remote_read | | redpanda.remote.write | cloud_storage_enable_remote_write | | redpanda.storage.mode | default_redpanda_storage_mode | | retention.bytes | retention_bytes | | retention.local.target.bytes | retention_local_target_bytes_default | | retention.local.target.ms | retention_local_target_ms_default | | retention.ms | log_retention_ms | | segment.bytes | log_segment_size or compacted_log_segment_size | | segment.ms | log_segment_ms | | write.caching | write_caching_default | * * * ## [](#retention-and-compaction-properties)Retention and Compaction Properties These properties control how data is stored, for how long, and when it is deleted or compacted. ### [](#cleanup-policy)cleanup.policy The cleanup policy to apply for log segments of a topic. When `cleanup.policy` is set, it overrides the cluster property [`log_cleanup_policy`](../cluster-properties/#log_cleanup_policy) for the topic. **Values**: - `delete` - Deletes data according to size-based or time-based retention limits, or both. - `compact` - Deletes data according to a key-based retention policy, discarding all but the latest value for each key. - `compact,delete` - The latest values are kept for each key, while the remaining data is deleted according to retention limits. | Property | Value | | --- | --- | | Type | string (enum) | | Accepted Values | none, delete, compact | | Corresponding cluster property | log_cleanup_policy | | Default | delete | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | log_cleanup_policyConfigure segment sizeCompacted topics in Tiered Storagelog_cleanup_policy | ### [](#compaction-strategy)compaction.strategy Specifies the strategy used to determine which records to remove during log compaction. The compaction strategy controls how Redpanda identifies and removes duplicate records while preserving the latest value for each key. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | compaction_strategy | ### [](#delete-retention-ms)delete.retention.ms The retention time for tombstone records in a compacted topic. Redpanda removes tombstone records after the retention limit is exceeded. If you have enabled Tiered Storage and set [`redpanda.remote.read`](#redpandaremoteread) or [`redpanda.remote.write`](#redpandaremotewrite) for the topic, you cannot enable tombstone removal. If both `delete.retention.ms` and the cluster property `[tombstone_retention_ms](../cluster-properties/#tombstone_retention_ms)` are set, `delete.retention.ms` overrides the cluster level tombstone retention for an individual topic. This property supports three states: - Positive value: Sets the milliseconds to retain tombstone records before removal. - 0: Tombstone records are immediately eligible for removal. - Negative value: Disables tombstone removal entirely for this topic. | Property | Value | | --- | --- | | Type | integer | | Accepted values | milliseconds (integer) | | Corresponding cluster property | tombstone_retention_ms | | Default | null | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | tombstone_retention_msTombstone record removal | ### [](#max-compaction-lag-ms)max.compaction.lag.ms The maximum amount of time (in ms) that a log segment can remain unaltered before it is eligible for compaction in a compact topic. Overrides the cluster property [`max_compaction_lag_ms`](../cluster-properties/#max_compaction_lag_ms) for the topic. | Property | Value | | --- | --- | | Type | integer | | Accepted values | milliseconds (integer) | | Corresponding cluster property | max_compaction_lag_ms | | Default | 9223372036854 | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | max_compaction_lag_msConfigure maximum compaction lag | ### [](#min-cleanable-dirty-ratio)min.cleanable.dirty.ratio The minimum ratio between dirty and total bytes in closed segments before a partition’s log is eligible for compaction in a compact topic. This property supports three states: - Positive value: Sets the minimum dirty ratio (0.0 to 1.0) required before compaction. - 0: Compaction is always eligible regardless of dirty ratio. - Negative value: This property is not considered when deciding if a log is eligible for compaction. | Property | Value | | --- | --- | | Type | number | | Accepted values | [0, 1.0] | | Corresponding cluster property | min_cleanable_dirty_ratio | | Default | 0.2 | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | min_cleanable_dirty_ratio | ### [](#min-compaction-lag-ms)min.compaction.lag.ms The minimum amount of time (in ms) that a log segment must remain unaltered before it can be compacted in a compact topic. Overrides the cluster property [`min_compaction_lag_ms`](../cluster-properties/#min_compaction_lag_ms) for the topic. | Property | Value | | --- | --- | | Type | integer | | Accepted values | milliseconds (integer) | | Corresponding cluster property | min_compaction_lag_ms | | Default | 0 (0 milliseconds) | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | min_compaction_lag_msmin_compaction_lag_msConfigure minimum compaction lag | ### [](#retention-bytes)retention.bytes A size-based retention limit that configures the maximum size that a topic partition can grow before becoming eligible for cleanup. If `retention.bytes` is set to a positive value, it overrides the cluster property [`retention_bytes`](../cluster-properties/#retention_bytes) for the topic, and the total retained size for the topic is `retention.bytes` multiplied by the number of partitions for the topic. When both size-based (`retention.bytes`) and time-based (`retention.ms`) retention limits are set, cleanup occurs when either limit is reached. This property supports three states: - Positive value: Sets the maximum bytes per partition. When exceeded, oldest data becomes eligible for cleanup. - 0: Partitions are immediately eligible for cleanup. - Negative value: Disables size-based retention for this topic. | Property | Value | | --- | --- | | Type | integer | | Accepted values | bytes (integer) | | Corresponding cluster property | retention_bytes | | Default | null | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | retention_bytesretention_bytesConfigure message retention | ### [](#retention-ms)retention.ms A time-based retention limit that configures the maximum duration that a log’s segment file for a topic is retained before it becomes eligible to be cleaned up. To consume all data, a consumer of the topic must read from a segment before its `retention.ms` elapses, otherwise the segment may be compacted and/or deleted. If `retention.ms` is set to a positive value, it overrides the cluster property [`log_retention_ms`](../cluster-properties/#log_retention_ms) for the topic. When both size-based (`retention.bytes`) and time-based (`retention.ms`) retention limits are set, the earliest occurring limit applies. This property supports three states: - Positive value: Sets the maximum milliseconds to retain data. After this duration, segments become eligible for cleanup. - 0: Data is immediately eligible for cleanup. - Negative value: Disables time-based retention for this topic. | Property | Value | | --- | --- | | Type | retention_duration_property | | Corresponding cluster property | log_retention_ms | | Default | 604800000 (1 week) | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | log_retention_msConfigure message retention | ## [](#segment-and-message-properties)Segment and Message Properties These properties control the size and lifecycle of log segment files and settings for individual messages. ### [](#compression-type)compression.type Redpanda ignores this property and always uses producer compression semantics. If producers send compressed data, Redpanda stores and serves it as-is. If producers send uncompressed data, Redpanda stores it uncompressed. This property exists for Apache Kafka compatibility. Configure compression in your producers instead of using this topic property. Compression reduces message size and improves throughput, but increases CPU utilization. Enable producer batching to increase compression efficiency. When set, this property overrides the cluster property [`log_compression_type`](../cluster-properties/#log_compression_type) for the topic. | Property | Value | | --- | --- | | Type | string (enum) | | Accepted Values | none, gzip, snappy, lz4, zstd, count, producer | | Corresponding cluster property | log_compression_type | | Default | producer | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | log_compression_typeMessage batchingCommon producer configuration options | ### [](#max-message-bytes)max.message.bytes The maximum size of a message or batch of a topic. If a compression type is enabled, `max.message.bytes` sets the maximum size of the compressed message or batch. If `max.message.bytes` is set to a positive value, it overrides the cluster property [`kafka_batch_max_bytes`](../cluster-properties/#kafka_batch_max_bytes) for the topic. Set an upper limit for `max.message.bytes` using the cluster property `[kafka_max_message_size_upper_limit_bytes](../cluster-properties/#kafka_max_message_size_upper_limit_bytes)`. | Property | Value | | --- | --- | | Type | integer | | Accepted values | bytes (integer) | | Corresponding cluster property | kafka_batch_max_bytes | | Default | 1048576 | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | kafka_batch_max_bytesMessage batchingkafka_max_message_size_upper_limit_bytes | ### [](#message-timestamp-type)message.timestamp.type The source of a message’s timestamp: either the message’s creation time or its log append time. When `message.timestamp.type` is set, it overrides the cluster property [`log_message_timestamp_type`](../cluster-properties/#log_message_timestamp_type) for the topic. | Property | Value | | --- | --- | | Type | string (enum) | | Accepted Values | CreateTime, LogAppendTime | | Corresponding cluster property | log_message_timestamp_type | | Default | CreateTime | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | log_message_timestamp_type | ### [](#segment-bytes)segment.bytes The maximum size of an active log segment for a topic. When the size of an active segment exceeds `segment.bytes`, the segment is closed and a new active segment is created. The closed, inactive segment is then eligible to be cleaned up according to retention properties. When `segment.bytes` is set to a positive value, it overrides the cluster property: - [`log_segment_size`](../cluster-properties/#log_segment_size) for non-compacted topics - [`compacted_log_segment_size`](../cluster-properties/#compacted_log_segment_size) for compacted topics (when `cleanup.policy=compact`) | Property | Value | | --- | --- | | Type | integer | | Accepted values | bytes (integer) | | Corresponding cluster property | log_segment_size | | Default | 134217728 | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | log_segment_sizeConfigure segment sizeConfigure message retentionRemote Read Replicascompacted_log_segment_size | ### [](#segment-ms)segment.ms The maximum duration that a log segment of a topic is active (open for writes and not deletable). A periodic event, with `segment.ms` as its period, forcibly closes the active segment and transitions, or rolls, to a new active segment. The closed (inactive) segment is then eligible to be cleaned up according to cleanup and retention properties. If set to a positive duration, `segment.ms` overrides the cluster property [`log_segment_ms`](../cluster-properties/#log_segment_ms). Values are automatically clamped between the cluster bounds set by [`log_segment_ms_min`](../cluster-properties/#log_segment_ms_min) (default: 10 minutes) and [`log_segment_ms_max`](../cluster-properties/#log_segment_ms_max) (default: 1 year). If your configured value exceeds these bounds, Redpanda uses the bound value and logs a warning. Check current cluster bounds with `rpk cluster config get log_segment_ms_min log_segment_ms_max`. For topics with compaction enabled, `max.compaction.lag.ms` also acts as a limit to `segment.ms`. This property supports three states: - Positive value: Sets the maximum milliseconds a segment remains active before rolling to a new segment. - 0: Segments are immediately eligible for closure. - Negative value: Disables time-based segment rolling for this topic. | Property | Value | | --- | --- | | Type | integer | | Accepted values | milliseconds (integer) | | Corresponding cluster property | log_segment_ms | | Default | 2 weeks | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | log_segment_mslog_segment_ms_minlog_segment_ms_maxLog rolling | ## [](#performance-and-cluster-properties)Performance and Cluster Properties These properties control disk flushing, replication, and how topics interact with the cluster. ### [](#flush-bytes)flush.bytes The maximum bytes not fsynced per partition. If this configured threshold is reached, the log is automatically fsynced, even though it wasn’t explicitly requested. | Property | Value | | --- | --- | | Type | integer | | Accepted values | bytes (integer) | | Corresponding cluster property | raft_replica_max_pending_flush_bytes | | Default | 262144 | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | flush_bytes | ### [](#flush-ms)flush.ms The maximum delay (in ms) between two subsequent fsyncs. After this delay, the log is automatically fsynced. | Property | Value | | --- | --- | | Type | integer | | Accepted values | milliseconds (integer) | | Corresponding cluster property | raft_replica_max_flush_delay_ms | | Default | 100 (100 milliseconds) | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | flush_ms | ### [](#redpanda-leaders-preference)redpanda.leaders.preference The preferred location (rack) for partition leaders of a topic. This property inherits the value from the `[default_leaders_preference](../cluster-properties/#default_leaders_preference)` cluster configuration property. You may override the cluster-wide setting by specifying the value for individual topics. If the cluster configuration property `[enable_rack_awareness](../cluster-properties/#enable_rack_awareness)` is set to `false`, Leader Pinning is disabled across the cluster. | Property | Value | | --- | --- | | Type | object | | Corresponding cluster property | default_leaders_preference | | Default | none | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | Leader pinning | ### [](#replication-factor)replication.factor The number of replicas of a topic to save in different nodes (brokers) of a cluster. If `replication.factor` is set to a positive value, it overrides the cluster property [default\_topic\_replication](../cluster-properties/#default_topic_replication) for the topic. > 📝 **NOTE** > > Although `replication.factor` isn’t returned or displayed by [`rpk topic describe`](../../rpk/rpk-topic/rpk-topic-describe/) as a valid Kafka property, you can set it using [`rpk topic alter-config`](../../rpk/rpk-topic/rpk-topic-alter-config/). When the `replication.factor` of a topic is altered, it isn’t simply a property value that’s updated, but rather the actual replica sets of topic partitions that are changed. | Property | Value | | --- | --- | | Type | integer | | Accepted values | integer (1 or greater) | | Default | null | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | rpk topic describerpk topic alter-configdefault_topic_replicationChoose the replication factorChange the replication factordefault_topic_replication | ### [](#write-caching)write.caching The write caching mode to apply to a topic. When `write.caching` is set, it overrides the cluster property [`write_caching_default`](../cluster-properties/#write_caching_default). Write caching acknowledges a message as soon as it is received and acknowledged on a majority of brokers, without waiting for it to be written to disk. With `acks=all`, this provides lower latency while still ensuring that a majority of brokers acknowledge the write. Fsyncs follow [`flush.ms`](#flushms) and [`flush.bytes`](#flushbytes), whichever is reached first. | Property | Value | | --- | --- | | Type | string (enum) | | Accepted Values | true, false, disabled | | Corresponding cluster property | write_caching_default | | Default | false | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | Write cachingTiered Storagewrite_caching_defaultwrite_caching_default | The maximum bytes not fsynced per partition. If this configured threshold is reached, the log is automatically fsynced, even though it wasn’t explicitly requested. **Type:** integer **Unit:** bytes **Accepted values:** \[`1`, `9223372036854775807`\] **Default:** `262144` **Related cluster property:** [`flush_bytes`](../cluster-properties/#flush_bytes) **Related topics**: - [Configure Producers](../../../develop/produce-data/configure-producers/) * * * ### [](#flushms)flush.ms The maximum delay (in ms) between two subsequent fsyncs. After this delay, the log is automatically fsynced. **Type:** integer **Unit:** milliseconds **Accepted values:** \[`1`, `9223372036854775`\] **Default:** `100` **Related cluster property:** [`flush_ms`](../cluster-properties/#flush_ms) **Related topics**: - [Configure Producers](../../../develop/produce-data/configure-producers/) * * * ### [](#redpandaleaderspreference)redpanda.leaders.preference The preferred location (rack) for partition leaders of a topic. This property inherits the value from the `[default_leaders_preference](../cluster-properties/#default_leaders_preference)` cluster configuration property. You may override the cluster-wide setting by specifying the value for individual topics. If the cluster configuration property `[enable_rack_awareness](../cluster-properties/#enable_rack_awareness)` is set to `false`, Leader Pinning is disabled across the cluster. **Type:** string **Default:** `none` **Values**: - `none`: Opt out the topic from Leader Pinning. - `racks:[,,…​]`: Specify the preferred location (rack) of all topic partition leaders. The list can contain one or more rack IDs. If you specify multiple IDs, Redpanda tries to distribute the partition leader locations equally across brokers in these racks. **Related topics**: - [Leader pinning](../../../develop/produce-data/leader-pinning/) * * * ### [](#replicationfactor)replication.factor The number of replicas of a topic to save in different nodes (brokers) of a cluster. If `replication.factor` is set to a positive value, it overrides the cluster property [default\_topic\_replication](../cluster-properties/#default_topic_replication) for the topic. > 📝 **NOTE** > > Although `replication.factor` isn’t returned or displayed by [`rpk topic describe`](../../rpk/rpk-topic/rpk-topic-describe/) as a valid Kafka property, you can set it using [`rpk topic alter-config`](../../rpk/rpk-topic/rpk-topic-alter-config/). When the `replication.factor` of a topic is altered, it isn’t simply a property value that’s updated, but rather the actual replica sets of topic partitions that are changed. **Type:** integer **Accepted values:** \[`1`, `512`\] **Default:** null **Related cluster property:** [`default_topic_replication`](../cluster-properties/#default_topic_replication) **Related topics**: - [Choose the replication factor](../../../develop/manage-topics/config-topics/#choose-the-replication-factor) - [Change the replication factor](../../../develop/manage-topics/config-topics/#change-the-replication-factor) * * * ### [](#writecaching)write.caching The write caching mode to apply to a topic. When `write.caching` is set, it overrides the cluster property [`write_caching_default`](../cluster-properties/#write_caching_default). Write caching acknowledges a message as soon as it is received and acknowledged on a majority of brokers, without waiting for it to be written to disk. With `acks=all`, this provides lower latency while still ensuring that a majority of brokers acknowledge the write. Fsyncs follow [`flush.ms`](#flushms) and [`flush.bytes`](#flushbytes), whichever is reached first. **Type:** boolean **Default:** `false` **Values**: - `true` - Enables write caching for a topic, according to [`flush.ms`](#flushms) and [`flush.bytes`](#flushbytes). - `false` - Disables write caching for a topic, according to [`flush.ms`](#flushms) and [`flush.bytes`](#flushbytes). **Related cluster property:** [`write_caching_default`](../cluster-properties/#write_caching_default) **Related topics**: - [Write caching](../../../develop/manage-topics/config-topics/#configure-write-caching) * * * ## [](#tiered-storage-properties)Tiered Storage properties Configure properties to manage topics for [Tiered Storage](../../../manage/tiered-storage/). ### [](#initial-retention-local-target-bytes)initial.retention.local.target.bytes A size-based initial retention limit for Tiered Storage that determines how much data in local storage is transferred to a partition replica when a cluster is resized. If `null` (default), all locally retained data is transferred. This property supports three states: - Positive value: Sets the maximum bytes of local data to transfer during cluster resize. - 0: No local data is transferred during cluster resize. - Negative value: All locally retained data is transferred (default behavior). | Property | Value | | --- | --- | | Type | integer | | Accepted values | bytes (integer) | | Corresponding cluster property | initial_retention_local_target_bytes_default | | Default | null | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | initial_retention_local_target_bytesFast commission and decommission through Tiered Storage | ### [](#initial-retention-local-target-ms)initial.retention.local.target.ms A time-based initial retention limit for Tiered Storage that determines how much data in local storage is transferred to a partition replica when a cluster is resized. If `null` (default), all locally retained data is transferred. This property supports three states: - Positive value: Sets the maximum age (milliseconds) of local data to transfer during cluster resize. - 0: No local data is transferred during cluster resize. - Negative value: All locally retained data is transferred (default behavior). | Property | Value | | --- | --- | | Type | integer | | Accepted values | milliseconds (integer) | | Corresponding cluster property | initial_retention_local_target_ms_default | | Default | null | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | initial_retention_local_target_msFast commission and decommission through Tiered Storage | ### [](#redpanda-cloud_topic-enabled)redpanda.cloud\_topic.enabled Enable Cloud Topic storage mode for this topic. When enabled, topic data is stored primarily in object storage with local storage used only as a write buffer. > 💡 **TIP** > > To configure storage modes with more flexibility, use [`redpanda.storage.mode`](#redpandastorage-mode) which supports `local`, `tiered`, `cloud`, and `unset` modes. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | Cloud TopicsTiered Storage | ### [](#redpanda-remote-delete)redpanda.remote.delete A flag that enables deletion of data from object storage for Tiered Storage when it’s deleted from local storage for a topic. > 📝 **NOTE** > > `redpanda.remote.delete` doesn’t apply to Remote Read Replica topics: a Remote Read Replica topic isn’t deleted from object storage when this flag is `true`. | Property | Value | | --- | --- | | Type | boolean | | Default | null | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | Tiered Storage | ### [](#redpanda-remote-read)redpanda.remote.read A flag for enabling Redpanda to fetch data for a topic from object storage to local storage. When set to `true` together with [`redpanda.remote.write`](#redpandaremotewrite), it enables the [Tiered Storage](../../../manage/tiered-storage/) feature. | Property | Value | | --- | --- | | Type | boolean | | Corresponding cluster property | cloud_storage_enable_remote_read | | Default | false | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | Tiered Storage | ### [](#redpanda-remote-recovery)redpanda.remote.recovery A flag that enables the recovery or reproduction of a topic from object storage for Tiered Storage. The recovered data is saved in local storage, and the maximum amount of recovered data is determined by the local storage retention limits of the topic. > 💡 **TIP** > > You can only configure `redpanda.remote.recovery` when you create a topic. You cannot apply this setting to existing topics. | Property | Value | | --- | --- | | Type | boolean | | Default | null | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | Tiered Storage | ### [](#redpanda-remote-write)redpanda.remote.write A flag for enabling Redpanda to upload data for a topic from local storage to object storage. When set to `true` together with [`redpanda.remote.read`](#redpandaremoteread), it enables the [Tiered Storage](../../../manage/tiered-storage/) feature. | Property | Value | | --- | --- | | Type | boolean | | Corresponding cluster property | cloud_storage_enable_remote_write | | Default | false | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | Tiered Storage | ### [](#redpanda-storage-mode)redpanda.storage.mode **Introduced in v26.1.1** The storage mode for a topic. Determines how topic data is stored and whether it is eligible for upload to object storage. Accepted values: - `local`: Topic data is stored only on the broker’s local disk. Object storage upload is disabled for the topic, regardless of cluster-level Tiered Storage settings. - `tiered`: Topic data is stored on local disk and also uploaded to object storage. Enables [Tiered Storage](../../../manage/tiered-storage/) for the topic. - `cloud`: Topic data is stored in object storage using the [Cloud Topics](../../../develop/manage-topics/cloud-topics/) architecture. Local storage is used only as a write buffer. - `unset`: Specifies that the topic’s storage mode is unset, regardless of the cluster default. The topic may still have Tiered Storage enabled through the legacy properties `redpanda.remote.read` and `redpanda.remote.write`. This property overrides the cluster-wide `[default_redpanda_storage_mode](../cluster-properties/#default_redpanda_storage_mode)` setting for individual topics. | Property | Value | | --- | --- | | Type | string (enum) | | Accepted Values | local, tiered, cloud, unset | | Corresponding cluster property | default_redpanda_storage_mode | | Default | unset | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | Tiered StorageManage Cloud Topics | ### [](#retention-local-target-bytes)retention.local.target.bytes A size-based retention limit for Tiered Storage that configures the maximum size that a topic partition in local storage can grow before becoming eligible for cleanup. It applies per partition and is equivalent to [`retention.bytes`](#retentionbytes) without Tiered Storage. This property supports three states: - Positive value: Sets the maximum bytes per partition in local storage before cleanup. - 0: Data in local storage is immediately eligible for cleanup. - Negative value: Disables size-based local retention override for this topic. | Property | Value | | --- | --- | | Type | integer | | Accepted values | bytes (integer) | | Corresponding cluster property | retention_local_target_bytes_default | | Default | null | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | retention_local_target_bytesTiered Storage | ### [](#retention-local-target-ms)retention.local.target.ms A time-based retention limit for Tiered Storage that sets the maximum duration that a log’s segment file for a topic is retained in local storage before cleanup. It applies per partition and is equivalent to [`retention.ms`](#retention-ms) without Tiered Storage. This property supports three states: - Positive value: Sets the maximum milliseconds to retain data in local storage. - 0: Data in local storage is immediately eligible for cleanup. - Negative value: Disables time-based local retention override for this topic. | Property | Value | | --- | --- | | Type | integer | | Accepted values | milliseconds (integer) | | Corresponding cluster property | retention_local_target_ms_default | | Default | 86400000 (1 day) | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | retention_local_target_msTiered StorageRemote Read Replicas | ## [](#remote-read-replica-properties)Remote Read Replica properties Configure properties to manage topics for [Remote Read Replicas](../../../manage/remote-read-replicas/). ### [](#redpanda-remote-readreplica)redpanda.remote.readreplica The name of the object storage bucket for a Remote Read Replica topic. > ⚠️ **CAUTION** > > Setting `redpanda.remote.readreplica` together with either `redpanda.remote.read` or `redpanda.remote.write` results in an error. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | Remote Read Replicas | ## [](#apache-iceberg-integration-properties)Apache Iceberg integration properties Integrate Redpanda topics as Iceberg tables. ### [](#redpanda-iceberg-delete)redpanda.iceberg.delete Whether the corresponding Iceberg table is deleted upon deleting the topic. | Property | Value | | --- | --- | | Type | boolean | | Corresponding cluster property | iceberg_delete | | Default | true | | Nullable | No | | Restored on Whole Cluster Restore | Yes | ### [](#redpanda-iceberg-invalid-record-action)redpanda.iceberg.invalid.record.action Whether to write invalid records to a dead-letter queue (DLQ). | Property | Value | | --- | --- | | Type | string (enum) | | Accepted Values | drop, dlq_table | | Corresponding cluster property | iceberg_invalid_record_action | | Default | dlq_table | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | Troubleshoot errors | ### [](#redpanda-iceberg-mode)redpanda.iceberg.mode Enable the Iceberg integration for the topic. You can choose one of four modes. | Property | Value | | --- | --- | | Type | string | | Default | null | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | Choose an Iceberg Mode | ### [](#redpanda-iceberg-partition-spec)redpanda.iceberg.partition.spec The [partitioning](https://iceberg.apache.org/docs/nightly/partitioning/) specification for the Iceberg table. | Property | Value | | --- | --- | | Type | string | | Corresponding cluster property | iceberg_default_partition_spec | | Default | (hour(redpanda.timestamp)) | | Nullable | No | | Restored on Whole Cluster Restore | Yes | | Related topics | Use custom partitioning | ### [](#redpanda-iceberg-target-lag-ms)redpanda.iceberg.target.lag.ms Controls how often the data in the Iceberg table is refreshed with new data from the topic. Redpanda attempts to commit all data produced to the topic within the lag target, subject to resource availability. | Property | Value | | --- | --- | | Type | integer | | Accepted values | milliseconds (integer) | | Default | null | | Nullable | No | | Restored on Whole Cluster Restore | Yes | --- # Page 267: Public Metrics **URL**: https://docs.redpanda.com/current/reference/public-metrics-reference.md --- # Public Metrics --- title: Public Metrics latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: public-metrics-reference page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: public-metrics-reference.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/public-metrics-reference.adoc description: Public metrics to create your system dashboard. page-git-created-date: "2023-05-30" page-git-modified-date: "2025-12-12" support-status: supported --- This section provides reference descriptions for the public metrics exported from Redpanda’s `/public_metrics` endpoint. > 💡 **TIP** > > Use [/public\_metrics](./) for your primary dashboards for monitoring system health. These metrics have low cardinality and are designed for customer consumption, with aggregated labels for better performance. **Public metrics use the `redpanda_` prefix.** > > Use [/metrics](../internal-metrics-reference/) for detailed analysis and debugging. These metrics can have high cardinality with thousands of series, providing granular operational insights. **Internal metrics use the `vectorized_` prefix.** > ❗ **IMPORTANT** > > In a live system, Redpanda metrics are exported only for features that are in use. For example, Redpanda does not export metrics for consumer groups if no groups are registered. > > To see the available public metrics in your system, query the `/public_metrics` endpoint: > > ```bash > curl http://:9644/public_metrics | grep "[HELP|TYPE]" > ``` ## [](#cluster-metrics)Cluster metrics ### [](#redpanda_cluster_brokers)redpanda\_cluster\_brokers Total number of fully commissioned brokers configured in the cluster. **Type**: gauge **Usage**: Create an alert if this gauge falls below a steady-state threshold, which may indicate that a broker has become unresponsive. * * * ### [](#redpanda_cluster_controller_log_limit_requests_available_rps)redpanda\_cluster\_controller\_log\_limit\_requests\_available\_rps The upper limit on the requests per second (RPS) that the cluster controller log is allowed to process, segmented by command group. **Type**: gauge **Labels**: - `redpanda_cmd_group=("move_operations" | "topic_operations" | "configuration_operations" | "node_management_operations" | "acls_and_users_operations")` * * * ### [](#redpanda_cluster_controller_log_limit_requests_dropped)redpanda\_cluster\_controller\_log\_limit\_requests\_dropped The cumulative number of requests dropped by the controller log because the incoming rate exceeded the available RPS limit. **Type**: counter **Labels**: - `redpanda_cmd_group=("move_operations" | "topic_operations" | "configuration_operations" | "node_management_operations" | "acls_and_users_operations")` **Usage**: A rising counter indicates that requests are being dropped, which could signal overload or misconfiguration. * * * ### [](#redpanda_cluster_features_enterprise_license_expiry_sec)redpanda\_cluster\_features\_enterprise\_license\_expiry\_sec Number of seconds remaining until the Enterprise Edition license expires. **Type**: gauge **Usage**: - A value of `-1` indicates that no license is present. - A value of `0` signifies an expired license. Use this metric to proactively monitor license status and trigger alerts for timely renewal. * * * ### [](#redpanda_cluster_latest_cluster_metadata_manifest_age)redpanda\_cluster\_latest\_cluster\_metadata\_manifest\_age The amount of time in seconds since the last time Redpanda uploaded metadata files to Tiered Storage for your cluster. A value of `0` indicates metadata has not yet been uploaded. When performing a whole cluster restore operation, metadata for new clusters will not include any changes made to a source cluster that is newer than this age. **Type**: gauge **Usage**: On a healthy system, this should not exceed the value set for `cloud_storage_cluster_metadata_upload_interval_ms`. You may consider setting an alert if this remains `0` for longer than 1.5 \* `cloud_storage_cluster_metadata_upload_interval_ms` as that may indicate a configuration issue. **Related topics**: - [Whole Cluster Restore](../../manage/disaster-recovery/whole-cluster-restore/) * * * ### [](#redpanda_cluster_members_backend_queued_node_operations)redpanda\_cluster\_members\_backend\_queued\_node\_operations The number of node operations queued per shard that are awaiting processing by the backend. **Type**: gauge **Labels**: - `shard` * * * ### [](#redpanda_cluster_non_homogenous_fips_mode)redpanda\_cluster\_non\_homogenous\_fips\_mode Count of brokers whose FIPS mode configuration differs from the rest of the cluster. **Type**: gauge **Usage**: Indicates inconsistencies in security configurations that might affect compliance or interoperability. * * * ### [](#redpanda_cluster_partition_moving_from_node)redpanda\_cluster\_partition\_moving\_from\_node Number of partition replicas that are in the process of being removed from a broker. **Type**: gauge **Usage**: A non-zero value can indicate ongoing or unexpected partition reassignments. Investigate if this metric remains elevated. * * * ### [](#redpanda_cluster_partition_moving_to_node)redpanda\_cluster\_partition\_moving\_to\_node Number of partition replicas in the cluster currently being added or moved to a broker. **Type**: gauge **Usage**: When this gauge is non-zero, determine whether there is an expected or unexpected reassignment of partitions causing partition replicas movement. * * * ### [](#redpanda_cluster_partition_node_cancelling_movements)redpanda\_cluster\_partition\_node\_cancelling\_movements During a partition movement cancellation operation, the number of partition replicas that were being moved that now need to be canceled. **Type**: gauge **Usage**: Track this metric to verify that partition reassignments are proceeding as expected; persistent non-zero values may warrant further investigation. * * * ### [](#redpanda_cluster_partition_num_with_broken_rack_constraint)redpanda\_cluster\_partition\_num\_with\_broken\_rack\_constraint During a partition movement cancellation operation, the number of partition replicas that were scheduled for movement but now require cancellation. **Type**: gauge **Usage**: A non-zero value may indicate issues in the partition reassignment process that need attention. * * * ### [](#redpanda_cluster_partitions)redpanda\_cluster\_partitions Total number of logical partitions managed by the cluster. This includes partitions for the controller topic but excludes replicas. **Type**: gauge * * * ### [](#redpanda_cluster_topics)redpanda\_cluster\_topics The total number of topics configured within the cluster. **Type**: gauge * * * ### [](#redpanda_cluster_unavailable_partitions)redpanda\_cluster\_unavailable\_partitions Number of partitions that are unavailable due to a lack of quorum among their replica set. **Type**: gauge **Usage**: A non-zero value indicates that some partitions do not have an active leader. Consider increasing the number of brokers or the replication factor if this persists. ## [](#debug-bundle-metrics)Debug bundle metrics ### [](#redpanda_debug_bundle_failed_generation_count)redpanda\_debug\_bundle\_failed\_generation\_count Running count of debug bundle generation failures, reported per shard. **Type**: counter **Labels**: - `shard` * * * ### [](#redpanda_debug_bundle_last_failed_bundle_timestamp_seconds)redpanda\_debug\_bundle\_last\_failed\_bundle\_timestamp\_seconds Unix epoch timestamp of the last failed debug bundle generation, per shard. **Type**: gauge **Labels**: - `shard` * * * ### [](#redpanda_debug_bundle_last_successful_bundle_timestamp_seconds)redpanda\_debug\_bundle\_last\_successful\_bundle\_timestamp\_seconds Unix epoch timestamp of the last successfully generated debug bundle, per shard. **Type**: gauge **Labels**: - `shard` * * * ### [](#redpanda_debug_bundle_successful_generation_count)redpanda\_debug\_bundle\_successful\_generation\_count Running count of successfully generated debug bundles, reported per shard. **Type**: counter **Labels**: - `shard` ## [](#iceberg-metrics)Iceberg metrics ### [](#redpanda_iceberg_rest_client_active_gets)redpanda\_iceberg\_rest\_client\_active\_gets Number of active GET requests. **Type**: gauge **Labels**: - `role` * * * ### [](#redpanda_iceberg_rest_client_active_puts)redpanda\_iceberg\_rest\_client\_active\_puts Number of active PUT requests. **Type**: gauge **Labels**: - `role` * * * ### [](#redpanda_iceberg_rest_client_active_requests)redpanda\_iceberg\_rest\_client\_active\_requests Number of active HTTP requests (includes PUT and GET). **Type**: gauge **Labels**: - `role` * * * ### [](#redpanda_iceberg_rest_client_num_commit_table_update_requests)redpanda\_iceberg\_rest\_client\_num\_commit\_table\_update\_requests Total number of requests sent to the `commit_table_update` endpoint. **Type**: counter **Labels**: - `role` * * * ### [](#redpanda_iceberg_rest_client_num_commit_table_update_requests_failed)redpanda\_iceberg\_rest\_client\_num\_commit\_table\_update\_requests\_failed Number of requests sent to the `commit_table_update` endpoint that failed. **Type**: counter **Labels**: - `role` * * * ### [](#redpanda_iceberg_rest_client_num_create_namespace_requests)redpanda\_iceberg\_rest\_client\_num\_create\_namespace\_requests Total number of requests sent to the `create_namespace` endpoint. **Type**: counter **Labels**: - `role` * * * ### [](#redpanda_iceberg_rest_client_num_create_namespace_requests_failed)redpanda\_iceberg\_rest\_client\_num\_create\_namespace\_requests\_failed Number of requests sent to the `create_namespace` endpoint that failed. **Type**: counter **Labels**: - `role` * * * ### [](#redpanda_iceberg_rest_client_num_create_table_requests)redpanda\_iceberg\_rest\_client\_num\_create\_table\_requests Total number of requests sent to the `create_table` endpoint. **Type**: counter **Labels**: - `role` * * * ### [](#redpanda_iceberg_rest_client_num_create_table_requests_failed)redpanda\_iceberg\_rest\_client\_num\_create\_table\_requests\_failed Number of requests sent to the `create_table` endpoint that failed. **Type**: counter **Labels**: - `role` * * * ### [](#redpanda_iceberg_rest_client_num_drop_table_requests)redpanda\_iceberg\_rest\_client\_num\_drop\_table\_requests Total number of requests sent to the `drop_table` endpoint. **Type**: counter **Labels**: - `role` * * * ### [](#redpanda_iceberg_rest_client_num_drop_table_requests_failed)redpanda\_iceberg\_rest\_client\_num\_drop\_table\_requests\_failed Number of requests sent to the `drop_table` endpoint that failed. **Type**: counter **Labels**: - `role` * * * ### [](#redpanda_iceberg_rest_client_num_get_config_requests)redpanda\_iceberg\_rest\_client\_num\_get\_config\_requests Total number of requests sent to the `config` endpoint. **Type**: counter **Labels**: - `role` * * * ### [](#redpanda_iceberg_rest_client_num_get_config_requests_failed)redpanda\_iceberg\_rest\_client\_num\_get\_config\_requests\_failed Number of requests sent to the `config` endpoint that failed. **Type**: counter **Labels**: - `role` * * * ### [](#redpanda_iceberg_rest_client_num_load_table_requests)redpanda\_iceberg\_rest\_client\_num\_load\_table\_requests Total number of requests sent to the `load_table` endpoint. **Type**: counter **Labels**: - `role` * * * ### [](#redpanda_iceberg_rest_client_num_load_table_requests_failed)redpanda\_iceberg\_rest\_client\_num\_load\_table\_requests\_failed Number of requests sent to the `load_table` endpoint that failed. **Type**: counter **Labels**: - `role` * * * ### [](#redpanda_iceberg_rest_client_num_oauth_token_requests)redpanda\_iceberg\_rest\_client\_num\_oauth\_token\_requests Total number of requests sent to the `oauth_token` endpoint. **Type**: counter **Labels**: - `role` * * * ### [](#redpanda_iceberg_rest_client_num_oauth_token_requests_failed)redpanda\_iceberg\_rest\_client\_num\_oauth\_token\_requests\_failed Number of requests sent to the `oauth_token` endpoint that failed. **Type**: counter **Labels**: - `role` * * * ### [](#redpanda_iceberg_rest_client_num_request_timeouts)redpanda\_iceberg\_rest\_client\_num\_request\_timeouts Total number of catalog requests that could no longer be retried because they timed out. This may occur if the catalog is not responding. **Type**: counter **Labels**: - `role` * * * ### [](#redpanda_iceberg_rest_client_num_transport_errors)redpanda\_iceberg\_rest\_client\_num\_transport\_errors Total number of transport errors (TCP and TLS). **Type**: counter **Labels**: - `role` * * * ### [](#redpanda_iceberg_rest_client_total_gets)redpanda\_iceberg\_rest\_client\_total\_gets Number of completed GET requests. **Type**: counter **Labels**: - `role` * * * ### [](#redpanda_iceberg_rest_client_total_inbound_bytes)redpanda\_iceberg\_rest\_client\_total\_inbound\_bytes Total number of bytes received from the Iceberg REST catalog. **Type**: counter **Labels**: - `role` * * * ### [](#redpanda_iceberg_rest_client_total_outbound_bytes)redpanda\_iceberg\_rest\_client\_total\_outbound\_bytes Total number of bytes sent to the Iceberg REST catalog. **Type**: counter **Labels**: - `role` * * * ### [](#redpanda_iceberg_rest_client_total_puts)redpanda\_iceberg\_rest\_client\_total\_puts Number of completed PUT requests. **Type**: counter **Labels**: - `role` * * * ### [](#redpanda_iceberg_rest_client_total_requests)redpanda\_iceberg\_rest\_client\_total\_requests Number of completed HTTP requests (includes PUT and GET). **Type**: counter **Labels**: - `role` * * * ### [](#redpanda_iceberg_translation_decompressed_bytes_processed)redpanda\_iceberg\_translation\_decompressed\_bytes\_processed Number of bytes consumed post-decompression for processing that may or may not succeed in being processed. For example, if Redpanda fails to communicate with the coordinator preventing processing of a batch, this metric still increases. **Type**: counter **Labels**: - `redpanda_namespace` - `redpanda_topic` * * * ### [](#redpanda_iceberg_translation_dlq_files_created)redpanda\_iceberg\_translation\_dlq\_files\_created Number of created Parquet files for the dead letter queue (DLQ) table. **Type**: counter **Labels**: - `redpanda_namespace` - `redpanda_topic` * * * ### [](#redpanda_iceberg_translation_files_created)redpanda\_iceberg\_translation\_files\_created Number of created Parquet files (not counting the DLQ table). **Type**: counter **Labels**: - `redpanda_namespace` - `redpanda_topic` * * * ### [](#redpanda_iceberg_translation_invalid_records)redpanda\_iceberg\_translation\_invalid\_records Number of invalid records handled by translation. **Type**: counter **Labels**: - `redpanda_cause` - `redpanda_namespace` - `redpanda_topic` * * * ### [](#redpanda_iceberg_translation_parquet_bytes_added)redpanda\_iceberg\_translation\_parquet\_bytes\_added Number of bytes in created Parquet files (not counting the DLQ table). **Type**: counter **Labels**: - `redpanda_namespace` - `redpanda_topic` * * * ### [](#redpanda_iceberg_translation_parquet_rows_added)redpanda\_iceberg\_translation\_parquet\_rows\_added Number of rows in created Parquet files (not counting the DLQ table). **Type**: counter **Labels**: - `redpanda_namespace` - `redpanda_topic` * * * ### [](#redpanda_iceberg_translation_raw_bytes_processed)redpanda\_iceberg\_translation\_raw\_bytes\_processed Number of raw, potentially compressed bytes, consumed for processing that may or may not succeed in being processed. For example, if Redpanda fails to communicate with the coordinator preventing processing of a batch, this metric still increases. **Type**: counter **Labels**: - `redpanda_namespace` - `redpanda_topic` * * * ### [](#redpanda_iceberg_translation_translations_finished)redpanda\_iceberg\_translation\_translations\_finished Number of finished translator executions. **Type**: counter **Labels**: - `redpanda_namespace` - `redpanda_topic` * * * ## [](#infrastructure-metrics)Infrastructure metrics ### [](#redpanda_cpu_busy_seconds_total)redpanda\_cpu\_busy\_seconds\_total Total time (in seconds) the CPU has been actively processing tasks. **Type**: counter **Usage**: Useful for tracking overall CPU utilization. **Labels**: - `shard` * * * ### [](#redpanda_io_queue_total_read_ops)redpanda\_io\_queue\_total\_read\_ops Cumulative count of read operations processed by the I/O queue. **Type**: counter **Labels**: - `class=("default" | "compaction" | "raft")` - `iogroup` - `mountpoint` - `shard` * * * ### [](#redpanda_io_queue_total_write_ops)redpanda\_io\_queue\_total\_write\_ops Cumulative count of write operations processed by the I/O queue. **Type**: counter **Labels**: - `class=("default" | "compaction" | "raft")` - `iogroup` - `mountpoint` - `shard` * * * ### [](#redpanda_memory_allocated_memory)redpanda\_memory\_allocated\_memory Total memory allocated (in bytes) per CPU shard. **Type**: gauge **Labels**: - `shard` **Usage**: This metric includes reclaimable memory from the batch cache. For monitoring memory pressure, consider using `redpanda_memory_available_memory` instead, which provides a more accurate picture of memory that can be immediately reallocated. * * * ### [](#redpanda_memory_available_memory)redpanda\_memory\_available\_memory Total memory (in bytes) available to a CPU shard—including both free and reclaimable memory. **Type**: gauge **Labels**: - `shard` **Usage**: This metric is more useful than `redpanda_memory_allocated_memory` for monitoring memory pressure, as it accounts for reclaimable memory in the batch cache. A low value indicates the system is approaching memory exhaustion. * * * ### [](#redpanda_memory_available_memory_low_water_mark)redpanda\_memory\_available\_memory\_low\_water\_mark The lowest recorded available memory (in bytes) per CPU shard since the process started. **Type**: gauge **Labels**: - `shard` **Usage**: This metric helps identify the closest the system has come to memory exhaustion. Useful for capacity planning and understanding historical memory pressure patterns. * * * ### [](#redpanda_memory_free_memory)redpanda\_memory\_free\_memory Total unallocated (free) memory in bytes available for each CPU shard. **Type**: gauge **Labels**: - `shard` * * * ### [](#redpanda_rpc_active_connections)redpanda\_rpc\_active\_connections Current number of active RPC client connections on a shard. **Type**: gauge **Labels**: - `redpanda_server=("kafka" | "internal")` * * * ### [](#redpanda_rpc_received_bytes)redpanda\_rpc\_received\_bytes Number of bytes received from the clients in valid requests. The `redpanda_server` label supports the following options for this metric: - `kafka`: Data sent over the Kafka API - `internal`: Inter-broker traffic **Type**: counter **Labels**: - `redpanda_server` * * * ### [](#redpanda_rpc_request_errors_total)redpanda\_rpc\_request\_errors\_total Cumulative count of RPC errors encountered, segmented by server type. **Type**: counter **Labels**: - `redpanda_server=("kafka" | "internal")` **Usage**: Use this metric to diagnose potential issues in RPC communication. * * * ### [](#redpanda_rpc_request_latency_seconds)redpanda\_rpc\_request\_latency\_seconds Histogram capturing the latency (in seconds) for RPC requests. **Type**: histogram **Labels**: - `redpanda_server=("kafka" | "internal")` * * * ### [](#redpanda_rpc_sent_bytes)redpanda\_rpc\_sent\_bytes Number of bytes sent to clients. The `redpanda_server` label supports the following options for this metric: - `kafka`: Data sent over the Kafka API - `internal`: Inter-broker traffic **Type**: counter **Labels**: - `redpanda_server` * * * ### [](#redpanda_scheduler_runtime_seconds_total)redpanda\_scheduler\_runtime\_seconds\_total Total accumulated runtime (in seconds) for the task queue associated with each scheduling group per shard. **Type**: counter **Labels**: - `redpanda_scheduling_group=("admin" | "archival_upload" | "cache_background_reclaim" | "cluster" | "coproc" | "kafka" | "log_compaction" | "main" | "node_status" | "raft" | "raft_learner_recovery")` - `shard` * * * ### [](#redpanda_storage_cache_disk_free_bytes)redpanda\_storage\_cache\_disk\_free\_bytes Amount of free disk space (in bytes) available on the cache storage. **Type**: gauge **Usage**: Monitor this to ensure sufficient cache storage capacity. * * * ### [](#redpanda_storage_cache_disk_free_space_alert)redpanda\_storage\_cache\_disk\_free\_space\_alert Alert indicator for cache storage free space, where: - `0` = OK - `1` = Low space - `2` = Degraded **Type**: gauge * * * ### [](#redpanda_storage_cache_disk_total_bytes)redpanda\_storage\_cache\_disk\_total\_bytes Total size of attached storage, in bytes. **Type**: gauge * * * ### [](#redpanda_storage_disk_free_bytes)redpanda\_storage\_disk\_free\_bytes Amount of free disk space (in bytes) available on attached storage. **Type**: gauge ### [](#redpanda_storage_disk_free_space_alert)redpanda\_storage\_disk\_free\_space\_alert Alert indicator for overall disk storage free space, where: - `0` = OK - `1` = Low space - `2` = Degraded **Type**: gauge * * * ### [](#redpanda_storage_disk_total_bytes)redpanda\_storage\_disk\_total\_bytes Total capacity (in bytes) of the attached storage. **Type**: gauge * * * ### [](#redpanda_uptime_seconds_total)redpanda\_uptime\_seconds\_total Total system uptime (in seconds) representing the overall CPU runtime. **Type**: gauge ## [](#raft-metrics)Raft metrics ### [](#redpanda_node_status_rpcs_received)redpanda\_node\_status\_rpcs\_received Total count of node status RPCs received by a broker. **Type**: gauge * * * ### [](#redpanda_node_status_rpcs_sent)redpanda\_node\_status\_rpcs\_sent Total count of node status RPCs sent by a broker. **Type**: gauge * * * ### [](#redpanda_node_status_rpcs_timed_out)redpanda\_node\_status\_rpcs\_timed\_out Total count of node status RPCs that timed out on a broker. **Type**: gauge ## [](#redpanda-connect-metrics)Redpanda Connect metrics ### [](#input_connection_failed)input\_connection\_failed Number of input connections to the Redpanda Connect pipeline that have failed. **Type**: counter * * * ### [](#input_connection_lost)input\_connection\_lost Number of times a connection to the upstream system is lost in a Redpanda Connect pipeline. **Type**: counter * * * ### [](#input_connection_up)input\_connection\_up Number of active input connections to the Redpanda Connect pipeline. **Type**: counter * * * ### [](#input_latency_ns)input\_latency\_ns Input latency for the Redpanda Connect pipeline. **Type**: summary * * * ### [](#input_received)input\_received Number of records received by the Redpanda Connect pipeline. **Type**: counter * * * ### [](#output_batch_sent)output\_batch\_sent Number of batches produced by the Redpanda Connect pipeline. **Type**: counter * * * ### [](#output_connection_failed)output\_connection\_failed Number of output connections from the Redpanda Connect pipeline that have failed. **Type**: counter * * * ### [](#output_connection_lost)output\_connection\_lost Number of times the connection to the downstream system is lost in a Redpanda Connect pipeline. **Type**: counter * * * ### [](#output_connection_up)output\_connection\_up Number of active output connections from the Redpanda Connect pipeline. **Type**: counter * * * ### [](#output_error)output\_error Number of errors encountered in the Redpanda Connect pipeline output. **Type**: counter * * * ### [](#output_latency_ns)output\_latency\_ns Output latency for the Redpanda Connect pipeline. **Type**: summary * * * ### [](#output_sent)output\_sent Records sent by the Redpanda Connect pipeline. **Type**: counter * * * ### [](#processor_batch_received)processor\_batch\_received Number of record batches received as input in a Redpanda Connect pipeline processor. **Type**: counter * * * ### [](#processor_batch_sent)processor\_batch\_sent Number of record batches produced as output by a Redpanda Connect pipeline processor. **Type**: counter * * * ### [](#processor_error)processor\_error Number of errors encountered by a Redpanda Connect pipeline processor. **Type**: counter * * * ### [](#processor_latency_ns)processor\_latency\_ns Processing time in nanoseconds of a Redpanda Connect pipeline processor. **Type**: summary * * * ### [](#processor_received)processor\_received Number of records received as input in a Redpanda Connect pipeline processor. **Type**: counter * * * ### [](#processor_sent)processor\_sent Number of records produced as output by a Redpanda Connect pipeline processor. **Type**: counter ## [](#service-metrics)Service metrics ### [](#redpanda_authorization_result)redpanda\_authorization\_result Cumulative count of authorization results, categorized by result type. **Type**: counter **Labels**: - `type` * * * ### [](#redpanda_kafka_rpc_sasl_session_expiration_total)redpanda\_kafka\_rpc\_sasl\_session\_expiration\_total Total number of SASL session expirations observed. **Type**: counter * * * ### [](#redpanda_kafka_rpc_sasl_session_reauth_attempts_total)redpanda\_kafka\_rpc\_sasl\_session\_reauth\_attempts\_total Total number of SASL reauthentication attempts made by clients. **Type**: counter * * * ### [](#redpanda_kafka_rpc_sasl_session_revoked_total)redpanda\_kafka\_rpc\_sasl\_session\_revoked\_total Total number of SASL sessions that have been revoked. **Type**: counter * * * ### [](#redpanda_rest_proxy_request_latency_seconds)redpanda\_rest\_proxy\_request\_latency\_seconds Histogram capturing the latency (in seconds) for REST proxy requests. The measurement includes waiting for resource availability, processing, and response dispatch. **Type**: histogram * * * ### [](#redpanda_schema_registry_cache_schema_count)redpanda\_schema\_registry\_cache\_schema\_count Total number of schemas currently stored in the Schema Registry cache. **Type**: gauge * * * ### [](#redpanda_schema_registry_cache_schema_memory_bytes)redpanda\_schema\_registry\_cache\_schema\_memory\_bytes Memory usage (in bytes) by schemas stored in the Schema Registry cache. **Type**: gauge * * * ### [](#redpanda_schema_registry_cache_subject_count)redpanda\_schema\_registry\_cache\_subject\_count Count of subjects stored in the Schema Registry cache. **Type**: gauge **Labels**: - `deleted` * * * ### [](#redpanda_schema_registry_cache_subject_version_count)redpanda\_schema\_registry\_cache\_subject\_version\_count Count of versions available for each subject in the Schema Registry cache. **Type**: gauge **Labels**: - `deleted` - `subject` * * * ### [](#redpanda_schema_registry_inflight_requests_memory_usage_ratio)redpanda\_schema\_registry\_inflight\_requests\_memory\_usage\_ratio Ratio of memory used by in-flight requests in the Schema Registry, reported per shard. **Type**: gauge **Labels**: - `shard` * * * ### [](#redpanda_schema_registry_inflight_requests_usage_ratio)redpanda\_schema\_registry\_inflight\_requests\_usage\_ratio Usage ratio for in-flight Schema Registry requests, reported per shard. **Type**: gauge **Labels**: - `shard` * * * ### [](#redpanda_schema_registry_queued_requests_memory_blocked)redpanda\_schema\_registry\_queued\_requests\_memory\_blocked Count of Schema Registry requests queued due to memory constraints, reported per shard. **Type**: gauge **Labels**: - `shard` * * * ### [](#redpanda_schema_registry_request_errors_total)redpanda\_schema\_registry\_request\_errors\_total Total number of errors encountered by the Schema Registry, categorized by status code. **Type**: counter **Labels**: - `redpanda_status=("5xx" | "4xx" | "3xx")` * * * ### [](#redpanda_schema_registry_request_latency_seconds)redpanda\_schema\_registry\_request\_latency\_seconds Histogram capturing the latency (in seconds) for Schema Registry requests. **Type**: histogram ## [](#partition-metrics)Partition metrics ### [](#redpanda_kafka_max_offset)redpanda\_kafka\_max\_offset High watermark offset for a partition, used to calculate consumer group lag. **Type**: gauge **Labels**: - `redpanda_namespace` - `redpanda_partition` - `redpanda_topic` **Related topics**: - [Consumer group lag](../../manage/monitoring/#consumer-group-lag) * * * ### [](#redpanda_kafka_request_bytes_total)redpanda\_kafka\_request\_bytes\_total Total number of bytes read from or written to the partitions of a topic. The total may include fetched bytes that are not returned to the client. **Type**: counter **Labels**: - `redpanda_namespace` - `redpanda_topic` - `redpanda_request=("produce" | "consume")` * * * ### [](#redpanda_kafka_under_replicated_replicas)redpanda\_kafka\_under\_replicated\_replicas Number of partition replicas that are live yet lag behind the latest offset, [redpanda\_kafka\_max\_offset](#redpanda_kafka_max_offset). **Type**: gauge **Labels**: - `redpanda_namespace` - `redpanda_partition` - `redpanda_topic` * * * ### [](#redpanda_raft_leadership_changes)redpanda\_raft\_leadership\_changes Total count of leadership changes (such as successful leader elections) across all partitions for a given topic. **Type**: counter **Labels**: - `redpanda_namespace` - `redpanda_topic` * * * ### [](#redpanda_raft_learners_gap_bytes)redpanda\_raft\_learners\_gap\_bytes Total number of bytes that must be delivered to learner replicas to bring them up to date. **Type**: gauge **Labels**: - `shard` * * * ### [](#redpanda_raft_recovery_offsets_pending)redpanda\_raft\_recovery\_offsets\_pending Sum of offsets across partitions on a broker that still need to be recovered. **Type**: gauge * * * ### [](#redpanda_raft_recovery_partition_movement_available_bandwidth)redpanda\_raft\_recovery\_partition\_movement\_available\_bandwidth Available network bandwidth (in bytes per second) for partition movement operations. **Type**: gauge **Labels**: - `shard` * * * ### [](#redpanda_raft_recovery_partition_movement_consumed_bandwidth)redpanda\_raft\_recovery\_partition\_movement\_consumed\_bandwidth Network bandwidth (in bytes per second) currently being consumed for partition movement. **Type**: gauge **Labels**: - `shard` * * * ### [](#redpanda_raft_recovery_partitions_active)redpanda\_raft\_recovery\_partitions\_active Number of partition replicas currently undergoing recovery on a broker. **Type**: gauge * * * ### [](#redpanda_raft_recovery_partitions_to_recover)redpanda\_raft\_recovery\_partitions\_to\_recover Total count of partition replicas that are pending recovery on a broker. **Type**: gauge ## [](#topic-metrics)Topic metrics ### [](#redpanda_cluster_partition_schema_id_validation_records_failed)redpanda\_cluster\_partition\_schema\_id\_validation\_records\_failed Count of records that failed schema ID validation during ingestion. **Type**: counter * * * ### [](#redpanda_kafka_partitions)redpanda\_kafka\_partitions Configured number of partitions for a topic. **Type**: gauge **Labels**: - `redpanda_namespace` - `redpanda_topic` * * * ### [](#redpanda_kafka_records_fetched_total)redpanda\_kafka\_records\_fetched\_total Total number of records fetched from a topic. **Type**: counter **Labels**: - `redpanda_namespace` - `redpanda_topic` * * * ### [](#redpanda_kafka_records_produced_total)redpanda\_kafka\_records\_produced\_total Total number of records produced to a topic. **Type**: counter **Labels**: - `redpanda_namespace` - `redpanda_topic` * * * ### [](#redpanda_kafka_replicas)redpanda\_kafka\_replicas Configured number of replicas for a topic. **Type**: gauge **Labels**: - `redpanda_namespace` - `redpanda_topic` * * * ### [](#redpanda_security_audit_errors_total)redpanda\_security\_audit\_errors\_total Cumulative count of errors encountered when creating or publishing audit event log entries. **Type**: counter * * * ### [](#redpanda_security_audit_last_event_timestamp_seconds)redpanda\_security\_audit\_last\_event\_timestamp\_seconds Unix epoch timestamp of the last successful audit log event publication. **Type**: counter ## [](#broker-metrics)Broker metrics ### [](#redpanda_kafka_handler_latency_seconds)redpanda\_kafka\_handler\_latency\_seconds Histogram capturing the latency for processing Kafka requests at the broker level. **Type**: histogram * * * ### [](#redpanda_kafka_request_latency_seconds)redpanda\_kafka\_request\_latency\_seconds Histogram capturing the latency (in seconds) for produce/consume requests at the broker. This duration spans from request initiation to response fulfillment. **Type**: histogram **Labels**: - `redpanda_request=("produce" | "consume")` * * * ### [](#redpanda_kafka_quotas_client_quota_throttle_time)redpanda\_kafka\_quotas\_client\_quota\_throttle\_time Histogram of client quota throttling delays (in seconds) per quota rule and type. **Type**: histogram **Labels**: - `quota_rule=("not_applicable" | "kafka_client_default" | "cluster_client_default" | "kafka_client_prefix" | "cluster_client_prefix" | "kafka_client_id")` - `quota_type=("produce_quota" | "fetch_quota" | "partition_mutation_quota")` * * * ### [](#redpanda_kafka_quotas_client_quota_throughput)redpanda\_kafka\_quotas\_client\_quota\_throughput Histogram of client quota throughput per quota rule and type. **Type**: histogram **Labels**: - `quota_rule=("not_applicable" | "kafka_client_default" | "cluster_client_default" | "kafka_client_prefix" | "cluster_client_prefix" | "kafka_client_id")` - `quota_type=("produce_quota" | "fetch_quota" | "partition_mutation_quota")` ## [](#consumer-group-metrics)Consumer group metrics ### [](#redpanda_kafka_consumer_group_committed_offset)redpanda\_kafka\_consumer\_group\_committed\_offset Committed offset for a consumer group, segmented by topic and partition. To enable this metric, you must include the `partition` option in the [`enable_consumer_group_metrics`](../properties/cluster-properties/#enable_consumer_group_metrics) cluster property. **Type**: gauge **Labels**: - `redpanda_group` - `redpanda_partition` - `redpanda_topic` - `shard` * * * ### [](#redpanda_kafka_consumer_group_consumers)redpanda\_kafka\_consumer\_group\_consumers Number of active consumers within a consumer group. To enable this metric, you must include the `group` option in the [`enable_consumer_group_metrics`](../properties/cluster-properties/#enable_consumer_group_metrics) cluster property. **Type**: gauge **Labels**: - `redpanda_group` - `shard` * * * ### [](#redpanda_kafka_consumer_group_lag_max)redpanda\_kafka\_consumer\_group\_lag\_max Maximum consumer group lag across topic partitions. This metric is useful for identifying the most delayed partition in the consumer group. To enable this metric, you must include the `consumer_lag` option in the [`enable_consumer_group_metrics`](../properties/cluster-properties/#enable_consumer_group_metrics) cluster property. **Type**: gauge **Labels**: - `redpanda_group` **Related topics**: - [Consumer group lag](../../manage/monitoring/#consumer-group-lag) * * * ### [](#redpanda_kafka_consumer_group_lag_sum)redpanda\_kafka\_consumer\_group\_lag\_sum Sum of consumer group lag for all topic partitions. This metric is useful for tracking the total lag across all partitions. To enable this metric, you must include the `consumer_lag` option in the [`enable_consumer_group_metrics`](../properties/cluster-properties/#enable_consumer_group_metrics) cluster property. **Type**: gauge **Labels**: - `redpanda_group` **Related topics**: - [Consumer group lag](../../manage/monitoring/#consumer-group-lag) * * * ### [](#redpanda_kafka_consumer_group_topics)redpanda\_kafka\_consumer\_group\_topics Number of topics being consumed by a consumer group. To enable this metric, you must include the `group` option in the [`enable_consumer_group_metrics`](../properties/cluster-properties/#enable_consumer_group_metrics) cluster property. **Type**: gauge **Labels**: - `redpanda_group` - `shard` ## [](#rest-proxy-metrics)REST proxy metrics ### [](#redpanda_rest_proxy_inflight_requests_memory_usage_ratio)redpanda\_rest\_proxy\_inflight\_requests\_memory\_usage\_ratio Ratio of memory used by in-flight REST proxy requests, measured per shard. **Type**: gauge **Labels**: - `shard` * * * ### [](#redpanda_rest_proxy_inflight_requests_usage_ratio)redpanda\_rest\_proxy\_inflight\_requests\_usage\_ratio Usage ratio for in-flight REST proxy requests, measured per shard. **Type**: gauge **Labels**: - `shard` * * * ### [](#redpanda_rest_proxy_queued_requests_memory_blocked)redpanda\_rest\_proxy\_queued\_requests\_memory\_blocked Count of REST proxy requests queued due to memory limitations, measured per shard. **Type**: gauge **Labels**: - `shard` * * * ### [](#redpanda_rest_proxy_request_errors_total)redpanda\_rest\_proxy\_request\_errors\_total Cumulative count of REST proxy errors, categorized by HTTP status code. **Type**: counter **Labels**: - `redpanda_status("5xx" | "4xx" | "3xx")` * * * ### [](#redpanda_rest_proxy_request_latency_seconds_bucket)redpanda\_rest\_proxy\_request\_latency\_seconds\_bucket Histogram representing the internal latency buckets for REST proxy requests. **Type**: histogram ## [](#application-metrics)Application metrics ### [](#redpanda_application_build)redpanda\_application\_build Build information for Redpanda, including the revision and version details. **Type**: gauge **Labels**: - `redpanda_revision` - `redpanda_version` * * * ### [](#redpanda_application_fips_mode)redpanda\_application\_fips\_mode Indicates whether Redpanda is running in FIPS mode. Possible values: - `0` = disabled - `1` = permissive - `2` = enabled **Type**: gauge * * * ### [](#redpanda_application_uptime_seconds_total)redpanda\_application\_uptime\_seconds\_total Total runtime (in seconds) of the Redpanda application. **Type**: gauge ## [](#cloud-metrics)Cloud metrics ### [](#redpanda_cloud_client_backoff)redpanda\_cloud\_client\_backoff Total number of object storage requests that experienced backoff delays. **Type**: counter **Labels**: - For S3 and GCP: - `redpanda_endpoint` - `redpanda_region` - For Azure Blob Storage (ABS): - `redpanda_endpoint` - `redpanda_storage_account` * * * ### [](#redpanda_cloud_client_client_pool_utilization)redpanda\_cloud\_client\_client\_pool\_utilization Utilization of the object storage pool(0 - unused, 100 - fully utilized). **Type**: gauge **Labels**: - `redpanda_endpoint` - `redpanda_region` - `shard` * * * ### [](#redpanda_cloud_client_download_backoff)redpanda\_cloud\_client\_download\_backoff Total number of object storage download requests that experienced backoff delays. **Type**: counter **Labels**: - For S3 and GCP: - `redpanda_endpoint` - `redpanda_region` - For Azure Blob Storage (ABS): - `redpanda_endpoint` - `redpanda_storage_account` * * * ### [](#redpanda_cloud_client_downloads)redpanda\_cloud\_client\_downloads Total number of successful download requests from object storage. **Type**: counter **Labels**: - For S3 and GCP: - `redpanda_endpoint` - `redpanda_region` - For Azure Blob Storage (ABS): - `redpanda_endpoint` - `redpanda_storage_account` * * * ### [](#redpanda_cloud_client_lease_duration)redpanda\_cloud\_client\_lease\_duration Histogram representing the lease duration for object storage clients. **Type**: histogram * * * ### [](#redpanda_cloud_client_not_found)redpanda\_cloud\_client\_not\_found Total number of object storage requests that resulted in a "not found" error. **Type**: counter **Labels**: - For S3 and GCP: - `redpanda_endpoint` - `redpanda_region` - For Azure Blob Storage (ABS): - `redpanda_endpoint` - `redpanda_storage_account` * * * ### [](#redpanda_cloud_client_num_borrows)redpanda\_cloud\_client\_num\_borrows Count of instances where a shard borrowed a object storage client from another shard. **Type**: counter **Labels**: - `redpanda_endpoint` - `redpanda_region` - `shard` * * * ### [](#redpanda_cloud_client_upload_backoff)redpanda\_cloud\_client\_upload\_backoff Total number of object storage upload requests that experienced backoff delays. **Type**: counter **Labels**: - For S3 and GCP: - `redpanda_endpoint` - `redpanda_region` - For Azure Blob Storage (ABS): - `redpanda_endpoint` - `redpanda_storage_account` * * * ### [](#redpanda_cloud_client_uploads)redpanda\_cloud\_client\_uploads Total number of successful upload requests to object storage. **Type**: counter **Labels**: - For S3 and GCP: - `redpanda_endpoint` - `redpanda_region` - For Azure Blob Storage (ABS): - `redpanda_endpoint` - `redpanda_storage_account` * * * ## [](#tls_metrics)TLS metrics ### [](#redpanda_tls_certificate_expires_at_timestamp_seconds)redpanda\_tls\_certificate\_expires\_at\_timestamp\_seconds Unix epoch timestamp for the expiration of the shortest-lived installed TLS certificate. **Type**: gauge **Labels**: - `area` - `detail` **Usage**: Useful for proactive certificate renewal by indicating the next certificate set to expire. * * * ### [](#redpanda_tls_certificate_serial)redpanda\_tls\_certificate\_serial The least significant 4 bytes of the serial number for the certificate that will expire next. **Type**: gauge **Labels**: - `area` - `detail` **Usage**: Provides a quick reference to identify the certificate in question. * * * ### [](#redpanda_tls_certificate_valid)redpanda\_tls\_certificate\_valid Indicator of whether a resource has at least one valid TLS certificate installed. Returns `1` if a valid certificate is present and `0` if not. **Type**: gauge **Labels**: - `area` - `detail` **Usage**: Aids in continuous monitoring of certificate validity across resources. * * * ### [](#redpanda_tls_loaded_at_timestamp_seconds)redpanda\_tls\_loaded\_at\_timestamp\_seconds Unix epoch timestamp marking the last time a TLS certificate was loaded for a resource. **Type**: gauge **Labels**: - `area` - `detail` **Usage**: Indicates recent certificate updates across resources. * * * ### [](#redpanda_tls_truststore_expires_at_timestamp_seconds)redpanda\_tls\_truststore\_expires\_at\_timestamp\_seconds Unix epoch timestamp representing the expiration time of the shortest-lived certificate authority (CA) in the installed truststore. **Type**: gauge **Labels**: - `area` - `detail` **Usage**: Helps identify when any CA in the chain is nearing expiration. * * * ### [](#redpanda_trust_file_crc32c)redpanda\_trust\_file\_crc32c CRC32C checksum calculated from the contents of the trust file. This value is calculated when a valid certificate is loaded and a trust store is present. Otherwise, the value is zero. **Type**: gauge **Labels**: - `area` - `detail` - `shard` * * * ### [](#redpanda_truststore_expires_at_timestamp_seconds)redpanda\_truststore\_expires\_at\_timestamp\_seconds Expiry time of the shortest-lived CA in the truststore, measured in seconds since epoch. **Type**: gauge **Labels**: - `area` - `detail` - `shard` * * * ## [](#data_transform_metrics)Data transforms metrics ### [](#redpanda_transform_execution_errors)redpanda\_transform\_execution\_errors Counter for the number of errors encountered during the invocation of data transforms. **Type**: counter **Labels**: - `function_name` * * * ### [](#redpanda_transform_execution_latency_sec)redpanda\_transform\_execution\_latency\_sec Histogram tracking the execution latency (in seconds) for processing a single record using data transforms. **Type**: histogram **Labels**: - `function_name` * * * ### [](#redpanda_transform_failures)redpanda\_transform\_failures Counter for each failure encountered by a data transform processor. **Type**: counter **Labels**: - `function_name` * * * ### [](#redpanda_transform_processor_lag)redpanda\_transform\_processor\_lag Number of records pending processing in the input topic for a data transform. **Type**: gauge **Labels**: - `function_name` * * * ### [](#redpanda_transform_read_bytes)redpanda\_transform\_read\_bytes Cumulative count of bytes read as input to data transforms. **Type**: counter **Labels**: - `function_name` * * * ### [](#redpanda_transform_state)redpanda\_transform\_state Current count of transform processors in a specific state (running, inactive, or errored). **Type**: gauge **Labels**: - `function_name` - `state=("running" | "inactive" | "errored")` * * * ### [](#redpanda_transform_write_bytes)redpanda\_transform\_write\_bytes Cumulative count of bytes output from data transforms. **Type**: counter **Labels**: - `function_name` * * * ### [](#redpanda_wasm_binary_executable_memory_usage)redpanda\_wasm\_binary\_executable\_memory\_usage Number of bytes (memory) used by executable WebAssembly binaries. **Type**: gauge * * * ### [](#redpanda_wasm_engine_cpu_seconds_total)redpanda\_wasm\_engine\_cpu\_seconds\_total Total CPU time (in seconds) consumed by WebAssembly functions. **Type**: counter **Labels**: - `function_name` * * * ### [](#redpanda_wasm_engine_max_memory)redpanda\_wasm\_engine\_max\_memory Maximum allowed memory (in bytes) allocated for a WebAssembly function. **Type**: gauge **Labels**: - `function_name` * * * ### [](#redpanda_wasm_engine_memory_usage)redpanda\_wasm\_engine\_memory\_usage Current memory usage (in bytes) by a WebAssembly function. **Type**: gauge **Labels**: - `function_name` ## [](#object-storage-metrics)Object storage metrics > 📝 **NOTE** > > Object storage metrics are available only if you have: > > - [Tiered Storage](../../manage/tiered-storage/) enabled > > - The cluster property [cloud\_storage\_enabled](../properties/object-storage-properties/#cloud_storage_enabled) set to `true` ### [](#redpanda_cloud_storage_active_segments)redpanda\_cloud\_storage\_active\_segments Number of remote log segments that are currently hydrated and available for read operations. **Type**: gauge * * * ### [](#redpanda_cloud_storage_anomalies)redpanda\_cloud\_storage\_anomalies Count of missing partition manifest anomalies detected for the topic. **Type**: gauge * * * ### [](#redpanda_cloud_storage_cache_op_hit)redpanda\_cloud\_storage\_cache\_op\_hit Total number of successful get requests that found the requested object in the cache. **Type**: counter * * * ### [](#redpanda_cloud_storage_cache_op_in_progress_files)redpanda\_cloud\_storage\_cache\_op\_in\_progress\_files Number of files currently being written to the cache. **Type**: gauge * * * ### [](#redpanda_cloud_storage_cache_op_miss)redpanda\_cloud\_storage\_cache\_op\_miss Total count of get requests that did not find the requested object in the cache. **Type**: counter * * * ### [](#redpanda_cloud_storage_cache_op_put)redpanda\_cloud\_storage\_cache\_op\_put Total number of objects successfully written into the cache. **Type**: counter * * * ### [](#redpanda_cloud_storage_cache_space_files)redpanda\_cloud\_storage\_cache\_space\_files Current number of objects stored in the cache. **Type**: gauge * * * ### [](#redpanda_cloud_storage_cache_space_hwm_files)redpanda\_cloud\_storage\_cache\_space\_hwm\_files High watermark for the number of objects stored in the cache. **Type**: gauge * * * ### [](#redpanda_cloud_storage_cache_space_hwm_size_bytes)redpanda\_cloud\_storage\_cache\_space\_hwm\_size\_bytes High watermark for the total size (in bytes) of cached objects. **Type**: gauge * * * ### [](#redpanda_cloud_storage_cache_space_size_bytes)redpanda\_cloud\_storage\_cache\_space\_size\_bytes Total size (in bytes) of objects currently stored in the cache. **Type**: gauge * * * ### [](#redpanda_cloud_storage_cache_space_tracker_size)redpanda\_cloud\_storage\_cache\_space\_tracker\_size Current count of entries in the cache access tracker. **Type**: gauge * * * ### [](#redpanda_cloud_storage_cache_space_tracker_syncs)redpanda\_cloud\_storage\_cache\_space\_tracker\_syncs Total number of times the cache access tracker was synchronized with disk data. **Type**: counter * * * ### [](#redpanda_cloud_storage_cache_trim_carryover_trims)redpanda\_cloud\_storage\_cache\_trim\_carryover\_trims Count of times the cache trim operation was invoked using a carryover strategy. **Type**: counter * * * ### [](#redpanda_cloud_storage_cache_trim_exhaustive_trims)redpanda\_cloud\_storage\_cache\_trim\_exhaustive\_trims Count of instances where a fast cache trim was insufficient and an exhaustive trim was required. **Type**: counter * * * ### [](#redpanda_cloud_storage_cache_trim_failed_trims)redpanda\_cloud\_storage\_cache\_trim\_failed\_trims Count of cache trim operations that failed to free the expected amount of space, possibly indicating a bug or misconfiguration. **Type**: counter * * * ### [](#redpanda_cloud_storage_cache_trim_fast_trims)redpanda\_cloud\_storage\_cache\_trim\_fast\_trims Count of successful fast cache trim operations. **Type**: counter * * * ### [](#redpanda_cloud_storage_cache_trim_in_mem_trims)redpanda\_cloud\_storage\_cache\_trim\_in\_mem\_trims Count of cache trim operations performed using the in-memory access tracker. **Type**: counter * * * ### [](#redpanda_cloud_storage_cloud_log_size)redpanda\_cloud\_storage\_cloud\_log\_size Total size (in bytes) of user-visible log data stored in Tiered Storage. This value increases with every segment offload and decreases when segments are deleted due to retention or compaction. **Type**: gauge **Usage**: Segmented by `redpanda_namespace` (e.g., `kafka`, `kafka_internal`, or `redpanda`), `redpanda_topic`, and `redpanda_partition`. * * * ### [](#redpanda_cloud_storage_deleted_segments)redpanda\_cloud\_storage\_deleted\_segments Count of log segments that have been deleted from object storage due to retention policies or compaction processes. **Type**: counter * * * ### [](#redpanda_cloud_storage_errors_total)redpanda\_cloud\_storage\_errors\_total Cumulative count of errors encountered during object storage operations, segmented by direction. **Type**: counter **Labels**: - `redpanda_direction` * * * ### [](#redpanda_cloud_storage_housekeeping_drains)redpanda\_cloud\_storage\_housekeeping\_drains Count of times the object storage upload housekeeping queue was fully drained. **Type**: gauge * * * ### [](#redpanda_cloud_storage_housekeeping_jobs_completed)redpanda\_cloud\_storage\_housekeeping\_jobs\_completed Total number of successfully executed object storage housekeeping jobs. **Type**: counter * * * ### [](#redpanda_cloud_storage_housekeeping_jobs_failed)redpanda\_cloud\_storage\_housekeeping\_jobs\_failed Total number of object storage housekeeping jobs that failed. **Type**: counter * * * ### [](#redpanda_cloud_storage_housekeeping_jobs_skipped)redpanda\_cloud\_storage\_housekeeping\_jobs\_skipped Count of object storage housekeeping jobs that were skipped during execution. **Type**: counter * * * ### [](#redpanda_cloud_storage_housekeeping_pauses)redpanda\_cloud\_storage\_housekeeping\_pauses Count of times object storage upload housekeeping was paused. **Type**: gauge * * * ### [](#redpanda_cloud_storage_housekeeping_requests_throttled_average_rate)redpanda\_cloud\_storage\_housekeeping\_requests\_throttled\_average\_rate Average rate (per shard) of requests that were throttled during object storage operations. **Type**: gauge * * * ### [](#redpanda_cloud_storage_housekeeping_resumes)redpanda\_cloud\_storage\_housekeeping\_resumes Count of instances when object storage upload housekeeping resumed after a pause. **Type**: gauge * * * ### [](#redpanda_cloud_storage_housekeeping_rounds)redpanda\_cloud\_storage\_housekeeping\_rounds Total number of rounds executed by the object storage upload housekeeping process. **Type**: counter * * * ### [](#redpanda_cloud_storage_jobs_cloud_segment_reuploads)redpanda\_cloud\_storage\_jobs\_cloud\_segment\_reuploads Count of log segments reuploaded from object storage sources (either from the cache or via direct download). **Type**: gauge * * * ### [](#redpanda_cloud_storage_jobs_local_segment_reuploads)redpanda\_cloud\_storage\_jobs\_local\_segment\_reuploads Count of log segments reuploaded from the local data directory. **Type**: gauge * * * ### [](#redpanda_cloud_storage_jobs_manifest_reuploads)redpanda\_cloud\_storage\_jobs\_manifest\_reuploads Total number of partition manifest reuploads performed by housekeeping jobs. **Type**: gauge * * * ### [](#redpanda_cloud_storage_jobs_metadata_syncs)redpanda\_cloud\_storage\_jobs\_metadata\_syncs Total number of archival configuration updates (metadata synchronizations) executed by housekeeping jobs. **Type**: gauge * * * ### [](#redpanda_cloud_storage_jobs_segment_deletions)redpanda\_cloud\_storage\_jobs\_segment\_deletions Total count of log segments deleted by housekeeping jobs. **Type**: gauge * * * ### [](#redpanda_cloud_storage_limits_downloads_throttled_sum)redpanda\_cloud\_storage\_limits\_downloads\_throttled\_sum Total cumulative time (in milliseconds) during which downloads were throttled. **Type**: counter * * * ### [](#redpanda_cloud_storage_partition_manifest_uploads_total)redpanda\_cloud\_storage\_partition\_manifest\_uploads\_total Total number of successful partition manifest uploads to object storage. **Type**: counter * * * ### [](#redpanda_cloud_storage_partition_readers)redpanda\_cloud\_storage\_partition\_readers Number of active partition reader instances (fetch/timequery operations) reading from Tiered Storage. **Type**: gauge * * * ### [](#redpanda_cloud_storage_partition_readers_delayed)redpanda\_cloud\_storage\_partition\_readers\_delayed Count of partition read operations delayed due to reaching the reader limit, suggesting potential saturation of Tiered Storage reads. **Type**: counter * * * ### [](#redpanda_cloud_storage_paused_archivers)redpanda\_cloud\_storage\_paused\_archivers Number of paused archivers. **Type**: gauge **Labels**: - `redpanda_namespace` - `redpanda_topic` * * * ### [](#redpanda_cloud_storage_readers)redpanda\_cloud\_storage\_readers Total number of segment read cursors for hydrated remote log segments. **Type**: gauge * * * ### [](#redpanda_cloud_storage_segment_index_uploads_total)redpanda\_cloud\_storage\_segment\_index\_uploads\_total Total number of successful segment index uploads to object storage. **Type**: counter * * * ### [](#redpanda_cloud_storage_segment_materializations_delayed)redpanda\_cloud\_storage\_segment\_materializations\_delayed Count of segment materialization operations that were delayed because of reader limit constraints. **Type**: counter * * * ### [](#redpanda_cloud_storage_segment_readers_delayed)redpanda\_cloud\_storage\_segment\_readers\_delayed Count of segment reader operations delayed due to reaching the reader limit. This indicates a cluster is saturated with Tiered Storage reads. **Type**: counter * * * ### [](#redpanda_cloud_storage_segment_uploads_total)redpanda\_cloud\_storage\_segment\_uploads\_total Total number of successful data segment uploads to object storage. **Type**: counter * * * ### [](#redpanda_cloud_storage_segments)redpanda\_cloud\_storage\_segments Total number of log segments accounted for in object storage for the topic. **Type**: gauge **Labels**: - `redpanda_namespace` - `redpanda_topic` * * * ### [](#redpanda_cloud_storage_segments_pending_deletion)redpanda\_cloud\_storage\_segments\_pending\_deletion Total number of log segments pending deletion from object storage for the topic. **Type**: gauge **Labels**: - `redpanda_namespace` - `redpanda_topic` * * * ### [](#redpanda_cloud_storage_spillover_manifest_uploads_total)redpanda\_cloud\_storage\_spillover\_manifest\_uploads\_total Total number of successful spillover manifest uploads to object storage. **Type**: counter * * * ### [](#redpanda_cloud_storage_spillover_manifests_materialized_bytes)redpanda\_cloud\_storage\_spillover\_manifests\_materialized\_bytes Total bytes of memory used by spilled manifests that are currently cached in memory. **Type**: gauge * * * ### [](#redpanda_cloud_storage_spillover_manifests_materialized_count)redpanda\_cloud\_storage\_spillover\_manifests\_materialized\_count Count of spilled manifests currently held in memory cache. **Type**: gauge * * * ### [](#redpanda_cloud_storage_uploaded_bytes)redpanda\_cloud\_storage\_uploaded\_bytes Total number of bytes uploaded for the topic to object storage. **Type**: counter **Labels**: - `redpanda_namespace` - `redpanda_topic` * * * ## [](#shadow-link-metrics)Shadow link metrics ### [](#redpanda_shadow_link_shadow_lag)redpanda\_shadow\_link\_shadow\_lag The lag of the shadow partition against the source partition, calculated as source partition last stable offset (LSO) minus shadow partition high watermark (HWM). Monitor this metric to understand replication lag for each partition and ensure your recovery point objective (RPO) requirements are being met. **Type**: gauge **Labels**: - `shadow_link_name` - Name of the shadow link - `topic` - Topic name - `partition` - Partition identifier * * * ### [](#redpanda_shadow_link_shadow_topic_state)redpanda\_shadow\_link\_shadow\_topic\_state Number of shadow topics in the respective states. Monitor this metric to track the health and status distribution of shadow topics across your shadow links. **Type**: gauge **Labels**: - `shadow_link_name` - Name of the shadow link - `state` - Topic state (active, failed, paused, failing\_over, failed\_over, promoting, promoted) * * * ### [](#redpanda_shadow_link_client_errors)redpanda\_shadow\_link\_client\_errors Total number of errors encountered by the Kafka client during shadow link operations. Monitor this metric to identify connection issues, authentication failures, or other client-side problems affecting shadow link replication. **Type**: counter **Labels**: - `shadow_link_name` - Name of the shadow link * * * ### [](#redpanda_shadow_link_total_bytes_fetched)redpanda\_shadow\_link\_total\_bytes\_fetched Total number of bytes fetched by a sharded replicator (bytes received by the client). Use this metric to track data transfer volume from the source cluster. **Type**: counter **Labels**: - `shadow_link_name` - Name of the shadow link - `shard` - Shard identifier * * * ### [](#redpanda_shadow_link_total_bytes_written)redpanda\_shadow\_link\_total\_bytes\_written Total number of bytes written by a sharded replicator (bytes written to the write\_at\_offset\_stm). Use this metric to monitor data written to the shadow cluster. **Type**: counter **Labels**: - `shadow_link_name` - Name of the shadow link - `shard` - Shard identifier * * * ### [](#redpanda_shadow_link_total_records_fetched)redpanda\_shadow\_link\_total\_records\_fetched Total number of records fetched by the sharded replicator (records received by the client). Monitor this metric to track message throughput from the source cluster. **Type**: counter **Labels**: - `shadow_link_name` - Name of the shadow link - `shard` - Shard identifier * * * ### [](#redpanda_shadow_link_total_records_written)redpanda\_shadow\_link\_total\_records\_written Total number of records written by a sharded replicator (records written to the write\_at\_offset\_stm). Use this metric to monitor message throughput to the shadow cluster. **Type**: counter **Labels**: - `shadow_link_name` - Name of the shadow link - `shard` - Shard identifier ## [](#related-topics)Related topics - [Learn how to monitor Redpanda](../../manage/monitoring/) - [Internal metrics reference](../internal-metrics-reference/) --- # Page 268: Release Notes **URL**: https://docs.redpanda.com/current/reference/releases.md --- # Release Notes --- title: Release Notes latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: releases/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: releases/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/releases/index.adoc description: This page provides a centralized index of release notes for Redpanda products. Use release notes to understand the enhancements, fixes, and important changes in each version of our products. page-git-created-date: "2024-05-07" page-git-modified-date: "2024-05-07" support-status: supported --- This page provides a centralized index of release notes for Redpanda products. Use release notes to understand the enhancements, fixes, and important changes in each version of our products. - [Redpanda](https://github.com/redpanda-data/redpanda/releases) - [Redpanda Console](https://github.com/redpanda-data/console/releases) - [Redpanda Helm Chart](https://github.com/redpanda-data/helm-charts/releases) - [Redpanda Operator](https://github.com/redpanda-data/redpanda-operator/releases) --- # Page 269: rpk Commands **URL**: https://docs.redpanda.com/current/reference/rpk.md --- # rpk Commands --- title: rpk Commands latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/index page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/index.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/index.adoc description: Index page of rpk commands in alphabetical order. page-git-created-date: "2023-05-17" page-git-modified-date: "2024-01-24" support-status: supported --- This page contains an alphabetized list of `rpk` commands. Each command includes a table of flags and their descriptions. You can also get descriptions for each flag by running `rpk --help` in your locally-installed Redpanda, and you can get descriptions of all rpk-specific options by running [`rpk -X help`](rpk-x-options/). > 📝 **NOTE** > > All `rpk` commands feature autocompletion. To use the feature, press tab. See [`rpk generate shell-completion`](rpk-generate/rpk-generate-shell-completion/). For information on deprecated `rpk` commands and flags, see [Deprecated features - rpk commands](../../upgrade/deprecated/#rpk-commands). - [rpk](rpk-commands/) The `rpk` is Redpanda's command line interface (CLI) utility. - [rpk -X](rpk-x-options/) This command lets you override `rpk` configuration options. - [rpk cluster](rpk-cluster/rpk-cluster/) These commands let you interact with a Redpanda cluster. - [rpk connect](rpk-connect/rpk-connect/) These commands let you create and manage data pipelines using Redpanda Connect. - [rpk container](rpk-container/rpk-container/) These commands let you manage (start, stop, purge) a local container cluster. - [rpk debug](rpk-debug/rpk-debug/) These commands let you debug the local Redpanda process and collect a diagnostics bundle. - [rpk generate](rpk-generate/rpk-generate/) These commands let you generate a configuration template for related services. - [rpk group](rpk-group/rpk-group/) These commands let you describe, list, and delete consumer groups and manage their offsets. - [rpk help](rpk-help/) This command provides additional information for any command in the application. - [rpk iotune](rpk-iotune/) This command measures the I/O performance of the hardware used by a Redpanda instance. - [rpk plugin](rpk-plugin/rpk-plugin/) These commands let you list, download, update, and remove `rpk` plugins. - [rpk profile](rpk-profile/rpk-profile/) These commands let you manage `rpk` profiles. - [rpk registry](rpk-registry/rpk-registry/) These commands let you manage Redpanda Schema Registry. - [rpk redpanda](rpk-redpanda/rpk-redpanda/) These commands let you interact with (start, stop, tune) a local Redpanda process. - [rpk security](rpk-security/rpk-security/) These commands let you create SASL users and create, list, and delete ACLs and RBAC. - [rpk shadow](rpk-shadow/rpk-shadow/) These commands let you manage shadow links for disaster recovery. - [rpk topic](rpk-topic/rpk-topic/) These commands let you manage your topics, including creating, producing, and consuming new messages. - [rpk transform](rpk-transform/rpk-transform/) These commands let you build and manage data transforms with WebAssembly. - [rpk version](rpk-version/) This command checks the current version of `rpk`. --- # Page 270: rpk cluster config edit **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-config-edit.md --- # rpk cluster config edit --- title: rpk cluster config edit latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-config-edit page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-config-edit.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-config-edit.adoc page-git-created-date: "2023-05-17" page-git-modified-date: "2025-06-02" support-status: supported --- Edit cluster-wide configuration properties. This command opens a text editor to modify the cluster’s configuration. Cluster properties are Redpanda settings that apply to all brokers in the cluster. These are separate from broker properties, which you can set with `rpk redpanda config`. Modified values are saved after the file is saved and the editor is closed. If you delete a property, Redpanda resets it to its default value. By default, low-level tunables are excluded. Use the `--all` flag to edit all properties including tunables. ## [](#usage)Usage ```bash rpk cluster config edit [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for edit. | | --all | - | Include all properties, including tunables. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 271: rpk cluster config export **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-config-export.md --- # rpk cluster config export --- title: rpk cluster config export latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-config-export page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-config-export.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-config-export.adoc page-git-created-date: "2023-05-17" page-git-modified-date: "2025-06-02" support-status: supported --- Export cluster configuration. Writes out a YAML representation of the cluster configuration to a file, suitable for editing and later applying with the corresponding `import` command. By default, low-level tunables are excluded. Use the `--all` flag to edit all properties, including these tunables. ## [](#usage)Usage ```bash rpk cluster config export [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -f, --filename | string | Path to file to export to; for example, ./config.yml. | | -h, --help | - | Help for export. | | --all | - | Include all properties, including tunables. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 272: rpk cluster config force-reset **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-config-force-reset.md --- # rpk cluster config force-reset --- title: rpk cluster config force-reset latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-config-force-reset page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-config-force-reset.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-config-force-reset.adoc page-git-created-date: "2023-05-17" page-git-modified-date: "2025-11-19" support-status: supported --- Forcibly clear a cluster configuration property on a broker. Do not use this command for general changes to cluster configuration. Use `force-reset` only when Redpanda does not start due to a configuration issue; for example, when a property is set to an invalid value or when a property is missing that Redpanda requires to start. This command erases the named property from an internal cache of the cluster configuration on the local broker, so that on next startup Redpanda treats the property as if it was set to the default. If your cluster is working properly and you want to reset a property to its default value, either use the `set` command with an empty string, or use the `edit` command and delete the line containing the property. > ⚠️ **WARNING** > > Use this command only when Redpanda isn’t running. ## [](#usage)Usage ```bash rpk cluster config force-reset [PROPERTY...] [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --cache-file | string | Location of configuration cache file (defaults to Redpanda data directory). | | -h, --help | - | Help for force-reset. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 273: rpk cluster config get **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-config-get.md --- # rpk cluster config get --- title: rpk cluster config get latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-config-get page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-config-get.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-config-get.adoc page-git-created-date: "2023-05-17" page-git-modified-date: "2025-11-19" support-status: supported --- Get a cluster configuration property. This command is provided for use in scripts. For interactive editing, or bulk output, use the `edit` and `export` commands respectively. ## [](#usage)Usage ```bash rpk cluster config get [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for get. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 274: rpk cluster config import **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-config-import.md --- # rpk cluster config import --- title: rpk cluster config import latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-config-import page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-config-import.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-config-import.adoc page-git-created-date: "2023-05-17" page-git-modified-date: "2025-06-02" support-status: supported --- > ⚠️ **CAUTION** > > Redpanda does not support importing cluster-specific identification (such as `cluster_id`) with this command. Import cluster configuration from a file. This command imports a cluster configuration from a YAML file, typically generated with the `export` command. The command first retrieves the current cluster configuration, compares it with the specified YAML file, and then updates any properties that were changed. If a property exists in the current configuration but is absent from the YAML file, that property is reset to its default value. ## [](#usage)Usage ```bash rpk cluster config import [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -f, --filename | string | Full path to file to import; for example, /tmp/config.yml. | | -h, --help | - | Help for import. | | --all | - | Include all properties, including tunables. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 275: rpk cluster config lint **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-config-lint.md --- # rpk cluster config lint --- title: rpk cluster config lint latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-config-lint page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-config-lint.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-config-lint.adoc page-git-created-date: "2023-05-17" page-git-modified-date: "2025-11-19" support-status: supported --- Remove any deprecated content from `redpanda.yaml`. Deprecated content includes properties that were set in the `redpanda.yaml` file in earlier versions but are now managed through Redpanda’s central configuration store and through `rpk cluster config edit`. ## [](#usage)Usage ```bash rpk cluster config lint [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for lint. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 276: rpk cluster config list **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-config-list.md --- # rpk cluster config list --- title: rpk cluster config list latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-config-list page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-config-list.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-config-list.adoc page-git-created-date: "2025-08-01" page-git-modified-date: "2025-08-05" support-status: supported --- This command lists all available cluster configuration properties. Use [`rpk cluster config get`](../rpk-cluster-config-get/) to retrieve specific property values. Use [`rpk cluster config edit`](../rpk-cluster-config-edit/) for interactive editing. Use the `--filter` flag with a regular expression to filter configuration keys. This is useful for exploring related configuration properties or finding specific settings. ## [](#usage)Usage ```bash rpk cluster config list [flags] ``` ## [](#examples)Examples List all cluster configuration properties: ```bash rpk cluster config list ``` List configuration properties matching a filter: ```bash rpk cluster config list --filter="kafka.*" ``` Filter properties containing "log": ```bash rpk cluster config list --filter=".*log.*" ``` Filter with case-insensitive matching: ```bash rpk cluster config list --filter="(?i)batch.*" ``` List configuration properties in JSON format: ```bash rpk cluster config list --format=json ``` List configuration properties in YAML format: ```bash rpk cluster config list --format=yaml ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --filter | string | Filter configuration keys using regular expression. | | --format | string | Output format. Possible values: json, yaml, text, wide, help. Default: text. | | -h, --help | - | Help for list. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 277: rpk cluster config set **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-config-set.md --- # rpk cluster config set --- title: rpk cluster config set latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-config-set page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-config-set.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-config-set.adoc page-git-created-date: "2023-05-17" page-git-modified-date: "2025-12-12" support-status: supported --- Set a cluster configuration property. You can set a single property or multiple properties at once, for example: ```bash rpk cluster config set audit_enabled true ``` ```bash rpk cluster config set iceberg_enabled=true iceberg_catalog_type=rest ``` You must use `=` notation to set multiple properties. If you set the cluster property value to an empty string, the property is reset to its default. This command is provided for use in scripts. For interactive editing, or bulk changes, use the `edit` and `import` commands respectively. For a list of available properties, see [Cluster Configuration Properties](../../../properties/cluster-properties/). ## [](#usage)Usage ```bash rpk cluster config set [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for set. | | --no-confirm | - | Disable confirmation prompt. | | --timeout | duration | Maximum time to poll for operation completion before displaying operation ID for manual status checking (for example 300ms, 1.5s, 30s). Default 10s. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | > 📝 **NOTE** > > Setting properties to non-number values (such as setting string values with `-`) can be problematic for some terminals due to how POSIX flags are parsed. For example, the following command may not work from some terminals: > > ```none > rpk cluster config set log_retention_ms -1 > ``` > > Workaround: Use `--` to disable parsing for all subsequent characters. For example: > > ```none > rpk cluster config set -- log_retention_ms -1 > ``` --- # Page 278: rpk cluster config status **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-config-status.md --- # rpk cluster config status --- title: rpk cluster config status latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-config-status page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-config-status.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-config-status.adoc page-git-created-date: "2023-05-17" page-git-modified-date: "2025-11-19" support-status: supported --- Get the configuration status of Redpanda brokers. For each broker, the command output shows: - Whether you need to restart the broker to apply the new settings - Any settings that the broker has flagged as invalid or unknown The command also returns the version of cluster configuration that each broker has applied. The version should be the same across all brokers, and it is incremented each time a configuration change is applied to the cluster. If a broker is using an earlier version as indicated by a lower number, it may be out of sync with the rest of the cluster. This can happen if a broker is offline or if it has not yet applied the latest configuration changes. The cluster configuration version number is not the same as the Redpanda version number. ## [](#usage)Usage ```bash rpk cluster config status [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for status. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 279: rpk cluster config **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-config.md --- # rpk cluster config --- title: rpk cluster config latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-config page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-config.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-config.adoc page-git-created-date: "2023-05-17" page-git-modified-date: "2025-11-19" support-status: supported --- Interact with cluster configuration properties. Cluster properties are Redpanda settings that apply to all brokers in the cluster. These are separate from broker properties, which apply to only that broker and are set with `rpk redpanda config`. Use the `edit` subcommand to interactively modify the cluster configuration, or `export` and `import` to write the configuration to a file that can be edited and read back later. These commands take an optional `--all` flag to include all properties such as low-level tunables (for example, internal buffer sizes) that do not usually need to be changed during normal operations. These properties generally require some expertise to set safely, so if in doubt, avoid using `--all`. Modified properties are propagated immediately to all brokers. Use the `status` subcommand to verify that all brokers are up to date and identify any settings which were rejected by a broker; for example, if the broker is running a different Redpanda version that does not recognize certain properties. ## [](#usage)Usage ```bash rpk cluster config [command] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for config. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 280: rpk cluster connections list **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-connections-list.md --- # rpk cluster connections list --- title: rpk cluster connections list latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-connections-list page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-connections-list.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-connections-list.adoc page-git-created-date: "2025-11-19" page-git-modified-date: "2025-11-19" support-status: supported --- Display statistics about current Kafka connections. This command displays a table of active and recently closed connections within the cluster. Use filtering and sorting to identify the connections of the client applications that you are interested in. See `--help` for the list of filtering arguments and sorting arguments. In addition to filtering shorthand CLI arguments (For example, `--client-id`, `--state`), you can also use the `--filter-raw` and `--order-by` arguments that take string expressions. To understand the syntax of these arguments, refer to the Admin API docs of the filter and order-by fields of the [ListKafkaConnections endpoint](/api/doc/admin/v2/operation/operation-redpanda-core-admin-v2-clusterservice-listkafkaconnections). By default only a subset of the per-connection data is printed. To see all of the available data, use `--format=json`. ## [](#usage)Usage ```bash rpk cluster connections list [flags] ``` ## [](#examples)Examples List connections ordered by their recent produce throughput: ```bash rpk cluster connections list --order-by="recent_request_statistics.produce_bytes desc" ``` List connections ordered by their recent fetch throughput: ```bash rpk cluster connections list --order-by="recent_request_statistics.fetch_bytes desc" ``` List connections ordered by the time that they’ve been idle: ```bash rpk cluster connections list --order-by="idle_duration desc" ``` List connections ordered by those that have made the least requests: ```bash rpk cluster connections list --order-by="total_request_statistics.request_count asc" ``` List extended output for open connections in JSON format: ```bash rpk cluster connections list --format=json --state="OPEN" ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --client-id | string | Filter results by the client ID. | | --client-software-name | string | Filter results by the client software name. | | --client-software-version | string | Filter results by the client software version. | | --filter-raw | string | Filter connections based on a raw query (overrides other filters). | | --format | string | Output format. Possible values: json, yaml, text, wide, help. Default: text. | | -g, --group-id | string | Filter by client group ID. | | -h, --help | - | Help for connections list. | | -i, --idle-ms | int | Show connections idle for more than i milliseconds. | | --ip-address | string | Filter results by the client IP address. | | --limit | int32 | Limit how many records can be returned (default 20). | | --order-by | string | Order the results by their values. See Examples. | | -s, --state | string | Filter results by state. Acceptable values: OPEN, CLOSED. | | -u, --user | string | Filter results by a specific user principal. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 281: rpk cluster connections **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-connections.md --- # rpk cluster connections --- title: rpk cluster connections latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-connections page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-connections.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-connections.adoc page-git-created-date: "2025-11-19" page-git-modified-date: "2025-11-19" support-status: supported --- Manage and monitor cluster connections. ## [](#usage)Usage ```bash rpk cluster connections [command] [flags] ``` ## [](#aliases)Aliases ```bash connections, connection ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for connections. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 282: rpk cluster health **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-health.md --- # rpk cluster health --- title: rpk cluster health latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-health page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-health.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-health.adoc page-git-created-date: "2023-05-17" page-git-modified-date: "2024-09-21" support-status: supported --- Queries health overview. Health overview is created based on the health reports collected periodically from all nodes in the cluster. A cluster is considered healthy when the following conditions are met: - all cluster nodes are responding - all partitions have leaders - the cluster controller is present ## [](#usage)Usage ```bash rpk cluster health [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -e, --exit-when-healthy | - | Exits when the cluster is back in a healthy state. | | -h, --help | - | Help for health. | | -w, --watch | - | Blocks and writes out all cluster health changes. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 283: rpk cluster info **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-info.md --- # rpk cluster info --- title: rpk cluster info latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-info page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-info.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-info.adoc page-git-created-date: "2024-05-14" page-git-modified-date: "2024-07-24" support-status: supported --- Request broker metadata information. The Kafka protocol’s metadata contains information about brokers, topics, and the cluster as a whole. This command only runs if specific sections of metadata are requested. There are currently three sections: the cluster, the list of brokers, and the topics. If no section is specified, this defaults to printing all sections. If the topic section is requested, all topics are requested by default unless some are manually specified as arguments. Expanded per-partition information can be printed with the -d flag, and internal topics can be printed with the -i flag. In the broker section, the controller node is suffixed with `\*`. ## [](#usage)Usage ```bash rpk cluster info [flags] ``` ## [](#aliases)Aliases ```bash metadata, status, info ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for metadata. | | -b, --print-brokers | - | Print brokers section. | | -c, --print-cluster | - | Print cluster section. | | -d, --print-detailed-topics | - | Print per-partition information for topics (implies -t). | | -i, --print-internal-topics | - | Print internal topics (if all topics requested, implies -t). | | -t, --print-topics | - | Print topics section (implied if any topics are specified). | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 284: rpk cluster license info **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-license-info.md --- # rpk cluster license info --- title: rpk cluster license info latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-license-info page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-license-info.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-license-info.adoc page-git-created-date: "2023-05-17" page-git-modified-date: "2024-12-03" support-status: supported --- Retrieve license information: - Organization: Organization the license was generated for. - Type: Type of license (free, enterprise, etc). - Expires: Expiration date of the license. - License Status: Status of the loaded license (valid, expired, not\_present). - Violation: Whether the cluster is using enterprise features without a valid license. ## [](#usage)Usage ```bash rpk cluster license info [flags] ``` ## [](#aliases)Aliases ```bash info, status ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --format | string | Output format. Possible values: json, yaml, text, wide, help. Default: text. | | -h, --help | - | Help for info. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 285: rpk cluster license set **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-license-set.md --- # rpk cluster license set --- title: rpk cluster license set latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-license-set page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-license-set.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-license-set.adoc page-git-created-date: "2023-05-17" page-git-modified-date: "2024-06-14" support-status: supported --- Upload license to the cluster. Updating the license does not require a cluster restart. You can either provide a path to a file containing the license: ```bash rpk cluster license set --path /home/organization/redpanda.license ``` Or inline the license string: ```bash rpk cluster license set ``` If neither are present, `rpk` will look for the license in the default location `/etc/redpanda/redpanda.license`. ## [](#usage)Usage ```bash rpk cluster license set [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for set. | | --path | string | Path to the license file. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 286: rpk cluster license **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-license.md --- # rpk cluster license --- title: rpk cluster license latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-license page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-license.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-license.adoc page-git-created-date: "2023-05-17" page-git-modified-date: "2024-04-30" support-status: supported --- Manage cluster license. ## [](#usage)Usage ```bash rpk cluster license [flags] [command] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for license. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 287: rpk cluster logdirs describe **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-logdirs-describe.md --- # rpk cluster logdirs describe --- title: rpk cluster logdirs describe latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-logdirs-describe page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-logdirs-describe.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-logdirs-describe.adoc page-git-created-date: "2023-05-17" page-git-modified-date: "2024-07-24" support-status: supported --- Describe log directories on Redpanda brokers. This command prints information about log directories on brokers, particularly, the base directory that topics and partitions are located in, and the size of data that has been written to the partitions. The size you see may not exactly match the size on disk as reported by du: Redpanda allocates files in chunks. The chunks will show up in du, while the actual bytes so far written to the file will show up in this command. The directory returned is the root directory for partitions. Within Redpanda, the partition data lives underneath the returned root directory in `kafka/{topic}/{partition}_{revision}/`, where `revision` is a Redpanda internal concept. ## [](#usage)Usage ```bash rpk cluster logdirs describe [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --aggregate-into | string | If non-empty, what column to aggregate into starting from the partition column (broker, dir, topic). | | -b, --broker | int32 | If non-negative, the specific broker to describe (default -1). | | -h, --help | - | Help for describe. | | -H, --human-readable | - | Print the logdirs size in a human-readable form. | | --sort-by-size | - | If true, sort by size. | | --topics | strings | Specific topics to describe. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 288: rpk cluster logdirs **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-logdirs.md --- # rpk cluster logdirs --- title: rpk cluster logdirs latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-logdirs page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-logdirs.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-logdirs.adoc page-git-created-date: "2023-05-17" page-git-modified-date: "2024-07-24" support-status: supported --- Describe log directories on Redpanda brokers. ## [](#usage)Usage ```bash rpk cluster logdirs [flags] [command] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for logdirs. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 289: rpk cluster maintenance disable **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-maintenance-disable.md --- # rpk cluster maintenance disable --- title: rpk cluster maintenance disable latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-maintenance-disable page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-maintenance-disable.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-maintenance-disable.adoc page-git-created-date: "2023-05-17" page-git-modified-date: "2024-04-30" support-status: supported --- Disable maintenance mode for a node. ## [](#usage)Usage ```bash rpk cluster maintenance disable [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for disable. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 290: rpk cluster maintenance enable **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-maintenance-enable.md --- # rpk cluster maintenance enable --- title: rpk cluster maintenance enable latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-maintenance-enable page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-maintenance-enable.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-maintenance-enable.adoc page-git-created-date: "2023-05-17" page-git-modified-date: "2024-04-30" support-status: supported --- Enable maintenance mode for a node. This command enables maintenance mode for the node with the specified ID. If a node exists that is already in maintenance mode then an error will be returned. ## [](#usage)Usage ```bash rpk cluster maintenance enable [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for enable. | | -w, --wait | - | Wait until node is drained. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 291: rpk cluster maintenance status **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-maintenance-status.md --- # rpk cluster maintenance status --- title: rpk cluster maintenance status latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-maintenance-status page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-maintenance-status.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-maintenance-status.adoc page-git-created-date: "2023-05-17" page-git-modified-date: "2024-04-30" support-status: supported --- Report maintenance status. This command reports maintenance status for each node in the cluster. The output is presented as a table with each row representing a node in the cluster. The output can be used to monitor the progress of node draining. NODE-ID DRAINING FINISHED ERRORS PARTITIONS ELIGIBLE TRANSFERRING FAILED 1 false false false 0 0 0 0 | Field | Description | | --- | --- | | Node-id | The node ID. | | Draining | true if the node is actively draining leadership. | | Finished | Leadership draining has completed. | | Errors | Errors have been encountered while draining. | | Partitions | Number of partitions whose leadership has moved. | | Eligible | Number of partitions with leadership eligible to move. | | Transferring | Current active number of leadership transfers. | | Failed | Number of failed leadership transfers. | > 📝 **NOTE** > > - When errors are present further information will be available in the logs for the corresponding node. > > - Only partitions with more than one replica are eligible for leadership transfer. ## [](#usage)Usage ```bash rpk cluster maintenance status [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for status. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 292: rpk cluster maintenance **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-maintenance.md --- # rpk cluster maintenance --- title: rpk cluster maintenance latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-maintenance page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-maintenance.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-maintenance.adoc page-git-created-date: "2023-05-17" page-git-modified-date: "2024-04-30" support-status: supported --- Interact with cluster maintenance mode. Maintenance mode is a state that a node may be placed into in which the node may be shutdown or restarted with minimal disruption to client workloads. The primary use of maintenance mode is to perform a rolling upgrade in which each node is placed into maintenance mode prior to upgrading the node. Use the `enable` and `disable` subcommands to place a node into maintenance mode or remove it, respectively. Only one node at a time may be in maintenance mode. When a node is placed into maintenance mode the following occurs: Leadership draining. All raft leadership is transferred to another eligible node, and the node in maintenance mode rejects new leadership requests. By transferring leadership off of the node in maintenance mode all client traffic and requests are directed to other nodes minimizing disruption to client workloads when the node is shutdown. Currently leadership is not transferred for partitions with one replica. ## [](#usage)Usage ```bash rpk cluster maintenance [flags] [command] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for maintenance. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 293: rpk cluster partitions balance **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-partitions-balance.md --- # rpk cluster partitions balance --- title: rpk cluster partitions balance latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-partitions-balance page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-partitions-balance.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-partitions-balance.adoc description: rpk cluster partitions balance page-git-created-date: "2024-09-21" page-git-modified-date: "2024-09-21" support-status: supported --- Triggers on-demand partition balancing. With Redpanda Community Edition, the partition count on each broker can easily become uneven, which leads to data skewing. To distribute partitions across brokers, you can run this command to trigger on-demand partition balancing. With Redpanda Enterprise Edition, Continuous Data Balancing monitors broker and rack availability, as well as disk usage, to avoid topic hotspots. However, there are edge cases where users should manually trigger partition balancing (such as a node becoming unavailable for a prolonged time and rejoining the cluster thereafter). In such cases, you should run this command to trigger partition balancing manually. After you run this command, monitor the balancer progress using: ```bash rpk cluster partitions balancer-status ``` To see more detailed movement status, monitor the progress using: ```bash rpk cluster partitions move-status ``` ## [](#usage)Usage ```bash rpk cluster partitions balance [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for balance. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 294: rpk cluster partitions balancer-status **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-partitions-balancer-status.md --- # rpk cluster partitions balancer-status --- title: rpk cluster partitions balancer-status latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-partitions-balancer-status page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-partitions-balancer-status.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-partitions-balancer-status.adoc page-git-created-date: "2023-05-17" page-git-modified-date: "2024-04-30" support-status: supported --- Queries cluster for partition balancer status: If continuous partition balancing is enabled, redpanda will continuously reassign partitions from both unavailable nodes and from nodes using more disk space than the configured limit. This command can be used to monitor the partition balancer status. ## [](#fields)Fields | Field | Description | | --- | --- | | Status | Either off, ready, starting, in progress, or stalled. | | Seconds Since Last Tick | The last time the partition balancer ran. | | Current Reassignments Count | Current number of partition reassignments in progress. | | Unavailable Nodes | The nodes that have been unavailable after a time set by the partition_autobalancing_node_availability_timeout_sec cluster property. | | Over Disk Limit Nodes | The nodes that surpassed the threshold of used disk percentage specified in the partition_autobalancing_max_disk_usage_percent cluster property. | ## [](#balancer-status)Balancer status | Balancer status | Description | | --- | --- | | off | The balancer is disabled. | | ready | The balancer is active but there is nothing to do | | starting | The balancer is starting but has not run yet. | | in_progress | The balancer is active and is in the process of scheduling partition movements. | | stalled | Violations have been detected and the balancer cannot correct them. | ## [](#stalled-balancer)Stalled Balancer A stalled balancer can occur for a few reasons and requires a bit of manual investigation. A few areas to investigate: - Are there are enough healthy nodes to which to move partitions? For example, in a three node cluster, no movements are possible for partitions with three replicas. You will see a stall every time there is a violation. - Does the cluster have sufficient space? If all nodes in the cluster are utilizing more than 80% of their disk space, rebalancing cannot proceed. - Do all partitions have quorum? If the majority of a partition’s replicas are down, the partition cannot be moved. - Are any nodes in maintenance mode? Partitions are not moved if any node is in maintenance mode. ## [](#usage)Usage ```bash rpk cluster partitions balancer-status [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for balancer-status. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 295: rpk cluster partitions disable **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-partitions-disable.md --- # rpk cluster partitions disable --- title: rpk cluster partitions disable latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-partitions-disable page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-partitions-disable.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-partitions-disable.adoc page-git-created-date: "2023-12-22" page-git-modified-date: "2024-04-30" support-status: supported --- Disable partitions of a topic. You may disable all partitions of a topic using the `--all` flag or you may select a set of topic/partitions to disable with the `--partitions` or `-p` flag. The partition flag accepts the format `//[partitions…​]` where namespace and topic are optional parameters. If the namespace is not provided, `rpk` will assume `kafka`. If the topic is not provided in the flag, `rpk` will use the topic provided as an argument to this command. ## [](#disabled-partitions)Disabled Partitions Disabling a partition in Redpanda involves prohibiting any data consumption or production to and from it. All internal processes associated with the partition are stopped, and it remains unloaded during system startup. This measure aims to maintain cluster health by preventing issues caused by specific corrupted partitions that may lead to Redpanda crashes. Although the data remains stored on disk, Redpanda ceases interaction with the disabled partitions to ensure system stability. ## [](#examples)Examples Disable all partitions in topic `foo`: ```bash rpk cluster partitions disable foo --all ``` Disable partitions 1,2 and 3 of topic `bar` in the namespace `internal`: ```bash rpk cluster partitions disable internal/bar --partitions 1,2,3 ``` Disable partition 1, and 2 of topic `foo`, and partition 5 of topic `bar` in the `internal` namespace: ```bash rpk cluster partitions disable -p foo/1,2 -p internal/bar/5 ``` ## [](#usage)Usage ```bash rpk cluster partitions disable [TOPIC] [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -a, --all | - | If true, disable all partitions for the specified topic. | | -h, --help | - | Help for disable. | | -p, --partitions | stringArray | Comma-separated list of partitions you want to disable. Use --help for additional information. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 296: rpk cluster partitions enable **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-partitions-enable.md --- # rpk cluster partitions enable --- title: rpk cluster partitions enable latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-partitions-enable page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-partitions-enable.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-partitions-enable.adoc page-git-created-date: "2023-12-22" page-git-modified-date: "2024-04-30" support-status: supported --- Enable partitions of a topic. You may enable all partitions of a topic using the `--all` flag or you may select a set of topic/partitions to enable with the `--partitions` or `-p` flag. The partition flag accepts the format `//[partitions…​]` where namespace and topic are optional parameters. If the namespace is not provided, `rpk` will assume `kafka`. If the topic is not provided in the flag, `rpk` will use the topic provided as an argument to this command. ## [](#examples)Examples Enable all partitions in topic `foo`: ```bash rpk cluster partitions enable foo --all ``` Enable partitions 1,2 and 3 of topic `bar` in the namespace `internal`: ```bash rpk cluster partitions enable internal/bar --partitions 1,2,3 ``` Enable partition 1, and 2 of topic `foo`, and partition 5 of topic `bar` in the `internal` namespace: ```bash rpk cluster partitions enable -p foo/1,2 -p internal/bar/5 ``` ## [](#usage)Usage ```bash rpk cluster partitions enable [TOPIC] [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -a, --all | - | If true, enable all partitions for the specified topic. | | -h, --help | - | Help for enable. | | -p, --partitions | stringArray | Comma-separated list of partitions you want to enable. Check help for extended usage. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 297: rpk cluster partitions list **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-partitions-list.md --- # rpk cluster partitions list --- title: rpk cluster partitions list latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-partitions-list page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-partitions-list.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-partitions-list.adoc page-git-created-date: "2023-12-22" page-git-modified-date: "2024-08-01" support-status: supported --- List partitions in the cluster. This commands lists the cluster-level metadata of all partitions in the cluster. It shows the current replica assignments on both brokers and CPU cores for given topics. By default, it assumes the `kafka` namespace, but you can specify an internal namespace using the `/` prefix. The `Replica-Core` column displayed in the output table contains a list of replica assignments in the form of -. If the Disabled column contains a '-' value, then it means you are running this command against a cluster that does not support the underlying API. ## [](#enableddisabled)Enabled/Disabled Disabling a partition in Redpanda involves prohibiting any data consumption or production to and from it. All internal processes associated with the partition are stopped, and it remains unloaded during system startup. This measure aims to maintain cluster health by preventing issues caused by specific corrupted partitions that may lead to Redpanda crashes. Although the data remains stored on disk, Redpanda ceases interaction with the disabled partitions to ensure system stability. You may disable/enable partition using `rpk cluster partitions enable/disable`. ## [](#usage)Usage ```bash rpk cluster partitions list [TOPICS...] [flags] ``` ## [](#aliases)Aliases ```bash list, ls, describe ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -a, --all | - | If true, list all partitions in the cluster. | | --disabled-only | - | If true, list disabled partitions only. | | --format | string | Output format. Possible values: json, yaml, text, wide, help. Default: text. | | -h, --help | - | Help for list. | | -n, --node-ids | ints | List of comma-separated broker IDs you wish to use to filter the results. | | -p, --partition | ints | List of comma-separated partitions IDs you wish to use to filter the results. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | ## [](#examples)Examples List all partitions in the cluster: ```bash rpk cluster partitions list --all ``` List all partitions in the cluster, filtering for topic foo and bar: ```bash rpk cluster partitions list foo bar ``` List partitions with replicas that are assigned to brokers 1 and 2. ```bash rpk cluster partitions list foo --node-ids 1,2 ``` List only the disabled partitions: ```bash rpk cluster partitions list -a --disabled-only ``` List all in JSON format: ```bash rpk cluster partition list -a --format json ``` --- # Page 298: rpk cluster partitions move-cancel **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-partitions-move-cancel.md --- # rpk cluster partitions move-cancel --- title: rpk cluster partitions move-cancel latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-partitions-move-cancel page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-partitions-move-cancel.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-partitions-move-cancel.adoc page-git-created-date: "2023-12-22" page-git-modified-date: "2024-04-30" support-status: supported --- Cancel ongoing partition movements. By default, this command cancels all the partition movements in the cluster. To ensure that you do not accidentally cancel all partition movements, this command prompts users for confirmation before issuing the cancellation request. ## [](#example)Example You can use `--no-confirm` to disable the confirmation prompt: ```bash rpk cluster partitions move-cancel --no-confirm ``` If `--node` is set, this command will only stop the partition movements occurring in the specified broker: ```bash rpk cluster partitions move-cancel --node 1 ``` ## [](#usage)Usage ```bash rpk cluster partitions move-cancel [flags] ``` ## [](#aliases)Aliases ```bash move-cancel, alter-cancel ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for move-cancel. | | --no-confirm | - | Disable confirmation prompt. | | --node | int | ID of a specific broker on which to cancel ongoing partition movements (default -1). | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 299: rpk cluster partitions move-status **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-partitions-move-status.md --- # rpk cluster partitions move-status --- title: rpk cluster partitions move-status latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-partitions-move-status page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-partitions-move-status.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-partitions-move-status.adoc page-git-created-date: "2023-12-22" page-git-modified-date: "2024-04-30" support-status: supported --- Show ongoing partition movements. By default this command lists all ongoing partition movements in the cluster. Topics can be specified to print the move status of specific topics. By default, this command assumes the `kafka` namespace, but you can use a `/` to specify internal namespaces. ```bash rpk cluster partitions move-status ``` ```bash rpk cluster partitions move-status foo bar kafka_internal/tx ``` The `--partition / -p` flag can be used with topics to additional filter requested partitions: ```bash rpk cluster partitions move-status foo bar --partition 0,1,2 ``` The output contains the following columns. The Partition-Size column is in bytes. Using -H, it prints the partition size in a human-readable format - Namespace-Topic - Partition - Moving-From - Moving-To - Completion-% - Partition-Size - Bytes-Moved - Bytes-Remaining Using `--print-all / -a` the command additionally prints the column `Reconciliation-Statuses`, which reveals the internal status of the ongoing reconciliations. Reported errors do not necessarily mean real problems. ## [](#usage)Usage ```bash rpk cluster partitions move-status [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for move-status. | | -H, --human-readable | - | Print the partition size in a human-readable form. | | -p, --partition | strings | Partitions to filter ongoing movements status (repeatable). | | -a, --print-all | - | Print internal states about movements for debugging. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 300: rpk cluster partitions move **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-partitions-move.md --- # rpk cluster partitions move --- title: rpk cluster partitions move latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-partitions-move page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-partitions-move.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-partitions-move.adoc page-git-created-date: "2023-12-22" page-git-modified-date: "2024-12-09" support-status: supported --- Move partition replicas across brokers/cores. This command changes replica assignments for given partitions. By default, it assumes the `kafka` namespace, but you can specify an internal namespace using the `/` prefix. ## [](#examples)Examples To move replicas, use the following syntax: ```bash rpk cluster partitions move foo --partition 0:1,2,3 -p 1:2,3,4 ``` Here, the command assigns new replicas for partition 0 to brokers \[1, 2, 3\] and for partition 1 to brokers \[2, 3, 4\] for the topic `foo`. You can also specify the core id with `--` where the new replicas should be placed: ```bash rpk cluster partitions move foo -p 0:1-0,2-0,3-0 ``` Here all new replicas \[1, 2, 3\] will be assigned on core 0 on the brokers. The command does not change a core assignment unless it is explicitly specified. When a core is not specified for a new broker, the command randomly picks a core and assigns a replica to the core. Topic arguments are optional. For more control, you can specify the topic name in the `--partition` flag: ```bash rpk cluster partitions move -p foo/0:1,2,3 -p kafka_internal/tx/0:1-0,2-0,3-0 ``` ## [](#usage)Usage ```bash rpk cluster partitions move [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --format | string | Output format. Possible values: json, yaml, text, wide, help. Default: text. | | -h, --help | - | Help for move. | | -p, --partition | stringArray | Topic partitions to move and new replica locations (repeatable). | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 301: rpk cluster partitions transfer-leadership **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-partitions-transfer-leadership.md --- # rpk cluster partitions transfer-leadership --- title: rpk cluster partitions transfer-leadership latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-partitions-transfer-leadership page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-partitions-transfer-leadership.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-partitions-transfer-leadership.adoc page-git-created-date: "2024-05-30" page-git-modified-date: "2025-05-21" support-status: supported --- Transfer partition leadership between brokers. This command supports transferring only one partition leader at a time. > 📝 **NOTE** > > Redpanda tries to balance leadership distribution across brokers by default. If the distribution of leaders becomes uneven as a result of transferring leadership across brokers, the cluster may move leadership back to the original brokers automatically. ## [](#usage)Usage ```bash rpk cluster partitions transfer-leadership [flags] ``` ## [](#examples)Examples To transfer partition leadership for a partition `0` to a broker ID `2`, run: ```bash rpk cluster partitions transfer-leadership foo --partition 0:2 ``` The `--partition` flag accepts a value `:`, where `A` is a topic-partition and `B` is the ID of the broker to which you want to transfer leadership. To specify a topic-partition, you can use just the partition ID (`0`) or also use the topic name together with the partition using the following syntax: ```bash rpk cluster partitions transfer-leadership --partition test-topic/0:2 ``` In this case, the name of the topic is `test-topic` and the partition ID is `0`. The preceding examples transfer leadership for the partition `kafka/test-topic/0`. The command behavior is based on the assumption that the default namespace is `kafka`, but you can also specify an internal namespace using the `{namespace}/` prefix. ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --format | string | Output format. Possible values: json, yaml, text, wide, help. Default: text. | | -h, --help | - | Help for transfer-leadership. | | -p, --partition | string | Specify the topic-partition’s leadership to transfer and the location of the new leader. Use the syntax -p :. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 302: rpk cluster partitions unsafe-recover **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-partitions-unsafe-recover.md --- # rpk cluster partitions unsafe-recover --- title: rpk cluster partitions unsafe-recover latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-partitions-unsafe-recover page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-partitions-unsafe-recover.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-partitions-unsafe-recover.adoc page-git-created-date: "2023-12-22" page-git-modified-date: "2024-04-30" support-status: supported --- Recover unsafely from partitions that have lost majority. > ❗ **IMPORTANT** > > This operation is unsafe because it allows the forced leader election of the partitions that have lost majority when nodes are gone and irrecoverable; this may result in data loss. This command allows you to unsafely recover all data adversely affected by the loss of the nodes specified in the `--from-nodes` flag. You can perform a dry run and verify the partitions that will be recovered by using the `--dry` flag. ## [](#usage)Usage ```bash rpk cluster partitions unsafe-recover [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --dry | - | Dry run: print the partition movement plan. Does not execute it. | | --format | string | Output format. Possible values: json, yaml, text, wide, help. Default: text. | | --from-nodes | - | Comma-separated list of node IDs from which to recover the partitions. | | -h, --help | - | Help for unsafe-recover. | | --no-confirm | - | Disable confirmation prompt. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 303: rpk cluster partitions **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-partitions.md --- # rpk cluster partitions --- title: rpk cluster partitions latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-partitions page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-partitions.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-partitions.adoc page-git-created-date: "2023-05-17" page-git-modified-date: "2024-04-30" support-status: supported --- Manage cluster partitions. ## [](#usage)Usage ```bash rpk cluster partitions [command] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for partitions. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 304: rpk cluster quotas alter **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-quotas-alter.md --- # rpk cluster quotas alter --- title: rpk cluster quotas alter latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-quotas-alter page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-quotas-alter.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-quotas-alter.adoc page-git-created-date: "2024-07-31" page-git-modified-date: "2025-11-19" support-status: supported --- Add or delete a client quota. A client quota consists of an entity (to which the quota is applied) and a quota type (what is being applied). There are two entity types supported by Redpanda: client ID and client ID prefix. Use the `--default` flag to assign quotas to default entity types. You can perform a dry run using the `--dry` flag. ## [](#usage)Usage ```bash rpk cluster quotas alter [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --add | strings | Key=value quota to add, where the value is a float number (repeatable). | | --default | strings | Entity type for default matching, where type is client-id or client-id-prefix (repeatable). | | --delete | strings | Key of the quota to delete (repeatable). | | --dry | - | Perform a dry run. Validate the request without altering the quotas. Show what would be done, but do not execute the command. | | --format | string | Output format. Possible values: json, yaml, text, wide, help. Default: text. | | -h, --help | - | Help for alter. | | --name | strings | Entity for exact matching. Format type=name where type is the client-id or client-id-prefix (repeatable). | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | ## [](#examples)Examples Add quota (consumer\_byte\_rate) to client ID ``: ```bash rpk cluster quotas alter --add consumer_byte_rate=200000 --name client-id= ``` Add quota (consumer\_byte\_rate) to client ID starting with `-`: ```bash rpk cluster quotas alter --add consumer_byte_rate=200000 --name client-id-prefix=- ``` Add quota (producer\_byte\_rate) to default client ID: ```bash rpk cluster quotas alter --add producer_byte_rate=180000 --default client-id ``` Remove quota (producer\_byte\_rate) from client ID `foo`: ```bash rpk cluster quotas alter --delete producer_byte_rate --name client-id= ``` --- # Page 305: rpk cluster quotas describe **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-quotas-describe.md --- # rpk cluster quotas describe --- title: rpk cluster quotas describe latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-quotas-describe page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-quotas-describe.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-quotas-describe.adoc page-git-created-date: "2024-07-31" page-git-modified-date: "2025-08-19" support-status: supported --- Describe client quotas. This command describes client quotas that match the provided filtering criteria. Running the command without filters returns all client quotas. Use the `--strict` flag for strict matching, which means that the only quotas returned exactly match the filters. You can specify filters in terms of entities. An entity consists of either a client ID or a client ID prefix. ## [](#usage)Usage ```bash rpk cluster quotas describe [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --any | strings | Type for any matching (names or default), where type is client-id or client-id-prefix (repeatable). | | --default | strings | Type for default matching, where type is client-id or client-id-prefix (repeatable). | | --format | string | Output format. Possible values: json, yaml, text, wide, help. Default: text. | | -h, --help | - | Help for describe. | | --name | strings | The type=name pair for exact name matching, where type is client-id or client-id-prefix (repeatable). | | --strict | - | Specifies whether matches are strict. If true, entities with unspecified entity types are excluded. | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | ## [](#examples)Examples Describe all client quotas: ```bash rpk cluster quotas describe ``` Describe all client quota with client ID ``: ```bash rpk cluster quotas describe --name client-id= ``` Describe client quotas for a given client ID prefix `.`: ```bash rpk cluster quotas describe --name client-id=. ``` --- # Page 306: rpk cluster quotas import **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-quotas-import.md --- # rpk cluster quotas import --- title: rpk cluster quotas import latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-quotas-import page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-quotas-import.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-quotas-import.adoc page-git-created-date: "2024-07-31" page-git-modified-date: "2025-08-19" support-status: supported --- Use this command to import client quotas in the format produced by `rpk cluster quotas describe --format json/yaml`. The schema of the import string matches the schema from `rpk cluster quotas describe --format help`: #### YAML ```yaml quotas: - entity: - name: string - type: string values: - key: string - values: string ``` #### JSON ```yaml { "quotas": [ { "entity": [ { "name": "string", "type": "string" } ], "values": [ { "key": "string", "values": "string" } ] } ] } ``` Use the `--no-confirm` flag to avoid the confirmation prompt. ## [](#usage)Usage ```bash rpk cluster quotas import [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --from | string | Either the quotas or a path to a file containing the quotas to import; check help text for more information. | | -h, --help | - | Help for import. | | --no-confirm | - | Disable confirmation prompt. | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | ## [](#examples)Examples Import client quotas from a file: ```bash rpk cluster quotas import --from /path/to/file ``` Import client quotas from a string: ```bash rpk cluster quotas import --from '{"quotas":...}' ``` Import client quotas from a JSON string: ```bash rpk cluster quotas import --from ' { "quotas": [ { "entity": [ { "name": "retrievals-", "type": "client-id-prefix" } ], "values": [ { "key": "consumer_byte_rate", "value": "140000" } ] }, { "entity": [ { "name": "consumer-1", "type": "client-id" } ], "values": [ { "key": "producer_byte_rate", "value": "140000" } ] } ] } ' ``` Import client quotas from a YAML string: ```bash rpk cluster quotas import --from ' quotas: - entity: - name: retrievals- type: client-id-prefix values: - key: consumer_byte_rate value: "140000" - entity: - name: consumer-1 type: client-id values: - key: producer_byte_rate value: "140000" ' ``` --- # Page 307: rpk cluster quotas **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-quotas.md --- # rpk cluster quotas --- title: rpk cluster quotas latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-quotas page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-quotas.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-quotas.adoc page-git-created-date: "2024-07-31" page-git-modified-date: "2025-08-19" support-status: supported --- Manage Redpanda client quotas. ## [](#usage)Usage ```bash rpk cluster quotas [command] [flags] ``` ## [](#aliases)Aliases ```bash quotas, quota ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --format | string | Output format. Possible values: json, yaml, text, wide, help. Default: text. | | -h, --help | - | Help for quotas. | | --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 308: rpk cluster self-test start **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-self-test-start.md --- # rpk cluster self-test start --- title: rpk cluster self-test start latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-self-test-start page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-self-test-start.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-self-test-start.adoc description: Reference for the 'rpk cluster self-test start' command. Starts one or more benchmark tests on one or more nodes of the cluster. page-git-created-date: "2023-08-04" page-git-modified-date: "2025-07-29" support-status: supported --- Starts one or more benchmark tests on one or more nodes of the cluster. > 📝 **NOTE** > > Redpanda self-test runs benchmarks that consume significant system resources. Do not start self-test if large workloads are already running on the system. Available tests to run: - **Disk tests** - Throughput test: 512 KB messages, sequential read/write - Uses a larger request message sizes and deeper I/O queue depth to write/read more bytes in a shorter amount of time, at the cost of IOPS/latency. - Latency test: 4 KB messages, sequential read/write - Uses smaller request message sizes and lower levels of parallelism to achieve higher IOPS and lower latency. - **Network tests** - Throughput test: 8192-bit messages - Unique pairs of Redpanda nodes each act as a client and a server. - The test pushes as much data over the wire, within the test parameters. - **Cloud storage tests** - Configuration/latency test: 1024-byte object. - If cloud storage is enabled ([`cloud_storage_enabled`](../../../properties/object-storage-properties/#cloud_storage_enabled)), a series of remote operations are performed: 1. Upload an object (a random buffer of 1024 bytes) to the cloud storage bucket/container. 2. List objects in the bucket/container. 3. Download the uploaded object from the bucket/container. 4. Download the uploaded object’s metadata from the bucket/container. 5. Delete the uploaded object from the bucket/container. 6. Upload and then delete multiple objects (random buffers) at once from the bucket/container. This command prompts users for confirmation (unless the flag `--no-confirm` is specified), then returns a test identifier ID, and runs the tests. To view the test status, poll [rpk cluster self-test status](../rpk-cluster-self-test-status/). Once the tests end, the cached results will be available with `rpk cluster self-test status`. ## [](#usage)Usage ```bash rpk cluster self-test start [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --cloud-backoff-ms | uint | The backoff in milliseconds for a cloud storage request (default 100). | | --cloud-timeout-ms | uint | The timeout in milliseconds for a cloud storage request (default 10000). | | --disk-duration-ms | uint | The duration in milliseconds of individual disk test runs (default 30000). | | -h, --help | - | Help for start. | | --network-duration-ms | uint | The duration in milliseconds of individual network test runs (default 30000). | | --no-confirm | - | Acknowledge warning prompt skipping read from stdin. | | --only-cloud-test | - | Runs only cloud storage verification. | | --only-disk-test | - | Runs only the disk benchmarks. | | --only-network-test | - | Runs only network benchmarks. | | --participant-node-ids | uints | Comma-separated list of broker IDs that the tests will run on. If not set, tests will run for all node IDs. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 309: rpk cluster self-test status **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-self-test-status.md --- # rpk cluster self-test status --- title: rpk cluster self-test status latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-self-test-status page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-self-test-status.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-self-test-status.adoc description: Reference for the 'rpk cluster self-test status' command. Queries the status of the currently running or last completed self-test run. page-git-created-date: "2023-08-04" page-git-modified-date: "2024-08-01" support-status: supported --- Returns the status of the current running tests or the cached results of the last completed run. Use this command after invoking [rpk cluster self-test start](../rpk-cluster-self-test-start/) to determine the status of the jobs launched. Possible results are: - One or more jobs still running - Returns the IDs of Redpanda brokers (nodes) still running self-tests. Example: ```bash Node 1 is still running net self test ``` - No jobs running - Returns the cached results for all brokers of the last completed test. Test results are grouped by broker ID. Each test returns the following: - **Name**: Description of the test. - **Info**: Details about the test run attached by Redpanda. - **Type**: Either `disk`, `network`, or `cloud` test. - **Test Id**: Unique identifier given to jobs of a run. All IDs in a test should match. If they don’t match, then newer and/or older test results have been included erroneously. - **Timeouts**: Number of timeouts incurred during the test. - **Start time**: Time that the test started, in UTC. - **End time**: Time that the test ended, in UTC. - **Avg Duration**: Duration of the test. - **IOPS**: Number of operations per second. For disk, it’s `seastar::dma_read` and `seastar::dma_write`. For network, it’s `rpc.send()`. - **Throughput**: For disk, throughput rate is in bytes per second. For network, throughput rate is in bits per second. Note that GiB vs. Gib is the correct notation displayed by the UI. - **Latency**: 50th, 90th, etc. percentiles of operation latency, reported in microseconds (μs). Represented as P50, P90, P99, P999, and MAX respectively. If [Tiered Storage](../../../../manage/tiered-storage/) is not enabled, then cloud storage tests do not run, and a warning displays: "Cloud storage is not enabled." All results are shown as 0. ## [](#usage)Usage ```bash rpk cluster self-test status [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --format | string | Output format. Possible values: json, text. Default: text. | | -h, --help | - | Help for status. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | ## [](#example)Example Example input: ```bash rpk cluster self-test status ``` Example output ```console $ rpk cluster self-test status NODE ID: 0 | STATUS: IDLE ========================= NAME 512KB sequential r/w INFO write run (iodepth: 4, dsync: true) TYPE disk TEST ID 21c5a3de-c75b-480c-8a3d-0cbb63228cb1 TIMEOUTS 0 START TIME Fri Jul 19 15:02:45 UTC 2024 END TIME Fri Jul 19 15:03:15 UTC 2024 AVG DURATION 30002ms IOPS 1182 req/sec THROUGHPUT 591.4MiB/sec LATENCY P50 P90 P99 P999 MAX 3199us 3839us 9727us 12799us 21503us NAME 512KB sequential r/w INFO read run TYPE disk TEST ID 21c5a3de-c75b-480c-8a3d-0cbb63228cb1 TIMEOUTS 0 START TIME Fri Jul 19 15:03:15 UTC 2024 END TIME Fri Jul 19 15:03:45 UTC 2024 AVG DURATION 30000ms IOPS 6652 req/sec THROUGHPUT 3.248GiB/sec LATENCY P50 P90 P99 P999 MAX 607us 671us 831us 991us 2431us NAME 4KB sequential r/w, low io depth INFO write run (iodepth: 1, dsync: true) TYPE disk TEST ID 21c5a3de-c75b-480c-8a3d-0cbb63228cb1 TIMEOUTS 0 START TIME Fri Jul 19 15:03:45 UTC 2024 END TIME Fri Jul 19 15:04:15 UTC 2024 AVG DURATION 30000ms IOPS 406 req/sec THROUGHPUT 1.59MiB/sec LATENCY P50 P90 P99 P999 MAX 2431us 2559us 2815us 5887us 9215us NAME 4KB sequential r/w, low io depth INFO read run TYPE disk TEST ID 21c5a3de-c75b-480c-8a3d-0cbb63228cb1 TIMEOUTS 0 START TIME Fri Jul 19 15:04:15 UTC 2024 END TIME Fri Jul 19 15:04:45 UTC 2024 AVG DURATION 30000ms IOPS 430131 req/sec THROUGHPUT 1.641GiB/sec LATENCY P50 P90 P99 P999 MAX 1us 2us 12us 28us 511us NAME 4KB sequential write, medium io depth INFO write run (iodepth: 8, dsync: true) TYPE disk TEST ID 21c5a3de-c75b-480c-8a3d-0cbb63228cb1 TIMEOUTS 0 START TIME Fri Jul 19 15:04:45 UTC 2024 END TIME Fri Jul 19 15:05:15 UTC 2024 AVG DURATION 30013ms IOPS 513 req/sec THROUGHPUT 2.004MiB/sec LATENCY P50 P90 P99 P999 MAX 15871us 16383us 21503us 32767us 40959us NAME 4KB sequential write, high io depth INFO write run (iodepth: 64, dsync: true) TYPE disk TEST ID 21c5a3de-c75b-480c-8a3d-0cbb63228cb1 TIMEOUTS 0 START TIME Fri Jul 19 15:05:15 UTC 2024 END TIME Fri Jul 19 15:05:45 UTC 2024 AVG DURATION 30114ms IOPS 550 req/sec THROUGHPUT 2.151MiB/sec LATENCY P50 P90 P99 P999 MAX 118783us 118783us 147455us 180223us 180223us NAME 4KB sequential write, very high io depth INFO write run (iodepth: 256, dsync: true) TYPE disk TEST ID 21c5a3de-c75b-480c-8a3d-0cbb63228cb1 TIMEOUTS 0 START TIME Fri Jul 19 15:05:45 UTC 2024 END TIME Fri Jul 19 15:06:16 UTC 2024 AVG DURATION 30460ms IOPS 558 req/sec THROUGHPUT 2.183MiB/sec LATENCY P50 P90 P99 P999 MAX 475135us 491519us 507903us 524287us 524287us NAME 4KB sequential write, no dsync INFO write run (iodepth: 64, dsync: false) TYPE disk TEST ID 21c5a3de-c75b-480c-8a3d-0cbb63228cb1 TIMEOUTS 0 START TIME Fri Jul 19 15:06:16 UTC 2024 END TIME Fri Jul 19 15:06:46 UTC 2024 AVG DURATION 30000ms IOPS 424997 req/sec THROUGHPUT 1.621GiB/sec LATENCY P50 P90 P99 P999 MAX 135us 183us 303us 543us 9727us NAME 16KB sequential r/w, high io depth INFO write run (iodepth: 64, dsync: false) TYPE disk TEST ID 21c5a3de-c75b-480c-8a3d-0cbb63228cb1 TIMEOUTS 0 START TIME Fri Jul 19 15:06:46 UTC 2024 END TIME Fri Jul 19 15:07:16 UTC 2024 AVG DURATION 30000ms IOPS 103047 req/sec THROUGHPUT 1.572GiB/sec LATENCY P50 P90 P99 P999 MAX 511us 1087us 1343us 1471us 15871us NAME 16KB sequential r/w, high io depth INFO read run TYPE disk TEST ID 21c5a3de-c75b-480c-8a3d-0cbb63228cb1 TIMEOUTS 0 START TIME Fri Jul 19 15:07:16 UTC 2024 END TIME Fri Jul 19 15:07:46 UTC 2024 AVG DURATION 30000ms IOPS 193966 req/sec THROUGHPUT 2.96GiB/sec LATENCY P50 P90 P99 P999 MAX 319us 383us 735us 1023us 6399us NAME 8K Network Throughput Test INFO Test performed against node: 1 TYPE network TEST ID 5e4052f3-b828-4c0d-8fd0-b34ff0b6c35d TIMEOUTS 0 DURATION 5000ms IOPS 61612 req/sec THROUGHPUT 3.76Gib/sec LATENCY P50 P90 P99 P999 MAX 159us 207us 303us 431us 1151us NAME 8K Network Throughput Test INFO Test performed against node: 2 TYPE network TEST ID 5e4052f3-b828-4c0d-8fd0-b34ff0b6c35d TIMEOUTS 0 DURATION 5000ms IOPS 60306 req/sec THROUGHPUT 3.68Gib/sec LATENCY P50 P90 P99 P999 MAX 159us 215us 351us 495us 11263us NAME Cloud Storage Test INFO Put TYPE cloud TEST ID a349685a-ee49-4141-8390-c302975db3a5 TIMEOUTS 0 START TIME Tue Jul 16 18:06:30 UTC 2024 END TIME Tue Jul 16 18:06:30 UTC 2024 AVG DURATION 8ms NAME Cloud Storage Test INFO List TYPE cloud TEST ID a349685a-ee49-4141-8390-c302975db3a5 TIMEOUTS 0 START TIME Tue Jul 16 18:06:30 UTC 2024 END TIME Tue Jul 16 18:06:30 UTC 2024 AVG DURATION 1ms NAME Cloud Storage Test INFO Get TYPE cloud TEST ID a349685a-ee49-4141-8390-c302975db3a5 TIMEOUTS 0 START TIME Tue Jul 16 18:06:30 UTC 2024 END TIME Tue Jul 16 18:06:30 UTC 2024 AVG DURATION 1ms NAME Cloud Storage Test INFO Head TYPE cloud TEST ID a349685a-ee49-4141-8390-c302975db3a5 TIMEOUTS 0 START TIME Tue Jul 16 18:06:30 UTC 2024 END TIME Tue Jul 16 18:06:30 UTC 2024 AVG DURATION 0ms NAME Cloud Storage Test INFO Delete TYPE cloud TEST ID a349685a-ee49-4141-8390-c302975db3a5 TIMEOUTS 0 START TIME Tue Jul 16 18:06:30 UTC 2024 END TIME Tue Jul 16 18:06:30 UTC 2024 AVG DURATION 1ms NAME Cloud Storage Test INFO Plural Delete TYPE cloud TEST ID a349685a-ee49-4141-8390-c302975db3a5 TIMEOUTS 0 START TIME Tue Jul 16 18:06:30 UTC 2024 END TIME Tue Jul 16 18:06:30 UTC 2024 AVG DURATION 47ms ``` > 📝 **NOTE** > > If self-test returns write results that are unexpectedly and significantly lower than read results, it may be because the Redpanda `rpk` client hardcodes the `DSync` option to `true`. When `DSync` is enabled, files are opened with the `O_DSYNC` flag set, and this represents the actual setting that Redpanda uses when it writes to disk. ## [](#related-topics)Related topics - [Guide for running self-test for cluster diagnostics](../../../../troubleshoot/cluster-diagnostics/diagnose-issues/#disk-and-network-self-test-benchmarks) - [rpk cluster self-test](../rpk-cluster-self-test/) - [rpk cluster self-test start](../rpk-cluster-self-test-start/) - [rpk cluster self-test stop](../rpk-cluster-self-test-stop/) --- # Page 310: rpk cluster self-test stop **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-self-test-stop.md --- # rpk cluster self-test stop --- title: rpk cluster self-test stop latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-self-test-stop page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-self-test-stop.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-self-test-stop.adoc description: Reference for the 'rpk cluster self-test stop' command. Stops the currently executing self-test. page-git-created-date: "2023-08-04" page-git-modified-date: "2024-04-30" support-status: supported --- Stops all self-test tests. This command stops all currently running self-tests. The command is synchronous and returns success when all jobs have been stopped or reports errors if broker timeouts have expired. ## [](#usage)Usage ```bash rpk cluster self-test stop [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for stop. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | ## [](#example-output)Example output $ rpk cluster self-test stop All self-test jobs have been stopped ## [](#related-topics)Related topics - [Guide for running self-test for cluster diagnostics](../../../../troubleshoot/cluster-diagnostics/diagnose-issues/#disk-and-network-self-test-benchmarks) - [rpk cluster self-test](../rpk-cluster-self-test/) - [rpk cluster self-test start](../rpk-cluster-self-test-start/) - [rpk cluster self-test status](../rpk-cluster-self-test-status/) --- # Page 311: rpk cluster self-test **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-self-test.md --- # rpk cluster self-test --- title: rpk cluster self-test latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-self-test page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-self-test.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-self-test.adoc page-git-created-date: "2023-08-04" page-git-modified-date: "2024-04-30" support-status: supported --- ## [](#usage)Usage ```bash rpk cluster self-test [command] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for self-test. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | ## [](#related-topics)Related topics - [Guide for running self-test for cluster diagnostics](../../../../troubleshoot/cluster-diagnostics/diagnose-issues/#disk-and-network-self-test-benchmarks) - [rpk cluster self-test start](../rpk-cluster-self-test-start/) - [rpk cluster self-test status](../rpk-cluster-self-test-status/) - [rpk cluster self-test stop](../rpk-cluster-self-test-stop/) --- # Page 312: rpk cluster storage cancel mount **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-storage-cancel-mount.md --- # rpk cluster storage cancel mount --- title: rpk cluster storage cancel mount latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-storage-cancel-mount page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-storage-cancel-mount.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-storage-cancel-mount.adoc page-git-created-date: "2024-12-03" page-git-modified-date: "2025-05-09" support-status: supported --- Cancels a mount/unmount operation on a topic. Use the migration ID that is emitted when the mount or unmount operation is executed. You can also get the migration ID by listing the mount/unmount operations. ## [](#usage)Usage ```bash rpk cluster storage cancel-mount [MIGRATION ID] [flags] ``` ## [](#aliases)Aliases ```bash cancel-mount, cancel-unmount ``` ## [](#examples)Examples Cancel a mount/unmount operation: ```bash rpk cluster storage cancel-mount 123 ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for cancel-mount. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 313: rpk cluster storage list mount **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-storage-list-mount.md --- # rpk cluster storage list mount --- title: rpk cluster storage list mount latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-storage-list-mount page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-storage-list-mount.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-storage-list-mount.adoc page-git-created-date: "2024-12-03" page-git-modified-date: "2025-05-09" support-status: supported --- List mount/unmount operations on a topic in the Redpanda cluster from [Tiered Storage](https://docs.redpanda.com/current/reference/glossary/#tiered-storage). You can also filter the list by state using the `--filter` flag. The possible states are: - `planned` - `prepared` - `executed` - `finished` If no filter is provided, all migrations are listed. ## [](#usage)Usage ```bash rpk cluster storage list-mount [flags] ``` ## [](#aliases)Aliases ```bash list-mount, list-unmount ``` ## [](#examples)Examples Lists mount/unmount operations: ```bash rpk cluster storage list-mount ``` Use a filter to list only migrations in a specific state: ```bash rpk cluster storage list-mount --filter planned ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -f, --filter | string | Filter the list of migrations by state. Only valid for text (default all). | | --format | string | Output format. Possible values: json, yaml, text, wide, help. Default: text. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 314: rpk cluster storage list-mountable **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-storage-list-mountable.md --- # rpk cluster storage list-mountable --- title: rpk cluster storage list-mountable latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-storage-list-mountable page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-storage-list-mountable.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-storage-list-mountable.adoc page-git-created-date: "2024-12-03" page-git-modified-date: "2025-05-09" support-status: supported --- List topics that are available to mount from object storage. This command displays topics that exist in object storage and can be mounted to your Redpanda cluster. Each topic includes its location in object storage and namespace information if applicable. ## [](#usage)Usage ```bash rpk cluster storage list-mountable [flags] ``` ## [](#examples)Examples List all mountable topics: ```bash rpk cluster storage list-mountable ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for list-mountable. | | --format | string | Output format. Possible values: json, yaml, text, wide, help. Default: text. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 315: rpk cluster storage mount **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-storage-mount.md --- # rpk cluster storage mount --- title: rpk cluster storage mount latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-storage-mount page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-storage-mount.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-storage-mount.adoc page-git-created-date: "2024-12-03" page-git-modified-date: "2025-05-09" support-status: supported --- Mount a topic to the Redpanda cluster from [Tiered Storage](https://docs.redpanda.com/current/reference/glossary/#tiered-storage). This command mounts a topic in the Redpanda cluster using log segments stored in Tiered Storage. You can optionally rename the topic using the `--to` flag. Requirements: - [Tiered Storage must be enabled](../../../../manage/tiered-storage/#enable-tiered-storage). - Log segments for the topic must be available in Tiered Storage. - A topic with the same name must not already exist in the cluster. ## [](#usage)Usage ```bash rpk cluster storage mount [TOPIC] [flags] ``` ## [](#examples)Examples Mounts topic ` from Tiered Storage to the cluster in the my-namespace: ```bash rpk cluster storage mount ``` Mount topic `` from Tiered Storage to the cluster in the `` with `` as the new topic name: ```bash rpk cluster storage mount / --to / ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --to | string | New namespace/topic name for the mounted topic (optional). | | -h, --help | - | Help for mount. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 316: rpk cluster storage restore start **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-storage-restore-start.md --- # rpk cluster storage restore start --- title: rpk cluster storage restore start latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-storage-restore-start page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-storage-restore-start.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-storage-restore-start.adoc page-git-created-date: "2023-12-22" page-git-modified-date: "2024-04-30" support-status: supported --- Start the topic restoration process. This command starts the process of restoring topics from the archival bucket. If the wait flag (--wait/-w) is set, the command will poll the status of the recovery process until it’s finished. See also: [Whole Cluster Restore](../../../../manage/disaster-recovery/whole-cluster-restore/). ## [](#usage)Usage ```bash rpk cluster storage restore start [flags] ``` ## [](#aliases)Aliases ```bash restore, recovery ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for start. | | --polling-interval | duration | The status check interval (e.g. '30s', '1.5m'); ignored if --wait is not used (default 5s). | | -w, --wait | - | Wait until the operation is complete. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 317: rpk cluster storage restore status **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-storage-restore-status.md --- # rpk cluster storage restore status --- title: rpk cluster storage restore status latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-storage-restore-status page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-storage-restore-status.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-storage-restore-status.adoc page-git-created-date: "2023-12-22" page-git-modified-date: "2024-04-30" support-status: supported --- Fetch the status of the topic restoration process. This command fetches the status of the process of restoring topics from the archival bucket. See also: [Whole Cluster Restore](../../../../manage/disaster-recovery/whole-cluster-restore/). ## [](#usage)Usage ```bash rpk cluster storage restore status [flags] ``` ## [](#aliases)Aliases ```bash restore, recovery ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for status. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 318: rpk cluster storage restore **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-storage-restore.md --- # rpk cluster storage restore --- title: rpk cluster storage restore latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-storage-restore page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-storage-restore.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-storage-restore.adoc page-git-created-date: "2023-12-22" page-git-modified-date: "2024-04-30" support-status: supported --- Interact with the topic restoration process. This command is used to restore topics from the archival bucket, which can be useful for disaster recovery or if a topic was accidentally deleted. To begin the recovery process, use the `restore start` command. Note that this process can take a while to complete, so the command will exit after starting it. If you want the command to wait for the process to finish, use the `--wait` or `-w` flag. You can check the status of the recovery process with the `restore status` command after it has been started. See also: [Whole Cluster Restore](../../../../manage/disaster-recovery/whole-cluster-restore/). ## [](#usage)Usage ```bash rpk cluster storage restore [command] [flags] ``` ## [](#aliases)Aliases ```bash restore, recovery ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for restore. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 319: rpk cluster storage status mount **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-storage-status-mount.md --- # rpk cluster storage status mount --- title: rpk cluster storage status mount latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-storage-status-mount page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-storage-status-mount.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-storage-status-mount.adoc page-git-created-date: "2024-12-03" page-git-modified-date: "2025-05-09" support-status: supported --- Status of mount/unmount operation on topic in a Redpanda cluster from [Tiered Storage](https://docs.redpanda.com/current/reference/glossary/#tiered-storage). ## [](#usage)Usage ```bash rpk cluster storage status-mount [MIGRATION ID] [flags] ``` ## [](#aliases)Aliases ```bash status-mount, status-unmount ``` ## [](#examples)Examples Status for a mount/unmount operation: ```bash rpk cluster storage status-mount 123 ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --format | string | Output format. Possible values: json, yaml, text, wide, help. Default: text. | | -h, --help | - | Help for status-mount. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 320: rpk cluster storage unmount **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-storage-unmount.md --- # rpk cluster storage unmount --- title: rpk cluster storage unmount latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-storage-unmount page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-storage-unmount.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-storage-unmount.adoc page-git-created-date: "2024-12-03" page-git-modified-date: "2025-05-09" support-status: supported --- Unmount a topic from the Redpanda cluster and secure it in [Tiered Storage](https://docs.redpanda.com/current/reference/glossary/#tiered-storage). This command performs an operation that: 1. Rejects all writes to the topic. 2. Flushes data to Tiered Storage. 3. Removes the topic from the cluster. Key Points: - During unmounting, any attempted writes or reads will receive an `UNKNOWN_TOPIC_OR_PARTITION` error. - The unmount operation works independently of other topic configurations like `remote.delete=false`. - After unmounting, the topic can be remounted to this cluster or a different cluster if the log segments are moved to that cluster’s Tiered Storage. ## [](#usage)Usage ```bash rpk cluster storage unmount [TOPIC] [flags] ``` ## [](#examples)Examples Unmount topic '' from the cluster in the '': ```bash rpk cluster storage unmount / ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for unmount. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 321: rpk cluster storage **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-storage.md --- # rpk cluster storage --- title: rpk cluster storage latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-storage page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-storage.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-storage.adoc page-git-created-date: "2023-08-04" page-git-modified-date: "2025-05-09" support-status: supported --- Manage the cluster storage. ## [](#usage)Usage ```bash rpk cluster storage [command] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for storage. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 322: rpk cluster txn describe-producers **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-txn-describe-producers.md --- # rpk cluster txn describe-producers --- title: rpk cluster txn describe-producers latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-txn-describe-producers page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-txn-describe-producers.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-txn-describe-producers.adoc page-git-created-date: "2023-12-22" page-git-modified-date: "2024-07-24" support-status: supported --- Describe transactional producers to partitions. This command describes partitions that active transactional producers are producing to. For more information on the producer ID and epoch columns, see `rpk cluster txn --help`. ## [](#concept)Concept The last timestamp corresponds to the timestamp of the last record that was written by the client. The transaction start offset corresponds to the offset that the transaction is began at. All consumers configured to read only committed records cannot read past the transaction start offset. The output includes a few advanced fields that can be used for sanity checking: the last sequence is the last sequence number that the producer has written, and the coordinator epoch is the epoch of the broker that is being written to. The last sequence should always go up and then wrap back to 0 at MaxInt32. The coordinator epoch should remain fixed, or rarely, increase. You can query all topics and partitions that have active producers with --all. To filter for specific topics, use `--topics`. You can additionally filter by partitions with `--partitions`. ## [](#usage)Usage ```bash rpk cluster txn describe-producers [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -a, --all | - | Query all producer IDs on any topic. | | -h, --help | - | Help for describe-producers. | | -p, --partitions | int32 | int32Slice Partitions to describe producers for (repeatable) (default []). | | -t, --topics | strings | Topic to describe producers for (repeatable). | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --format | string | Output format. Possible values: json, yaml, text, wide, help. Default: text. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 323: rpk cluster txn describe **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-txn-describe.md --- # rpk cluster txn describe --- title: rpk cluster txn describe latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-txn-describe page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-txn-describe.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-txn-describe.adoc page-git-created-date: "2023-12-22" page-git-modified-date: "2024-07-24" support-status: supported --- Describe transactional IDs. This command, in comparison to `list`, is a more detailed per-transaction view of transactional IDs. In addition to the state and producer ID, this command also outputs when a transaction started, the epoch of the producer ID, how long until the transaction times out, and the partitions currently a part of the transaction. For information on what the columns in the output mean, see `rpk cluster txn --help`. By default, all topics in a transaction are merged into one line. To print a row per topic, use `--format=long`. To include partitions with topics, use `--print-partitions`; `--format=json/yaml` will return the equivalent of the long format with print partitions included. If no transactional IDs are requested, all transactional IDs are printed. ## [](#usage)Usage ```bash rpk cluster txn describe [TXN-IDS...] [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for describe. | | -p, --print-partitions | - | Include per-topic partitions that are in the transaction. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --format | string | Output format. Possible values: json, yaml, text, wide, help. Default: text. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 324: rpk cluster txn list **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-txn-list.md --- # rpk cluster txn list --- title: rpk cluster txn list latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-txn-list page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-txn-list.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-txn-list.adoc page-git-created-date: "2023-12-22" page-git-modified-date: "2024-07-24" support-status: supported --- List transactions and their current states. This command lists all known transactions in the cluster, the producer ID for the transactional ID, and the and the state of the transaction. For information on what the columns in the output mean, see `rpk cluster txn --help`. ## [](#usage)Usage ```bash rpk cluster txn list [flags] ``` ## [](#aliases)Aliases ```bash list, ls ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for list. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --format | string | Output format. Possible values: json, yaml, text, wide, help. Default: text. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 325: rpk cluster txn **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster-txn.md --- # rpk cluster txn --- title: rpk cluster txn latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster-txn page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster-txn.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster-txn.adoc page-git-created-date: "2023-12-22" page-git-modified-date: "2024-07-24" support-status: supported --- Information about transactions and transactional producers. ## [](#concept)Concept Transactions allow producing, or consume-modifying-producing, to Redpanda. The consume-modify-produce loop is also referred to as EOS (exactly once semantics). Transactions involve a lot of technical complexity that is largely hidden within clients. This command space helps shed a light on what is actually happening in clients and brokers while transactions are in use. ### [](#transactional-id)Transactional ID The transactional ID is the string you define in clients when actually using transactions. ### [](#producer-id-epoch)Producer ID & Epoch The producer ID is generated within clients when you transactionally produce. The producer ID is a number that maps to your transactional ID, allowing requests to be smaller when producing, and allowing some optimizations within brokers when managing transactions. Some clients expose the producer ID, allowing you to track the transactional ID that a producer ID maps to. If possible, it is recommended to monitor the producer ID used in your applications. The producer epoch is a number that somewhat "counts" the number of times your transaction has been initialized or expired. If you have one client that uses a transactional ID, it may receive producer ID 3 epoch 0. Another client that uses that same transactional ID will receive producer ID 3 epoch 1. If the client starts a transaction but does not finish it in time, the cluster will internally bump the epoch to 2. The epoch allows the cluster to "fence" clients: if a client attempts to use a producer ID with an old epoch, the cluster will reject the client’s produce request as stale. ### [](#transaction-state)Transaction State The state of a transaction indicates what is currently happening with a transaction. A high level overview of transactional states: - Empty: The transactional ID is ready, but there are no partitions nor groups added to it. There is no active transaction. - Ongoing: The transactional ID is being used in a began transaction. - PrepareCommit: A commit is in progress. - PrepareAbort: An abort is in progress. - PrepareEpochFence: The transactional ID is timing out. - Dead: The transactional ID has expired and/or is not in use. ### [](#last-stable-offset)Last Stable Offset The last stable offset is the offset at which a transaction has begun and clients cannot consume past, if the client is configured to read only committed offsets. The last stable offset can be seen when describing active transactional producers by looking for the earliest transaction start offset per partition. ## [](#usage)Usage ```bash rpk cluster txn [command] [flags] ``` ## [](#aliases)Aliases ```bash txn, transaction ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --format | string | Output format. Possible values: json, yaml, text, wide, help. Default: text. | | -h, --help | - | Help for txn. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 326: rpk cluster **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-cluster/rpk-cluster.md --- # rpk cluster --- title: rpk cluster latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-cluster/rpk-cluster page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-cluster/rpk-cluster.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-cluster/rpk-cluster.adoc description: These commands let you interact with a Redpanda cluster. page-git-created-date: "2023-05-17" page-git-modified-date: "2024-07-24" support-status: supported --- Interact with a Redpanda cluster. ## [](#usage)Usage ```bash rpk cluster [command] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for cluster. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 327: rpk **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-commands.md --- # rpk --- title: rpk latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-commands page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-commands.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-commands.adoc description: The rpk is Redpanda's command line interface (CLI) utility. page-git-created-date: "2023-05-17" page-git-modified-date: "2024-07-24" support-status: supported --- `rpk` is a command line interface (CLI) toolbox that let you configure, manage, and tune Redpanda clusters. It also lets you manage topics, groups, and access control lists (ACLs). `rpk` stands for Redpanda Keeper. ## [](#rpk)rpk `rpk` is the Redpanda CLI toolbox. ### [](#usage)Usage ```bash rpk [command] ``` ### [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for rpk`. | | -v, --verbose | - | Enable verbose logging (default false). | ## [](#related-topics)Related topics - [Introduction to rpk](../../../get-started/rpk-install/) * * * ## [](#suggested-reading)Suggested reading - [Introducing rpk container](https://redpanda.com/blog/rpk-container/) - [Get started with rpk commands](https://redpanda.com/blog/getting-started-rpk/) --- # Page 328: rpk connect blobl server **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-connect/rpk-connect-blobl-server.md --- # rpk connect blobl server --- title: rpk connect blobl server latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-connect/rpk-connect-blobl-server page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-connect/rpk-connect-blobl-server.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-connect/rpk-connect-blobl-server.adoc page-git-created-date: "2024-05-30" page-git-modified-date: "2024-05-30" support-status: supported --- Run a web server that provides an interactive application for writing and testing Bloblang mappings. ## [](#usage)Usage ```bash rpk connect blobl server [command options] [arguments...] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --host | - | The host to bind to (default: "localhost"). | | --port, -p | - | The port to bind to (default: "4195"). | | --no-open, -n | - | Do not open the app in the browser automatically (default: false). | | --mapping-file, -m | - | An optional path to a mapping file to load as the initial mapping within the app. | | --input-file, -i | - | An optional path to an input file to load as the initial input to the mapping within the app. | | --write, -w | - | When editing a mapping or input file, write changes made back to the respective source file. If the file does not exist, it is created (default: false). | | --help, -h | - | When editing a mapping or input file, write changes made back to the respective source file. If the file does not exist, it is created (default: false). | --- # Page 329: rpk connect create **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-connect/rpk-connect-create.md --- # rpk connect create --- title: rpk connect create latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-connect/rpk-connect-create page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-connect/rpk-connect-create.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-connect/rpk-connect-create.adoc page-git-created-date: "2024-05-30" page-git-modified-date: "2024-05-30" support-status: supported --- Create a new Redpanda Connect config and print a new Redpanda Connect config to stdout containing specified components according to an expression. The expression must take the form of three comma-separated lists of inputs, processors, and outputs, divided by forward slashes. If the expression is omitted, a default config is created. ## [](#usage)Usage ```bash rpk connect create [command options] [arguments...] ``` ## [](#examples)Examples ```bash rpk connect create stdin/bloblang,awk/nats ``` ```bash rpk connect create file,http_server/protobuf/http_client ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --small, -s | - | Print only the main components of a Redpanda Connect config (input, pipeline, output) and omit all fields marked as advanced (default: false). | | --help, -h | - | Show help | --- # Page 330: rpk connect echo **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-connect/rpk-connect-echo.md --- # rpk connect echo --- title: rpk connect echo latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-connect/rpk-connect-echo page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-connect/rpk-connect-echo.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-connect/rpk-connect-echo.adoc page-git-created-date: "2024-05-30" page-git-modified-date: "2024-07-26" support-status: supported --- Parse a configuration file and echo back a normalized version. This command is useful to check a configuration that isn’t working as expected. It shows a normalized version after environment variables have been resolved. ## [](#usage)Usage ```bash rpk connect echo [arguments...] ``` ## [](#example)Example ```bash rpk connect echo ./config.yaml | less ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --help, -h | - | Show help. | --- # Page 331: rpk connect install **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-connect/rpk-connect-install.md --- # rpk connect install --- title: rpk connect install latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-connect/rpk-connect-install page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-connect/rpk-connect-install.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-connect/rpk-connect-install.adoc page-git-created-date: "2024-10-02" page-git-modified-date: "2024-10-02" support-status: supported --- Install Redpanda Connect. By default, this command installs the latest version of Redpanda Connect. Alternatively, you can use the command with the `--connect-version` flag to install a specific version. To force the installation of Redpanda Connect, use the `--force` flag. ## [](#usage)Usage ```bash rpk connect install [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --connect-version | string | The Redpanda Connect version to install. For example: "4.32.0" (default "latest"). | | --force | - | Force install of Redpanda Connect. | | -h, --help | - | Help for install. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 332: rpk connect lint **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-connect/rpk-connect-lint.md --- # rpk connect lint --- title: rpk connect lint latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-connect/rpk-connect-lint page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-connect/rpk-connect-lint.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-connect/rpk-connect-lint.adoc page-git-created-date: "2024-05-30" page-git-modified-date: "2024-07-26" support-status: supported --- Parse Redpanda Connect configs and report any linting errors. Exits with a status code 1 if any linting errors are detected. If a path ends with `…​`, Redpanda Connect lints any files with the `.yaml` or `.yml` extension. ## [](#usage)Usage ```bash rpk connect lint [command options] [arguments...] ``` ## [](#examples)Examples ```bash rpk connect lint target.yaml ``` ```bash rpk connect lint ./configs/*.yaml ``` ```bash rpk connect lint -r ./foo.yaml ./bar.yaml ``` ```bash rpk connect lint ./configs/... ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --resources, -r | - | Pulls in extra resources from a file, which you can reference with a unique label in the main configuration. Supports glob patterns (requires quotes). | | --deprecated | - | Print linting errors for the presence of deprecated fields (default: false). | | --labels | - | Print linting errors when components do not have labels (default: false). | | --skip-env-var-check | - | Do not produce lint errors for environment interpolations missing defaults (default: false). | | --help, -h | - | Show help. | --- # Page 333: rpk connect list **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-connect/rpk-connect-list.md --- # rpk connect list --- title: rpk connect list latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-connect/rpk-connect-list page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-connect/rpk-connect-list.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-connect/rpk-connect-list.adoc page-git-created-date: "2024-05-30" page-git-modified-date: "2024-05-30" support-status: supported --- List all Redpanda Connect component types. If any component types are explicitly listed, then only types of those components are shown. ## [](#usage)Usage ```bash rpk connect list [command options] [arguments...] ``` ## [](#examples)Examples ```bash rpk connect list ``` ```bash rpk connect list --format json inputs output ``` ```bash rpk connect list rate-limits buffers ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --format | - | Print the component list in a specific format. Options are text, json, or cue (default: "text"). | | --status | - | Filter the component list to only those matching the given status. Options are stable, beta, or experimental. | | --help, -h | - | Show help. | --- # Page 334: rpk connect mcp-server init **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-connect/rpk-connect-mcp-server-init.md --- # rpk connect mcp-server init --- title: rpk connect mcp-server init latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-connect/rpk-connect-mcp-server-init page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-connect/rpk-connect-mcp-server-init.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-connect/rpk-connect-mcp-server-init.adoc description: Create the folder structure of an MCP server. page-git-created-date: "2025-09-22" page-git-modified-date: "2025-09-22" support-status: supported --- Creates the folder structure required for an MCP server project. ├── o11y │ ├── metrics.yaml │ └── tracer.yaml └── resources ├── caches │ └── example-cache.yaml ├── inputs │ └── example-input.yaml ├── outputs │ └── example-output.yaml └── processors └── example-processor.yaml The `resources` directory is where you define your tools such as inputs, outputs, and processors. Each tool is defined in its own YAML file. By default, the `example-` files are provided as templates. The `o11y` directory contains configuration for observability, including metrics and tracing. Files that already exist are overwritten. ## [](#usage)Usage rpk connect mcp-server init \[OPTIONS\] ## [](#options)Options | Option | Description | | --- | --- | | --help, -h | Show help for the command. | --- # Page 335: rpk connect mcp-server lint **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-connect/rpk-connect-mcp-server-lint.md --- # rpk connect mcp-server lint --- title: rpk connect mcp-server lint latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-connect/rpk-connect-mcp-server-lint page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-connect/rpk-connect-mcp-server-lint.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-connect/rpk-connect-mcp-server-lint.adoc description: Parse Redpanda Connect configs and report any linting errors. page-git-created-date: "2025-09-22" page-git-modified-date: "2025-09-22" support-status: supported --- Parse Redpanda Connect configs and report any linting errors. Exits with a status code 1 if any linting errors are detected in a directory. ## [](#usage)Usage ```bash rpk connect mcp-server lint [command options] ``` ## [](#examples)Examples ```bash rpk connect mcp-server lint . rpk connect mcp-server lint ./foo ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --deprecated | - | Print linting errors for the presence of deprecated fields. (default: false) | | --labels | - | Print linting errors when components do not have labels. (default: false) | | --skip-env-var-check | - | Do not produce lint errors when environment interpolations exist without defaults within configs but aren’t defined. (default: false) | | --verbose | - | Print the lint result for each target file. (default: false) | | --secrets env: [ --secrets env: ] | - | Attempt to load secrets from a provided URN. If more than one entry is specified they will be attempted in order until a value is found. Environment variable lookups are specified with the URN env:, which by default is the only entry. In order to disable all secret lookups specify a single entry of none:. (default: "env:") | | --env-file value, -e value [ --env-file value, -e value ] | - | Import environment variables from a dotenv file. | | --help, -h | - | Show help for the command. | --- # Page 336: rpk connect mcp-server **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-connect/rpk-connect-mcp-server.md --- # rpk connect mcp-server --- title: rpk connect mcp-server latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-connect/rpk-connect-mcp-server page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-connect/rpk-connect-mcp-server.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-connect/rpk-connect-mcp-server.adoc description: Execute an MCP server against a suite of Redpanda Connect resources. page-git-created-date: "2025-09-22" page-git-modified-date: "2025-09-22" support-status: supported --- Executes an MCP server against a suite of Redpanda Connect resources. Each resource is exposed as a tool for AI interaction. ## [](#usage)Usage rpk connect mcp-server \[command options\] Each resource will be exposed as a tool that AI can interact with: rpk connect mcp-server ./repo ## [](#subcommands)Subcommands - [init](../rpk-connect-mcp-server-init/): Create the basic folder structure of an MCP server. - [lint](../rpk-connect-mcp-server-lint/): Parse Redpanda Connect configs and report any linting errors. - help, h: Shows a list of commands or help for one command. ## [](#options)Options | Option | Description | | --- | --- | | --address | An optional address to bind the MCP server to instead of running in stdio mode. | | --tag meta.tags | Optionally limit the resources that this command runs by providing one or more regular expressions. Resources that do not contain a match within the field meta.tags for each tag regular expression specified will be ignored. | | --secrets env: | Attempt to load secrets from a provided URN. If more than one entry is specified they will be attempted in order until a value is found. Environment variable lookups are specified with the URN env:, which by default is the only entry. In order to disable all secret lookups specify a single entry of none:. (default: "env:") | | --env-file, -e | Import environment variables from a dotenv file. | | --redpanda-license | Provide an explicit Redpanda License, which enables enterprise functionality. By default licenses found at the path /etc/redpanda/redpanda.license are applied. | | --help, -h | Show help for the command. | --- # Page 337: rpk connect run **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-connect/rpk-connect-run.md --- # rpk connect run --- title: rpk connect run latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-connect/rpk-connect-run page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-connect/rpk-connect-run.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-connect/rpk-connect-run.adoc page-git-created-date: "2024-05-30" page-git-modified-date: "2024-08-01" support-status: supported --- Run Redpanda Connect in normal mode against a specified config file. ## [](#usage)Usage ```bash rpk connect run [command options] [arguments...] ``` ## [](#example)Example ```bash rpk connect run ./foo.yaml ``` ## [](#flags)Flags ## [](#flags-2)Flags | Value | Type | Description | | --- | --- | --- | | --log.level | - | Override the configured log level. Available values: off, error, warn, info, debug, trace | | --set | - | Set a field (identified by a dot path) in the main configuration file. For example: metrics.type=prometheus | | --resources, -r | - | Pull in extra resources from a file, which can be referenced by the same as resources defined in the main config. This supports glob patterns (requires quotes). | | --chilled | - | Continue to execute a config containing linter errors (default: false). | | --watcher, -w | - | EXPERIMENTAL: Watch config files for changes and automatically apply them (default: false). | | --env-file, -e | - | Import environment variables from a dotenv file. | | --templates, -t | - | EXPERIMENTAL: Import Redpanda Connect templates. This supports glob patterns (requires quotes). | | --set | - | Set a field (identified by a dot path) in the main configuration file. For example: metrics.type=prometheus | --- # Page 338: rpk connect streams **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-connect/rpk-connect-streams.md --- # rpk connect streams --- title: rpk connect streams latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-connect/rpk-connect-streams page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-connect/rpk-connect-streams.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-connect/rpk-connect-streams.adoc page-git-created-date: "2024-05-30" page-git-modified-date: "2024-07-26" support-status: supported --- Run Redpanda Connect in streams mode, where multiple pipelines can be executed in a single process and can be created, updated, and removed with REST HTTP endpoints. In streams mode, the stream fields of a root target configuration (input, buffer, pipeline, output) are ignored. Other fields are shared across all loaded streams (resources, metrics, etc.). See [Streams Mode](../../../../../redpanda-connect/guides/streams_mode/about/). ## [](#usage)Usage ```bash rpk connect streams [command options] [arguments...] ``` ## [](#examples)Examples ```bash rpk connect streams ``` ```bash rpk connect streams -o ./root_config.yaml ``` ```bash rpk connect streams ./path/to/stream/configs ./and/some/more ``` ```bash rpk connect streams -o ./root_config.yaml ./streams/*.yaml ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --no-api | - | Disable the HTTP API for streams mode (default: false). | | --observability, -o | - | Specify a path to a service wide configuration file, which can include observability configuration, such as metrics, logger, and tracing sections. | | --prefix-stream-endpoints | - | Whether HTTP endpoints registered by stream configs should be prefixed with the stream ID (default: true). | | --help, -h | - | Show help. | --- # Page 339: rpk connect studio pull **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-connect/rpk-connect-studio-pull.md --- # rpk connect studio pull --- title: rpk connect studio pull latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-connect/rpk-connect-studio-pull page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-connect/rpk-connect-studio-pull.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-connect/rpk-connect-studio-pull.adoc page-git-created-date: "2024-05-30" page-git-modified-date: "2024-05-30" support-status: supported --- Run deployments configured within a Redpanda Connect session. When a Studio session has one or more deployments added, this command synchronizes with the session and obtains a deployment assignment. The assigned deployment then determines which configs from the session to download and execute. When changes are made to files of an assigned deployment, or when a new deployment is assigned, this service automatically downloads the new config files and executes them, replacing the previous running stream. ## [](#usage)Usage ```bash rpk connect studio pull [command options] [arguments...] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --session, -s | - | The session ID to synchronize with. | | --name | - | An explicit name to adopt in this instance, used to identify its connection to the session. Each running node must have a unique name. If left unset, a name is generated each time the command is run. | | --token, -h | - | A token for the session, used to authenticate requests. If left blank, the environment variable BSTDIO_NODE_TOKEN is used. | | --token-secret | - | A token secret the session, used to authenticate requests. If left blank, the environment variable BSTDIO_NODE_SECRET is used. | | --send-traces | - | Whether to send trace data back to Studio during execution. This is an opt-in way to add trace events to the graph editor for testing and debugging configs. This is a very useful feature, but use it with caution, because it exports information about messages passing through the stream (default: false). | | --help, -h | - | Show help. | --- # Page 340: rpk connect studio sync-schema **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-connect/rpk-connect-studio-sync-schema.md --- # rpk connect studio sync-schema --- title: rpk connect studio sync-schema latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-connect/rpk-connect-studio-sync-schema page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-connect/rpk-connect-studio-sync-schema.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-connect/rpk-connect-studio-sync-schema.adoc page-git-created-date: "2024-05-30" page-git-modified-date: "2024-05-30" support-status: supported --- Synchronizes the schema of this Redpanda Connect instance with a Studio session. This sync allows custom plugins and templates to be configured and linted correctly within Benthos Studio. To synchronize a single use, a token must be generated from the session page within the Studio application. ## [](#usage)Usage ```bash rpk connect studio sync-schema [command options] [arguments...] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --session, -s | - | The session ID to synchronize with. | | --token, -t | - | The single use token used to authenticate the request. | | --help, -h | - | Show help. | --- # Page 341: rpk connect template lint **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-connect/rpk-connect-template-lint.md --- # rpk connect template lint --- title: rpk connect template lint latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-connect/rpk-connect-template-lint page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-connect/rpk-connect-template-lint.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-connect/rpk-connect-template-lint.adoc page-git-created-date: "2024-05-30" page-git-modified-date: "2024-05-30" support-status: supported --- Parse Redpanda Connect templates and report any linting errors. Exits with a status code 1 if any linting errors are detected. If a path ends with `…​`, Redpanda Connect lints any files with the `.yaml` or `.yml` extension. ## [](#usage)Usage ```bash rpk connect template lint [command options] [arguments...] ``` ## [](#examples)Examples ```bash rpk connect template lint ``` ```bash rpk connect template lint ./templates/*.yaml ``` ```bash rpk connect template lint ./foo.yaml ./bar.yaml ``` ```bash rpk connect template lint ./templates/... ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --help, -h | - | Show help. | --- # Page 342: rpk connect test **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-connect/rpk-connect-test.md --- # rpk connect test --- title: rpk connect test latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-connect/rpk-connect-test page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-connect/rpk-connect-test.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-connect/rpk-connect-test.adoc page-git-created-date: "2024-05-30" page-git-modified-date: "2024-05-30" support-status: supported --- Execute any number of Redpanda Connect unit test definitions. If any tests fail, the process reports the errors and exits with a status code 1. See [Unit Testing](../../../../../redpanda-connect/configuration/unit_testing/). ## [](#usage)Usage ```bash /opt/redpanda/bin/.rpk.ac-connect test [command options] [arguments...] ``` ## [](#examples)Examples ```bash rpk connect test ./path/to/configs/... ``` ```bash rpk connect test ./foo_configs/*.yaml ./bar_configs/*.yaml ``` ```bash rpk connect test ./foo.yaml ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --log | - | Allow components to write logs at a provided level to stdout. | | --help, -h | - | Show help. | --- # Page 343: rpk connect uninstall **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-connect/rpk-connect-uninstall.md --- # rpk connect uninstall --- title: rpk connect uninstall latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-connect/rpk-connect-uninstall page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-connect/rpk-connect-uninstall.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-connect/rpk-connect-uninstall.adoc page-git-created-date: "2024-10-02" page-git-modified-date: "2024-10-02" support-status: supported --- Uninstall the Redpanda Connect plugin. ## [](#usage)Usage ```bash rpk connect uninstall [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for uninstall. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 344: rpk connect upgrade **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-connect/rpk-connect-upgrade.md --- # rpk connect upgrade --- title: rpk connect upgrade latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-connect/rpk-connect-upgrade page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-connect/rpk-connect-upgrade.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-connect/rpk-connect-upgrade.adoc page-git-created-date: "2024-10-02" page-git-modified-date: "2024-10-02" support-status: supported --- Upgrade to the latest Redpanda Connect version. ## [](#usage)Usage ```bash rpk connect upgrade [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --no-confirm | - | Disable confirmation prompt for major version upgrades. | | -h, --help | - | Help for upgrade. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 345: rpk connect **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-connect/rpk-connect.md --- # rpk connect --- title: rpk connect latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-connect/rpk-connect page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-connect/rpk-connect.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-connect/rpk-connect.adoc description: These commands let you create and manage data pipelines using Redpanda Connect. page-git-created-date: "2024-05-30" page-git-modified-date: "2024-10-02" support-status: supported --- Create and manage data pipelines using Redpanda Connect. For full details, see the [Redpanda Connect documentation](../../../../../redpanda-connect/get-started/about/). ## [](#usage)Usage ```bash rpk connect [command] [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for connect. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 346: rpk container purge **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-container/rpk-container-purge.md --- # rpk container purge --- title: rpk container purge latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-container/rpk-container-purge page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-container/rpk-container-purge.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-container/rpk-container-purge.adoc page-git-created-date: "2023-05-17" page-git-modified-date: "2024-07-24" support-status: supported --- Stop and remove an existing local container cluster’s data. ## [](#usage)Usage ```bash rpk container purge [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for purge. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 347: rpk container start **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-container/rpk-container-start.md --- # rpk container start --- title: rpk container start latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-container/rpk-container-start page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-container/rpk-container-start.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-container/rpk-container-start.adoc page-git-created-date: "2023-05-17" page-git-modified-date: "2024-12-03" support-status: supported --- Start a local container cluster. This command uses Docker to initiate a local container cluster. Use the `--nodes` (or the shorthand version `-n`) flag to specify the number of brokers. The initial broker starts on default ports, with subsequent brokers' ports offset by 1000. You can use the following flags to specify listener ports: - `--kafka-ports` - `--admin-ports` - `--rpc-ports` - `--schema-registry-ports` - `--proxy-ports` Each flag accepts a comma-separated list of ports for your listeners. Use the `--any-port` flag to let `rpk` randomly select an available port on the host machine. In case of IP address pool conflict, you may specify a custom subnet and gateway using the `--subnet` and `--gateway` flags respectively. By default, this command uses the `redpandadata/redpanda:latest` Redpanda container image. You can specify a container image by using the `--image` flag. See the available images at [Docker Hub](#https://hub.docker.com/r/redpandadata/redpanda/tags). ## [](#usage)Usage ```bash rpk container start [flags] ``` ## [](#examples)Examples Start a three-broker cluster: ```bash rpk container start -n 3 ``` Start a single-broker cluster, selecting random ports for every listener: ```bash rpk container start --any-port ``` Start a 3-broker cluster, selecting the seed kafka and console port only: ```bash rpk container start --kafka-ports 9092 --console-port 8080 ``` Start a three-broker cluster, specifying the Admin API port for each broker: ```bash rpk container start --admin-ports 9644,9645,9646 ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --admin-ports | strings | Redpanda Admin API ports to listen on; check help text for more information. | | --any-port | - | Opt in for any (random) ports in all listeners. | | --console-image | string | An arbitrary Redpanda Console container image to use (default redpandadata/console:latest). | | --console-port | string | Redpanda Console ports to listen on; check help text for more information (default 8080). | | --gateway | string | Gateway IP address for the subnet. Must be in the subnet address range (default 172.24.1.1). | | -h, --help | - | Help for start. | | --image | string | An arbitrary container Redpanda image to use (default redpandadata/redpanda:v26.1.3). | | --kafka-ports | strings | Kafka protocol ports to listen on; check help text for more information. | | --no-profile | - | If true, rpk will not create an rpk profile after creating a cluster. | | -n, --nodes | uint | The number of brokers (nodes) to start (default 1). | | --proxy-ports | strings | HTTP Proxy ports to listen on; check help text for more information. | | --pull | - | Force pull the container image used. | | --retries | uint | The amount of times to check for the cluster before considering it unstable and exiting (default 10). | | --rpc-ports | strings | RPC ports to listen on; check help text for more information. | | --schema-registry-ports | strings | Schema Registry ports to listen on; check help text for more information. | | --subnet | string | Subnet to create the cluster network on (default 172.24.1.0/24). | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | ## [](#see-also)See also - [QuickStart - Deploy Redpanda to Docker with a Single Broker](../../../../get-started/quick-start/#tabs-1-single-brokers) - [QuickStart - Deploy Redpanda to Docker with Three Nodes](../../../../get-started/quick-start/#tabs-1-three-brokers) --- # Page 348: rpk container status **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-container/rpk-container-status.md --- # rpk container status --- title: rpk container status latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-container/rpk-container-status page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-container/rpk-container-status.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-container/rpk-container-status.adoc page-git-created-date: "2023-08-04" page-git-modified-date: "2025-08-21" support-status: supported --- Get a local container’s status. ## [](#usage)Usage ```bash rpk container status [flags] ``` ## [](#example)Example If you’re following [QuickStart - Deploy Redpanda to Docker with Three Nodes](../../../../get-started/quick-start/#tabs-1-three-brokers), you can run `rpk container status` to see more information about your containers: ```bash rpk container status NODE-ID STATUS KAFKA-ADDRESS ADMIN-ADDRESS PROXY-ADDRESS SCHEMA-REGISTRY-ADDRESS 0 running 127.0.0.1:9092 127.0.0.1:9644 127.0.0.1:8082 127.0.0.1:8081 Redpanda Console started in: http://localhost:8080 You can use rpk to interact with this cluster. E.g: rpk cluster info rpk cluster health You may also set an environment variable with the comma-separated list of broker addresses: export RPK_BROKERS="127.0.0.1:34189,127.0.0.1:45523,127.0.0.1:37223" rpk cluster info ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for status. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 349: rpk container stop **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-container/rpk-container-stop.md --- # rpk container stop --- title: rpk container stop latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-container/rpk-container-stop page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-container/rpk-container-stop.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-container/rpk-container-stop.adoc page-git-created-date: "2023-05-17" page-git-modified-date: "2024-07-24" support-status: supported --- Stop an existing local container cluster. ## [](#usage)Usage ```bash rpk container stop [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for stop. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 350: rpk container **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-container/rpk-container.md --- # rpk container --- title: rpk container latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-container/rpk-container page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-container/rpk-container.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-container/rpk-container.adoc description: These commands let you manage (start, stop, purge) a local container cluster. page-git-created-date: "2023-05-17" page-git-modified-date: "2024-07-24" support-status: supported --- Manage a local container cluster. ## [](#usage)Usage ```bash rpk container [command] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | -h, --help | - | Help for container. | | --config | string | Redpanda or rpk config file; default search paths are /var/lib/redpanda/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. | | -X, --config-opt | stringArray | Override rpk configuration settings. See rpk -X or execute rpk -X help for inline detail or rpk -X list for terser detail. | | --profile | string | Profile to use. See rpk profile for more details. | | -v, --verbose | - | Enable verbose logging. | --- # Page 351: rpk debug bundle **URL**: https://docs.redpanda.com/current/reference/rpk/rpk-debug/rpk-debug-bundle.md --- # rpk debug bundle --- title: rpk debug bundle latest-redpanda-tag: v26.1.3 latest-console-tag: v3.7.1 latest-operator-version: v26.1.2 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: March 31, 2027 latest-connect-version: 4.87.0 docname: rpk/rpk-debug/rpk-debug-bundle page-component-name: ROOT page-version: "26.1" page-component-version: "26.1" page-component-title: Self-Managed page-relative-src-path: rpk/rpk-debug/rpk-debug-bundle.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/reference/pages/rpk/rpk-debug/rpk-debug-bundle.adoc description: This command generates a diagnostics bundle for troubleshooting Redpanda deployments. page-git-created-date: "2023-05-17" page-git-modified-date: "2025-12-12" support-status: supported --- > 📝 **NOTE** > > In Kubernetes, you must run the `rpk debug bundle` command inside a container that’s running a Redpanda broker. ## [](#concept)Concept The `rpk debug bundle` command collects environment data that can help debug and diagnose issues with a Redpanda cluster, a broker, or the machine it’s running on. It then bundles the collected data into a ZIP file, called a diagnostics bundle. ### [](#diagnostic-bundle-files)Diagnostic bundle files The files and directories in the diagnostics bundle differ depending on the environment in which Redpanda is running: ### [](#common-files)Common files - Kafka metadata: Broker configs, topic configs, start/committed/end offsets, groups, group commits. - Controller logs: The controller logs directory up to a limit set by --controller-logs-size-limit flag - Data directory structure: A file describing the data directory’s contents. - redpanda configuration: The redpanda configuration file (`redpanda.yaml`; SASL credentials are stripped). - /proc/cpuinfo: CPU information like make, core count, cache, frequency. - /proc/interrupts: IRQ distribution across CPU cores. - Resource usage data: CPU usage percentage, free memory available for the redpanda process. - Clock drift: The ntp clock delta (using pool.ntp.org as a reference) and round trip time. - Admin API calls: Cluster and broker configurations, cluster health data, CPU profiles, and license key information. - Broker metrics: The broker’s Prometheus metrics, fetched through its admin API (/metrics and /public\_metrics). ### [](#bare-metal)Bare-metal - Kernel: The kernel logs ring buffer (syslog) and parameters (sysctl). - DNS: The DNS info as reported by 'dig', using the hosts in /etc/resolv.conf. - Disk usage: The disk usage for the data directory, as output by 'du'. - Redpanda logs: The broker’s Redpanda logs written to `journald` since `yesterday` (00:00:00 of the previous day based on `systemd.time`). If `--logs-since` or `--logs-until` is passed, only the logs within the resulting time frame are included. - Socket info: The active sockets data output by 'ss'. - Running process info: As reported by 'top'. - Virtual memory stats: As reported by 'vmstat'. - Network config: As reported by 'ip addr'. - lspci: List the PCI buses and the devices connected to them. - dmidecode: The DMI table contents. Only included if this command is run as root. ### [](#extra-requests-for-partitions)Extra requests for partitions You can provide a list of partitions to save additional admin API requests specifically for those partitions. The partition flag accepts the format `/[topic]/[partitions…​]` where the namespace is optional, if the namespace is not provided, `rpk` will assume 'kafka'. For example: Topic 'foo', partitions 1, 2 and 3: ```bash --partitions foo/1,2,3 ``` Namespace \_redpanda-internal, topic 'bar', partition 2 ```bash --partitions _redpanda-internal/bar/2 ``` If you have an upload URL from the Redpanda support team, provide it in the --upload-url flag to upload your diagnostics bundle to Redpanda. ## [](#kubernetes)Kubernetes - Kubernetes Resources: Kubernetes manifests for all resources in the given Kubernetes namespace using `--namespace`, or the shorthand version `-n`. - redpanda logs: Logs of each Pod in the given Kubernetes namespace. If `--logs-since` is passed, only the logs within the given timeframe are included. ## [](#usage)Usage ```bash rpk debug bundle [flags] ``` ## [](#flags)Flags | Value | Type | Description | | --- | --- | --- | | --controller-logs-size-limit | string | Sets the limit of the controller log size that can be stored in the bundle. Multipliers are also supported, e.g. 3MB, 1GiB (default 132MB). | | --cpu-profiler-wait | duration | Specifies the duration for collecting samples for the CPU profiler (for example, 30s, 1.5m). Must be higher than 15s (default 30s). | | -h, --help | - | Display documentation for rpk debug bundle. | | --kafka-connections-limit | int | The maximum number of Kafka connections to store in the bundle (k8s only). Default 256. | | -l, --label-selector | stringArray | Comma-separated label selectors to filter your resources. e.g: