Implantar e gerenciar workers

Este documento explica como implantar, escalonar, desativar e monitorar workers do Spanner Omni em máquinas virtuais (VMs) e no Kubernetes.

Os workers são nós de computação dedicados e sem estado projetados para descarregar operações em segundo plano e com uso intensivo de recursos dos servidores do Spanner Omni. Os workers não hospedam dados do usuário nem participam de eleições de líderes, transações ou outras atividades principais do banco de dados. Ao contrário dos servidores, os workers não estão associados a uma zona específica. Em vez disso, os workers se registram em um local e podem executar tarefas para qualquer zona nesse local. Adicionar e remover workers é leve e instantâneo porque eles não têm estado e não exigem movimentação ou rebalanceamento de dados.

Os workers são necessários para criar índices vetoriais em tabelas grandes (mais de 1 milhão de linhas) para consultas de pesquisa de vizinho mais próximo aproximado (ANN). Para mais informações, consulte Visão geral da pesquisa de vetor do Spanner Omni.

Os workers estão disponíveis apenas na edição comercial do Spanner Omni. A edição para desenvolvedores não oferece suporte a workers. A computação dos trabalhadores é faturada com a mesma taxa dos servidores na implantação (por vCPU). Para mais informações, consulte a Visão geral das edições do Spanner Omni.

Antes de começar

Antes de adicionar workers a uma implantação do Spanner Omni, verifique se o ambiente atende aos seguintes requisitos:

  • Faça o download e configure o binário do Spanner Omni.

  • Implantação atual: verifique se você tem uma implantação do Spanner Omni em execução (não uma implantação de servidor único) no estado READY, configurada com a edição Commercial. A edição Developer não é compatível com workers. A computação dos workers é cobrada à mesma taxa dos servidores na implantação. Para mais informações, consulte a Visão geral das edições do Spanner Omni. Confira se você tem as seguintes informações:

    • O nome do local de destino (por exemplo, us-central1), conforme definido na configuração de implantação.
    • O endpoint de implantação (HOST:PORT, como my-spanner-deployment:15003) ou uma lista de endereços de servidor raiz (ROOT_HOST_1:PORT, ROOT_HOST_2:PORT, como root-server-1:15000, root-server-2:15000) para descoberta de cluster.

  • Recursos de sistema e hardware: verifique se os recursos de computação alocados para o worker são suficientes para realizar as operações necessárias em um período de tempo aceitável.

  • Configuração do vSphere: se você executar o Spanner Omni na plataforma de virtualização do vSphere, desative a virtualização do contador de carimbo de data/hora (TSC, na sigla em inglês). Adicione monitor_control.virtual_rdtsc = FALSE ao arquivo de configuração .vmx da máquina virtual.

  • Configuração de rede e firewall: os workers usam a porta 15027 além das portas de comunicação padrão do servidor (15000 a 15025). Verifique se a configuração de rede permite a comunicação nas portas 15000 a 15027.

Implantar workers em VMs

Para implantar workers em uma máquina virtual (VM), inicie o processo de worker usando o endpoint de implantação ou uma lista de servidores raiz.

Opção A: começar a usar o endpoint de implantação

Para iniciar um worker usando o endpoint de implantação, execute o comando spanner workers start:

spanner workers start \
  --location=LOCATION_NAME \
  --address=WORKER_HOSTNAME:WORKER_PORT_BASE \
  --deployment=DEPLOYMENT_ENDPOINT \
  --base-dir=BASE_DIR \
  --license-file-path=LICENSE_FILE_PATH

Substitua:

  • LOCATION_NAME: o nome do local de destino. Por exemplo, us-central1.
  • WORKER_HOSTNAME: o nome do host ou endereço IP resolvível da VM de worker.
  • WORKER_PORT_BASE: a porta base em que o worker é iniciado, por exemplo, 15000 ou 20000.
  • DEPLOYMENT_ENDPOINT: o host e a porta do endpoint de implantação. Por exemplo, my-spanner-deployment:15003.
  • BASE_DIR: o diretório base para dados e registros do worker, por exemplo, /var/spanner.
  • LICENSE_FILE_PATH: o caminho para o arquivo de licença do Spanner Omni.

Opção B: começar a usar uma lista de servidores raiz

Para iniciar um worker usando uma lista de servidores raiz, execute o comando spanner workers start:

spanner workers start \
  --location=LOCATION_NAME \
  --address=WORKER_HOSTNAME:WORKER_PORT_BASE \
  --join-servers=ROOT_SERVER_1_HOST:ROOT_SERVER_PORT_BASE,\
ROOT_SERVER_2_HOST:ROOT_SERVER_PORT_BASE \
  --base-dir=BASE_DIR \
  --license-file-path=LICENSE_FILE_PATH

Substitua:

  • LOCATION_NAME: o nome do local de destino. Por exemplo, us-central1.
  • WORKER_HOSTNAME: o nome do host ou endereço IP resolvível da VM de worker.
  • WORKER_PORT_BASE: a porta base em que o worker é iniciado, por exemplo, 15000 ou 20000.
  • ROOT_SERVER_1_HOST, ROOT_SERVER_2_HOST: os nomes de host ou endereços IP dos servidores raiz na sua implantação.
  • ROOT_SERVER_PORT_BASE: a porta base dos servidores raiz, por exemplo, 15000.
  • BASE_DIR: o diretório base para dados e registros do worker, por exemplo, /var/spanner.
  • LICENSE_FILE_PATH: o caminho para o arquivo de licença do Spanner Omni.

Configurar criptografia

Se a implantação do Spanner Omni usar criptografia TLS ou mTLS, configure a criptografia para cada worker:

  1. Atualize o certificado do servidor para incluir nomes de host de trabalhadores, se ainda não tiver feito isso.
  2. Copie o diretório de certificados que contém ca.crt, server.crt e server.key para a VM de worker.

  3. Adicione a flag --certificate-directory ao executar spanner workers start:

    spanner workers start \
  --location=LOCATION_NAME \
  --address=WORKER_HOSTNAME:WORKER_PORT_BASE \
  --deployment=DEPLOYMENT_ENDPOINT \
  --base-dir=BASE_DIR \
  --certificate-directory=CERTIFICATE_DIRECTORY \
  --license-file-path=LICENSE_FILE_PATH

    Substitua CERTIFICATE_DIRECTORY pelo diretório que contém ca.crt, server.crt e server.key.

Para mais informações sobre como configurar certificados e implantações seguras, consulte Criar uma implantação segura em VMs.

Implantar workers no Kubernetes

Em ambientes do Kubernetes, como o Google Kubernetes Engine (GKE) ou o Amazon Elastic Kubernetes Service (Amazon EKS), você implanta workers como parte da versão do Spanner Omni Helm no mesmo namespace do cluster. O gráfico do Helm implanta workers como um StatefulSet do Kubernetes com um serviço sem cabeçalho, a cada pod de worker uma identidade de rede estável e PersistentVolumeClaims (PVCs), que permite que os servidores raiz se comuniquem de maneira confiável com cada worker.

Por padrão, o gráfico do Helm programa pods de worker apenas em nós rotulados como spanner-role=workers, aceita a restrição spanner-role=workers:NoSchedule e executa no máximo um pod de worker por nó. Antes de ativar os workers, adicione um pool de nós com esse rótulo e taint que tenha pelo menos tantos nós quanto workers.replicas. Cada nó precisa de CPU e memória alocáveis suficientes para um pod worker, conforme definido por workers.resources.cpu e workers.resources.memory. O Kubernetes reserva parte da capacidade de cada nó para componentes do sistema. Portanto, escolha nós maiores que esses valores. Para usar um marcador diferente, defina workers.nodeLabelKey e workers.nodeLabelValue. Para remover a exigência de rótulo, defina workers.nodeLabelKey="". Para substituir as regras de programação padrão, defina workers.affinity.

Para ativar os workers na implantação atual, execute o comando helm upgrade:

helm upgrade spanner-omni HELM_CHART_PATH \
  --reuse-values \
  --set workers.enabled=true \
  --namespace NAMESPACE

Substitua:

  • HELM_CHART_PATH: o caminho para o gráfico Helm do Spanner Omni.
  • NAMESPACE: o namespace do Kubernetes em que o cluster do Spanner Omni está implantado. Por exemplo, spanner-ns.

Para permitir que os workers sejam executados em qualquer nó com CPU e memória alocáveis suficientes, defina workers.nodeLabelKey como uma string vazia. Isso remove o requisito de rótulo do nó e a tolerância de taint:

helm upgrade spanner-omni HELM_CHART_PATH \
  --reuse-values \
  --set workers.enabled=true \
  --set workers.nodeLabelKey="" \
  --namespace NAMESPACE

As configurações opcionais incluem:

  • --set workers.replicas=WORKER_REPLICAS: o número de réplicas de worker a serem implantadas. O padrão é 1.

  • --set workers.resources.cpu=CPU_CORES: o limite de CPU e a solicitação de cada worker. O padrão é 6.

  • --set workers.resources.memory=MEMORY_LIMIT: o limite e a solicitação de memória para cada worker. O padrão é 24Gi.

  • --set workers.storage.size=STORAGE_SIZE: a capacidade de armazenamento de cada worker. O padrão é 20Gi.

  • --set workers.storage.storageClassName=STORAGE_CLASS: a classe de armazenamento a ser usada para o armazenamento do worker. Por exemplo, hyperdisk-balanced-rwo no GKE ou aws-gp3 no Amazon EKS. O padrão é uma string vazia, que herda a classe de armazenamento padrão do cluster.

  • --set workers.port=WORKER_PORT: a porta de rede em que o worker fica à escuta. O padrão é deployment.basePort, que é 15000.

  • --set workers.joinServers={ROOT_HOST_1:PORT,ROOT_HOST_2:PORT}: uma lista explícita separada por vírgulas de endereços de servidores raiz a serem associados. O padrão é uma lista vazia ([]), que descobre todos os servidores raiz ativos da topologia de implantação.

  • --set workers.nodeLabelKey=NODE_LABEL_KEY: a chave do rótulo do nó do Kubernetes usada para afinidade e tolerâncias de nós para isolar os trabalhadores em um pool de nós dedicado. O padrão é spanner-role. Defina como uma string vazia "" para desativar a afinidade e as tolerâncias de nós.

  • --set workers.nodeLabelValue=NODE_LABEL_VALUE: o valor do rótulo do nó do Kubernetes usado para afinidade e tolerâncias de nós. O padrão é workers.

  • --set workers.pdbMaxUnavailable=MAX_UNAVAILABLE: o número máximo de pods de worker que podem ficar indisponíveis durante interrupções voluntárias no PodDisruptionBudget. O padrão é 1.

  • workers.affinity: regras de afinidade personalizadas do Kubernetes para pods de worker. Se não for especificado, a afinidade de nó padrão (usando workers.nodeLabelKey e workers.nodeLabelValue) e a antiafinidade de pod em nomes de host (kubernetes.io/hostname) serão aplicadas. Como esse é um objeto aninhado, especifique-o em um arquivo values.yaml usando a flag -f.

Verificar a implantação do worker

Para verificar se os pods de worker estão em execução e prontos, execute o seguinte comando:

kubectl get pods --namespace NAMESPACE -l app.kubernetes.io/component=spanner-worker

Escalonar e desativar workers

Os workers não armazenam dados do usuário nem participam do consenso do banco de dados. O escalonamento e a desativação de workers são instantâneos. É possível iniciar um worker antes ou depois de iniciar a criação do índice de vetores e desativar o worker imediatamente após a conclusão da criação do índice.

Automatizar o escalonamento de workers

Para automatizar a criação e o escalonamento de workers, monitore a métrica spanner_box_compute_heavy_workers_required. Quando o valor da métrica é maior que 0, a implantação exige um ou mais workers para concluir operações em segundo plano pendentes, como criar um índice de vetor em uma tabela grande. Quando o valor da métrica voltar a 0, todas as operações pendentes serão concluídas e você poderá desativar os workers.

Desativar um worker de VM

Para interromper um processo de worker em execução em uma VM, pressione Control+C no terminal que executa o processo de worker ou interrompa o processo usando o ID dele (PID):

kill -TERM PID

Substitua PID pelo ID do processo spanner workers. Como alternativa, desligue a VM de worker.

Desativar um worker do Kubernetes

Para desativar trabalhadores no Kubernetes, desative-os na sua versão do Helm ou reduzir escala vertical as réplicas de trabalhadores diretamente usando kubectl:

  • Desativar trabalhadores: para remover o trabalhador StatefulSet e o serviço do cluster, preservando o restante da implantação, execute o comando helm upgrade com workers.enabled=false:

    helm upgrade spanner-omni HELM_CHART_PATH \
  --reuse-values \
  --set workers.enabled=false \
  --namespace NAMESPACE

    Substitua:

    • HELM_CHART_PATH: o caminho para o gráfico Helm do Spanner Omni.
    • NAMESPACE: o namespace do Kubernetes em que o cluster do Spanner Omni está implantado. Por exemplo, spanner-ns.

  • Reduzir as réplicas de worker: para reduzir escala vertical os pods de worker a zero réplicas mantendo a configuração de worker ativa no cluster, execute o comando kubectl scale:

    kubectl scale statefulset spanner-worker \
  --replicas=0 \
  --namespace NAMESPACE

    Substitua NAMESPACE pelo namespace do Kubernetes em que o cluster do Spanner Omni está implantado, por exemplo, spanner-ns.

Monitorar e resolver problemas de workers

Se a implantação tiver o monitoramento ativado, será possível monitorar os workers usando painéis do Prometheus ou do Grafana. Os workers expõem métricas semelhantes aos servidores do Spanner Omni. Os painéis do Grafana incluem um painel Insights do worker que permite monitorar a utilização de recursos de cada worker.

Os workers gravam arquivos de registro no subdiretório logs dentro do diretório base especificado por --base-dir:

BASE_DIR/logs

O comando spanner admin diagnostics create não coleta registros nem diagnósticos dos workers. Para inspecionar os registros do worker, veja os arquivos em BASE_DIR/logs diretamente na máquina ou no pod do worker ou execute kubectl logs para pods de worker do Kubernetes.

Para mais informações sobre como monitorar e configurar painéis, consulte Visão geral do monitoramento e Monitorar usando painéis do Grafana.

A criação do índice de vetor não avança

Se você criar um índice de vetor em uma tabela grande e a criação do índice permanecer pendente sem progredir, verifique se pelo menos um worker está em execução e conectado à implantação.

Com o Spanner Omni, é possível criar um índice vetorial mesmo quando não há trabalhadores ativos, para que você possa implantar trabalhadores apenas quando necessário. Se nenhum worker estiver ativo, a operação de criação de índice será pausada indefinidamente até que um worker seja implantado. Quando um worker é iniciado e registrado no deployment, a criação do índice é retomada automaticamente.