From 7699ad983c0b978f932eee102f74052b763ef999 Mon Sep 17 00:00:00 2001 From: Michael Ernest Date: Wed, 18 Mar 2026 12:13:25 -0700 Subject: [PATCH 1/6] fix(DOC-1675): document --overprovisioned flag and improve rpk redpanda start prose - Add missing --overprovisioned flag to the flags table with a description explaining that it disables thread affinity to allow fairer CPU distribution and must not be used in production environments - Fix several pre-existing prose issues: lowercase 'redpanda' in prose, 'setup' used as a verb, missing comma after introductory clause, future tense 'will disable/enable', 'terser', and weak constructions Co-Authored-By: Claude Sonnet 4.6 --- .../rpk/rpk-redpanda/rpk-redpanda-start.adoc | 22 ++++++++++--------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc index 2a226b075f..35f4620056 100644 --- a/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc +++ b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc @@ -5,18 +5,18 @@ include::reference:partial$unsupported-os-rpk.adoc[] Start Redpanda. -== Setting up a mode +== Set up a mode -It's possible to setup a mode for redpanda to start. Currently we support the mode `dev-container`. +You can set up a mode for Redpanda to use on start. -To set up the mode `dev-container` run: +To set up the `dev-container` mode, run: [,bash] ---- rpk redpanda start --mode dev-container ---- -Mode uses well-known configuration properties for development or tests +The mode uses well-known configuration properties for development and test environments: Bundled flags: @@ -35,7 +35,7 @@ Bundled cluster properties: * `topic_partitions_per_shard: 1000` * `fetch_reads_debounce_timeout: 10` -After redpanda starts you can modify the cluster properties using: +After Redpanda starts, you can modify the cluster properties by running: [,bash] ---- @@ -78,7 +78,7 @@ Pandaproxy addresses to advertise. : ---- -|--check |- |When set to `false`, will disable system checking before +|--check |- |When set to `false`, disables system checking before starting `redpanda` (default `true`). |-h, --help |- |Help for start. @@ -98,6 +98,8 @@ development or test environments; use `--mode help` for more info. |--node-tuner-state-path |string |Alternative path to read the node tuner state file from (if exists). +|--overprovisioned |- |Disables thread affinity (CPU pinning) to allow fairer CPU distribution among all processes. Do not use in production environments. Set automatically by `--mode dev-container`. + |--pandaproxy-addr |strings |A comma-separated list of Pandaproxy listener addresses to bind to. @@ -131,11 +133,11 @@ to. |--timeout |duration |The maximum time to wait for the checks and tune processes to complete. The value passed is a sequence of decimal -numbers, each with optional fraction and a unit suffix, such as +numbers, each with an optional fraction and a unit suffix, such as `300ms`, `1.5s` or `2h45m`. Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h` (default 10s). -|--tune |- |When present will enable tuning before starting `redpanda`. +|--tune |- |Enables tuning before starting `redpanda`. |--well-known-io |string |The cloud vendor and VM type, in the format @@ -144,9 +146,9 @@ numbers, each with optional fraction and a unit suffix, such as :: ---- -|--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`. +|--config |string |Path to the Redpanda or `rpk` configuration file. If not specified, `rpk` searches `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. -|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. +|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terse detail. |--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. From 641895b01e4a294a64c765e8e706fe7f416db1f7 Mon Sep 17 00:00:00 2001 From: Michael Ernest Date: Mon, 23 Mar 2026 20:24:13 -0700 Subject: [PATCH 2/6] style(DOC-1675): remove \"You can\" and redundant phrasing in dev-container section Co-Authored-By: Claude Sonnet 4.6 --- .../pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc index 35f4620056..1da78608c8 100644 --- a/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc +++ b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc @@ -7,7 +7,7 @@ Start Redpanda. == Set up a mode -You can set up a mode for Redpanda to use on start. +Redpanda supports a `dev-container` mode with preset configuration for development and test environments. To set up the `dev-container` mode, run: @@ -16,8 +16,7 @@ To set up the `dev-container` mode, run: rpk redpanda start --mode dev-container ---- -The mode uses well-known configuration properties for development and test -environments: +This mode bundles the following flags and cluster properties: Bundled flags: @@ -35,7 +34,7 @@ Bundled cluster properties: * `topic_partitions_per_shard: 1000` * `fetch_reads_debounce_timeout: 10` -After Redpanda starts, you can modify the cluster properties by running: +After Redpanda starts, modify the cluster properties by running: [,bash] ---- From 058eac2d3541705f2061f0ca0ad92bf676012409 Mon Sep 17 00:00:00 2001 From: Michael Ernest Date: Tue, 24 Mar 2026 11:30:39 -0700 Subject: [PATCH 3/6] style(DOC-1675): apply Michele style tweaks to rpk-redpanda-start prose Co-Authored-By: Claude Sonnet 4.6 --- .../reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc index 1da78608c8..675501df24 100644 --- a/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc +++ b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc @@ -34,7 +34,7 @@ Bundled cluster properties: * `topic_partitions_per_shard: 1000` * `fetch_reads_debounce_timeout: 10` -After Redpanda starts, modify the cluster properties by running: +After Redpanda starts, you can modify cluster properties by running: [,bash] ---- @@ -97,7 +97,7 @@ development or test environments; use `--mode help` for more info. |--node-tuner-state-path |string |Alternative path to read the node tuner state file from (if exists). -|--overprovisioned |- |Disables thread affinity (CPU pinning) to allow fairer CPU distribution among all processes. Do not use in production environments. Set automatically by `--mode dev-container`. +|--overprovisioned |- |Disables thread affinity (CPU pinning) to allow fairer CPU distribution among all processes. Do not use in production environments. Set automatically when using `--mode dev-container`. |--pandaproxy-addr |strings |A comma-separated list of Pandaproxy listener addresses to bind to. From 9059e63380b799c4b9be9e17df8c9317420f45b2 Mon Sep 17 00:00:00 2001 From: Michael Ernest Date: Tue, 24 Mar 2026 15:53:27 -0700 Subject: [PATCH 4/6] fix(DOC-1675): remove --overprovisioned from flags table; xref mode page The --overprovisioned flag is a Seastar passthrough, not an rpk flag, so it does not appear in rpk help output and will be dropped on any future regen. Document it via xref to rpk-redpanda-mode.adoc, which already has a full explanation (including the Seastar reference). Co-Authored-By: Claude Sonnet 4.6 --- .../reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc index 675501df24..62e26e6053 100644 --- a/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc +++ b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc @@ -20,7 +20,7 @@ This mode bundles the following flags and cluster properties: Bundled flags: -* `--overprovisioned` +* xref:reference:rpk/rpk-redpanda/rpk-redpanda-mode.adoc[`--overprovisioned`] * `--reserve-memory 0M` * `--check=false` * `--unsafe-bypass-fsync` @@ -97,8 +97,6 @@ development or test environments; use `--mode help` for more info. |--node-tuner-state-path |string |Alternative path to read the node tuner state file from (if exists). -|--overprovisioned |- |Disables thread affinity (CPU pinning) to allow fairer CPU distribution among all processes. Do not use in production environments. Set automatically when using `--mode dev-container`. - |--pandaproxy-addr |strings |A comma-separated list of Pandaproxy listener addresses to bind to. From a3fe122fd93aa11b5c99996bad85a63a4b3d86e7 Mon Sep 17 00:00:00 2001 From: Michael Ernest Date: Tue, 24 Mar 2026 16:23:00 -0700 Subject: [PATCH 5/6] style(DOC-1675): apply style guide fixes to rpk-redpanda-start prose - Reword lead-in to direct imperative (no "To [verb], run:") - Remove "you can" weak construction - Fix "--timeout" description awkward phrasing ("tune processes") Co-Authored-By: Claude Sonnet 4.6 --- .../pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc index 62e26e6053..0d4abf60f7 100644 --- a/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc +++ b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc @@ -9,7 +9,7 @@ Start Redpanda. Redpanda supports a `dev-container` mode with preset configuration for development and test environments. -To set up the `dev-container` mode, run: +Run the following command to start Redpanda in `dev-container` mode: [,bash] ---- @@ -34,7 +34,7 @@ Bundled cluster properties: * `topic_partitions_per_shard: 1000` * `fetch_reads_debounce_timeout: 10` -After Redpanda starts, you can modify cluster properties by running: +After Redpanda starts, modify cluster properties by running: [,bash] ---- @@ -128,11 +128,7 @@ to. ::\| ---- -|--timeout |duration |The maximum time to wait for the checks and tune -processes to complete. The value passed is a sequence of decimal -numbers, each with an optional fraction and a unit suffix, such as -`300ms`, `1.5s` or `2h45m`. Valid time units are `ns`, `us` -(or `µs`), `ms`, `s`, `m`, `h` (default 10s). +|--timeout |duration |The maximum time to wait for the system checks and tuning processes to complete. The value passed is a sequence of decimal numbers, each with an optional fraction and a unit suffix, such as `300ms`, `1.5s` or `2h45m`. Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h` (default 10s). |--tune |- |Enables tuning before starting `redpanda`. From 5218dd5e47f5f9dc4d5efb647442ea3e876b0c2b Mon Sep 17 00:00:00 2001 From: Michael Ernest Date: Thu, 26 Mar 2026 10:52:10 -0700 Subject: [PATCH 6/6] fix(DOC-1675): restore auto-gen flags table to main; keep manual zone only Per Michele's review: manual edits to the auto-generated flags table will be overwritten on the next rpk doc regeneration. Restoring the flags table to main's version; retaining only the safe manual zone changes (heading, prose rewrite, overprovisioned xref). Co-Authored-By: Claude Sonnet 4.6 --- .../rpk/rpk-redpanda/rpk-redpanda-start.adoc | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc index 0d4abf60f7..ef14d86d29 100644 --- a/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc +++ b/modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc @@ -34,7 +34,7 @@ Bundled cluster properties: * `topic_partitions_per_shard: 1000` * `fetch_reads_debounce_timeout: 10` -After Redpanda starts, modify cluster properties by running: +After Redpanda starts, you can modify cluster properties by running: [,bash] ---- @@ -77,7 +77,7 @@ Pandaproxy addresses to advertise. : ---- -|--check |- |When set to `false`, disables system checking before +|--check |- |When set to `false`, will disable system checking before starting `redpanda` (default `true`). |-h, --help |- |Help for start. @@ -128,9 +128,13 @@ to. ::\| ---- -|--timeout |duration |The maximum time to wait for the system checks and tuning processes to complete. The value passed is a sequence of decimal numbers, each with an optional fraction and a unit suffix, such as `300ms`, `1.5s` or `2h45m`. Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h` (default 10s). +|--timeout |duration |The maximum time to wait for the checks and tune +processes to complete. The value passed is a sequence of decimal +numbers, each with optional fraction and a unit suffix, such as +`300ms`, `1.5s` or `2h45m`. Valid time units are `ns`, `us` +(or `µs`), `ms`, `s`, `m`, `h` (default 10s). -|--tune |- |Enables tuning before starting `redpanda`. +|--tune |- |When present will enable tuning before starting `redpanda`. |--well-known-io |string |The cloud vendor and VM type, in the format @@ -139,9 +143,9 @@ to. :: ---- -|--config |string |Path to the Redpanda or `rpk` configuration file. If not specified, `rpk` searches `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`. +|--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 xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terse detail. +|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. |--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details.