# Manage Roles with the Redpanda Operator

> For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [streaming-full.txt](https://docs.redpanda.com/streaming-full.txt)

---
title: Manage Roles with the Redpanda Operator
latest-redpanda-tag: v26.1.9
latest-console-tag: v3.7.3
latest-operator-version: v26.1.4
# EOL = End-of-Life (support lifecycle status)
page-is-nearing-eol: "false"
page-is-past-eol: "false"
page-eol-date: March 31, 2027
latest-connect-version: 4.93.0
docname: kubernetes/security/authorization/k-role-controller
page-component-name: streaming
page-version: "26.1"
page-component-version: "26.1"
page-component-title: Streaming
page-relative-src-path: kubernetes/security/authorization/k-role-controller.adoc
page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/manage/pages/kubernetes/security/authorization/k-role-controller.adoc
description: Use the RedpandaRole resource to declaratively create and manage roles as part of a Redpanda deployment. Each RedpandaRole resource defines a set of permissions that can be assigned to multiple users, providing role-based access control (RBAC) for your Redpanda cluster.
page-git-created-date: "2025-12-04"
page-git-modified-date: "2025-12-04"
support-status: supported
---

<!-- Source: https://docs.redpanda.com/streaming/current/manage/kubernetes/security/authorization/k-role-controller.md -->

With the Redpanda Operator, you can declaratively create and manage Redpanda roles using [RedpandaRole custom resources](https://docs.redpanda.com/streaming/current/reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-role) (resources) in Kubernetes. Each RedpandaRole resource defines a set of permissions that can be assigned to multiple users, providing role-based access control (RBAC) for your Redpanda cluster. The role controller, a component of the Redpanda Operator, keeps the corresponding Redpanda role in sync with the RedpandaRole resource.

> 📝 **NOTE**
>
> RedpandaRole resources do not create users. Users must already exist in the Redpanda cluster before they can be assigned to roles, unless they are OIDC principals. OIDC principals do not need to be created as users in the cluster. Use [User resources](https://docs.redpanda.com/streaming/current/manage/kubernetes/security/authentication/k-user-controller/) to create and manage Redpanda users.

## [](#what-are-roles-and-why-use-them)What are roles and why use them?

Think of roles like job titles in a company. Instead of giving each employee individual permissions for every door, system, and resource, you create job titles (roles) like "Developer," "Manager," or "Security Guard." Each job title comes with a specific set of permissions, and you assign employees to those job titles.

In Redpanda, roles work the same way:

-   **Without roles**: You set up permissions individually for each user. If you have 10 developers who all need the same access to certain topics, you configure the same permissions 10 times.

-   **With roles**: You create a "Developer" role once with all the necessary permissions, then assign all 10 developers to that role. When you need to change what developers can access, you update the role once instead of updating 10 individual users.


## [](#prerequisites)Prerequisites

You must have the following:

-   **Kubectl**: Ensure you have the [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) command-line tool installed and configured to communicate with your cluster.

-   **Redpanda Operator**: Ensure you have at least version 25.2 of the [Redpanda Operator](https://docs.redpanda.com/streaming/current/deploy/redpanda/kubernetes/k-production-deployment/).

-   **Redpanda cluster with SASL enabled**: Ensure you have a Redpanda resource deployed with [SASL authentication enabled](https://docs.redpanda.com/streaming/current/manage/kubernetes/security/authentication/k-authentication/#enable).

-   **Existing users**: If you plan to assign users to roles, ensure the users already exist in your Redpanda cluster. You can create users using [User resources](https://docs.redpanda.com/streaming/current/manage/kubernetes/security/authentication/k-user-controller/).


## [](#create-a-role)Create a role

You can use the RedpandaRole resource to:

-   [Create a role with authorization rules (ACLs)](#with-authorization)

-   [Create a role with principals (users)](#with-principals)

-   [Create authorization rules for an existing role](#authorization-only)


Each Role instance is responsible for managing both the role membership (principals) and the role’s ACLs within the Redpanda cluster. You cannot use one RedpandaRole resource to manage the principals and another resource to manage the ACLs. Only one Role instance is allowed per role in the Redpanda cluster.

### [](#with-authorization)Create a role with authorization rules

-   **Use case**: You want to create a role that defines permissions and assign users to inherit those permissions. This is the most common use case for role-based access control, where you define permissions once and apply them to multiple users.

-   **What happens when deleted**: Both the role and its associated ACLs are removed. Users assigned to the role lose the permissions granted by this role but retain any other permissions they have.


This example shows how to create a role with both principals and authorization rules.

`read-only-role.yaml`

```yaml
---
apiVersion: cluster.redpanda.com/v1alpha2
kind: RedpandaRole
metadata:
  name: read-only-role
spec:
  cluster:
    clusterRef:
      name: sasl
  principals:
    - User:charlie
  authorization:
    acls:
      - type: allow
        resource:
          type: topic
          name: public-
          patternType: prefixed
        operations: [Read, Describe]
      - type: allow
        resource:
          type: subject
          name: public-
          patternType: prefixed
        operations: [Read, Describe]
```

### [](#with-principals)Create a role with principals

-   **Use case**: You want to create a role and assign users (principals) to it. This is useful for grouping users together without necessarily defining permissions at the role level, allowing you to manage group membership centrally.

-   **What happens when deleted**: The role is deleted, but users assigned to the role remain in the cluster. Any ACLs defined at the user level are unaffected.


This example shows how to create a role and assign principals to it.

`admin-role.yaml`

```yaml
# In this example manifest, a role called "admin-role" is created in a cluster called "sasl".
# The role includes two principals (alice and bob) who will inherit the role's permissions.
---
apiVersion: cluster.redpanda.com/v1alpha2
kind: RedpandaRole
metadata:
  name: admin-role
spec:
  cluster:
    clusterRef:
      name: sasl
  principals:
    - User:alice
    - User:bob
```

### [](#authorization-only)Create authorization rules for an existing role

-   **Use case**: You want to manage ACLs for an existing role in the Redpanda cluster, but not modify the role’s membership. Use this option if role membership is managed by another process or tool, and you only want to control what resources the role can access.

-   **What happens when deleted**: The ACLs are removed, but the role and its members remain. This is useful when you want to revoke permissions but retain the role structure for future use.


This example shows how to manage only the ACLs for an existing role in the Redpanda cluster.

`authorization-only-role.yaml`

```yaml
# 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.
# Note: When the CRD is deleted, the operator will remove both the role and ACLs since it takes full ownership.
---
apiVersion: cluster.redpanda.com/v1alpha2
kind: RedpandaRole
metadata:
  name: travis-role
spec:
  cluster:
    clusterRef:
      name: sasl
  principals:
    - User:travis
  authorization:
    acls:
      - type: allow
        resource:
          type: topic
          name: some-topic
          patternType: prefixed
        operations: [Read]
```

## [](#configuration)Configuration

The following sections provide guidance on setting up role membership, managing authorization rules, and defining ACLs within your Kubernetes environment. These recommendations ensure proper role management while minimizing manual interventions and preventing potential security issues.

You can find all configuration options for the RedpandaRedpandaRole resource in the [CRD reference](https://docs.redpanda.com/streaming/current/reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-role).

### [](#choose-a-role-name)Choose a role name

The `metadata.name` field in the RedpandaRedpandaRole resource is used to specify the role name. Keep in mind the following best practices when choosing a role name:

-   **Unique**: Ensure each role has a unique name to avoid conflicts. The role name must be unique within the Redpanda cluster.

-   **Descriptive**: Choose a name that identifies the purpose or permissions of the role. For example, use names like `data-readers` or `topic-admins`.

-   **Stable**: Avoid changing role names frequently. Role names are tied to authorization rules (ACLs) and user assignments. Renaming a role involves deleting and recreating the role.


```yaml
metadata:
  name: read-only-role
```

In this example, `read-only-role` is the role name, which will be referenced in authorization rules and user assignments.

### [](#configure-principals)Configure principals

The [`spec.principals`](https://docs.redpanda.com/streaming/current/reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-rolespec) field allows you to specify which users are assigned to the role. Principals are specified in the format `User:<username>`.

> ❗ **IMPORTANT**
>
> Users must already exist in the Redpanda cluster before they can be assigned to a role. The RedpandaRole resource does not create users that don’t exist.

```yaml
spec:
  principals:
    - User:alice
    - User:bob
```

When users are assigned to a role, they inherit all the permissions defined in the role’s ACLs. If a role has no ACLs defined, the users gain no additional permissions from the role membership.

### [](#define-authorization-rules)Define authorization rules

The [`spec.authorization`](https://docs.redpanda.com/streaming/current/reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-roleauthorizationspec) field allows you to manage ACLs for the role. ACLs define the permissions that all members of the role have over specific resources in Redpanda, such as topics, consumer groups, and clusters.

You can define ACLs for a role by specifying which resources members can access and the operations they are permitted to perform. Here’s an example configuration for managing ACLs:

```yaml
spec:
  authorization:
    acls:
      - type: allow
        resource:
          type: topic
          name: public-
          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`.

-   `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`, and `Delete`.


You can find all configuration options for authorization in the [RoleAuthorizationSpec](https://docs.redpanda.com/streaming/current/reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-roleauthorizationspec) of the CRD reference.

For more details about ACLs, including supported operations and resources in Redpanda, see [Configure Access Control Lists](https://docs.redpanda.com/streaming/current/manage/security/authorization/acl/).

## [](#deploy-a-redpandarole-resource)Deploy a RedpandaRole resource

To deploy a RedpandaRole resource, apply the manifest to the same namespace as your Redpanda cluster:

```bash
kubectl apply -f <manifest-filename>.yaml --namespace <namespace>
```

-   Replace `<manifest-filename>` with the filename of your manifest.

-   Replace `<namespace>` with the namespace in which you deployed Redpanda.


## [](#verify-a-role)Verify a role

After deploying a RedpandaRole resource, verify that the Redpanda Operator reconciled it:

```bash
kubectl logs -l app.kubernetes.io/name=operator -c manager --namespace <namespace>
```

## [](#update-a-role)Update a role

To update a role, edit the RedpandaRole resource configuration and apply the changes.

```bash
kubectl apply -f <manifest-filename>.yaml --namespace <namespace>
```

## [](#delete-a-role)Delete a role

To delete a role, delete the RedpandaRole resource:

```bash
kubectl delete -f <manifest-filename>.yaml --namespace <namespace>
```

When a RedpandaRole resource is deleted, its underlying data is removed as well. If the role has ACLs, those ACLs are also removed.

Deleting a RedpandaRole resource has different impacts depending on how it is configured:

-   **Principals-only**: When a RedpandaRole resource that manages only principals is deleted, the role is removed from the cluster. However, any ACLs not managed by the same resource will remain in place.

-   **Authorization-only**: When a RedpandaRole resource that manages only ACLs is deleted, the ACLs are removed, but the role and its members remain in the cluster.

-   **Full role management (both principals and authorization)**: When the resource manages both membership and ACLs, the role and its associated ACLs are removed.


## [](#best-practices)Best practices

When working with RedpandaRole resources, consider the following best practices:

### [](#role-design)Role design

-   **Principle of least privilege**: Grant only the minimum permissions necessary for users to perform their tasks.

-   **Logical grouping**: Create roles that align with job functions or responsibilities rather than individual users.

-   **Naming conventions**: Use consistent, descriptive names that indicate the role’s purpose, such as `topic-readers` or `admin-users`.


### [](#permission-management)Permission management

-   **Prefer role-based over user-based ACLs**: When possible, assign permissions to roles rather than individual users to simplify management.

-   **Use specific resource patterns**: Prefer `literal` patterns over `prefixed` patterns unless you specifically need pattern matching.

-   **Regular reviews**: Periodically review role permissions to ensure they remain appropriate and necessary.


### [](#integration-with-user-resources)Integration with User resources

-   **Consistent management**: If you’re using both Role and User resources, establish clear guidelines about which permissions are managed at the role level versus the user level.

-   **Avoid conflicts**: Be careful not to create conflicting ACLs between Role and User resources for the same users.


## [](#suggested-reading)Suggested reading

-   [RedpandaRole resource](https://docs.redpanda.com/streaming/current/reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-role)

-   [RoleList resource](https://docs.redpanda.com/streaming/current/reference/k-crd/#k8s-api-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-rolelist)

-   [Manage Users and ACLs](https://docs.redpanda.com/streaming/current/manage/kubernetes/security/authentication/k-user-controller/)

-   [Role-Based Access Control (RBAC)](https://docs.redpanda.com/streaming/current/manage/security/authorization/rbac/)

-   [Access Control Lists (ACLs)](https://docs.redpanda.com/streaming/current/manage/security/authorization/acl/)


## Suggested labs

-   [Enable Unified Identity with Azure Entra ID for Redpanda and Redpanda Console](https://docs.redpanda.com/labs/docker-compose/oidc/)
-   [Migrate Data with Redpanda Migrator](https://docs.redpanda.com/labs/docker-compose/redpanda-migrator/)

[Search all labs](https://docs.redpanda.com/labs)