Using a Cassandra Java client driver to access Amazon Keyspaces programmatically
This section shows you how to connect to Amazon Keyspaces by using a Java client driver.
Note
Java 17 and the DataStax Java Driver 4.17 are currently only in Beta support. For more information,
see https://docs.datastax.com/en/developer/java-driver/4.17/upgrade_guide/
To provide users and applications with credentials for programmatic access to Amazon Keyspaces resources, you can do either of the following:
-
Create service-specific credentials that are associated with a specific Amazon Identity and Access Management (IAM) user.
-
For enhanced security, we recommend to create IAM access keys for IAM identities that are used across all Amazon services. The Amazon Keyspaces SigV4 authentication plugin for Cassandra client drivers enables you to authenticate calls to Amazon Keyspaces using IAM access keys instead of user name and password. For more information, see How to create and configure Amazon credentials for Amazon Keyspaces.
Note
For an example how to use Amazon Keyspaces with Spring Boot, see https://github.com/aws-samples/amazon-keyspaces-examples/tree/main/java/datastax-v4/spring
Topics
- Before you begin
- Step-by-step tutorial to connect to Amazon Keyspaces using the DataStax Java driver for Apache Cassandra using service-specific credentials
- Step-by-step tutorial to connect to Amazon Keyspaces using the 4.x DataStax Java driver for Apache Cassandra and the SigV4 authentication plugin
- Connect to Amazon Keyspaces using the 3.x DataStax Java driver for Apache Cassandra and the SigV4 authentication plugin
Before you begin
To connect to Amazon Keyspaces, you need to complete the following tasks before you can start.
Amazon Keyspaces requires the use of Transport Layer Security (TLS) to help secure connections with clients.
Download the Starfield digital certificate using the following command and save
sf-class2-root.crt
locally or in your home directory.curl https://certs.secureserver.net/repository/sf-class2-root.crt -O
Note
You can also use the Amazon digital certificate to connect to Amazon Keyspaces and can continue to do so if your client is connecting to Amazon Keyspaces successfully. The Starfield certificate provides additional backwards compatibility for clients using older certificate authorities.
Convert the Starfield digital certificate into a trustStore file.
openssl x509 -outform der -in sf-class2-root.crt -out temp_file.der keytool -import -alias cassandra -keystore cassandra_truststore.jks -file temp_file.der
In this step, you need to create a password for the keystore and trust this certificate. The interactive command looks like this.
Enter keystore password: Re-enter new password: Owner: OU=Starfield Class 2 Certification Authority, O="Starfield Technologies, Inc.", C=US Issuer: OU=Starfield Class 2 Certification Authority, O="Starfield Technologies, Inc.", C=US Serial number: 0 Valid from: Tue Jun 29 17:39:16 UTC 2004 until: Thu Jun 29 17:39:16 UTC 2034 Certificate fingerprints: MD5: 32:4A:4B:BB:C8:63:69:9B:BE:74:9A:C6:DD:1D:46:24 SHA1: AD:7E:1C:28:B0:64:EF:8F:60:03:40:20:14:C3:D0:E3:37:0E:B5:8A SHA256: 14:65:FA:20:53:97:B8:76:FA:A6:F0:A9:95:8E:55:90:E4:0F:CC:7F:AA:4F:B7:C2:C8:67:75:21:FB:5F:B6:58 Signature algorithm name: SHA1withRSA Subject Public Key Algorithm: 2048-bit RSA key Version: 3 Extensions: #1: ObjectId: 2.5.29.35 Criticality=false AuthorityKeyIdentifier [ KeyIdentifier [ 0000: BF 5F B7 D1 CE DD 1F 86 F4 5B 55 AC DC D7 10 C2 ._.......[U..... 0010: 0E A9 88 E7 .... ] [OU=Starfield Class 2 Certification Authority, O="Starfield Technologies, Inc.", C=US] SerialNumber: [ 00] ] #2: ObjectId: 2.5.29.19 Criticality=false BasicConstraints:[ CA:true PathLen:2147483647 ] #3: ObjectId: 2.5.29.14 Criticality=false SubjectKeyIdentifier [ KeyIdentifier [ 0000: BF 5F B7 D1 CE DD 1F 86 F4 5B 55 AC DC D7 10 C2 ._.......[U..... 0010: 0E A9 88 E7 .... ] ] Trust this certificate? [no]: y
-
Attach the trustStore file in the JVM arguments:
-Djavax.net.ssl.trustStore=
path_to_file
/cassandra_truststore.jks -Djavax.net.ssl.trustStorePassword=my_password
Step-by-step tutorial to connect to Amazon Keyspaces using the DataStax Java driver for Apache Cassandra using service-specific credentials
The following step-by-step tutorial walks you through connecting to Amazon Keyspaces using a Java driver for Cassandra using service-specific credentials. Specifically, you'll use the 4.0 version of the DataStax Java driver for Apache Cassandra.
Step 1: Prerequisites
To follow this tutorial, you need to generate service-specific credentials and add the DataStax Java driver for Apache Cassandra to your Java project.
Generate service-specific credentials for your Amazon Keyspaces IAM user by completing the steps in Generate service-specific credentials. If you prefer to use IAM access keys for authentication, see Step-by-step tutorial to connect to Amazon Keyspaces using the 4.x DataStax Java driver for Apache Cassandra and the SigV4 authentication plugin.
Add the DataStax Java driver for Apache Cassandra to your Java project. Ensure that you're using a version of the driver that supports Apache Cassandra 3.11.2. For more information, see the DataStax Java driver for Apache Cassandra documentation
.
Step 2: Configure the driver
You can specify settings for the DataStax Java Cassandra driver by creating a configuration file for your application. This configuration file overrides the default settings and tells the driver to connect to the Amazon Keyspaces service endpoint using port 9142. For a list of available service endpoints, see Service endpoints for Amazon Keyspaces.
Create a configuration file and save the file in the application's
resources folder—for example,
src/main/resources/application.conf
. Open
application.conf
and add the following
configuration settings.
Authentication provider – Create the authentication provider with the
PlainTextAuthProvider
class.ServiceUserName
andServicePassword
should match the user name and password you obtained when you generated the service-specific credentials by following the steps in Generate service-specific credentials.Note
You can use short-term credentials by using the authentication plugin for the DataStax Java driver for Apache Cassandra instead of hardcoding credentials in your driver configuration file. To learn more, follow the instructions for the Step-by-step tutorial to connect to Amazon Keyspaces using the 4.x DataStax Java driver for Apache Cassandra and the SigV4 authentication plugin.
Local data center – Set the value for
local-datacenter
to the Region you're connecting to. For example, if the application is connecting tocassandra.us-east-2.amazonaws.com
, then set the local data center tous-east-2
. For all available Amazon Web Services Regions, see Service endpoints for Amazon Keyspaces. Setslow-replica-avoidance = false
to load balance against fewer nodes.SSL/TLS – Initialize the SSLEngineFactory by adding a section in the configuration file with a single line that specifies the class with
class = DefaultSslEngineFactory
. Provide the path to the trustStore file and the password that you created previously. Amazon Keyspaces doesn't supporthostname-validation
of peers, so set this option to false.
datastax-java-driver { basic.contact-points = [ "
cassandra.us-east-2.amazonaws.com
:9142"] advanced.auth-provider{ class = PlainTextAuthProvider username ="ServiceUserName"
password ="ServicePassword"
} basic.load-balancing-policy { local-datacenter ="us-east-2"
slow-replica-avoidance = false } advanced.ssl-engine-factory { class = DefaultSslEngineFactory truststore-path ="./src/main/resources/cassandra_truststore.jks"
truststore-password ="my_password"
hostname-validation = false } }
Note
Instead of adding the path to the trustStore in the configuration file, you can also add the trustStore path directly in the application code or you can add the path to the trustStore to your JVM arguments.
Step 3: Run the sample application
This code example shows a simple command line application that creates a connection pool to Amazon Keyspaces by using the configuration file we created earlier. It confirms that the connection is established by running a simple query.
package
<your package>
; // add the following imports to your project import com.datastax.oss.driver.api.core.CqlSession; import com.datastax.oss.driver.api.core.config.DriverConfigLoader; import com.datastax.oss.driver.api.core.cql.ResultSet; import com.datastax.oss.driver.api.core.cql.Row; public class App { public static void main( String[] args ) { //Use DriverConfigLoader to load your configuration file DriverConfigLoader loader = DriverConfigLoader.fromClasspath("application.conf"); try (CqlSession session = CqlSession.builder() .withConfigLoader(loader) .build()) { ResultSet rs = session.execute("select * from system_schema.keyspaces"); Row row = rs.one(); System.out.println(row.getString("keyspace_name")); } } }
Note
Use a try
block to establish the connection to ensure that it's
always closed. If you don't use a try
block, remember
to close your connection to avoid leaking resources.
Step-by-step tutorial to connect to Amazon Keyspaces using the 4.x DataStax Java driver for Apache Cassandra and the SigV4 authentication plugin
The following section describes how to use the SigV4 authentication
plugin for the open-source 4.x DataStax Java driver for Apache Cassandra to access
Amazon Keyspaces (for Apache Cassandra). The plugin is available from the GitHub
repository
The SigV4 authentication plugin allows you to use IAM credentials for users or roles when connecting to Amazon Keyspaces. Instead of requiring a user name and password, this plugin signs API requests using access keys. For more information, see How to create and configure Amazon credentials for Amazon Keyspaces.
Step 1: Prerequisites
To follow this tutorial, you need to complete the following tasks.
If you haven't already done so, create credentials for your IAM user or role following the steps at How to create and configure Amazon credentials for Amazon Keyspaces. This tutorial assumes that the access keys are stored as environment variables. For more information, see How to manage access keys for IAM users.
Add the DataStax Java driver for Apache Cassandra to your Java project. Ensure that you're using a version of the driver that supports Apache Cassandra 3.11.2. For more information, see the DataStax Java Driver for Apache Cassandra documentation
. Add the authentication plugin to your application. The authentication plugin supports version 4.x of the DataStax Java driver for Apache Cassandra. If you’re using Apache Maven, or a build system that can use Maven dependencies, add the following dependencies to your
pom.xml
file.Important
Replace the version of the plugin with the latest version as shown at GitHub repository
. <dependency> <groupId>software.aws.mcs</groupId> <artifactId>aws-sigv4-auth-cassandra-java-driver-plugin</artifactId> <version>
4.0.9
</version> </dependency>
Step 2: Configure the driver
You can specify settings for the DataStax Java Cassandra driver by creating a configuration file for your application. This configuration file overrides the default settings and tells the driver to connect to the Amazon Keyspaces service endpoint using port 9142. For a list of available service endpoints, see Service endpoints for Amazon Keyspaces.
Create a configuration file and save the file in the application's
resources folder—for example,
src/main/resources/application.conf
. Open
application.conf
and add the following
configuration settings.
Authentication provider – Set the
advanced.auth-provider.class
to a new instance ofsoftware.aws.mcs.auth.SigV4AuthProvider
. The SigV4AuthProvider is the authentication handler provided by the plugin for performing SigV4 authentication.Local data center – Set the value for
local-datacenter
to the Region you're connecting to. For example, if the application is connecting tocassandra.us-east-2.amazonaws.com
, then set the local data center tous-east-2
. For all available Amazon Web Services Regions, see Service endpoints for Amazon Keyspaces. Setslow-replica-avoidance = false
to load balance against all available nodes.Idempotence – Set the default
idempotence
for the application totrue
to configure the driver to always retry failed read/write/prepare/execute requests. This is a best practice for distributed applications that helps to handle transient failures by retrying failed requests.SSL/TLS – Initialize the SSLEngineFactory by adding a section in the configuration file with a single line that specifies the class with
class = DefaultSslEngineFactory
. Provide the path to the trustStore file and the password that you created previously. Amazon Keyspaces doesn't supporthostname-validation
of peers, so set this option to false.Connections – Create at least 3 local connections per endpoint by setting
local.size = 3
. This is a best practice that helps your application to handle overhead and traffic bursts. For more information about how to calculate how many local connections per endpoint your application needs based on expected traffic patterns, see How to configure connections in Amazon Keyspaces.Retry policy – The Amazon Keyspaces retry policy
AmazonKeyspacesExponentialRetryPolicy
is an alternative to theDefaultRetryPolicy
that comes with the Cassandra driver. The main difference between the two retry policies is that you can configure the amount of retry attempts for theAmazonKeyspacesExponentialRetryPolicy
to meet your needs. By default, the number of retry attempts for theAmazonKeyspacesExponentialRetryPolicy
is set to 3. In addition, the Amazon Keyspaces retry policy doesn't return the genericNoHostAvailableException
. Instead, the Amazon Keyspaces retry policy passes back the original exception returned by the service. For more code examples implementing retry policies, see Amazon Keyspaces retry policieson Github. Prepared statements – Set
prepare-on-all-nodes
to false to optimize network usage.
datastax-java-driver { basic { contact-points = [ "
cassandra.us-east-2.amazonaws.com:9142
"] request { timeout = 2 seconds consistency = LOCAL_QUORUM page-size = 1024 default-idempotence = true } load-balancing-policy { local-datacenter = "us-east-2
" class = DefaultLoadBalancingPolicy slow-replica-avoidance = false } } advanced { auth-provider { class = software.aws.mcs.auth.SigV4AuthProvider aws-region =us-east-2
} ssl-engine-factory { class = DefaultSslEngineFactory truststore-path = "./src/main/resources/cassandra_truststore.jks
" truststore-password = "my_password
" hostname-validation = false } connection { connect-timeout = 5 seconds max-requests-per-connection = 512 pool { local.size = 3 } } retry-policy { class = com.aws.ssa.keyspaces.retry.AmazonKeyspacesExponentialRetryPolicy max-attempts = 3 min-wait = 10 mills max-wait = 100 mills } prepared-statements { prepare-on-all-nodes = false } } }
Note
Instead of adding the path to the trustStore in the configuration file, you can also add the trustStore path directly in the application code or you can add the path to the trustStore to your JVM arguments.
Step 3: Run the application
This code example shows a simple command line application that creates a connection pool to Amazon Keyspaces by using the configuration file we created earlier. It confirms that the connection is established by running a simple query.
package
<your package>
; // add the following imports to your project import com.datastax.oss.driver.api.core.CqlSession; import com.datastax.oss.driver.api.core.config.DriverConfigLoader; import com.datastax.oss.driver.api.core.cql.ResultSet; import com.datastax.oss.driver.api.core.cql.Row; public class App { public static void main( String[] args ) { //Use DriverConfigLoader to load your configuration file DriverConfigLoader loader = DriverConfigLoader.fromClasspath("application.conf"); try (CqlSession session = CqlSession.builder() .withConfigLoader(loader) .build()) { ResultSet rs = session.execute("select * from system_schema.keyspaces"); Row row = rs.one(); System.out.println(row.getString("keyspace_name")); } } }
Note
Use a try
block to establish the connection to ensure that it's
always closed. If you don't use a try
block, remember
to close your connection to avoid leaking resources.
Connect to Amazon Keyspaces using the 3.x DataStax Java driver for Apache Cassandra and the SigV4 authentication plugin
The following section describes how to use the SigV4 authentication plugin for
the 3.x open-source DataStax Java driver for Apache Cassandra to access Amazon Keyspaces. The
plugin is available from the GitHub repository
The SigV4 authentication plugin allows you to use IAM credentials for users and roles when connecting to Amazon Keyspaces. Instead of requiring a user name and password, this plugin signs API requests using access keys. For more information, see How to create and configure Amazon credentials for Amazon Keyspaces.
Step 1: Prerequisites
To run this code sample, you first need to complete the following tasks.
Create credentials for your IAM user or role following the steps at How to create and configure Amazon credentials for Amazon Keyspaces. This tutorial assumes that the access keys are stored as environment variables. For more information, see How to manage access keys for IAM users.
Follow the steps at Before you begin to download the Starfield digital certificate, convert it to a trustStore file, and attach the trustStore file in the JVM arguments to your application.
Add the DataStax Java driver for Apache Cassandra to your Java project. Ensure that you're using a version of the driver that supports Apache Cassandra 3.11.2. For more information, see the DataStax Java Driver for Apache Cassandra documentation
. Add the authentication plugin to your application. The authentication plugin supports version 3.x of the DataStax Java driver for Apache Cassandra. If you’re using Apache Maven, or a build system that can use Maven dependencies, add the following dependencies to your
pom.xml
file. Replace the version of the plugin with the latest version as shown at GitHub repository. <dependency> <groupId>software.aws.mcs</groupId> <artifactId>aws-sigv4-auth-cassandra-java-driver-plugin_3</artifactId> <version>
3.0.3
</version> </dependency>
Step 2: Run the application
This code example shows a simple command line application that creates a connection pool to Amazon Keyspaces. It confirms that the connection is established by running a simple query.
package
<your package>
; // add the following imports to your project import software.aws.mcs.auth.SigV4AuthProvider; import com.datastax.driver.core.Cluster; import com.datastax.driver.core.ResultSet; import com.datastax.driver.core.Row; import com.datastax.driver.core.Session; public class App { public static void main( String[] args ) { String endPoint = "cassandra.us-east-2.amazonaws.com
"; int portNumber = 9142; Session session = Cluster.builder() .addContactPoint(endPoint) .withPort(portNumber) .withAuthProvider(new SigV4AuthProvider("us-east-2
")) .withSSL() .build() .connect(); ResultSet rs = session.execute("select * from system_schema.keyspaces"); Row row = rs.one(); System.out.println(row.getString("keyspace_name")); } }
Usage notes:
For a list of available endpoints, see Service endpoints for Amazon Keyspaces.
See the following repository for helpful Java driver policies, examples, and best practices
when using the Java Driver with Amazon Keyspaces:
https://github.com/aws-samples/amazon-keyspaces-java-driver-helpers