Connect via CQL¶

Authentication setup¶

For security, always enable authentication and authorization. Create a ConfigMap with the ScyllaDB configuration before deploying your cluster:

apiVersion: v1
kind: ConfigMap
metadata:
  name: scylladb-config
data:
  scylla.yaml: |
    authenticator: PasswordAuthenticator
    authorizer: CassandraAuthorizer

Reference this ConfigMap from your ScyllaCluster via scyllaConfig on each rack:

apiVersion: scylla.scylladb.com/v1
kind: ScyllaCluster
metadata:
  name: scylladb
spec:
  datacenter:
    racks:
    - name: us-east-1a
      scyllaConfig: scylladb-config
      # ...

After deployment, follow the Creating a Custom Superuser guide in the ScyllaDB documentation to replace the default cassandra superuser with a dedicated role.

Embedded cqlsh¶

Every ScyllaDB Pod includes a built-in cqlsh. This is the simplest way to run queries:

kubectl exec -it service/<cluster-name>-client -c scylla -- cqlsh -u <user>

kubectl exec -it pod/<cluster-name>-<datacenter>-<rack>-<ordinal> -c scylla -- cqlsh -u <user>

Password:
Connected to scylla at 0.0.0.0:9042
[cqlsh 6.0.32 | Scylla 2026.1.0-0.20260309.9190d42863d4 | CQL spec 3.3.1 | Native protocol v4]
Use HELP for help.
<user>@cqlsh>

Remote cqlsh with TLS¶

ScyllaDB Operator configures TLS certificates automatically. The encrypted CQL port 9142 works by default.

kubectl -n scylla get configmap <cluster-name>-local-serving-ca \
  --template='{{ index .data "ca-bundle.crt" }}' > ca.crt
kubectl -n scylla get secret <cluster-name>-local-user-admin \
  -o jsonpath='{.data.tls\.crt}' | base64 -d > client.crt
kubectl -n scylla get secret <cluster-name>-local-user-admin \
  -o jsonpath='{.data.tls\.key}' | base64 -d > client.key

export SCYLLADB_CONFIG=/path/to/scylladb-config
mkdir -p "${SCYLLADB_CONFIG}"
cp ca.crt client.crt client.key "${SCYLLADB_CONFIG}/"
cat > "${SCYLLADB_CONFIG}/cqlshrc" <<EOF
[connection]
hostname = <cluster-name>-client.<namespace>.svc
port = 9142
ssl = true

[ssl]
certfile = ${SCYLLADB_CONFIG}/ca.crt
usercert = ${SCYLLADB_CONFIG}/client.crt
userkey = ${SCYLLADB_CONFIG}/client.key
validate = true

[authentication]
username = cassandra
password = <password>
EOF

cqlsh --cqlshrc="${SCYLLADB_CONFIG}/cqlshrc"

podman run -it --rm --entrypoint=cqlsh \
  -v="${SCYLLADB_CONFIG}:${SCYLLADB_CONFIG}:ro,Z" \
  -v="${SCYLLADB_CONFIG}/cqlshrc:/root/.cassandra/cqlshrc:ro,Z" \
  docker.io/scylladb/scylla:2026.3.3

docker run -it --rm --entrypoint=cqlsh \
  -v="${SCYLLADB_CONFIG}:${SCYLLADB_CONFIG}:ro" \
  -v="${SCYLLADB_CONFIG}/cqlshrc:/root/.cassandra/cqlshrc:ro" \
  docker.io/scylladb/scylla:2026.3.3

Driver configuration tips¶

When using a ScyllaDB or Cassandra driver in your application:

Mount TLS files in application Pods¶

Mount the serving CA bundle ConfigMap into your application Pods instead of copying it, so that they pick up a reissued serving CA. Kubernetes updates the mounted file when the ConfigMap changes.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  # ...
  template:
    spec:
      containers:
      - name: app
        image: <your-app-image>
        volumeMounts:
        - name: scylladb-serving-ca
          mountPath: /etc/scylladb/serving-ca
          readOnly: true
        - name: scylladb-client-certificate
          mountPath: /etc/scylladb/client-certificate
          readOnly: true
      volumes:
      - name: scylladb-serving-ca
        configMap:
          name: <cluster-name>-local-serving-ca
      - name: scylladb-client-certificate
        secret:
          secretName: <client-certificate-secret-name>

Configure your driver to use /etc/scylladb/serving-ca/ca-bundle.crt as the CA, and /etc/scylladb/client-certificate/tls.crt and /etc/scylladb/client-certificate/tls.key as the client certificate and key. The client certificate Secret has to hold a certificate signed by the cluster’s client CA, such as the <cluster-name>-local-user-admin Secret.

Keep in mind:

• Don’t mount the files with subPath. Kubernetes doesn’t update files mounted with subPath.

• Kubernetes updates mounted files with a delay, so new connections can fail for a short time after the serving CA is reissued.

• Your application has to read the files again when it opens new connections. If it reads them only at startup, restart it after the serving CA is reissued.

• A Pod can only mount ConfigMaps and Secrets from its own namespace. For applications in other namespaces, keep a copy of the bundle up to date instead.

Related pages¶

• Discovery endpoint — how the client Service works and how to expose it.

• Alternator (DynamoDB API) — connecting via the DynamoDB-compatible API.

• Configure external access — connecting from outside the Kubernetes cluster.

• Security — TLS certificate management.