Quickstart for developers

Completion time: 10 minutes.

In this quickstart for developers, we’ll cover:

• Setting up port forwarding to access Stargate services and CQLSH outside your Kubernetes (K8s) cluster.
• Accessing Cassandra using Stargate by creating an access token, and using Stargates’s REST, GraphQL and document interfaces.
• Accessing Cassandra using CQLSH including some basic CQL commands.

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.80.3.92     <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.80.13.197   <none>        8080/TCP,8081/TCP,8082/TCP,8084/TCP,8085/TCP,9042/TCP   21h
k8ssandra-grafana                      ClusterIP   10.80.7.168    <none>        80/TCP                                                  21h
k8ssandra-kube-prometheus-operator     ClusterIP   10.80.8.109    <none>        443/TCP                                                 21h
k8ssandra-kube-prometheus-prometheus   ClusterIP   10.80.2.44     <none>        9090/TCP                                                21h
k8ssandra-reaper-reaper-service        ClusterIP   10.80.5.77     <none>        8080/TCP                                                21h
k8ssandra-seed-service                 ClusterIP   None           <none>        <none>                                                  21h
kubernetes                             ClusterIP   10.80.0.1      <none>        443/TCP                                                 23h
prometheus-operated                    ClusterIP   None           <none>        9090/TCP                                                21h

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:

• Access Document Data API
• Access REST Data API
• Access GraphQL Data API

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

• Stargate swagger UI: http://127.0.0.1:8082/swagger-ui
• GraphQL Playground: http://127.0.0.1:8080/playground

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 steps

• FAQs: If you’re new to K8ssandra, these FAQs are for you.
• Components: Dig in to each deployed component of the K8ssandra stack and see how it communicates with the others.
• Tasks: Need to get something done? Check out the Tasks topics for a helpful collection of outcome-based solutions.
• Reference: Explore the K8ssandra configuration interface (Helm charts), the available options, and a Glossary.

We encourage developers to actively participate in the K8ssandra community.