Configurações de implantação

Este documento descreve as configurações de implantação do Spanner Omni em máquinas virtuais (VMs) ou servidores bare metal. Ele explica a estrutura e as opções de configuração do arquivo YAML de configuração de implantação (deployment.yaml) usado para definir topologias de implantação de VM e parâmetros de tempo de execução ao usar a CLI do Spanner Omni.

Para saber como criar uma implantação, consulte uma das seguintes opções:

• Criar uma implantação em VMs
• Criar uma implantação segura em VMs
• Criar uma implantação no Kubernetes
• Criar uma implantação segura no Kubernetes

Visão geral da configuração de implantação

Ao criar uma implantação em VMs ou servidores bare metal, transmita esse arquivo de configuração para o comando spanner deployment create na CLI do Spanner Omni:

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

A configuração de implantação define os seguintes elementos principais:

• Modo de servidor único: modo de otimização que restringe toda a implantação a um único servidor para desenvolvimento e teste.
• Locais: sites físicos ou regiões da nuvem onde seus servidores estão localizados.
• Distâncias de localização: latências de rede entre pares de locais.
• Zonas: agrupamentos lógicos de servidores que representam réplicas do Paxos.
• Servidores raiz: servidores dedicados responsáveis pelos metadados da zona e pelo quorum de associação.
• Tipos de réplica: papéis para cada zona (leitura/gravação, testemunha ou somente leitura).
• SLA de relógio: parâmetros de sincronização do TrueTime, incluindo erros de jitter e taxa de variação do relógio.
• Configurações de implantação: configurações globais, como locais preferidos de líder e configurações de segurança de autenticação.

Estrutura do arquivo de configuração

O exemplo a seguir mostra a estrutura de nível superior de um arquivo de configuração de implantação:

# 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

Campos de nível superior

A configuração de implantação é compatível com os seguintes campos de nível superior:

Campo	Tipo	Descrição
name	String	O nome da implantação, como prod, staging ou regional-deployment.
single_server	Booleano	Opcional. Se definido como true, especifica que toda a implantação é de servidor único, restringindo-a a uma zona e um servidor. As implantações criadas com single_server: true não podem adicionar zonas ou servidores após a criação. Se você quiser executar o Spanner Omni no modo de servidor único, não é necessário criar manualmente essa configuração porque o Spanner Omni a gera automaticamente quando você executa o comando spanner start-single-server. O padrão é false.
location	Lista de objetos	Os locais físicos ou lógicos (regiões) na implantação.
location_distance	Lista de objetos	Opcional. A latência de rede entre pares de locais.
zone	Lista de objetos	Obrigatório. As zonas que compõem a implantação. É necessário especificar pelo menos uma zona.
clock_sla	Objeto	Opcional. Os parâmetros do contrato de nível de serviço (SLA) de sincronização de relógio para o software TrueTime.
deployment_settings	Objeto	Opcional. Configurações de tempo de execução para posicionamento preferencial do líder e autenticação de segurança.

Nome da implantação

O campo name especifica um nome escolhido pelo usuário para a implantação. É possível usar qualquer string que identifique a implantação, como prod, staging ou regional-deployment.

Modo de servidor único

O campo single_server de nível superior especifica que toda a implantação é de servidor único. Quando definida como true, essa configuração restringe a implantação a uma zona e um servidor, o que reduz a sobrecarga de recursos para ambientes locais de desenvolvimento e teste. Não é possível adicionar zonas ou servidores a implantações criadas com single_server:true depois da criação.

Se você quiser executar o Spanner Omni no modo de servidor único, não precisa criar essa configuração manualmente. Quando você executa o comando spanner start-single-server, o Spanner Omni gera automaticamente essa configuração. Para mais informações, consulte Opção A: implantação em um único servidor.

O campo single_server de nível superior é diferente do campo single_server no nível da zona:

• O campo single_server de nível superior se aplica a toda a implantação.
• O campo zone-level single_server se aplica apenas a uma zona individual em uma implantação. Para mais informações, consulte Zonas de servidor único.

Locais

Um local representa um data center físico ou uma região da nuvem onde as máquinas estão localizadas (equivalente a uma região em Google Cloud).

Você define locais na lista location:

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

Os nomes de locais precisam atender aos seguintes requisitos:

• Precisa começar com uma letra e terminar com uma letra ou um dígito.
• Pode conter apenas letras, dígitos, sublinhados (_) e traços (-).
• Opcionalmente, inclua um prefixo de domínio seguido por dois pontos (por exemplo, cloud.google.com:us-east1 ou onprem:datacenter1).
• Não é possível usar o nome reservado default.
• Precisa ser exclusivo em toda a implantação.

Distâncias de local

A lista location_distance especifica a latência de rede entre pares de locais. O Spanner Omni usa essas informações para otimizar a replicação e o roteamento de consultas.

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

Cada objeto de distância do local contém os seguintes campos:

• src: obrigatório. O nome do local de origem. Precisa corresponder a um local definido na lista location.
• dest: obrigatório. O nome do local de destino. Precisa corresponder a um local definido e não pode ser idêntico a src.
• latency_ms: a latência de rede em milissegundos. Precisa ser um número inteiro não negativo. Se omitido, o Spanner Omni vai presumir que a latência é insignificante (menos de um milissegundo).

A latência de rede em redes físicas nem sempre é simétrica. Se você fornecer (src, dest) e (dest, src), o Spanner Omni vai respeitar as duas medições. Se você fornecer apenas uma direção, o Spanner Omni vai presumir que a direção inversa tem a mesma latência.

Zonas

Uma zona é um agrupamento lógico de um ou mais servidores em um local. Para replicação de dados, cada zona representa uma réplica do Paxos. Uma implantação precisa ter pelo menos uma zona.

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

Cada objeto de zona é compatível com os seguintes campos:

Campo	Tipo	Descrição
name	String	Obrigatório. O nome da zona. Segue as mesmas regras de nomenclatura dos nomes de locais. Precisa ser exclusivo em toda a implantação.
location	String	O nome do local em que a zona reside. Precisa corresponder a um local definido na lista location. Se omitido, o Spanner Omni vai atribuir a zona ao local default.
single_server	Booleano	Opcional. Se definido como true, designa que esta zona tem apenas um único servidor (só pode ter um servidor raiz e nenhum outro servidor). Elimina a sobrecarga de replicação de metadados de zona dentro da zona. Em uma implantação multizonal, você pode definir isso como true para zonas específicas, como uma zona de réplica WITNESS que não armazena dados do usuário, enquanto outras zonas têm vários servidores. O padrão é false.
replica_type	String de enumeração	A função de réplica da zona em quóruns do Paxos. Os valores aceitos são READ_WRITE, WITNESS e READ_ONLY. O padrão é READ_WRITE.
root_server	Lista de objetos	Obrigatório. A lista de servidores raiz na zona.

Tipos de réplica

O Spanner Omni oferece suporte a três tipos de réplicas para zonas:

• READ_WRITE: armazena uma cópia completa dos dados do usuário, atende a solicitações de leitura e vota em quóruns do Paxos. As réplicas de leitura/gravação podem se tornar líderes do Paxos para propor gravações.
• WITNESS: vota em quóruns do Paxos para ajudar a alcançar um consenso, mas não pode se tornar um líder. As réplicas de testemunha não armazenam dados do usuário e não podem atender a solicitações de leitura. Eles ajudam a alcançar o quorum sem a sobrecarga de armazenamento ou a latência de gravação de uma réplica completa em locais distantes.
• READ_ONLY: armazena uma cópia completa dos dados do usuário que é replicada de forma assíncrona dos líderes. As réplicas somente leitura não podem se tornar líderes e não votam em quóruns do Paxos. Elas descarregam o tráfego de leitura das réplicas de leitura/gravação.

Ao configurar tipos de réplicas, verifique se a implantação atende às seguintes regras:

• A implantação precisa conter pelo menos uma zona READ_WRITE.
• O número de zonas READ_WRITE precisa ser estritamente maior que o número de zonas WITNESS.

Servidores raiz

Os servidores raiz têm responsabilidades especiais no Spanner Omni. Eles armazenam metadados de zona e gerenciam a associação de outros servidores na zona. Se um quorum de servidores raiz ficar indisponível, toda a zona ficará indisponível.

Ao configurar servidores raiz em deployment.yaml, siga estas diretrizes:

• O número de servidores raiz por zona precisa ser um número ímpar entre 1 e 9, inclusive, para garantir o quorum de consistência. Se o número de servidores for par, as implantações poderão falhar. Ao configurar as zonas, designe servidores como servidores raiz. Recomendamos que você use um para desenvolvimento ou teste e três para zonas de produção de alta disponibilidade.
• Especifique apenas servidores raiz no arquivo deployment.yaml durante a criação da implantação inicial. Servidores não raiz podem ser adicionados depois para escalonar a capacidade de computação e armazenamento.

Cada objeto de servidor raiz aceita os seguintes campos:

• host: obrigatório. O nome do host ou o endereço IP da máquina que executa o servidor.
• port_base: opcional. O número da porta inicial do servidor. O padrão é 15000. Essa porta se torna a porta gRPC pública para conexões de clientes. É necessário reservar portas no intervalo [port_base + 1, port_base + 31] (por exemplo, 15001 a 15031) para processos internos do Spanner Omni.

Zonas de servidor único

O campo single_server no nível da zona especifica que uma zona individual contém apenas um servidor. Uma zona de servidor único pode ter apenas um servidor raiz e não é possível adicionar outros depois. Essa configuração elimina a sobrecarga de replicar metadados de zona dentro dessa zona.

Ao contrário do campo single_server de nível superior, que designa que toda a implantação consiste em um único servidor, o campo single_server no nível da zona se aplica apenas a essa zona específica.

Em uma implantação multizonal, é possível configurar zonas individuais como zonas de servidor único, enquanto outras zonas contêm vários servidores. Por exemplo, considere uma implantação com duas zonas de réplica READ_WRITE e uma zona de réplica WITNESS:

• As duas zonas READ_WRITE contêm vários servidores (single_server: false) para oferecer alta disponibilidade e escalonar a capacidade de computação e armazenamento dos dados do usuário.
• É possível configurar a zona WITNESS como de servidor único ou de vários servidores, dependendo do volume de votos do Paxos:
  • Cargas de trabalho pequenas a médias: se uma única VM ou servidor tiver capacidade suficiente para processar todo o tráfego de votação do Paxos para a implantação, defina single_server: true. Como as réplicas de testemunha apenas votam e não armazenam dados do usuário, o uso de um único servidor elimina a sobrecarga de replicação de metadados intra-zona.
  • Implantações em grande escala: se você tiver alta capacidade de processamento de gravação ou muitos servidores em cada zona READ_WRITE (por exemplo, dezenas ou centenas de nós), um único servidor poderá ficar sobrecarregado e causar falhas de consenso do Paxos. Configure a zona WITNESS com vários servidores (single_server: false) para distribuir a carga de trabalho de votação.

Para ver um exemplo de configuração, consulte Implantação em vários locais com réplica de testemunha.

SLA de relógio

O Spanner Omni usa o software TrueTime para fornecer consistência externa sem exigir hardware de GPS especializado ou relógios atômicos. O objeto clock_sla define os limites de sincronização esperados para relógios do servidor em toda a implantação:

clock_sla:
  jitter_in_s: 0.005
  rate_error_in_ppm: 200

A configuração clock_sla inclui os seguintes campos:

• jitter_in_s: o jitter máximo esperado do relógio em segundos. Precisa ser um número de ponto flutuante não negativo (>= 0).
• rate_error_in_ppm: o erro máximo de taxa de variação do relógio em partes por milhão (ppm). Precisa ser um valor entre 0 e 10000.

Para mais informações sobre a sincronização de tempo, consulte TrueTime e consistência externa.

Configurações de implantação

O objeto deployment_settings configura o comportamento de implantação global, incluindo a preferência de local do líder e a segurança de rede:

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

Local líder preferido

O campo preferred_leader_location designa um local em que os líderes do Paxos são colocados preferencialmente. A escolha de líderes perto da sua carga de trabalho principal do aplicativo reduz a latência de gravação, evitando viagens de ida e volta extras na rede.

Ao configurar o preferred_leader_location, verifique o seguinte:

• O local especificado precisa corresponder a um local definido na lista location (ou default).
• O local designado precisa conter pelo menos uma zona READ_WRITE.

Configurações de segurança

O objeto security_settings configura os modos de autenticação e criptografia:

• insecure_mode: booleano. Se definido como true, desativa a autenticação e a autorização para conexões de entrada. Esse modo é destinado apenas a prototipagem e avaliação. O padrão é false.
• authentication_methods: lista de métodos de autenticação ativados. Obrigatório se insecure_mode for false. Valores aceitos:
  • AUTHENTICATION_METHOD_PASSWORD: ativa a autenticação de nome de usuário e senha.
  • AUTHENTICATION_METHOD_CLIENT_CERTIFICATE: ativa a autenticação de certificado do cliente TLS mútuo (mTLS).
• password_authentication_protocol: o protocolo usado para verificação de senha. Obrigatório se AUTHENTICATION_METHOD_PASSWORD estiver incluído em authentication_methods. Valor compatível:
  • PASSWORD_AUTHENTICATION_PROTOCOL_OPAQUE: usa o protocolo de troca de chaves autenticadas por senha assimétrica OPAQUE.

Para mais informações sobre como configurar criptografia e credenciais, consulte Criar uma implantação com criptografia TLS em VMs.

Exemplos de configuração de implantação

Os exemplos a seguir demonstram padrões de implantação comuns.

Implantação multizonal regional

A configuração a seguir cria uma implantação regional de alta disponibilidade em três zonas em um único local:

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

Implantação em vários locais com réplica testemunha

A configuração a seguir cria uma implantação multirregional abrangendo dois data centers e um site de testemunha, com posicionamento preferencial do líder. A lista location_distance especifica latências de rede realistas e assimétricas entre cada par de locais. As duas zonas READ_WRITE usam três servidores raiz para alta disponibilidade, enquanto a zona WITNESS usa single_server: true com um único servidor raiz porque as réplicas de testemunha não armazenam dados do usuário:

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

Implantação segura com TLS e autenticação

A configuração a seguir define uma implantação com mTLS e autenticação de senha ativada:

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

A seguir

• Criar uma implantação em VMs
• Criar um deployment com criptografia TLS em VMs
• Escalonar uma implantação de VM
• Manter uma implantação