Update schema registry ACL details #1528
Open
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 PR adds documentation for Schema Registry ACL operations and configuration examples across two reference files. The changes introduce detailed guidance on six Schema Registry operations (read, write, delete, describe, describe_configs, alter_configs) with practical ACL configuration examples for common use cases, including schema migration, read-only consumer access, producer access, and schema administrator access. A new usage example for schema migration ACL permissions is also added to the rpk security ACL create reference documentation. Estimated code review effort🎯 2 (Simple) | ⏱️ ~10–15 minutes
Possibly related PRs
Suggested reviewers
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
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: 2
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Jira integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (2)
modules/manage/pages/schema-reg/schema-reg-authorization.adoc(1 hunks)modules/reference/pages/rpk/rpk-security/rpk-security-acl-create.adoc(1 hunks)
🧰 Additional context used
🧠 Learnings (3)
📓 Common learnings
Learnt from: micheleRP
Repo: redpanda-data/docs PR: 1334
File: modules/manage/partials/rbac-dp.adoc:93-98
Timestamp: 2025-08-25T21:00:26.626Z
Learning: In cloud documentation (env-cloud), Security is at the top level navigation, so ACL references should use `security:authorization/rbac/acl.adoc`. In self-managed documentation, Security is nested under Manage, so ACL references use `manage:security/authorization/acl.adoc`. The different xref paths in conditional blocks reflect these different navigation structures.
📚 Learning: 2025-08-25T21:00:26.626Z
Learnt from: micheleRP
Repo: redpanda-data/docs PR: 1334
File: modules/manage/partials/rbac-dp.adoc:93-98
Timestamp: 2025-08-25T21:00:26.626Z
Learning: In cloud documentation (env-cloud), Security is at the top level navigation, so ACL references should use `security:authorization/rbac/acl.adoc`. In self-managed documentation, Security is nested under Manage, so ACL references use `manage:security/authorization/acl.adoc`. The different xref paths in conditional blocks reflect these different navigation structures.
Applied to files:
modules/reference/pages/rpk/rpk-security/rpk-security-acl-create.adocmodules/manage/pages/schema-reg/schema-reg-authorization.adoc
📚 Learning: 2025-12-12T16:18:28.126Z
Learnt from: andrewstucki
Repo: redpanda-data/docs PR: 1514
File: modules/troubleshoot/partials/errors-and-solutions.adoc:618-632
Timestamp: 2025-12-12T16:18:28.126Z
Learning: In Redpanda ShadowLink CRD usage, do not copy CA certificates into pods via kubectl cp because they won't persist across pod restarts. Store CA certs in Kubernetes Secrets and reference them in the ShadowLink's staticConfiguration block (or inline the cert data in that block) to ensure persistence and proper secret management.
Applied to files:
modules/reference/pages/rpk/rpk-security/rpk-security-acl-create.adocmodules/manage/pages/schema-reg/schema-reg-authorization.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 (5)
modules/reference/pages/rpk/rpk-security/rpk-security-acl-create.adoc (1)
47-51: New schema migration example is clear and well-placed.The addition appropriately documents a common use case for Schema Registry ACL permissions with the correct combination of operations for migration scenarios.
modules/manage/pages/schema-reg/schema-reg-authorization.adoc (4)
199-209: Excellent operation descriptions with clear, actionable explanations.The new "Understanding Schema Registry operations" section clearly explains each of the six supported operations and provides concrete use-case examples for each. These descriptions align accurately with the endpoint-operation mapping table.
214-238: Add conditional handling to the schema-reg-api xref.Line 237 references
xref:manage:schema-reg/schema-reg-api.adoc#set-global-mode[], which is a self-managed path. Since this page is shared between both cloud and self-managed documentation, this xref needs to be wrapped in conditional blocks (usingifdef::env-cloud[]/ifndef::env-cloud[]) to point to the correct API documentation for each environment.🔎 Suggested fix for conditional xref
[NOTE] ==== The target Schema Registry must be in IMPORT mode to preserve schema IDs during migration. Only superusers or principals with `alter_configs` permission on the `registry` resource can change the global mode. See xref:manage:schema-reg/schema-reg-api.adoc#set-global-mode[Set global mode]. ====Replace with:
[NOTE] ==== The target Schema Registry must be in IMPORT mode to preserve schema IDs during migration. Only superusers or principals with `alter_configs` permission on the `registry` resource can change the global mode. +ifndef::env-cloud[] See xref:manage:schema-reg/schema-reg-api.adoc#set-global-mode[Set global mode]. +endif::[] +ifdef::env-cloud[] +See xref:manage:schema-reg/schema-reg-api.adoc#set-global-mode[Set global mode]. +endif::[] ====Based on learnings from previous PRs, the conditional xref paths should be:
manage:schema-reg/schema-reg-api.adocfor self-managed and the cloud equivalent for cloud documentation.
278-296: Schema administrator example is clear and complete.The use of
--operation allfor full schema management is appropriate and well-explained, with clear descriptions of the capabilities granted by the full permission set.
31-35: xref paths correctly handle env-cloud conditions.The conditional blocks properly route to
manage:security/authorization/acl.adocfor self-managed andsecurity:/authorization/acl.adocfor cloud documentation.
Comment on lines
+240
to
+257
| ==== Read-only access for consumers | ||
|
|
||
| Applications that only consume messages with schemas need: | ||
|
|
||
| [,bash] | ||
| ---- | ||
| # For consuming with schema validation | ||
| rpk security acl create \ | ||
| --allow-principal consumer-app \ | ||
| --operation read \ | ||
| --registry-subject "orders-*" | ||
| ---- | ||
|
|
||
| This allows: | ||
|
|
||
| * Reading schema content by ID (embedded in messages) | ||
| * Viewing specific schema versions | ||
| * Does NOT allow listing all subjects or modifying schemas |
Contributor
There was a problem hiding this comment.
Add --resource-pattern-type prefixed flag for wildcard subject patterns.
Line 250 uses --registry-subject "orders-*" with a wildcard pattern, but does not specify --resource-pattern-type prefixed. Without this flag, the literal default pattern type will only match a subject literally named "orders-*", not subjects starting with "orders-". This same issue applies to the producer example at line 269.
🔎 Suggested fix
-# For consuming with schema validation
-rpk security acl create \
- --allow-principal consumer-app \
- --operation read \
- --registry-subject "orders-*"
+# For consuming with schema validation
+rpk security acl create \
+ --allow-principal consumer-app \
+ --operation read \
+ --resource-pattern-type prefixed \
+ --registry-subject "orders-*"🤖 Prompt for AI Agents
In modules/manage/pages/schema-reg/schema-reg-authorization.adoc around lines
240 to 257 (and also update the producer example at line ~269), the rpk ACL
commands use wildcard registry subjects like "orders-*" but omit the
--resource-pattern-type prefixed flag so the pattern will be interpreted
literally; update the examples to include --resource-pattern-type prefixed on
any ACL commands that use wildcard subject patterns (e.g., add
--resource-pattern-type prefixed to the read-only consumer command at line ~250
and to the producer example at line ~269) so the ACLs match subjects with the
given prefix.
Comment on lines
+259
to
+276
| ==== Producer access | ||
|
|
||
| Applications that produce messages with schemas need: | ||
|
|
||
| [,bash] | ||
| ---- | ||
| # For producing with new schemas | ||
| rpk security acl create \ | ||
| --allow-principal producer-app \ | ||
| --operation read,write,describe \ | ||
| --registry-subject "orders-*" | ||
| ---- | ||
|
|
||
| This allows: | ||
|
|
||
| * Checking if schemas already exist (`describe`) | ||
| * Reading existing schema versions (`read`) | ||
| * Registering new schema versions (`write`) |
Contributor
There was a problem hiding this comment.
Add --resource-pattern-type prefixed flag for wildcard subject patterns.
Line 269 uses --registry-subject "orders-*" with a wildcard pattern, but does not specify --resource-pattern-type prefixed. The literal default pattern type will only match a subject literally named "orders-*", not subjects starting with "orders-".
🔎 Suggested fix
-# For producing with new schemas
-rpk security acl create \
- --allow-principal producer-app \
- --operation read,write,describe \
- --registry-subject "orders-*"
+# For producing with new schemas
+rpk security acl create \
+ --allow-principal producer-app \
+ --operation read,write,describe \
+ --resource-pattern-type prefixed \
+ --registry-subject "orders-*"📝 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.
Suggested change
| ==== Producer access | |
| Applications that produce messages with schemas need: | |
| [,bash] | |
| ---- | |
| # For producing with new schemas | |
| rpk security acl create \ | |
| --allow-principal producer-app \ | |
| --operation read,write,describe \ | |
| --registry-subject "orders-*" | |
| ---- | |
| This allows: | |
| * Checking if schemas already exist (`describe`) | |
| * Reading existing schema versions (`read`) | |
| * Registering new schema versions (`write`) | |
| ==== Producer access | |
| Applications that produce messages with schemas need: | |
| [,bash] | |
| ---- | |
| # For producing with new schemas | |
| rpk security acl create \ | |
| --allow-principal producer-app \ | |
| --operation read,write,describe \ | |
| --resource-pattern-type prefixed \ | |
| --registry-subject "orders-*" | |
| ---- | |
| This allows: | |
| * Checking if schemas already exist (`describe`) | |
| * Reading existing schema versions (`read`) | |
| * Registering new schema versions (`write`) |
🤖 Prompt for AI Agents
In modules/manage/pages/schema-reg/schema-reg-authorization.adoc around lines
259 to 276, the rpk ACL example uses --registry-subject "orders-*" but omits the
--resource-pattern-type prefixed flag, so the wildcard will be treated
literally; update the example command to include --resource-pattern-type
prefixed so the ACL applies to subjects starting with "orders-" (i.e., add the
flag to the rpk security acl create invocation).
Feediver1
reviewed
Dec 19, 2025
|
|
||
| === Understanding Schema Registry operations | ||
|
|
||
| The following operations are used to control access to Schema Registry resources: |
Contributor
There was a problem hiding this comment.
Suggested change
| The following operations are used to control access to Schema Registry resources: | |
| You can use the following operations to control access to Schema Registry resources: |
Feediver1
reviewed
Dec 19, 2025
|
|
||
| For additional guidance on these operations, see the link:/api/doc/schema-registry/operation/operation-get_security_acls[Redpanda Schema Registry API]. | ||
|
|
||
| === Understanding Schema Registry operations |
Contributor
There was a problem hiding this comment.
Suggested change
| === Understanding Schema Registry operations | |
| === Operation definitions |
Feediver1
reviewed
Dec 19, 2025
|
|
||
| The following operations are used to control access to Schema Registry resources: | ||
|
|
||
| * **`read`**: Allows reading schemas and their content. Required for consuming messages that use Schema Registry, fetching specific schema versions, and reading schema content by ID. |
Contributor
There was a problem hiding this comment.
Suggested change
| * **`read`**: Allows reading schemas and their content. Required for consuming messages that use Schema Registry, fetching specific schema versions, and reading schema content by ID. | |
| * **`read`**: Allows user to read schemas and their content. Required for consuming messages that use Schema Registry, fetching specific schema versions, and reading schema content by ID. |
Feediver1
reviewed
Dec 19, 2025
| The following operations are used to control access to Schema Registry resources: | ||
|
|
||
| * **`read`**: Allows reading schemas and their content. Required for consuming messages that use Schema Registry, fetching specific schema versions, and reading schema content by ID. | ||
| * **`write`**: Allows registering new schemas and schema versions. Required for producing messages with new schemas and updating existing subjects with new schema versions. |
Contributor
There was a problem hiding this comment.
Suggested change
| * **`write`**: Allows registering new schemas and schema versions. Required for producing messages with new schemas and updating existing subjects with new schema versions. | |
| * **`write`**: Allows user to register new schemas and schema versions. Required for producing messages with new schemas and updating existing subjects with new schema versions. |
Feediver1
reviewed
Dec 19, 2025
|
|
||
| * **`read`**: Allows reading schemas and their content. Required for consuming messages that use Schema Registry, fetching specific schema versions, and reading schema content by ID. | ||
| * **`write`**: Allows registering new schemas and schema versions. Required for producing messages with new schemas and updating existing subjects with new schema versions. | ||
| * **`delete`**: Allows deleting schema versions and subjects. Required for cleanup operations and removing deprecated schemas. |
Contributor
There was a problem hiding this comment.
Suggested change
| * **`delete`**: Allows deleting schema versions and subjects. Required for cleanup operations and removing deprecated schemas. | |
| * **`delete`**: Allows user to delete schema versions and subjects. Required for cleanup operations and removing deprecated schemas. |
Feediver1
reviewed
Dec 19, 2025
| * **`read`**: Allows reading schemas and their content. Required for consuming messages that use Schema Registry, fetching specific schema versions, and reading schema content by ID. | ||
| * **`write`**: Allows registering new schemas and schema versions. Required for producing messages with new schemas and updating existing subjects with new schema versions. | ||
| * **`delete`**: Allows deleting schema versions and subjects. Required for cleanup operations and removing deprecated schemas. | ||
| * **`describe`**: Allows listing and describing Schema Registry resources. Required for discovering available subjects, listing schema versions, and viewing metadata. |
Contributor
There was a problem hiding this comment.
Suggested change
| * **`describe`**: Allows listing and describing Schema Registry resources. Required for discovering available subjects, listing schema versions, and viewing metadata. | |
| * **`describe`**: Allows user to list and describe Schema Registry resources. Required for discovering available subjects, listing schema versions, and viewing metadata. |
Feediver1
reviewed
Dec 19, 2025
| * **`write`**: Allows registering new schemas and schema versions. Required for producing messages with new schemas and updating existing subjects with new schema versions. | ||
| * **`delete`**: Allows deleting schema versions and subjects. Required for cleanup operations and removing deprecated schemas. | ||
| * **`describe`**: Allows listing and describing Schema Registry resources. Required for discovering available subjects, listing schema versions, and viewing metadata. | ||
| * **`describe_configs`**: Allows reading configuration settings. Required for viewing compatibility settings, reading modes (IMPORT/READWRITE), and checking global or per-subject configurations. |
Contributor
There was a problem hiding this comment.
Suggested change
| * **`describe_configs`**: Allows reading configuration settings. Required for viewing compatibility settings, reading modes (IMPORT/READWRITE), and checking global or per-subject configurations. | |
| * **`describe_configs`**: Allows user to read configuration settings. Required for viewing compatibility settings, reading modes (IMPORT/READWRITE), and checking global or per-subject configurations. |
Feediver1
reviewed
Dec 19, 2025
| * **`delete`**: Allows deleting schema versions and subjects. Required for cleanup operations and removing deprecated schemas. | ||
| * **`describe`**: Allows listing and describing Schema Registry resources. Required for discovering available subjects, listing schema versions, and viewing metadata. | ||
| * **`describe_configs`**: Allows reading configuration settings. Required for viewing compatibility settings, reading modes (IMPORT/READWRITE), and checking global or per-subject configurations. | ||
| * **`alter_configs`**: Allows modifying configuration settings. Required for changing compatibility levels, setting IMPORT mode for migrations, and updating global or per-subject configurations. |
Contributor
There was a problem hiding this comment.
Suggested change
| * **`alter_configs`**: Allows modifying configuration settings. Required for changing compatibility levels, setting IMPORT mode for migrations, and updating global or per-subject configurations. | |
| * **`alter_configs`**: Allows user to modify configuration settings. Required for changing compatibility levels, setting IMPORT mode for migrations, and updating global or per-subject configurations. |
Feediver1
reviewed
Dec 19, 2025
|
|
||
| ==== Read-only access for consumers | ||
|
|
||
| Applications that only consume messages with schemas need: |
Contributor
There was a problem hiding this comment.
Suggested change
| Applications that only consume messages with schemas need: | |
| Applications that only consume messages with schemas require: |
Feediver1
reviewed
Dec 19, 2025
|
|
||
| * Reading schema content by ID (embedded in messages) | ||
| * Viewing specific schema versions | ||
| * Does NOT allow listing all subjects or modifying schemas |
Contributor
There was a problem hiding this comment.
Suggested change
| * Does NOT allow listing all subjects or modifying schemas | |
| * Does _not_ allow listing all subjects or modifying schemas |
Feediver1
reviewed
Dec 19, 2025
|
|
||
| ==== Producer access | ||
|
|
||
| Applications that produce messages with schemas need: |
Contributor
There was a problem hiding this comment.
Suggested change
| Applications that produce messages with schemas need: | |
| Applications that produce messages with schemas require: |
Feediver1
reviewed
Dec 19, 2025
|
|
||
| ==== Schema administrator access | ||
|
|
||
| Schema administrators who manage compatibility and cleanup need: |
Contributor
There was a problem hiding this comment.
Suggested change
| Schema administrators who manage compatibility and cleanup need: | |
| Schema administrators who manage compatibility and cleanup require: |
Feediver1
reviewed
Dec 19, 2025
| --registry-global | ||
| ---- | ||
|
|
||
| This grants all operations including: |
Contributor
There was a problem hiding this comment.
Suggested change
| This grants all operations including: | |
| This grants all operations, including: |
Feediver1
reviewed
Dec 19, 2025
Comment on lines
+48
to
+51
|
|
||
| ```bash | ||
| rpk security acl create --allow-principal migrator-user --operation read,write,describe,alter_configs,describe_configs --registry-global | ||
| ``` |
Contributor
There was a problem hiding this comment.
Suggested change
| ```bash | |
| rpk security acl create --allow-principal migrator-user --operation read,write,describe,alter_configs,describe_configs --registry-global | |
| ``` | |
| [,bash] | |
| ---- | |
| rpk security acl create --allow-principal migrator-user --operation read,write,describe,alter_configs,describe_configs --registry-global | |
| ---- |
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
Added two new sections to explain what ACLs operations relate to the schema registry (and when to use them).
"Understanding Schema Registry operations" - Explains what each operation does in plain language:
"Common use cases" - Provides practical examples for:
Also added a new example showing migration permissions (
rpk security acl create --allow-principal migrator-user --operation read,write,describe,alter_configs,describe_configs --registry-global).Page previews
Checks