rpk: update profile docs #1015

r-vasquez · 2025-03-14T22:05:05Z

Description

There are multiple changes here:

Update default -> global
Not documenting the manipulation of the redpanda.yaml (deprecated) or rpk.yaml (we use rpk profile for this instead)
Adding information about how to turn a flag into an env variable.

Page previews

Checks

New feature
Content gap
Support Follow-up
Small fix (typos, links, copyedits, etc)

netlify · 2025-03-14T22:05:33Z

✅ Deploy Preview for redpanda-docs-preview ready!

Name	Link
🔨 Latest commit	`9e6e90f`
🔍 Latest deploy log	https://app.netlify.com/sites/redpanda-docs-preview/deploys/67d88be180f0e80008c4991d
😎 Deploy Preview	https://deploy-preview-1015--redpanda-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

hyperlint-ai-deprecated · 2025-03-14T22:05:35Z

PR Change Summary

Updated the profile documentation to reflect changes in configuration management and environment variable usage.

Changed references from 'default' to 'global' in configuration settings.
Removed documentation for deprecated redpanda.yaml manipulation in favor of rpk profile.
Added instructions on converting flags to environment variables.

Modified Files

modules/get-started/pages/config-rpk-profile.adoc
modules/get-started/pages/intro-to-rpk.adoc

How can I customize these reviews?

Check out the Hyperlint AI Reviewer docs for more information on how to customize the review.

If you just want to ignore it on this PR, you can add the hyperlint-ignore label to the PR. Future changes won't trigger a Hyperlint review.

Note specifically for link checks, we only check the first 30 links in a file and we cache the results for several hours (for instance, if you just added a page, you might experience this). Our recommendation is to add hyperlint-ignore to the PR to ignore the link check for this PR.

What is Hyperlint?

Hyperlint is an AI agent that helps you write, edit, and maintain your documentation.

Learn more about the Hyperlint AI reviewer and the checks that we can run on your documentation.

r-vasquez · 2025-03-14T22:05:47Z

modules/get-started/pages/config-rpk-profile.adoc

+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.
+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`]


I swapped the order here as setting configuration values for single profiles are more important than setting globals.

r-vasquez · 2025-03-14T22:06:38Z

modules/get-started/pages/config-rpk-profile.adoc

+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.
+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`]


Not sure if we should instead have a partial that gets rendered both here and on the -X page.

r-vasquez · 2025-03-14T22:09:47Z

modules/get-started/pages/intro-to-rpk.adoc

 endif::[]

-== Specify command properties
+== Specify configuration properties


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

r-vasquez · 2025-03-14T22:11:19Z

modules/get-started/pages/intro-to-rpk.adoc

 * Define the corresponding environment variables.
 +
 Environment variable settings only last for the duration of a shell session.



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

@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.

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

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.

r-vasquez · 2025-03-14T22:11:45Z

modules/get-started/pages/intro-to-rpk.adoc

 ----

-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 with `RPK_` and replacing periods (`.`) with underscores (`_`). For example, the flag `tls.enabled` has the equivalent environment variable `RPK_TLS_ENABLED`.


This paragraph is a copy from https://docs.redpanda.com/current/reference/rpk/rpk-x-options/

There are multiple changes here: 1. Update `default` -> `global` 2. Not documenting the manipulation of the redpanda.yaml (deprecated) or rpk.yaml (we use rpk profile for this instead) 3. Adding information about how to turn a flag into an env variable.

modules/get-started/pages/intro-to-rpk.adoc

modules/get-started/pages/config-rpk-profile.adoc

Co-authored-by: Michele Cyran <[email protected]>

micheleRP

lgtm, thank you!

Co-authored-by: Michele Cyran <[email protected]>

r-vasquez requested a review from a team as a code owner March 14, 2025 22:05

r-vasquez requested a review from kbatuigas March 14, 2025 22:05

r-vasquez commented Mar 14, 2025

View reviewed changes

rpk: update profile docs

f2c027f

There are multiple changes here: 1. Update `default` -> `global` 2. Not documenting the manipulation of the redpanda.yaml (deprecated) or rpk.yaml (we use rpk profile for this instead) 3. Adding information about how to turn a flag into an env variable.

r-vasquez force-pushed the rpk-profile-2 branch from 961f38a to f2c027f Compare March 14, 2025 22:13

r-vasquez requested a review from micheleRP March 14, 2025 22:14

micheleRP reviewed Mar 17, 2025

View reviewed changes

modules/get-started/pages/intro-to-rpk.adoc Outdated Show resolved Hide resolved

micheleRP reviewed Mar 17, 2025

View reviewed changes

modules/get-started/pages/intro-to-rpk.adoc Outdated Show resolved Hide resolved

micheleRP reviewed Mar 17, 2025

View reviewed changes

modules/get-started/pages/config-rpk-profile.adoc Outdated Show resolved Hide resolved

Apply suggestions from code review

9e6e90f

Co-authored-by: Michele Cyran <[email protected]>

r-vasquez requested a review from micheleRP March 17, 2025 20:54

micheleRP approved these changes Mar 17, 2025

View reviewed changes

r-vasquez merged commit 14639b2 into main Mar 17, 2025
9 checks passed

r-vasquez deleted the rpk-profile-2 branch March 17, 2025 22:36

JakeSCahill pushed a commit that referenced this pull request Apr 3, 2025

rpk: update profile docs (#1015)

3fcba0c

Co-authored-by: Michele Cyran <[email protected]>

rpk: update profile docs #1015

rpk: update profile docs #1015

Uh oh!

Conversation

r-vasquez commented Mar 14, 2025

Description

Page previews

Checks

Uh oh!

netlify bot commented Mar 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for redpanda-docs-preview ready!

Uh oh!

hyperlint-ai-deprecated bot commented Mar 14, 2025

PR Change Summary

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

micheleRP left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

netlify bot commented Mar 14, 2025 •

edited

Loading