Back in September, we announced the availability of the Stargate v2 Beta release. After several betas and a release candidate, we’re excited to announce the availability of the general release of Stargate v2!

As we’ve discussed in previous posts, v2 represents an architectural refactoring that allows more flexible deployments and makes it easier to create new APIs.

The GA release includes the results of community feedback as well as learnings from the DataStax team on integrating Stargate v2 into DataStax AstraDB, which have served to inject a high level of confidence in the quality of this release.

Quickstart for v2

If you want to try out the v2 release, we have everything set to go for you. In the Beta release blog, we provided instructions on how to quickly deploy Stargate v2 on your desktop using Docker compose, and then use Postman collections to exercise the APIs.

We also recommend checking out Pieter Humphrey’s blog post for a more in-depth introduction to these collections and how to use them.

Migrating to v2

If you’re currently using Stargate v1 and are ready to upgrade to v2, the process is straightforward. For users that are only using gRPC and CQL APIs, you only need to update your configuration to run the v2 version of the coordinator. Restarting nodes in your backing Cassandra cluster is not required, and you can use a rolling restart approach to update coordinator nodes and your clients for a zero-downtime update.

In addition, if you’re using Stargate HTTP APIs such as REST, GraphQL or Docs API, you will need to run instances of each API service you need. These APIs are packaged as separate containers from the v2 coordinator node.

We recommend running at least two instances of each API service you use to ensure high availability, as shown in the figure. The good news is that this will not consume a large amount of additional resources, since all three API services use the Quarkus framework to create lightweight container images based on JDK 17. For more detail see Ivan Senic’s recent interview on the Quarkus Insights podcast.

Images for the coordinator and API services are available on Docker Hub, and we’ve also made sample Docker compose configurations available in the Stargate GitHub repository.

In order to complete a migration of your HTTP clients to the new APIs, you’ll want to repoint your clients to the new API endpoints. If you’ve deployed a load balancer in front of the Stargate HTTP APIs in v1 deployments, this will be a trivial change requiring no downtime.

• All of the default port numbers are the same, with the exception of the Documents API.
• Paths for APIs move to the new services, including developer tools like Swagger and GraphQL playground
• The REST v1 API remains on the coordinator node, we’re actively discussing how long to maintain this original version of the REST API, but for the moment it is not supported by the v2 REST API service.

For more details on ports and paths for v2, see the table below.

Regardless of your particular deployment, no application code changes should be required (beyond any configuration updates required to point to new endpoints), as all Stargate v2 API implementations are backward compatible with v1 implementations.

Some users may be deploying Stargate as part of a K8ssandra cluster. We’re actively collaborating with the K8ssandra team on extending the K8ssandra operator to be able to deploy and scale Stargate v2, including both the coordinator node and the new API services.

What Comes After v2?

As we move forward, we’ll continue to maintain the support of existing APIs and work toward modernization of the coordinator node including JDK updates, Quarkus adoption, and removal of OSGI from the coordinator.

We’re also excited for the possibility of developing new APIs. The Dynamo API prototype developed as a masters project by a team of students from Carnegie Mellon University has served as a valuable proof point of the extensibility of the v2 architecture.

In our next blog we’ll talk more about how you can contribute to the Stargate project, whether by creating new examples, adding APIs, or extending the coordinator node.