From ad672e24018240f5d6576b940379fd553ce6e098 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Tue, 31 Mar 2026 17:36:45 +0100 Subject: [PATCH 1/5] docs: Fix broken xrefs in single-sourced content Fix broken cross-references that appear when building cloud-docs: - Conditionalize tiered-storage.adoc xrefs using self-managed-only prefix - Fix k-production-deployment.adoc path in k-group-controller.adoc - Conditionalize gbac.adoc xrefs for cloud builds - Update property-overrides.json to preserve changes in autogenerated docs --- docs-data/property-overrides.json | 8 ++++---- .../pages/audit-logging/audit-log-samples.adoc | 5 ++++- .../authorization/k-group-controller.adoc | 9 +++++++-- .../manage/pages/security/authorization/acl.adoc | 3 --- .../partials/properties/cluster-properties.adoc | 16 ++++++++++++++++ 5 files changed, 31 insertions(+), 10 deletions(-) diff --git a/docs-data/property-overrides.json b/docs-data/property-overrides.json index 370f4ce092..ab5cb9b54d 100644 --- a/docs-data/property-overrides.json +++ b/docs-data/property-overrides.json @@ -1092,16 +1092,16 @@ "config_scope": "topic" }, "initial_retention_local_target_bytes_default": { - "description": "Initial local retention size target for partitions of topics with xref:manage:tiered-storage.adoc[Tiered Storage] enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to learner when joining the partition replica set.", + "description": "Initial local retention size target for partitions of topics with Tiered Storage enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to learner when joining the partition replica set.", "related_topics": [ - "xref:manage:tiered-storage.adoc[Tiered Storage]" + "self-managed-only: xref:manage:tiered-storage.adoc[Tiered Storage]" ], "config_scope": "cluster" }, "initial_retention_local_target_ms_default": { - "description": "Initial local retention time target for partitions of topics with xref:manage:tiered-storage.adoc[Tiered Storage] enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to learner when joining the partition replica is set.", + "description": "Initial local retention time target for partitions of topics with Tiered Storage enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to learner when joining the partition replica is set.", "related_topics": [ - "xref:manage:tiered-storage.adoc[Tiered Storage]" + "self-managed-only: xref:manage:tiered-storage.adoc[Tiered Storage]" ], "config_scope": "cluster" }, diff --git a/modules/manage/pages/audit-logging/audit-log-samples.adoc b/modules/manage/pages/audit-logging/audit-log-samples.adoc index 6681c21047..70741e4ddd 100644 --- a/modules/manage/pages/audit-logging/audit-log-samples.adoc +++ b/modules/manage/pages/audit-logging/audit-log-samples.adoc @@ -296,7 +296,10 @@ This example illustrates an ACL update that also requires a superuser authentica .Authorization matched on a group ACL [%collapsible] ==== -This example shows an API Activity (6003) where the authorization decision matched an ALLOW ACL on a `Group:` principal. The `actor.user.groups` field includes the matched group with type `idp_group`, and the `authorization_metadata` shows the group ACL that granted access. See xref:{gbac-doc}[Group-Based Access Control]. +This example shows an API Activity (6003) where the authorization decision matched an ALLOW ACL on a `Group:` principal. The `actor.user.groups` field includes the matched group with type `idp_group`, and the `authorization_metadata` shows the group ACL that granted access. +ifndef::env-cloud[] +See xref:{gbac-doc}[Group-Based Access Control]. +endif::[] [,json] ---- diff --git a/modules/manage/pages/kubernetes/security/authorization/k-group-controller.adoc b/modules/manage/pages/kubernetes/security/authorization/k-group-controller.adoc index 1c21d6cbcd..a0139649bc 100644 --- a/modules/manage/pages/kubernetes/security/authorization/k-group-controller.adoc +++ b/modules/manage/pages/kubernetes/security/authorization/k-group-controller.adoc @@ -40,8 +40,13 @@ This is useful when: You must have the following: * *Kubectl*: Ensure you have the https://kubernetes.io/docs/tasks/tools/#kubectl[kubectl^] command-line tool installed and configured to communicate with your cluster. -* *Redpanda Operator*: Ensure you have at least version 25.3 of the xref:deploy:kubernetes/k-production-deployment.adoc[Redpanda Operator]. -* *Redpanda cluster with OIDC enabled*: Ensure you have a Redpanda cluster deployed with xref:manage:security/authentication/oidc/index.adoc[OIDC authentication] configured. Group-based access control (GBAC) is an enterprise feature that requires OIDC. +* *Redpanda Operator*: Ensure you have at least version 25.3 of the xref:deploy:redpanda/kubernetes/k-production-deployment.adoc[Redpanda Operator]. +ifndef::env-cloud[] +* *Redpanda cluster with OIDC enabled*: Ensure you have a Redpanda cluster deployed with xref:manage:security/authorization/gbac.adoc[OIDC authentication] configured. Group-based access control (GBAC) is an enterprise feature that requires OIDC. +endif::[] +ifdef::env-cloud[] +* *Redpanda cluster with OIDC enabled*: Ensure you have a Redpanda cluster deployed with OIDC authentication configured. Group-based access control (GBAC) is an enterprise feature that requires OIDC. +endif::[] * *Redpanda v26.1+*: The cluster must be running Redpanda v26.1 or later, which supports the v2 Security API required for group principals. == Create a Group resource diff --git a/modules/manage/pages/security/authorization/acl.adoc b/modules/manage/pages/security/authorization/acl.adoc index 35fec7a6f3..cdb6df6142 100644 --- a/modules/manage/pages/security/authorization/acl.adoc +++ b/modules/manage/pages/security/authorization/acl.adoc @@ -95,9 +95,6 @@ All ACLs require a principal. A principal is composed of two parts: the type, an ifndef::env-cloud[] See xref:manage:security/authorization/gbac.adoc[]. endif::[] -ifdef::env-cloud[] -See xref:security:authorization/gbac.adoc[]. -endif::[] The `--allow-principal` and `--deny-principal` flags add this prefix for you, if necessary. diff --git a/modules/reference/partials/properties/cluster-properties.adoc b/modules/reference/partials/properties/cluster-properties.adoc index f2d8c5c636..752ef3d494 100644 --- a/modules/reference/partials/properties/cluster-properties.adoc +++ b/modules/reference/partials/properties/cluster-properties.adoc @@ -4990,7 +4990,9 @@ endif::[] | Related topics | +ifndef::env-cloud[] * xref:manage:tiered-storage.adoc[Tiered Storage] +endif::[] * xref:develop:manage-topics/cloud-topics.adoc[Manage Cloud Topics] @@ -9166,7 +9168,12 @@ endif::[] === initial_retention_local_target_bytes_default +ifndef::env-cloud[] Initial local retention size target for partitions of topics with xref:manage:tiered-storage.adoc[Tiered Storage] enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to learner when joining the partition replica set. +endif::[] +ifdef::env-cloud[] +Initial local retention size target for partitions of topics with Tiered Storage enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to learner when joining the partition replica set. +endif::[] [cols="1s,2a"] |=== @@ -9202,15 +9209,22 @@ ifndef::env-cloud[] | User endif::[] +ifndef::env-cloud[] | Related topics |xref:manage:tiered-storage.adoc[Tiered Storage] +endif::[] |=== === initial_retention_local_target_ms_default +ifndef::env-cloud[] Initial local retention time target for partitions of topics with xref:manage:tiered-storage.adoc[Tiered Storage] enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to learner when joining the partition replica is set. +endif::[] +ifdef::env-cloud[] +Initial local retention time target for partitions of topics with Tiered Storage enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to learner when joining the partition replica is set. +endif::[] [cols="1s,2a"] |=== @@ -9249,8 +9263,10 @@ ifndef::env-cloud[] | User endif::[] +ifndef::env-cloud[] | Related topics |xref:manage:tiered-storage.adoc[Tiered Storage] +endif::[] |=== From ee7121df1f83b59b913ae50f8954c3c57a6af952 Mon Sep 17 00:00:00 2001 From: Jake Cahill <45230295+JakeSCahill@users.noreply.github.com> Date: Tue, 31 Mar 2026 17:44:01 +0100 Subject: [PATCH 2/5] Update docs-data/property-overrides.json Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- docs-data/property-overrides.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-data/property-overrides.json b/docs-data/property-overrides.json index ab5cb9b54d..2dcc09389b 100644 --- a/docs-data/property-overrides.json +++ b/docs-data/property-overrides.json @@ -1099,7 +1099,7 @@ "config_scope": "cluster" }, "initial_retention_local_target_ms_default": { - "description": "Initial local retention time target for partitions of topics with Tiered Storage enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to learner when joining the partition replica is set.", + "description": "Initial local retention time target for partitions of topics with Tiered Storage enabled. If no initial local target retention is configured, then all locally-retained data will be delivered to the learner when joining the partition replica set.", "related_topics": [ "self-managed-only: xref:manage:tiered-storage.adoc[Tiered Storage]" ], From c0e58055dd67c647479a7c4e48306cd8355d33b9 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Tue, 31 Mar 2026 17:47:07 +0100 Subject: [PATCH 3/5] docs: Fix cloud-topics.adoc xrefs in property docs Add self-managed-only prefix to cloud-topics.adoc xrefs in: - cloud_topics_enabled property - default_redpanda_storage_mode property --- docs-data/property-overrides.json | 2 +- modules/reference/partials/properties/cluster-properties.adoc | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs-data/property-overrides.json b/docs-data/property-overrides.json index 2dcc09389b..a13c840587 100644 --- a/docs-data/property-overrides.json +++ b/docs-data/property-overrides.json @@ -499,7 +499,7 @@ "cloud_topics_enabled": { "description": "Enable Cloud Topics for the cluster. Cloud Topics are optimized for high-throughput, cost-sensitive workloads that can tolerate higher latencies compared to standard Kafka topics.", "related_topics": [ - "xref:develop:manage-topics/cloud-topics.adoc[Cloud Topics]" + "self-managed-only: xref:develop:manage-topics/cloud-topics.adoc[Cloud Topics]" ], "config_scope": "cluster" }, diff --git a/modules/reference/partials/properties/cluster-properties.adoc b/modules/reference/partials/properties/cluster-properties.adoc index 752ef3d494..a3ca43602a 100644 --- a/modules/reference/partials/properties/cluster-properties.adoc +++ b/modules/reference/partials/properties/cluster-properties.adoc @@ -1185,8 +1185,10 @@ ifndef::env-cloud[] | User endif::[] +ifndef::env-cloud[] | Related topics |xref:develop:manage-topics/cloud-topics.adoc[Cloud Topics] +endif::[] |=== @@ -4992,9 +4994,9 @@ endif::[] | ifndef::env-cloud[] * xref:manage:tiered-storage.adoc[Tiered Storage] -endif::[] * xref:develop:manage-topics/cloud-topics.adoc[Manage Cloud Topics] +endif::[] |=== From fc24c96e4e3a2413172e67a519dbbe20cad0566b Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Tue, 31 Mar 2026 17:56:29 +0100 Subject: [PATCH 4/5] docs: Add cloud xrefs for gbac.adoc Use attribute-based xrefs to point to correct gbac.adoc location: - Self-managed: manage:security/authorization/gbac.adoc - Cloud: security:authorization/gbac.adoc --- modules/manage/pages/audit-logging/audit-log-samples.adoc | 5 +---- modules/manage/pages/security/authorization/acl.adoc | 8 ++++---- 2 files changed, 5 insertions(+), 8 deletions(-) diff --git a/modules/manage/pages/audit-logging/audit-log-samples.adoc b/modules/manage/pages/audit-logging/audit-log-samples.adoc index 70741e4ddd..6681c21047 100644 --- a/modules/manage/pages/audit-logging/audit-log-samples.adoc +++ b/modules/manage/pages/audit-logging/audit-log-samples.adoc @@ -296,10 +296,7 @@ This example illustrates an ACL update that also requires a superuser authentica .Authorization matched on a group ACL [%collapsible] ==== -This example shows an API Activity (6003) where the authorization decision matched an ALLOW ACL on a `Group:` principal. The `actor.user.groups` field includes the matched group with type `idp_group`, and the `authorization_metadata` shows the group ACL that granted access. -ifndef::env-cloud[] -See xref:{gbac-doc}[Group-Based Access Control]. -endif::[] +This example shows an API Activity (6003) where the authorization decision matched an ALLOW ACL on a `Group:` principal. The `actor.user.groups` field includes the matched group with type `idp_group`, and the `authorization_metadata` shows the group ACL that granted access. See xref:{gbac-doc}[Group-Based Access Control]. [,json] ---- diff --git a/modules/manage/pages/security/authorization/acl.adoc b/modules/manage/pages/security/authorization/acl.adoc index cdb6df6142..4ea377c8c5 100644 --- a/modules/manage/pages/security/authorization/acl.adoc +++ b/modules/manage/pages/security/authorization/acl.adoc @@ -4,6 +4,9 @@ // tag::single-source[] :description: Learn how to use ACLs to configure fine-grained access to Redpanda resources. +ifdef::env-cloud[:gbac-doc: security:authorization/gbac.adoc] +ifndef::env-cloud[:gbac-doc: manage:security/authorization/gbac.adoc] + Access control lists (ACLs) provide a way to configure fine-grained access to Redpanda resources. ACLs are permission rules that determine which actions users or roles can perform on Redpanda resources. Redpanda stores ACLs internally, replicated with glossterm:Raft[] to provide the same consensus guarantees as your data. ifndef::env-cloud[] @@ -91,10 +94,7 @@ ACL commands work on a multiplicative basis. If you specify two principals and t [[principals]] === Principals -All ACLs require a principal. A principal is composed of two parts: the type, and the name. Redpanda supports the types "User", "RedpandaRole", and "Group". When you create user "bar", Redpanda expects you to add ACLs for "User:bar". To grant permissions to an OIDC group, use the `Group:` prefix (for example, `Group:engineering`). -ifndef::env-cloud[] -See xref:manage:security/authorization/gbac.adoc[]. -endif::[] +All ACLs require a principal. A principal is composed of two parts: the type, and the name. Redpanda supports the types "User", "RedpandaRole", and "Group". When you create user "bar", Redpanda expects you to add ACLs for "User:bar". To grant permissions to an OIDC group, use the `Group:` prefix (for example, `Group:engineering`). See xref:{gbac-doc}[]. The `--allow-principal` and `--deny-principal` flags add this prefix for you, if necessary. From 7e471a84ca10f70a5c832dfbcc0b5a97ce430184 Mon Sep 17 00:00:00 2001 From: Jake Cahill <45230295+JakeSCahill@users.noreply.github.com> Date: Tue, 31 Mar 2026 17:59:38 +0100 Subject: [PATCH 5/5] Update k-group-controller.adoc --- .../security/authorization/k-group-controller.adoc | 5 ----- 1 file changed, 5 deletions(-) diff --git a/modules/manage/pages/kubernetes/security/authorization/k-group-controller.adoc b/modules/manage/pages/kubernetes/security/authorization/k-group-controller.adoc index a0139649bc..5a336af40b 100644 --- a/modules/manage/pages/kubernetes/security/authorization/k-group-controller.adoc +++ b/modules/manage/pages/kubernetes/security/authorization/k-group-controller.adoc @@ -41,12 +41,7 @@ You must have the following: * *Kubectl*: Ensure you have the https://kubernetes.io/docs/tasks/tools/#kubectl[kubectl^] command-line tool installed and configured to communicate with your cluster. * *Redpanda Operator*: Ensure you have at least version 25.3 of the xref:deploy:redpanda/kubernetes/k-production-deployment.adoc[Redpanda Operator]. -ifndef::env-cloud[] * *Redpanda cluster with OIDC enabled*: Ensure you have a Redpanda cluster deployed with xref:manage:security/authorization/gbac.adoc[OIDC authentication] configured. Group-based access control (GBAC) is an enterprise feature that requires OIDC. -endif::[] -ifdef::env-cloud[] -* *Redpanda cluster with OIDC enabled*: Ensure you have a Redpanda cluster deployed with OIDC authentication configured. Group-based access control (GBAC) is an enterprise feature that requires OIDC. -endif::[] * *Redpanda v26.1+*: The cluster must be running Redpanda v26.1 or later, which supports the v2 Security API required for group principals. == Create a Group resource