TLS 认证#

Ray 可以配置在其 gRPC 通道上使用 TLS。这意味着连接到 Ray Head 将需要一套合适的凭证，并且各种进程（客户端、Head、Worker）之间交换的数据将是加密的（Ray 文档）。

本文档提供了为 KubeRay 配置生成公私钥对和 CA 证书的详细说明。

警告：启用 TLS 将会因额外的双向认证和加密开销而导致性能下降。测试表明，对于小规模工作负载，这种开销很大，而对于大规模工作负载，开销则相对较小。确切的开销将取决于您的工作负载的性质。

先决条件#

为了完全理解本文档，强烈建议您对以下概念有扎实的理解：

  • 私钥/公钥

  • CA（证书颁发机构）

  • CSR（证书签名请求）

  • 自签名证书

此YouTube 视频是一个不错的起点。

简而言之#

请注意，本文档旨在支持 KubeRay 版本 0.5.0 或更高版本。如果您使用的是旧版本的 KubeRay，某些说明或配置可能不适用或需要进行额外修改。

警告：请注意，ray-cluster.tls.yaml 文件仅用于演示目的。在生产环境中，您绝不应将 CA 私钥存储在 Kubernetes Secret 中。

# Install KubeRay operator
# `ray-cluster.tls.yaml` will cover from Step 1 to Step 3

# Download `ray-cluster.tls.yaml`
curl -LO https://raw.githubusercontent.com/ray-project/kuberay/v1.5.1/ray-operator/config/samples/ray-cluster.tls.yaml

# Create a RayCluster
kubectl apply -f ray-cluster.tls.yaml

# Jump to Step 4 "Verify TLS authentication" to verify the connection.

ray-cluster.tls.yaml 将创建

  • 一个包含 CA 私钥（ca.key）和自签名证书（ca.crt）的 Kubernetes Secret（步骤 1）。

  • 一个包含脚本 gencert_head.sh 和 gencert_worker.sh 的 Kubernetes ConfigMap，这些脚本允许 Ray Pod 生成私钥（tls.key）和自签名证书（tls.crt）（步骤 2）。

  • 一个带有正确 TLS 环境变量配置的 RayCluster（步骤 3）。

Ray Pod 的证书（tls.crt）使用 CA 的私钥（ca.key）进行加密。此外，所有 Ray Pod 都包含 CA 的公钥 ca.crt，这允许它们解密其他 Ray Pod 的证书。

步骤 1：为 CA 生成私钥和自签名证书#

在本文档中，使用了自签名证书，但用户也可以选择为 TLS 认证选择一个公开受信任的证书颁发机构 (CA)。

# Step 1-1: Generate a self-signed certificate and a new private key file for CA.
openssl req -x509 \
            -sha256 -days 3650 \
            -nodes \
            -newkey rsa:2048 \
            -subj "/CN=*.kuberay.com/C=US/L=San Francisco" \
            -keyout ca.key -out ca.crt

# Step 1-2: Check the CA's public key from the self-signed certificate.
openssl x509 -in ca.crt -noout -text

# Step 1-3
# Method 1: Use `cat $FILENAME | base64` to encode `ca.key` and `ca.crt`.
#           Then, paste the encoding strings to the Kubernetes Secret in `ray-cluster.tls.yaml`.

# Method 2: Use kubectl to encode the certificate as Kubernetes Secret automatically.
#           (Note: You should comment out the Kubernetes Secret in `ray-cluster.tls.yaml`.)
kubectl create secret generic ca-tls --from-file=ca.key --from-file=ca.crt

  • ca.key：CA 的私钥

  • ca.crt：CA 的自签名证书

此步骤是可选的，因为 ca.key 和 ca.crt 文件已包含在 ray-cluster.tls.yaml 中指定的 Kubernetes Secret 里。

步骤 2：为 Ray Pod 创建单独的私钥和自签名证书#

在 ray-cluster.tls.yaml 中，每个 Ray Pod（Head 和 Worker）在其 init 容器中生成自己的私钥文件（tls.key）和自签名证书文件（tls.crt）。我们为每个 Pod 生成单独的文件是因为 Worker Pod 没有确定的 DNS 名称，我们无法在不同的 Pod 之间使用相同的证书。

在 YAML 文件中，您会找到一个名为 tls 的 ConfigMap，其中包含两个 shell 脚本：gencert_head.sh 和 gencert_worker.sh。这些脚本用于为 Ray Head 和 Worker Pod 生成私钥和自签名证书文件（tls.key 和 tls.crt）。另一种方法是，用户可以将 shell 脚本直接预先编译到 init 容器使用的 docker 镜像中，而不是依赖 ConfigMap。

下面是对这些脚本中每个脚本所执行操作的简要说明：

  1. 生成一个 2048 位的 RSA 私钥，并保存为 /etc/ray/tls/tls.key。

  2. 使用私钥文件（tls.key）和 csr.conf 配置文件生成证书签名请求 (CSR)。

  3. 使用证书颁发机构 (CA) 的私钥（ca.key）和先前生成的 CSR 生成自签名证书（tls.crt）。

gencert_head.sh 和 gencert_worker.sh 之间的唯一区别在于 csr.conf 和 cert.conf 中的 [ alt_names ] 部分。Worker Pod 使用 Head Kubernetes 服务的完全限定域名 (FQDN) 来建立与 Head Pod 的连接。因此，Head Pod 的 [alt_names] 部分需要包含 Head Kubernetes 服务的 FQDN。顺便说一句，Head Pod 使用 $POD_IP 与 Worker Pod 通信。

# gencert_head.sh
[alt_names]
DNS.1 = localhost
DNS.2 = $FQ_RAY_IP
IP.1 = 127.0.0.1
IP.2 = $POD_IP

# gencert_worker.sh
[alt_names]
DNS.1 = localhost
IP.1 = 127.0.0.1
IP.2 = $POD_IP

在 Kubernetes 网络模型中，Pod 看到的 IP 与其他人看到的 IP 是相同的。这就是为什么 Ray Pod 可以自我注册证书的原因。

步骤 3：为 Ray TLS 认证配置环境变量#

要在 Ray 集群中启用 TLS 认证，请设置以下环境变量：

  • RAY_USE_TLS：1 或 0，用于启用/禁用 TLS。如果设置为 1，则以下所有环境变量都必须设置。默认为：0。

  • RAY_TLS_SERVER_CERT：证书文件的位置，该文件将呈现给其他端点以实现双向认证（即 tls.crt）。

  • RAY_TLS_SERVER_KEY：私钥文件的位置，它是证明您是给定证书的授权用户的加密手段（即 tls.key）。

  • RAY_TLS_CA_CERT：CA 证书文件的位置，它允许 TLS 判断一个端点的证书是否由正确的机构签名（即 ca.crt）。

有关如何使用 TLS 认证配置 Ray 的更多信息，请参阅 Ray 的文档。

步骤 4：验证 TLS 认证#

# Log in to the worker Pod
kubectl exec -it ${WORKER_POD} -- bash

# Since the head Pod has the certificate of $FQ_RAY_IP, the connection to the worker Pods
# will be established successfully, and the exit code of the ray health-check command
# should be 0.
ray health-check --address $FQ_RAY_IP:6379
echo $? # 0

# Since the head Pod has the certificate of $RAY_IP, the connection will fail and an error
# message similar to the following will be displayed: "Peer name raycluster-tls-head-svc is
# not in peer certificate".
ray health-check --address $RAY_IP:6379

# If you add `DNS.3 = $RAY_IP` to the [alt_names] section in `gencert_head.sh`,
# the head Pod will generate the certificate of $RAY_IP.
#
# For KubeRay versions prior to 0.5.0, this step is necessary because Ray workers in earlier
# versions use $RAY_IP to connect with Ray head.