Conectar-se ao Cloud Storage usando o gRPC

O gRPC é um framework RPC universal de alto desempenho e código aberto desenvolvido pelo Google que pode ser usado 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).

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

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 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á sendo executado em 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 sua 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 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 para @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 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 seu 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) das bibliotecas doGoogle Cloud . Para atualizar seu projeto para usar a BOM, use um dos seguintes métodos:

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 Google Cloud

Se você estiver usando a biblioteca de cliente do Cloud Storage com outras bibliotecas Google Cloud , use a BOM das bibliotecas de cliente 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 no gRPC. O cliente Java gRPC usa automaticamente a conectividade direta quando detecta que o aplicativo está sendo executado 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. Use a versão 1.46.0 ou mais recente da biblioteca de cliente Go do Cloud Storage.

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

Para informações sobre 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 (Controles de serviço da VPC) para aumentar a segurança da sua rede, será necessário atualizar as regras de firewall para ativar a conectividade direta e ter um desempenho ideal 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 dos seguintes blocos de CIDR:

  • Para tráfego IPv4: 34.126.0.0/18
  • Para 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 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.

É 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:

  • Monitore e otimize a performance das solicitações gRPC para o Cloud Storage.

  • Resolver e depurar problemas.

  • 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 não for necessário coletar métricas para seu caso de uso, você poderá desativar a 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.

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

Solução de problemas de conectividade direta

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

A seguir