cql-proxy

目录

• 什么是cql-proxy?
• 何时使用cql-proxy
• 配置
• 入门
  • 本地构建和运行
  • 运行cql-proxy docker镜像
  • 使用Kubernetes
• 已知问题
  • 基于令牌的负载均衡

什么是cql-proxy?

cql-proxy旨在将应用程序的CQL流量转发到适当的数据库服务。它监听本地地址并安全地转发流量。

何时使用cql-proxy

cql-proxy边车使不受支持的CQL驱动程序能够与DataStax Astra一起工作。这些驱动程序包括DataStax的旧版[驱动程序]和社区维护的CQL驱动程序，如gocql驱动程序和rust-driver。

cql-proxy还使当前使用Apache Cassandra或DataStax Enterprise (DSE)的应用程序能够使用Astra而无需任何代码更改。只需将应用程序配置为使用代理即可。

如果您正在使用DataStax [驱动程序]构建新应用程序，则不需要cql-proxy，因为驱动程序可以直接与Astra通信。DataStax驱动程序对Astra有出色的开箱即用支持，并在driver-guide指南中有详细的文档。

配置

使用-h或--help标志显示所有标志及其相应的描述和环境变量（下面显示为以$开头的项）列表：

$ ./cql-proxy -h
用法: cql-proxy

标志:
  -h, --help                                              显示上下文相关的帮助。
  -b, --astra-bundle=STRING                               Astra数据库的安全连接包路径。需要'--username'和'--password'。如果使用令牌或联系点选项则忽略($ASTRA_BUNDLE)。
  -t, --astra-token=STRING                                用于向Astra数据库进行身份验证的令牌。需要'--astra-database-id'。如果使用包路径或联系点选项则忽略($ASTRA_TOKEN)。
  -i, --astra-database-id=STRING                          Astra数据库的数据库ID。需要'--astra-token'($ASTRA_DATABASE_ID)
      --astra-api-url="https://api.astra.datastax.com"    Astra API的URL($ASTRA_API_URL)
      --astra-timeout=10s                                 检索包和元数据时联系Astra的超时时间($ASTRA_TIMEOUT)
  -c, --contact-points=CONTACT-POINTS,...                 集群的联系点。如果使用包路径或令牌选项则忽略($CONTACT_POINTS)。
  -u, --username=STRING                                   用于身份验证的用户名($USERNAME)
  -p, --password=STRING                                   用于身份验证的密码($PASSWORD)
  -r, --port=9042                                         连接到集群时使用的默认端口($PORT)
  -n, --protocol-version="v4"                             连接到后端集群时使用的初始协议版本(默认: v4, 选项: v3, v4, v5, DSEv1, DSEv2) ($PROTOCOL_VERSION)
  -m, --max-protocol-version="v4"                         后端集群支持的最大协议版本(默认: v4, 选项: v3, v4, v5, DSEv1, DSEv2) ($MAX_PROTOCOL_VERSION)
  -a, --bind=":9042"                                      用于绑定服务器的地址($BIND)
  -f, --config=CONFIG                                     YAML配置文件($CONFIG_FILE)
      --debug                                             显示调试日志($DEBUG)
      --health-check                                      启用活性和就绪性检查($HEALTH_CHECK)
      --http-bind=":8000"                                 用于绑定HTTP服务器的地址，用于健康检查($HTTP_BIND)
      --heartbeat-interval=30s                            对集群执行心跳的间隔($HEARTBEAT_INTERVAL)
      --idle-timeout=60s                                  成功心跳之间的持续时间，超过此时间后与集群的连接被视为无响应并关闭($IDLE_TIMEOUT)
      --readiness-timeout=30s                             代理无法连接到后端集群的持续时间，超过此时间后被视为未就绪($READINESS_TIMEOUT)
      --idempotent-graph                                  如果为true，将默认将所有图查询视为幂等并自动重试。重试某些图查询可能很危险 -- 请谨慎使用($IDEMPOTENT_GRAPH)。
      --num-conns=1                                       创建到后端集群的每个节点的连接数($NUM_CONNS)
      --proxy-cert-file=STRING                            PEM编码证书文件的路径，包含其中间证书链。用于加密代理客户端的流量($PROXY_CERT_FILE)
      --proxy-key-file=STRING                             PEM编码私钥文件的路径。用于加密代理客户端的流量($PROXY_KEY_FILE)
      --rpc-address=STRING                                在'system.local'表中为'rpc_address'广告的地址。如果配置对等代理，则必须设置($RPC_ADDRESS)
      --data-center=STRING                                系统表中使用的数据中心($DATA_CENTER)
      --tokens=TOKENS,...                                 系统表中使用的令牌。不推荐使用($TOKENS)

要向cql-proxy传递配置，可以使用命令行标志、环境变量或配置文件。以docker方法为例，以下示例展示了如何使用每种方法定义令牌和数据库ID。

使用标志

docker run -p 9042:9042 \
  --rm datastax/cql-proxy:v0.1.5 \
  --astra-token <astra-token> --astra-database-id <astra-datbase-id>

使用环境变量

docker run -p 9042:9042  \
  --rm datastax/cql-proxy:v0.1.5 \
  -e ASTRA_TOKEN=<astra-token> -e ASTRA_DATABASE_ID=<astra-datbase-id>

使用配置文件

代理设置也可以使用--config /path/to/proxy.yaml标志通过配置文件传递。这可以与命令行标志和环境变量混合使用。以下是一些示例配置文件：

contact-points:
  - 127.0.0.1
username: cassandra
password: cassandra
port: 9042
bind: 127.0.0.1:9042
# ...

或使用Astra令牌：

astra-token: <astra-token>
astra-database-id: <astra-database-id>
bind: 127.0.0.1:9042
# ...

所有配置键都与其命令行标志对应，例如--astra-bundle对应astra-bundle:，--contact-points对应contact-points:等。

设置对等代理

具有数据中心感知负载均衡策略的多区域故障转移是多代理设置最有用的情况。

配置peers:时，每个代理必须设置--rpc-address（或yaml中的rpc-address:），并且必须与其对应的peers:条目匹配。此外，peers:只能在配置文件中设置，不能使用命令行标志设置。

多区域设置

以下是配置具有两个代理的多区域故障转移的示例。每个区域的集群都启动一个代理，使用该区域的包连接到集群。它们都共享一个包含完整代理列表的通用配置文件。

*注意：*多区域设置仅支持包。

cql-proxy --astra-bundle astra-region1-bundle.zip --username token --password <astra-token> \
  --bind 127.0.0.1:9042 --rpc-address 127.0.0.1 --data-center dc-1 --config proxy.yaml

cql-proxy ---astra-bundle astra-region2-bundle.zip --username token --password <astra-token> \
  --bind 127.0.0.2:9042 --rpc-address 127.0.0.2 --data-center dc-2 --config proxy.yaml

对等设置使用yaml文件配置。明确提供--data-center标志是个好主意，否则；这些值将从后端集群中提取，需要从system.local和system.peers表中提取以正确设置对等的data-center:值。以下是proxy.yaml的示例：

peers:
  - rpc-address: 127.0.0.1
    data-center: dc-1
  - rpc-address: 127.0.0.2
    data-center: dc-2

注意：peers:包含当前代理自身的条目是可以的，因为它们会被忽略。

入门

使用cql-proxy有三种方法：

• 本地构建和运行cql-proxy
• 运行安装了cql-proxy的docker镜像
• 使用Kubernetes容器运行cql-proxy

本地构建和运行

1. 构建cql-proxy。

   go build
   

2. 使用您想要的数据库运行。

   • DataStax Astra集群：

     ./cql-proxy --astra-token <astra-token> --astra-database-id <astra-database-id>
     

     可以使用这些[说明]生成<astra-token>。代理还支持使用Astra安全连接包以及使用这些[说明]生成的客户端ID和密钥：

     ./cql-proxy --astra-bundle <your-secure-connect-zip> \
     --username <astra-client-id> --password <astra-client-secret>
     

   • Apache Cassandra集群：

     ./cql-proxy --contact-points <集群节点IP或DNS名称> [--username <用户名>] [--password <密码>]
     

运行cql-proxy docker镜像

1. 使用您想要的数据库运行。

   • DataStax Astra集群：

docker run -p 9042:9042 \
  datastax/cql-proxy:v0.1.5 \
  --astra-token <astra-token> --astra-database-id <astra-database-id>

可以使用这些[说明]生成 <astra-token>。代理还支持使用 Astra 安全连接包，但需要将包挂载到容器中的卷：

docker run -v <your-secure-connect-bundle.zip>:/tmp/scb.zip -p 9042:9042 \
--rm datastax/cql-proxy:v0.1.5 \
--astra-bundle /tmp/scb.zip --username <astra-client-id> --password <astra-client-secret>

• Apache Cassandra 集群：

docker run -p 9042:9042 \
  datastax/cql-proxy:v0.1.5 \
  --contact-points <集群节点IP或DNS名称> [--username <用户名>] [--password <密码>]

如果您希望在使用完毕后删除 Docker 镜像，请在镜像名称 datastax/cql-proxy:v0.1.5 之前添加 --rm。

使用 Kubernetes

在 Kubernetes 中使用 cql-proxy 需要以下几个步骤：

1. 按照 Astra 说明生成令牌。此步骤将显示您的客户端 ID、客户端密钥和令牌；确保下载这些信息以备下一步使用。将安全包存储在 /tmp/scb.zip 中以匹配下面的示例。

2. 创建 cql-proxy.yaml。您需要添加三组信息：参数、卷挂载和卷。完整示例可以在这里找到。

• 参数：修改本地包位置、用户名和密码，使用上一步获得的客户端 ID 和客户端密钥作为容器参数。

  command: ["./cql-proxy"]
  args: ["--astra-bundle=/tmp/scb.zip","--username=Client ID","--password=Client Secret"]
  

• 卷挂载：根据需要修改 /tmp/ 作为卷挂载。

  volumeMounts:
    - name: my-cm-vol
    mountPath: /tmp/
  

• 卷：根据需要修改 configMap 文件名。在此示例中，它被命名为 cql-proxy-configmap。对 volumes 使用与 volumeMounts 相同的名称。

  volumes:
    - name: my-cm-vol
      configMap:
        name: cql-proxy-configmap        
  

3. 创建配置映射。使用在 cql-proxy.yaml 中指定的相同安全包。

   kubectl create configmap cql-proxy-configmap --from-file /tmp/scb.zip 
   

4. 检查创建的配置映射。

   kubectl describe configmap cql-proxy-configmap
     
     Name:         cql-proxy-configmap
     Namespace:    default
     Labels:       <none>
     Annotations:  <none>
   
     Data
     ====
   
     BinaryData
     ====
     scb.zip: 12311 bytes
   

5. 使用您创建的 YAML 文件创建 Kubernetes 部署：

   kubectl create -f cql-proxy.yaml
   

6. 检查日志：

   kubectl logs <部署名称>
   

已知问题

令牌感知负载均衡

使用令牌感知负载均衡的驱动程序在使用 cql-proxy 时可能会打印警告或无法工作。因为 cql-proxy 将后端集群抽象为单个端点，这与期望集群中至少有"复制因子"数量节点的令牌感知驱动程序不太兼容。许多驱动程序会打印一个警告（可以忽略）并回退到类似轮询的方式，但其他驱动程序可能会因错误而失败。对于因错误而失败的驱动程序，需要禁用令牌感知或配置轮询负载均衡策略。