Access Cassandra Via Stargate APIs

Stargate runs as a Docker image within a pod that we install using a deployment. As is customary in Kubernetes, we place a service in front of the deployment. The service listens on three ports (8080, 8081 and 8082) for requests for the Stargate interfaces (GraphQL, Auth and REST respectively).

In this module’s example configuration, we have an ingress installed on port 80. The ingress inspects the URL paths and routes the requests to the appropriate service port.

The service forwards requests to the corresponding port of the pod. One of the benefits of using the service is that if the pod dies and must be restarted, the interface for the ingress does not change.

The deployment monitors the pod to keep the pod running. Another possible benefit of the deployment is that, if we need to scale up Stargate, we can do so merely by increasing the number of replicas in the deployment.

The Stargate auth interface allows you to supply the Cassandra credentials, one time, in exchange for an auth token. When the Cassandra Operator creates a Cassandra cluster, the operator stores the Cassandra credentials in a Kubernetes secret. To get the auth token from the Stargate auth interface, a client can retrieve the credentials from the secret and supply them as part of the request. In response to this request, the auth interface provides an auth token. Clients can then use the auth token to access the other Stargate APIs such as REST or GraphQL.

In this module’s configuration, the ingress determines an auth request by identifying the URL path starting with /v1/auth. When the ingress sees this path, the ingress forwards the request to port 8081 on the Stargate service. The service uses the same path to access port 8081 on the Stargate pod. The pod, in turn, verifies the credentials with the Cassandra cluster and then creates the auth token, which is ultimately returned to the client.

The REST API provides REST access to a Cassandra table using information embedded in the REST URL endpoint. The REST endpoint path must start with /v2/keyspaces. This base path causes the ingress to forward the request to the Stargate service on port 8082. The remainder of the URL encodes the keyspace name, the table name, and the search criteria (such as the primary key value).

The Stargate service forwards this entire URL to the pod. The pod then decodes the URL and formualtes a Cassandra query, and returns the results back to the client.

Note that the client embeds the auth token in the HTTP headers of the request.

Like the REST API, the GraphQL API provides GraphQL access to a Cassandra table. The big difference between REST and GraphQL is that, with REST, the client receives all the table columns back. But, with GraphQL, the client can specify how much data the API will return. This can optimize API traffic.

Similar to how the REST API works, the ingress inspects the request URL for a base path of /graphql. Upon identifying this path, the ingress forwards the request to port 8080 on the Stargate service. In turn, the service forwards the request to the pod on port 8080.

Unlike REST requests, GraphQL requests embed only the keyspace name in the URL. The remainder of the request uses a JSON format within the body of the request. As previously mentioned, this request body not only specifies the table name and search criteria, but also includes a specification of the desired output.

The pod parses this information and formulates a query to the Cassandra table. The pod then returns the results of the query to the client.

Similar to the REST API requests, GraphQL clients embed the auth token in the HTTP headers of the request.

The GraphQL Playground UI is an interactive GraphQL client that you can run in a browser. The Playground understands GraphQL and helps users formulate queries by supplying command hints. Using the Playground, users can formulate GraphQL queries, submit the queries to the GraphQL API, and view the results.

Users configure the Playground to talk to the Stargate GraphQL API by supplying the Playground with the GraphQL URL and the auth token.

The web-server for the Playground has a URL base path of /playground. So, when the ingress fields HTTP requests with this base path, the ingress forwards these requests to the Stargate service on port 8080. The service forwards the request on to the pod, also using port 8080. The pod contains a web-server that services the Playground app.