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:
-
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 areSCRAM-SHA-256
orSCRAM-SHA-512
.
-
-
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
-
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 inauth.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 areSCRAM-SHA-256
orSCRAM-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 inauth.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.
-
Use the
rpk acl create
command to grantcreate
anddescribe
permissions tomyuser
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 hasdescribe
privileges for a cluster, it does not mean that the user is automatically granteddescribe
privileges for a specific topic. -
-
Grant the new user permissions for a specific topic. The following command grants
describe
privileges to a topic calledmyfirsttopic
:-
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