23.2 23.1 22.3 22.2 22.1 21.11

Configure SASL for Redpanda in Kubernetes

Simple Authentication and Security Layer (SASL) is a framework for adding authentication support to connection-based protocols. In the Redpanda Helm chart, enabling SASL provides authentication between all Redpanda brokers and clients. For example, you can give clients a username and password for authentication as well as restrict their access to the cluster through access control lists (ACLs).

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

Supported authentication mechanisms

The Redpanda Helm chart supports SASL/SCRAM (Salted Challenge Response Authentication Mechanism), also known as SCRAM.

SCRAM provides strong encryption for usernames and passwords by default and does not require an external data store for user information. Redpanda supports SCRAM-SHA-256 and SCRAM-SHA-512 authentication mechanisms.

The Redpanda Helm chart does not support Kerberos authentication.

Enable SASL

Enable SASL for the cluster and create a superuser that can grant permissions to additional users through ACLS.

To create one or more superusers, you must define the following credentials:

  • Username

  • Password

You can also set the authentication mechanism for each superuser. Or, you can set the default authentication mechanism for all superusers in the auth.sasl.mechanism configuration. This default authentication mechanism is applied to all superusers that don’t include an authentication mechanism.

You can define these credentials in Secrets or in YAML list items.

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

Use Secrets

To use a Secret to store superuser credentials, do the following:

  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.

  2. Use the file to create a Secret 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 Redpanda Helm 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.

To add new superusers to the cluster or change existing users, edit the superusers.txt file and reapply the Secret.

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

A sidecar in the Pod polls the Secret for changes and triggers a rolling upgrade to add the new superusers to the Redpanda cluster.

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

Use a YAML list

To use a YAML list item to store superuser credentials in configuration settings, do the following.

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.

  • 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.

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

Create users

When you have SASL enabled for your Redpanda cluster and you have at least one superuser, you can create new users that are not superusers. 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.

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

  • TLS Enabled

  • TLS Disabled

kubectl exec --namespace <namespace> -c redpanda redpanda-0 -- \
  rpk acl user create myuser -p 'changethispassword' \
  -X admin.tls.enabled=true \
  -X admin.tls.ca=<path-to-admin-api-ca-certificate> \
  -X admin.hosts=<broker-url>:<admin-api-port>
kubectl exec --namespace <namespace> -c redpanda redpanda-0 -- \
  rpk acl user create myuser -p 'changethispassword' \
  -X admin.hosts=<broker-url>:<admin-api-port>
Put passwords in single quotes to avoid conflicts with special characters. Enclosing characters in single quotes preserves the literal value of each character.

Grant permissions

By default, new users don’t have any permissions in the cluster. The superuser can grant permissions to new users through ACLs.

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

    • TLS Enabled

    • TLS Disabled

    kubectl exec -n redpanda -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> \
  -X tls.enabled=true \
  -X tls.ca=<path-to-ca-certificate> \
  -X brokers=<broker-urls>
    kubectl exec -n redpanda -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> \
  -X brokers=<broker-urls>
    A user must be explicitly granted describe privileges for topics. Even if a user has describe privileges for a cluster, it does not mean that the user is automatically granted describe privileges for a specific topic.

  2. Grant the new user permissions for a specific topic. The following command grants describe privileges to a topic called myfirsttopic:

    • TLS Enabled

    • TLS Disabled

    kubectl exec -n redpanda -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> \
  -X tls.enabled=true \
  -X tls.ca=<path-to-ca-certificate> \
  -X brokers=<broker-url>:<kafka-api-port>
    kubectl exec -n redpanda -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> \
  -X brokers=<broker-url>:<kafka-api-port>

Use rpk to authenticate to Redpanda using SASL

Authenticate a new user to Redpanda with the user’s credentials to start working with the cluster.

The --sasl-mechanism flag is required. This flag tells rpk the authentication method to use to authenticate the user.

To create a topic, run rpk topic create:

  • TLS Enabled

  • TLS Disabled

kubectl exec -n redpanda -c redpanda redpanda-0 -- \
  rpk topic create myfirsttopic \
  -X user=myuser \
  -X pass='changethispassword' \
  -X sasl.mechanism=SCRAM-SHA-256 \
  -X tls.enabled=true \
  -X tls.ca=<path-to-ca-certificate> \
  -X brokers=<broker-url>:<kafka-api-port>
kubectl exec -n redpanda -c redpanda redpanda-0 -- \
  rpk topic create myfirsttopic \
  -X user=myuser \
  -X pass='changethispassword' \
  -X sasl.mechanism=SCRAM-SHA-256 \
  -X brokers=<broker-url>:<kafka-api-port>

To describe the topic, run rpk topic describe:

  • TLS Enabled

  • TLS Disabled

kubectl exec -n redpanda -c redpanda redpanda-0 -- \
  rpk topic describe myfirsttopic \
  -X user=myuser \
  -X pass='changethispassword' \
  -X sasl.mechanism=SCRAM-SHA-256 \
  -X tls.enabled=true \
  -X tls.ca=<path-to-ca-certificate> \
  -X brokers=<broker-url>:<kafka-api-port>
kubectl exec -n redpanda -c redpanda redpanda-0 -- \
  rpk topic describe myfirsttopic \
  -X user=myuser \
  -X pass='changethispassword' \
  -X sasl.mechanism=SCRAM-SHA-256 \
  -X brokers=<broker-url>:<kafka-api-port>

Troubleshoot

This section lists error messages and provides ways to diagnose and solve issues.

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

Suggested reading