Add docs for the Role resource in Kubernetes

modules/ROOT/nav.adoc

@@ -130,9 +130,10 @@
 **** xref:manage:kubernetes/security/tls/index.adoc[TLS Encryption]
 ***** xref:manage:kubernetes/security/tls/k-cert-manager.adoc[Use cert-manager]
 ***** xref:manage:kubernetes/security/tls/k-secrets.adoc[Use Secrets]
-**** xref:manage:kubernetes/security/authentication/index.adoc[Authentication]
+**** xref:manage:kubernetes/security/authentication/index.adoc[Authentication and Authorization]
 ***** xref:manage:kubernetes/security/authentication/k-authentication.adoc[Enable Authentication]
-***** xref:manage:kubernetes/security/authentication/k-user-controller.adoc[Manage Users and ACLs]
+***** 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/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]

modules/manage/examples/kubernetes/role-crds.feature

@@ -0,0 +1,109 @@
+@cluster:roles
+Feature: Role CRDs
+  Background: Cluster available
+    Given cluster "roles" is available
+
+  @skip:gke @skip:aks @skip:eks
+  Scenario: Manage roles
+    Given there is no role "admin-role" in cluster "roles"
+    And there are the following pre-existing users in cluster "roles"
+      | name    | password | mechanism     |
+      | alice   | password | SCRAM-SHA-256 |
+      | bob     | password | SCRAM-SHA-256 |
+    When I apply Kubernetes manifest:
+    """
+# tag::manage-roles-with-principals[]
+    # In this example manifest, a role called "admin-role" is created in a cluster called "roles".
+    # The role includes two principals (alice and bob) who will inherit the role's permissions.
+    ---
+    apiVersion: cluster.redpanda.com/v1alpha2
+    kind: Role
+    metadata:
+      name: admin-role
+    spec:
+      cluster:
+        clusterRef:
+          name: roles
+      principals:
+        - User:alice
+        - User:bob
+# end::manage-roles-with-principals[]
+    """
+    And role "admin-role" is successfully synced
+    Then role "admin-role" should exist in cluster "roles"
+    And role "admin-role" should have members "alice" and "bob" in cluster "roles"
+
+  @skip:gke @skip:aks @skip:eks
+  Scenario: Manage roles with authorization
+    Given there is no role "read-only-role" in cluster "roles"
+    And there are the following pre-existing users in cluster "roles"
+      | name    | password | mechanism     |
+      | charlie | password | SCRAM-SHA-256 |
+    When I apply Kubernetes manifest:
+    """
+# tag::manage-roles-with-authorization[]
+    # In this example manifest, a role called "read-only-role" is created in a cluster called "roles".
+    # The role includes authorization rules that allow reading from topics with names starting with "public-".
+    ---
+    apiVersion: cluster.redpanda.com/v1alpha2
+    kind: Role
+    metadata:
+      name: read-only-role
+    spec:
+      cluster:
+        clusterRef:
+          name: roles
+      principals:
+        - User:charlie
+      authorization:
+        acls:
+          - type: allow
+            resource:
+              type: topic
+              name: public-
+              patternType: prefixed
+            operations: [Read, Describe]
+# end::manage-roles-with-authorization[]
+    """
+    And role "read-only-role" is successfully synced
+    Then role "read-only-role" should exist in cluster "roles"
+    And role "read-only-role" should have ACLs for topic pattern "public-" in cluster "roles"
+    And user "charlie" should be able to read from topic "public-test" in cluster "roles"
+
+  @skip:gke @skip:aks @skip:eks
+  Scenario: Manage authorization-only roles
+    Given there are the following pre-existing users in cluster "roles"
+      | name    | password | mechanism     |
+      | travis  | password | SCRAM-SHA-256 |
+    And there is a pre-existing role "travis-role" in cluster "roles"
+    When I apply Kubernetes manifest:
+    """
+# tag::manage-authz-only-roles[]
+    # In this example manifest, a role CRD called "travis-role" manages ACLs for an existing role.
+    # The role includes authorization rules that allow reading from topics with names starting with "some-topic".
+    # This example assumes that you already have a role called "travis-role" in your cluster.
+    ---
+    apiVersion: cluster.redpanda.com/v1alpha2
+    kind: Role
+    metadata:
+      name: travis-role
+    spec:
+      cluster:
+        clusterRef:
+          name: roles
+      principals:
+        - User:travis
+      authorization:
+        acls:
+          - type: allow
+            resource:
+              type: topic
+              name: some-topic
+              patternType: prefixed
+            operations: [Read]
+# end::manage-authz-only-roles[]
+    """
+    And role "travis-role" is successfully synced
+    And I delete the CRD role "travis-role"
+    Then there should still be role "travis-role" in cluster "roles"
+    And there should be no ACLs for role "travis-role" in cluster "roles"

modules/manage/pages/kubernetes/security/authentication/index.adoc

@@ -1,6 +1,6 @@
-= Authentication for Redpanda in Kubernetes
+= Authentication and Authorization for Redpanda in Kubernetes
 :page-layout: index
-:description: Learn how to configure authentication for Redpanda in Kubernetes using Helm values or the User resource with the Redpanda Operator.
+:description: Learn how to configure authentication and authorization for Redpanda in Kubernetes using Helm values or the User resource with the Redpanda Operator.
 :page-aliases: security:sasl-kubernetes.adoc, manage:kubernetes/security/sasl-kubernetes.adoc, security:kubernetes-sasl.adoc, manage:kubernetes/security/authentication/sasl-kubernetes.adoc, reference:redpanda-operator/kubernetes-mtls.adoc, reference:redpanda-operator/kubernetes-sasl.adoc
 
-Redpanda offers two methods to manage authentication in a Kubernetes environment. These options allow administrators to control user access and permissions, ensuring secure communication with the Redpanda cluster.
+Redpanda offers two methods to manage authentication and authorization in a Kubernetes environment. These options allow administrators to control user access and permissions, ensuring secure communication with the Redpanda cluster.

modules/manage/pages/kubernetes/security/authentication/k-user-controller.adoc

@@ -5,6 +5,8 @@
 
 With the Redpanda Operator, you can declaratively create and manage Redpanda users and glossterm:ACL[,access control lists (ACLs)] using xref:reference:k-crd.adoc#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-user[User custom resources] (resources) in Kubernetes. Each User resource is mapped to a user in your Redpanda cluster. The user controller, a component of the Redpanda Operator, keeps the corresponding user in sync with the User resource.
 
+For role-based access control where you want to define permissions once and apply them to multiple users, see xref:manage:kubernetes/security/authorization/k-role-controller.adoc[Manage Roles and ACLs].
+
 == Prerequisites
 
 You must have the following:
@@ -267,8 +269,32 @@ Deleting a User resource will have different impacts depending on how it is conf
 - **Authorization-only**: When a User resource that manages only ACLs is deleted, the ACLs are removed, but the user remains in the cluster.
 - **Full user management (both authentication and authorization)**: When the resource manages both users and ACLs, the user and its associated ACLs are removed.
 
+== Best practices
+
+When working with User resources, consider the following best practices:
+
+=== User design
+
+- *Principle of least privilege*: Grant only the minimum permissions necessary for users to perform their tasks.
+- *Descriptive usernames*: Use clear, consistent naming conventions that identify the user's purpose or role.
+- *Avoid shared accounts*: Create individual user accounts rather than sharing credentials between multiple people or applications.
+
+=== Permission management
+
+- *Consider roles for shared permissions*: When multiple users need the same set of permissions, consider using xref:manage:kubernetes/security/authorization/k-role-controller.adoc[Role resources] instead of duplicating ACLs across individual User resources.
+- *User-specific permissions*: Use User resource ACLs for permissions that are specific to individual users and don't need to be shared.
+- *Avoid conflicts*: If using both Role and User resources, be careful not to create conflicting ACLs for the same users.
+
+=== Secret management
+
+- *Use Kubernetes Secrets*: Store passwords in Kubernetes Secrets rather than hardcoding them in manifests.
+- *Regular rotation*: Implement a regular password rotation strategy for production environments.
+
 == Suggested reading
 
 * xref:reference:k-crd.adoc#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-user[User resource]
 * xref:reference:k-crd.adoc#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-userlist[UserList resource]
-* xref:manage:kubernetes/security/authentication/k-authentication.adoc[]
+* xref:manage:kubernetes/security/authorization/k-role-controller.adoc[Manage Roles and ACLs]
+* xref:manage:kubernetes/security/authentication/k-authentication.adoc[]
+* xref:manage:security/authorization/rbac.adoc[Role-Based Access Control (RBAC)]
+* xref:manage:security/authorization/acl.adoc[Access Control Lists (ACLs)]