CQL Proxy - datastax-archive/awesome-astra GitHub Wiki

🏠 Back to home | Written by Cedrick Lunven, Last Update 2/24/2022

📘 This content has been retrieved from Reference Documentation

📋 On this page

• A - Overview
  • What is the cql-proxy?
  • When to use cql-proxy
• B - Configuration
  • Using Flags
  • Using environment variables
• C - Getting started
  • Locally build and run
  • Run a cql-proxy docker image
  • Use Kubernetes

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.

Note: cql-proxy was made as a genrally available release on 2/16/2022. See this blog for additional details.

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-proxy installed
• Use a Kubernetes container to run cql-proxy

1. Build cql-proxy.

   go build

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

1. 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:

1. 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.zip to match the example below.

2. 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 configMap filename as required. In this example, it is named cql-proxy-configmap. Use the same name for the volumes that you used for the volumeMounts.

  volumes:
    - name: my-cm-vol
      configMap:
        name: cql-proxy-configmap        
  

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

4. Check the configmap that was created.

   kubectl describe configmap config
     
     Name:         config
     Namespace:    default
     Labels:       <none>
     Annotations:  <none>
   
     Data
     ====
   
     BinaryData
     ====
     scb.zip: 12311 bytes

5. Create a Kubernetes deployment with the YAML file you created:

   kubectl create -f cql-proxy.yaml

6. Check the logs:

   kubectl logs <deployment-name>