cql-proxy is designed to forward your application's CQL traffic to an appropriate database service. It listens on a local address and securely forwards that traffic.
Warning: cql-proxy in its current state works well, and you should give it a try. However, it is still under development, so things might break or change.
Please give it a try and let us know what you think!
The cql-proxy sidecar enables unsupported CQL drivers to work with DataStax Astra. These drivers include both legacy DataStax drivers and community-maintained CQL drivers, such as the gocql driver and the rust-driver.
cql-proxy also enables applications that are currently using Apache Cassandra or DataStax Enterprise (DSE) to use Astra without requiring any code changes. Your application just needs to be configured to use the proxy.
If you're building a new application using DataStax drivers, cql-proxy is not required, as the drivers can communicate directly with Astra. DataStax drivers have excellent support for Astra out-of-the-box, and are well-documented in the driver-guide guide.
Use the -h or --help flag to display a listing all flags and their corresponding descriptions and environment variables (shown below as items starting with $):
$ ./cql-proxy -h
Usage: cql-proxy
Flags:
-h, --help Show context-sensitive help.
-b, --bundle=STRING Path to secure connect bundle ($BUNDLE)
-u, --username=STRING Username to use for authentication ($USERNAME)
-p, --password=STRING Password to use for authentication ($PASSWORD)
-c, --contact-points=CONTACT-POINTS,...
Contact points for cluster. Ignored if using the bundle path
option ($CONTACT_POINTS).
-a, --bind=STRING Address to use to bind serve ($BIND)
--debug Show debug logging ($DEBUG)
--profiling Enable profiling ($PROFILING)To pass configuration to cql-proxy, either command-line flags or environment variables can be used. Using the docker method as an example, the follwing samples show how username, password and bundle are defined with each method.
docker run -v <your-secure-connect-bundle.zip>:/tmp/scb.zip -p 9042:9042 \
--rm datastax/cql-proxy:v0.0.4 \
--bundle /tmp/scb.zip --username <astra-client-id> --password <astra-client-secret>docker run -v <your-secure-connect-bundle.zip>:/tmp/scb.zip -p 9042:9042 \
--rm datastax/cql-proxy:v0.0.4 \
-e BUNDLE=/tmp/scb.zip -e USERNAME=<astra-client-id> -e PASSWORD=<astra-client-secret>There are three methods for using cql-proxy:
- Locally build and run
cql-proxy - Run a docker image that has
cql-proxyinstalled - Use a Kubernetes container to run
cql-proxy
-
Build
cql-proxy.go build
-
Run with your desired database.
-
DataStax Astra cluster:
./cql-proxy --bundle <your-secure-connect-zip> \ --username <astra-client-id> --password <astra-client-secret>
-
Apache Cassandra cluster:
./cql-proxy --contact-points <cluster node IPs or DNS names>
-
-
Run with your desired database.
-
DataStax Astra cluster:
docker run -v <your-secure-connect-bundle.zip>:/tmp/scb.zip -p 9042:9042 \ datastax/cql-proxy:v0.0.4 \ --bundle /tmp/scb.zip --username <astra-client-id> --password <astra-client-secret>
The
<astra-client-id>and<astra-client-secret>can be generated using these instructions. -
Apache Cassandra cluster:
docker run -p 9042:9042 \ datastax/cql-proxy:v0.0.4 \ --contact-points <cluster node IPs or DNS names>
-
If you wish to have the docker image removed after you are done with it, add --rm before the image name datastax/cql-proxy:v0.0.4 .
Using Kubernetes with cql-proxy requires a number of steps:
-
Generate a token following the Astra instructions. This step will display your Client ID, Client Secret, and Token; make sure you download the information for the next steps. Store the secure bundle in
/tmp/scb.zipto match the example below. -
Create
cql-proxy.yaml. You'll need to add three sets of information: arguments, volume mounts, and volumes.
-
Argument: Modify the local bundle location, username and password, using the client ID and client secret obtained in the last step to the container argument.
command: ["./cql-proxy"] args: ["--bundle=/tmp/scb.zip","--username=Client ID","--password=Client Secret"] -
Volume mounts: Modify
/tmp/as a volume mount as required.volumeMounts: - name: my-cm-vol mountPath: /tmp/ -
Volume: Modify the
configMapfilename as required. In this example, it is namedcql-proxy-configmap. Use the same name for thevolumesthat you used for thevolumeMounts.volumes: - name: my-cm-vol configMap: name: cql-proxy-configmap
-
Create a configmap. Use the same secure bundle that was specified in the
cql-proxy.yaml.kubectl create configmap cql-proxy-configmap --from-file /tmp/scb.zip
-
Check the configmap that was created.
kubectl describe configmap config Name: config Namespace: default Labels: <none> Annotations: <none> Data ==== BinaryData ==== scb.zip: 12311 bytes
-
Create a Kubernetes deployment with the YAML file you created:
kubectl create -f cql-proxy.yaml
-
Check the logs:
kubectl logs <deployment-name>