使用 cqlsh 连接 Amazon Keyspaces - Amazon Keyspaces（Apache Cassandra 兼容）
使用cqlsh-expansion如何为 TLS 手动配置 cqlsh 连接
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 的平台上安装。

有关 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
    pip3 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 DEFAULT=${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 Keyspaces 创建和配置 Amazon 凭证。

    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 出站规则的更多信息，请参阅《适用于 Linux 实例的 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 表。

      为用户创建服务特定凭证和权限后，您必须更新 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. 使用以下命令下载 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