Using cqlsh to connect to Amazon Keyspaces

Installing and configuring the cqlsh-expansion

1. To install the cqlsh-expansion Python package, you can run a pip command. This installs the cqlsh-expansion scripts on your machine using a pip install along with a file containing a list of dependencies. The --user flag tells pip to use the Python user install directory for your platform. On a Unix based system, that should be the ~/.local/ directory.

   You need Python 3 to install the cqlsh-expansion, to find out your Python version, use Python --version. To install, you can run the following command.

   python3 -m pip install --user cqlsh-expansion

   The output should look similar to this.

   Collecting cqlsh-expansion
     Downloading cqlsh_expansion-0.9.6-py3-none-any.whl (153 kB)
        ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 153.7/153.7 KB 3.3 MB/s eta 0:00:00
   Collecting cassandra-driver
     Downloading cassandra_driver-3.28.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (19.1 MB)
        ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 19.1/19.1 MB 44.5 MB/s eta 0:00:00
   Requirement already satisfied: six>=1.12.0 in /usr/lib/python3/dist-packages (from cqlsh-expansion) (1.16.0)
   Collecting boto3
     Downloading boto3-1.29.2-py3-none-any.whl (135 kB)
        ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 135.8/135.8 KB 17.2 MB/s eta 0:00:00
   Collecting cassandra-sigv4>=4.0.2
     Downloading cassandra_sigv4-4.0.2-py2.py3-none-any.whl (9.8 kB)
   Collecting botocore<1.33.0,>=1.32.2
     Downloading botocore-1.32.2-py3-none-any.whl (11.4 MB)
        ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 11.4/11.4 MB 60.9 MB/s eta 0:00:00
   Collecting s3transfer<0.8.0,>=0.7.0
     Downloading s3transfer-0.7.0-py3-none-any.whl (79 kB)
        ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 79.8/79.8 KB 13.1 MB/s eta 0:00:00
   Collecting jmespath<2.0.0,>=0.7.1
     Downloading jmespath-1.0.1-py3-none-any.whl (20 kB)
   Collecting geomet<0.3,>=0.1
     Downloading geomet-0.2.1.post1-py3-none-any.whl (18 kB)
   Collecting python-dateutil<3.0.0,>=2.1
     Downloading python_dateutil-2.8.2-py2.py3-none-any.whl (247 kB)
        ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 247.7/247.7 KB 33.1 MB/s eta 0:00:00
   Requirement already satisfied: urllib3<2.1,>=1.25.4 in /usr/lib/python3/dist-packages (from botocore<1.33.0,>=1.32.2->boto3->cqlsh-expansion) (1.26.5)
   Requirement already satisfied: click in /usr/lib/python3/dist-packages (from geomet<0.3,>=0.1->cassandra-driver->cqlsh-expansion) (8.0.3)
   Installing collected packages: python-dateutil, jmespath, geomet, cassandra-driver, botocore, s3transfer, boto3, cassandra-sigv4, cqlsh-expansion
     WARNING: The script geomet is installed in '/home/ubuntu/.local/bin' which is not on PATH.
     Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
     WARNING: The scripts cqlsh, cqlsh-expansion and cqlsh-expansion.init are installed in '/home/ubuntu/.local/bin' which is not on PATH.
     Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
   Successfully installed boto3-1.29.2 botocore-1.32.2 cassandra-driver-3.28.0 cassandra-sigv4-4.0.2 cqlsh-expansion-0.9.6 geomet-0.2.1.post1 jmespath-1.0.1 python-dateutil-2.8.2 s3transfer-0.7.0

   If the install directory is not in the PATH, you need to add it following the instructions of your operating system. Below is one example for Ubuntu Linux.

   export PATH="$PATH:/home/ubuntu/.local/bin"

   To confirm that the package is installed, you can run the following command.

   cqlsh-expansion --version

   The output should look like this.

   cqlsh 6.1.0

2. To configure the cqlsh-expansion, you can run a post-install script to automatically complete the following steps:

   1. Create the .cassandra directory in the user home directory if it doesn't already exist.

   2. Copy a preconfigured cqlshrc configuration file into the .cassandra directory.

   3. Copy the combined certificate file into the .cassandra directory. Amazon Keyspaces uses this certificate to configure the secure connection with Transport Layer Security (TLS). Encryption in transit provides an additional layer of data protection by encrypting your data as it travels to and from Amazon Keyspaces. For more information about certificates, see How to manually configure cqlsh connections for TLS.

   To review the script first, you can access it in the Github repo at post_install.py.

   To use the script, you can run the following command.

   cqlsh-expansion.init

   Note

   The directory and file created by the post-install script are not removed when you uninstall the cqlsh-expansion using pip uninstall, and have to be deleted manually.

Connecting to Amazon Keyspaces using the cqlsh-expansion

1. Configure your Amazon Web Services Region and add it as a user environment variable.

   To add your default Region as an environment variable on a Unix based system, you can run the following command. For this example, we use us-east-1.

   export AWS_DEFAULT_REGION=us-east-1

   For more information about how to set environment variables, including for other platforms, see How to set environment variables.

2. Find your service endpoint.

   Choose the appropriate service endpoint for your Region. To review the available endpoints for Amazon Keyspaces, see Service endpoints for Amazon Keyspaces. For this example, we use the endpoint cassandra.us-east-1.amazonaws.com.

3. Configure the authentication method.

   Connecting with IAM access keys (IAM users, roles, and federated identities) is the recommended method for enhanced security.

   Before you can connect with IAM access keys, you need to complete the following steps:

   1. Create an IAM user, or follow the best practice and create an IAM role that IAM users can assume. For more information on how to create IAM access keys, see Create and configure Amazon credentials for Amazon Keyspaces.

   2. Create an IAM policy that grants the role (or IAM user) at least read-only access to Amazon Keyspaces. For more information about the permissions required for the IAM user or role to connect to Amazon Keyspaces, see Accessing Amazon Keyspaces tables.

   3. Add the access keys of the IAM user to the user's environment variables as shown in the following example.

      export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
      export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

      For more information about how to set environment variables, including for other platforms, see How to set environment variables.

      Note

      If you're connecting from an Amazon EC2 instance, you also need to configure an outbound rule in the security group that allows traffic from the instance to Amazon Keyspaces. For more information about how to view and edit EC2 outbound rules, see Add rules to a security group in the Amazon EC2 User Guide.

4. Connect to Amazon Keyspaces using the cqlsh-expansion and SigV4 authentication.

   To connect to Amazon Keyspaces with the cqlsh-expansion, you can use the following command. Make sure to replace the service endpoint with the correct endpoint for your Region.

   cqlsh-expansion cassandra.us-east-1.amazonaws.com 9142 --ssl

   If the connection is successful, you should see output similar to the following example.

   Connected to Amazon Keyspaces at cassandra.us-east-1.amazonaws.com:9142
   [cqlsh 6.1.0 | Cassandra 3.11.2 | CQL spec 3.4.4 | Native protocol v4]
   Use HELP for help.
   cqlsh current consistency level is ONE.
   cqlsh>

   If you encounter a connection error, see I can't connect to Amazon Keyspaces with cqlsh for troubleshooting information.

   • Connect to Amazon Keyspaces with service-specific credentials.

     To connect with the traditional username and password combination that Cassandra uses for authentication, you must first create service-specific credentials for Amazon Keyspaces as described in Create service-specific credentials for programmatic access to Amazon Keyspaces. You also have to give that user permissions to access Amazon Keyspaces, for more information see Accessing Amazon Keyspaces tables.

     After you have created service-specific credentials and permissions for the user, you must update the cqlshrc file, typically found in the user directory path ~/.cassandra/. In the cqlshrc file, go to the Cassandra [authentication] section and comment out the SigV4 module and class under [auth_provider] using the ";" character as shown in the following example.

     [auth_provider]
     
     ; module = cassandra_sigv4.auth
     
     ; classname = SigV4AuthProvider

     After you have updated the cqlshrc file, you can connect to Amazon Keyspaces with service-specific credentials using the following command.

     cqlsh-expansion cassandra.us-east-1.amazonaws.com 9142 -u myUserName -p myPassword --ssl

Cleanup

• To remove the cqlsh-expansion package you can use the pip uninstall command.

  pip3 uninstall cqlsh-expansion

  The pip3 uninstall command doesn't remove the directory and related files created by the post-install script. To remove the folder and files created by the post-install script, you can delete the .cassandra directory.