diff --git a/docs-data/rpk-overrides.json b/docs-data/rpk-overrides.json index d226cc1525..bc7b0dd9ee 100644 --- a/docs-data/rpk-overrides.json +++ b/docs-data/rpk-overrides.json @@ -338,7 +338,7 @@ "flags": "g" }, { - "description": "Wrap bare flag with adjacent format/value word as inline code before auto-backtick step splits them (e.g. -f json -> `‌-f json`, --format yaml -> `--format yaml`)", + "description": "Wrap bare flag with adjacent format/value word as inline code before auto-backtick step splits them (e.g. -f json -> `\u200c-f json`, --format yaml -> `--format yaml`)", "pattern": "(?iIqQc.$]} |The unpack modifier has a further internal specification, similar to timestamps above.\n|===\n\nUnpacking text can allow translating binary input into readable output. If a value is a big-endian uint32, `%v` prints the raw four bytes, while `%v{unpack[>I]}` prints the number as ASCII. If unpacking exhausts the input before something is unpacked fully, an error message is appended to the output." + "content": "Text fields without modifiers default to writing the raw bytes. Alternatively, there are the following modifiers:\n\n[cols=\"1m,2a\"]\n|===\n|Modifier |Description\n\n|%t{hex} |Hex encoding\n|%k{base64} |Base64 standard encoding\n|%k{base64raw} |Base64 encoding raw\n|%v{unpack[iIqQc.$]} |The unpack modifier has a further internal specification, similar to timestamps above.\n|===\n\nUnpacking text can allow translating binary input into readable output. If a value is a big-endian uint32, `%v` prints the raw four bytes, while `%v{unpack[>I]}` prints the number as ASCII. If unpacking exhausts the input before something is unpacked fully, an error message is appended to the output.\n\nThe unpack modifier has a further internal specification:\n\n[cols=\"1m,2a\"]\n|===\n|Character |Meaning\n\n|x |Pad character (does not parse input)\n|< |Switch what follows to little endian\n|> |Switch what follows to big endian\n|b |Signed byte\n|B |Unsigned byte\n|h |int16 (\"half word\")\n|H |uint16 (\"half word\")\n|i |int32\n|I |uint32\n|q |int64 (\"quad word\")\n|Q |uint64 (\"quad word\")\n|c |Any character\n|. |Alias for `c`\n|s |Consume the rest of the input as a string\n|$ |Match the end of the line (append error string if anything remains)\n|===" }, { "type": "section", @@ -756,7 +760,7 @@ "position": "after_usage", "parent": "usage", "headingLevel": 3, - "content": "Headers are formatted with percent encoding inside of the modifier:\n\n[,bash]\n----\n%h{%k=%v{hex}}\n----\n\nThis prints all headers with a space before the key and after the value, an equals sign between the key and value, and with the value hex encoded. Header formatting actually just parses the internal format as a record format, so all of the above rules about `%K`, `%V`, text, and numbers apply." + "content": "Headers are formatted with percent encoding inside of the modifier:\n\n[,bash]\n----\n%h{ %k=%v{hex} }\n----\n\nThis prints all headers with a space before the key and after the value, an equals sign between the key and value, and with the value hex encoded. Header formatting actually just parses the internal format as a record format, so all of the above rules about `%K`, `%V`, text, and numbers apply." }, { "type": "section", @@ -776,6 +780,12 @@ "headingLevel": 3, "content": "The `--offset` flag allows for specifying where to begin consuming, and optionally, where to stop consuming. The literal words `start` and `end` specify consuming from the start and the end.\n\n[cols=\"1m,2a\"]\n|===\n|Offset |Description\n\n|start |Consume from the beginning\n|end |Consume from the end\n|:end |Consume until the current end\n|+oo |Consume oo after the current start offset\n|-oo |Consume oo before the current end offset\n|oo |Consume after an exact offset\n|oo: |Alias for oo\n|:oo |Consume until an exact offset\n|o1:o2 |Consume from exact offset o1 until exact offset o2\n|@t |Consume starting from a given timestamp\n|@t: |Alias for @t\n|@:t |Consume until a given timestamp\n|@t1:t2 |Consume from timestamp t1 until timestamp t2\n|===\n\nEach timestamp option is evaluated until one succeeds.\n\n[cols=\"1m,2a\"]\n|===\n|Timestamp |Description\n\n|13 digits |Parsed as a unix millisecond\n|9 digits |Parsed as a unix second\n|YYYY-MM-DD |Parsed as a day, UTC\n|YYYY-MM-DDTHH:MM:SSZ |Parsed as RFC3339, UTC; fractional seconds optional (.MMM)\n|-dur |Duration; from now (as t1) or from t1 (as t2)\n|dur |For t2 in @t1:t2, relative duration from t1\n|end |For t2 in @t1:t2, the current end of the partition\n|===\n\nDurations are parsed simply:\n\n[,bash]\n----\n3ms three milliseconds\n10s ten seconds\n9m nine minutes\n1h one hour\n1m3ms one minute and three milliseconds\n----" }, + { + "type": "section", + "title": "Connection behavior", + "position": "after_usage", + "content": "By default, `rpk topic consume` runs continuously, waiting for new records to arrive. It does not exit after consuming existing records. To stop consuming, press Ctrl+C. You can also use `--num` to exit after a fixed number of records, or use `--offset` to define a stop point (for example, `-o :end` stops at the current log end)." + }, { "type": "section", "id": "examples", @@ -847,7 +857,7 @@ "pageAliases": "reference:rpk/rpk-redpanda/rpk-redpanda-admin.adoc" }, "rpk cluster config": { - "description": "View and modify cluster-wide configuration properties. Changes take effect across all brokers.", + "description": "View and modify Redpanda cluster configuration properties.\n\nModified properties are propagated immediately to all brokers. Use `rpk cluster config status` to verify that all brokers are up to date, and to identify any settings that were rejected, for example, if a broker is still restarting.", "$refs": [ "#/definitions/common-admin-flags" ], @@ -879,7 +889,6 @@ ] }, "rpk cluster storage mount": { - "description": "Mount a topic from Tiered Storage, making it available for reads.", "$refs": [ "#/definitions/common-admin-flags" ], @@ -912,7 +921,6 @@ ] }, "rpk cluster storage unmount": { - "description": "Unmount a topic, removing it from local storage while preserving data in Tiered Storage.", "$refs": [ "#/definitions/common-admin-flags" ], @@ -1021,7 +1029,6 @@ "description": "Check the status of a mount or unmount operation for a topic in Tiered Storage." }, "rpk group": { - "description": "Manage Kafka consumer groups, including listing groups, viewing lag, and resetting offsets.", "$refs": [ "#/definitions/common-kafka-flags", "#/definitions/common-tls-flags" @@ -1029,7 +1036,6 @@ "pageAliases": "reference:rpk/rpk-group.adoc" }, "rpk group describe": { - "description": "Display detailed information about a consumer group, including member assignments, lag per partition, and group state.", "flags": { "lag": { "description": "Show consumer lag information: current offset, log end offset, and lag per partition." @@ -1105,7 +1111,7 @@ } }, "rpk connect lint": { - "description": "Check a Redpanda Connect configuration file for syntax errors and potential issues without running it.", + "description": "Check a Redpanda Connect configuration file for syntax errors and potential issues without running it.\n\nThis command exits with status code 1 if any linting errors are detected.", "flags": {}, "content": [ { @@ -1134,7 +1140,7 @@ ] }, "rpk connect test": { - "description": "Run unit tests defined in Redpanda Connect configuration files to verify pipeline behavior.", + "description": "Run unit tests defined in Redpanda Connect configuration files to verify pipeline behavior.\n\nIf one or more tests fail, the command reports the errors and exits with status code 1.", "flags": {}, "seeAlso": [ "xref:connect:configuration:unit_testing.adoc[Unit Testing]" @@ -1162,7 +1168,6 @@ ] }, "rpk profile": { - "description": "Manage rpk configuration profiles. Profiles store connection settings for different clusters, making it easy to switch between environments.", "flags": {}, "pageAliases": "reference:rpk/rpk-profile.adoc" }, @@ -1182,7 +1187,6 @@ ] }, "rpk profile set": { - "description": "Set a configuration field in the current rpk profile.", "content": [ { "type": "include", @@ -1196,7 +1200,7 @@ "flags": {} }, "rpk security acl": { - "description": "Manage Kafka ACLs (Access Control Lists) for authorization. ACLs control which principals can perform operations on resources.", + "description": "Manage ACLs and SASL users.\n\nThis command space creates, lists, and deletes ACLs, as well as creates SASL users. This page is specific to ACLs. To learn about SASL users, see xref:reference:rpk/rpk-security/rpk-security-user.adoc[`rpk security user`].\n\nWhen using SASL, ACLs allow or deny you access to certain requests. The `create`, `delete`, and `list` commands help you manage your ACLs.\n\nAn ACL is made up of five components:\n\n* A principal (the user) or role\n* A host, which the principal (or role) is allowed or denied requests from\n* What resource to access (such as a topic name or group ID)\n* The operation (such as read or write)\n* The permission: whether to allow or deny the above\n\nACL commands work on a multiplicative basis. If creating, specifying two principals and two permissions creates four ACLs: both permissions for the first principal, as well as both permissions for the second principal. Adding two resources further doubles the ACLs created.\n\nIt is recommended to be as specific as possible when granting ACLs. Granting more ACLs than necessary per principal may inadvertently allow clients to do things they should not, such as deleting topics or joining the wrong consumer group.\n\nIn flag form, to set up a general producing and consuming client, you can invoke `rpk security acl create` three times with the following (including your `--allow-principal`):\n\n* `--operation write,read,describe --topic [topics]`\n* `--operation describe,read --group [group.id]`\n* `--operation describe,write --transactional-id [id]`", "$refs": [ "#/definitions/common-kafka-flags", "#/definitions/common-tls-flags" @@ -1316,12 +1320,12 @@ { "type": "note", "position": "after_usage", - "content": "The schema migration examples above are Schema Registry ACLs only. You also require Kafka ACLs for topics, consumer groups, and cluster operations. See xref:manage:security/authorization/acl.adoc[Configure Access Control Lists]." + "content": "The schema migration examples on this page are Schema Registry ACLs only. You also require Kafka ACLs for topics, consumer groups, and cluster operations. See xref:manage:security/authorization/acl.adoc[Configure Access Control Lists]." } ] }, "rpk connect list": { - "description": "List available Redpanda Connect components. Shows inputs, outputs, processors, caches, rate limits, buffers, metrics, and tracers that can be used in pipelines.", + "description": "List available Redpanda Connect components. Shows inputs, outputs, processors, caches, rate limits, buffers, metrics, and tracers that can be used in pipelines.\n\nIf any component types are explicitly listed, only types of those components are shown.\n\nWhen using `--format jsonschema` with `bloblang-functions` or `bloblang-methods`, you can optionally specify function or method names to retrieve metadata for only those items, for example `rpk connect list --format jsonschema bloblang-functions uuid_v4`.", "flags": { "format": { "description": "Output format: `text` (human-readable table), `json` (machine-readable), `cue` (CUE schema). Default is `text`." @@ -1357,7 +1361,6 @@ "path": "shared:partial$warning-delete-records.adoc" } ], - "description": "Trim records from topics by setting the LogStartOffset for partitions to the requested offset. All segments whose base offset is less than the requested offset are deleted, and any records within the segment before the requested offset can no longer be read.", "flags": { "from-file": { "description": "Path to a file specifying topic, partition, and offset values to trim." @@ -1365,7 +1368,6 @@ } }, "rpk group offset-delete": { - "description": "Forcefully delete offsets for a Kafka group.", "flags": { "from-file": { "description": "Path to a file containing topic/partition tuples for which to delete offsets." @@ -1426,8 +1428,7 @@ } ] } - ], - "description": "Modify a group's current offsets.\n\nThis command allows you to modify a group's offsets. Sometimes, you may need to rewind a group if you had a mistaken deploy, or fast-forward a group if it is falling behind.\n\nThe `--to` option allows you to seek to a specific offset, or to the start or end of partitions. The offset can be at any timestamp precision (seconds since epoch, millis since epoch, etc). The start and end options are self explanatory. If any partition is deleted and recreated (a la `rpk topic delete; rpk topic create`), the prior commits are wiped out and the group will be committed to the earliest offset (similar to if specifying start).\n\nThe `--to-group` option allows you to seek to commits that are in another group. This is a merging operation: if g1 is consuming topics A and B, and g2 is consuming only topic B, `rpk group seek g1 --to-group g2` will update g1's commits for topic B only. The `--topics` flag can be used to further narrow which topics are updated. Unlike `--to`, all non-filtered topics are committed, even topics not yet being consumed, meaning `--allow-new-topics` is not needed.\n\nThe `--to-file` option allows to seek to offsets specified in a text file with the following format:\n\n[,text]\n----\n \n \n...\n----\n\nEach line contains the topic, the partition, and the offset to seek to. As with the prior options, `--topics` allows filtering which topics are updated. Similar to `--to-group`, all non-filtered topics are committed, even topics not yet being consumed, meaning `--allow-new-topics` is not needed.\n\nThe `--to`, `--to-group`, and `--to-file` options are mutually exclusive. If you are not authorized to describe or read some topics used in a group, you will not be able to modify offsets for those topics." + ] }, "rpk cluster partitions unsafe-recover": { "content": [ @@ -1466,7 +1467,6 @@ ] }, "rpk topic list": { - "description": "List topics, optionally listing specific topics. This command lists all topics that you have access to by default.", "flags": { "regex": { "description": "Filter topics using regular expressions. Expressions are automatically anchored with `^` and `$`, so they must match the full topic name." @@ -1490,7 +1490,6 @@ ] }, "rpk cluster health": { - "description": "Query cluster health and display the overall health status of the cluster. Redpanda collects health reports periodically from all nodes and aggregates them into a health overview.", "flags": { "watch": { "description": "Continuously monitor health status, refreshing periodically." @@ -1502,26 +1501,15 @@ "$refs": [ "#/definitions/common-admin-flags" ], - "content": [ - { - "type": "section", - "id": "health-criteria", - "title": null, - "position": "after_description", - "content": "A cluster is considered healthy when the following conditions are met:\n\n* All cluster nodes are responding\n* All partitions have leaders\n* The cluster controller is present" - } - ], "selfHostedOnly": true }, "rpk cluster maintenance": { - "description": "Manage cluster maintenance mode for performing rolling upgrades and other maintenance operations.", "$refs": [ "#/definitions/common-admin-flags" ], "selfHostedOnly": true }, "rpk cluster maintenance enable": { - "description": "Enable maintenance mode on a broker. While in maintenance mode, the broker drains partition leadership to other brokers. Use this command before performing broker upgrades or hardware maintenance. After maintenance is complete, run `rpk cluster maintenance disable ` to restore normal operation.", "flags": { "node": { "description": "Node ID to put into maintenance mode." @@ -1532,6 +1520,13 @@ }, "$refs": [ "#/definitions/common-admin-flags" + ], + "content": [ + { + "type": "section", + "position": "after_description", + "content": "Use this command before performing broker upgrades or hardware maintenance. After maintenance is complete, run `rpk cluster maintenance disable ` to restore normal operation." + } ] }, "rpk cluster maintenance disable": { @@ -1609,7 +1604,6 @@ "pageAliases": "features:guide-rpk-container.adoc, deployment:guide-rpk-container.adoc" }, "rpk generate app": { - "description": "Generate application code to connect to Redpanda. Creates starter code for various programming languages.", "content": [ { "type": "cloud-only", @@ -1620,15 +1614,6 @@ "type": "self-hosted", "position": "after_description", "content": "If you are having trouble connecting to your cluster, you can use the common xref:reference:rpk/rpk-x-options.adoc#adminhosts[`-X admin.hosts=`] flag to pass a specific Admin API address." - }, - { - "type": "section", - "id": "supported-languages", - "title": "Supported languages", - "position": "after_usage", - "content": "The following programming languages are supported:\n\n* Python\n* Go\n* Java\n* JavaScript/Node.js\n* Rust", - "parent": "usage", - "headingLevel": 3 } ], "flags": { @@ -1771,9 +1756,6 @@ } } }, - "rpk cluster license set": { - "description": "Upload a license to the cluster using a file path, inline string, or default location." - }, "rpk cluster partitions disable": {}, "rpk cluster partitions enable": {}, "rpk cluster partitions list": { @@ -1814,7 +1796,6 @@ "content": "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 partitions using `rpk cluster partitions enable/disable`." } ], - "description": "List partitions in the cluster. This command lists the cluster-level metadata of all partitions, including current replica assignments on brokers and CPU cores for given topics.", "flags": { "all": { "description": "List all partitions in the cluster." @@ -1843,7 +1824,6 @@ }, "rpk cluster partitions move": { "pageAliases": "reference:rpk/rpk-cluster/rpk-cluster-partitions-movement.adoc", - "description": "Move partition replicas across nodes / cores.\n\nThis command changes replica assignments for given partitions. By default, it\nassumes the `kafka` namespace, but you can specify an internal namespace using\nthe `{namespace}/` prefix.", "content": [ { "type": "section", @@ -1890,9 +1870,6 @@ } } }, - "rpk cluster partitions balance": { - "description": "Trigger on-demand partition balancing to redistribute partitions evenly across brokers. Redpanda automatically balances partitions when it detects imbalance; run this command to trigger balancing manually." - }, "rpk cluster partitions transfer-leadership": { "content": [ { @@ -1982,7 +1959,7 @@ } }, "rpk cluster quotas import": { - "description": "Use this command to import client quotas in the format produced by `rpk cluster quotas describe --format json/yaml`.", + "description": "Use this command to import client quotas in the format produced by `rpk cluster quotas describe --format json/yaml`.\n\nThe schema of the import string matches the schema from `rpk cluster quotas describe --format help`:\n\n[,text]\n----\n{\n quotas: []{\n entity: []{\n name: string\n type: string\n }\n values: []{\n key: string\n values: string\n }\n }\n}\n----\n\nUse the `--no-confirm` flag if you wish to avoid the confirmation prompt.", "content": [ { "type": "section", @@ -1995,23 +1972,8 @@ ] }, "rpk cluster self-test start": { - "description": "Starts one or more benchmark tests on one or more nodes of the cluster.", "seeAlso": [ "xref:reference:rpk/rpk-cluster/rpk-cluster-self-test-status.adoc[`rpk cluster self-test status`]" - ], - "content": [ - { - "type": "note", - "position": "after_description", - "content": "Redpanda self-test runs benchmarks that consume significant system resources. Do not start self-test if large workloads are already running on the system." - }, - { - "type": "section", - "id": "available-tests", - "title": null, - "position": "after_description", - "content": "Available tests to run:\n\n* *Disk tests*\n** Throughput test: 512 KB messages, sequential read/write\n*** Uses 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.\n** Latency test: 4 KB messages, sequential read/write\n*** Uses smaller request message sizes and lower levels of parallelism to achieve higher IOPS and lower latency.\n* *Network tests*\n** Throughput test: 8192-bit messages\n*** Unique pairs of Redpanda nodes each act as a client and a server.\n*** The test pushes as much data over the wire, within the test parameters.\n* *Cloud storage tests*\n** Configuration/latency test: 1024-byte object.\n** If cloud storage is enabled (xref:reference:properties/object-storage-properties.adoc#cloud_storage_enabled[`cloud_storage_enabled`]), a series of remote operations are performed:\n+\n--\ninclude::reference:partial$rpk-self-test-cloud-tests.adoc[]\n--\n\nThis command prompts users for confirmation (unless the flag `--no-confirm` is specified), then returns a test identifier ID, and runs the tests.\n\nTo view the test status, poll xref:reference:rpk/rpk-cluster/rpk-cluster-self-test-status.adoc[`rpk cluster self-test status`]. Once the tests end, the cached results will be available with `rpk cluster self-test status`." - } ] }, "rpk cluster self-test status": { @@ -2221,7 +2183,7 @@ } }, "rpk debug remote-bundle download": { - "description": "Download the debug bundle from a remote cluster configured in flags, environment variables, or your rpk profile.", + "description": "Download the debug bundle from a remote cluster configured in flags, environment variables, or your rpk profile.\n\nUse the `--job-id` flag to only download the debug bundle with the given job ID.\n\nUse the `--no-confirm` flag to avoid the confirmation prompt.", "content": [ { "type": "section", @@ -2255,7 +2217,6 @@ "content": "The selected dashboard is downloaded from Redpanda Data's https://github.com/redpanda-data/observability[observability GitHub repository^].\n\nNOTE: The legacy dashboard is still available as an option (`legacy`), but it isn't downloaded from GitHub. Instead, the generated dashboard is based on which metrics endpoint is used (`--metrics-endpoint`)." } ], - "description": "Generate Grafana dashboards for Redpanda metrics. Use this command to generate sample Grafana dashboards that can be imported into a Grafana or Grafana Cloud instance.", "flags": { "dashboard": { "description": "The name of the dashboard to download. Use `--dashboard=help` to list available dashboards." @@ -2280,7 +2241,6 @@ "content": "Consumer groups are automatically deleted when the last committed offset expires. Group offset deletion can happen through:\n\n* Kafka `OffsetDelete` API: Offsets can be explicitly deleted using the Kafka `OffsetDelete` API. See xref:reference:rpk/rpk-group/rpk-group-offset-delete.adoc[`rpk group offset delete`].\n* Periodic offset expiration: Offsets expire automatically when the group has been empty for a set duration." } ], - "description": "Delete one or more consumer groups from Redpanda brokers. A group must have no active members to be deleted.", "flags": { "format": { "introducedInVersion": "v26.2.1" @@ -2291,9 +2251,6 @@ "pageAliases": "reference:rpk/rpk-plugin.adoc" }, "rpk profile edit-globals": {}, - "rpk profile prompt": { - "description": "Prompt a profile name formatted for a PS1 prompt.\n\nThis command prints ANSI-escaped text per your current profile's `prompt`\nfield. If the current profile does not have a prompt, this prints nothing.\nIf the prompt is invalid, this exits 0 with no message. To validate the\ncurrent prompt, use the `--validate` flag.\n\nThis command may introduce other `%` variables in the future, if you want to\nprint a `%` directly, use `%%` to escape it.\n\nTo use this in zsh, be sure to add setopt PROMPT_SUBST to your .zshrc.\nTo edit your PS1, use something like `PS1='$(rpk profile prompt)` in your\nshell rc file." - }, "rpk profile set-globals": {}, "rpk registry context": { "seeAlso": [ @@ -2450,7 +2407,7 @@ ] } ], - "description": "Describe one or more shadow links. For Redpanda Cloud, `rpk` uses the Redpanda ID of the cluster you are currently logged in to.", + "description": "Describe one or more shadow links. For Redpanda Cloud, `rpk` uses the Redpanda ID of the cluster you are currently logged in to.\n\nThis command shows the Shadow Link configuration, including connection settings, synchronization options, and filters. By default, the command displays the overview and client configuration sections. Use the flags to display additional sections such as topic synchronization, consumer offset synchronization, and security synchronization settings.\n\nUsing the `--format` flag with JSON or YAML outputs the full configuration in the specified format, ignoring section flags.", "flags": { "print-role": { "introducedInVersion": "v26.2.1" @@ -2478,7 +2435,6 @@ } }, "rpk topic describe-storage": { - "description": "Describe the cloud storage status of a topic, including storage mode, offset availability, segment sizes, and synchronization state.", "flags": { "human-readable": { "description": "Print times (in milliseconds) and byte values in human-readable units (for example, 1.2 GiB, 3m 20s)." @@ -2652,7 +2608,7 @@ ] }, "rpk connect echo": { - "description": "Parse a config file and echo back a normalized version. This command is useful for sanity checking a config if it isn't behaving as expected, as it shows you a normalised version after environment variables have been resolved." + "description": "Parse a config file and echo back a normalized version. This command is useful for sanity checking a config if it isn't behaving as expected, as it shows you a normalised version after environment variables have been resolved.\n\nExamples:\n\n[,bash]\n----\nrpk connect echo ./config.yaml | less\nrpk connect echo --set 'input.generate.mapping=root.id = uuid_v4()'\n----" }, "rpk connect blobl server": { "description": "Run a web server that provides an interactive application for writing and testing Bloblang mappings.", @@ -2693,7 +2649,7 @@ ] }, "rpk connect template": { - "description": "Work with Redpanda Connect templates. Templates allow you to define reusable configuration patterns.", + "description": "Work with Redpanda Connect templates. Templates allow you to define reusable configuration patterns.\n\nWARNING: This subcommand, and templates in general, are experimental and subject to change outside of major version releases.", "seeAlso": [ "xref:connect:configuration:templating.adoc[Templating]" ], @@ -2969,7 +2925,6 @@ ] } ], - "description": "Display the status of a shadow link. When using `--format json` or `--format yaml`, the command outputs all sections by default.", "flags": { "print-registry": { "introducedInVersion": "v26.2.1" @@ -3110,7 +3065,7 @@ }, "rpk transform init": { "pageAliases": "labs:data-transform/rpk-transform-init.adoc", - "description": "Initialize a new data transform project. Creates a new directory with the required project files. To initialize in a new subdirectory, specify the directory name as an argument.", + "description": "Initialize a new data transform project. Creates a new directory with the required project files. To initialize in a new subdirectory, specify the directory name as an argument.\n\nThe project is created from a template. For example, `rpk transform init foobar` initializes a transform project in the `foobar` directory.", "flags": { "install-deps": { "description": "Install project dependencies automatically after initialization." @@ -3146,10 +3101,6 @@ }, "selfHostedOnly": true }, - "rpk cluster config lint": { - "description": "Identify any Redpanda configuration properties that are not recognized. These may be properties that were valid in earlier versions of Redpanda but are now managed via the central configuration store.", - "selfHostedOnly": true - }, "rpk cluster logdirs describe": { "flags": { "aggregate-into": { @@ -3158,8 +3109,7 @@ "format": { "introducedInVersion": "v26.2.1" } - }, - "description": "Describe log directories on Redpanda brokers.\n\nThis command prints information about log directories on brokers, as well as the number of records in those log directories. The information is sorted first by topic, then by partition, and last by broker.\n\nThe 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." + } }, "rpk profile clear": { "description": "Clear the current profile. This command clears the current profile, which can be useful to unset a production cluster profile." @@ -3233,17 +3183,10 @@ } }, "rpk connect install": { - "description": "Install Redpanda Connect. This command installs the latest version by default. Use the `--connect-version` flag to specify a version." - }, - "rpk transform logs": { - "description": "View logs for a data transform. Streams STDOUT and STDERR output captured during runtime to your terminal." - }, - "rpk generate license": { - "description": "Generate a trial license for a 30-day Redpanda Enterprise Edition trial. The license is saved in your working directory or the specified path.", - "selfHostedOnly": true + "description": "Install Redpanda Connect. This command installs the latest version by default. Use the `--connect-version` flag to specify a version.\n\nYou may force the installation using the `--force` flag." }, "rpk ai auth login": { - "description": "Run the OAuth 2.0 device authorization grant against Redpanda Cloud, persist the resulting credentials, and prompt to select an environment whose AI Gateway URL becomes the active profile's dataplane URL." + "description": "Run the OAuth 2.0 device authorization grant against Redpanda Cloud, persist the resulting credentials, and prompt to select an environment whose AI Gateway URL becomes the active profile's dataplane URL.\n\nCredentials are stored in the `rpk ai` credentials file with `0600` permissions, keyed by organization.\n\nA successful login rewrites the config in the current schema, so running `rpk ai auth login` is also how you migrate a config left over from an older version of the plugin.\n\nIf the current environment's organization still holds valid credentials, login is a no-op and prints \"Already logged in\". Run `rpk ai auth logout` first to re-authenticate, or `rpk ai auth logout --all` for a full clean slate." }, "rpk ai oauth-client": { "description": "Manage OAuth clients registered with the AI gateway's OAuth Authorization Server. An OAuth client is an external tool (such as Claude AI, ChatGPT, or Cursor) that requests access tokens for an MCP server." @@ -3258,7 +3201,7 @@ "description": "Stop a managed agent, setting its desired state to stopped." }, "rpk ai llm-provider check": { - "description": "Run a lightweight probe against the configured LLM provider to verify credentials and reachability." + "introducedInVersion": "0.2.32" }, "rpk ai agent credential create": { "description": "Create a client ID and secret pair for an agent. The client secret is shown once and cannot be retrieved again." @@ -3267,7 +3210,7 @@ "description": "Delete a credential. Specify the full resource name as shown by `rpk ai agent credential list`, for example `agents/my-agent/credentials/abc123`." }, "rpk ai oauth-client revoke-tokens": { - "description": "Revoke every refresh token the AI gateway has issued for the named OAuth client. Forces all users who connected this client to sign in again." + "description": "Revoke every refresh token the AI gateway has issued for the named OAuth client. Forces all users who connected this client to sign in again.\n\nAlready-issued short-lived access tokens may continue working until natural expiry (typically minutes).\n\nThis command is idempotent: running it again returns 0." }, "rpk ai oauth-client create": { "description": "Register an OAuth client with the AI gateway. The generated client secret is printed once and cannot be retrieved afterward. Save it immediately in a secret manager." @@ -3282,7 +3225,7 @@ "description": "Manage tasks created by agent-to-agent (A2A) conversations. Task IDs come from `rpk ai agent a2a send` replies. Use subcommands to get, watch, or cancel a task." }, "rpk ai oauth-client dcr": { - "description": "Manage Dynamic Client Registration (DCR) settings for the AI gateway. DCR allows OAuth clients to register themselves programmatically at a public endpoint." + "description": "Manage Dynamic Client Registration (DCR) settings for the AI gateway. DCR allows OAuth clients to register themselves programmatically at a public endpoint.\n\nWhen DCR is enabled, spec-conformant MCP clients (such as Claude and Cursor) self-register at the public `/oauth/idp/register` endpoint with no admin pre-provisioning. Admission is governed by the mode:\n\n* `open`: anyone may register (rate limit and client cap still apply)\n* `initial-access-token`: callers must present an admin-minted one-shot bearer token\n* `software-statement`: reserved, not yet supported\n\nDCR is disabled per tenant by default. The gateway operator must also enable the global `ingress.idp.dcr.global_enabled` flag." }, "rpk redpanda tune list": { "content": [ @@ -3389,7 +3332,7 @@ ] }, "rpk cloud mcp install": { - "description": "Install the MCP client configuration to connect your AI assistant to the local MCP server for Redpanda Cloud.\n\nThis command generates and installs the necessary configuration files for your MCP client (like Claude Code) to automatically connect to the local MCP server for Redpanda Cloud. The local MCP server provides your AI assistant with tools to manage your Redpanda Cloud account and clusters.\n\nSupports Claude Desktop and Claude Code.", + "description": "Install the MCP client configuration to connect your AI assistant to the local MCP server for Redpanda Cloud.\n\nThis command generates and installs the necessary configuration files for your MCP client (like Claude Code) to automatically connect to the local MCP server for Redpanda Cloud. The local MCP server provides your AI assistant with tools to manage your Redpanda Cloud account and clusters.\n\nSupports Claude Desktop and Claude Code.\n\nThis command writes an `mcpServer` entry named `redpandaCloud` into the appropriate config file.", "flags": { "client": { "description": "Name of the MCP client to configure. Supported values: `claude` or `claude-code`." @@ -3462,7 +3405,6 @@ "_note": "Linux-only command. The v26.2.1-rc2 tree data wrongly reported darwin support, so pin the platform here." }, "rpk cluster maintenance status": { - "description": "Report maintenance status.\n\nThis command reports maintenance status for each broker in the cluster. The output is presented as a table with each row representing a broker in the cluster. The output can be used to monitor the progress of node draining.", "content": [ { "type": "section", @@ -3485,11 +3427,8 @@ }, "rpk cluster brokers": { "pageAliases": "reference:rpk/rpk-redpanda/rpk-redpanda-admin-brokers.adoc", -<<<<<<< HEAD - "introducedInVersion": "v26.2.1" -======= + "introducedInVersion": "v26.2.1", "selfHostedOnly": true ->>>>>>> a8cf35b4 (Add selfHostedOnly overrides for cloud-unavailable rpk commands) }, "rpk cluster brokers decommission": { "pageAliases": "reference:rpk/rpk-redpanda/rpk-redpanda-admin-brokers-decommission.adoc", @@ -3505,11 +3444,8 @@ }, "rpk cluster loggers": { "pageAliases": "reference:rpk/rpk-redpanda/rpk-redpanda-admin-config-log-level.adoc", -<<<<<<< HEAD - "introducedInVersion": "v26.2.1" -======= + "introducedInVersion": "v26.2.1", "selfHostedOnly": true ->>>>>>> a8cf35b4 (Add selfHostedOnly overrides for cloud-unavailable rpk commands) }, "rpk cluster loggers set": { "pageAliases": "reference:rpk/rpk-redpanda/rpk-redpanda-admin-config-log-level-set.adoc", @@ -3570,7 +3506,6 @@ }, "rpk check install": { "description": "Install Redpanda Check.\n\nThis command installs the latest version by default.\n\nAlternatively, you may specify a version using the `--check-version` flag.\n\nYou may force the installation using the `--force` flag.", -<<<<<<< HEAD "_note": "The source help text is missing a period after the summary sentence, which breaks the generated meta description.", "introducedInVersion": "v26.2.1" }, @@ -3580,9 +3515,6 @@ "rpk ai llm-provider apply": { "introducedInVersion": "0.2.32" }, - "rpk ai llm-provider check": { - "introducedInVersion": "0.2.32" - }, "rpk ai llm-provider create": { "introducedInVersion": "0.2.32" }, @@ -3677,7 +3609,8 @@ "introducedInVersion": "v26.2.1" }, "rpk cluster upgrade": { - "introducedInVersion": "v26.2.1" + "introducedInVersion": "v26.2.1", + "selfHostedOnly": true }, "rpk cluster upgrade finalize": { "introducedInVersion": "v26.2.1" @@ -3750,19 +3683,20 @@ "introducedInVersion": "v26.2.1" } } -======= - "_note": "The source help text is missing a period after the summary sentence, which breaks the generated meta description." }, - "rpk cluster license": { + "rpk cluster config edit": { "selfHostedOnly": true }, - "rpk cluster upgrade": { + "rpk cluster config export": { "selfHostedOnly": true }, - "rpk cluster config edit": { + "rpk cluster license": { "selfHostedOnly": true }, - "rpk cluster config export": { + "rpk profile validate": { + "selfHostedOnly": true + }, + "rpk shadow config": { "selfHostedOnly": true }, "rpk transform pause": { @@ -3771,12 +3705,11 @@ "rpk transform resume": { "selfHostedOnly": true }, - "rpk shadow config": { + "rpk cluster config lint": { "selfHostedOnly": true }, - "rpk profile validate": { + "rpk generate license": { "selfHostedOnly": true ->>>>>>> a8cf35b4 (Add selfHostedOnly overrides for cloud-unavailable rpk commands) } } -} \ No newline at end of file +} diff --git a/modules/reference/pages/rpk/rpk-topic/rpk-topic-produce.adoc b/modules/reference/pages/rpk/rpk-topic/rpk-topic-produce.adoc index 2f508d833e..0ed0a45c2c 100644 --- a/modules/reference/pages/rpk/rpk-topic/rpk-topic-produce.adoc +++ b/modules/reference/pages/rpk/rpk-topic/rpk-topic-produce.adoc @@ -10,7 +10,7 @@ Produce records to a topic. Producing records reads from `STDIN`, parses input a The input formatter understands a wide variety of formats. Parsing input operates on either sizes or on delimiters, both of which can be specified in the same formatting options. -include::reference:partial$topic-format.adoc[] +include::reference:partial$topic-format-produce.adoc[] == Usage diff --git a/modules/reference/partials/topic-format-produce.adoc b/modules/reference/partials/topic-format-produce.adoc new file mode 100644 index 0000000000..7e38dd3efb --- /dev/null +++ b/modules/reference/partials/topic-format-produce.adoc @@ -0,0 +1,105 @@ +== Formatting + +Parsing is based on percent escapes and modifiers. If using sizes to specify +something, the size must come before what it is specifying. Delimiters match on +an exact text basis. This command will quit with an error if any input fails to +match your specified format. + +Slashes can be used for common escapes: + +[cols=",",] +|=== +|Escape |Description + +|`\t` |Tabs +|`\n` |Newlines +|`\r` |Carriage returns +|`\\` |Slashes +|`\xNN` |Hex encoded characters +|=== + +Percent encoding reads into specific values of a record: + +[cols=",",] +|=== +|Percent encoding |Description + +|`%t` |Topic +|`%T` |Topic length +|`%k` |Key +|`%K` |Key length +|`%v` |Value +|`%V` |Value length +|`%h` |Begin the header specification +|`%H` |Number of headers +|`%p` |Partition (if using the `--partition` flag) +|`%%` |Percent sign +|`%{` |Left brace +|`%}` |Right brace +|=== + +=== Modifiers + +Text and numbers can be read in multiple formats, and the default format can be +changed within brace modifiers. `%v` reads a value, while pass:q[`%v{hex}`] +reads a value and then hex decodes it before producing. `%T` reads the length +of a topic from the input, while pass:q[`%T{3}`] reads exactly three bytes for +a topic from the input. + +All modifiers go within braces following a percent-escape. + +=== Numbers + +Reading number values can have the following modifiers: + +[cols=",",] +|=== +|Number |Description + +|`ascii` |Parse numeric digits until a non-numeric (default) +|`hex64` |Sixteen hex characters +|`hex32` |Eight hex characters +|`hex16` |Four hex characters +|`hex8` |Two hex characters +|`hex4` |One hex character +|`big64` |Eight byte big endian number +|`big32` |Four byte big endian number +|`big16` |Two byte big endian number +|`big8` |Alias for byte +|`little64` |Eight byte little endian number +|`little32` |Four byte little endian number +|`little16` |Two byte little endian number +|`little8` |Alias for byte +|`byte` |One byte number +|`` |Directly specify the length as this many digits +|`bool` |Read "true" as 1, "false" as 0 +|=== + +When reading number sizes, the size corresponds to the size of the encoded +values, not the decoded values. pass:q[`%T{6}%t{hex}`] reads six hex bytes and +decodes them into three. + +=== Text + +Reading text values can have the following modifiers: + +[cols=",",] +|=== +|Modifier |Description + +|`hex` |Read text, then hex decode it +|`base64` |Read text, then std-encoding base64 decode it +|`re` |Read text matching a regular expression +|`json` |Read text as JSON, then compact it +|=== + +=== Headers + +Headers are parsed with an internal key/value specifier format. For example, +the following reads three headers that begin and end with a space and are +separated by an equals sign: + +[,bash] +---- +%H{3}%h{ %k=%v } +----