Get up and coding with K8ssandra by exposing access to Stargate and CQL APIs!

Completion time: 10 minutes.

Important

You must complete the steps in Quick start before continuing.

In this guide, we’ll cover:

Set up port forwarding

In order to access Apache Cassandra® outside of the K8s cluster, you’ll need to utilize port forwarding unless ingress is configured.

Begin by getting a list of your K8ssandra K8s services and ports:

kubectl get services

Output:

NAME                                        TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)                                                 AGE
cass-operator-metrics                       ClusterIP   10.99.98.218     <none>        8383/TCP,8686/TCP                                       21h
k8ssandra-dc1-all-pods-service              ClusterIP   None             <none>        9042/TCP,8080/TCP,9103/TCP                              21h
k8ssandra-dc1-service                       ClusterIP   None             <none>        9042/TCP,9142/TCP,8080/TCP,9103/TCP,9160/TCP            21h
k8ssandra-dc1-stargate-service              ClusterIP   10.106.70.148    <none>        8080/TCP,8081/TCP,8082/TCP,8084/TCP,8085/TCP,9042/TCP   21h
k8ssandra-grafana                           ClusterIP   10.96.120.157    <none>        80/TCP                                                  21h
k8ssandra-kube-prometheus-operator          ClusterIP   10.97.21.175     <none>        443/TCP                                                 21h
k8ssandra-kube-prometheus-prometheus        ClusterIP   10.111.184.111   <none>        9090/TCP                                                21h
k8ssandra-reaper-k8ssandra-reaper-service   ClusterIP   10.104.46.103    <none>        8080/TCP                                                21h
k8ssandra-seed-service                      ClusterIP   None             <none>        <none>                                                  21h
kubernetes                                  ClusterIP   10.96.0.1        <none>        443/TCP                                                 21h
prometheus-operated                         ClusterIP   None             <none>        9090/TCP                                                2

In the output above, the service of interest is:

  • k8ssandra-dc1-stargate-service: The K8ssandra Stargate service where the name is a combination of the K8ssandra cluster name you specified during the Helm install, k8ssandra, the datacenter name, dc1 and the postfix, -service. This service listens on the ports:
    • 8080/TCP: GraphQL interface
    • 8081/TCP: REST authorization service for generating tokens
    • 8082/TCP: REST interface
    • 9042/TCP: CQL service

Those are the ports we’ll need to forward for CQLSH and Stargate access.

To configure port forwarding:

  1. Open a new terminal.
  2. Run the kubectl port-forward command in the background:
    kubectl port-forward svc/k8ssandra-dc1-stargate-service 8080 8081 8082 9042 &
    Output:[1] 80940 ~/ Forwarding from 127.0.0.1:8080 -> 8080 Forwarding from [::1]:8080 -> 8080 Forwarding from 127.0.0.1:8081 -> 8081 Forwarding from [::1]:8081 -> 8081 Forwarding from 127.0.0.1:8082 -> 8082 Forwarding from [::1]:8082 -> 8082

Terminate port forwarding

To terminate the port forwarding service:

  1. Get the process ID:
    jobs -l
    Output:[1] + 80940 running kubectl port-forward svc/k8ssandra-dc1-stargate-service 8080 8081 8082
  2. Kill the process
    kill 80940
    Output:[1] + terminated kubectl port-forward svc/k8ssandra-dc1-stargate-service 8080 8081 8082

Tip

Exiting the terminal instance will terminate the port forwarding service.

Access Cassandra using the Stargate APIs

Stargate provides APIs, data types and access methods that bring new capabilities to existing databases. Currently Stargate adds Document, REST and GraphQL APIs for CRUD access to data stored in Apache Cassandra® and there are many more APIs coming soon. Separating compute and storage also has benefits for maximizing resource consumption in cloud environments. When using Stargate with Cassandra, you can offload the request coordination overhead from your storage instances onto Stargate instances which has shown latency improvements in preliminary testing.

To access K8ssandra using Stargate:

  1. Generate a Stargate access token replacing <k8ssandra-username> and <k8ssandra-password> with the values you retrieved in Retrieve K8ssandra superuser credentials:
    curl -L -X POST 'http://localhost:8081/v1/auth' -H 'Content-Type: application/json' --data-raw '{"username": "<k8ssandra-username>", "password": "<k8ssandra-password>"}'
    Output:{"authToken":"<access-token>"}
  2. Use <access-token> to populate the x-cassandra-token header for all Stargate requests.

Once you’ve got the access token, take a look at the following Stargate access options:

You can access the following interfaces to make development easier as well:

For complete details on Stargate, see the Stargate documentation.

Access Cassandra using CQLSH

If you’re familiar with Cassandra, then you’re familiar with CQLSH. You can download a full-featured stand alone CQLSH utility from Datastax and use that to interact with K8ssandra as if you were in a native Cassandra environment.

To access K8ssandra using the stand alone CQLSH utility:

  1. Make sure you have Python 2.7 installed on your system.
  2. Download CQLSH from the DataStax download site choosing the version for DataStax Astra.
  3. Connect to Cassandra replacing <k8ssandra-username> and <k8ssandra-password> with the values you retrieved in Retrieve K8ssandra superuser credentials:
    cqlsh -u <k8ssandra-username> -p <k8ssandra-password>
    Output:Connected to k8ssandra at 127.0.0.1:9042. [cqlsh 6.8.0 | Cassandra 3.11.6 | CQL spec 3.4.4 | Native protocol v4] Use HELP for help. k8ssandra-superuser@cqlsh>
  4. Create a new keyspace, k8ssandra_test, using CREATE KEYSPACE:CREATE KEYSPACE k8ssandra_test WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 1};
  5. Switch to the new keyspace using USE:
    USE k8ssandra_test;
  6. Create a new table, users using CREATE TABLE
    CREATE TABLE users (email text primary key, name text, state text);
  7. Insert some sample data into the new table using INSERT
    INSERT INTO users (email, name, state) values ('[email protected]', 'Alice Smith', 'TX'); INSERT INTO users (email, name, state) values ('[email protected]', 'Bob Jones', 'VA'); INSERT INTO users (email, name, state) values ('[email protected]', 'Carol Jackson', 'CA'); INSERT INTO users (email, name, state) values ('[email protected]', 'David Yang', 'NV');
  8. Query the data using SELECT and validate the return results:cqlsh> SELECT * FROM k8ssandra_test.users;
    Output: email | name | state -------------------+---------------+------- [email protected] | Alice Smith | TX [email protected] | Bob Jones | VA [email protected] | David Yang | NV [email protected] | Carol Jackson | CA
    When you’re done, exit CQLSH using QUIT:cqlsh> QUIT;

For complete details on Cassandra, CQL and CQLSH, see the Apache Cassandra web site.

Next

With a running installation check out some of our other guides and docs.