使用 cqlsh 连接 Amazon Keyspaces - Amazon Keyspaces(Apache Cassandra 兼容)
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

使用 cqlsh 连接 Amazon Keyspaces

要使用 cqlsh 连接 Amazon Keyspaces,您可以使用 cqlsh-expansion。该工具包包含常用的 Apache Cassandra 工具(例如 cqlsh 和帮助程序),能够对 Amazon Keyspaces 进行预配置,同时保持与 Apache Cassandra 的完全兼容。cqlsh-expansion集成了 SigV4 身份验证插件,允许您使用IAM访问密钥而不是用户名和密码进行连接。您只需安装 cqlsh 脚本即可建立连接,无需安装完整的 Apache Cassandra 发行版,因为 Amazon Keyspaces 是无服务器的。这一轻量级安装包包括 cqlsh-expansion 和经典 cqlsh 脚本,可以在任何支持 Python 的平台上安装。

注意

Murmur3Partitioner是 Amazon Keyspaces 和. 的推荐分区器。cqlsh-expansioncqlsh-expansion不支持 Amazon Key DefaultPartitioner spaces。有关更多信息,请参阅 使用 Amazon Keyspaces 中的分区程序

有关的一般信息cqlsh,请参阅 cqlsh:外CQL壳

使用 cqlsh-expansion 连接 Amazon Keyspaces

安装和配置 cqlsh-expansion
  1. 要安装 cqlsh-expansion Python 软件包,您可以运行 pip 命令。该命令将使用 pip 安装在您的设备上安装 cqlsh-expansion 脚本以及一个包含依赖项列表的文件。--user flag 会告诉 pip 使用 Python 用户为平台安装目录。在基于 Unix 的系统上,应安装 ~/.local/ 目录。

    您需要使用 Python 3 来安装 cqlsh-expansion,要弄清楚您的 Python 版本,可使用 Python --version。要进行安装,可以运行以下命令。

    python3 -m pip install --user cqlsh-expansion

    输出应如下所示:

    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

    如果安装目录不在中PATH,则需要按照操作系统的说明进行添加。以下是 Ubuntu Linux 的一个示例。

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

    要确认软件包已安装,可以运行以下命令。

    cqlsh-expansion --version

    输出应如下所示:

    cqlsh 6.1.0
  2. 要配置 cqlsh-expansion,您可以运行安装后脚本来自动完成以下步骤:

    1. 在用户主目录下创建 .cassandra 目录(如果该目录尚不存在)。

    2. 将预配置的 cqlshrc 配置文件复制到 .cassandra 目录。

    3. 将 Starfield 数字证书复制到 .cassandra 目录。Amazon Keyspaces 使用此证书配置与传输层安全 () TLS 的安全连接。传输中加密可在数据进出 Amazon Keyspaces 时对其进行加密,从而提供额外一层数据保护。

    要先查看脚本,您可以访问 post_install.py 中的 Github 代码库中。

    要使用脚本,您可以运行以下命令。

    cqlsh-expansion.init
    注意

    使用 pip uninstall 卸载 cqlsh-expansion 时,安装后脚本创建的目录和文件不会随之删除,必须要手动删除。

使用 cqlsh-expansion 连接 Amazon Keyspaces
  1. 配置你的 Amazon Web Services 区域 并将其添加为用户环境变量。

    要在基于 Unix 的系统上将默认区域添加为环境变量,可以运行以下命令。在本示例中,我们使用的是美国东部(弗吉尼亚州北部)。

    export AWS_DEFAULT_REGION=us-east-1

    要详细了解如何设置环境变量(包括其他平台),请参阅如何设置环境变量

  2. 找到您的服务端点。

    为您的区域选择合适的服务端点。要查看 Amazon Keyspaces 的可用端点,请参阅 Amazon Keyspaces 的服务端点。在本示例中,我们使用的端点是 cassandra.us-east-1.amazonaws.com

  3. 配置身份验证方法。

    为了增强安全性,推荐使用IAM访问密钥(IAM用户、角色和联合身份)进行连接。

    在IAM使用访问密钥进行连接之前,您需要完成以下步骤:

    1. 创建IAM用户,或者遵循最佳实践并创建IAM用户可以IAM扮演的角色。有关如何创建IAM访问密钥的更多信息,请参阅创建和配置 Amazon Amazon Keyspaces 的凭证

    2. 创建一项IAM策略,向角色(或IAM用户)授予对 Amazon Keyspaces 的至少只读访问权限。有关IAM用户或角色连接到 Amazon Keyspaces 所需的权限的更多信息,请参阅。访问 Amazon Keyspaces 表

    3. 将用户的访问密钥添加到IAM用户的环境变量中,如以下示例所示。

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

      要详细了解如何设置环境变量(包括其他平台),请参阅如何设置环境变量

      注意

      如果您从亚马逊EC2实例进行连接,则还需要在安全组中配置出站规则,允许从该实例到亚马逊密钥空间的流量。有关如何查看和编辑EC2出站规则的更多信息,请参阅 Amazon EC2 用户指南中的向安全组添加规则

  4. 使用 cqlsh-expansion 和 SigV4 身份验证连接到 Amazon Keyspaces。

    要使用 cqlsh-expansion 连接到 Amazon Keyspaces,您可以使用以下命令。确保将服务端点替换为您所在区域的正确端点。

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

    如果连接成功,您应该会看到类似于以下内容的输出:

    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>

    如果您遇到连接错误,请参见我无法使用 cqlsh 连接到 Amazon Keyspaces以获取故障排除信息。

    • 使用服务特定凭证连接 Amazon Keyspaces。

      要使用 Cassandra 用于身份验证的传统用户名和密码组合进行连接,您必须首先为 Amazon Keyspaces 创建服务特定凭证,如创建特定于服务的凭证,以便以编程方式访问 Amazon Keyspaces中所述。您还必须向该用户授予访问 Amazon Keyspaces 的权限,更多信息请参阅访问 Amazon Keyspaces 表

      为用户创建服务特定凭证和权限后,您必须更新 cqlshrc 文件,该文件通常位于用户目录路径 ~/.cassandra/ 中。在 cqlshrc 文件中,转到 Cassandra [authentication] 部分,使用 ";" 字符注释掉 [auth_provider] 下的 SigV4 模块和类,如以下示例所示。

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

      更新 cqlshrc 文件后,您可以使用以下命令通过服务特定凭证连接 Amazon Keyspaces。

      cqlsh-expansion cassandra.us-east-1.amazonaws.com 9142 -u myUserName -p myPassword --ssl
清理
  • 要删除 cqlsh-expansion 软件包,您可以使用 pip uninstall 命令。

    pip3 uninstall cqlsh-expansion

    pip3 uninstall 命令不会删除安装后脚本创建的目录和相关文件。要删除安装后脚本创建的文件夹和文件,您可以删除 .cassandra 目录。

如何手动配置cqlsh连接 TLS

Amazon Keyspaces 仅接受使用传输层安全 () TLS 的安全连接。您可以使用 cqlsh-expansion 实用程序自动下载证书并安装预配置的 cqlshrc 配置文件。有关更多信息,请参阅本页上的使用 cqlsh-expansion 连接 Amazon Keyspaces

如果要下载证书并手动配置连接,您可以使用以下步骤。

  1. 使用以下命令下载 Starfield 数字证书,并将 sf-class2-root.crt 保存在本地或您的主目录中。

    curl https://certs.secureserver.net/repository/sf-class2-root.crt -O
    注意

    您还可以使用 Amazon 数字证书连接到 Amazon Keyspaces。如果您的客户端成功连接到 Amazon Keyspaces,您可以继续这样做。Starfield 证书为使用旧证书颁发机构的客户端提供了额外的向后兼容性。

  2. 打开 Cassandra 主目录下的 cqlshrc 配置文件(例如 ${HOME}/.cassandra/cqlshrc),然后添加以下行。

    [connection] port = 9142 factory = cqlshlib.ssl.ssl_transport_factory [ssl] validate = true certfile = path_to_file/sf-class2-root.crt