# The Amazon Keyspaces (for Apache Cassandra) developer toolkit cqlsh-expansion script
The Amazon Keyspaces toolkit contains common Cassandra tooling and helpers preconfigured for Amazon Keyspaces. The cqlsh-expansion utility extends native cqlsh functionality to include parameters and capabilities specific to Amazon Keyspaces without breaking compatibility with Apache Cassandra. This includes support for the Sigv4 Authentication plugin. Normally, cqlsh is packaged with the full distribution of Apache Cassandra, but since Amazon Keyspaces is a serverless database service, we only require the cqlsh scripts and not the full distribution. This repository provides a lightweight distribution of cqlsh that can be installed on platforms that support python.
## Installing cqlsh-expansion
To install the cqlsh-expansion python package you can run the following pip command. The command below executes a “pip install” that will install the cqlsh-expansion scripts. It will also install a requirements file containing a list of dependencies. The --`user` flag tells pip to use the Python *user install directory* for your platform. Typically ~/.local/ on unix based systems.
```
pip install --user cqlsh-expansion
```
Alternatively, if you are using python3 as default you may have to use the following command to install the cqlsh-expansion package.
```
python3 -m pip install --user cqlsh-expansion
```
## Setup cqlsh-expansion to connect to Amazon Keyspaces
To use the cqlsh-expansion with Amazon Keyspaces you can use the following post install script or by following the instructions found in the official [Amazon Keyspaces documentation.](https://docs.aws.amazon.com/keyspaces/latest/devguide/programmatic.cqlsh.html)
By default the cqlsh-expansion is not configured with ssl enabled, but the package includes a [post install script](https://github.com/aws-samples/amazon-keyspaces-toolkit/blob/master/cqlsh-expansion/config/post_install.py) helper to quickly setup your environment after installation. The script will place the necessary configuration and SSL certificate in the user’s *.cassandra* directory. Amazon Keyspaces only accepts secure connections using 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. The post install script first will create the .cassandra directory if it does not exist already. Then it will copy a [preconfigure a cqlshrc file](https://github.com/aws-samples/amazon-keyspaces-toolkit/blob/master/cqlsh-expansion/config/cqlshrc_template) and the Starfield digital certificate into the .cassandra directory. The .cassandra directory will be created in the user home directory as it is the default location. As best practice, please review the [post install script](https://github.com/aws-samples/amazon-keyspaces-toolkit/blob/master/cqlsh-expansion/config/post_install.py)before executing. Modifications made by this post install script will not be undone if uninstalling the cqlsh-expansion with pip.
```
cqlsh-expansion.init
```
## Connection to Amazon Keyspaces
Now that you have you cqlsh-expansion installed and have setup up the configuration for SSL communication with Amazon Keyspaces, you can now connect to the Amazon Keyspaces services using your IAM access keys or Service Specific Credentials.
### Choose a region and endpoint
To connect to Amazon Keyspaces you will need to choose one of the [service endpoints](https://docs.aws.amazon.com/keyspaces/latest/devguide/programmatic.endpoints.html). You can also connect to Amazon Keyspaces using [Interface VPC endpoints](https://docs.aws.amazon.com/keyspaces/latest/devguide/vpc-endpoints.html) to enable private communication between your virtual private cloud (VPC) running in Amazon VPC and Amazon Keyspaces. For example, to connect to the Keyspaces service in US East (N. Virginia) (us-east-1) you will want to use the [cassandra.us-east-1.amazonaws.com](http://cassandra.us-east-1.amazonaws.com/) service endpoint. All communication with Amazon Keyspaces will be over port 9142.
### Choose authentication method and connect
To provide users and applications with credentials for programmatic access to Amazon Keyspaces resources, you can do either of the following:
#### Connect with IAM access keys (users,roles, and federated identities)
For enhanced security, we recommend to create IAM access keys for IAM users and roles that are used across all AWS services. To use IAM access keys to connect to Amazon Keyspaces, customers can use the Signature Version 4 Process (SigV4) authentication plugin for Cassandra client drivers. To learn more about how the Amazon Keyspaces SigV4 plugin enables [IAM users, roles, and federated identities](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) to authenticate in Amazon Keyspaces API requests, see [AWS Signature Version 4 process (SigV4)](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html).
After you have the credentials setup with [privileges](https://docs.aws.amazon.com/keyspaces/latest/devguide/security_iam_service-with-iam.html) to access Amazon Keyspaces system tables, you can execute the following command to connect to Amazon Keyspaces with CQLSH using the Sigv4 process.
Validate the module name and classname, region_name based on keyspaces endpoint in cqlshrc file.
```
[auth_provider]
;; you can specify any auth provider found in your python environment
;; module and class will be used to dynamically load the class
;; all other properties found here and in the credentials file under the class name
;; will be passed to the constructor
module = cassandra_sigv4.auth
classname = SigV4AuthProvider
region_name = us-east-1
```
you can also set region as Environment variable
```
export AWS_DEFAULT_REGION=us-east-1
```
To connect to Amazon Keyspaces with cqlsh-expansion using Sigv4 authenticator.
```
cqlsh-expansion cassandra.us-east-1.amazonaws.com 9142 --ssl
```
#### Connect with service-specific credentials
You can create service-specific credentials that are similar to the traditional username and password that Cassandra uses for authentication and access management. AWS service-specific credentials are associated with a specific AWS Identity and Access Management (IAM) user and can only be used for the service they were created for. For more information, see [Using IAM with Amazon Keyspaces (for Apache Cassandra)](http://using%20iam%20with%20amazon%20keyspaces%20%28for%20apache%20cassandra%29/) in the IAM User Guide. To connect to Amazon Keyspaces using the cqlsh-expansion and IAM service-specific credentials you can use the command below. In this command we are connecting to us-east-1 region with service specific user *‘Sri-user-99’ *and service specific user password* ‘user-pass-01’. *You will need to replace these credentials with your own user name and password that were given to you when creating the service specific credentials.
```
[auth_provider]
;; you can specify any auth provider found in your python environment
;; module and class will be used to dynamically load the class
;; all other properties found here and in the credentials file under the class name
;; will be passed to the constructor
module = cassandra.auth
classname = PlainTextAuthProvider
```
```
cqlsh-expansion cassandra.us-east-1.amazonaws.com -u Sri-user-99 -p user-pass-01
```
## Cleanup
To remove the cqlsh-expansion package you can use the pip uninstall api. Additionally, if you executed the post install script ```cqlsh-expansion.init```, you may want to delete the .cassandra directory which contains the cqlshrc file and the ssl certificate. Using pip uninstall will not remove changes made by the post install script.
```
pip uninstall cqlsh-expansion
```
### New output for TTY
When creating a new cqlsh session with the cqlsh-expansion utility, it will show the default consistency level after establishing a new connection. We find customers using cqlsh may not be aware of the default consistency level of `ONE`, and additional transparency will lead to better operational excellence.
### COPY FROM/TO required Consistency Levels
When executing the `COPY FROM` import operation from the cqlsh-expansion utility, `LOCAL_QUORUM` will be strictly enforced. Executing `COPY FROM` with consistency level other than LOCAL_QUORUM will result in an SyntaxError. This restriction is to provide better experience when using `COPY FROM` with Amazon Keyspaces. Amazon Keyspaces replicates all write operations three times across multiple Availability Zones for durability and high availability. Writes are durably stored before they are acknowledged using the `LOCAL_QUORUM` consistency level.
When executing the `COPY TO` export operation from the cqlsh-expansion utility, consistency of `ONE, LOCAL_ONE, or LOCAL_QUORUM` will be strictly enforced. Executing `COPY FROM` with consistency level other than these three will result in an SyntaxError. This restriction is to provide better experience when using `COPY FROM` with Amazon Keyspaces.
### Contributing:
```
# Security
See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
# License
This library is licensed under the MIT-0 License. See the LICENSE file.
```
Raw data
{
"_id": null,
"home_page": "https://github.com/aws-samples/amazon-keyspaces-toolkit/tree/master/cqlsh-expansion",
"name": "cqlsh-expansion",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "cql,cqlsh,cqlsh-expansion,aws,keyspaces,cassandra,sigv4",
"author": "Michael Raney, Sri Rathan Rangisetti",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/8f/34/a1e5e00e9fa5b40e2b5092188b3ba9919fd3d3fd95a161d19701ad3f1f49/cqlsh-expansion-0.9.6.tar.gz",
"platform": null,
"description": "\n# The Amazon Keyspaces (for Apache Cassandra) developer toolkit cqlsh-expansion script\n\nThe Amazon Keyspaces toolkit contains common Cassandra tooling and helpers preconfigured for Amazon Keyspaces. The cqlsh-expansion utility extends native cqlsh functionality to include parameters and capabilities specific to Amazon Keyspaces without breaking compatibility with Apache Cassandra. This includes support for the Sigv4 Authentication plugin. Normally, cqlsh is packaged with the full distribution of Apache Cassandra, but since Amazon Keyspaces is a serverless database service, we only require the cqlsh scripts and not the full distribution. This repository provides a lightweight distribution of cqlsh that can be installed on platforms that support python. \n\n\n## Installing cqlsh-expansion\n\nTo install the cqlsh-expansion python package you can run the following pip command. The command below executes a \u201cpip install\u201d that will install the cqlsh-expansion scripts. It will also install a requirements file containing a list of dependencies. The --`user` flag tells pip to use the Python *user install directory* for your platform. Typically ~/.local/ on unix based systems. \n\n```\npip install --user cqlsh-expansion \n```\n\nAlternatively, if you are using python3 as default you may have to use the following command to install the cqlsh-expansion package. \n\n```\npython3 -m pip install --user cqlsh-expansion\n```\n\n## Setup cqlsh-expansion to connect to Amazon Keyspaces\n\nTo use the cqlsh-expansion with Amazon Keyspaces you can use the following post install script or by following the instructions found in the official [Amazon Keyspaces documentation.](https://docs.aws.amazon.com/keyspaces/latest/devguide/programmatic.cqlsh.html) \n\nBy default the cqlsh-expansion is not configured with ssl enabled, but the package includes a [post install script](https://github.com/aws-samples/amazon-keyspaces-toolkit/blob/master/cqlsh-expansion/config/post_install.py) helper to quickly setup your environment after installation. The script will place the necessary configuration and SSL certificate in the user\u2019s *.cassandra* directory. Amazon Keyspaces only accepts secure connections using 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. The post install script first will create the .cassandra directory if it does not exist already. Then it will copy a [preconfigure a cqlshrc file](https://github.com/aws-samples/amazon-keyspaces-toolkit/blob/master/cqlsh-expansion/config/cqlshrc_template) and the Starfield digital certificate into the .cassandra directory. The .cassandra directory will be created in the user home directory as it is the default location. As best practice, please review the [post install script](https://github.com/aws-samples/amazon-keyspaces-toolkit/blob/master/cqlsh-expansion/config/post_install.py)before executing. Modifications made by this post install script will not be undone if uninstalling the cqlsh-expansion with pip. \n\n```\n\ncqlsh-expansion.init\n\n```\n\n## Connection to Amazon Keyspaces\n\nNow that you have you cqlsh-expansion installed and have setup up the configuration for SSL communication with Amazon Keyspaces, you can now connect to the Amazon Keyspaces services using your IAM access keys or Service Specific Credentials. \n\n### Choose a region and endpoint\n\nTo connect to Amazon Keyspaces you will need to choose one of the [service endpoints](https://docs.aws.amazon.com/keyspaces/latest/devguide/programmatic.endpoints.html). You can also connect to Amazon Keyspaces using [Interface VPC endpoints](https://docs.aws.amazon.com/keyspaces/latest/devguide/vpc-endpoints.html) to enable private communication between your virtual private cloud (VPC) running in Amazon VPC and Amazon Keyspaces. For example, to connect to the Keyspaces service in US East (N. Virginia) (us-east-1) you will want to use the [cassandra.us-east-1.amazonaws.com](http://cassandra.us-east-1.amazonaws.com/) service endpoint. All communication with Amazon Keyspaces will be over port 9142. \n\n### Choose authentication method and connect\nTo provide users and applications with credentials for programmatic access to Amazon Keyspaces resources, you can do either of the following:\n\n#### Connect with IAM access keys (users,roles, and federated identities)\n\nFor enhanced security, we recommend to create IAM access keys for IAM users and roles that are used across all AWS services. To use IAM access keys to connect to Amazon Keyspaces, customers can use the Signature Version 4 Process (SigV4) authentication plugin for Cassandra client drivers. To learn more about how the Amazon Keyspaces SigV4 plugin enables [IAM users, roles, and federated identities](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) to authenticate in Amazon Keyspaces API requests, see [AWS Signature Version 4 process (SigV4)](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html). \n\nAfter you have the credentials setup with [privileges](https://docs.aws.amazon.com/keyspaces/latest/devguide/security_iam_service-with-iam.html) to access Amazon Keyspaces system tables, you can execute the following command to connect to Amazon Keyspaces with CQLSH using the Sigv4 process. \n\nValidate the module name and classname, region_name based on keyspaces endpoint in cqlshrc file. \n\n```\n[auth_provider]\n;; you can specify any auth provider found in your python environment\n;; module and class will be used to dynamically load the class\n;; all other properties found here and in the credentials file under the class name\n;; will be passed to the constructor\nmodule = cassandra_sigv4.auth\nclassname = SigV4AuthProvider\nregion_name = us-east-1\n```\nyou can also set region as Environment variable\n\n```\n export AWS_DEFAULT_REGION=us-east-1 \n```\n\nTo connect to Amazon Keyspaces with cqlsh-expansion using Sigv4 authenticator. \n```\ncqlsh-expansion cassandra.us-east-1.amazonaws.com 9142 --ssl \n```\n\n#### Connect with service-specific credentials\n\nYou can create service-specific credentials that are similar to the traditional username and password that Cassandra uses for authentication and access management. AWS service-specific credentials are associated with a specific AWS Identity and Access Management (IAM) user and can only be used for the service they were created for. For more information, see [Using IAM with Amazon Keyspaces (for Apache Cassandra)](http://using%20iam%20with%20amazon%20keyspaces%20%28for%20apache%20cassandra%29/) in the IAM User Guide. To connect to Amazon Keyspaces using the cqlsh-expansion and IAM service-specific credentials you can use the command below. In this command we are connecting to us-east-1 region with service specific user *\u2018Sri-user-99\u2019 *and service specific user password* \u2018user-pass-01\u2019. *You will need to replace these credentials with your own user name and password that were given to you when creating the service specific credentials. \n\n\n```\n[auth_provider]\n;; you can specify any auth provider found in your python environment\n;; module and class will be used to dynamically load the class\n;; all other properties found here and in the credentials file under the class name\n;; will be passed to the constructor\nmodule = cassandra.auth\nclassname = PlainTextAuthProvider\n```\n\n```\ncqlsh-expansion cassandra.us-east-1.amazonaws.com -u Sri-user-99 -p user-pass-01\n```\n\n\n## Cleanup\nTo remove the cqlsh-expansion package you can use the pip uninstall api. Additionally, if you executed the post install script ```cqlsh-expansion.init```, you may want to delete the .cassandra directory which contains the cqlshrc file and the ssl certificate. Using pip uninstall will not remove changes made by the post install script. \n\n```\npip uninstall cqlsh-expansion\n```\n\n### New output for TTY\n\nWhen creating a new cqlsh session with the cqlsh-expansion utility, it will show the default consistency level after establishing a new connection. We find customers using cqlsh may not be aware of the default consistency level of `ONE`, and additional transparency will lead to better operational excellence.\n\n### COPY FROM/TO required Consistency Levels\n\nWhen executing the `COPY FROM` import operation from the cqlsh-expansion utility, `LOCAL_QUORUM` will be strictly enforced. Executing `COPY FROM` with consistency level other than LOCAL_QUORUM will result in an SyntaxError. This restriction is to provide better experience when using `COPY FROM` with Amazon Keyspaces. Amazon Keyspaces replicates all write operations three times across multiple Availability Zones for durability and high availability. Writes are durably stored before they are acknowledged using the `LOCAL_QUORUM` consistency level.\nWhen executing the `COPY TO` export operation from the cqlsh-expansion utility, consistency of `ONE, LOCAL_ONE, or LOCAL_QUORUM` will be strictly enforced. Executing `COPY FROM` with consistency level other than these three will result in an SyntaxError. This restriction is to provide better experience when using `COPY FROM` with Amazon Keyspaces. \n\n### Contributing:\n\n```\n\n# Security\n\nSee [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.\n\n# License\n\nThis library is licensed under the MIT-0 License. See the LICENSE file.\n```\n\n",
"bugtrack_url": null,
"license": "",
"summary": "The cqlsh-expansion utility extends native cqlsh functionality to include cloud native capabilities",
"version": "0.9.6",
"project_urls": {
"Homepage": "https://github.com/aws-samples/amazon-keyspaces-toolkit/tree/master/cqlsh-expansion"
},
"split_keywords": [
"cql",
"cqlsh",
"cqlsh-expansion",
"aws",
"keyspaces",
"cassandra",
"sigv4"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e3e52a0d6b0edd5d14376fee92cf71e553bb94cdd724161f39d9a27daa730713",
"md5": "d4b0ae71b6184b75e6fcc92d528cab86",
"sha256": "8071c5781dd32385bad57fd9d05ae2ac7b1ae6ca9a0f5537bba803197cccb508"
},
"downloads": -1,
"filename": "cqlsh_expansion-0.9.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d4b0ae71b6184b75e6fcc92d528cab86",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 153734,
"upload_time": "2023-08-23T21:08:14",
"upload_time_iso_8601": "2023-08-23T21:08:14.813881Z",
"url": "https://files.pythonhosted.org/packages/e3/e5/2a0d6b0edd5d14376fee92cf71e553bb94cdd724161f39d9a27daa730713/cqlsh_expansion-0.9.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8f34a1e5e00e9fa5b40e2b5092188b3ba9919fd3d3fd95a161d19701ad3f1f49",
"md5": "5ad2697f28e29c998a398229089e7c23",
"sha256": "79ae5ec3b685d7d25c773a0c80baef963d060bfc0b7db22c0012ca471713e834"
},
"downloads": -1,
"filename": "cqlsh-expansion-0.9.6.tar.gz",
"has_sig": false,
"md5_digest": "5ad2697f28e29c998a398229089e7c23",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 144391,
"upload_time": "2023-08-23T21:08:17",
"upload_time_iso_8601": "2023-08-23T21:08:17.041757Z",
"url": "https://files.pythonhosted.org/packages/8f/34/a1e5e00e9fa5b40e2b5092188b3ba9919fd3d3fd95a161d19701ad3f1f49/cqlsh-expansion-0.9.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-23 21:08:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aws-samples",
"github_project": "amazon-keyspaces-toolkit",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "cqlsh-expansion"
}
JSON
