Was this page helpful?
Caution
You're viewing documentation for an unstable version of ScyllaDB Operator. Switch to the latest stable version.
Alternator (DynamoDB API)¶
This page explains how to enable and use ScyllaDB’s Alternator, a DynamoDB-compatible API, on Kubernetes.
Enable Alternator¶
Add the alternator section to your ScyllaCluster spec:
apiVersion: scylla.scylladb.com/v1
kind: ScyllaCluster
metadata:
name: scylladb
spec:
alternator: {}
# ... rest of the spec
This enables the Alternator API with HTTPS on port 8043 and authorization enabled by default.
Configuration options¶
Field |
Description |
Default |
|---|---|---|
|
Write isolation level for Alternator operations. |
|
|
Also serve Alternator on the unencrypted HTTP port. |
|
|
Disable Alternator authorization. |
|
|
TLS certificate configuration ( |
|
Note
Unlike CQL clients, Alternator clients do not need to connect to every ScyllaDB node directly or discover individual node IP addresses. The Alternator protocol is HTTP-based, so you can also expose it through an Ingress or other HTTP networking concepts.
Obtain credentials¶
Alternator uses the CQL salted_hash from system.roles as the AWS secret access key. The access key ID is the CQL username.
Caution
The salted_hash is only available when CQL password authentication is enabled. Always configure authentication before using Alternator.
CLUSTER_NAME=scylladb
CQL_USER=cassandra
kubectl exec -it service/${CLUSTER_NAME}-client -c scylla -- cqlsh --user ${CQL_USER} \
-e "SELECT salted_hash FROM system.roles WHERE role = '${CQL_USER}'"
Connect with AWS CLI¶
Set up the environment variables and TLS CA bundle:
Step 1: Look up the Alternator endpoint
CLUSTER_NAME=scylladb
CQL_USER=cassandra
SCYLLADB_EP="$(kubectl get service/${CLUSTER_NAME}-client -o='jsonpath={.spec.clusterIP}')"
export AWS_ENDPOINT_URL_DYNAMODB="https://${SCYLLADB_EP}:8043"
Step 2: Set the access key ID
export AWS_ACCESS_KEY_ID="${CQL_USER}"
Step 3: Get the secret access key
AWS_SECRET_ACCESS_KEY="$(kubectl exec -i service/${CLUSTER_NAME}-client -c scylla -- cqlsh --user ${CQL_USER} --no-color \
-e "SELECT salted_hash from system.roles WHERE role = '${AWS_ACCESS_KEY_ID}';" \
| sed -e 's/\r//g' | sed -e '4q;d' | sed -E -e 's/^\s+//')"
export AWS_SECRET_ACCESS_KEY
Step 4: Download the TLS CA bundle
AWS_CA_BUNDLE="$(mktemp)"
export AWS_CA_BUNDLE
kubectl get configmap/${CLUSTER_NAME}-alternator-local-serving-ca \
--template='{{ index .data "ca-bundle.crt" }}' > "${AWS_CA_BUNDLE}"
Now use the aws dynamodb CLI normally:
aws dynamodb create-table \
--table-name SeaMonsters \
--attribute-definitions AttributeName=Species,AttributeType=S AttributeName=MonsterName,AttributeType=S \
--key-schema AttributeName=Species,KeyType=HASH AttributeName=MonsterName,KeyType=RANGE \
--provisioned-throughput ReadCapacityUnits=5,WriteCapacityUnits=5
aws dynamodb list-tables
TABLENAMES SeaMonsters
TLS certificate resources¶
The Operator creates these resources for Alternator:
Resource |
Name |
Contents |
|---|---|---|
Serving CA |
|
|
Troubleshoot¶
AccessDeniedException: Confirms Alternator is reachable but credentials are wrong. Re-extract credentials per the steps above and verify they match.Could not connect to the endpoint: Alternator may not be enabled on the cluster. Verifyspec.alternatoris set in the ScyllaCluster and Pods are running. Check that the Service port (8043 for HTTPS by default) is reachable.
Multi-datacenter limitations¶
When using Alternator with a multi-datacenter ScyllaDB deployment (multiple ScyllaCluster resources connected via externalSeeds), the following constraints apply:
Limitation |
Detail |
|---|---|
No built-in cross-DC routing |
Alternator endpoints are per-datacenter. There is no built-in load balancer that routes DynamoDB API requests across datacenters. Connect your application to the Alternator endpoint in the datacenter closest to it. |
Authentication tokens are DC-local |
Each |