Se connecter à Cloud Storage à l'aide de gRPC

gRPC est un framework RPC universel Open Source hautes performances développé par Google. Il vous permet de définir vos services à l'aide de Protocol Buffers. Vous pouvez utiliser gRPC pour interagir avec Cloud Storage. gRPC utilise la connectivité directe entre les instances Compute Engine et les buckets Cloud Storage, en contournant les Google Front Ends (GFE).

Vous pouvez vous connecter à Cloud Storage à l'aide de gRPC via les clients compatibles suivants :

Activer gRPC sur une bibliothèque cliente

C++

Avant de commencer

  1. Assurez-vous que les versions suivantes sont installées :

    • gRPC version 1.65.1 ou ultérieure

    • Bibliothèque cliente C++ version v2.30.0 ou ultérieure

    • C++ version 14 ou ultérieure

    Pour obtenir des instructions d'installation, consultez Configurer un environnement de développement C++.

  2. Configurez l'authentification.

  3. Assurez-vous que chaque instance Compute Engine est associée à un compte de service, même si ce compte ne dispose d'aucune autorisation. Ce compte de service est utilisé pour représenter l'instance Compute Engine dans le processus de handshake Application Layer Transport Security (ALTS). Il est requis pour la connectivité directe.

Configurer la bibliothèque cliente C++

  1. Créez un client gRPC à l'aide de gcs::MakeGrpcClient() :

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

    La bibliothèque cliente C++ utilise automatiquement la connectivité directe lorsqu'elle détecte que l'application s'exécute sur Google Cloud.

  2. Pour configurer la bibliothèque cliente C++ afin qu'elle utilise gRPC, activez le client gRPC Cloud Storage pour mettre à jour la configuration de votre système de compilation pour CMake ou Bazel.

    CMake

    1. Activez le plug-in client gRPC Cloud Storage au moment de la compilation.

      cmake -DGOOGLE_CLOUD_CPP_ENABLE=storage_grpc [other options here]
      
    2. Dans votre code, pour la commande target_link_libraries(), remplacez google-cloud-cpp::storage par google-cloud-cpp::storage_grpc.

      Par exemple, le programme de démarrage rapide pour gRPC utilise le code suivant :

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

    Bazel

    Remplacez les dépendances de @google_cloud_cpp//:storage par @google_cloud_cpp//:storage_grpc.

    Par exemple, le programme de démarrage rapide pour gRPC utilise le code suivant :

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

Java

Avant de commencer

  1. Assurez-vous que les versions suivantes sont installées :

    • Bibliothèques clientes Java :

      • com.google.cloud:google-cloud-storage:2.43.1 ou version ultérieure.
      • com.google.cloud:libraries-bom:26.48 ou version ultérieure.
    • Java 8 ou version ultérieure

    Pour obtenir des instructions d'installation, consultez Configurer un environnement de développement Java.

  2. Configurez l'authentification.

  3. Assurez-vous que chaque instance Compute Engine est associée à un compte de service, même si ce compte ne dispose d'aucune autorisation. Ce compte de service est utilisé pour représenter l'instance Compute Engine dans le processus de handshake Application Layer Transport Security (ALTS). Il est requis pour la connectivité directe.

Mettre à jour votre projet pour utiliser la BOM

Pour vous assurer que vos projets disposent de versions compatibles des bibliothèques clientes Google Cloud , utilisez les versions spécifiées dans la nomenclature (BOM) des bibliothèquesGoogle Cloud . Pour mettre à jour votre projet afin d'utiliser la BOM, utilisez l'une des méthodes suivantes :

Cloud Storage autonome

Si vous utilisez la bibliothèque cliente Cloud Storage de manière indépendante (sans d'autres bibliothèquesGoogle Cloud ), utilisez la BOM spécifique à la bibliothèque cliente Cloud Storage.

Maven

Importez la BOM dans la section dependencyManagement de votre fichier pom.xml.

L'exemple suivant montre comment importer le BOM et inclure l'artefact 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

Ajoutez une dépendance de plate-forme sur 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 avec d'autres bibliothèques Google Cloud

Si vous utilisez la bibliothèque cliente Cloud Storage avec d'autres bibliothèques Google Cloud , utilisez la BOM des bibliothèques clientes Google Cloud .

Maven

Importez la BOM dans la section dependencyManagement de votre fichier pom.xml.

L'exemple suivant montre comment importer le BOM et inclure l'artefact 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

Ajoutez une dépendance de plate-forme sur com.google.cloud:libraries-bom :

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

Créer un client gRPC

L'exemple suivant utilise un compilateur axé sur gRPC. Le client gRPC Java utilise automatiquement la connectivité directe lorsqu'il détecte que l'application s'exécute sur 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

Avant de commencer

  1. Configurez votre environnement de développement.

  2. Assurez-vous d'utiliser la version 1.46.0 ou ultérieure de la bibliothèque cliente Go Cloud Storage.

  3. Configurez l'authentification.

  4. Assurez-vous que chaque instance Compute Engine est associée à un compte de service, même si ce compte ne dispose d'aucune autorisation. Ce compte de service est utilisé pour représenter l'instance Compute Engine dans le processus de handshake Application Layer Transport Security (ALTS). Il est requis pour la connectivité directe.

Créer un client gRPC

Pour utiliser le client, vous devez appeler le constructeur NewGRPCClient dans votre application au lieu 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)
}

La bibliothèque cliente Go utilise automatiquement la connectivité directe lorsqu'elle détecte que l'application s'exécute sur Google Cloud.

Pour savoir comment utiliser un client gRPC, consultez API gRPC.

Configurez VPC Service Controls

Si vous utilisez un cloud privé virtuel avec des adresses IP virtuelles restreintes (VPC Service Controls) pour renforcer la sécurité de votre réseau, vous devez mettre à jour vos règles de pare-feu afin d'activer la connectivité directe pour des performances optimales entre votre instance Compute Engine et votre bucket Cloud Storage.

Pour ce faire, ajoutez des règles de pare-feu à la liste d'autorisation afin d'autoriser le trafic sur tous les ports pour les blocs CIDR suivants :

  • Pour le trafic IPv4 : 34.126.0.0/18
  • Pour le trafic IPv6 : 2001:4860:8040::/42

En plus des règles précédentes, conservez la règle de liste d'autorisation existante pour 199.36.153.4/30.

Si vous avez des restrictions sur les modifications des règles de pare-feu et que vous ne pouvez pas les mettre à jour, vous pouvez forcer le trafic à éviter la connectivité directe en utilisant storage.googleapis.com comme point de terminaison Cloud Storage au lieu de google-c2p://storage.googleapis.com.

Par exemple, pour C++, utilisez .set<google::cloud::EndpointOption>(storage.googleapis.com) au lieu de google-c2p:///storage.googleapis.com.

Vous pouvez configurer les bibliothèques clientes Cloud Storage pour générer des métriques liées à gRPC dans Cloud Monitoring. Les métriques liées à gRPC peuvent vous aider à effectuer les opérations suivantes :

  • Surveillez et optimisez les performances des requêtes gRPC adressées à Cloud Storage.

  • Résolvez et déboguez les problèmes.

  • Obtenez des insights sur l'utilisation et le comportement de votre application.

Pour savoir comment générer des métriques liées à gRPC, consultez Utiliser des métriques côté client.

Si la collecte de métriques n'est pas nécessaire pour votre cas d'utilisation, vous pouvez choisir de la désactiver. Pour obtenir des instructions, consultez Désactiver les métriques côté client.

Limites

  • Les requêtes IPv6 ne peuvent pas être envoyées sur les anciens réseaux.

  • La connectivité directe n'est pas compatible avec les versions GKE suivantes sur les clusters IPv4 uniquement :

    • 1.28, 1.28.0-gke.100 ou version ultérieure jusqu'à 1.28.5-gke.1199000
    • 1.27, 1.27.4-gke.1900 ou version ultérieure
    • 1.26, 1.26.10-gke.1238000 ou versions ultérieures
    • 1.25, 1.25.15-gke.1045000 ou versions ultérieures
  • gRPC n'est pas compatible avec les méthodes notifications, hmacKeys et serviceAccount.

  • Les options de constructeur de client HTTP spécifiques, telles que WithHTTPClient, ne sont pas compatibles avec la bibliothèque cliente Go.

Résoudre les problèmes de connectivité directe

Pour savoir comment vérifier la connectivité directe et résoudre les problèmes lorsqu'elle n'est pas disponible, consultez Connectivité directe.

Étapes suivantes