Rpk Topic

rpk topic: Manage, Produce & Consume

rpk topic is the rpk command group for all topic-level operations on a Redpanda cluster. It wraps the Kafka protocol to create, inspect, alter, and delete topics, and provides full-featured produce and consume commands with a powerful percent-escape format language. All subcommands read connection config from the active rpk profile or -X flags.

Quickstart

# 1. Create a 3-partition topic with replication factor 3
rpk topic create orders -p 3 -r 3

# 2. Create with configs set at creation time
rpk topic create events -p 6 -r 3 \
  -c cleanup.policy=compact \
  -c retention.ms=86400000

# 3. Produce three keyed JSON records — key and value on each line (Ctrl-D to finish)
# Note: when %k appears in --format, it reads the key from the input line and
# takes precedence over any -k flag. Use one mechanism or the other, not both.
rpk topic produce orders -f '%k %v{json}\n'
order-1 {"id":1,"status":"pending"}
order-2 {"id":2,"status":"shipped"}
order-3 {"id":3,"status":"delivered"}

# 4. Produce a single record inline via stdin redirect
printf 'hello world\n' | rpk topic produce orders

# 5. Consume from the beginning and stop at current end
rpk topic consume orders -o start

# 6. Consume last 5 records
rpk topic consume orders -o -5

# 7. Consume from a specific offset until current end
rpk topic consume orders -o 100:end

# 8. Consume in a named consumer group
rpk topic consume orders -g my-service

# 9. Describe the topic (summary + configs by default)
rpk topic describe orders

# 10. Describe including partition detail
rpk topic describe orders -p

# 11. Alter a topic config
rpk topic alter-config orders --set retention.ms=3600000

# 12. Delete a topic config key (revert to cluster default)
rpk topic alter-config orders --delete retention.ms

# 13. Add 2 more partitions
rpk topic add-partitions orders -n 2

# 14. List all topics
rpk topic list

# 15. Delete a topic
rpk topic delete orders

Subcommands

create

rpk topic create <TOPICS...> [flags]

# Compact topic
rpk topic create audit-log -p 12 -r 3 -c cleanup.policy=compact

# Dry run
rpk topic create test-topic -p 3 -r 3 -d

list

rpk topic list [TOPICS...] [flags]

rpk topic list
rpk topic list -r '^orders.*'
rpk topic list -d

describe

rpk topic describe <TOPICS...> [flags]

By default prints the summary and configs sections. Sections:

rpk topic describe orders -a
rpk topic describe -r '^events.*' -a

alter-config

rpk topic alter-config <TOPICS...> [flags]

Supports four operations (all repeatable):

# Enable tiered storage on a topic
rpk topic alter-config orders \
  --set redpanda.remote.read=true \
  --set redpanda.remote.write=true

# Change retention
rpk topic alter-config orders --set retention.ms=86400000

# Revert retention to cluster default
rpk topic alter-config orders --delete retention.ms

# Apply one change to every topic matching an expression
rpk topic alter-config -r '^events-.*' --set retention.ms=86400000

-r/--regex uses the same anchored expression format as rpk topic list -r and rpk topic delete -r, so list first to preview exactly which topics an expression will alter.

add-partitions

rpk topic add-partitions <TOPICS...> -n <N> [flags]

-n is required. Partitions can only be added, never removed.

rpk topic add-partitions orders -n 6

trim-prefix

Moves the log start offset (low watermark) forward, deleting segments before the specified offset. Data before the new start offset is no longer readable.

rpk topic trim-prefix [TOPIC] -o <OFFSET> [flags]

# Trim partition 0 to offset 1000
rpk topic trim-prefix orders -o 1000 -p 0

# Trim all partitions to a timestamp
rpk topic trim-prefix orders -o "@2024-01-01T00:00:00Z"

# Trim to the current end (delete everything)
rpk topic trim-prefix orders -o end

analyze

Consumes a time window of records and reports batch rate and size statistics.

rpk topic analyze <TOPICS...> [flags]

rpk topic analyze orders -t -1h:end -a
rpk topic analyze -r '^orders.*' -t -24h:end -s --print-topics

describe-storage

Requires the Admin API endpoint (from your profile or -X admin.hosts=...). Shows tiered storage cloud vs. local bytes, segment counts, offsets, and sync lag per partition. Not supported on Redpanda Cloud clusters (the Admin API is not exposed there); all other rpk topic subcommands are.

rpk topic describe-storage <TOPIC> [flags]

rpk topic describe-storage orders -a -H

Cloud storage modes: disabled, write_only, read_only, full, read_replica, cloud_topic, cloud_topic_read_replica, tiered_cloud_topic. The three cloud-topic modes print the L0/L1 SIZE layout rather than the segment-based tiered-storage one; see manage.md for the column sets.

delete

rpk topic delete <TOPICS...> [flags]

-r, --regex parses topic names as regular expressions. Expressions are anchored with ^ and $.

rpk topic delete old-topic
rpk topic delete -r '^test-.*'

produce

See Produce Reference for full detail.

rpk topic produce [TOPIC] [flags]

Key flags:

# Fixed key, newline-delimited values from stdin
rpk topic produce orders -k order-key

# Key and value separated by space
rpk topic produce orders -f '%k %v\n'

# Add headers
rpk topic produce orders -H source:backend -H env:prod

# Encode with schema registry (TopicName strategy)
rpk topic produce orders --schema-id=topic

# Tombstone
rpk topic produce orders -k deleted-key -Z

consume

See Consume Reference for full detail.

rpk topic consume <TOPICS...> [flags]

Key flags:

# Consume all records from beginning
rpk topic consume orders -o start

# Consume last 10 records
rpk topic consume orders -o -10

# Consume in a group, print key+value
rpk topic consume orders -g my-svc -f '%k %v\n'

# Consume a timestamp window
rpk topic consume orders -o @2024-01-01:1h

# Stop at current end
rpk topic consume orders -o :end

# Decode values via schema registry
rpk topic consume orders --use-schema-registry=value

Redpanda Cloud notes

rpk topic works against Redpanda Cloud clusters (Serverless, BYOC, Dedicated) over the Kafka API. Authenticate with rpk cloud login and wire your profile to the cluster (rpk cloud cluster select, or rpk profile create --from-cloud); plain rpk topic ... commands then target the Cloud cluster.

• All rpk topic subcommands are supported on Cloud except rpk topic describe-storage, which needs the Admin API (not exposed by Redpanda Cloud).
• Automatic topic creation is disabled in Redpanda Cloud — create topics explicitly. BYOC/Dedicated clusters can opt in via the auto_create_topics_enabled cluster property.
• Replication factor: Redpanda Cloud requires a minimum of 3 replicas; a topic created with -r 1 is reset to 3.
• Message size: capped per topic by max.message.bytes; the default and maximum differ by cluster type (Serverless caps are lower than BYOC/Dedicated). Check the Cloud "Topics Overview" page for current values rather than assuming self-managed defaults.
• Partition limits: Serverless clusters have a per-cluster partition cap (logical partitions, pre-replication) plus other usage limits (consumer groups, connections, ACLs, producer IDs) — see "Serverless usage limits" on the Serverless cluster-type page of the cloud docs. BYOC/Dedicated partition maxima depend on the usage tier — see the "BYOC Tiers and Regions" / "Dedicated Tiers and Regions" reference pages. These numbers change; do not hardcode them.
• Managed cluster defaults: cluster properties (e.g. default_topic_partitions) are not user-configurable on Serverless, and on BYOC/Dedicated (AWS/GCP only) only a curated subset is settable.
• Tiered Storage on Cloud is enabled and configured by Redpanda by default. The Enterprise topic properties section below is written for self-managed clusters — note rpk cluster license is also unsupported on Cloud.
• TODO (unverified): the cloud docs do not publish an explicit list of which topic-level configs are settable versus rejected/managed on Serverless. Before advising a specific alter-config --set key on Serverless, verify against a live cluster or the Cloud UI.

Enterprise topic properties

Several Redpanda differentiators are configured as topic-level properties through rpk topic create -c key=value or rpk topic alter-config <topic> --set key=value. All of these require a valid Enterprise Edition license; without one they cannot be enabled, and they enter a restricted state on license expiration. Verify license status with rpk cluster license info.

# Tiered Storage
rpk topic alter-config orders --set redpanda.storage.mode=tiered

# Iceberg topic
rpk topic create txns --topic-config=redpanda.iceberg.mode=key_value

# Leader Pinning
rpk topic alter-config orders --set redpanda.leaders.preference=ordered_racks:A,B,C

# Schema ID validation
rpk topic alter-config events --set redpanda.value.schema.id.validation=true

See enterprise-topic-properties.md for the full nested key list, accepted values, defaults, and expiration behavior.

Reference Directory

• produce.md: rpk topic produce in depth — format percent-escape tokens, keys, headers, compression, acks, schema-registry encoding, tombstones, and worked examples.
• consume.md: rpk topic consume in depth — all --offset forms (numeric, relative, timestamp, ranges), consumer groups, format tokens, schema-registry decoding, and worked examples.
• manage.md: create, alter-config, add-partitions, describe, describe-storage, trim-prefix, analyze, and delete — with key config keys for retention, compaction, and tiered storage.
• enterprise-topic-properties.md: Enterprise-licensed topic properties set via create -c / alter-config --set — Tiered Storage (redpanda.remote.*, redpanda.storage.mode, retention.local.target.*), Cloud Topics (redpanda.cloud_topic.enabled), Iceberg Topics (redpanda.iceberg.mode/delete/partition.spec/target.lag.ms/invalid.record.action), Remote Read Replicas (redpanda.remote.readreplica), Leader Pinning (redpanda.leaders.preference), and Schema ID Validation (redpanda.key/value.schema.id.validation, subject.name.strategy), with accepted values, defaults, and license-expiration behavior.