Distinguish between the two ways to enable SASL #1562
+195
−18
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
✅ Deploy Preview for redpanda-docs-preview ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
📝 WalkthroughWalkthroughThis change updates the authentication documentation in Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Suggested reviewers
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
Warning Review ran into problems🔥 ProblemsErrors were encountered while retrieving linked issues. Errors (1)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@modules/manage/partials/authentication.adoc`:
- Around line 548-554: The cross-reference to enable-sasl-authentication is
broken because that anchor isn’t present; fix it by either adding the missing
anchor id "enable-sasl-authentication" immediately above the relevant heading
(so the xref resolves) or update the xref to point to an existing anchor/ID used
in this document (for example the actual heading ID for SASL enablement or the
authentication section); ensure the xref text remains
"enable-sasl-authentication" or change it to the correct existing ID and verify
the xref renders.
vuldin
force-pushed
the
distinguish-two-sasl-enable-routes
branch
from
2a62d06 to
08de78d
Compare
Feediver1
reviewed
Jan 28, 2026
| === Enable SASL authentication | ||
|
|
||
| To enable authentication in your Redpanda cluster, you have the following options, depending on your requirements for SASL authentication and authorization. | ||
| Redpanda provides two methods for enabling SASL authentication. |
Contributor
There was a problem hiding this comment.
Suggested change
| Redpanda provides two methods for enabling SASL authentication. | |
| Redpanda provides the following options for enabling SASL authentication: |
Contributor
There was a problem hiding this comment.
I try to avoid saying how many options there are because if it changes, then I have to remember to change the number too (over the years, I've seen this come up many times).
Feediver1
reviewed
Jan 28, 2026
| To enable authentication in your Redpanda cluster, you have the following options, depending on your requirements for SASL authentication and authorization. | ||
| Redpanda provides two methods for enabling SASL authentication. | ||
|
|
||
| *Why two methods?* |
Contributor
There was a problem hiding this comment.
Suggested change
| *Why two methods?* |
Feediver1
reviewed
Jan 28, 2026
|
|
||
| *Why two methods?* | ||
|
|
||
| * *Method 1* (`enable_sasl`) is the original approach, maintained for backwards compatibility. It applies SASL globally to all Kafka listeners with a single command. |
Contributor
There was a problem hiding this comment.
Suggested change
| * *Method 1* (`enable_sasl`) is the original approach, maintained for backwards compatibility. It applies SASL globally to all Kafka listeners with a single command. | |
| * *`enable_sasl`* - is the original approach, which is maintained for backwards compatibility. It applies SASL globally to all Kafka listeners with a single command. |
Contributor
There was a problem hiding this comment.
@vuldin
I'm not sure "the original approach" will resonate so much with users. Original from when? Is there any other distinguishing quality other than it is an "original approach"? Legacy approach?
Feediver1
reviewed
Jan 28, 2026
| *Why two methods?* | ||
|
|
||
| * *Method 1* (`enable_sasl`) is the original approach, maintained for backwards compatibility. It applies SASL globally to all Kafka listeners with a single command. | ||
| * *Method 2* (per-listener configuration) is the newer, more flexible approach that allows you to configure different authentication methods on different listeners. |
Contributor
There was a problem hiding this comment.
Suggested change
| * *Method 2* (per-listener configuration) is the newer, more flexible approach that allows you to configure different authentication methods on different listeners. | |
| * *per-listener configuration* - A more flexible approach that allows you to configure different authentication methods on different listeners. |
Feediver1
reviewed
Jan 28, 2026
| * *Method 1* (`enable_sasl`) is the original approach, maintained for backwards compatibility. It applies SASL globally to all Kafka listeners with a single command. | ||
| * *Method 2* (per-listener configuration) is the newer, more flexible approach that allows you to configure different authentication methods on different listeners. | ||
|
|
||
| *Which method should I use?* |
Contributor
There was a problem hiding this comment.
Suggested change
| *Which method should I use?* | |
| Use the following criteria to help you select the best option: |
Feediver1
reviewed
Jan 28, 2026
Comment on lines
+467
to
+469
| * **For new clusters:** Use *Method 2* (per-listener configuration). This gives you the flexibility to configure authentication per listener, which is useful for mixed environments where some listeners are internal (no auth required) and others are external (auth required). | ||
| * **For existing clusters using `enable_sasl`:** Continue using *Method 1* if it meets your needs. Only migrate to Method 2 if you need per-listener authentication control. | ||
| * **For uniform authentication:** If you know all your Kafka listeners will use SASL authentication, *Method 1* is simpler and doesn't require a restart. |
Contributor
There was a problem hiding this comment.
Suggested change
| * **For new clusters:** Use *Method 2* (per-listener configuration). This gives you the flexibility to configure authentication per listener, which is useful for mixed environments where some listeners are internal (no auth required) and others are external (auth required). | |
| * **For existing clusters using `enable_sasl`:** Continue using *Method 1* if it meets your needs. Only migrate to Method 2 if you need per-listener authentication control. | |
| * **For uniform authentication:** If you know all your Kafka listeners will use SASL authentication, *Method 1* is simpler and doesn't require a restart. | |
| [cols="1,1,2",options="header"] | |
| |=== | |
| |Use Case |Use Authentication Method |Explanation | |
| |When creating new clusters | |
| |Use per-listener configuration | |
| |Provides you the flexibility to configure authentication per listener, which is useful for mixed environments where some listeners are internal (no authentication required) and others are external (authentication required). | |
| |When you have existing clusters already using `enable_sasl` | |
| |Use `enable_sasl` | |
| |You can use per-listener configuration if it continues to meet your needs. You only need to migrate to `enable_sasl` if you need per-listener authentication control. | |
| |When you require uniform authentication | |
| |Use `enable_sasl` | |
| |If you know all your Kafka listeners will use SASL authentication, this option is simpler and doesn't require a restart. | |
| |=== |
Feediver1
reviewed
Jan 28, 2026
|
|
||
| [IMPORTANT] | ||
| ==== | ||
| *Do not mix configuration methods* |
Contributor
There was a problem hiding this comment.
Suggested change
| *Do not mix configuration methods* | |
| *Do not mix configuration methods*. |
Feediver1
reviewed
Jan 28, 2026
| + | ||
| NOTE: This command implicitly enables authorization. If you want to disable authorization, you can use the `kafka_enable_authorization` cluster configuration property. | ||
| + | ||
| ==== Method 1: Global authentication (backwards compatible) |
Contributor
There was a problem hiding this comment.
Suggested change
| ==== Method 1: Global authentication (backwards compatible) | |
| ==== Use `enable_sasl` for Global authentication (backwards compatible) |
Feediver1
reviewed
Jan 28, 2026
| + | ||
| ==== Method 1: Global authentication (backwards compatible) | ||
|
|
||
| This method applies SASL authentication to all Kafka API listeners with a single command. |
Contributor
There was a problem hiding this comment.
Suggested change
| This method applies SASL authentication to all Kafka API listeners with a single command. | |
| Using the `enable_sasl` option applies SASL authentication to all Kafka API listeners with a single command. |
Feediver1
reviewed
Jan 28, 2026
|
|
||
| This method applies SASL authentication to all Kafka API listeners with a single command. | ||
|
|
||
| *When to use:* |
Contributor
There was a problem hiding this comment.
Suggested change
| *When to use:* | |
| Use this option when: |
Feediver1
reviewed
Jan 28, 2026
| * You prefer simpler configuration | ||
| * You want to avoid a cluster restart | ||
|
|
||
| *Tradeoffs:* |
Contributor
There was a problem hiding this comment.
Suggested change
| *Tradeoffs:* | |
| Trade-offs when using this `enable_sasl`: |
Feediver1
reviewed
Jan 28, 2026
|
|
||
| * ✅ Simple: One command enables authentication on all listeners | ||
| * ✅ No restart required | ||
| * ✅ No `redpanda.yaml` changes needed |
Contributor
There was a problem hiding this comment.
Suggested change
| * ✅ No `redpanda.yaml` changes needed | |
| * ✅ No `redpanda.yaml` changes required |
Feediver1
reviewed
Jan 28, 2026
| * ❌ Cannot configure different authentication methods per listener | ||
| * ❌ All listeners must use the same authentication method | ||
|
|
||
| *Command:* |
Contributor
There was a problem hiding this comment.
Suggested change
| *Command:* | |
| To use this option, run: |
Feediver1
reviewed
Jan 28, 2026
| When using this method, do NOT additionally set `kafka_enable_authorization: true` or add `authentication_method: sasl` to `redpanda.yaml`. The `enable_sasl` setting handles both automatically. | ||
| ==== | ||
|
|
||
| ==== Method 2: Per-listener authentication (recommended for new clusters) |
Contributor
There was a problem hiding this comment.
Suggested change
| ==== Method 2: Per-listener authentication (recommended for new clusters) | |
| ==== Use per-listener authentication (recommended for new clusters) |
Feediver1
reviewed
Jan 28, 2026
|
|
||
| ==== Method 2: Per-listener authentication (recommended for new clusters) | ||
|
|
||
| This method allows you to configure authentication per listener, giving you flexibility to have different authentication methods on different listeners. |
Contributor
There was a problem hiding this comment.
Suggested change
| This method allows you to configure authentication per listener, giving you flexibility to have different authentication methods on different listeners. | |
| This option allows you to configure authentication per listener, giving you flexibility to have different authentication methods on different listeners. |
Feediver1
reviewed
Jan 28, 2026
|
|
||
| This method allows you to configure authentication per listener, giving you flexibility to have different authentication methods on different listeners. | ||
|
|
||
| *When to use:* |
Contributor
There was a problem hiding this comment.
Suggested change
| *When to use:* | |
| Use this option when: |
Feediver1
reviewed
Jan 28, 2026
| * You're setting up a new cluster | ||
| * You want explicit control over which listeners have authentication enabled | ||
|
|
||
| *Tradeoffs:* |
Contributor
There was a problem hiding this comment.
Suggested change
| *Tradeoffs:* | |
| Trade-offs when using per listener configuration: |
Feediver1
reviewed
Jan 28, 2026
|
|
||
| * ✅ Flexible: Configure authentication per listener | ||
| * ✅ Explicit: Clear configuration in `redpanda.yaml` for each listener | ||
| * ✅ Can mix authentication methods (some listeners with auth, some without) |
Contributor
There was a problem hiding this comment.
Suggested change
| * ✅ Can mix authentication methods (some listeners with auth, some without) | |
| * ✅ Can mix authentication methods (some listeners with authentication, some without) |
Feediver1
reviewed
Jan 28, 2026
| * ❌ Requires configuration in `redpanda.yaml` for each listener | ||
| * ❌ Requires cluster restart to apply changes | ||
|
|
||
| *Steps:* |
Contributor
There was a problem hiding this comment.
Suggested change
| *Steps:* | |
| To configure per listener authentication: |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
This PR makes it clear there are two ways to enable SASL, explains what they are, when to choose one or the other, and why we even have two ways to begin with (why not just one?), and which is the recommended path for new clusters.
Page previews
https://deploy-preview-1562--redpanda-docs-preview.netlify.app/current/manage/security/authentication/
Checks