vpc-cni, kube-proxy, coredns, aws-ebs-csi-driver), ainsi que les rôles IAM, les clés KMS et les balises ; existing-eks installe uniquement les add-ons que vous indiquez dans install_addons. Sur la cible Helm, clicklink clctl init installe ensuite la couche plateforme à partir des sorties et d’un bundle de plateforme : Karpenter, le contrôleur AWS Load Balancer, la StorageClass et les composants à version figée (voir initialiser le connecteur à partir des sorties Terraform). Les racines nécessitent Terraform 1.10+ ou OpenTofu 1.12+, ainsi que le fournisseur AWS ~> 6.0. Vous pouvez utiliser tofu à la place de terraform dans toutes les commandes de cette page.
Avant de commencer
Vous aurez besoin de :- Terraform 1.10+ ou OpenTofu 1.12+, ainsi que le fournisseur AWS
~> 6.0. - Une identity AWS autorisée à créer et à modifier les ressources requises par la racine choisie.
curl, un outil SHA-256 (sha256sumoushasum) etcosignpour télécharger et vérifier l’archive de la version.- Issus de l’enregistrement : le
chart_repository_arnexigé par chaque racine, ainsi que votre connector endpoint, le jeton d’inscription et le bundle de plateforme à transmettre àinità la dernière étape.
production et existing-vpc, déterminez à l’avance comment la machine qui exécute clicklink clctl init et kubectl accédera à l’API EKS privée, par exemple via un VPN, un bastion, un réseau appairé ou une redirection de port SSM.
Choisissez le répertoire racine Terraform adapté à votre environnement
Les quatre racines génèrent la même sortie
Le VPC couvre trois zones (
Aucune des deux racines ne modifie ce qu’elle n’a pas créé : tables de routage, passerelles NAT, endpoints, règles de groupe de sécurité, groupes de nœuds, modèles de lancement, configuration du cluster ou clés KMS. Toutes deux appliquent aux sous-réseaux privés les balises
clicklink. La transmission à clicklink clctl init est identique, quelle que soit celle que vous appliquez.minimal
minimal assouplit l’endpoint public, les endpoints d’interface, les flow logs, la rétention des logs et la taille du pool système. Chaque variable assouplie existe dans les deux racines sous le même nom. Passer l’une d’elles à sa valeur de production se résume à modifier terraform.tfvars puis à appliquer de nouveau la configuration. En revanche, la zone unique de charge de travail et l’absence de clés KMS sont figées : les sous-réseaux ne peuvent pas changer de zone, et la racine ne propose aucune variable pour le chiffrement des secrets EKS. Pour combler ces écarts, il faut appliquer production sous la forme d’un nouveau cluster.production
Le VPC couvre trois zones (availability_zone_count, de 2 à 4) avec un sous-réseau privé /19 et un sous-réseau public /21 par zone, une passerelle NAT par zone, un endpoint de passerelle S3, des endpoints d’interface pour ECR, STS, EKS, EC2, CloudWatch Logs, SSM, SQS, KMS et ELB, ainsi que des logs de flux VPC. Le cluster EKS dispose d’un endpoint d’API privé, d’une authentification par entrées d’accès (access entries), de tous les types de journaux du plan de contrôle dans un groupe de journaux appartenant au module racine, et de secrets chiffrés avec une clé KMS gérée par le client. Le cluster reçoit les modules complémentaires gérés vpc-cni, kube-proxy, coredns et aws-ebs-csi-driver, ainsi qu’un groupe de nœuds système sans taint, étiqueté clickhouseGroup=system (de deux à quatre nœuds m7g.large par défaut). Le module racine crée également les ressources IAM de Karpenter avec une file d’attente d’interruption et des balises karpenter.sh/discovery, des rôles IRSA pour le contrôleur AWS Load Balancer et pour l’executor du connector, ainsi que des clés KMS pour les volumes EBS et pour les buckets de stockage d’objet.existing-vpc et existing-eks
Aucune des deux racines ne modifie ce qu’elle n’a pas créé : tables de routage, passerelles NAT, endpoints, règles de groupe de sécurité, groupes de nœuds, modèles de lancement, configuration du cluster ou clés KMS. Toutes deux appliquent aux sous-réseaux privés les balises karpenter.sh/discovery=<cluster_name> et kubernetes.io/role/internal-elb=1 ; existing-vpc applique également la balise kubernetes.io/role/elb=1 aux sous-réseaux publics, et existing-eks balise le groupe de sécurité du cluster.Avec existing-vpc, le VPC doit déjà disposer des éléments suivants :- Prise en charge DNS et noms d’hôte DNS activés.
- Deux à quatre sous-réseaux privés répartis sur au moins deux zones de disponibilité, avec
map_public_ip_on_launchdésactivé, et routés vers une NAT gateway ou vers des endpoints d’interface pour ECR, STS, EKS, EC2, CloudWatch Logs, SSM, SQS, KMS et ELB. Ajoutez un endpoint de passerelle S3 : sans lui, le trafic vers le stockage d’objet transite par les NAT gateways. - Des sous-réseaux publics uniquement si vous souhaitez des répartiteurs de charge exposés à Internet. Laissez
public_subnet_idsvide si le VPC ne comporte pas de niveau public.
existing-eks, le cluster doit déjà disposer des éléments suivants :- Kubernetes 1.34 ou version ultérieure.
- Mode d’authentification
APIouAPI_AND_CONFIG_MAP. Pour un cluster en modeCONFIG_MAP, le plan affiche la commande permettant de changer de mode. - Un fournisseur OIDC IAM pour l’émetteur du cluster.
- Des sous-réseaux privés répartis sur au moins deux zones de disponibilité, disposant d’un accès sortant vers les API AWS via une passerelle NAT ou des endpoint d’interface. Par défaut, le module racine les déduit des sous-réseaux du cluster en excluant ceux dont la table de routage mène à une passerelle Internet. Définissez
private_subnet_idssi les sous-réseaux du cluster sont des/28réservés au plan de contrôle, ou si les nœuds doivent être placés dans d’autres sous-réseaux. - Aucune installation existante de Karpenter : ce module racine crée les ressources IAM de Karpenter ainsi que la file d’attente d’interruption. Cette file d’attente étant nommée
<cluster_name>-clicklink, elle ne peut pas entrer en conflit avec une file résiduelle provenant d’une installation de Karpenter supprimée. - Des nœuds système sans taint, portant les labels définis dans
system_node_selector(clickhouseGroup=systempar défaut). Ce module racine ne crée aucun groupe de nœuds.
terraform plan échoue si l’un de ces éléments manque.Si un module complémentaire listé dans install_addons est déjà installé et exécuté en mode autogéré, EKS renvoie Conflicts found when trying to apply. Définissez addon_resolve_conflicts_on_create = "OVERWRITE" pour que le module complémentaire géré prenne le relais, ou retirez-le de install_addons.Téléchargez et vérifiez l’archive de la version de Terraform
Les racines sont distribuées sous la forme d’une archive par version, dont le numéro de version suit celui du binaire Vérifiez la signature avec cosign avant d’extraire l’archive :Puis extrayez-le :L’archive s’extrait dans un seul répertoire contenant
clicklink. Récupérez l’archive correspondant à la version actuelle, ainsi que sa somme de contrôle et son bundle cosign :aws/production, aws/minimal, aws/existing-vpc, aws/existing-eks et aws/modules. Les configurations racines font référence aux modules via ../modules. Conservez l’arborescence extraite telle quelle au lieu d’en extraire une seule racine. Les README racines de l’archive peuvent présenter le passage de relais init sans --platform-bundle ; la commande indiquée dans initialiser le connector à partir des sorties Terraform est celle qui est prise en charge.Configurez et appliquez la racine sélectionnée
Depuis le répertoire racine, copiez le fichier de variables d’exemple, puis renseignez-le :Chaque racine requiert L’archive ne contient pas de fichier de verrouillage des providers. La commande
region, cluster_name et chart_repository_arn. cluster_name définit le nom du cluster, sert de préfixe à chaque ressource et constitue la valeur du tag de découverte. Dans production, minimal et existing-vpc, il comporte de 3 à 32 lettres minuscules, chiffres et traits d’union, doit commencer par une lettre et ne pas se terminer par un trait d’union. Pour existing-eks, il s’agit du nom du cluster que vous exploitez déjà, dans la limite de 32 caractères. chart_repository_arn désigne le dépôt ECR du chart du cluster ClickHouse, que votre équipe de compte vous communique lors de l’inscription. Les racines qui créent un cluster requièrent également cluster_admin_principal_arns, c’est-à-dire les principaux qui obtiennent les droits d’administrateur du cluster via les entrées d’accès EKS. L’identity qui exécute la racine doit figurer dans cette liste, faute de quoi elle ne pourra plus accéder au cluster par la suite. Le créateur du cluster ne reçoit aucun accès implicite. Selon la racine :minimalrequiertendpoint_public_access_cidrs, la liste d’autorisation IPv4 de l’endpoint public de l’API. Le réseau depuis lequel vous exécutezinitetkubectldoit y figurer. Un/0est refusé, sauf siallow_public_endpoint_from_anywhere = true. Avecendpoint_public_access = false, la liste peut être vide et l’endpoint est alors uniquement privé, comme dansproduction.existing-vpcrequiertvpc_idetprivate_subnet_ids.public_subnet_idsest facultatif et sert aux répartiteurs de charge exposés à Internet.existing-eksne requiert aucune autre variable.install_addonsindique les modules complémentaires gérés qui manquent au cluster, etebs_kms_key_arnfournit une clé pour les volumes des services.
terraform providers lock en génère un, que vous pourrez commiter dans votre copie. Par défaut, l’état est stocké localement. Le fichier versions.tf contient un bloc backend "s3" commenté qui illustre la configuration d’un état partagé.Les points de terminaison de l’API
production et existing-vpc sont privés. Exécutez init et kubectl depuis le VPC (via une redirection de port SSM vers un nœud système, un bastion, un VPN ou un réseau appairé), ou activez l’accès public avec endpoint_public_access = true en définissant une liste d’autorisation dans endpoint_public_access_cidrs.Initialisez le connector à partir des sorties de Terraform
Exportez les sorties, puis transmettez-les à Les modules racines ne prennent en charge que la cible Helm. Sur une VM (
init avec le bundle de la plateforme, depuis une machine dont le contexte kube pointe vers le nouveau cluster :--target systemd), init refuse --platform-bundle, et clicklink clctl platform approve --bundle n’installe que les composants épinglés : le cluster ne dispose donc d’aucun provisionneur de nœuds. Réservez --target systemd aux connectors qui enregistrent un ClickHouse que vous exploitez vous-même ; cette option n’est pas prise en charge avec ces modules racines.--platform-bundle installe ce que les modules racines laissent de côté : Karpenter avec un EC2NodeClass et les NodePools clickhouse-server et clickhouse-keeper, le contrôleur AWS Load Balancer, la StorageClass gp3-encrypted (chiffrée avec la clé EBS lorsque les sorties en contiennent une), ainsi que les composants de plateforme épinglés par le bundle : le contrôleur de snapshots, le ClickHouse Operator et les collectors de supervision. Le bundle est le manifeste de plateforme que ClickHouse Cloud génère pour votre environnement ; votre équipe de compte vous le fournit lors de l’onboarding, et sa section cluster: épingle les versions de Karpenter et du contrôleur de répartiteur de charge. L’indicateur nécessite --target helm, --managed et --from-terraform. Les composants déjà présents sont laissés en l’état : la commande peut donc être réexécutée sans risque, et init affiche un rapport indiquant ce qui a été installé, ce qui a été ignoré et pour quelle raison. Sans cet indicateur, init enregistre le connector mais n’installe aucun de ces éléments, et le cluster ne peut exécuter aucun service tant qu’ils ne sont pas en place. Les mises à jour de plateforme ultérieures modifient le contrôleur de snapshots, l’opérateur et les collectors ; Karpenter, le contrôleur de répartiteur de charge et la StorageClass restent tels que init les a installés.--from-terraform accepte soit le document complet affiché par terraform output -json, soit l’objet brut renvoyé par terraform output -json clicklink. La sortie clicklink contient l’identité du cluster (account_id, region, cluster_name, cluster_endpoint, cluster_ca), le fournisseur OIDC, le namespace du connector, le rôle IAM de l’executor (executor_role_arn), la clé EBS, le rôle et la file d’attente des nœuds Karpenter, le rôle du contrôleur de répartiteur de charge et system_node_selector. init lit dans le fichier l’identité du cluster et le namespace du connector. Il définit executor_role_arn comme annotation IRSA sur le ServiceAccount pcm-executor du connector et applique le sélecteur de nœuds aux pods du connector. Les services managés ne partagent pas ce rôle : clicklink clctl executor prepare crée un rôle par service (CH-S3-<service>-<region>-00-Role par défaut), associé au service lors de sa création ; consultez le modèle de privilèges.init rejette tout indicateur, tel que --cluster-name ou --target-namespace, qui contredit le fichier, en indiquant les deux valeurs. Supprimez l’indicateur ou corrigez les sorties. Il rejette également tout contexte kube dont le serveur d’API n’est pas cluster_endpoint, ou dont l’ARN EKS désigne un autre cluster. La sortie comporte un champ schema, actuellement égal à 1. clctl rejette tout fichier dont il ne prend pas en charge le schema.Le reste de l’enregistrement suit la procédure standard décrite dans onboarding.Clés KMS et grants requis
production et existing-vpc créent trois clés KMS gérées par le client, avec rotation activée, pour les secrets EKS, les volumes EBS et les buckets de stockage d’objet, sauf si vous fournissez des ARN dans kms. existing-eks crée la clé de stockage sauf si vous définissez storage_kms_key_arn, et accepte ebs_kms_key_arn pour les volumes des services sans en créer. minimal n’en crée aucune ; sans storage_kms_key_arn, ses buckets restent en SSE-S3. Une clé créée comporte un unique statement pour le compte root, qui délègue l’accès à IAM. Une clé que vous fournissez doit disposer de la même délégation, ou bien des grants suivants dans sa politique de clé :
Dans tous les cas, les modules racines rattachent les politiques des rôles IAM pour les clés des secrets EKS et EBS, ainsi que la politique de clé de stockage de l’executor dès lors que le module racine dispose d’une clé de stockage ;
executor prepare rattache la politique de chaque rôle de service. Les volumes racines des nœuds système contiennent les images et les logs du kubelet, et non les données des services ; ils utilisent la clé EBS par défaut du compte.
Détruire l’infrastructure gérée par Terraform
terraform destroy supprime tout ce que la racine a créé. Les clés KMS créées entrent dans une période de suppression de 30 jours. Les groupes de logs sont supprimés avec les logs qu’ils conservent : exportez donc au préalable ce dont vous avez besoin. Les instances lancées par Karpenter et les volumes créés par le ClickHouse Operator ne figurent pas dans l’état Terraform ; supprimez d’abord vos services et désinstallez Karpenter, faute de quoi la suppression du VPC et du rôle des nœuds échouera.
existing-eks conserve le cluster. Il supprime les rôles, la file d’attente d’interruption et ses règles, l’entrée d’accès ainsi que les balises qu’il a ajoutées. Les addons vpc-cni, kube-proxy et coredns qu’il a installés ne sont plus gérés par EKS, mais leurs pods continuent de s’exécuter. Si la racine a installé l’addon du driver EBS CSI, celui-ci est supprimé avec elle, car son rôle IRSA est également détruit. Pour conserver le driver, recréez l’addon avec votre propre rôle avant la destruction.
La destruction supprime toutes les balises ajoutées par ces racines, y compris une éventuelle balise kubernetes.io/role/internal-elb antérieure à la racine, car aws_ec2_tag s’approprie toute balise existante. Pour les conserver, définissez manage_subnet_tags = false (existing-vpc) ou manage_discovery_tags = false (existing-eks) et appliquez la configuration avant la destruction, ou retirez les ressources aws_ec2_tag de l’état avec terraform state rm.