DOC-31 add rpk tutorial

modules/ROOT/nav.adoc

@@ -24,6 +24,7 @@
 ** xref:get-started:rpk/index.adoc[Redpanda CLI]
 *** xref:get-started:intro-to-rpk.adoc[Introduction to rpk]
 *** xref:get-started:rpk-install.adoc[]
+*** xref:get-started:rpk-first-steps.adoc[]
 *** xref:get-started:config-rpk-profile.adoc[]
 *** xref:get-started:broker-admin.adoc[]
 *** xref:get-started:admin-addresses.adoc[]

modules/get-started/pages/rpk-first-steps.adoc

@@ -0,0 +1,240 @@
+= Quickstart with rpk
+:page-categories: rpk
+// Do not put page aliases in the single-sourced content
+// tag::single-source[]
+
+This guide shows how to run the Redpanda CLI, `rpk`, for basic Redpanda tasks, including creating, producing to, describing, and deleting topics, as well as consuming records and managing consumer groups. Follow these examples to quickly become familiar with `rpk` commands.
+
+== Create a topic
+
+To start streaming data, first create a topic as the destination for your records:
+
+[source,bash]
+----
+rpk topic create tutorial
+----
+
+Output:
+[source,bash]
+----
+TOPIC     STATUS
+tutorial  OK
+----
+
+See xref:reference:rpk/rpk-topic/rpk-topic-create.adoc[].
+
+== Produce records to a topic
+
+Produce records to the topic. Downstream consumers will then be able to read these records.
+
+[source,bash]
+----
+rpk topic produce tutorial
+----
+
+Additional input:
+[source,bash]
+----
+hello
+world
+----
+
+Output:
+[source,bash]
+----
+Produced to partition 0 at offset 0 with timestamp 1734640650348.
+Produced to partition 0 at offset 1 with timestamp 1734640653558.
+----
+
+See xref:reference:rpk/rpk-topic/rpk-topic-produce.adoc[].
+
+== Get a description of a topic
+
+Check the topic’s configuration and status to ensure that it’s ready for use:
+
+[source,bash]
+----
+rpk topic describe tutorial
+----
+
+Output:
+[source,bash]
+----
+SUMMARY
+=======
+NAME        tutorial
+PARTITIONS  1
+REPLICAS    1
+
+CONFIGS
+=======
+KEY                                   VALUE       SOURCE
+cleanup.policy                        delete      DEFAULT_CONFIG
+compression.type                      producer    DEFAULT_CONFIG
+delete.retention.ms                   -1          DEFAULT_CONFIG
+flush.bytes                           262144      DEFAULT_CONFIG
+flush.ms                              100         DEFAULT_CONFIG
+initial.retention.local.target.bytes  -1          DEFAULT_CONFIG
+initial.retention.local.target.ms     -1          DEFAULT_CONFIG
+max.message.bytes                     1048576     DEFAULT_CONFIG
+message.timestamp.type                CreateTime  DEFAULT_CONFIG
+redpanda.iceberg.delete               true        DEFAULT_CONFIG
+redpanda.iceberg.mode                 disabled    DEFAULT_CONFIG
+redpanda.leaders.preference           none        DEFAULT_CONFIG
+redpanda.remote.delete                true        DEFAULT_CONFIG
+redpanda.remote.read                  false       DEFAULT_CONFIG
+redpanda.remote.write                 false       DEFAULT_CONFIG
+retention.bytes                       -1          DEFAULT_CONFIG
+retention.local.target.bytes          -1          DEFAULT_CONFIG
+retention.local.target.ms             86400000    DEFAULT_CONFIG
+retention.ms                          604800000   DEFAULT_CONFIG
+segment.bytes                         134217728   DEFAULT_CONFIG
+segment.ms                            1209600000  DEFAULT_CONFIG
+write.caching                         true        DEFAULT_CONFIG
+----
+
+See xref:reference:rpk/rpk-topic/rpk-topic-describe.adoc[].
+
+== Consume records from a topic
+
+Consume records from the topic:
+
+[source,bash]
+----
+rpk topic consume tutorial
+----
+
+Output:
+[source,json]
+----
+{ "topic": "tutorial", "value": "hello", "timestamp": 1678807229837, "partition": 0, "offset": 0 }
+{ "topic": "tutorial", "value": "world", "timestamp": 1678807232413, "partition": 0, "offset": 1 }
+----
+
+Consume from an offset, where `2` is not inclusive: 
+[source,bash]
+----
+rpk topic consume tutorial --offset 0:2
+----
+Output:
+[source,json]
+----
+{ "topic": "tutorial", "value": "hello", "timestamp": 1678807229837, "partition": 0, "offset": 0 }
+{ "topic": "tutorial", "value": "world", "timestamp": 1678807232413, "partition": 0, "offset": 1 }
+----
+
+See xref:reference:rpk/rpk-topic/rpk-topic-consume.adoc[].
+
+== Create a consumer group and consume topics
+
+Organize consumers into groups to share workloads and balance consumption:
+
+[source,bash]
+----
+rpk topic consume tutorial --group tutorial-group
+----
+
+NOTE: The consumer group is created when you consume from the topic.
+
+Output:
+[source,json]
+----
+{
+  "topic": "tutorial",
+  "value": "hello",
+  "timestamp": 1734640650348,
+  "partition": 0,
+  "offset": 0
+}
+{
+  "topic": "tutorial",
+  "value": "world",
+  "timestamp": 1734640653558,
+  "partition": 0,
+  "offset": 1
+}
+----
+
+See xref:reference:rpk/rpk-topic/rpk-topic-consume.adoc[].
+
+== List all consumer groups
+
+List available consumer groups in your cluster:
+
+[source,bash]
+----
+rpk group list
+----
+
+Output:
+[source,bash]
+----
+BROKER  GROUP           STATE
+0       tutorial-group  Empty
+----
+
+See xref:reference:rpk/rpk-group/rpk-group-list.adoc[].
+
+== Get a description of a consumer group
+
+View details about the consumer group’s state, coordinator, members, and offsets:
+
+[source,bash]
+----
+rpk group describe tutorial-group
+----
+Output:
+[source,bash]
+----
+GROUP        tutorial-group
+COORDINATOR  0
+STATE        Empty
+BALANCER
+MEMBERS      0
+TOTAL-LAG    0
+
+TOPIC     PARTITION  CURRENT-OFFSET  LOG-START-OFFSET  LOG-END-OFFSET  LAG   MEMBER-ID  CLIENT-ID  HOST
+tutorial  0          2               0                 2               0
+----
+
+See xref:reference:rpk/rpk-group/rpk-group-describe.adoc[].
+
+== Delete a consumer group
+
+Clean up by removing the `tutorial-group` consumer group:
+
+[source,bash]
+----
+rpk group delete tutorial-group
+----
+Output:
+[source,bash]
+----
+GROUP           STATUS
+tutorial-group  OK
+----
+
+See xref:reference:rpk/rpk-group/rpk-group-delete.adoc[].
+
+== Delete a topic
+
+Clean up by removing the `tutorial` topic:
+
+[source,bash]
+----
+rpk topic delete tutorial
+----
+Output:
+[source,bash]
+----
+TOPIC     STATUS
+tutorial  OK
+----
+
+See xref:reference:rpk/rpk-topic/rpk-topic-delete.adoc[].
+
+== Next steps
+
+For the complete list of `rpk` commands and their syntax, see the xref:reference:rpk/index.adoc[rpk reference].
+
+// end::single-source[]

modules/get-started/pages/rpk-install.adoc

@@ -35,6 +35,7 @@ include::get-started:partial$install-rpk-macos.adoc[]
 
 == Next steps
 
-For a list of `rpk` commands and their syntax, see the xref:reference:rpk/index.adoc[rpk reference].
+Explore rpk with the xref:rpk-first-steps.adoc[] guide.
+For the complete list of `rpk` commands and their syntax, see the xref:reference:rpk/index.adoc[rpk reference].
 
 // end::single-source[]