Rpk Redpanda

rpk redpanda: Node Lifecycle, Tuning & Broker Decommission

The rpk redpanda family operates a single Redpanda broker process and its host node: starting/stopping the process, editing the node's local redpanda.yaml, tuning the Linux kernel for production, and talking to a broker's Admin API listener (including broker decommission/recommission). rpk iotune (a separate top-level command) benchmarks the node's disk hardware for the same node-provisioning story.

Self-managed only. These commands manage the broker process on the node itself. They are not applicable to Redpanda Cloud (Serverless, BYOC, Dedicated), where Redpanda operates the brokers. Most of the family is also Linux-only: start, stop, mode, check, tune, config, and iotune are hidden on macOS/Windows builds of rpk — only the admin subtree (which talks to a possibly-remote Admin API) is available everywhere.

Command Tree

| Command | Purpose | |---|---| | rpk redpanda start | Start the local broker process (optionally tuning first) | | rpk redpanda stop | Stop the local broker: SIGINT → SIGTERM → SIGKILL escalation | | rpk redpanda mode | Switch node presets: production/prod, development/dev, recovery | | rpk redpanda check | Verify the system meets Redpanda's requirements | | rpk redpanda tune ... \| all | The autotuner — optimize Linux kernel settings (root required) | | rpk redpanda tune list | List tuners with enabled/supported status | | rpk redpanda tune help [TUNER] | Describe a tuner in detail | | rpk redpanda config bootstrap | Generate redpanda.yaml to form/join a cluster | | rpk redpanda config set | Set node config values in redpanda.yaml | | rpk redpanda config print | Display the node configuration (alias: dump) | | rpk redpanda config init | (Deprecated) Set the node UUID after install | | rpk redpanda admin brokers list | List brokers via the admin listener (alias: ls) | | rpk redpanda admin brokers decommission | Remove a broker from the cluster (moves its replicas away) | | rpk redpanda admin brokers decommission-status | Monitor decommission progress | | rpk redpanda admin brokers recommission | Abort an in-progress decommission | | rpk redpanda admin partitions list [ID] | List the partitions hosted on one broker | | rpk redpanda admin config print | Display a broker's effective configuration | | rpk redpanda admin config log-level set | Temporarily change a broker's logger levels | | rpk iotune | Benchmark disk I/O and write io-config.yaml for the broker to read at startup |

Quickstart

# --- Provision a production node (run on the node, as root where noted) ---

# 1. Generate redpanda.yaml with this node's IP and the seed servers
rpk redpanda config bootstrap --self  --ips ,,

# 2. Switch the node to production mode (enables the production tuner set)
rpk redpanda mode production

# 3. Run the autotuner (requires root; Linux kernel settings)
sudo rpk redpanda tune all

# 4. Benchmark disk I/O once per hardware type (defaults: 10m run,
#    writes /etc/redpanda/io-config.yaml which redpanda reads at startup)
sudo rpk iotune

# 5. Verify the system meets requirements, then start
rpk redpanda check
rpk redpanda start

# --- Development: one-shot local broker with dev presets ---
rpk redpanda start --mode dev-container

# --- Stop the local broker (SIGINT, then SIGTERM, then SIGKILL) ---
rpk redpanda stop --timeout 10s

# --- Node configuration (redpanda.yaml on local disk) ---
rpk redpanda config set redpanda.empty_seed_starts_cluster false
rpk redpanda config set rpk.tune_aio_events true
rpk redpanda config print

# --- Broker decommission (works from any machine; talks to the Admin API) ---
rpk redpanda admin brokers list
rpk redpanda admin brokers decommission 4
rpk redpanda admin brokers decommission-status 4 -d -H   # monitor
rpk redpanda admin brokers recommission 4                # abort (only while in progress)

# --- Per-broker diagnostics via the admin listener ---
rpk redpanda admin partitions list 1 --leader-only
rpk redpanda admin config print --host 0
rpk redpanda admin config log-level set storage -l debug -e 300

Decision Rules

• rpk redpanda vs rpk cluster: rpk redpanda is node-level (the

local process, the local redpanda.yaml, per-broker admin operations). rpk cluster is cluster-wide (cluster config, health, partition balancing/movement, maintenance mode, self-test) — see the rpk-cluster skill.

• Broker decommission lives here. There is no rpk cluster brokers

command group — decommission/recommission are rpk redpanda admin brokers ....

• Maintenance mode is NOT here. Draining leadership for a rolling

restart is rpk cluster maintenance enable/disable/status (rpk-cluster skill). Entering maintenance mode before decommissioning is optional — decommission drains leadership gracefully on its own.

• Node config vs cluster config: properties in the local

redpanda.yaml (listeners, seeds, data dir, rpk.tune_* tuner flags) are set with rpk redpanda config set and generally need a broker restart. Cluster-wide properties (retention, tiered storage, etc.) are rpk cluster config set and propagate to all nodes.

• tune vs iotune: rpk redpanda tune (the autotuner) modifies

Linux kernel settings; rpk iotune benchmarks the disks and writes an I/O properties file that redpanda reads at startup. A production node wants both. iotune output is reusable across nodes with identical hardware.

• Which node does a command touch? start, stop, mode, check,

tune, config, and iotune act on the local machine. The admin subtree targets whatever rpk.admin_api.addresses (or -X admin.hosts=...) points at, so it can be run from anywhere.

• Not for local dev containers: to spin up throwaway local clusters in

Docker, use rpk container (see the rpk skill) instead of rpk redpanda start.

Broker Decommission (Top-Tier Ops Task)

Decommissioning permanently removes a broker: the controller leader moves all of its partition replicas to the remaining brokers, then removes it from the cluster. A decommissioned broker cannot rejoin, and its node ID must never be reused.

# 1. Pre-check: cluster healthy, and remaining brokers can absorb the data
rpk cluster health
rpk redpanda admin brokers list

# 2. Start the decommission
rpk redpanda admin brokers decommission 4

# 3. Monitor until every partition reaches 100% (add -d for bytes moved/remaining)
rpk redpanda admin brokers decommission-status 4 -d -H

# 4. Changed your mind while it is still moving data? Abort:
rpk redpanda admin brokers recommission 4

# 5. When complete, verify removal, then shut the node's process down
rpk redpanda admin brokers list --include-decommissioned

Before decommissioning, confirm the remaining broker count still satisfies the highest topic replication factor, rack-awareness spread, disk capacity, and partition-per-core limits. If progress stalls, check for leaderless partitions and consider raising raft_learner_recovery_rate. Full pre-checks, failure modes, --force semantics, and the maintenance-mode interaction are in [admin-and-decommission.md](references/admin-and-decommission.md).

The Autotuner and iotune

rpk redpanda tune identifies the node's hardware and optimizes the Linux kernel for Redpanda (disk IRQs, scheduler, AIO limits, swappiness, CPU governor, and more). Run it as root, as part of production deployment, on every broker node. Do not run it in Azure self-managed environments.

sudo rpk redpanda tune all          # run every enabled tuner
rpk redpanda tune list              # tuners + enabled/supported status (live source of truth)
rpk redpanda tune help       # what one tuner does
sudo rpk iotune                     # disk benchmark -> /etc/redpanda/io-config.yaml

The available tuners and their support status vary by kernel, hardware, and cloud — always introspect with rpk redpanda tune list rather than relying on a static list. Each tuner is toggled by an rpk.tune_* key in redpanda.yaml (for example rpk.tune_aio_events), set via rpk redpanda config set; rpk redpanda mode production enables the production tuner set in one step. Details, IRQ modes (sq/sq_split/mq), the redpanda-tuner systemd service, and iotune reuse across identical hardware are in [node-lifecycle-and-tuning.md](references/node-lifecycle-and-tuning.md).

Reference Directory

• [node-lifecycle-and-tuning.md](references/node-lifecycle-and-tuning.md):

rpk redpanda start (flags, --mode dev-container, tuning-at-start, well-known-io), stop (signal escalation), mode (production/development/recovery semantics), check, the autotuner (tune, tune list, tune help, IRQ modes, systemd unit), and rpk iotune (flags, output file, reuse workflow).

• [admin-and-decommission.md](references/admin-and-decommission.md): the

rpk redpanda admin subtree — brokers list/decommission/ decommission-status/recommission with the full safe-decommission workflow, capacity pre-checks, stall troubleshooting, and maintenance-mode interaction; partitions list; config print; and config log-level set.

• [config-bootstrap.md](references/config-bootstrap.md): node configuration —

rpk redpanda config bootstrap (forming a cluster, --self, --ips, advertised addresses), config set (dot paths, YAML/JSON values, arrays), config print, the deprecated config init, and node-vs-cluster config rules.

• [SOURCES.md](references/SOURCES.md): source map — where each claim comes

from and what is deferred to live introspection.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: redpanda-data
• Source: redpanda-data/skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.