在 Kubernetes 上创建使用 TLS 加密的部署

Spanner Omni 使用 TLS 1.3 加密客户端与服务器之间以及 Spanner Omni 服务器之间的数据流。 Spanner Omni 提供 mTLS 以增强安全性，双方在交换任何数据之前都会确定对方的真实性。如果您使用加密，则服务器必须通过 mTLS 进行通信。您可以选择客户端和服务器是否也使用 mTLS。

Spanner Omni 的预览版不支持 TLS 加密，并且会在您创建部署 90 天后停止写入数据。如需提前使用具有完整功能的版本，请与 Google 联系。

准备工作

确保您满足以下要求：

创建一个 Kubernetes 集群。该配置支持 Google Kubernetes Engine (GKE) 和 Amazon Elastic Kubernetes Service (Amazon EKS)。您可能需要自定义配置才能在其他环境中运行。
确保 Kubernetes 集群可以访问托管 Spanner Omni 容器的 Artifact Registry 制品。
安装和配置 kubectl命令行工具和 Helm。
如果您在 vSphere 虚拟化平台机器上设置 Kubernetes 环境，请将 monitor_control.virtual_rdtsc = FALSE 添加到虚拟机的 .vmx 配置文件中，以停用时间戳计数器 (TSC) 虚拟化。这可确保 TrueTime 正常运行。
验证您的环境是否满足 Spanner Omni 系统要求。

第 1 步：生成证书

您必须创建三组证书：

API 证书：这些证书有助于保护 Spanner Omni API 服务器。
服务器证书：这些证书有助于保护服务器间通信。
客户端证书：最终用户或应用使用这些证书来确定其身份并与 Spanner Omni 服务器建立信任关系。

这些证书由证书授权机构 (CA) 颁发。 Spanner Omni 提供了用于创建自签名 CA 和所有三种类型证书的工具。

在您的某台机器上执行以下步骤。这些步骤假定命名空间为 spanner-ns。请将其更改为您打算在部署中使用的命名空间。

您可以使用 Spanner Omni CLI 在工作站上创建这些证书。

1. 创建证书授权机构 (CA)

所有证书均由证书授权机构 (CA) 颁发。您的组织可能有一个中央 CA，或者您可以使用公共 CA。虽然您可以对所有证书使用相同的 CA，但 API 证书和客户端证书必须使用相同的 CA。

Spanner Omni 可让您创建私有 CA。

./google/spanner/bin/spanner certificates create-ca --ca-certificate-directory=certs

create-ca 命令会在 certs 目录中生成 CA 证书。您可以复制此证书以用作 API 证书的 CA，也可以创建其他 CA。请确保在创建证书时使用正确的 CA。

cp certs/ca.crt certs/ca-api.crt

目录 $HOME/.spanner/private-keys 包含 CA 的私钥。备份和保护此目录至关重要。有权访问私钥的用户可以签署客户端信任自签名 CA 的任意证书。（可选）您可以为 API 证书创建额外的 CA（或使用外部受信任的 CA）。本文档对所有类型的证书使用相同的 CA。

2. 生成服务器证书

您必须生成两种类型的服务器证书：

API 证书：使用此证书加密与部署交互的系统的通信。
Spanner 服务器证书：Spanner Omni 服务器使用此证书来加密彼此之间的通信。

此配置在管理这些证书方面提供了灵活性。例如，它允许您使用证书轮替。

创建 Spanner 服务器证书

如需创建服务器证书，请运行以下命令：

# Comma-separate names of the Spanner servers; wildcards are supported.
SERVER_NAMES=*.pod.NAMESPACE
./google/spanner/bin/spanner certificates create-server --hostnames=${SERVER_NAMES} --ca-certificate-directory certs --output-directory certs

此命令会在 certs 目录中创建 server.crt 和 server.key。

创建 API 证书

如需创建 API 证书，请运行以下命令：

OMNI_ENDPOINT=spanner.NAMESPACE
./google/spanner/bin/spanner certificates create-server --filename-prefix=api --hostnames=${OMNI_ENDPOINT} --ca-certificate-directory certs --output-directory certs

此命令会在 certs 目录中创建 api.crt 和 api.key。如有必要，请为 API 证书使用外部受信任的 CA。

3. 生成客户端证书

您可以使用客户端证书对用户和应用进行身份验证。客户端证书可在客户端和服务器之间启用 mTLS。如果您不打算使用 mTLS，则可以跳过此步骤。

签署 API 证书的 CA 必须签署客户端证书，客户端证书还必须包含用于授权的用户名。在此示例中，请使用 admin 用户，这是每个新数据库的默认用户。如需了解详情，请参阅 Spanner Omni 中的身份验证和授权。

USERNAME=admin
./google/spanner/bin/spanner certificates create-client $USERNAME --output-directory clientcerts --ca-certificate-directory certs

此命令会在 clientcerts 目录中创建 client.crt 和 client.key。将这些文件发送到连接到部署的任何机器。

如果您打算将客户端证书与 Java 客户端库搭配使用，则必须以 PKCS#8 格式生成证书密钥。请使用以下命令：

USERNAME=admin
./google/spanner/bin/spanner certificates create-client $USERNAME --output-directory clientcerts --ca-certificate-directory certs --generate-pkcs8-key

第 2 步：将证书推送到 Kubernetes 集群

运行以下命令，将证书推送到 Kubernetes 集群：

kubectl create namespace NAMESPACE

kubectl create secret generic tls-certs \
  --from-file=ca.crt="certs/ca.crt" \
  --from-file=ca-api.crt="certs/ca-api.crt" \
  --from-file=server.crt="certs/server.crt" \
  --from-file=server.key="certs/server.key" \
  --from-file=api.crt="certs/api.crt" \
  --from-file=api.key="certs/api.key" \
  -n NAMESPACE

第 3 步：创建具有 TLS 加密的部署

按照以下步骤创建具有 TLS 加密的部署。

1. 准备 Helm 配置

请参阅创建 Helm 图表配置，并为您的环境创建部署配置。

如需启用 TLS，请在 Helm 图表配置中设置以下值：

# Enables TLS
global:
  insecureMode: false

# Enables client certificate authentication (mTLS)
deployment:
  enableClientCertificateAuthentication: true

2. 创建部署

运行以下命令以创建部署：

kubectl create ns monitoring

helm upgrade --install spanner-omni oci://us-docker.pkg.dev/spanner-omni/charts/spanner-omni \
  --version VERSION \
  --set global.platform=gke \
  --set global.insecureMode=false \
  --set deployment.enableClientCertificateAuthentication=true \
  --namespace NAMESPACE \
  --set monitoring.enabled=true

该命令会触发引导作业。您可以通过查看此作业的日志来跟踪进度：

kubectl logs -n NAMESPACE -l app.kubernetes.io/component=bootstrap -f

输出会指示进度。完成后，您会看到一条消息，指出“部署已成功创建”。

3. 检查 Pod 的状态

运行以下命令以验证 Pod 状态：

kubectl get pods --watch --namespace NAMESPACE

所有 Pod 都处于 READY 状态。

4. 使用负载均衡器详细信息更新证书和部署

如果您希望客户端从 Kubernetes 集群外部进行连接，则需要执行此步骤。

# Get the service details
kubectl get service spanner -n NAMESPACE

# The EXTERNAL-IP:PORT is the API or deployment endpoint for your deployment.
# Update the API certificate with these details.
OMNI_ENDPOINT=EXTERNAL_IP,spanner.NAMESPACE.svc
./google/spanner/bin/spanner certificates update --filename_prefix=api --hostnames=${OMNI_ENDPOINT} --ca_certificate_directory certs --output_directory certs --overwrite

# Update the secrets in Kubernetes
kubectl patch secret tls-certs -n NAMESPACE -p "{\"data\":{\"api.crt\":\"$(base64 -w 0 certs/api.crt)\"}}"

第 4 步：与 Spanner Omni 交互

您可以使用 Spanner Omni CLI 从任何虚拟机与 Spanner Omni 部署进行交互。

如果您为客户端启用了 mTLS，请在每个命令中使用以下标志：

--client-certificate-directory=CLIENT_CERTIFICATE_DIRECTORY
--ca-certificate-file=API_CA_CERT_FILE_PATH

运行以下命令以登录：

./google/spanner/bin/spanner auth login admin --ca-certificate-file=certs/ca-api.crt \
--client-certificate_directory=clientcerts --deployment-endpoint=DEPLOYMENT_ENDPOINT

默认密码为 admin。

Successfully logged in as "admin"

2. 创建数据库

运行以下命令以创建数据库：

./google/spanner/bin/spanner --deployment-endpoint=DEPLOYMENT_ENDPOINT databases create DATABASE_NAME --ca-certificate-file=certs/ca-api.crt --client-certificate-directory=clientcerts

3. 打开 SQL Shell

运行以下命令以打开 Shell：

./google/spanner/bin/spanner sql --database=DATABASE_NAME --deployment-endpoint=DEPLOYMENT_ENDPOINT --ca-certificate-file=certs/ca-api.crt --client-certificate-directory=clientcerts

4. 创建表并添加数据

运行以下 SQL 命令：

spanner> CREATE TABLE names (nameId INT64 NOT NULL, name String(100)) PRIMARY KEY (nameId);
Query OK, 0 rows affected (4.62 sec)

spanner> INSERT names (nameId, name) VALUES (1, "Jack");
Query OK, 1 rows affected (0.18 sec)

5. 验证部署

如需列出数据库，请运行以下命令：

./google/spanner/bin/spanner databases list --ca-certificate-file=certs/ca-api.crt --client-certificate-directory=clientcerts --deployment-endpoint=DEPLOYMENT_ENDPOINT

输出类似于以下内容：

NAME	状态	VERSION_RETENTION_PERIOD	EARLIEST_VERSION_TIME	ENABLE_DROP_PROTECTION
`DATABASE_NAME`	准备就绪	1 小时	2025-02-07T12:25:30Z	false

如需查询数据，请运行以下命令：

./google/spanner/bin/spanner sql --database=DATABASE_NAME --ca-certificate-file=certs/ca-api.crt --client-certificate-directory=clientcerts --deployment-endpoint=DEPLOYMENT_ENDPOINT