Criar um deployment com criptografia TLS em VMs

Neste documento, descrevemos como adicionar criptografia TLS a uma implantação do Spanner Omni em máquinas virtuais (VMs). Uma implantação com recursos de segurança de rede usa o Transport Layer Security (TLS) 1.3 para criptografar e autenticar a comunicação dentro da implantação e com os clientes. O Spanner Omni oferece TLS mútuo (mTLS) para maior segurança, em que ambas as partes estabelecem a autenticidade antes de trocar dados. O mTLS é opcional entre o cliente e o servidor, mas os servidores do Spanner Omni se comunicam entre si por mTLS.

Antes de começar

Antes de começar, verifique se o ambiente atende aos seguintes requisitos:

  • Verifique se você tem acesso SSH a cada máquina na implantação. Esse acesso permite que você faça o download e execute o binário do Spanner Omni.

  • Sua rede precisa permitir a comunicação TCP nas portas 15000 a 15030.

  • Cada máquina precisa ter armazenamento suficiente para hospedar os dados que a implantação processa.

  • Consulte a página Requisitos do sistema para garantir que sua configuração atenda aos requisitos.

  • Se você executar os binários na plataforma de virtualização do vSphere, desative a virtualização do TSC. Para fazer isso, adicione a configuração monitor_control.virtual_rdtsc = FALSE ao arquivo de configuração .vmx da máquina virtual.

Etapa 1: criar uma implantação sem criptografia TLS

Siga as etapas em Criar uma implantação de VM do Spanner Omni sem criptografia. Verifique se a implantação da VM sem recursos de criptografia e segurança funciona corretamente. Nesta página, presumimos que você tenha criado uma implantação regional com três zonas.

Etapa 2: gerar os certificados

Você precisa criar três conjuntos de certificados:

Tipo de certificado Descrição
Certificados de API Os certificados de API ajudam a proteger o servidor de API Spanner.
Certificados do servidor Os certificados de servidor ajudam a proteger a comunicação entre servidores.
Certificados do cliente Os usuários finais ou aplicativos usam certificados do cliente para estabelecer a identidade e a confiança com os servidores do Spanner Omni.

Uma autoridade certificadora (CA) emite esses certificados. O Spanner Omni oferece ferramentas para criar uma CA e os três tipos de certificados. Siga as etapas abaixo em uma das suas máquinas.

É possível criar esses certificados na estação de trabalho usando a CLI do Spanner Omni e, em seguida, transferir os arquivos de certificado para cada servidor do Spanner Omni. Para mais informações, consulte o Guia de início rápido sobre como usar a CLI do Spanner Omni.

Para gerar certificados, siga estas etapas:

Criar autoridades certificadoras

É preciso criar duas autoridades certificadoras (CAs) separadas para isolar a comunicação interna entre servidores da comunicação externa de clientes e APIs:

  • CA do servidor interno (ca.crt): emite certificados de servidor (server.crt) usados exclusivamente para comunicação mTLS interna entre servidores do Spanner Omni.
  • AC de API e cliente (ca-api.crt): emite o certificado do servidor de API (api.crt) e os certificados mTLS do cliente (client.crt). Como alternativa, é possível usar uma AC confiável externamente para os certificados de API e cliente.

  1. Crie a CA do servidor interno para comunicação entre servidores:

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

    Esse comando cria o certificado de CA do servidor interno (certs/ca.crt) e grava a chave privada dele em $HOME/.spanner/private-keys/ca.key.

  2. Crie uma CA separada para os certificados de API e de cliente e copie o certificado de CA para certs/ca-api.crt:

    spanner certificates create-ca \
    --ca-certificate-directory=api-certs \
    --ca-private-key-directory=$HOME/.spanner/api-private-keys
cp api-certs/ca.crt certs/ca-api.crt

    Esses comandos criam o certificado de CA da API e do cliente (api-certs/ca.crt, copiado para certs/ca-api.crt) e gravam a chave privada em $HOME/.spanner/api-private-keys/ca.key.

Faça backup e proteja $HOME/.spanner/private-keys e $HOME/.spanner/api-private-keys. Um usuário com acesso a essas chaves privadas pode assinar certificados arbitrários em que a implantação confia.

Gerar certificados do servidor

Você gera dois tipos de certificados de servidor:

Essa configuração oferece um gerenciamento mais flexível desses certificados, como uma rotação de certificados.

Criar o certificado do servidor do Spanner

Os servidores do Spanner Omni usam certificados de servidor para criptografar a comunicação entre si (comunicação entre servidores).

Crie o certificado do servidor:

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

Substitua SERVER_LIST por uma lista separada por vírgulas de nomes de servidores ou sufixos do Spanner.

Esse comando cria dois arquivos, server.crt e server.key, no diretório certs.

Criar o certificado da API

Os certificados de API criptografam a comunicação de sistemas que interagem com a implantação. O uso de certificados e CAs separados para a API e a comunicação entre servidores permite isolar domínios de confiança e alternar cada tipo de forma independente.

Crie o certificado de API usando a CA de API:

SERVER_NAMES=LB_DNS
spanner certificates create-server \
    --filename-prefix=api \
    --hostnames=${SERVER_NAMES} \
    --ca-certificate-directory=api-certs \
    --ca-private-key-directory=$HOME/.spanner/api-private-keys \
    --output-directory=certs

Substitua LB_DNS pelo nome do host DNS do balanceador de carga.

Esse comando cria mais dois arquivos, api.crt e api.key, no diretório certs. Se necessário, use uma CA confiável externamente para os certificados da API.

Distribuir os certificados para todos os servidores

Copie o diretório certs para todos os outros servidores na implantação para iniciá-los com recursos de segurança de rede.

scp -r certs REMOTE_HOST:SPANNER_DIR/certs

Etapa 3: gerar certificados do cliente

É possível usar certificados do cliente para autenticar usuários e aplicativos no Spanner. Os certificados do cliente ativam o mTLS entre o cliente e o servidor.

Assine os certificados do cliente com a API e a AC do cliente (api-certs/ca.crt, que corresponde a certs/ca-api.crt) e inclua um nome de usuário para autorização. Não assine certificados do cliente com a CA do servidor interno (certs/ca.crt). Este exemplo usa o usuário admin, que é o usuário padrão de cada banco de dados. Para mais informações sobre usuários, papéis e opções de autenticação, consulte Autenticação e autorização no Spanner Omni.

Crie o certificado do cliente:

USERNAME=admin
spanner certificates create-client $USERNAME \
    --output-directory=clientcerts \
    --ca-certificate-directory=api-certs \
    --ca-private-key-directory=$HOME/.spanner/api-private-keys

Esse comando cria os arquivos client.crt e client.key no diretório clientcerts. Envie esses arquivos para qualquer máquina que se conecte aos servidores da implantação.

Se você planeja usar os certificados do cliente com a biblioteca de cliente Java, gere a chave do certificado no formato PKCS#8. Use o comando a seguir:

USERNAME=admin
spanner certificates create-client $USERNAME \
    --output-directory=clientcerts \
    --ca-certificate-directory=api-certs \
    --ca-private-key-directory=$HOME/.spanner/api-private-keys \
    --generate-pkcs8-key

Etapa 4: gerar o conjunto de chaves do wrapper

O Spanner Omni usa um conjunto de chaves de encapsulamento de chave de criptografia de chaves (KEK) para criptografar chaves internas, como chaves de criptografia e assinatura de token. Os servidores do Spanner Omni leem esse conjunto de chaves de BASE_DIR/kms/wrapper_key.

Para gerar um novo arquivo de conjunto de chaves de wrapper usando spanner keys create-keyset, execute o seguinte comando:

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

Por padrão, spanner keys create-keyset gera uma chave AES256_GCM. Para gerar um tipo diferente de chave, use a flag --key-template com um dos seguintes valores de tipo de chave: AES256_GCM, AES128_GCM, AES256_GCM_RAW, CHACHA20_POLY1305 ou XCHACHA20_POLY1305.

Distribuir o conjunto de chaves do wrapper para todos os servidores

Copie o diretório kms para o diretório base em todos os servidores na implantação antes de iniciá-los:

scp -r kms REMOTE_HOST:BASE_DIR/kms

Etapa 5: iniciar os servidores

Para iniciar os servidores na implantação, siga estas etapas:

  1. Confirme se você gerou os certificados e o conjunto de chaves de wrapper e os copiou para todos os servidores na sua implantação.
  2. Crie um diretório base em cada servidor para armazenar dados, metadados e registros. Se um servidor precisar ser reiniciado, especifique o mesmo diretório base para garantir a continuidade.
  3. Inicie cada servidor usando as instruções para seu tipo de implantação nas seções a seguir.

Implantação de servidor único

Para iniciar uma implantação de servidor único com criptografia, crie um arquivo de senha para o usuário admin inicial e inicie o servidor com os métodos de autenticação e certificados compatíveis.

  1. Crie o arquivo de senha com conjunto de permissões definido como 600 para que ele seja legível apenas pelo proprietário:

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

    A senha precisa atender aos seguintes requisitos:

    • Entre 8 e 32 caracteres.
    • Pelo menos um caractere maiúsculo.
    • Pelo menos um caractere minúsculo.
    • Pelo menos um número.
    • Pelo menos um caractere especial.

  2. Inicie o servidor único com o TLS e a autenticação configurados:

    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 &

    Na inicialização, o spanner start-single-server define os métodos de autenticação e o protocolo de senha compatíveis e cria o usuário inicial admin com o papel roles/spanner.admin usando o arquivo de senha especificado.

Para saber como interagir com a implantação, consulte Etapa 8: interagir com a implantação.

Implantação de escalonamento horizontal

Para implantações de escalonamento horizontal, inicie o servidor em cada máquina. Os valores de server-address e zone precisam corresponder aos valores na configuração da implantação. A rede precisa resolver server-address. Os servidores usam server-address para comunicação interna. Execute o seguinte comando para iniciar o servidor raiz:

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

O comando a seguir mostra um exemplo com valores específicos:

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

Com os servidores em execução em cada máquina, você já pode criar a implantação.

Etapa 6: criar uma implantação com criptografia TLS

Para criar a implantação, siga estas etapas:

  1. Crie um arquivo de senha que contenha a senha do usuário padrão do admin com o conjunto de permissões definido como 600 (legível apenas pelo proprietário):

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

    A senha precisa atender aos seguintes requisitos:

    • Entre 8 e 32 caracteres.
    • Pelo menos um caractere maiúsculo.
    • Pelo menos um caractere minúsculo.
    • Pelo menos um número.
    • Pelo menos um caractere especial.

  2. Verifique se deployment.yaml inclui os métodos de autenticação selecionados e o protocolo de senha:

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

    É possível especificar um ou mais dos seguintes métodos de autenticação:

    • AUTHENTICATION_METHOD_PASSWORD: autenticação por senha
    • AUTHENTICATION_METHOD_CLIENT_CERTIFICATE: autenticação de certificado do cliente

    É possível especificar o seguinte protocolo de senha:

    • PASSWORD_AUTHENTICATION_PROTOCOL_OPAQUE: protocolo OPAQUE

  3. Execute o comando spanner deployment create em um dos servidores raiz para criar a implantação. Especifique o diretório base com a flag --base-dir (usando o mesmo BASE_DIR especificado ao iniciar o servidor raiz) e forneça o arquivo de senha do administrador com a flag --admin-password-file:

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

O console de cada máquina mostra mensagens indicando que a implantação agora inclui criptografia TLS. Todos os servidores se comunicam entre si por um canal criptografado.

Etapa 7: (opcional) configurar um balanceador de carga

Para gerenciar e distribuir o tráfego de clientes entre os servidores na implantação, configure um balanceador de carga. Verifique se a configuração do balanceador de carga para a verificação de integridade usa HTTPS em vez de HTTP. Use os seguintes detalhes de configuração:

Parâmetro Valor
Protocolo TCP
IP do back-end Os endereços IP dos seus servidores.
Porta 15000 (Esta é a porta padrão. Se você usou uma porta diferente na flag --server-address, use essa porta.
URL da verificação de integridade https://IP_ADDRESS:15012/healthz
Estratégia de balanceamento roundrobin (distribui solicitações sequencialmente entre servidores)

Etapa 8: interagir com a implantação

É possível interagir com sua implantação do Spanner Omni em qualquer VM usando a CLI do Spanner Omni.

É preciso incluir a seguinte flag em cada comando para estabelecer uma conexão criptografada:

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

Se você tiver ativado o mTLS para clientes, inclua também a seguinte flag em cada comando:

  • --client-certificate-directory=clientcerts

Para fazer login e interagir com a implantação, siga estas etapas:

  1. Fazer login no Spanner Omni

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

    Quando solicitado, digite a senha configurada em admin_password.txt.

    Successfully logged in as "admin"

  2. Criar um banco de dados

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

    Creating database...done.

  3. Abra o SQL Shell.

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

    Connected.
spanner>

  4. Criar uma tabela e adicionar dados

    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. Verificar os dados

    Liste os bancos de dados:

    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

    Receba os dados da tabela:

    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)

Etapa 9: (opcional) escalonar a implantação

É possível adicionar servidores não raiz a uma zona para escalonar a capacidade dela. Para adicionar um servidor não raiz, siga estas etapas:

  1. Gere um certificado de servidor para o servidor não raiz e copie os certificados para ele. Para mais informações, consulte Etapa 2: gerar os certificados.

  2. Copie o conjunto de chaves do wrapper para o servidor não raiz. Para mais informações, consulte Etapa 4: gerar o conjunto de chaves do wrapper.

  3. Inicie o servidor não raiz:

    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

Próximas etapas