24.1 beta 23.3 23.2 23.1

Configure Authentication for Redpanda in Kubernetes

Authentication verifies the identity of users and applications that connect to Redpanda clusters.

In the Redpanda Helm chart, all listeners are configured without authentication by default. This topic presents the supported authentication methods and describes how to configure authentication for Redpanda in Kubernetes.

The Redpanda Helm chart supports these authentication methods:

  • SASL (Simple Authentication and Security Layer): Provides a flexible and adaptable framework for implementing various authentication mechanisms, such as username and password validation through SCRAM (Salted Challenge Response Authentication Mechanism).

  • Basic authentication: Provides a method for an HTTP user agent, such as a web browser, to provide a username and password when making a request.

The APIs in Redpanda support these authentication methods:

API Supported Authentication Methods

Admin API

Basic authentication (not supported in the Helm chart)

Kafka API

SASL/SCRAM

HTTP Proxy (PandaProxy)

Basic authentication

Schema Registry

Basic authentication

Only the Kafka API supports SASL/SCRAM, which adds an extra layer of security. Unlike basic authentication, SASL/SCRAM does not require sending passwords over the network, even in an encrypted form. It uses a challenge-response mechanism, ensuring that the password is not directly accessible to the server. It works with hashed passwords, providing additional security against dictionary attacks.

Prerequisites

You must have the following:

  • Kubernetes cluster. Ensure you have a running Kubernetes cluster, either locally, such as with minikube or kind, or remotely.

  • Kubectl. Ensure you have the kubectl command-line tool installed and configured to communicate with your cluster.

Enable authentication

When authentication is enabled in the Redpanda Helm chart, clients are required to provide valid credentials to access internal and external listeners by default (except the Admin API). Enabling authentication for all listeners ensures that only authorized users can interact with your Redpanda cluster.

As the cluster administrator, you must create credentials for clients using a superuser account. Superusers are special users with all permissions on the cluster. They can grant permissions to other users of the Kafka API through access control lists (ACLs).

With authentication enabled, the Kafka API requires SASL/SCRAM authentication and the HTTP APIs require basic authentication. Both superusers and regular users can authenticate to these APIs using their respective credentials. Redpanda supports the following SASL/SCRAM authentication mechanisms for the Kafka API:

  • SCRAM-SHA-256

  • SCRAM-SHA-512

For secure authentication, use TLS encryption. TLS is enabled in the Helm chart by default.

Create superusers

Before you can create users with ACLs, you must define at least one superuser at startup. Without a superuser, you can create other users, but you can’t grant them permissions to the cluster.

To create one or more superusers, you must define a username and password. You can also set the SASL/SCRAM authentication mechanism for each superuser.

To define superusers and their credentials you can:

For default values and documentation for configuration options, see the values.yaml file.

Use a Secret resource

To use a Secret resource to store superuser credentials:

  1. Create a file in which to store the credentials.

    Make sure to include an empty line at the end of the file. 
    echo '<superuser-name>:<superuser-password>:<superuser-authentication-mechanism>' >> superusers.txt

    Replace the following placeholders with your own values for the superuser:

    • <superuser-name>: The name of the superuser.

    • <superuser-password>: The superuser’s password.

    • <superuser-authentication-mechanism>: The authentication mechanism. Valid values are SCRAM-SHA-256 or SCRAM-SHA-512.

      Or, leave this placeholder empty to set it to the default authentication mechanism. The default is SCRAM-SHA-512. This default is applied to all superusers that don’t include an explicit authentication mechanism.

  2. Use the file to create a Secret resource in the same namespace as your Redpanda cluster.

    kubectl create secret generic redpanda-superusers --namespace <namespace> --from-file=superusers.txt

  3. Enable SASL and create the superuser using your Secret:

    • Helm + Operator

    • Helm

    redpanda-cluster.yaml
    apiVersion: cluster.redpanda.com/v1alpha1
kind: Redpanda
metadata:
  name: redpanda
spec:
  chartRef: {}
  clusterSpec:
    auth:
      sasl:
        enabled: true
        secretRef: "redpanda-superusers"
        users: []
    kubectl apply -f redpanda-cluster.yaml --namespace <namespace>

    • --values

    • --set

    enable-sasl.yaml
    auth:
  sasl:
    enabled: true
    secretRef: "redpanda-superusers"
    users: []
    helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --values enable-sasl.yaml --reuse-values
    helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --set auth.sasl.enabled=true \
  --set auth.sasl.secretRef=redpanda-superusers \
  --set "auth.sasl.users=[]"

    • auth.sasl.enabled: Enable SASL authentication.

    • auth.sasl.secretRef: The name of the Secret that contains the superuser credentials. The Secret must be in the same namespace as the Redpanda cluster.

    • auth.sasl.users: Make sure that this list is empty. Otherwise, the chart will try to create a new Secret with the same name as the one set in auth.sasl.secretRef and fail because it already exists.

Use a YAML list

You can use a YAML list item to store superuser credentials in configuration settings.

Replace the following placeholders with your own values for the superuser:

  • <superuser-name>: The name of the superuser.

  • <superuser-password>: The superuser’s password.

  • <superuser-authentication-mechanism>: The authentication mechanism. Valid values are SCRAM-SHA-256 or SCRAM-SHA-512.

    If you leave this placeholder empty, the Helm chart uses the default authentication mechanism. The default is SCRAM-SHA-512. This default is applied to all superusers that don’t include an explicit authentication mechanism.

  • Helm + Operator

  • Helm

redpanda-cluster.yaml
apiVersion: cluster.redpanda.com/v1alpha1
kind: Redpanda
metadata:
  name: redpanda
spec:
  chartRef: {}
  clusterSpec:
    auth:
      sasl:
        enabled: true
        secretRef: redpanda-superusers
        users:
          - name: <superuser-name>
            password: <superuser-password>
            mechanism: <superuser-authentication-mechanism>
kubectl apply -f redpanda-cluster.yaml --namespace <namespace>

  • --values

  • --set

enable-sasl.yaml
auth:
  sasl:
    enabled: true
    secretRef: redpanda-superusers
    users:
      - name: <superuser-name>
        password: <superuser-password>
        mechanism: <superuser-authentication-mechanism>
helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --values sasl-enable.yaml --reuse-values
helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --set auth.sasl.enabled=true \
  --set auth.sasl.secretRef=redpanda-superusers \
  --set "auth.sasl.users[0].name=<superuser-name>" \
  --set "auth.sasl.users[0].password=<superuser-password>" \
  --set "auth.sasl.users[0].mechanism=<superuser-authentication-mechanism>"

  • auth.sasl.enabled: Enable SASL authentication.

  • auth.sasl.secretRef: The name of the Secret that the Redpanda Helm chart will create and use to store the user credentials listed in auth.sasl.users. This Secret must not already exist in the cluster.

  • auth.sasl.users: A list of superusers.

Edit superusers

You can add new superusers to the cluster or update existing users. For example, if you wanted to rotate credentials for superusers, you could update the username or password of an existing superuser.

You cannot delete superusers by changing the Helm values or updating the Secret.

  • If you created superusers using a Secret, you can edit the superusers.txt file and reapply the Secret resource:

    kubectl create secret generic redpanda-superusers \
  --namespace <namespace> \
  --from-file=superusers.txt \
  --save-config \
  --dry-run=client -o yaml | kubectl apply -f -

    The config-watcher sidecar in the Pod polls the Secret resource for changes and triggers a rolling upgrade to add the new superusers to the Redpanda cluster.

  • If you created superusers using a YAML list, you can update the list:

    • Helm + Operator

    • Helm

    redpanda-cluster.yaml
    apiVersion: cluster.redpanda.com/v1alpha1
kind: Redpanda
metadata:
  name: redpanda
spec:
  chartRef: {}
  clusterSpec:
    auth:
      sasl:
        enabled: true
        secretRef: redpanda-superusers
        users:
          - name: <superuser-name>
            password: <new-superuser-password>
            mechanism: <superuser-authentication-mechanism>
    kubectl apply -f redpanda-cluster.yaml --namespace <namespace>

    • --values

    • --set

    enable-sasl.yaml
    auth:
  sasl:
    enabled: true
    secretRef: redpanda-superusers
    users:
      - name: <superuser-name>
        password: <new-superuser-password>
        mechanism: <superuser-authentication-mechanism>
    helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --values sasl-enable.yaml --reuse-values
    helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --set auth.sasl.enabled=true \
  --set auth.sasl.secretRef=redpanda-superusers \
  --set "auth.sasl.users[0].name=<superuser-name>" \
  --set "auth.sasl.users[0].password=<new-superuser-password>" \
  --set "auth.sasl.users[0].mechanism=<superuser-authentication-mechanism>"

Create new users

When you have authentication enabled for your Redpanda cluster, you can create new users. By default, these users don’t have any permissions in the cluster.

As a security best practice, superusers should not run commands on the cluster. Instead, run commands as new users with specific permissions.

To create the user myuser with a password changethispassword, run rpk acl user create:

kubectl exec --namespace <namespace> -c redpanda redpanda-0 -- \
  rpk acl user create myuser -p 'changethispassword'
Enclose passwords in single quotes to avoid conflicts with special characters. Enclosing characters in single quotes preserves the literal value of each character.

Grant permissions to new users with ACLs

By default, new users don’t have any permissions in the cluster. Only superusers can grant permissions to new users through access-control lists (ACLs).

  1. Use the rpk acl create command to grant create and describe permissions to myuser in the cluster:

    kubectl exec --namespace <namespace> -c redpanda redpanda-0 -- \
  rpk acl create --allow-principal User:myuser \
  --operation create,describe \
  --cluster \
  -X user=<superuser-name> \
  -X pass='<superuser-password>' \
  -X sasl.mechanism=<superuser-authentication-mechanism>

  2. Grant the new user describe privileges for a topic called myfirsttopic:

    kubectl exec --namespace <namespace> -c redpanda redpanda-0 -- \
  rpk acl create --allow-principal User:myuser \
  --operation describe \
  --topic myfirsttopic \
  -X user=<superuser-name> \
  -X pass='<superuser-password>' \
  -X sasl.mechanism=<superuser-authentication-mechanism>
    You must grant privileges for specific topics. Even if a user has describe privileges for a cluster, it does not mean that the user is granted describe privileges for topics.

Connect to Redpanda

This section provides examples of connecting to Redpanda internally when authentication is enabled. For more details on connecting to Redpanda, see Connect to Redpanda in Kubernetes.

Connect to the Kafka API

Create a topic as the myuser user by running rpk topic create:

kubectl exec --namespace <namespace> -c redpanda redpanda-0 -- \
  rpk topic create myfirsttopic \
  -X user=myuser \
  -X pass='changethispassword' \
  -X sasl.mechanism=SCRAM-SHA-256

You can also use environment variables to set the user credentials instead of flags:

export RPK_USER=myuser
export RPK_PASS=changethispassword
export RPK_SASL_MECHANISM=SCRAM-SHA-256

To describe the topic, run rpk topic describe:

kubectl exec --namespace <namespace> -c redpanda redpanda-0 -- \
  rpk topic describe myfirsttopic \
  -X user=myuser \
  -X pass='changethispassword' \
  -X sasl.mechanism=SCRAM-SHA-256

Connect to the HTTP Proxy

By default, the Redpanda Helm chart configures an internal and external listener for the HTTP Proxy API.

To access the internal listener:

kubectl exec <pod-name> --namespace <namespace> -- curl http://redpanda-0.redpanda.redpanda.svc.cluster.local:8082/topics -u <username>:<password> -sS

If TLS is enabled, specify the HTTPS protocol and pass the path to the ca.crt file:

kubectl exec <pod-name> --namespace <namespace> -- curl https://redpanda-0.redpanda.redpanda.svc.cluster.local:8082/topics --cacert /etc/tls/certs/default/ca.crt -u <username>:<password> -sS
If the broker’s certificate is signed by a well-known, trusted CA, and you’re confident about the integrity of your system’s CA trust store, you don’t need the --cacert flag.

For all available endpoints, see HTTP Proxy API.

Connect to Schema Registry

By default, the Redpanda Helm chart configures an internal and external listener for the Schema Registry API.

To access the internal listener:

kubectl exec <pod-name> --namespace <namespace> -- curl http://redpanda-0.redpanda.redpanda.svc.cluster.local:8081/subjects -u <username>:<password> -sS

If TLS is enabled, specify the HTTPS protocol and pass the path to the ca.crt file:

kubectl exec <pod-name> --namespace <namespace> -- curl https://redpanda-0.redpanda.redpanda.svc.cluster.local:8081/subjects --cacert /etc/tls/certs/default/ca.crt -u <username>:<password> -sS
If the broker’s certificate is signed by a well-known, trusted CA, and you’re confident about the integrity of your system’s CA trust store, you don’t need the --cacert flag.

For all available endpoints, see Schema Registry API.

Disable authentication

To disable authentication for a listener, set authentication_method to none:

listeners:
  kafka:
    port: 9093
    tls:
      enabled: true
    authenticationMethod: "none"

Troubleshoot

This section lists error messages and provides ways to diagnose and solve issues. For more troubleshooting steps, see Troubleshoot Redpanda in Kubernetes.

Is SASL missing?

This error appears when you try to interact with a cluster that has SASL enabled without passing a user’s credentials.

unable to request metadata: broker closed the connection immediately after a request was issued, which happens when SASL is required but not provided: is SASL missing?

If you’re using rpk, ensure to specify the -X user, -X pass, and -X sasl.mechanism flags.

For all available flags, see the rpk command reference.

Unable to continue with update: Secret

When you use a YAML list to specify superusers, the Helm chart creates a Secret using the value of auth.sasl.secretRef as the Secret’s name, and stores those superusers in the Secret. If the Secret already exists in the namespace when you deploy Redpanda, the following error is displayed:

Error: UPGRADE FAILED: rendered manifests contain a resource that already exists. Unable to continue with update: Secret

To resolve this issue, ensure that you use only one of the following methods to create superusers:

  • auth.sasl.secretRef

  • auth.sasl.users

Next steps

Suggested reading