Configuration personnalisée pour AWS

Déployez ClickHouse BYOC dans votre VPC AWS existant

​

VPC géré par le client (BYO-VPC) pour AWS

Si vous préférez utiliser un VPC existant pour déployer ClickHouse BYOC plutôt que de laisser ClickHouse Cloud créer un nouveau VPC, suivez les étapes ci-dessous. Cette approche vous offre un contrôle accru sur votre configuration réseau et vous permet d’intégrer ClickHouse BYOC à votre infrastructure réseau existante.

1. Configurez votre VPC existant

   1. Ajoutez le tag clickhouse-byoc="true" à votre VPC.
   2. Allouez exactement 3 sous-réseaux privés répartis sur 3 zones de disponibilité différentes pour que ClickHouse Cloud puisse les utiliser.
   3. Assurez-vous que chaque sous-réseau dispose d’une plage CIDR minimale de /25 (par ex. 10.0.0.0/25). Un /25 prend en charge environ 10 nœuds de serveur ClickHouse par zone de disponibilité ; /24 est recommandé pour la plupart des déploiements, et des sous-réseaux plus grands pour les déploiements dont vous prévoyez la croissance. Les adresses IP des pods sont allouées à partir du sous-réseau lui-même, donc chaque réplique consomme des adresses du sous-réseau.
   4. Ajoutez les tags kubernetes.io/role/internal-elb=1 et clickhouse-byoc="true" à chaque sous-réseau afin de permettre une configuration correcte de l’équilibreur de charge.
2. Configurez le point de terminaison Gateway S3

   Si votre VPC n’a pas encore de point de terminaison Gateway S3 configuré, vous devrez en créer un pour permettre une communication sécurisée et privée entre votre VPC et Amazon S3. Ce point de terminaison permet à vos services ClickHouse d’accéder à S3 sans passer par l’internet public. Reportez-vous à la capture d’écran ci-dessous pour voir un exemple de configuration.

3. Assurez la connectivité réseau

   Accès sortant à internet Votre VPC doit au minimum autoriser l’accès sortant à internet, soit directement, soit via une NAT gateway. Deux éléments en dépendent :

   • Tailscale. Les composants BYOC de ClickHouse s’enregistrent auprès du plan de contrôle Tailscale, qui fournit un réseau sécurisé de type zero trust pour les opérations de gestion privées, sans nécessiter d’accès public entrant. L’enregistrement initial et la configuration nécessitent une connectivité à l’internet public.
   • Images de conteneur. Certaines images exécutées par le déploiement ne sont pas répliquées dans le registry BYOC, notamment les images communautaires, et sont récupérées depuis leurs registries upstream.

   Un VPC sans chemin sortant n’achèvera pas son provisionnement. Il n’existe pas de liste de points de terminaison publiée ; si votre politique réseau exige un inventaire explicite, contactez le support pour examiner votre configuration.

   Résolution DNS Assurez-vous que votre VPC dispose d’une résolution DNS fonctionnelle et qu’il ne bloque pas, ne perturbe pas et ne remplace pas les noms DNS standard. ClickHouse BYOC s’appuie sur DNS pour résoudre les serveurs de contrôle Tailscale et les points de terminaison de service ClickHouse. Si DNS n’est pas disponible ou est mal configuré, les services BYOC risquent de ne pas pouvoir se connecter ou fonctionner correctement.

4. Configurez votre compte AWS

   La configuration initiale de BYOC crée un rôle IAM privilégié (ClickHouseManagementRole) qui permet aux contrôleurs BYOC de ClickHouse Cloud de gérer votre infrastructure. Cela peut être effectué à l’aide d’un CloudFormation template ou d’un module Terraform (voir ci-dessous).

   Le nom du rôle IAM est une exigence stricte. Le rôle doit conserver son nom par défaut, ClickHouseManagementRole — sans préfixes, suffixes ni renommage pour respecter une convention de nommage organisationnelle — sauf si ClickHouse a explicitement convenu au préalable d’un nom différent (l’entrée Terraform role_name ne doit être modifiée qu’en coordination avec ClickHouse). Un rôle renommé est appliqué avec succès, mais le provisionnement échoue ensuite, car ClickHouse ne peut pas assumer le rôle attendu. Plus généralement, ne modifiez rien dans le template ou le module fourni sans l’approbation explicite de ClickHouse ; les personnalisations prises en charge sont exposées sous forme de paramètres.

   Lors d’un déploiement dans une configuration BYO-VPC, définissez le paramètre IncludeVPCWritePermissions sur false afin de garantir que ClickHouse Cloud ne reçoive pas les autorisations lui permettant de modifier votre VPC géré par le client.

   Les buckets de stockage, le cluster Kubernetes et les ressources de calcul nécessaires à l’exécution de ClickHouse ne sont pas inclus dans cette configuration initiale. Ils seront provisionnés à une étape ultérieure. Même si vous contrôlez votre VPC, ClickHouse Cloud a toujours besoin d’autorisations IAM pour créer et gérer le cluster Kubernetes, les rôles IAM pour les comptes de service, les buckets S3 et d’autres ressources essentielles dans votre compte AWS.

   ​

   Module Terraform

   Si vous préférez utiliser Terraform plutôt que CloudFormation, utilisez le module terraform-byoc-onboarding :

   module "clickhouse_onboarding" {
     source                        = "github.com/ClickHouse/terraform-byoc-onboarding.git//modules/aws?ref=<version>"
     external_id                   = "<external-id-provided-by-clickhouse>"
     include_vpc_write_permissions = false
   }
   

   Remplacez <version> par le tag le plus récent de la page des releases du module — utilisez toujours la dernière release.

   Le module génère clickhouse_management_role_arn. Dans le flux standard, vous n’avez rien à faire avec cette valeur — l’onboarding se poursuit dans la console ClickHouse Cloud — mais conservez-la à portée de main : ClickHouse vous la demandera si votre configuration s’écarte des valeurs par défaut (par exemple, en cas de nom de rôle personnalisé coordonné).

   La valeur external_id est générée par la console ClickHouse Cloud et est partagée par toutes les infrastructures BYOC du même compte AWS. Consultez ID externe AWS pour en savoir plus, notamment sur l’espace réservé legacy emptyid.

   Le module était auparavant distribué sous forme d’archive tar à l’adresse https://s3.us-east-2.amazonaws.com/clickhouse-public-resources.clickhouse.cloud/tf/byoc.tar.gz. Cette URL reste disponible, mais est obsolète — utilisez le module GitHub ci-dessus.

5. Configurez l’infrastructure BYOC

   Lorsque vous cliquez sur Set up Infrastructure, ClickHouse Cloud exécute automatiquement une validation préalable avant le provisionnement. Si votre VPC personnalisé ou votre compte ne répond pas aux exigences, la configuration est interrompue et les problèmes à corriger sont indiqués.

   Dans la console ClickHouse Cloud, configurez les éléments suivants lors de la mise en place d’une nouvelle infrastructure :

   1. Sous VPC configuration, sélectionnez Use existing VPC.
   2. Saisissez votre VPC ID (par ex. vpc-0bb751a5b888ad123).
   3. Saisissez les Private subnet IDs pour les 3 sous-réseaux que vous avez configurés précédemment.
   4. Si nécessaire, saisissez également les Public subnet IDs si votre configuration requiert des équilibreurs de charge exposés publiquement.
   5. Cliquez sur Set up Infrastructure pour lancer le provisionnement.

   La configuration d’une nouvelle région peut prendre jusqu’à 40 minutes.

​

Sous-réseaux partagés depuis un autre compte (AWS RAM)

Vous pouvez exécuter BYOC dans un compte satellite (spoke) sur des sous-réseaux partagés depuis un compte central (hub) avec AWS Resource Access Manager (RAM), ce qui permet de centraliser la gestion du réseau. La configuration est identique à celle décrite ci-dessus, à deux différences près, qui découlent du fonctionnement des partages RAM :

• Appliquez les tags depuis le compte spoke. Les ressources partagées via RAM ont une vue des tags propre à chaque compte : les tags appliqués dans le compte hub ne sont donc pas visibles depuis le compte spoke. Appliquez clickhouse-byoc="true" au VPC, ainsi que kubernetes.io/role/internal-elb=1 et clickhouse-byoc="true" à chaque sous-réseau partagé, depuis le compte spoke. Faute de quoi, la validation préalable signalera des tags manquants et le provisionnement échouera.
• Le routage reste à la charge du compte hub. Les route tables des sous-réseaux partagés restent la propriété du compte hub, qui est donc responsable du NAT et du routage de l’egress, ainsi que du endpoint gateway S3, puisqu’il s’agit d’une ressource de niveau VPC. Vérifiez que les sous-réseaux partagés répondent toujours à l’exigence de connectivité sortante indiquée ci-dessus.

Tout le reste est inchangé : trois private subnets répartis sur trois availability zones, un CIDR minimal de /25 par sous-réseau, et la configuration de ClickHouseManagementRole dans le compte spoke où s’exécute la infrastructure BYOC.

​

Rôles IAM gérés par le client

Pour les organisations ayant des exigences de sécurité avancées ou des politiques de conformité strictes, vous pouvez fournir vos propres rôles IAM au lieu de laisser ClickHouse Cloud les créer. Cette approche vous donne un contrôle total sur les permissions IAM et vous permet d’appliquer les politiques de sécurité de votre organisation.

Les rôles IAM gérés par le client sont en private preview. Contactez ClickHouse Support pour activer cette fonctionnalité pour votre organisation avant de suivre les étapes ci-dessous.

Avec des rôles IAM gérés par le client, vous :

• Créez à l’avance les rôles IAM propres à chaque infrastructure que ClickHouse Cloud créerait autrement
• Supprimez les permissions d’écriture IAM du ClickHouseManagementRole utilisé pour l’accès inter-comptes
• Conservez un contrôle total sur les permissions des rôles et les relations d’approbation

Les deux modules ci-dessous utilisent l’external_id généré par la console ClickHouse Cloud ; toutes les infrastructures BYOC d’un même compte AWS partagent le même ID externe. Consultez ID externe AWS pour plus de détails, y compris l’espace réservé emptyid legacy.

1. Configurer le rôle de gestion sans permissions d’écriture IAM

   Lors de la configuration initiale de BYOC, désactivez les permissions d’écriture IAM sur le rôle de gestion. Avec le CloudFormation template, définissez le paramètre IncludeIAMWritePermissions sur false. Avec le module Terraform :

   module "clickhouse_onboarding" {
     source                        = "github.com/ClickHouse/terraform-byoc-onboarding.git//modules/aws?ref=<version>"
     external_id                   = "<external-id-provided-by-clickhouse>"
     include_iam_write_permissions = false
   }
   

   Remplacez <version> par le tag le plus récent de la page des releases du module — utilisez toujours la dernière release.

2. Créer les rôles IAM propres à chaque infrastructure

   Avant que chaque infrastructure BYOC soit provisionnée, créez les rôles IAM requis (rôles d’identité de pod EKS, rôle d’accès ClickHouse S3 et rôle de gestion du plan de données) avec le module par infrastructure terraform-byoc-onboarding :

   module "clickhouse_per_infra_iam" {
     source = "github.com/ClickHouse/terraform-byoc-onboarding.git//modules/aws-per-infra-iam?ref=<version>"
   
     spoken_name = "<spoken-name-provided-by-clickhouse>"
     region      = "<aws-region-of-the-infrastructure>"
     external_id = "<external-id-provided-by-clickhouse>"
   }
   

   Remplacez <version> par le tag le plus récent de la page des releases du module — utilisez toujours la dernière release.

3. Maintenir à jour les rôles propres à chaque infrastructure

   ClickHouse ajoute régulièrement des rôles et des permissions requis par les nouvelles fonctionnalités de la plateforme. Lorsque ClickHouse vous informe d’une mise à jour, réappliquez le module par infrastructure avec la dernière release — l’utilisation d’une version obsolète peut entraîner l’échec du provisionnement et des mises à niveau de votre infrastructure BYOC.

Pour plus d’informations sur les rôles IAM que ClickHouse Cloud crée par défaut, consultez la référence des privilèges BYOC.