Criar uma implantação com criptografia TLS no Kubernetes

O Spanner Omni usa o TLS 1.3 para criptografar dados que fluem entre o cliente e o servidor e entre os servidores do Spanner Omni. O Spanner Omni fornece mTLS para maior segurança, em que ambas as partes estabelecem a autenticidade uma da outra antes de trocar dados. Se você usar a criptografia, seus servidores precisarão se comunicar por mTLS. Você pode escolher se o cliente e o servidor também usam mTLS.

A versão de visualização do Spanner Omni não oferece suporte à criptografia TLS. Para acessar os recursos que permitem criar implantações com criptografia TLS, entre em contato com o Google para solicitar acesso antecipado à versão completa do Spanner Omni.

Antes de começar

Verifique se você atende aos seguintes requisitos:

Criar um cluster do Kubernetes A configuração oferece suporte ao Google Kubernetes Engine (GKE) e ao Amazon Elastic Kubernetes Service (Amazon EKS). Talvez seja necessário personalizar a configuração para trabalhar em outros ambientes.
Verifique se o cluster do Kubernetes pode acessar o artefato do Artifact Registry que hospeda o contêiner do Spanner Omni.
Instale e configure a kubectl ferramenta de linha de comando e o Helm.
Se você configurar o ambiente do Kubernetes em máquinas da plataforma de virtualização vSphere, desative a virtualização do contador de carimbo de data/hora (TSC, na sigla em inglês) adicionando monitor_control.virtual_rdtsc = FALSE ao arquivo de configuração .vmx da máquina virtual. Isso garante que o TrueTime funcione corretamente.
Verifique se o ambiente atende aos requisitos de sistema do Spanner Omni.

Etapa 1: gerar os certificados

Crie três conjuntos de certificados:

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

Uma autoridade de certificação (AC) emite esses certificados. O Spanner Omni fornece ferramentas para criar uma AC autoassinada e todos os três tipos de certificados.

Siga estas etapas em uma das suas máquinas. As etapas pressupõem que o namespace seja spanner-ns. Mude isso para o namespace que você pretende usar na implantação.

É possível criar esses certificados na estação de trabalho usando a CLI do Spanner Omni.

1. Criar uma autoridade de certificação (AC)

Uma autoridade de certificação (AC) emite todos os certificados. Sua organização pode ter uma AC central ou você pode usar uma AC pública. Embora seja possível usar a mesma AC para todos os certificados, os certificados de API e de cliente precisam usar a mesma AC.

O Spanner Omni permite criar uma AC particular.

./google/spanner/bin/spanner certificates create-ca --ca-certificate-directory=certs

O comando create-ca gera o certificado de CA no diretório certs. É possível copiar esse certificado para usar como AC para certificados de API ou criar uma AC diferente. Use a AC correta ao criar certificados.

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

O diretório $HOME/.spanner/private-keys contém a chave privada da AC. É fundamental fazer backup e proteger esse diretório. Os usuários com acesso à chave privada podem assinar certificados arbitrários em que os clientes que confiam na AC autoassinada confiam. Opcionalmente, é possível criar uma AC adicional (ou usar uma AC confiável externamente) para os certificados de API. Este documento usa a mesma AC para todos os tipos de certificados.

2. Gerar certificados do servidor

É necessário gerar dois tipos de certificados do servidor:

Certificado de API: use esse certificado para criptografar a comunicação de sistemas que interagem com a implantação.
Certificado do servidor do Spanner: os servidores do Spanner Omni usam este certificado para criptografar a comunicação entre si.

Essa configuração oferece flexibilidade no gerenciamento desses certificados. Por exemplo, ela permite usar a rotação de certificados.

Criar o certificado do servidor do Spanner

Para criar o certificado do servidor, execute o seguinte comando:

# Comma-separate names of the Spanner servers; wildcards are supported.
SERVER_NAMES=*.pod.NAMESPACE
./google/spanner/bin/spanner certificates create-server --hostnames=${SERVER_NAMES} --ca-certificate-directory certs --output-directory certs

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

Criar o certificado de API

Para criar o certificado de API, execute o seguinte comando:

OMNI_ENDPOINT=spanner.NAMESPACE
./google/spanner/bin/spanner certificates create-server --filename-prefix=api --hostnames=${OMNI_ENDPOINT} --ca-certificate-directory certs --output-directory certs

Esse comando cria api.crt e api.key no diretório certs. Se necessário, use uma AC confiável externamente para os certificados de API.

3. Gerar certificados do cliente

É possível usar certificados do cliente para autenticar usuários e aplicativos. Os certificados do cliente ativam o mTLS entre o cliente e o servidor. Pule esta etapa se você não planeja usar o mTLS.

A mesma AC que assina o certificado de API precisa assinar os certificados do cliente, que também precisam conter um nome de usuário para autorização. Para este exemplo, use o usuário admin, que é o usuário padrão para cada novo banco de dados. Para mais informações, consulte Autenticação e autorização no Spanner Omni.

USERNAME=admin
./google/spanner/bin/spanner certificates create-client $USERNAME --output-directory clientcerts --ca-certificate-directory certs

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

Se você planeja usar 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
./google/spanner/bin/spanner certificates create-client $USERNAME --output-directory clientcerts --ca-certificate-directory certs --generate-pkcs8-key

Etapa 2: enviar os certificados para o cluster do Kubernetes

Execute os comandos a seguir para enviar os certificados ao cluster do Kubernetes:

kubectl create namespace NAMESPACE

kubectl create secret generic tls-certs \
  --from-file=ca.crt="certs/ca.crt" \
  --from-file=ca-api.crt="certs/ca-api.crt" \
  --from-file=server.crt="certs/server.crt" \
  --from-file=server.key="certs/server.key" \
  --from-file=api.crt="certs/api.crt" \
  --from-file=api.key="certs/api.key" \
  -n NAMESPACE

Etapa 3: criar a implantação com criptografia TLS

Siga estas etapas para criar a implantação com criptografia TLS.

1. Preparar a configuração do Helm

Consulte Criar uma configuração de gráfico do Helm e crie a configuração de implantação para seu ambiente.

Para ativar o TLS, defina os seguintes valores na configuração do gráfico do Helm:

# Enables TLS
global:
  insecureMode: false

# Enables client certificate authentication (mTLS)
deployment:
  enableClientCertificateAuthentication: true

2. Criar a implantação

Execute o seguinte comando para criar a implantação:

kubectl create ns monitoring

helm upgrade --install spanner-omni oci://us-docker.pkg.dev/spanner-omni/charts/spanner-omni \
  --version VERSION \
  --set global.platform=gke \
  --set global.insecureMode=false \
  --set deployment.enableClientCertificateAuthentication=true \
  --namespace NAMESPACE \
  --set monitoring.enabled=true

O comando aciona um job de inicialização. É possível acompanhar o progresso observando os registros desse job:

kubectl logs -n NAMESPACE -l app.kubernetes.io/component=bootstrap -f

A saída indica o progresso. Quando concluído, uma mensagem informando "Implantação criada com sucesso" aparece.

3. Verificar o status dos pods

Execute o seguinte comando para verificar o status do pod:

kubectl get pods --watch --namespace NAMESPACE

Todos os pods estão no estado READY.

4. Atualizar o certificado e a implantação com detalhes do balanceador de carga

Essa etapa é necessária se você quiser que os clientes se conectem de fora do cluster do Kubernetes.

# Get the service details
kubectl get service spanner -n NAMESPACE

# The EXTERNAL-IP:PORT is the API or deployment endpoint for your deployment.
# Update the API certificate with these details.
OMNI_ENDPOINT=EXTERNAL_IP,spanner.NAMESPACE.svc
./google/spanner/bin/spanner certificates update --filename_prefix=api --hostnames=${OMNI_ENDPOINT} --ca_certificate_directory certs --output_directory certs --overwrite

# Update the secrets in Kubernetes
kubectl patch secret tls-certs -n NAMESPACE -p "{\"data\":{\"api.crt\":\"$(base64 -w 0 certs/api.crt)\"}}"

Etapa 4: interagir com o Spanner Omni

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

Se você ativou o mTLS para clientes, use as seguintes sinalizações com cada comando:

--client-certificate-directory=CLIENT_CERTIFICATE_DIRECTORY
--ca-certificate-file=API_CA_CERT_FILE_PATH

Execute o seguinte comando para fazer login:

./google/spanner/bin/spanner auth login admin --ca-certificate-file=certs/ca-api.crt \
--client-certificate_directory=clientcerts --deployment-endpoint=DEPLOYMENT_ENDPOINT

A senha padrão é admin.

Successfully logged in as "admin"

2. Criar um banco de dados

Execute o seguinte comando para criar um banco de dados:

./google/spanner/bin/spanner --deployment-endpoint=DEPLOYMENT_ENDPOINT databases create DATABASE_NAME --ca-certificate-file=certs/ca-api.crt --client-certificate-directory=clientcerts

3. Abrir o SQL Shell

Execute o seguinte comando para abrir o shell:

./google/spanner/bin/spanner sql --database=DATABASE_NAME --deployment-endpoint=DEPLOYMENT_ENDPOINT --ca-certificate-file=certs/ca-api.crt --client-certificate-directory=clientcerts

4. Criar uma tabela e adicionar dados

Execute os seguintes comandos SQL:

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 a implantação

Para listar os bancos de dados, execute o seguinte comando:

./google/spanner/bin/spanner databases list --ca-certificate-file=certs/ca-api.crt --client-certificate-directory=clientcerts --deployment-endpoint=DEPLOYMENT_ENDPOINT

A saída será assim:

NAME	ESTADO	VERSION_RETENTION_PERIOD	EARLIEST_VERSION_TIME	ENABLE_DROP_PROTECTION
`DATABASE_NAME`	READY	1h	2025-02-07T12:25:30Z	falso

Para consultar os dados, execute o seguinte comando:

./google/spanner/bin/spanner sql --database=DATABASE_NAME --ca-certificate-file=certs/ca-api.crt --client-certificate-directory=clientcerts --deployment-endpoint=DEPLOYMENT_ENDPOINT