Skip to content

rpk: update profile docs #1015

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
r-vasquez merged 2 commits into from
Mar 17, 2025
Merged

rpk: update profile docs #1015

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f2c027f
rpk: update profile docs
r-vasquez Mar 14, 2025
9e6e90f
Apply suggestions from code review
r-vasquez Mar 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions modules/get-started/pages/config-rpk-profile.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,16 +64,18 @@ rpk profile use <name-of-profile-to-use>

=== Set or edit configuration values

You can customize settings for a single profile. To set a profile's configuration:

* Use xref:reference:rpk/rpk-profile/rpk-profile-set.adoc[`rpk profile set`] to set `key=value` pairs of configuration options to write to the profile's section of `rpk.yaml`.
* Use xref:reference:rpk/rpk-profile/rpk-profile-edit.adoc[`rpk profile edit`] to edit the profile's section of the `rpk.yaml` file in your default editor.

You can configure settings that apply to all profiles. To set these `globals`:

* Use xref:reference:rpk/rpk-profile/rpk-profile-set-globals.adoc[`rpk profile set-globals`] to set `key=value` pairs to write to the globals section
of `rpk.yaml`.
* Use xref:reference:rpk/rpk-profile/rpk-profile-edit-globals.adoc[`rpk profile edit-globals`] to edit the globals section of the `rpk.yaml` file in your default editor.

You can customize settings for a single profile. To set a profile's configuration:

* Use xref:reference:rpk/rpk-profile/rpk-profile-set.adoc[`rpk profile set`] to set `key=value` pairs of configuration options to write to the profile's section of `rpk.yaml`.
* Use xref:reference:rpk/rpk-profile/rpk-profile-edit.adoc[`rpk profile edit`] to edit the profile's section of the `rpk.yaml` file in your default editor.
TIP: For a list of all the available properties that can be set in your profile, see xref:reference:rpk/rpk-x-options.adoc[`rpk -X options`].

==== Customize command prompt per profile

Expand Down
17 changes: 6 additions & 11 deletions modules/get-started/pages/intro-to-rpk.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,28 +20,21 @@ ifndef::env-cloud[]
* xref:get-started:rpk-quickstart.adoc[]
endif::[]

== Specify command properties
== Specify configuration properties
Copy link
Contributor Author

@r-vasquez r-vasquez Mar 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A command property only can be specified via flags when you execute a function, for example:

rpk topic consume foo --group g1

Here, --group is a command property and can only be specified via flags.

However, configuration properties can be specified in every command; for example, if I want to set which broker rpk talks to, I could do:

# set it in the profile
rpk profile set brokers=foo.com
rpk topic consume foo

# Pass it with a -X flag:
rpk topic consume foo -X brokers=foo.com

# Pass it via env flags:
RPK_BROKERS=foo.com rpk topic consume


You can specify `rpk` command properties in the following ways:

* Create an xref:get-started:config-rpk-profile.adoc[`rpk profile`].
* Specify the appropriate flag on the command line.
* Define the corresponding environment variables.
+
Environment variable settings only last for the duration of a shell session.

Copy link
Contributor Author

@r-vasquez r-vasquez Mar 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removing references to the rpk section as we want to move everything we can to profiles and the rpk section of the redpanda.yaml is deprecated.

It will always be maintained, but any new feature will be added to profiles and not there.

w.r.t modifying the rpk.yaml, we prefer the user to use rpk profile commands to do so and not manually edit the rpk.yaml

Copy link
Contributor

@micheleRP micheleRP Mar 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@r-vasquez Should this line in the next paragraph also be changed then to remove the part about redpanda.yaml?
If the environment variable is not set, the value in the rpk.yaml configuration file is used, if that file is available, otherwise the value in the redpanda.yaml configuration file is used.

Copy link
Contributor

@micheleRP micheleRP Mar 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@r-vasquez should we also remove the rpk bullet from this page?

Copy link
Contributor Author

@r-vasquez r-vasquez Mar 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's fine to leave both as:

If the environment variable is not set, the value in the rpk.yaml configuration file is used, if that file is available, otherwise the value in the redpanda.yaml configuration file is used.

It's useful information on how rpk parses the properties but doesn't encourage users to use the redpanda.yaml

And from the link, it's fine to keep it.

* Edit the configuration file settings in the `rpk` section of the `redpanda.yaml` file.
+
Configuration file property settings stay the same for each shell session.

* Edit the configuration file settings in the `rpk.yaml` file.
+
Configuration file property settings stay the same for each shell session.

Command line flag settings take precedence over the corresponding environment variables, and environment variables take precedence over configuration file settings. If a required flag is not specified on the command line, Redpanda searches the environment variable. If the environment variable is not set, the value in the `rpk.yaml` configuration file is used, if that file is available, otherwise the value in the `redpanda.yaml` configuration file is used.

TIP: If you specify `rpk` command properties in the configuration files or as environment variables, you don't need to specify them again on the command line.

== Common configuration properties
=== Common configuration properties

Every `rpk` command supports a set of common configuration properties. You can set one or more options in an `rpk` command by using the `-X` flag:

Expand All @@ -64,7 +57,9 @@ Or, get a detailed description about each option with `-X help`:
rpk -X help
----

Some of the common configuration properties apply across all `rpk` commands as defaults. These default properties have keys with names starting with `defaults`, and they're viewable in `rpk -X list` and `rpk -X help`. For more details, see xref:reference:rpk/rpk-x-options.adoc[`rpk -X options`].
Every `-X` option can be translated into an environment variable by prefixing it with `RPK_` and replacing periods (`.`) with underscores (`_`). For example, the flag `tls.enabled` has the equivalent environment variable `RPK_TLS_ENABLED`.

Some of the common configuration properties apply across all `rpk` commands as defaults. These default properties have keys with names starting with `globals`, and they're viewable in `rpk -X list` and `rpk -X help`. For more details, see xref:reference:rpk/rpk-x-options.adoc[`rpk -X options`].

== Next steps

Expand Down