Object Storage Properties

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 to form the complete credentials required for authentication. To authenticate using IAM roles, see cloud_storage_credentials_source.

Optional API endpoint. The only instance in which you must set this value is when using a custom domain with your object storage service.

TLS port override.

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.

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.

Azure Data Lake Storage v2 port override. See also: cloud_storage_azure_adls_endpoint. Use when hierarchical namespaces are enabled on your storage account and you have set up a custom endpoint.

The name of the Azure container to use with Tiered Storage. If null, the property is disabled.

Force Redpanda to use or not use an Azure Data Lake Storage (ADLS) Gen2 hierarchical namespace-compliant client in cloud_storage_azure_storage_account.

When this property is not set, 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.

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 to azure_vm_instance_metadata. See IAM Roles for more information on managed identities.

Type: string

Default: null

Requires restart: No

Supported versions: Redpanda v24.1 or later

The account access key to be used for Azure Shared Key authentication with the Azure storage account configured by cloud_storage_azure_storage_account. If null, the property is disabled.

Requires restart: Yes

The name of the Azure storage account to use with Tiered Storage. If null, the property is disabled.

Optional object storage backend variant used to select API capabilities. If not supplied, this will be inferred from other configuration properties.

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.

AWS or GCP bucket that should be used to store data.

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.

Size of chunks of segments downloaded into object storage cache. Reduces space usage by only downloading the necessary chunk from a segment.

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.

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.

Maximum size of the object storage cache, in bytes.

This property works together with cloud_storage_cache_size_percent to define cache behavior:

Maximum size of the cache as a percentage, minus the space that Redpanda avoids using defined by the 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 changes.

This property works together with cloud_storage_cache_size to define cache behavior:

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.

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.

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.

Selects a strategy for evicting unused cache chunks.

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.

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.

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.

Number of attempts metadata operations may be retried.

Time interval to wait between cluster metadata uploads.

Timeout for cluster metadata uploads.

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). 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.

The hostname to connect to for retrieving role based credentials. Derived from 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.

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.

Path to certificate revocation list for cloud_storage_trust_file.

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.

Use legacy upload mode and do not start archiver_manager.

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.

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.

If true, Redpanda disables remote labels and falls back on the hash-based object naming scheme for new topics.

Disable TLS for all object storage connections.

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.

Begins the upload loop in topic partitions with Tiered Storage enabled. The property exists to simplify testing and shouldn’t be set in production.

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.

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.

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.

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.

Enable routine checks (scrubbing) of object storage partitions. The scrubber validates the integrity of data and metadata uploaded to object storage.

Enables adjacent segment merging. The segments are reuploaded if there is an opportunity for that and if it will improve the tiered-storage performance

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 cluster configuration and redpanda.remote.allowgaps topic properties control local retention behavior.

Enable object storage. Must be set to true to use Tiered Storage or Remote Read Replicas.

Interval, in milliseconds, between a final scrub and the next scrub.

Timeout for running the cloud storage garbage collection, in milliseconds.

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.

Time limit on waiting for uploads to complete before a leadership transfer. If this is null, leadership transfers proceed without waiting.

Interval, in milliseconds, between object storage housekeeping tasks.

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.

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.

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.

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.

Initial backoff time for exponential backoff algorithm (ms).

Scrubber uses the latest cloud storage inventory report, if available, to check if the required objects exist in the bucket or container.

The name of the scheduled inventory job created by Redpanda to generate bucket or container inventory reports.

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.

Time interval between checks for a new inventory report in the cloud storage bucket or container.

The prefix to the path in the cloud storage bucket or container where inventory reports will be placed.

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.

Amount of memory that can be used to handle Tiered Storage metadata.

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.

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.

Manifest upload timeout, in milliseconds.

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.

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.

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.

Maximum simultaneous object storage connections per shard, applicable to upload and download activities.

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.

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.

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.

Timeout for Use Tiered Storage metadata synchronization.

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.

Time interval between two partial scrubs of the same partition.

Timeout to check if new data is available for partitions in object storage for read replicas.

Retention in bytes for topics created during automated recovery.

Number of metadata segments to validate, from newest to oldest, when cloud_storage_recovery_topic_validation_mode is set to check_manifest_and_segment_metadata.

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:

Example: Redpanda validates the topic kafka/panda-topic-recovery-NOT-OK and stops due to a fatal error on partition 0:

Each failing partition error message has the following format:

At the end of the process, Redpanda outputs a final ERROR message:

Cloud provider region that houses the bucket or container used for storage.

Timeout for IAM role related operations (ms).

Jitter applied to the object storage scrubbing interval.

Cloud provider secret key.

Time that a segment can be kept locally without uploading it to the object storage, in seconds.

Smallest acceptable segment size in the object storage. Default: cloud_storage_segment_size_target/2.

Desired segment size in the object storage. The default is set in the topic-level segment.bytes property.

Log segment upload timeout, in milliseconds.

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.

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.

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.

Grace period during which the purger refuses to purge the topic.

Path to certificate that should be used to validate server certificate during TLS handshake.

Derivative coefficient for upload PID controller.

Maximum number of I/O and CPU shares that archival upload can use.

Minimum number of I/O and CPU shares that archival upload can use.

Proportional coefficient for upload PID controller.

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.

Initial backoff interval when there is nothing to upload for a partition, in milliseconds.

Maximum backoff interval when there is nothing to upload for a partition, in milliseconds.