k-user-controller.adoc

= Manage Users with the Redpanda Operator
:description: Use the User resource to declaratively create and manage Redpanda users as part of a Redpanda deployment. Each User resource is mapped to a user in your Redpanda cluster. The user controller keeps the corresponding user in sync with the User resource.
:page-categories: Management, Development
:env-kubernetes: true

The Redpanda Operator allows you to declaratively create and manage Redpanda users using xref:reference:k-crd.adoc[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. This resource allows you to create users as part of a Redpanda deployment.

== Prerequisites

You must have the following:

* *Kubernetes cluster*: Ensure you have a running Kubernetes cluster, either locally (minikube or kind) or remotely.
* *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 the xref:deploy:deployment-option/self-hosted/kubernetes/k-production-deployment.adoc[Redpanda Operator].
* *Redpanda cluster with SASL enabled*: Ensure you have a Redpanda resource deployed with xref:manage:kubernetes/security/authentication/k-authentication.adoc#enable[SASL authentication enabled].

== User resource management

When using the Redpanda User resource, each User instance is responsible for managing both the user credentials (authentication) and the user's access control lists (ACLs) within the Redpanda cluster. You can choose to manage authentication or ACLs separately or you can manage both together.

[NOTE]
====
You cannot use one User resource to manage the user and another User resource to manage the ACLs. Only one User instance is allowed per user in the Redpanda cluster.
====

=== Manage new users (authentication only)

- *Use case*: You want to create and manage user credentials (authentication) without managing ACLs. Use this option If you have a separate process to manage ACLs or if you're working in an environment where access control is handled externally.
- *What happens when deleted*: The user is deleted, but any manually created ACLs for that user will remain in the cluster.

This example shows how to manage the creation and authentication of a user without configuring ACLs.

.`new-user.yaml`
[,yaml]
----
include::manage:example$kubernetes/user.feature[tags=manage-authn-only-manifest,indent=0]
----

=== Manage existing users (authorization only)

- *Use case*: You want to manage ACLs for an existing user in the Redpanda cluster, but not modify the user's credentials. Use this option if user credentials are managed by another process or tool, and you only want to control what resources the user can access (authorization).
- *What happens when deleted*: The ACLs are removed, but the user remains. This is useful when you want to revoke access but retain the user's credentials for future use.

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

.`new-acl.yaml`
[,yaml]
----
include::manage:example$kubernetes/user.feature[tags=manage-authz-only-manifest,indent=0]
----

=== Manage both authentication and authorization

- *Use case*: You want to manage both user credentials and ACLs within the same resource.
- *What happens when deleted*: Both the user and the associated ACLs are removed.

This example shows how to manage both authentication and ACLs for a user within the same User resource.

.`new-user-and-acl.yaml`
[source,yaml]
----
# In this example manifest, the user "full-user" is created and managed for both authentication and authorization.
# The user is granted both read and write access to the topic critical-topic.
apiVersion: cluster.redpanda.com/v1alpha2
kind: User
metadata:
  name: full-user
spec:
  cluster:
    clusterRef:
      name: sasl
  authentication:
    type: scram-sha-512
    password:
      valueFrom:
        secretKeyRef:
          name: full-user-secret
          key: password
  authorization:
    acls:
      - type: allow
        resource:
          type: topic
          name: critical-topic
          patternType: literal
        operations: [Read,Write]
----

== Configuration advice

The following sections provide guidance on setting up user authentication, managing secrets, and defining access control lists (ACLs) within your Kubernetes environment. These recommendations ensure proper user management while minimizing manual interventions and preventing potential security issues. By following these best practices, you can ensure that user access and permissions are correctly configured and maintained across your Redpanda cluster.

=== Choose an authentication type

You can specify the authentication type for a user using the `spec.authentication.type` field. Supported values include `scram-sha-256`, `scram-sha-512`, and their uppercase variants.

[source,yaml]
----
spec:
  authentication:
    type: scram-sha-512
----

If no authentication credentials are provided, no user will be created, but ACLs can still be managed for existing users.

=== Manage user secrets

Redpanda users require a password, which can be provided directly, using the `spec.password.value` field, or through a Kubernetes Secret, using the `spec.password.valueFrom.secretKeyRef`.

For example, to use a Kubernetes Secret for the password, ensure the secret exists and reference it like so:

[source,yaml]
----
spec:
  authentication:
    password:
      valueFrom:
        secretKeyRef:
          name: user-secret
          key: password
----

To create the Secret from a file:

[source,bash]
----
kubectl --namespace <namespace> create secret generic user-secret --from-file=<filepath>
----

.Example: Kubernetes Secret for User Password
[source,yaml]
----
apiVersion: v1
kind: Secret
metadata:
  name: user-secret
type: Opaque
data:
  password: cGFzc3dvcmQ=  # base64-encoded password
----

=== Define ACLs

The `spec.authorization` field allows you to manage ACLs for users. ACLs define the permissions users have over specific resources in Redpanda, such as topics, consumer groups, and clusters.

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

[source,yaml]
----
spec:
  authorization:
    acls:
      - type: allow
        resource:
          type: topic
          name: my-topic
          patternType: literal
        operations: [Read, Write]
----

- `type`: Defines whether the ACL is `allow` or `deny`.
- `resource.type`: Specifies the resource type.
- `patternType`: Specifies if the resource name is treated as a `literal` or a `prefixed` pattern.
- `operations`: Lists the allowed operations, such as `Read`, `Write`, `Create`, and `Delete`.

For more details about ACLs, including supported operations and resources in Redpanda, see xref:manage:security/authorization/acl.adoc[].

TIP: Use specific resource names where possible. Using `literal` names for resources ensures that only the exact resources you intend are accessible. Use `prefixed` patterns cautiously to avoid accidental permission grants.

== Deploy a User resource

To deploy a User 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 user

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

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

Example output:

[source,json]
----
{
  "level": "info",
  "ts": "2024-09-25T16:20:09.538Z",
  "logger": "UserReconciler.Reconcile",
  "msg": "Starting reconcile loop",
  "controller": "user",
  "User": {
    "name": "my-user",
    "namespace": "<namespace>"
  },
  "reconcileID": "c0cf9abc-a553-48b7-9b6e-2de3cdfb4432"
}
{
  "level": "info",
  "ts": "2024-09-25T16:20:09.581Z",
  "logger": "UserReconciler.Reconcile",
  "msg": "Reconciliation finished in 43.436125ms, next run in 3s",
}
----

== Update a user

To update a user, edit the User resource configuration and apply the changes.

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

== Delete a user

To delete a user, delete the User resource:

[bash]
----
kubectl delete -f example-user.yaml --namespace <namespace>
----

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

Deleting a User resource will have different impacts depending on how it is configured:

- **Authentication-only**: When a User resource managing only authentication is deleted, the user is removed from the cluster. However, any ACLs not managed by the same resource will remain in place.
- **Authorization-only**: When a User resource managing 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, the user and its associated ACLs are removed.

== Suggested reading

* xref:reference:k-crd.adoc[]
* xref:manage:kubernetes/security/authentication/k-authentication.adoc[]