K8ssandra Quick Start for Developers

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

Completion time: 10 minutes.

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
    

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.
    [email protected]>
    
  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
    -------------------+---------------+-------
     alice@example.com |   Alice Smith |    TX
       bob@example.com |     Bob Jones |    VA
     david@example.com |    David Yang |    NV
     carol@example.com | Carol Jackson |    CA
    
    (4 rows)
    
  9. 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.



Last modified April 20, 2021: Typo (#695) (72c43c0)