部署配置

本文档介绍了在虚拟机 (VM) 或裸金属服务器上部署 Spanner Omni 的配置。本文介绍了使用 Spanner Omni CLI 时用于定义虚拟机部署拓扑和运行时参数的 YAML 部署配置文件 (deployment.yaml) 的结构和配置选项。

如需了解如何创建部署，请参阅以下任一文档：

• 在虚拟机上创建部署
• 在虚拟机上创建安全部署
• 在 Kubernetes 上创建部署
• 在 Kubernetes 上创建安全部署

部署配置概览

在虚拟机或裸金属服务器上创建部署时，您需要将此配置文件传递给 Spanner Omni CLI 中的 spanner deployment create 命令：

spanner deployment create --config-file=deployment.yaml

部署配置定义了以下关键元素：

• 单服务器模式：一种优化模式，可将整个部署限制为单个服务器，以用于开发和测试。
• 位置：服务器所在的物理位置或云区域。
• 位置距离：位置对之间的网络延迟。
• 可用区：表示 Paxos 副本的服务器的逻辑分组。
• 根服务器：负责区域元数据和成员资格法定人数的专用服务器。
• 副本类型：每个可用区的角色（读写、见证或只读）。
• 时钟 SLA：TrueTime 同步参数，包括时钟抖动和漂移率误差。
• 部署设置：全局设置，例如首选的领导者位置和身份验证安全设置。

配置文件结构

以下示例展示了部署配置文件的顶级结构：

# Deployment name
name: regional-deployment

# Restrict the entire deployment to a single server (optional, default: false)
single_server: false

# Physical or logical locations (regions)
location:
  - name: us-central1

# Network distances between locations (optional)
location_distance:
  - src: us-central1
    dest: us-east1
    latency_ms: 30

# Zones and root servers in the deployment
zone:
  - name: us-central1-a
    location: us-central1
    single_server: false
    replica_type: READ_WRITE
    root_server:
      - host: rootserver1.example.internal
        port_base: 15000

# Clock synchronization SLA parameters (optional)
clock_sla:
  jitter_in_s: 0.005
  rate_error_in_ppm: 200

# Deployment settings (optional)
deployment_settings:
  preferred_leader_location: us-central1
  security_settings:
    insecure_mode: true

顶级字段

部署配置支持以下顶级字段：

字段	类型	说明
name	字符串	部署的名称，例如 prod、staging 或 regional-deployment。
single_server	布尔值	可选。如果设置为 true，则表示整个部署是单服务器部署，将其限制为一个可用区和一个服务器。使用 single_server: true 创建的部署在创建后无法添加区域或服务器。如果您想在单服务器模式下运行 Spanner Omni，则无需手动创建此配置，因为当您运行 spanner start-single-server 命令时，Spanner Omni 会自动生成该配置。默认值为 false。
location	对象列表	部署中的物理或逻辑位置（区域）。
location_distance	对象列表	可选。位置对之间的网络延迟时间。
zone	对象列表	必需。构成部署的可用区。您必须至少指定一个可用区。
clock_sla	对象	可选。软件 TrueTime 的时钟同步服务等级协议 (SLA) 参数。
deployment_settings	对象	可选。首选主放置位置和安全身份验证的运行时设置。

部署名称

name 字段用于指定部署的用户选择的名称。您可以使用任何可标识部署的字符串，例如 prod、staging 或 regional-deployment。

单服务器模式

顶级 single_server 字段指定整个部署为单服务器部署。如果设置为 true，此设置会将部署限制为一个可用区和一个服务器，从而减少本地开发和测试环境的资源开销。使用 single_server:true 创建的部署在创建后无法添加区域或服务器。

如果您想以单服务器模式运行 Spanner Omni，则无需手动创建此配置。运行 spanner start-single-server 命令时，Spanner Omni 会自动为您生成此配置。如需了解详情，请参阅方案 A：单服务器部署。

顶级 single_server 字段与区域级 single_server 字段不同：

• 顶级 single_server 字段适用于整个部署。
• 可用区级 single_server 字段仅适用于部署中的单个可用区。如需了解详情，请参阅单服务器区域。

位置

位置表示机器所在的物理数据中心或云区域（相当于 Google Cloud中的区域）。

您可以在 location 列表中定义位置：

location:
  - name: us-central1
  - name: europe-west2

位置名称必须满足以下要求：

• 必须以字母开头，并以字母或数字结尾。
• 只能包含字母、数字、下划线 (_) 和短划线 (-)。
• 可以选择性地包含网域前缀，后跟英文冒号（例如 cloud.google.com:us-east1 或 onprem:datacenter1）。
• 无法使用预留名称 default。
• 在整个部署中必须是唯一的。

地理位置距离

location_distance 列表用于指定位置对之间的网络延迟时间。Spanner Omni 会使用此信息来优化复制和查询路由。

location_distance:
  - src: us-central1
    dest: europe-west2
    latency_ms: 105
  - src: europe-west2
    dest: us-central1
    latency_ms: 110

每个位置距离对象都包含以下字段：

• src：必需。来源位置的名称。必须与 location 列表中定义的某个位置匹配。
• dest：必需。目的地位置的名称。必须与已定义的位置相匹配，并且不能与 src 相同。
• latency_ms：网络延迟时间（以毫秒为单位）。必须是非负整数。如果省略，Spanner Omni 会假定延迟时间可忽略不计（低于毫秒级）。

物理网络中的网络延迟时间并不总是对称的。如果您同时提供 (src, dest) 和 (dest, src)，Spanner Omni 会同时考虑这两个指标。如果您仅提供一个方向，Spanner Omni 会假设反向具有相同的延迟时间。

可用区

可用区是某个位置内一个或多个服务器的逻辑分组。对于数据复制，每个可用区都代表一个 Paxos 副本。部署必须至少包含一个可用区。

zone:
  - name: us-central1-a
    location: us-central1
    single_server: false
    replica_type: READ_WRITE
    root_server:
      - host: rootserver1.example.internal
        port_base: 15000
      - host: rootserver2.example.internal
        port_base: 15000
      - host: rootserver3.example.internal
        port_base: 15000

每个时区对象都支持以下字段：

字段	类型	说明
name	字符串	必需。相应可用区的名称。遵循与位置名称相同的命名规则。在整个部署中必须是唯一的。
location	字符串	可用区所在的地理位置的名称。必须与 location 列表中的某个已定义位置相匹配。如果省略，Spanner Omni 会将可用区分配给 default 位置。
single_server	布尔值	可选。如果设置为 true，则表示相应区域只有一个服务器（只能有一个根服务器，不能有其他服务器）。消除了可用区内的可用区元数据复制开销。 在多可用区部署中，您可以针对特定可用区（例如不存储用户数据的 WITNESS 副本可用区）将此值设置为 true，而其他可用区则具有多个服务器。默认值为 false。
replica_type	枚举字符串	可用区在 Paxos 仲裁中的副本角色。支持的值包括 READ_WRITE、WITNESS 和 READ_ONLY。默认值为 READ_WRITE。
root_server	对象列表	必需。相应区域中的根服务器列表。

副本类型

Spanner Omni 支持以下三种可用区副本类型：

• READ_WRITE：存储用户数据的完整副本，处理读取请求，并在 Paxos 定额中进行投票。读写副本有资格成为 Paxos 主要副本来提议写入。
• WITNESS：在 Paxos 仲裁中投票以帮助达成共识，但不能成为领导者。见证者副本不存储用户数据，也无法处理读取请求。它们有助于在不产生存储空间开销或写入延迟的情况下，在不同位置之间实现完整副本的仲裁。
• READ_ONLY：存储从领导者异步复制的用户数据的完整副本。只读副本无法成为领导者，也不会在 Paxos 仲裁中投票。它们可从读写副本分流读取流量。

配置副本类型时，请确保部署满足以下规则：

• 部署必须包含至少一个 READ_WRITE 区域。
• READ_WRITE 区域的数量必须严格大于 WITNESS 区域的数量。

根服务器

在 Spanner Omni 中，根服务器承担着特殊的责任。它们存储可用区元数据并管理可用区中其他服务器的成员资格。如果大多数根服务器变得不可用，整个网域都会变得不可用。

在 deployment.yaml 中配置根服务器时，请谨记以下准则：

• 每个区域的根服务器数量必须是介于 1 到 9 之间（含边界值）的奇数，以确保一致性的法定人数。如果服务器数量为偶数，部署可能会失败。配置区域时，将服务器指定为根服务器。我们建议您使用一个用于开发或测试，使用三个用于高可用性生产区域。
• 在创建初始部署时，仅在 deployment.yaml 文件中指定根服务器。以后可以添加非根服务器来扩缩计算和存储容量。

每个根服务器对象都支持以下字段：

• host：必需。运行服务器的计算机的主机名或 IP 地址。
• port_base：可选。服务器的起始端口号。默认值为 15000。此端口将成为客户端连接的公共 gRPC 端口。您必须预留 [port_base + 1, port_base + 31] 范围内的端口（例如 15001 到 15031）供内部 Spanner Omni 进程使用。

单服务器区域

区域级 single_server 字段用于指定单个可用区仅包含一台服务器。单服务器区域只能有一个根服务器，并且以后无法添加其他服务器。此设置可消除在该可用区内复制可用区元数据的开销。

与用于指定整个部署由单个服务器组成的顶级 single_server 字段不同，区域级 single_server 字段仅适用于相应特定区域。

在多可用区部署中，您可以将各个可用区配置为单服务器可用区，而其他可用区包含多个服务器。例如，假设某部署包含两个 READ_WRITE 副本可用区和一个 WITNESS 副本可用区：

• 这两个 READ_WRITE 可用区包含多个服务器 (single_server: false)，可提供高可用性，并可根据用户数据调整计算和存储容量。
• 您可以根据 Paxos 投票量将 WITNESS 区域配置为单服务器区域或多服务器区域：
  • 小型到中型工作负载：如果单个虚拟机或服务器有足够的容量来处理部署的所有 Paxos 投票流量，请将 single_server: true 设置为 1。由于见证副本仅投出选票，而不存储用户数据，因此使用单个服务器可消除区域内元数据复制开销。
  • 大规模部署：如果您在每个 READ_WRITE 可用区中都有很高的写入吞吐量或许多服务器（例如，数十个或数百个节点），则单个服务器可能会过载，从而导致 Paxos 共识失败。配置具有多个服务器 (single_server: false) 的 WITNESS 区域，以分发投票工作负载。

如需查看配置示例，请参阅使用见证副本进行多位置部署。

时钟 SLA

Spanner Omni 依靠软件 TrueTime 提供外部一致性，而无需使用专门的 GPS 硬件或原子钟。clock_sla 对象定义了部署中服务器时钟的预期同步界限：

clock_sla:
  jitter_in_s: 0.005
  rate_error_in_ppm: 200

clock_sla 配置包含以下字段：

• jitter_in_s：以秒为单位的最大预期时钟抖动。必须是非负浮点数 (>= 0)。
• rate_error_in_ppm：以百万分率 (ppm) 表示的最大时钟漂移率误差。必须是一个介于 0 到 10000 的值。

如需详细了解时间同步，请参阅 TrueTime 和外部一致性。

部署设置

deployment_settings 对象用于配置全局部署行为，包括领导者位置偏好设置和网络安全：

deployment_settings:
  preferred_leader_location: us-central1
  security_settings:
    insecure_mode: false
    authentication_methods:
      - AUTHENTICATION_METHOD_PASSWORD
      - AUTHENTICATION_METHOD_CLIENT_CERTIFICATE
    password_authentication_protocol: PASSWORD_AUTHENTICATION_PROTOCOL_OPAQUE

首选主要位置

preferred_leader_location 字段用于指定优先放置 Paxos 领导者的位置。选择靠近主要应用工作负载的领导者可避免额外的网络往返，从而缩短写入延迟时间。

配置 preferred_leader_location 时，请确保满足以下条件：

• 指定的位置必须与 location 列表（或 default）中定义的位置相匹配。
• 指定的位置必须包含至少一个 READ_WRITE 可用区。

安全设置

security_settings 对象用于配置身份验证和加密模式：

• insecure_mode：布尔值。如果设置为 true，则会针对传入连接停用身份验证和授权。此模式仅用于原型设计和评估。默认值为 false。
• authentication_methods：已启用的身份验证方法列表。 如果 insecure_mode 为 false，则必须提供此值。支持的值：
  • AUTHENTICATION_METHOD_PASSWORD：启用用户名和密码身份验证。
  • AUTHENTICATION_METHOD_CLIENT_CERTIFICATE：启用双向 TLS (mTLS) 客户端证书身份验证。
• password_authentication_protocol：用于密码验证的协议。如果 authentication_methods 中包含 AUTHENTICATION_METHOD_PASSWORD，则必须提供此值。支持的值：
  • PASSWORD_AUTHENTICATION_PROTOCOL_OPAQUE：使用 OPAQUE 非对称密码身份验证密钥交换协议。

如需详细了解如何设置加密和凭据，请参阅在虚拟机上创建具有 TLS 加密的部署。

部署配置示例

以下示例展示了常见的部署模式。

区域级多可用区部署

以下配置会在单个位置的三个可用区中创建一个高可用性区域级部署：

name: regional-prod
location:
  - name: us-central1
zone:
  - name: us-central1-a
    location: us-central1
    replica_type: READ_WRITE
    root_server:
      - host: root-a1.example.internal
      - host: root-a2.example.internal
      - host: root-a3.example.internal
  - name: us-central1-b
    location: us-central1
    replica_type: READ_WRITE
    root_server:
      - host: root-b1.example.internal
      - host: root-b2.example.internal
      - host: root-b3.example.internal
  - name: us-central1-c
    location: us-central1
    replica_type: READ_WRITE
    root_server:
      - host: root-c1.example.internal
      - host: root-c2.example.internal
      - host: root-c3.example.internal

使用见证者副本进行多位置部署

以下配置会创建一个跨越两个数据中心和一个见证站点的多位置部署，并采用首选的领导者放置方式。location_distance 列表指定了每对位置之间实际的不对称网络延迟时间。两个 READ_WRITE 可用区各使用三个根服务器来实现高可用性，而 WITNESS 可用区使用 single_server: true（只有一个根服务器），因为见证副本不存储用户数据：

name: multi-site-deployment
location:
  - name: datacenter-east
  - name: datacenter-west
  - name: datacenter-central
location_distance:
  - src: datacenter-east
    dest: datacenter-central
    latency_ms: 25
  - src: datacenter-central
    dest: datacenter-east
    latency_ms: 27
  - src: datacenter-central
    dest: datacenter-west
    latency_ms: 30
  - src: datacenter-west
    dest: datacenter-central
    latency_ms: 32
  - src: datacenter-east
    dest: datacenter-west
    latency_ms: 55
  - src: datacenter-west
    dest: datacenter-east
    latency_ms: 58
zone:
  - name: east-zone-1
    location: datacenter-east
    replica_type: READ_WRITE
    root_server:
      - host: east-root-1.example.internal
      - host: east-root-2.example.internal
      - host: east-root-3.example.internal
  - name: west-zone-1
    location: datacenter-west
    replica_type: READ_WRITE
    root_server:
      - host: west-root-1.example.internal
      - host: west-root-2.example.internal
      - host: west-root-3.example.internal
  - name: central-witness-zone
    location: datacenter-central
    single_server: true
    replica_type: WITNESS
    root_server:
      - host: witness-root-1.example.internal
deployment_settings:
  preferred_leader_location: datacenter-east

通过 TLS 和身份验证实现安全部署

以下配置定义了已启用 mTLS 和密码身份验证的部署：

name: secure-deployment
location:
  - name: us-central1
zone:
  - name: us-central1-a
    location: us-central1
    replica_type: READ_WRITE
    root_server:
      - host: server-1.example.internal
        port_base: 15000
      - host: server-2.example.internal
        port_base: 15000
      - host: server-3.example.internal
        port_base: 15000
deployment_settings:
  security_settings:
    insecure_mode: false
    authentication_methods:
      - AUTHENTICATION_METHOD_PASSWORD
      - AUTHENTICATION_METHOD_CLIENT_CERTIFICATE
    password_authentication_protocol: PASSWORD_AUTHENTICATION_PROTOCOL_OPAQUE

后续步骤

• 在虚拟机上创建部署
• 创建在虚拟机上使用 TLS 加密的部署
• 扩缩虚拟机部署
• 维护部署