From 5987568a464152c561faf2024ded82450fd9492b Mon Sep 17 00:00:00 2001 From: david-yu Date: Mon, 30 Mar 2026 13:12:36 -0700 Subject: [PATCH 1/4] docs (k8s): add Group CRD documentation for managing OIDC group ACLs Co-Authored-By: Claude Opus 4.6 (1M context) --- modules/ROOT/nav.adoc | 1 + .../examples/kubernetes/group-crds.feature | 40 +++ .../authorization/k-group-controller.adoc | 230 ++++++++++++++++++ 3 files changed, 271 insertions(+) create mode 100644 modules/manage/examples/kubernetes/group-crds.feature create mode 100644 modules/manage/pages/kubernetes/security/authorization/k-group-controller.adoc diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 3c8abcbce6..ce5ef37ca4 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -134,6 +134,7 @@ ***** xref:manage:kubernetes/security/authentication/k-authentication.adoc[Enable Authentication] ***** xref:manage:kubernetes/security/authentication/k-user-controller.adoc[Manage Users and ACLs (Operator)] ***** xref:manage:kubernetes/security/authorization/k-role-controller.adoc[Manage Roles and ACLs (Operator)] +***** xref:manage:kubernetes/security/authorization/k-group-controller.adoc[Manage Groups and ACLs (Operator)] **** xref:manage:kubernetes/security/k-audit-logging.adoc[Audit Logging] *** xref:manage:kubernetes/k-rack-awareness.adoc[Rack Awareness] *** xref:manage:kubernetes/k-remote-read-replicas.adoc[Remote Read Replicas] diff --git a/modules/manage/examples/kubernetes/group-crds.feature b/modules/manage/examples/kubernetes/group-crds.feature new file mode 100644 index 0000000000..0ff6536558 --- /dev/null +++ b/modules/manage/examples/kubernetes/group-crds.feature @@ -0,0 +1,40 @@ +@cluster:sasl @variant:vectorized +Feature: Group CRDs + Background: Cluster available + Given cluster "sasl" is available + + @skip:gke @skip:aks @skip:eks + Scenario: Manage group ACLs + When I apply Kubernetes manifest: + """ +# tag::manage-group-acls[] + # In this example manifest, ACLs are created for an OIDC group called "engineering" + # in a cluster called "sasl". The group is granted read access to topics matching "team-" + # and read access to Schema Registry subjects matching "team-". + --- + apiVersion: cluster.redpanda.com/v1alpha2 + kind: Group + metadata: + name: engineering + spec: + cluster: + clusterRef: + name: sasl + authorization: + acls: + - type: allow + resource: + type: topic + name: team- + patternType: prefixed + operations: [Read, Describe] + - type: allow + resource: + type: subject + name: team- + patternType: prefixed + operations: [Read, Describe] +# end::manage-group-acls[] + """ + And group "engineering" is successfully synced + Then group "engineering" should have 2 ACLs for topic pattern "team-" in cluster "sasl" diff --git a/modules/manage/pages/kubernetes/security/authorization/k-group-controller.adoc b/modules/manage/pages/kubernetes/security/authorization/k-group-controller.adoc new file mode 100644 index 0000000000..c8a1168bc4 --- /dev/null +++ b/modules/manage/pages/kubernetes/security/authorization/k-group-controller.adoc @@ -0,0 +1,230 @@ += Manage Groups and ACLs with the Redpanda Operator +:description: Use the Group resource to declaratively manage ACLs for OIDC groups as part of a Redpanda deployment. Each Group resource maps to an external OIDC group identity and manages the Kafka ACLs for that group principal. +:page-categories: Management, Security +:env-kubernetes: true + +With the Redpanda Operator, you can declaratively manage Kafka ACLs for OIDC groups using xref:reference:k-crd.adoc#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-group[Group custom resources] (resources) in Kubernetes. Each Group resource maps to an external OIDC group identity and manages the Kafka ACLs for that group's principal. The group controller, a component of the Redpanda Operator, keeps the corresponding ACLs in sync with the Group resource. + +NOTE: Groups are external identities sourced from your OIDC identity provider (IdP) via JWT token claims. Unlike xref:manage:kubernetes/security/authentication/k-user-controller.adoc[User resources], Group resources do not create entities in Redpanda -- they only manage ACLs for the `Group:` principal. + +== What are groups and why use them? + +Groups let you assign Kafka ACL permissions to OIDC identities without creating individual Redpanda users. When a user authenticates through your OIDC provider, the JWT token includes group claims. Redpanda maps those group claims to ACL principals of the form `Group:`, so any user in that OIDC group inherits the group's permissions. + +This is useful when: + +* *You use an external identity provider*: Your organization manages identities in an IdP such as Okta, Azure AD, or Keycloak, and you want Redpanda permissions to follow those group memberships. +* *You want centralized access management*: Instead of creating individual Redpanda users and assigning permissions one by one, you grant permissions to groups. When someone joins or leaves a group in your IdP, their Redpanda access updates automatically. +* *You want to combine with roles*: Groups can be assigned as principals in xref:manage:kubernetes/security/authorization/k-role-controller.adoc[RedpandaRole resources], allowing OIDC groups to inherit role-based permissions. + +== Prerequisites + +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:deployment-option/self-hosted/kubernetes/k-production-deployment.adoc[Redpanda Operator]. +* *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. +* *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 + +You can use the Group resource to: + +- <> +- <> + +Each Group resource manages the ACLs for a single group principal (`Group:`). Only one Group resource is allowed per group name in the Redpanda cluster. + +[[with-acls]] +=== Create ACLs for an OIDC group + +- *Use case*: You want to grant specific Kafka permissions to all users who belong to an OIDC group. This is the most common use case, where your IdP manages group membership and Redpanda enforces the permissions. +- *What happens when deleted*: All ACLs managed by this Group resource are removed. Users in the OIDC group lose the permissions granted by this resource. + +This example shows how to create ACLs for an OIDC group called `engineering`, granting read access to topics and Schema Registry subjects matching `team-`. + +.`engineering-group.yaml` +[,yaml,indent=0] +---- +include::manage:example$kubernetes/group-crds.feature[tags=manage-group-acls,indent=0] +---- + +[[without-acls]] +=== Register a group without ACLs + +- *Use case*: You want to ensure no stale ACLs exist for a group, or you want to create the Group resource first and add ACLs later. +- *What happens when deleted*: No ACLs are affected because none were defined. + +When you create a Group resource without an `authorization` section, the operator ensures that no ACLs exist for the group principal. If any pre-existing ACLs were previously set for this group, they are removed. + +.`empty-group.yaml` +[,yaml,indent=0] +---- +apiVersion: cluster.redpanda.com/v1alpha2 +kind: Group +metadata: + name: empty-group +spec: + cluster: + clusterRef: + name: redpanda +---- + +== Configuration + +The following sections provide guidance on configuring Group resources and defining ACLs for OIDC groups. + +=== Choose a group name + +The `metadata.name` field in the Group resource must match the group name in your OIDC provider's JWT token claims. Keep in mind the following: + +- *Match your IdP*: The name must exactly match the group claim value from your OIDC provider. For example, if your IdP sends `engineering` as a group claim, the Group resource must be named `engineering`. +- *Unique*: Each group name must be unique within the Redpanda cluster. +- *Stable*: Avoid changing group names, as this involves deleting and recreating the Group resource. The cluster source is immutable. + +[,yaml] +---- +metadata: + name: engineering +---- + +=== Reference the Redpanda cluster + +The `spec.cluster` field specifies which Redpanda cluster the ACLs should be applied to. This field is immutable after creation. + +[,yaml] +---- +spec: + cluster: + clusterRef: + name: redpanda +---- + +=== Define authorization rules + +The `spec.authorization` field allows you to manage ACLs for the group. ACLs define the permissions that all members of the OIDC group have over specific resources in Redpanda, such as topics, consumer groups, and Schema Registry subjects. + +[source,yaml] +---- +spec: + authorization: + acls: + - type: allow + resource: + type: topic + name: team- + patternType: prefixed + operations: [Read, Describe] + - type: allow + resource: + type: subject + name: team- + patternType: prefixed + operations: [Read, Describe] +---- + +- `type`: Defines whether the ACL allows or denies access. Acceptable values: `allow`, `deny`. +- `resource.type`: Specifies the resource type. Acceptable values: `topic`, `group`, `cluster`, `transactionalId`, `subject`. +- `patternType`: Specifies how the resource name is interpreted. Acceptable values: `literal`, `prefixed`. Default: `literal`. ++ +TIP: Using `literal` names for resources ensures that only the exact resources you intend are accessible. Use `prefixed` patterns cautiously to avoid accidental permission grants. +- `operations`: Lists the allowed operations, such as `Read`, `Write`, `Create`, `Describe`, and `Delete`. + +When the `authorization` field is omitted or contains an empty `acls` list, the operator removes any existing ACLs for the group principal. + +For more details about ACLs, including supported operations and resources in Redpanda, see xref:manage:security/authorization/acl.adoc[]. + +== Deploy a Group resource + +To deploy a Group resource, apply the manifest to the same namespace as your Redpanda cluster: + +[,bash] +---- +kubectl apply -f .yaml --namespace +---- + +- Replace `` with the filename of your manifest. +- Replace `` with the namespace in which you deployed Redpanda. + +== Verify a group + +After deploying a Group resource, verify that the Redpanda Operator reconciled it: + +[,bash] +---- +kubectl get groups --namespace +---- + +The `SYNCED` column should show `True` when the group's ACLs have been successfully applied. + +You can also check the operator logs for details: + +[,bash] +---- +kubectl logs -l app.kubernetes.io/name=operator -c manager --namespace +---- + +== Update a group + +To update a group's ACLs, edit the Group resource configuration and apply the changes. The operator will reconcile the ACLs to match the updated specification, adding new ACLs and removing any that are no longer defined. + +[,bash] +---- +kubectl apply -f .yaml --namespace +---- + +For example, to expand permissions for a group from read-only to read-write: + +[source,yaml] +---- +spec: + authorization: + acls: + - type: allow + resource: + type: topic + name: platform- + patternType: prefixed + operations: [Read, Write, Describe] +---- + +== Delete a group + +To delete a group, delete the Group resource: + +[,bash] +---- +kubectl delete -f .yaml --namespace +---- + +When a Group resource is deleted, all ACLs managed by that resource are removed from the Redpanda cluster. The group itself continues to exist in your OIDC provider -- only the Redpanda ACLs are affected. + +== Best practices + +When working with Group resources, consider the following best practices: + +=== Group design + +- *Align with your IdP*: Structure your Group resources to mirror the group hierarchy in your OIDC provider. This makes it easier to reason about who has access to what. +- *Principle of least privilege*: Grant only the minimum permissions necessary for the group's function. Start with read-only access and expand as needed. +- *Naming conventions*: Use the same group names as your IdP to avoid confusion. Document which IdP groups map to which Redpanda permissions. + +=== Permission management + +- *Prefer group-based over user-based ACLs*: When your organization uses OIDC, manage permissions through groups rather than individual users for easier administration. +- *Use specific resource patterns*: Prefer `literal` patterns over `prefixed` patterns unless you specifically need pattern matching. +- *Combine with roles*: For complex permission models, use Group resources for direct ACLs and xref:manage:kubernetes/security/authorization/k-role-controller.adoc[RedpandaRole resources] to assign groups to roles. +- *Regular reviews*: Periodically review group permissions to ensure they remain appropriate and necessary. + +=== Integration with other resources + +- *Groups and roles*: OIDC groups can be assigned as principals in RedpandaRole resources using the `Group:` format. This allows groups to inherit role-level permissions in addition to any direct ACLs. +- *Groups and users*: Group ACLs and user ACLs are independent. A user who belongs to an OIDC group receives both the group's permissions and any individual ACLs defined through a User resource. +- *Avoid conflicts*: Be careful not to create conflicting ACLs (allow vs. deny) between Group, Role, and User resources for the same principals and resources. + +== Suggested reading + +* xref:reference:k-crd.adoc#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-group[Group resource] +* xref:manage:kubernetes/security/authentication/k-user-controller.adoc[Manage Users and ACLs] +* xref:manage:kubernetes/security/authorization/k-role-controller.adoc[Manage Roles and ACLs] +* xref:manage:security/authorization/acl.adoc[Access Control Lists (ACLs)] From 2d31391e45122001469600070389d6fc922ac332 Mon Sep 17 00:00:00 2001 From: Jake Cahill <45230295+JakeSCahill@users.noreply.github.com> Date: Tue, 31 Mar 2026 16:12:27 +0100 Subject: [PATCH 2/4] Apply suggestion from @JakeSCahill --- .../kubernetes/security/authorization/k-group-controller.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 c8a1168bc4..f3c15f7627 100644 --- a/modules/manage/pages/kubernetes/security/authorization/k-group-controller.adoc +++ b/modules/manage/pages/kubernetes/security/authorization/k-group-controller.adoc @@ -22,7 +22,7 @@ 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:deployment-option/self-hosted/kubernetes/k-production-deployment.adoc[Redpanda Operator]. +* *Redpanda Operator*: Ensure you have at least version 25.3 of the xref:deploy:redpanda/kubernetes/k-production-deployment.adoc[Redpanda Operator]. * *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. * *Redpanda v26.1+*: The cluster must be running Redpanda v26.1 or later, which supports the v2 Security API required for group principals. From e40d4a28435fa60d1c9f6451657ce68bb1864059 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Tue, 31 Mar 2026 16:26:52 +0100 Subject: [PATCH 3/4] docs: Apply docs team standards fixes to k-group-controller.adoc Applied critical fixes based on docs team standards review: - Add page metadata (topic type, learning objectives, personas) - Add learning objectives display section - Fix broken xref in Prerequisites (deploy:kubernetes path) - Add link to OIDC authentication documentation - Standardize code block formatting ([,yaml]) - Fix term usage consistency (remove redundant "resources") - Improve sentence flow in opening paragraph These changes ensure the page integrates properly with the documentation architecture and follows Redpanda style standards. Co-Authored-By: Claude Sonnet 4.5 --- .../authorization/k-group-controller.adoc | 21 ++++++++++++++----- 1 file changed, 16 insertions(+), 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 f3c15f7627..61cc5af4c0 100644 --- a/modules/manage/pages/kubernetes/security/authorization/k-group-controller.adoc +++ b/modules/manage/pages/kubernetes/security/authorization/k-group-controller.adoc @@ -2,11 +2,22 @@ :description: Use the Group resource to declaratively manage ACLs for OIDC groups as part of a Redpanda deployment. Each Group resource maps to an external OIDC group identity and manages the Kafka ACLs for that group principal. :page-categories: Management, Security :env-kubernetes: true +:page-topic-type: how-to +:learning-objective-1: Create Group resources to manage ACLs for OIDC groups +:learning-objective-2: Configure authorization rules for group principals +:learning-objective-3: Deploy and verify Group resources in Kubernetes +:personas: platform_admin, security_admin -With the Redpanda Operator, you can declaratively manage Kafka ACLs for OIDC groups using xref:reference:k-crd.adoc#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-group[Group custom resources] (resources) in Kubernetes. Each Group resource maps to an external OIDC group identity and manages the Kafka ACLs for that group's principal. The group controller, a component of the Redpanda Operator, keeps the corresponding ACLs in sync with the Group resource. +With the Redpanda Operator, you can declaratively manage Kafka ACLs for OIDC groups using xref:reference:k-crd.adoc#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-group[Group custom resources] in Kubernetes. Each Group resource maps to an external OIDC group identity and manages the Kafka ACLs for that group's principal. The group controller (a component of the Redpanda Operator) keeps ACLs in sync with the Group resource. NOTE: Groups are external identities sourced from your OIDC identity provider (IdP) via JWT token claims. Unlike xref:manage:kubernetes/security/authentication/k-user-controller.adoc[User resources], Group resources do not create entities in Redpanda -- they only manage ACLs for the `Group:` principal. +After reading this page, you will be able to: + +* [ ] {learning-objective-1} +* [ ] {learning-objective-2} +* [ ] {learning-objective-3} + == What are groups and why use them? Groups let you assign Kafka ACL permissions to OIDC identities without creating individual Redpanda users. When a user authenticates through your OIDC provider, the JWT token includes group claims. Redpanda maps those group claims to ACL principals of the form `Group:`, so any user in that OIDC group inherits the group's permissions. @@ -22,8 +33,8 @@ 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:redpanda/kubernetes/k-production-deployment.adoc[Redpanda Operator]. -* *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. +* *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 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 @@ -104,7 +115,7 @@ spec: The `spec.authorization` field allows you to manage ACLs for the group. ACLs define the permissions that all members of the OIDC group have over specific resources in Redpanda, such as topics, consumer groups, and Schema Registry subjects. -[source,yaml] +[,yaml] ---- spec: authorization: @@ -175,7 +186,7 @@ kubectl apply -f .yaml --namespace For example, to expand permissions for a group from read-only to read-write: -[source,yaml] +[,yaml] ---- spec: authorization: From 066412f7c306c612bec48c92f778a004b6dbdf03 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Tue, 31 Mar 2026 16:32:19 +0100 Subject: [PATCH 4/4] docs: Add enterprise license banner for GBAC feature Adds enterprise license requirement banner to the Group controller documentation as GBAC (Group-Based Access Control) is an enterprise feature that requires OIDC authentication. Addresses PR feedback from david-yu requesting the license banner based on the pattern established in PR #1584. Co-Authored-By: Claude Sonnet 4.5 --- .../security/authorization/k-group-controller.adoc | 7 +++++++ 1 file changed, 7 insertions(+) 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 61cc5af4c0..1c21d6cbcd 100644 --- a/modules/manage/pages/kubernetes/security/authorization/k-group-controller.adoc +++ b/modules/manage/pages/kubernetes/security/authorization/k-group-controller.adoc @@ -8,6 +8,13 @@ :learning-objective-3: Deploy and verify Group resources in Kubernetes :personas: platform_admin, security_admin +ifndef::env-cloud[] +[NOTE] +==== +include::shared:partial$enterprise-license.adoc[] +==== +endif::[] + With the Redpanda Operator, you can declaratively manage Kafka ACLs for OIDC groups using xref:reference:k-crd.adoc#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-group[Group custom resources] in Kubernetes. Each Group resource maps to an external OIDC group identity and manages the Kafka ACLs for that group's principal. The group controller (a component of the Redpanda Operator) keeps ACLs in sync with the Group resource. NOTE: Groups are external identities sourced from your OIDC identity provider (IdP) via JWT token claims. Unlike xref:manage:kubernetes/security/authentication/k-user-controller.adoc[User resources], Group resources do not create entities in Redpanda -- they only manage ACLs for the `Group:` principal.