View a markdown version of this page

使用 cqlsh 连接 Amazon Keyspaces - Amazon Keyspaces（Apache Cassandra 兼容）
使用 cqlsh-expansion如何为 TLS 手动配置 cqlsh 连接

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

使用 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-expansion 的推荐分区程序。cqlsh-expansion 不支持 Amazon Keyspaces DefaultPartitioner。有关更多信息，请参阅 使用 Amazon Keyspaces 中的分区程序。

有关 cqlsh 的一般信息，请参阅 cqlsh：CQL Shell。

使用 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. 将合并后的证书文件复制到.cassandra目录中。Amazon Keyspaces 使用此证书通过传输层安全性协议 (TLS) 配置安全连接。传输中加密可在数据进出 Amazon Keyspaces 时对其进行加密，从而提供额外一层数据保护。有关证书的更多信息，请参阅如何为 TLS 手动配置 cqlsh 连接。

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

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

    cqlsh-expansion.init
    注意

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

使用 cqlsh-expansion 连接 Amazon Keyspaces

  1. 配置您的 AWS 区域 并将其添加为用户环境变量。

    要在基于 Unix 的系统上将默认区域添加为环境变量，您可以运行以下命令。在这个例子中，我们使用us-east-1。

    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 Keyspaces 创建和配置 AWS 证书。

    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

      要详细了解如何设置环境变量（包括其他平台），请参阅如何设置环境变量。

      注意

      如果您从 Amazon EC2 实例进行连接，则还需要在安全组中配置一条出站规则，允许流量从该实例流入 Amazon Keyspaces。有关如何查看和编辑 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 目录。

如何为 TLS 手动配置 cqlsh 连接

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

如果要下载证书并手动配置连接，则可以使用以下步骤进行操作。

  1. 下载以下数字证书并将文件保存在本地或您的主目录中。

    1. AmazonRootCA1

    2. AmazonRootCA2

    3. AmazonRootCA3

    4. AmazonRootCA4

    5. Starfield Class 2 Root（可选 — 为了向后兼容）

    要下载证书，您可以使用以下命令。

    curl -O https://www.amazontrust.com/repository/AmazonRootCA1.pem
curl -O https://www.amazontrust.com/repository/AmazonRootCA2.pem
curl -O https://www.amazontrust.com/repository/AmazonRootCA3.pem
curl -O https://www.amazontrust.com/repository/AmazonRootCA4.pem
curl -O https://certs.secureserver.net/repository/sf-class2-root.crt
    注意

    Amazon Keyspaces 之前使用锚定在 Starfield Class 2 CA 上的 TLS 证书。 AWS 正在将所有证书全部迁移 AWS 区域 到根据亚马逊信任服务（Amazon 根 CA 1—4）颁发的证书。在此过渡期间，将客户端配置为同时信任 Amazon 根 CA 1—4 和 Starfield 根，以确保所有区域之间的兼容性。

  2. 将所有下载的证书合并到一个pem文件中，其名称与我们的示例keyspaces-bundle.pem中的名称相同。您可以使用以下 命令进行这项操作：记下文件的路径，稍后需要这个。

    cat AmazonRootCA1.pem \
 AmazonRootCA2.pem \
 AmazonRootCA3.pem \
 AmazonRootCA4.pem \
 sf-class2-root.crt \
 > keyspaces-bundle.pem

  3. 打开 Cassandra 主目录下的 cqlshrc 配置文件（例如 ${HOME}/.cassandra/cqlshrc），然后添加以下行。

    [connection]
port = 9142
factory = cqlshlib.ssl.ssl_transport_factory

[ssl]
validate = true
certfile =  path_to_file/keyspaces-bundle.pem