Usar a biblioteca de cliente Java para se conectar ao Spanner Omni

A biblioteca de cliente Java para Spanner funciona com o Spanner Omni da mesma forma que funciona com o Spanner. Este documento mostra como estabelecer conexões seguras com o Spanner Omni configurando a biblioteca de cliente Java. Você estabelece essas conexões definindo as opções do cliente ao criar um cliente administrativo ou um cliente de banco de dados.

A biblioteca de cliente Java oferece suporte a conexões de texto simples, TLS, TLS com credenciais e mTLS.

Para mais informações, consulte Introdução ao Spanner no Java na documentação do Spanner.

Antes de começar

Para começar a usar o Spanner Omni no Java, use a biblioteca de cliente Java versão 6.119.0 ou mais recente.

Se você usar o Maven sem a lista de materiais (BOM), adicione o seguinte às dependências do arquivo pom.xml:

<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-spanner</artifactId>
  <version>6.119.0</version>
</dependency>

Configurações de segurança

A biblioteca de cliente Java do Spanner oferece suporte a quatro configurações de segurança, que definem como a comunicação é criptografada e autenticada entre o cliente e o Spanner Omni. A tabela a seguir descreve cada configuração:

Configuração de segurança Descrição
Texto simples A comunicação não é criptografada.
TLS A comunicação é criptografada usando o Transport Layer Security (TLS). Essa configuração exige que você adicione o certificado de CA do Spanner Omni ao keystore Java, conforme descrito em Configurar o keystore Java.
TLS com credenciais A comunicação é criptografada usando TLS, e a autenticação é realizada usando um nome de usuário e uma senha.
mTLS A comunicação é criptografada usando TLS mútuo (mTLS). Essa configuração exige que você forneça um certificado de cliente e uma chave privada do cliente.

Configurar o keystore Java

Para todos os tipos de conexão criptografada (TLS, TLS com credenciais e mTLS), é necessário adicionar o certificado de CA do Spanner Omni ao keystore Java para que o cliente possa verificar o certificado do servidor.

Para adicionar o certificado de CA ao keystore Java padrão, execute o seguinte comando:

sudo keytool -import -trustcacerts -file ~/.spanner/certs/ca.crt -alias spanner-ca -keystore $JAVA_HOME/lib/security/cacerts

Como alternativa, é possível especificar um keystore personalizado ao executar o aplicativo:

  1. Para manter a compatibilidade com outros serviços que usam autoridades de certificação (CAs) padrão, copie o keystore Java padrão:

    cp $JAVA_HOME/lib/security/cacerts /PATH_TO_CUSTOM_CACERTS

  2. Importe o certificado de CA para o keystore personalizado:

    keytool -import -trustcacerts -file ~/.spanner/certs/ca.crt -alias spanner-ca -keystore /PATH_TO_CUSTOM_CACERTS

  3. Especifique o keystore personalizado usando as propriedades do sistema JVM ao executar o aplicativo:

    java -Djavax.net.ssl.trustStore=/PATH_TO_CUSTOM_CACERTS -Djavax.net.ssl.trustStorePassword=changeit app

Configurar o objeto SpannerOptions

Ao configurar o SpannerOptions objeto para criar um DatabaseClient ou DatabaseAdminClient, especifique o endpoint do Spanner Omni usando setHost() seguido por setType(SpannerOptions.InstanceType.OMNI).

Os exemplos a seguir mostram como configurar o objeto SpannerOptions para cada configuração de segurança compatível:

Texto simples

Para estabelecer uma conexão de texto simples, especifique o endpoint do Spanner Omni com http:// e use o método usePlainText():

SpannerOptions options =
    SpannerOptions.newBuilder()
        .setHost("http://ENDPOINT") // Replace with your Spanner Omni endpoint
        .setType(SpannerOptions.InstanceType.OMNI)
        .usePlainText()
        .build();
Spanner spanner = options.getService();

TLS

Ao configurar o objeto SpannerOptions para uma conexão TLS, não é necessário especificar credenciais de nome de usuário e senha. Especifique o endpoint do Spanner Omni usando https://:

SpannerOptions options =
    SpannerOptions.newBuilder()
        .setHost("https://ENDPOINT") // Replace with your Spanner Omni endpoint
        .setType(SpannerOptions.InstanceType.OMNI)
        .build();
Spanner spanner = options.getService();

TLS com credenciais

Para estabelecer uma conexão TLS com autenticação de nome de usuário e senha, especifique o endpoint do Spanner Omni usando https:// e o nome de usuário e a senha usando o método login():

SpannerOptions options =
    SpannerOptions.newBuilder()
        .setHost("https://ENDPOINT") // Replace with your Spanner Omni endpoint
        .setType(SpannerOptions.InstanceType.OMNI)
        .login("USERNAME", "PASSWORD".toCharArray())
        .build();
Spanner spanner = options.getService();

mTLS

Para usar uma conexão mTLS, converta a chave gerada pelo Spanner Omni em um formato compatível com Java usando o seguinte comando:

openssl pkcs8 -topk8 -in ~/.spanner/certs/client.key -out ~/.spanner/certs/java-client.key -nocrypt

O exemplo a seguir mostra como configurar o objeto SpannerOptions para usar um certificado de cliente:

SpannerOptions options =
    SpannerOptions.newBuilder()
        .setHost("https://ENDPOINT") // Replace with your Spanner Omni endpoint
        .setType(SpannerOptions.InstanceType.OMNI)
        .useClientCert(
            "PATH_TO_CLIENT_CERT",
            "PATH_TO_CLIENT_CERT_KEY")
        .build();
Spanner spanner = options.getService();

Receber um cliente de banco de dados

Depois de configurar o objeto SpannerOptions, você pode receber um cliente de banco de dados. Como o Spanner Omni não usa IDs de projeto na nuvem ou de instância do Google Cloud, especifique default para o ID do projeto e o ID da instância ao criar um DatabaseId:

DatabaseId dbId = DatabaseId.of("default", "default", "DATABASE_ID");
DatabaseClient client = spanner.getDatabaseClient(dbId);