创建在虚拟机上使用 TLS 加密的部署

本文档介绍了如何为虚拟机 (VM) 上的 Spanner Omni 部署添加 TLS 加密。具有网络安全功能的部署使用传输层安全协议 (TLS) 1.3 对部署内部以及与客户端之间的通信进行加密和身份验证。Spanner Omni 提供双向 TLS (mTLS) 以增强安全性，双方在交换数据之前会先验证身份。客户端和服务器之间可以选择是否使用 mTLS，但 Spanner Omni 服务器之间会通过 mTLS 进行通信。

准备工作

在开始之前，请确保您的环境满足以下要求：

• 确保您对部署中的每台机器都拥有 SSH 访问权限。通过此访问权限，您可以下载并运行 Spanner Omni 二进制文件。

• 您的网络必须允许通过 15000 至 15030 端口进行 TCP 通信。

• 每台机器都必须有足够的存储空间来托管部署处理的数据。

• 查看系统要求页面，确保您的设置符合要求。

• 如果您在 vSphere 虚拟化平台上运行二进制文件，请停用 TSC 虚拟化。为此，请将 monitor_control.virtual_rdtsc = FALSE 设置添加到虚拟机的 .vmx 配置文件中。

第 1 步：创建不使用 TLS 加密的部署

按照创建不加密的 Spanner Omni 虚拟机部署中的步骤操作。验证不含加密和安全功能的虚拟机部署是否正常运行。本页面假定您已创建包含三个可用区的区域级部署。

第 2 步：生成证书

您需要创建三组证书：

证书类型	说明
API 证书	API 证书有助于保护 Spanner API 服务器。
服务器证书	服务器证书有助于保护服务器间通信。
客户端证书	最终用户或应用使用客户端证书来建立其身份以及与 Spanner Omni 服务器的信任关系。

这些证书由证书授权机构 (CA) 颁发。 Spanner Omni 提供了用于创建 CA 和所有三种类型证书的工具。在其中一台机器上执行以下步骤。

您可以使用 Spanner Omni CLI 在工作站上创建这些证书，然后将证书文件传输到每个 Spanner Omni 服务器。如需了解详情，请参阅快速入门：使用 Spanner Omni CLI。

如需生成证书，您必须完成以下步骤：

• 创建证书授权机构 (CA)
• 生成服务器证书
• 生成客户端证书

创建证书授权机构 (CA)

此授权机构是您在以下步骤中生成的所有客户端和服务器证书的根 CA。

spanner certificates create-ca --ca-certificate-directory=certs

certs 目录包含 CA 证书。创建此证书的副本，以用作 API 证书的 CA。

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

$HOME/.spanner/private-keys 目录包含 CA 的私钥。备份并保护此目录。有权访问私钥的用户可以签署信任自签名 CA 的客户端所信任的任意证书。虽然您可以对所有证书使用相同的 CA，但 API 证书和客户端证书必须使用相同的 CA。（可选）您可以为 API 证书创建额外的 CA（或使用外部受信任的 CA）。 在创建证书时，请确保在以下步骤中使用正确的 CA。本文档对所有证书类型使用相同的 CA。

生成服务器证书

您需要生成两种类型的服务器证书：

• Spanner 服务器证书：加密 Spanner Omni 服务器之间的通信。

• API 证书：加密与部署交互的系统之间的通信。

此设置可让您更灵活地管理这些证书，例如证书轮替。

创建 Spanner 服务器证书

Spanner Omni 服务器使用服务器证书来加密彼此之间的通信（服务器间通信）。

运行以下命令，创建服务器证书。将 SERVER_LIST 替换为 Spanner 服务器或后缀名称的英文逗号分隔列表。

SERVER_NAMES=SERVER_LIST
spanner certificates create-server --hostnames=${SERVER_NAMES} --ca-certificate-directory certs --output-directory certs

此命令会在 certs 目录中创建两个文件：server.crt 和 server.key。

创建 API 证书

API 证书可对与部署交互的系统之间的通信进行加密。为 API 和服务器间通信使用单独的证书，可让您独立管理和轮替每种类型的证书。

运行以下命令，创建 API 证书。将 LB_DNS 替换为负载均衡器的 DNS。

SERVER_NAMES=LB_DNS
spanner certificates create-server --filename-prefix=api --hostnames=${SERVER_NAMES} --ca-certificate-directory certs --output-directory certs

此命令会在 certs 目录中再创建两个文件：api.crt 和 api.key。如果需要，您可以为 API 证书使用外部受信任的 CA。

将证书分发到所有服务器

将 certs 目录复制到部署中的所有其他服务器，以便使用网络安全功能启动这些服务器。

scp -r certs REMOTE_HOST:SPANNER_DIR/certs

第 3 步：生成客户端证书

您可以使用客户端证书在 Spanner 中对用户和应用进行身份验证。客户端证书可在客户端和服务器之间启用 mTLS。

客户端证书必须由与 API 证书相同的 CA 签名，并且必须包含用于授权的用户名。此示例使用 admin 用户，这是每个数据库的默认用户。如需详细了解用户、角色和身份验证选项，请参阅 Spanner Omni 中的身份验证和授权。

USERNAME=admin
spanner certificates create-client $USERNAME --output-directory clientcerts --ca-certificate-directory certs

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

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

USERNAME=admin
spanner certificates create-client $USERNAME \
    --output-directory clientcerts \
    --ca-certificate-directory certs \
    --generate-pkcs8-key

第 4 步：生成封装容器密钥集

Spanner Omni 使用密钥加密密钥 (KEK) 封装密钥集来加密内部密钥，例如令牌加密和签名密钥。Spanner Omni 服务器会从 BASE_DIR/kms/wrapper_key 读取此密钥集。

如需使用 spanner keys create-keyset 生成新的封装容器密钥集文件，请运行以下命令：

spanner keys create-keyset --output-file=kms/wrapper_key

默认情况下，spanner keys create-keyset 会生成 AES256_GCM 密钥。如需生成其他类型的密钥，请将 --key-template 标志与以下密钥类型值之一搭配使用：AES256_GCM、AES128_GCM、AES256_GCM_RAW、CHACHA20_POLY1305 或 XCHACHA20_POLY1305。

将封装容器密钥集分发到所有服务器

在启动部署中的所有服务器之前，将 kms 目录复制到这些服务器的基本目录中：

scp -r kms REMOTE_HOST:BASE_DIR/kms

第 5 步：启动服务器

如需启动部署中的服务器，请按以下步骤操作：

1. 确认您已生成证书和封装密钥集，并将其复制到部署中的所有服务器。
2. 在每台服务器上创建一个基本目录，用于存储数据、元数据和日志。如果服务器需要重启，请指定相同的基本目录以确保连续性。
3. 按照以下部分中针对您的部署类型的说明启动每个服务器。

单服务器部署

如需启动采用加密的单服务器部署，请为初始 admin 用户创建密码文件，然后使用支持的身份验证方法和证书启动服务器。

1. 创建密码文件，并将权限设置为 600，以便只有其所有者可以读取该文件：

   printf '%s' 'PASSWORD' > admin_password.txt
   chmod 600 admin_password.txt
   

   密码必须符合以下要求：

   • 长度在 8 到 32 个字符之间。
   • 至少一个大写字符。
   • 至少一个字符为小写。
   • 至少一个数字。
   • 至少一个特殊字符。

2. 启动配置了 TLS 和身份验证的单服务器：

   nohup spanner start-single-server \
       --base-dir=BASE_DIR \
       --certificate-directory=${HOME}/.spanner/certs \
       --auth-methods=password,client-certificate \
       --password-protocol=opaque \
       --initial-admin-password-file=admin_password.txt &
   

   在初始启动时，spanner start-single-server 会设置支持的身份验证方法和密码协议，并使用指定的密码文件创建具有 roles/spanner.admin 角色的初始 admin 用户。

如需了解如何与部署进行交互，请参阅第 8 步：与部署进行交互。

横向扩容部署

对于横向扩容部署，请在每台机器上启动服务器。server-address 和 zone 的值必须与部署配置中的值一致。网络必须解析 server-address。服务器使用 server-address 进行内部通信。运行以下命令以启动根服务器：

nohup spanner start \
    --root \
    --server-address=HOST_NAME \
    --zone=ZONE_NAME \
    --base-dir=BASE_DIR \
    --certificate-directory=${HOME}/.spanner/certs &

以下命令展示了一个包含特定值的示例：

nohup spanner start \
    --root \
    --server-address=rootserver1 \
    --zone=us-central-1a \
    --base-dir=./spanbasedir \
    --certificate-directory=${HOME}/.spanner/certs &

现在，服务器已在每台机器上运行，您可以创建 Deployment 了。

第 6 步：创建采用 TLS 加密的部署

如需创建部署，请按以下步骤操作：

1. 创建一个密码文件，其中包含默认 admin 用户的密码，其权限设置为 600（仅其所有者可读）：

   printf '%s' 'PASSWORD' > admin_password.txt
   chmod 600 admin_password.txt
   

   密码必须符合以下要求：

   • 长度在 8 到 32 个字符之间。
   • 至少一个大写字符。
   • 至少一个字符为小写。
   • 至少一个数字。
   • 至少一个特殊字符。

2. 确保 deployment.yaml 包含您选择的身份验证方法和密码协议：

   deployment_settings:
     security_settings:
       authentication_methods:
         - AUTHENTICATION_METHOD_PASSWORD
         - AUTHENTICATION_METHOD_CLIENT_CERTIFICATE
       password_authentication_protocol: PASSWORD_AUTHENTICATION_PROTOCOL_OPAQUE
   

   您可以指定以下一种或多种身份验证方法：

   • AUTHENTICATION_METHOD_PASSWORD：密码身份验证
   • AUTHENTICATION_METHOD_CLIENT_CERTIFICATE：客户端证书身份验证

   您可以指定以下密码协议：

   • PASSWORD_AUTHENTICATION_PROTOCOL_OPAQUE：OPAQUE 协议

3. 从其中一个根服务器运行 spanner deployment create 命令以创建部署。使用 --base-dir 标志指定基本目录（使用启动根服务器时指定的同一 BASE_DIR），并使用 --admin-password-file 标志提供管理员密码文件：

   spanner deployment create \
       --config-file=deployment.yaml \
       --base-dir=BASE_DIR \
       --admin-password-file=admin_password.txt
   

每台机器的控制台都会显示消息，表明部署现在包含 TLS 加密。所有服务器都通过加密通道相互通信。

第 7 步：（可选）配置负载均衡器

如需在部署中的服务器之间管理和分配客户端流量，请设置负载均衡器。确保健康检查的负载均衡器配置使用 HTTPS 而不是 HTTP。使用以下配置详细信息：

参数	值
协议	TCP
后端 IP	服务器的 IP 地址。
端口	15000（这是默认端口。如果您在 --server-address 标志中使用了其他端口，请使用该端口。）
健康检查网址	https://IP_ADDRESS:15012/healthz
均衡策略	roundrobin（按顺序在服务器之间分配请求）

第 8 步：与部署互动

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

您必须在每个命令中包含以下标志，才能建立加密连接：

• --ca-certificate-file=certs/ca-api.crt

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

• --client-certificate-directory=clientcerts

如需登录并与您的部署进行交互，请按以下步骤操作：

1. 登录 Spanner Omni

   spanner auth login admin \
       --ca-certificate-file=certs/ca-api.crt \
       --deployment-endpoint=ENDPOINT
   

   出现提示时，输入在 admin_password.txt 中配置的密码。

   Successfully logged in as "admin"
   

2. 创建数据库

   spanner --deployment-endpoint=ENDPOINT databases create mydb --ca-certificate-file=certs/ca-api.crt
   

   Creating database...done.
   

3. 打开 SQL Shell

   spanner sql --database=mydb --ca-certificate-file=certs/ca-api.crt
   

   Connected.
   spanner>
   

4. 创建表并添加数据

   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. 验证数据

   列出数据库：

   spanner databases list --ca-certificate-file=certs/ca-api.crt
   

   NAME  STATE  VERSION_RETENTION_PERIOD  EARLIEST_VERSION_TIME  KMS_KEY_NAME  ENABLE_DROP_PROTECTION
   mydb  READY  1h                        2025-02-07T12:25:30Z                 false
   

   从表中获取数据：

   spanner sql --database=mydb --ca-certificate-file=certs/ca-api.crt
   

   Connected.
   spanner> show tables;
   +----------------+
   | Tables_in_mydb |
   +----------------+
   | names          |
   +----------------+
   1 rows in set (0.14 sec)
   
   spanner> select * from names;
   +--------+--------+
   | nameId | name   |
   +--------+--------+
   | 1      | Jack   |
   +--------+--------+
   1 rows in set (18.69 msecs)
   

第 9 步：（可选）扩缩部署

您可以向区域添加非根服务器，以扩充其容量。如需添加非根服务器，请按照以下步骤操作：

1. 为非根服务器生成服务器证书，并将证书复制到该服务器。如需了解详情，请参阅第 2 步：生成证书。

2. 将封装容器密钥集复制到非根服务器。如需了解详情，请参阅第 4 步：生成封装容器密钥集。

3. 启动非根服务器：

   spanner start \
       --server-address=NON_ROOT_MACHINE \
       --join-servers=ROOT_SERVER1,ROOT_SERVER2,ROOT_SERVER3 \
       --zone=us-central1-a \
       --base-dir=./spandir \
       --certificate-directory=${HOME}/.spanner/certs
   

后续步骤

• 使用客户端库和 JDBC 驱动程序将应用与部署连接。
• 管理用户和角色。