Quickstart for developers

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. Begin by getting a list of your K8ssandra K8s services and ports:

kubectl get services

The service of interest is:

• demo-dc1-stargate-service: The K8ssandra Stargate service where the name is a combination of the k8ssandra cluster name you specified during the Helm install, such as demo, 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/demo-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:

   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

• 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 Custom Resource Definitions (CRDs) used by K8ssandra Operator.

We encourage developers to actively participate in the K8ssandra community.