Conectar-se ao Cloud Storage usando o gRPC

É possível se conectar ao Cloud Storage usando o gRPC, um framework de RPC universal de código aberto e alto desempenho desenvolvido pelo Google que usa buffers de protocolo para definir serviços. O gRPC usa conectividade direta entre instâncias do Compute Engine e buckets do Cloud Storage, que ignora os Google Front Ends (GFEs) para reduzir a latência. Para cargas de trabalho de análise no Google Cloud, o gRPC melhora o desempenho de leitura do Cloud Storage apenas quando a instância do Compute Engine e o bucket do Cloud Storage estão na mesma região.

Clientes compatíveis

É possível se conectar ao Cloud Storage usando o gRPC por meio dos seguintes clientes compatíveis:

• Conector do Cloud Storage no Serviço Gerenciado para Apache Spark.

• Conector de E/S do Apache Beam no Dataflow para solicitações de leitura e gravação.

• Bibliotecas de cliente do Cloud Storage para C++, Go e Java. Para instruções sobre como ativar o gRPC para essas bibliotecas de cliente, consulte Ativar o gRPC na biblioteca de cliente.

• Cloud Storage FUSE. É possível usar o Cloud Storage FUSE como cliente especificando grpc no campo client-protocol usando um arquivo de configuração do Cloud Storage FUSE ou a opção --client-protocol usando a CLI do Cloud Storage FUSE. Para usar o gRPC com o Cloud Storage FUSE, recomendamos o uso do Cloud Storage FUSE versão 2.10.0 ou mais recente.

Ativar o gRPC em uma biblioteca de cliente

C++

Antes de começar

1. Verifique se você tem as seguintes versões instaladas:

   • gRPC versão 1.65.1 ou posterior

   • Biblioteca de cliente C++ versão v2.30.0 ou mais recente

   • C++ versão 14 ou mais recente

   Para instruções de instalação, consulte Como configurar um ambiente de desenvolvimento em C++.

2. Configure a autenticação.

3. Verifique se cada instância do Compute Engine tem uma conta de serviço anexada a ela, mesmo que a conta de serviço não tenha permissões. Essa conta de serviço é usada para representar a instância do Compute Engine no processo de handshake do Application Layer Transport Security (ALTS) e é necessária para a conectividade direta.

Configurar a biblioteca de cliente C++

1. Crie um cliente gRPC usando gcs::MakeGrpcClient():

     namespace gcs = google::cloud::storage;
     void App() {
      auto client = gcs::MakeGrpcClient();
   
     // application code
   
     }
   

   A biblioteca de cliente C++ usa automaticamente a conectividade direta quando detecta que o aplicativo está em execução no Google Cloud.

2. Para configurar a biblioteca de cliente C++ para usar o gRPC, ative o cliente gRPC do Cloud Storage para atualizar a configuração do sistema de build para CMake ou Bazel.

   CMake

   1. Ative o plug-in do cliente gRPC do Cloud Storage no tempo de compilação.

      cmake -DGOOGLE_CLOUD_CPP_ENABLE=storage_grpc [other options here]
      

   2. Na base de código, para o comando target_link_libraries(), substitua google-cloud-cpp::storage por google-cloud-cpp::storage_grpc.

      Por exemplo, o programa de início rápido para gRPC usa o seguinte código:

      add_executable(quickstart_grpc quickstart_grpc.cc)
      target_link_libraries(quickstart_grpc google-cloud-cpp::storage_grpc)
      

   Bazel

   Substitua as dependências de @google_cloud_cpp//:storage por @google_cloud_cpp//:storage_grpc.

   Por exemplo, o programa de início rápido para gRPC usa o seguinte código:

     cc_binary(
         name = "quickstart",
         srcs = [
             "quickstart.cc",
         ],
         deps = [
             "@com_github_googleapis_google_cloud_cpp//:storage_grpc",
         ],
     )
   

Java

Antes de começar

1. Verifique se você tem as seguintes versões instaladas:

   • Bibliotecas de cliente Java:

     • com.google.cloud:google-cloud-storage:2.43.1 ou mais recente.
     • com.google.cloud:libraries-bom:26.48 ou mais recente.

   • Java 8 ou mais recente

   Para instruções de instalação, consulte Como configurar um ambiente de desenvolvimento em Java.

2. Configure a autenticação.

3. Verifique se cada instância do Compute Engine tem uma conta de serviço anexada a ela, mesmo que a conta de serviço não tenha permissões. Essa conta de serviço é usada para representar a instância do Compute Engine no processo de handshake do Application Layer Transport Security (ALTS) e é necessária para a conectividade direta.

Atualizar o projeto para usar a BoM

Para garantir que seus projetos tenham versões compatíveis das bibliotecas de cliente do Google Cloud , use as versões especificadas na lista de materiais (BOM, na sigla em inglês) das bibliotecas doGoogle Cloud . Para atualizar o projeto para usar a BOM, use um dos seguintes métodos:

• Cloud Storage independente
• Cloud Storage com outras bibliotecas do Google Cloud

Cloud Storage independente

Se você estiver usando a biblioteca de cliente do Cloud Storage de forma independente (sem outras bibliotecas doGoogle Cloud ), use a BOM específica da biblioteca de cliente do Cloud Storage.

Maven

Importe a BOM na seção dependencyManagement do seu arquivo pom.xml.

O exemplo a seguir mostra como importar a BOM e incluir o artefato google-cloud-storage.

<dependencyManagement>
  <dependencies>
  <dependency>
   <groupId>com.google.cloud</groupId>
   <artifactId>google-cloud-storage-bom</artifactId>
   <version>2.43.1</version>
   <type>pom</type>
   <scope>import</scope>
  </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
   <groupId>com.google.cloud</groupId>
   <artifactId>google-cloud-storage</artifactId>
  </dependency>
</dependencies>

Gradle

Adicione uma dependência de plataforma em com.google.cloud:google-cloud-storage-bom:

implementation platform('com.google.cloud:google-cloud-storage-bom:2.43.1')
implementation 'com.google.cloud:google-cloud-storage'

Cloud Storage com outras bibliotecas do Google Cloud

Se você estiver usando a biblioteca de cliente do Cloud Storage com outras bibliotecas do Google Cloud , use a BOM das bibliotecas de cliente do Google Cloud .

Maven

Importe a BOM na seção dependencyManagement do seu arquivo pom.xml.

O exemplo a seguir mostra como importar a BOM e incluir o artefato libraries-bom.

<dependencyManagement>
  <dependencies>
  <dependency>
   <groupId>com.google.cloud</groupId>
   <artifactId>libraries-bom</artifactId>
   <version>26.48.0</version>
   <type>pom</type>
   <scope>import</scope>
  </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
   <groupId>com.google.cloud</groupId>
   <artifactId>google-cloud-storage</artifactId>
  </dependency>
</dependencies>

Gradle

Adicione uma dependência de plataforma em com.google.cloud:libraries-bom:

implementation platform('com.google.cloud:libraries-bom:26.48.0')
implementation 'com.google.cloud:google-cloud-storage'

Criar um cliente gRPC

O exemplo a seguir usa um builder centrado em gRPC. O cliente Java do gRPC usa automaticamente a conectividade direta quando detecta que o aplicativo está em execução no Google Cloud.

// Imports the Google Cloud client library
import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.BucketInfo;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class QuickstartGrpcSample {
  public static void main(String... args) throws Exception {

    // Create an instance of options which will use the Google Cloud Storage gRPC API for all
    // operations
    StorageOptions options = StorageOptions.grpc().build();

    // Instantiates a client in a try-with-resource to automatically cleanup underlying resources
    try (Storage storage = options.getService()) {
      // The name for the new bucket
      String bucketName = args[0]; // "my-new-bucket";

      // Creates the new bucket using a request to the gRPC API
      Bucket bucket = storage.create(BucketInfo.of(bucketName));

      System.out.printf("Bucket %s created.%n", bucket.getName());
    }
  }
}

Go

Antes de começar

1. Configure o ambiente de desenvolvimento.

2. Use a versão 1.46.0 ou mais recente da biblioteca de cliente do Cloud Storage para Go.

3. Configure a autenticação.

4. Verifique se cada instância do Compute Engine tem uma conta de serviço anexada a ela, mesmo que a conta de serviço não tenha permissões. Essa conta de serviço é usada para representar a instância do Compute Engine no processo de handshake do Application Layer Transport Security (ALTS) e é necessária para a conectividade direta.

Criar um cliente gRPC

Para usar o cliente, chame o construtor NewGRPCClient no aplicativo em vez de NewClient.

// Sample storage-quickstart creates a Google Cloud Storage bucket using
// gRPC API.
package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"cloud.google.com/go/storage"
)

func main() {
	ctx := context.Background()

	// Use your Google Cloud Platform project ID and Cloud Storage bucket
	projectID := "project-id"
	bucketName := "bucket-name"

	// Creates a gRPC enabled client.
	client, err := storage.NewGRPCClient(ctx)
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}
	defer client.Close()

	// Creates the new bucket.
	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()
	if err := client.Bucket(bucketName).Create(ctx, projectID, nil); err != nil {
		log.Fatalf("Failed to create bucket: %v", err)
	}

	fmt.Printf("Bucket %v created.\n", bucketName)
}

A biblioteca de cliente do Go usa automaticamente a conectividade direta quando detecta que o aplicativo está em execução no Google Cloud.

Para saber como usar um cliente gRPC, consulte API gRPC.

Configurar o VPC Service Controls

Se você estiver usando a nuvem privada virtual com endereços IP virtuais restritos (VPC Service Controls) para aumentar a segurança da rede, atualize as regras de firewall para ativar a conectividade direta e otimizar o desempenho entre a instância do Compute Engine e o bucket do Cloud Storage.

Para isso, adicione regras de firewall de lista de permissões para permitir o tráfego em todas as portas para os seguintes blocos CIDR:

• Para o tráfego IPv4: 34.126.0.0/18
• Para o tráfego IPv6: 2001:4860:8040::/42

Além das regras anteriores, mantenha a regra de lista de permissões atual para 199.36.153.4/30.

Se você tiver restrições nas modificações de regras de firewall e não puder atualizá-las, force o tráfego para evitar a conectividade direta usando storage.googleapis.com como o endpoint do Cloud Storage, em vez de google-c2p://storage.googleapis.com.

Por exemplo, para uso em C++, use .set<google::cloud::EndpointOption>(storage.googleapis.com) em vez de google-c2p:///storage.googleapis.com.

Observação : as redes VPC têm uma unidade máxima de transmissão (MTU) padrão de 1460 bytes. Para melhorar a capacidade de processamento, recomendamos aumentar a MTU padrão para pelo menos 4096 bytes. Para mais informações sobre MTUs de rede, consulte a visão geral da unidade de transmissão máxima.

Ativar a observabilidade para solicitações relacionadas ao gRPC

É possível configurar as bibliotecas de cliente do Cloud Storage para gerar métricas relacionadas ao gRPC no Cloud Monitoring. As métricas relacionadas ao gRPC podem ajudar você a:

• Monitorar e otimizar o desempenho das solicitações gRPC para o Cloud Storage.

• Resolver problemas e depurar.

• Receba insights sobre o uso e o comportamento do seu aplicativo.

Para informações sobre como gerar métricas relacionadas ao gRPC, consulte Usar métricas do lado do cliente.

Se a coleta de métricas não for necessária para seu caso de uso, você poderá desativar essa coleta. Para instruções, consulte Desativar as métricas do lado do cliente.

Limitações

• Não é possível enviar solicitações IPv6 por redes legadas.

• A conectividade direta não é compatível ao usar as seguintes versões do GKE em clusters somente IPv4:

  • 1.28, 1.28.0-gke.100 ou mais recente até 1.28.5-gke.1199000
  • 1.27, 1.27.4-gke.1900 ou mais recente
  • 1.26, 1.26.10-gke.1238000 ou mais recente
  • 1.25, 1.25.15-gke.1045000 ou mais recente

• O gRPC não é compatível com os métodos notifications, hmacKeys e serviceAccount.

• As opções de construtor de cliente específicas de HTTP, como WithHTTPClient, não são compatíveis com a biblioteca de cliente do Go.

• A API gRPC não é compatível com endpoints regionais.

Solução de problemas de conectividade direta

Para saber como verificar a conectividade direta e resolver problemas quando ela não estiver disponível, consulte Conectividade direta.

A seguir

• Conecte-se ao conector do Cloud Storage no Serviço Gerenciado para Apache Spark usando gRPC.
• Ative o gRPC no conector de E/S do Apache Beam no Dataflow.