Un connecteur de récepteur Cloud Storage diffuse les données de Managed Service pour Apache Kafka vers Cloud Storage, ce qui vous permet de stocker et de traiter de grands volumes de données de manière économique et évolutive.
Voici des cas d'utilisation typiques de ce connecteur :
Ingestion de lacs de données. Stockez les données Kafka dans un lac de données pour l'archivage à long terme et le traitement par lot.
Archiver des données pour répondre aux exigences réglementaires
Avant de commencer
Avant de créer un connecteur de récepteur Cloud Storage, assurez-vous de disposer des éléments suivants :
Créez un cluster Managed Service pour Apache Kafka pour votre cluster Connect. Il s'agit du cluster Kafka principal associé au cluster Connect. Il s'agit également du cluster source qui forme une extrémité du pipeline du connecteur.
Créez un cluster Connect pour héberger votre connecteur de récepteur Cloud Storage.
Créez un bucket Cloud Storage pour stocker les données diffusées depuis Kafka.
Créez et configurez un sujet Kafka dans le cluster source. Les données sont transférées de ce sujet Kafka vers le bucket Cloud Storage de destination.
Rôles et autorisations nécessaires
Pour obtenir les autorisations nécessaires pour créer un connecteur, demandez à votre administrateur de vous accorder le rôle IAM Éditeur de connecteur Kafka géré (roles/managedkafka.connectorEditor) sur votre projet.
Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.
Ce rôle prédéfini contient les autorisations requises pour créer un connecteur. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :
Autorisations requises
Les autorisations suivantes sont requises pour créer un connecteur :
-
Créez un connecteur :
managedkafka.connectors.create
Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.
Accorder des autorisations d'écriture dans le bucket Cloud Storage
L'agent de service Managed Kafka doit disposer des autorisations suivantes pour écrire des messages dans le bucket Cloud Storage :
storage.objects.createstorage.objects.delete
Pour accorder ces autorisations, attribuez à l'agent de service le rôle Utilisateur d'objets Storage (roles/storage.objectUser) sur le projet contenant le bucket Cloud Storage.
Si votre cluster Connect se trouve dans un projet différent de votre cluster Managed Service pour Apache Kafka, consultez Créer un cluster Connect dans un autre projet.
Créer un connecteur de récepteur Cloud Storage
Pour créer un connecteur de récepteur Cloud Storage, procédez comme suit :
Console
Dans la console Google Cloud , accédez à la page Connecter des clusters.
Cliquez sur le cluster Connect dans lequel vous souhaitez créer le connecteur.
Cliquez sur Créer un connecteur.
Dans le champ Nom du connecteur, saisissez un nom pour le connecteur.
Dans la liste Plug-in de connecteur, sélectionnez Cloud Storage Sink.
Dans la section Topics (Sujets), spécifiez les sujets Kafka à partir desquels le connecteur lit. Vous pouvez sélectionner des sujets individuels ou utiliser une expression régulière.
-
Pour sélectionner des thèmes individuels :
- Cliquez sur Sélectionner une liste de sujets Kafka.
- Sélectionnez un ou plusieurs sujets.
- Cliquez sur OK.
-
Pour utiliser une expression régulière :
- Cliquez sur Utiliser une expression régulière de sujet.
- Dans le champ Expression régulière du sujet, saisissez une expression régulière. Le connecteur lit tous les sujets qui correspondent à l'expression.
-
Dans le champ Bucket GCS, saisissez le chemin d'accès à un bucket Cloud Storage dans lequel le connecteur écrit des données, ou cliquez sur Parcourir pour sélectionner le bucket.
Facultatif : Dans le champ Configurations, ajoutez des propriétés de configuration ou modifiez les propriétés par défaut. Pour en savoir plus, consultez Configurer le connecteur.
Facultatif : sous Règle de redémarrage des tâches, sélectionnez la règle de redémarrage des tâches du connecteur. Pour en savoir plus, consultez Règle de redémarrage des tâches.
Cliquez sur Créer.
gcloud
Exécutez la commande gcloud
managed-kafka connectors create :
gcloud managed-kafka connectors create CONNECTOR_ID \
--connect-cluster=CONNECT_CLUSTER_ID \
--location=LOCATION \
--config-file=CONFIG_FILE
Remplacez les éléments suivants :
CONNECTOR_ID: ID ou nom du connecteur.CONNECT_CLUSTER_ID: ID du cluster Connect dans lequel le connecteur est créé.LOCATION: emplacement du cluster Connect.CONFIG_FILE: chemin d'accès à un fichier de configuration YAML ou JSON local.
Voici un exemple de fichier de configuration pour le connecteur récepteur Cloud Storage :
connector.class: "io.aiven.kafka.connect.gcs.GcsSinkConnector"
gcs.bucket.name: "BUCKET_NAME"
gcs.credentials.default: "true"
format.output.type: "json"
key.converter: "org.apache.kafka.connect.storage.StringConverter"
value.converter: "org.apache.kafka.connect.json.JsonConverter"
value.converter.schemas.enable: "false"
topics: "TOPIC_LIST"
tasks.max: "3"
Remplacez les éléments suivants :
BUCKET_NAME: nom du bucket Cloud Storage dans lequel écrire.TOPIC_LIST: liste de sujets Kafka à partir desquels lire, séparés par une virgule. La liste peut également inclure des expressions régulières.
Terraform
Vous pouvez utiliser une ressource Terraform pour créer un connecteur.
Pour savoir comment appliquer ou supprimer une configuration Terraform, consultez Commandes Terraform de base.
Go
Avant d'essayer cet exemple, suivez les instructions de configuration pour Go dans Installer les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Go Managed Service pour Apache Kafka.
Pour vous authentifier auprès de Managed Service pour Apache Kafka, configurez les Identifiants par défaut de l'application (ADC). Pour en savoir plus, consultez Configurer les ADC pour un environnement de développement local.
Java
Avant d'essayer cet exemple, suivez les instructions de configuration pour Java décrites dans Installer les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Java Managed Service pour Apache Kafka.
Pour vous authentifier auprès de Managed Service pour Apache Kafka, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer les ADC pour un environnement de développement local.
Python
Avant d'essayer cet exemple, suivez les instructions de configuration pour Python dans Installer les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Python de Managed Service pour Apache Kafka.
Pour vous authentifier auprès de Managed Service pour Apache Kafka, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer les ADC pour un environnement de développement local.
Configurer le connecteur
Pour obtenir la liste complète des propriétés spécifiques à ce connecteur, consultez la section Configuration dans la documentation du connecteur Cloud Storage Sink.
Output fields
Par défaut, le connecteur n'écrit que la valeur de chaque enregistrement Kafka.
Pour inclure des clés ou des en-têtes d'enregistrement, définissez la propriété format.output.fields sur une liste de champs à inclure, séparés par une virgule. Les champs acceptés sont key, value, headers et timestamp. Exemple :
format.output.fields=key,value,headers
Formats de sortie
Le connecteur permet d'écrire des enregistrements Kafka au format CSV, JSON et Parquet. Les sections suivantes expliquent comment configurer le format de sortie.
Format CSV
Pour écrire des fichiers CSV dans Cloud Storage, définissez format.output.type=csv.
Utilisez les convertisseurs suivants :
Convertisseur de clé :
org.apache.kafka.connect.storage.StringConverterouorg.apache.kafka.connect.json.JsonConverterConvertisseur de valeur :
org.apache.kafka.connect.converters.ByteArrayConverter
Format JSON
Pour écrire des fichiers au format JSON dans Cloud Storage, définissez format.output.type sur l'une des valeurs suivantes :
json: chaque fichier de sortie contient un seul tableau d'objets JSON, où chaque objet JSON représente un enregistrement Kafka.jsonl: le connecteur écrit chaque enregistrement Kafka en tant qu'objet JSON sur une ligne distincte.
L'exemple suivant montre comment le connecteur écrit un enregistrement Kafka au format JSON :
{"headers":[{"key":"k1","value":"v1"},{"key":"k2","value":"v2"}],"value":"Hello world","key":"my-key"}
Si vous définissez le convertisseur de clé ou de valeur sur org.apache.kafka.connect.converters.ByteArrayConverter, le connecteur écrit ce champ en tant que valeur encodée en base64.
Le connecteur n'inclut pas de schéma JSON dans la sortie, même si value.converter.schemas.enable est défini sur true.
Format Parquet
Pour écrire des fichiers Parquet dans Cloud Storage, définissez format.output.type=parquet.
Si le convertisseur de clé ou de valeur est org.apache.kafka.connect.json.JsonConverter, les données JSON doivent inclure un schéma. Définissez la propriété schemas.enable du convertisseur sur true.
Pour les données JSON, le connecteur écrit les données en tant que type struct dans le fichier Parquet. Par exemple, si la valeur de l'enregistrement Kafka comporte un champ nommé userid, le connecteur écrit une colonne nommée value.userid. Pour aplatir les noms de colonnes, définissez format.output.envelope=false. Si format.output.envelope est défini sur false, format.output.fields doit spécifier un seul champ de sortie.
Paramètres des fichiers Cloud Storage
Les paramètres suivants contrôlent la manière dont le connecteur écrit des fichiers dans Cloud Storage.
gcs.bucket.name: valeur obligatoire. Spécifie le nom du bucket Cloud Storage dans lequel le connecteur écrit les données.file.compression.type: spécifie le type de compression des fichiers de sortie. Par exemple,gzip,snappy,zstdetnone. La valeur par défaut estnone.file.name.prefix: spécifie un préfixe à ajouter au nom de chaque fichier. La valeur par défaut est vide ("").file.name.template: spécifie un modèle pour le nom de fichier. Le connecteur accepte les variables d'espace réservé pour le modèle, telles que{{topic}}pour le nom du sujet et{{partition}}pour le numéro de partition. Pour en savoir plus, consultez la documentation du connecteur de récepteur Cloud Storage.file.max.records: nombre maximal d'enregistrements à écrire dans un seul fichier. Si la valeur est 0, il n'y a pas de maximum spécifique. La valeur par défaut est 0.file.max.bytes: taille maximale du fichier à écrire, en octets. Si la valeur est 0, il n'y a pas de maximum spécifique. La valeur par défaut est 0.
Regroupement d'enregistrements
Lorsque le connecteur de récepteur Cloud Storage écrit des enregistrements Kafka, il les regroupe par défaut par sujet et par partition. Par exemple, les enregistrements de la partition 0 du sujet my-topic sont écrits dans des fichiers nommés my-topic-0-OFFSET, où OFFSET est le décalage de départ.
Si le paramètre file.name.template inclut la variable d'espace réservé {{key}}, le connecteur regroupe les enregistrements par clé. Dans ce mode, le connecteur écrit un fichier distinct pour chaque clé d'enregistrement. Le connecteur écrase chaque fichier avec le dernier enregistrement de cette clé.
Identifiants
La propriété gcs.credentials.default doit être définie sur true. Ce paramètre permet au connecteur de découvrir automatiquement les identifiants Google Cloud .