Dec 22, 2022

6 min read

Deploying Stargate API using Helm

In this blog, you will learn how to deploy Stargate data API gateway for Apache Cassandra® in a Kubernetes environment using Helm charts, turning Cassandra into an API-accessible cloud service.

Stargate

Since its inception in 2020, Stargate.io has helped companies like Netflix, Yelp, Netlify, PrepLadder, SHIELD, and more, who take advantage of the power of the open source NoSQL database, Apache Cassandra®, to make their data more accessible through APIs.

Stargate turns Apache Cassandra into a cloud data service. You can connect applications, services, and functions to Cassandra over HTTP APIs and Drivers, injecting limitless scale and speed for the data plane. In addition to supporting Cassandra’s traditional CQL interface, you can go driverless with Stargate v2’s high-performance gRPC implementation! It’s just as fast as native database drivers, and with so much of the networking configuration done by gRPC automatically, it is much easier to use (and learn). Other options include REST, GraphQL, and a JSON/REST Document API, allowing Cassandra to function as a document database.

Stargate has now come up with Helm-based configuration to get it deployed in a Kubernetes environment (which has a Cassandra cluster already running).

The need for Helm based deployment

Stargate runs as a multilayer architecture so that individual services can be scaled based on the workload. Helm-based deployment helps in deploying and managing these kinds of applications easily.

Environment setup

For this demo, I’m going to use three node Kubernetes cluster with each node having 8 CPU and 8GB memory.

$ kubectl get nodes
NAME                                       STATUS   ROLES    AGE    VERSION
gke-cluster-1-default-pool-xxa2e8bd-xxxx   Ready    <none>   4d2h   v1.23.12-gke.100
gke-cluster-1-default-pool-xxa2e8bd-xxxx   Ready    <none>   4d2h   v1.23.12-gke.100
gke-cluster-1-default-pool-xxa2e8bd-xxxx   Ready    <none>   4d2h   v1.23.12-gke.100

Installing Helm

Helm needs to be installed, which will be used for deploying all the components. Helm installation instructions can be found here.

Installing Cassandra

To demonstrate Stargate deployment, we need a running Cassandra cluster. For this demo, I will have a single-node Cassandra instance deployed via Bitnami. Stargate connects to Cassandra’s storage port, generally running on port 7000, which needs to be exposed as a headless service.

$ helm install my-release bitnami/cassandra --set image.tag=4.0.7 --set persistence.enabled=false
$ kubectl get pod,svc
NAME                         READY   STATUS    RESTARTS   AGE
pod/my-release-cassandra-0   1/1     Running   0          8m10s

NAME                                    TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)                               AGE
service/kubernetes                      ClusterIP   10.8.0.1     <none>        443/TCP                               30d
service/my-release-cassandra            ClusterIP   10.8.1.170   <none>        9042/TCP,8080/TCP                     3d4h
service/my-release-cassandra-headless   ClusterIP   None         <none>        7000/TCP,7001/TCP,7199/TCP,9042/TCP   3d4hInstalling Ingress Controller

Installing Ingress Controller

To expose access to Stargate APIs from clients outside your Kubernetes cluster, make sure an ingress controller is installed. To install the Nginx ingress controller, execute the command:

$  helm upgrade --install ingress-nginx ingress-nginx \
   --repo https://kubernetes.github.io/ingress-nginx \
   --namespace ingress-nginx --create-namespace

Set the ingress class name to ingress.ingressClassName in the Stargate Helm chart values.yaml. When using ingress, the API service paths need to be set as specified below.

Default paths when using ingress by Stargate API:

Auth-api: http://localhost/api/auth/v1/auth
Rest-api: http://localhost/api/rest/v2/schemas/keyspaces
Docs-api: http://localhost/api/docs/v2/namespaces/test/collections/library
Graphql-api: http://localhost/api/graphql/graphql-schema

Installing Metrics Server for Autoscaling

Stargate’s auto scaling feature uses Kubernetes HPA (Horizontal Pod Autoscaling). HPA needs a metrics server installed. Metrics server can be installed by executing the command:

$ kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yamlStargate deployment

Stargate comes with a coordinator service which will join a running Cassandra cluster, but will not store data. This service can act as Cassandra query coordinator. This service also hosts CQL interface and authentication API. There are three API services (REST, Document, and GraphQL) available that can be deployed depending on the requirement. Now that we have Cassandra running, let’s go ahead and deploy Stargate with two pods for each service.

Helm configuration for Stargate is available in the Stargate Github repo. Follow these steps to get Stargate deployed:

Clone the Stargate repo from Github.

$ git clone -b main https://github.com/stargate/stargate.git
Cloning into 'stargate'...
remote: Enumerating objects: 56232, done.
remote: Counting objects: 100% (823/823), done.
remote: Compressing objects: 100% (515/515), done.
remote: Total 56232 (delta 323), reused 622 (delta 192), pack-reused 55409
Receiving objects: 100% (56232/56232), 13.91 MiB | 22.68 MiB/s, done.
Resolving deltas: 100% (23439/23439), done.

2. Change directory to Helm folder.

$ cd stargate/helm/

3. Helm configuration is provided in values.yaml. Details of each of the configurations are provided in a table here.

3a. Default Cassandra cluster information is updated in values.yaml, which will work if Cassandra is installed as explained here. Cassandra cluster information can be changed in values.yaml in this section.

cassandra:
clusterName: “cassandra”
dcName: “datacenter1”
rack: “rack1”
seed: “my-release-cassandra-headless.default.svc.cluster.local”
isDse: null
clusterVersion: “4.0”
enableCqlAuth: true

3b. In this section of values.yaml, any API service deployment can be disabled/enabled. You can also control things like their number of replicas, and the pod’s cpu / memory in this section of values.yaml.

restapi:
image:
repository: “stargateio/restapi”
enabled: true
replicaCount: 1
cpu: 2000
memory: 2048
docsapi:
image:
repository: “stargateio/docsapi”
enabled: true
replicaCount: 1
cpu: 2000
memory: 2048
graphqlapi:
image:
repository: “stargateio/graphqlapi”
enabled: true
replicaCount: 1
cpu: 2000
memory: 2048

3c. For this installation, I have enabled the ingress deployment in the section below.

ingress:
enabled: true
ingressClassName: nginx

3d. For this installation, I have not enabled auto scaling. A CPU based auto scaling can be deployed by changing the flag in the below section.

autoscaling:
enabled: false
minReplicas: 1
maxReplicas: 100
targetCPUUtilizationPercentage: 80

4. Deploy Stargate using Helm.

$ helm install stargate stargate
NAME: stargate
LAST DEPLOYED: Thu Dec  8 20:10:13 2022
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None

5. First coordinator service will start and join the Cassandra cluster. Other API services will wait until coordinator service is up and running.

$ kubectl get pod
NAME                                        READY   STATUS     RESTARTS   AGE
pod/my-release-cassandra-0                  1/1     Running    0          11m
pod/stargate-coordinator-5cf79d4bd7-nmqbk   0/1     Running    0          11s
pod/stargate-docsapi-66c8659744-gd27z       0/1     Init:0/1   0          11s
pod/stargate-graphqlapi-6949665fd9-dcg56    0/1     Init:0/1   0          11s
pod/stargate-restapi-7f958f6895-jrxsr       0/1     Init:0/1   0          11s

6. Once the coordinator service is in running state, all other API services start up. Ingress configurations are also deployed for different API services.

$ kubectl get pod,svc
NAME                                        READY   STATUS    RESTARTS   AGE
pod/my-release-cassandra-0                  1/1     Running   0          13m
pod/stargate-coordinator-5cf79d4bd7-nmqbk   1/1     Running   0          5m13s
pod/stargate-docsapi-66c8659744-gd27z       1/1     Running   0          5m13s
pod/stargate-graphqlapi-6949665fd9-dcg56    1/1     Running   0          5m13s
pod/stargate-restapi-7f958f6895-jrxsr       1/1     Running   0          5m13s

NAME                                    TYPE        CLUSTER-IP    EXTERNAL-IP   PORT(S)                               AGE
service/kubernetes                      ClusterIP   10.8.0.1      <none>        443/TCP                               30d
service/my-release-cassandra            ClusterIP   10.8.1.170    <none>        9042/TCP,8080/TCP                     3d5h
service/my-release-cassandra-headless   ClusterIP   None          <none>        7000/TCP,7001/TCP,7199/TCP,9042/TCP   3d5h
service/stargate-auth                   ClusterIP   10.8.12.225   <none>        8081/TCP                              5m13s
service/stargate-bridge                 ClusterIP   10.8.10.195   <none>        8091/TCP                              5m13s
service/stargate-cql                    ClusterIP   10.8.0.70     <none>        9042/TCP                              5m13s
service/stargate-docsapi                ClusterIP   10.8.0.205    <none>        8180/TCP                              5m13s
service/stargate-graphqlapi             ClusterIP   10.8.0.251    <none>        8080/TCP                              5m13s
service/stargate-grpc                   ClusterIP   10.8.3.154    <none>        8090/TCP                              5m13s
service/stargate-restapi                ClusterIP   10.8.6.96     <none>        8082/TCP       


$ kubectl get ingress -A
NAMESPACE   NAME                          CLASS   HOSTS   ADDRESS         PORTS   AGE
default     stargate-auth-ingress         nginx   *       35.XX.XX.48   80      104s
default     stargate-docsapi-ingress      nginx   *       35.XX.XX.48   80      104s
default     stargate-graphqlapi-ingress   nginx   *       35.XX.XX.48   80      104s
default     stargate-grpc-ingress         nginx   *       35.XX.XX.48   80      105s
default     stargate-restapi-ingress      nginx   *       35.XX.XX.48   80      104s

Testing the deployment

Refer to official Stargate user documentation for different API usage.

Get authentication token based on Cassandra credentials.

curl -L -X POST ‘http://localhost/api/auth/v1/auth' \
 -H ‘Content-Type: application/json’ \
 — data-raw ‘{
 “username”: “cassandra”,
 “password”: “XXXXX”
}’
{“authToken”:”23e63c16–7af3–4029–8a17–1c61ce86297b”}XX

Export the authentication token.

export AUTH_TOKEN=23e63c16–7af3–4029–8a17–1c61ce86297b

Run REST API service call.

curl -s — location — request POST ‘http://localhost/api/rest/v2/schemas/keyspaces' \
 — header “X-Cassandra-Token: $AUTH_TOKEN” \
 — header ‘Content-Type: application/json’ \
 — data ‘{
 “name”: “users_keyspace”
}’
{“name”:”users_keyspace”}

Conclusion

Great, you’re off and running now with Stargate on Kubernetes, alongside your existing Cassandra cluster! If you’re just looking to learn Cassandra, or play around off-Kubernetes, DataStax Astra DB offers a serverless, auto-scaling DBaaS built on Cassandra, which is easy to deploy and use. Astra DB has Stargate built in to support different APIs like REST, GraphQL, gRPC, and even a JSON Document API. If you want to try a quick hand on Stargate APIs, try creating a database in Astra DB.