Intégration d’Amazon Glue à ClickHouse et Spark

Compatible avec ClickHouse

Amazon Glue est un service d’intégration de données serverless entièrement géré proposé par Amazon Web Services (AWS). Il simplifie la découverte, la préparation et la transformation des données pour l’analytics, le machine learning et le développement d’applications.

Installation

Pour intégrer votre code Glue à ClickHouse, vous pouvez utiliser notre connecteur Spark officiel dans Glue de l’une des façons suivantes :

Installer le connecteur ClickHouse Glue depuis AWS Marketplace (recommandé).
Ajouter manuellement les JARs du connecteur Spark à votre job Glue.

Accorder les autorisations requises

Assurez-vous que le rôle IAM de votre job Glue dispose des autorisations nécessaires, comme indiqué dans le guide sur les privilèges minimaux.

Activer le connecteur et créer une connexion

Après vous être abonné, sélectionnez la version de Glue qui correspond aux exigences de votre job. Dans la section Additional details, sous Usage instructions, cliquez sur le lien Open Glue Studio - Add ClickHouse connector. Cela ouvre la page de création de connexion Glue avec les champs principaux préremplis. Donnez un nom à la connexion, puis cliquez sur create (inutile de fournir les informations de connexion à ClickHouse à ce stade).

AWS Marketplace usage instructions for ClickHouse Glue connector

Utiliser dans un job Glue

Dans votre job Glue, sélectionnez l’onglet Job details, puis développez la section Advanced properties. Dans la section Connections, sélectionnez la connexion que vous venez de créer. Le connecteur injecte automatiquement les JARs requis dans l’environnement d’exécution du job.

Pour ajouter manuellement les JARs requis, procédez comme suit :

Téléverser le JAR du connecteur

Téléversez le JAR le plus récent du connecteur Spark (clickhouse-spark-runtime-3.X_2.X-0.10.X.jar) dans un bucket S3.

Accorder l’accès au bucket S3

Assurez-vous que le job Glue a accès à ce bucket.

Configurer le chemin des JARs dépendants

Dans l’onglet Job details, faites défiler vers le bas et développez le menu déroulant Advanced properties, puis indiquez le chemin des JARs dans Dependent JARs path :

Utiliser AWS Secrets Manager pour les identifiants

Au lieu d’inscrire en dur votre nom d’utilisateur et votre mot de passe ClickHouse dans le job, stockez-les dans AWS Secrets Manager et référencez le secret depuis votre connexion Glue ou le script du job. À l’exécution, Glue récupère le secret et fusionne ses paires clé-valeur avec les options de connexion du connecteur.

Créer le secret

Dans AWS Secrets Manager, créez un secret de type Autre type de secret avec des paires clé-valeur dont les clés correspondent aux noms des options du connecteur :

Clé	Valeur
`user`	votre nom d’utilisateur ClickHouse
`password`	votre mot de passe ClickHouse

Toute clé que vous ajoutez au secret est transmise au connecteur. Vous pouvez donc également y stocker host, database ou toute autre option si vous souhaitez ne pas les conserver dans le code.

Référencer le secret

Il existe deux façons d’intégrer le secret à un job.

Option 1 : l’attacher à la connexion Glue. Lors de la création ou de la modification de la connexion à ClickHouse dans Glue Studio, définissez le champ AWS secret sur le nom du secret. Tout job qui utilise cette connexion récupère automatiquement le secret — aucune modification du code n’est nécessaire.

Option 2 : transmettre secretId dans les options de connexion. Utilisez cette méthode lorsque le secret n’est pas attaché à la connexion. Ajoutez secretId en plus de connectionName :

source = glueContext.create_dynamic_frame.from_options(
    connection_type="marketplace.spark",
    connection_options={
        "connectionName": "<your-connection-name>",
        "secretId": "clickhouse/glue/credentials",
        "database": "default",
        "table": "example_table"
    },
    transformation_ctx="clickhouse_source"
)

val source = glueContext.getSource(
  connectionType = "marketplace.spark",
  connectionOptions = JsonOptions(Map(
    "connectionName" -> "<your-connection-name>",
    "secretId" -> "clickhouse/glue/credentials",
    "database" -> "default",
    "table" -> "example_table"
  )),
  transformationContext = "clickhouseSource"
)

Les clés user et password du secret sont fusionnées avec les options du connecteur à l’exécution, vous n’avez donc jamais besoin de les lire dans votre script.

Exemples

Les exemples ci-dessous utilisent marketplace.spark et font référence au connecteur via connectionName. Si vous avez installé le connecteur manuellement (onglet Installation manuelle), utilisez connection_type="custom.spark" et indiquez directement className, host, http_port, user et password dans les options.

Si vous avez associé un secret AWS à la connexion elle-même (option 1 dans Utilisation d'AWS Secrets Manager pour les identifiants), supprimez secretId des options — Glue récupère automatiquement les identifiants depuis la connexion.

Vous pouvez utiliser le connecteur ClickHouse comme source ou comme cible dans l'éditeur visuel de Glue Studio. Faites simplement glisser le composant ClickHouse Spark Connector sur le canevas et reliez-le à votre pipeline de données.

Éditeur visuel de Glue Studio avec le connecteur ClickHouse

import com.amazonaws.services.glue.GlueContext
import com.amazonaws.services.glue.util.{GlueArgParser, Job, JsonOptions}
import org.apache.spark.SparkContext
import scala.collection.JavaConverters._

object ClickHouseGlueExample {
  def main(sysArgs: Array[String]): Unit = {
    val args = GlueArgParser.getResolvedOptions(sysArgs, Seq("JOB_NAME").toArray)

    val sc = new SparkContext()
    val glueContext = new GlueContext(sc)
    Job.init(args("JOB_NAME"), glueContext, args.asJava)

    val readOptions = JsonOptions(Map(
      "connectionName" -> "<your-connection-name>",
      "secretId" -> "clickhouse/glue/credentials",
      "database" -> "default",
      "table" -> "example_table"
    ))

    val source = glueContext.getSource(
      connectionType = "marketplace.spark",
      connectionOptions = readOptions,
      transformationContext = "clickhouseSource"
    )
    val dyf = source.getDynamicFrame()

    val writeOptions = JsonOptions(Map(
      "connectionName" -> "<your-connection-name>",
      "secretId" -> "clickhouse/glue/credentials",
      "database" -> "default",
      "table" -> "target_table"
    ))

    glueContext.getSink(
      connectionType = "marketplace.spark",
      connectionOptions = writeOptions
    ).writeDynamicFrame(dyf)

    Job.commit()
  }
}

import sys
from awsglue.utils import getResolvedOptions
from pyspark.context import SparkContext
from awsglue.context import GlueContext
from awsglue.job import Job

args = getResolvedOptions(sys.argv, ['JOB_NAME'])

sc = SparkContext()
glueContext = GlueContext(sc)
logger = glueContext.get_logger()
job = Job(glueContext)
job.init(args['JOB_NAME'], args)

read_options = {
    "connectionName": "<your-connection-name>",
    "secretId": "clickhouse/glue/credentials",
    "database": "default",
    "table": "example_table"
}

source = glueContext.create_dynamic_frame.from_options(
    connection_type="marketplace.spark",
    connection_options=read_options,
    transformation_ctx="clickhouse_source"
)
dyf = source

logger.info(f"Read {dyf.count()} rows from ClickHouse")

write_options = {
    "connectionName": "<your-connection-name>",
    "secretId": "clickhouse/glue/credentials",
    "database": "default",
    "table": "target_table"
}

glueContext.write_dynamic_frame.from_options(
    frame=dyf,
    connection_type="marketplace.spark",
    connection_options=write_options,
    transformation_ctx="clickhouse_sink"
)

job.commit()

Pour plus de détails, consultez notre documentation Spark.