Conectar-se ao Cloud Storage usando o gRPC

gRPC é uma biblioteca RPC universal de código aberto e alto desempenho desenvolvida pelo Google que pode ser usada para definir seus serviços usando buffers de protocolo. É possível usar o gRPC para interagir com o Cloud Storage. O gRPC utiliza conectividade direta entre instâncias do Compute Engine e buckets do Cloud Storage, ignorando os front-ends do Google (GFEs).

**Observação** :para cargas de trabalho de análise Google Cloud, o gRPC melhora a performance de leitura do Cloud Storage somente quando a instância do Compute Engine e o bucket do Cloud Storage estão na mesma região.

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

• Conector do Cloud Storage no Managed Service for 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 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 um 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 usar as versões 2.10.0 ou mais recentes do Cloud Storage FUSE.

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 mais recente

   • 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 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 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 momento da compilação.

      cmake -DGOOGLE_CLOUD_CPP_ENABLE=storage_grpc [other options here]
      

   2. No 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 do 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 do 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 conectividade direta.

Atualizar seu projeto para usar a BOM

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

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

Cloud Storage independente

Se você estiver usando a biblioteca de cliente do Cloud Storage de forma independente (sem outras Google Cloud bibliotecas), 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 Google Cloud bibliotecas

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

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 no gRPC. O cliente Java do gRPC usa automaticamente a conectividade direta quando detecta que o aplicativo está em execução em 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. Verifique se você está usando a biblioteca de cliente do Cloud Storage Go versão 1.46.0 ou mais recente.

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 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 Go usa automaticamente a conectividade direta quando detecta que o aplicativo está em execução em Google Cloud.

Para informações sobre como usar um cliente gRPC, consulte a 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, é necessário atualizar as regras de firewall para ativar a conectividade direta para uma performance ideal entre a instância do Compute Engine e o bucket do Cloud Storage.

Para fazer isso, adicione regras de firewall de lista de permissões para permitir o tráfego em todas as portas dos 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 atualizar elas, force o tráfego a 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 de transmissão máxima (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 fazer o seguinte:

• Monitorar e otimizar a performance de solicitações gRPC para o Cloud Storage.

• Resolver e depurar problemas.

• Gerar insights sobre o uso e o comportamento do 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 a coleta de métricas. Para instruções, consulte Desativar as métricas do lado do cliente.

Limitações

• As solicitações IPv6 não podem ser enviadas 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 oferece suporte aos métodos notifications, hmacKeys e serviceAccount.

• As opções de construtor de cliente específicas de HTTP, como WithHTTPClient, são indisponíveis para a biblioteca de cliente 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 solucionar problemas quando ela não estiver disponível, consulte Conectividade direta.

A seguir

• Conecte-se ao conector do Cloud Storage no Managed Service for Apache Spark usando o gRPC.
• Ative o gRPC no conector de E/S do Apache Beam no Dataflow.