properties + sec: broker properties updates #1298
Conversation
✅ Deploy Preview for redpanda-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the 📝 WalkthroughWalkthroughThis changeset standardizes documentation references to the broker property authentication_method across many docs, replaces inline mentions of ephemeral HTTP Proxy credentials with explicit guidance to configure SCRAM credentials (scram_username, scram_password, sasl_mechanism) or use OIDC for HTTP Proxy, adds SCRAM and OIDC examples for HTTP Proxy clients, expands broker-properties with per-listener authentication_method details and many YAML examples, and converts numerous inline code/property mentions into cross-references to broker-properties.adoc. All edits are documentation-only; no runtime or API code changes. Sequence Diagram(s)Not applicable: The changes are limited to documentation presentation and do not introduce or modify any control flow or features. Estimated code review effort🎯 3 (Moderate) | ⏱️ ~15 minutes Possibly related PRs
Suggested reviewers
✨ Finishing Touches🧪 Generate unit tests
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🔭 Outside diff range comments (1)
modules/manage/partials/authentication.adoc (1)
1679-1693: OIDC section instructs settingauthentication_method: http_basic– this is misleadingPer the new property spec (Line 60 in broker-properties.adoc), valid values for HTTP endpoints are
noneandhttp_basic.
OIDC is enabled via thehttp_authenticationcluster property, not by changing the per-listenerauthentication_method. Telling users to set the listener tohttp_basicimplies Basic auth is mandatory for OIDC, which is not true and may lock out token-based clients.Please re-phrase:
-To enable OIDC for specific listeners, set ... to `http_basic`. +Leave `authentication_method` set to `none`. +OIDC enforcement is controlled by the `http_authentication` cluster property.
♻️ Duplicate comments (1)
modules/manage/pages/security/listener-configuration.adoc (1)
111-112: Same wording mismatch hereSame comment as above – show the exact property name (with underscore) to avoid confusing readers who might copy/paste.
🧹 Nitpick comments (6)
modules/shared/partials/http-proxy-ephemeral-credentials-breaking-change.adoc (1)
1-1: Anchor reference OK – consider styling the literal valueNice switch to an xref. For clarity, wrap the literal value
nonein back-ticks (`none`) so it is formatted consistently with all other literals in the paragraph.modules/manage/pages/security/listener-configuration.adoc (1)
56-57: Display text should match the property nameThe link target is correct, but the visible text shows
authentication method(with a space).
For consistency with every other occurrence in the docs, render the literal property name:-... [`authentication_method`] broker property. +... `xref:reference:properties/broker-properties.adoc#authentication_method[authentication_method]` broker property.modules/manage/partials/authentication.adoc (1)
706-720: Minor wording – tighten repetitionLines 706-720 repeat the same explanatory sentence twice. Consider merging them to avoid noise.
modules/reference/pages/properties/broker-properties.adoc (3)
45-67: Good addition – add a dedicated anchor block to prevent future rename breakageSection titles auto-generate IDs, but adding an explicit anchor makes refactors safer:
-=== authentication_method +[[authentication_method]] +=== authentication_method
60-63: Clarify OIDC relationshipBecause readers see OIDC elsewhere, add a short note:
NOTE: OIDC authentication is enabled through the `http_authentication` cluster property. Keep `authentication_method` set to `none` when using OIDC.
70-88: Indentation misleading for cluster property
sasl_mechanismsis a cluster property, not a child ofredpanda:. Add a
comment or indent correctly to avoid copy-paste errors.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
modules/get-started/pages/release-notes/redpanda.adoc(1 hunks)modules/manage/pages/security/listener-configuration.adoc(2 hunks)modules/manage/partials/authentication.adoc(9 hunks)modules/reference/pages/properties/broker-properties.adoc(4 hunks)modules/shared/partials/http-proxy-ephemeral-credentials-breaking-change.adoc(1 hunks)
🧰 Additional context used
🧠 Learnings (3)
📓 Common learnings
Learnt from: Feediver1
PR: redpanda-data/docs#1153
File: modules/reference/pages/properties/topic-properties.adoc:45-50
Timestamp: 2025-07-16T19:33:20.420Z
Learning: In the Redpanda documentation, topic property cross-references like <<max.compaction.lag.ms>> and <<min.compaction.lag.ms>> require corresponding property definition sections with anchors like [[maxcompactionlagms]] and [[mincompactionlagms]] to prevent broken links.
📚 Learning: 2025-07-14T19:28:43.296Z
Learnt from: Feediver1
PR: redpanda-data/docs#1153
File: antora.yml:3-5
Timestamp: 2025-07-14T19:28:43.296Z
Learning: In Redpanda docs, during beta releases, the version metadata may intentionally show inconsistencies where the header displays the beta version (e.g., 25.2 Beta) while internal attributes like full-version, latest-redpanda-tag, operator-beta-tag still reference the stable version (e.g., 25.1). This is resolved during the GA merge process when all version references are synchronized.
Applied to files:
modules/shared/partials/http-proxy-ephemeral-credentials-breaking-change.adocmodules/get-started/pages/release-notes/redpanda.adoc
📚 Learning: 2025-07-16T19:33:20.420Z
Learnt from: Feediver1
PR: redpanda-data/docs#1153
File: modules/reference/pages/properties/topic-properties.adoc:45-50
Timestamp: 2025-07-16T19:33:20.420Z
Learning: In the Redpanda documentation, topic property cross-references like <<max.compaction.lag.ms>> and <<min.compaction.lag.ms>> require corresponding property definition sections with anchors like [[maxcompactionlagms]] and [[mincompactionlagms]] to prevent broken links.
Applied to files:
modules/get-started/pages/release-notes/redpanda.adocmodules/manage/partials/authentication.adoc
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Redirect rules - redpanda-docs-preview
- GitHub Check: Header rules - redpanda-docs-preview
- GitHub Check: Pages changed - redpanda-docs-preview
🔇 Additional comments (1)
modules/get-started/pages/release-notes/redpanda.adoc (1)
55-56: Cross-reference looks good – please double-check the anchor rendersThe inline link to the new broker property renders correctly in the Asciidoc source.
Just make sure the rendered HTML actually includes anid="authentication_method"anchor inbroker-properties.html; otherwise this reference will be broken in the published docs.
paulohtb6
changed the title
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
There was a problem hiding this comment.
Actionable comments posted: 2
🔭 Outside diff range comments (1)
modules/manage/pages/security/encryption.adoc (1)
407-411: YAML indent off by oneUnrelated to this PR’s intent but visible nearby:
port: 9092is indented two spaces fewer than its sibling keys inside the sequence item, which renders invalid YAML.- port: 9092 + port: 9092
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (9)
modules/deploy/pages/deployment-option/self-hosted/manual/production/production-deployment.adoc(1 hunks)modules/deploy/pages/deployment-option/self-hosted/manual/production/production-readiness.adoc(1 hunks)modules/manage/pages/cluster-maintenance/node-property-configuration.adoc(1 hunks)modules/manage/pages/rack-awareness.adoc(1 hunks)modules/manage/pages/security/encryption.adoc(1 hunks)modules/manage/pages/security/listener-configuration.adoc(3 hunks)modules/manage/partials/authentication.adoc(9 hunks)modules/manage/partials/tiered-storage.adoc(1 hunks)modules/reference/pages/properties/broker-properties.adoc(9 hunks)
✅ Files skipped from review due to trivial changes (1)
- modules/manage/partials/tiered-storage.adoc
🚧 Files skipped from review as they are similar to previous changes (3)
- modules/manage/pages/security/listener-configuration.adoc
- modules/manage/partials/authentication.adoc
- modules/reference/pages/properties/broker-properties.adoc
🧰 Additional context used
🧠 Learnings (3)
📓 Common learnings
Learnt from: Feediver1
PR: redpanda-data/docs#1153
File: modules/reference/pages/properties/topic-properties.adoc:45-50
Timestamp: 2025-07-16T19:33:20.420Z
Learning: In the Redpanda documentation, topic property cross-references like <<max.compaction.lag.ms>> and <<min.compaction.lag.ms>> require corresponding property definition sections with anchors like [[maxcompactionlagms]] and [[mincompactionlagms]] to prevent broken links.
📚 Learning: 2025-07-16T19:33:20.420Z
Learnt from: Feediver1
PR: redpanda-data/docs#1153
File: modules/reference/pages/properties/topic-properties.adoc:45-50
Timestamp: 2025-07-16T19:33:20.420Z
Learning: In the Redpanda documentation, topic property cross-references like <<max.compaction.lag.ms>> and <<min.compaction.lag.ms>> require corresponding property definition sections with anchors like [[maxcompactionlagms]] and [[mincompactionlagms]] to prevent broken links.
Applied to files:
modules/manage/pages/rack-awareness.adocmodules/manage/pages/security/encryption.adocmodules/manage/pages/cluster-maintenance/node-property-configuration.adocmodules/deploy/pages/deployment-option/self-hosted/manual/production/production-deployment.adocmodules/deploy/pages/deployment-option/self-hosted/manual/production/production-readiness.adoc
📚 Learning: 2025-07-02T14:54:03.506Z
Learnt from: JakeSCahill
PR: redpanda-data/docs#1192
File: modules/deploy/partials/requirements.adoc:91-93
Timestamp: 2025-07-02T14:54:03.506Z
Learning: In Redpanda documentation, use GiB (binary units, powers of 2) for Kubernetes-specific memory requirements because Kubernetes treats memory units like Mi, Gi as binary units. Use GB (decimal units, powers of 10) for general broker memory requirements in non-Kubernetes contexts.
Applied to files:
modules/manage/pages/rack-awareness.adocmodules/manage/pages/cluster-maintenance/node-property-configuration.adoc
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Redirect rules - redpanda-docs-preview
- GitHub Check: Header rules - redpanda-docs-preview
- GitHub Check: Pages changed - redpanda-docs-preview
🔇 Additional comments (3)
modules/manage/pages/rack-awareness.adoc (1)
43-44: Cross-reference addition looks goodThe new TIP correctly links
seed_serversto its authoritative broker-property section, improving discoverability. No further action required.modules/deploy/pages/deployment-option/self-hosted/manual/production/production-deployment.adoc (1)
195-198: Good re-targeting of property docsSwitching the
seed_serversandempty_seed_starts_clusterlinks to point at the broker-properties reference is the right place for end-users. 👍modules/manage/pages/cluster-maintenance/node-property-configuration.adoc (1)
6-7: Updated references improve accuracyThe paragraph now links directly to
data_directory,node_id, and the full broker-property list. This eliminates a known source of broken links. Looks correct.
modules/deploy/pages/deployment-option/self-hosted/manual/production/production-readiness.adoc
Show resolved
Hide resolved
modules/shared/partials/http-proxy-ephemeral-credentials-breaking-change.adoc
Outdated
Show resolved
Hide resolved
Co-authored-by: Ben Pope <BenPope@users.noreply.github.com>
Co-authored-by: Ben Pope <BenPope@users.noreply.github.com>
Co-authored-by: Ben Pope <BenPope@users.noreply.github.com>
Feediver1
left a comment
Feediver1
left a comment
There was a problem hiding this comment.
Nice cleanup @paulohtb6! And thanks for getting these long-missing properties and descriptions added.
paulohtb6
changed the title
Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com>
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
There was a problem hiding this comment.
Actionable comments posted: 4
🔭 Outside diff range comments (2)
modules/reference/pages/properties/broker-properties.adoc (1)
749-758: Replace incorrect "HTTP Proxy API" text with "Schema Registry API" in api_doc_dirThe
api_doc_dirproperty is defined under the Schema Registry section but its description incorrectly references the HTTP Proxy API.
- File: modules/reference/pages/properties/broker-properties.adoc
- Location: === api_doc_dir (around lines 747–757)
Suggested change:
-Path to the API specifications for the HTTP Proxy API. +Path to the API specifications for the Schema Registry API.Also verify the default path (currently:
/usr/share/redpanda/proxy-api-doc) and update it to the correct Schema Registry docs path if necessary (e.g./usr/share/redpanda/schema-registry-api-doc).modules/manage/partials/authentication.adoc (1)
1487-1496: Fix YAML structure:pandaproxy_apiis not a listIn all three examples,
pandaproxy_apiis shown as a list entry (with-). Inredpanda.yaml,pandaproxy_apiis a single mapping (address/port/auth per listener), not an array. Remove the hyphen.Apply this pattern to each block:
pandaproxy: pandaproxy_api: - - address: "localhost" + address: "localhost" port: 8082 authentication_method: http_basicAnd similarly in the OIDC and “Disable authentication” examples.
Also applies to: 1679-1689, 1861-1871
🧹 Nitpick comments (7)
modules/reference/pages/properties/broker-properties.adoc (3)
162-163: Clarify prerequisite wording for cloud storage cache directory“Should be present when the ... property is present” is ambiguous. Recommend aligning with the boolean cluster property.
-Directory for archival cache. Should be present when the xref:reference:properties/cluster-properties.adoc#cloud_storage_enabled[`cloud_storage_enabled`] cluster property is present. +Directory for archival cache. Set when the xref:reference:properties/cluster-properties.adoc#cloud_storage_enabled[`cloud_storage_enabled`] cluster property is enabled.
519-521: Duplicate placeholder bullet — remove the extra line
<another-new-uuid>is listed twice.* `<another-ignore-flag>`: Additional ignore existing node ID flag -* `<another-new-uuid>`: Additional new UUID
927-931: Capitalize “API” in section descriptionMinor editorial fix for consistency.
-=== pandaproxy_api_tls - -TLS configuration for Pandaproxy api. +=== pandaproxy_api_tls + +TLS configuration for Pandaproxy API.modules/manage/partials/authentication.adoc (3)
703-717: Helpful clarification about HTTP Proxy client credentials requirementThe note correctly explains when
pandaproxy_clientSCRAM credentials are required post-25.2. Consider explicitly linking to the broker property anchors forscram_username,scram_password, andsasl_mechanismfor consistency.
1483-1498: Tighten wording and fix cross-references for basic authMinor wording improvement and consistent anchor usage:
-To enable basic authentication for specific listeners, set xref:reference:properties/broker-properties.adoc#schema_registry_auth_method[`authentication_method`] broker property to `http_basic`. For example, in `redpanda.yaml`, enter: +To enable basic authentication for HTTP API listeners, set xref:reference:properties/broker-properties.adoc#schema_registry_auth_method[`authentication_method`] to `http_basic`. For example:
1675-1695: Clarify OIDC enablement phrasingOIDC is enabled via the cluster
http_authenticationlist; listeners requireauthentication_method: http_basic. Your note captures this already; consider highlighting that both BASIC and OIDC can be enabled concurrently.Optional inline tweak below (comment-only), no content change required.
modules/develop/partials/http-proxy.adoc (1)
920-931: Fix the error handler in NodeJS examples
catch(error => console.log);logs the function reference, not the error. Useconsole.error(error)(orconsole.log(error)).- .then(response => console.log(response.data)) - .catch(error => console.log); + .then(response => console.log(response.data)) + .catch(error => console.error(error));Consider updating other NodeJS examples across the file for consistency.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these settings in your CodeRabbit configuration.
📒 Files selected for processing (7)
modules/develop/partials/http-proxy.adoc(2 hunks)modules/get-started/pages/release-notes/redpanda.adoc(0 hunks)modules/manage/pages/security/listener-configuration.adoc(3 hunks)modules/manage/partials/authentication.adoc(8 hunks)modules/reference/pages/properties/broker-properties.adoc(20 hunks)modules/shared/partials/http-proxy-ephemeral-credentials-breaking-change-short.adoc(0 hunks)modules/shared/partials/http-proxy-ephemeral-credentials-breaking-change.adoc(1 hunks)
💤 Files with no reviewable changes (2)
- modules/shared/partials/http-proxy-ephemeral-credentials-breaking-change-short.adoc
- modules/get-started/pages/release-notes/redpanda.adoc
🚧 Files skipped from review as they are similar to previous changes (1)
- modules/manage/pages/security/listener-configuration.adoc
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Redirect rules - redpanda-docs-preview
- GitHub Check: Header rules - redpanda-docs-preview
- GitHub Check: Pages changed - redpanda-docs-preview
🔇 Additional comments (3)
modules/shared/partials/http-proxy-ephemeral-credentials-breaking-change.adoc (1)
1-6: LGTM: Clear warning and correct cross-referencesThe breaking change is clearly communicated, the risk is explicit, and links point to the right configuration sections. No issues found.
modules/manage/partials/authentication.adoc (1)
509-514: Good addition: per-listener SASL enablement is explicit and consistentSetting
authentication_method: saslon Kafka listeners is the right lever and aligns with the examples below. Helm/K8s notes are accurate.modules/develop/partials/http-proxy.adoc (1)
856-861: Accurate summary of auth modes and controlsThis sets correct expectations: listener-level requirement via
authentication_methodand cluster-wide enablement viahttp_authentication. Nicely done.
| *Type:* array | ||
|
|
||
| *Default:* `127.0.0.1:9092` | ||
|
|
||
| .Basic example | ||
| [,yaml] | ||
| ---- | ||
| redpanda: | ||
| kafka_api: |
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Type/default mismatch for kafka_api
kafka_api is documented as an array, but the Default is 127.0.0.1:9092 (scalar). Either:
- Represent the default as an array-of-object (preferred), or
- Document that the property accepts both a legacy scalar and a list (if true).
Examples:
-*Default:* `127.0.0.1:9092`
+*Default:* `[{ address: "127.0.0.1", port: 9092 }]`If dual-typing is supported, add a brief note clarifying both forms.
Also applies to: 329-331
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Searching for occurrences of 'kafka_api'..."
rg -n "kafka_api" -S || true
FILE="modules/reference/pages/properties/broker-properties.adoc"
if [ -f "$FILE" ]; then
echo
echo "Showing lines 300-360 of $FILE for context:"
nl -ba -w3 -s': ' "$FILE" | sed -n '300,360p'
else
echo
echo "File not found at $FILE — listing nearby files in modules/reference/pages/properties:"
ls -la modules/reference/pages/properties || true
fiLength of output: 13038
🏁 Script executed:
#!/bin/bash
set -euo pipefail
FILE="modules/reference/pages/properties/broker-properties.adoc"
if [ -f "$FILE" ]; then
echo "Showing lines 312-348 of $FILE:"
sed -n '312,348p' "$FILE"
else
echo "File not found: $FILE"
ls -la modules/reference/pages/properties || true
fiLength of output: 1112
Type/default mismatch for kafka_api — fix required
Verified: in modules/reference/pages/properties/broker-properties.adoc the kafka_api section declares "Type: array" but the "Default:" is the scalar 127.0.0.1:9092. This is inconsistent and should be fixed.
Files/locations to change:
- modules/reference/pages/properties/broker-properties.adoc — kafka_api section (around the displayed block, Default currently
127.0.0.1:9092)
Suggested fixes (preferred: represent the default as an array-of-objects; alternative: document dual-typing):
Replace:
-*Default:* `127.0.0.1:9092`
+*Default:* `[{ address: "127.0.0.1", port: 9092 }]`If the configuration still accepts the legacy scalar form, add a short note clarifying both accepted forms and show examples for each.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| *Type:* array | |
| *Default:* `127.0.0.1:9092` | |
| .Basic example | |
| [,yaml] | |
| ---- | |
| redpanda: | |
| kafka_api: | |
| *Type:* array | |
| *Default:* `[{ address: "127.0.0.1", port: 9092 }]` | |
| .Basic example | |
| [,yaml] | |
| ---- | |
| redpanda: | |
| kafka_api: |
🤖 Prompt for AI Agents
In modules/reference/pages/properties/broker-properties.adoc around lines 327 to
335, the kafka_api entry declares "Type: array" but shows a scalar Default of
`127.0.0.1:9092`; update the Default to an array form that matches the declared
type (e.g., an array containing an object or string(s) as used by the
configuration), and update the example block to show the array form; if the
config still accepts the legacy scalar, instead document both forms: show the
array default and an additional note with an example of the legacy scalar form
and mention that both are accepted.
There was a problem hiding this comment.
I agree with this for:
admin
schema_registry_api
pandaproxy_api
kafka_api
There was a problem hiding this comment.
🧩 Analysis chain
I'll help fix the type/default mismatches for all four properties you mentioned. Let me first examine the current state of these properties in the documentation.
Now I'll provide the corrected documentation for all four properties. Based on the examples shown in the file content, here are the fixes needed:
1. admin property
Current issue: Type is array-like but default shows scalar format
Fix:
*Type:* array
*Default:* `[{ address: "127.0.0.1", port: 9644 }]`2. kafka_api property
Current issue: Type is array but default shows scalar 127.0.0.1:9092
Fix:
*Type:* array
*Default:* `[{ address: "127.0.0.1", port: 9092 }]`3. schema_registry_api property
Current issue: Likely shows scalar default instead of array format
Fix:
*Type:* array
*Default:* `[{ address: "0.0.0.0", port: 8081 }]`4. pandaproxy_api property
Current issue: Likely shows scalar default instead of array format
Fix:
*Type:* array
*Default:* `[{ address: "0.0.0.0", port: 8082 }]`@BenPope, I've identified the specific fixes needed for all four properties. Each should have their default value represented as an array of objects with address and port fields to match the declared array type and the examples provided in the documentation. This will ensure consistency between the type declarations and default values across all these listener configuration properties.
🏁 Script executed:
#!/bin/bash
# Check the current state of admin, schema_registry_api, pandaproxy_api, and kafka_api properties
echo "=== Examining admin property ==="
rg -A 10 -B 5 "=== admin$" modules/reference/pages/properties/broker-properties.adoc
echo -e "\n=== Examining schema_registry_api property ==="
rg -A 10 -B 5 "=== schema_registry_api$" modules/reference/pages/properties/broker-properties.adoc
echo -e "\n=== Examining pandaproxy_api property ==="
rg -A 10 -B 5 "=== pandaproxy_api$" modules/reference/pages/properties/broker-properties.adoc
echo -e "\n=== Examining kafka_api property ==="
rg -A 10 -B 5 "=== kafka_api$" modules/reference/pages/properties/broker-properties.adoc
Length of output: 1533
Perfect! The script results confirm the exact issues. Here are the specific fixes needed for all four properties:
Required Documentation Fixes
1. admin property
Current state: Scalar default 127.0.0.1:9644, no explicit type
Fix:
=== admin
Network address for the glossterm:Admin API[] server.
*Visibility:* `user`
+*Type:* array
+
-*Default:* `127.0.0.1:9644`
+*Default:* `[{ address: "127.0.0.1", port: 9644 }]`2. schema_registry_api property
Current state: Scalar default 0.0.0.0:8081, no explicit type
Fix:
=== schema_registry_api
Schema Registry API listener address and port.
*Visibility:* `user`
+*Type:* array
+
-*Default:* `0.0.0.0:8081`
+*Default:* `[{ address: "0.0.0.0", port: 8081 }]`3. pandaproxy_api property
Current state: Scalar default 0.0.0.0:8082, no explicit type
Fix:
=== pandaproxy_api
Rest API listener address and port.
*Visibility:* `user`
+*Type:* array
+
-*Default:* `0.0.0.0:8082`
+*Default:* `[{ address: "0.0.0.0", port: 8082 }]`4. kafka_api property
Current state: Has *Type:* array but scalar default 127.0.0.1:9092
Fix:
=== kafka_api
IP address and port of the Kafka API endpoint that handles requests. Supports multiple listeners with different configurations.
*Visibility:* `user`
*Type:* array
-*Default:* `127.0.0.1:9092`
+*Default:* `[{ address: "127.0.0.1", port: 9092 }]`@BenPope, these fixes will ensure consistency between the type declarations and default values for all four listener properties. Each default now properly represents an array containing an object with address and port fields, matching the format used in their respective examples.
| [[http_based_auth_method]] | ||
| ==== HTTP-Based Authentication | ||
|
|
||
| The `authentication_method` property configures authentication for HTTP-based API listeners (Schema Registry and HTTP Proxy). | ||
|
|
||
| *Accepted values:* | ||
| - `none` - No authentication required (allows anonymous access). | ||
| - `http_basic` - Authentication required. The specific authentication method (Basic vs OIDC) depends on the xref:reference:properties/cluster-properties.adoc#http_authentication[`http_authentication`] cluster property and the client's Authorization header type. | ||
|
|
||
| *Default:* `none` | ||
|
|
||
| This property works together with the cluster property xref:reference:properties/cluster-properties.adoc#http_authentication[`http_authentication`]: | ||
|
|
||
| * `authentication_method` (broker property): Controls whether a specific listener requires authentication (`http_basic`) or allows anonymous access (`none`) | ||
| * `http_authentication` (cluster property): Controls which authentication methods are available globally (`["BASIC"]`, `["OIDC"]`, or `["BASIC", "OIDC"]`) | ||
|
|
||
| When `authentication_method: http_basic` is set on a listener, clients can use any authentication method that is enabled in the `http_authentication` cluster property. | ||
|
|
||
| For detailed authentication configuration, see xref:manage:security/authentication.adoc[]. |
There was a problem hiding this comment.
Why does HTTP appear to exist under Kafka? Shouldn't this be a fragment embedded for pandaproxy_api and schema_registry_api
| === api_doc_dir | ||
|
|
||
| Path to the API specifications for the HTTP Proxy API. | ||
| Path to the API specifications directory. This directory contains API documentation for both the Schema Registry API and HTTP Proxy API. |
There was a problem hiding this comment.
This is nested under pandaproxy, why not give SR its own entry?
|
|
||
| *Default:* `/usr/share/redpanda/proxy-api-doc` | ||
|
|
||
| NOTE: Both Schema Registry and HTTP Proxy have independent `api_doc_dir` properties that can be configured separately. However, they both default to the same path (`/usr/share/redpanda/proxy-api-doc`) since they typically use the same API documentation directory. |
There was a problem hiding this comment.
This is nested under pandaproxy, why not give SR its own entry?
There was a problem hiding this comment.
I'm leaning more towards not duplicating properties but adding links when necessary.
Most updates from https://github.com/redpanda-data/docs/pull/1272/files (now Closed) were implemented in #1298. This PR captures the point about TLS, and the Note, which are still of value.
Add missing broker properties and improve examples
Key Changes
Missing Properties Added
advertised_kafka_apiadvertised_rpc_apicloud_storage_cache_directorycloud_storage_inventory_hash_storeProperties Enhanced with Examples
adminadmin_api_tlskafka_api/kafka_api_tlsnode_id_overridesrpc_server_tlsseed_serverspandaproxy_api/pandaproxy_api_tlsschema_registry_api/schema_registry_api_tlsauthentication_methoddeveloper_modeDocumentation Improvements
<placeholder>formatAll examples include explanatory notes for better usability.
Page previews
Most important content change
Broker Properties
Content changes
HTTP Proxy
Redpanda Release Notes
Listener Configuration
Configure Authentication
Link changes
Deploy for Production
Production Readiness
Node Property Configuration
Rack Awareness
Encryption
Tiered Storage
Checks