Mises à jour de la plateforme

Approuvez les bundles de plateforme que ClickHouse Cloud propose pour un cluster managé : ce qu’est un bundle, comment se déroule l’approbation et ce qu’elle autorise

Un cluster managé exécute une petite couche plateforme dont dépendent les services ClickHouse. ClickHouse Cloud propose des mises à jour de cette couche ; l’executor n’applique rien tant que vous ne les avez pas approuvées une à une avec vos propres identifiants de cluster.

​

Qu’est-ce qu’une mise à jour de la plateforme

La couche plateforme se compose de trois composants : le snapshot controller, le ClickHouse Operator et les collectors de supervision. Ils s’installent dans cet ordre, car chacun a besoin des définitions de custom resource du précédent. Les services utilisent une StorageClass nommée gp3-encrypted (volumes gp3 chiffrés) livrée avec eux.

Un bundle de plateforme est le manifest que ClickHouse Cloud génère pour votre environnement. Il fige les versions de chart et d’image de ces composants et désigne le registry depuis lequel ils sont récupérés. Chaque bundle est identifié par le sha256 de ce manifest. ClickHouse Cloud le transmet à l’executor via le canal de commandes, et l’executor le prépare en attente de votre approbation.

Un bundle s’applique en deux volets :

• Le volet permissions regroupe tout ce qui accorde ou encadre l’accès : Namespaces, CustomResourceDefinitions, ServiceAccounts, ClusterRoles et ClusterRoleBindings, Roles et RoleBindings, configurations de webhook et d’admission, PriorityClasses et la StorageClass. Vous seul l’appliquez, avec vos credentials, en exécutant clicklink clctl platform approve.
• Le volet charge de travail correspond à ce qui s’exécute : Deployments, Services, ConfigMaps, Secrets, Jobs et PodDisruptionBudgets. L’executor l’applique sous une identity dédiée pcm-platform, qui peut écrire ces types de ressources et rien d’autre, et uniquement tant que le jeton à durée de vie courte généré par votre approbation reste valide.

L’executor n’applique jamais un bundle que vous n’avez pas approuvé. Il refuse toute synchronisation de plateforme dont le volet permissions est absent, dont le sha256 diffère de celui approuvé, ou dont le jeton a expiré. Le refus signale qu’une approbation est nécessaire et précise le sha256 du bundle en attente. La création d’un service nécessitant une définition de custom resource absente de votre plateforme actuelle échoue de la même manière, avec la même commande à exécuter.

​

Approuver une mise à jour de la plateforme

​

Identifiants de registry

L’authentication auprès du registry dépend du mode de distribution d’image enregistré pour votre environnement :

• Accès direct au registry de ClickHouse. Exécutez l’approbation sur la VM EC2 du connector. La commande approve comme la synchronisation de plateforme de l’executor assument le rôle ECR puller en lecture seule de votre environnement à l’aide des identifiants de l’instance metadata service EC2. Ce rôle assure la connexion au registry de charts ; l’executor s’en sert également pour vérifier l’existence des images de plateforme. Les profils AWS, les identifiants d’environnement ou les identifiants SSO présents sur un poste de travail ne remplacent pas le profil d’instance. Votre kubeconfig fournit toujours les identifiants cluster-admin distincts qui appliquent le volet permissions.
• Charts dans un autre registry ECR, y compris votre propre mirror. La connexion au chart utilise les identifiants AWS ambiants du processus qui exécute approve ou l’executor. Ces identifiants doivent être autorisés à lire ce registry.

Réservez la procédure depuis un poste de travail Kubernetes décrite ci-dessous aux deployments avec registry mirroré et approbation de plateforme Kubernetes activée. Pour l’accès direct, demandez au préalable à votre account team de confirmer que votre environnement d’exécution est pris en charge et dispose du profil d’instance EC2 requis.

1. Recherchez le bundle préconfiguré

   ClickHouse Cloud envoie d’abord chaque bundle proposé à l’executor. L’executor le met en attente en tant que bundle pending et signale son sha256 dans le heartbeat. Un seul bundle en attente existe à la fois ; une proposition plus récente le remplace. L’executor refuse alors la synchronisation et enregistre une commande failed dont le résultat se termine par la commande à exécuter.

   clicklink clctl commands list --status failed --action sync_platform
   

   Le champ result se termine par run: clctl platform approve (pending bundle sha <sha256>). Sur Kubernetes, l’indication est run: clctl platform approve --secret-namespace <connector-namespace> (pending bundle sha <sha256>). Une création ayant rencontré une définition de custom resource manquante comporte la même ligne clctl platform approve. Celle-ci apparaît dans sa propre commande échouée ainsi que dans l’erreur affichée par clicklink clctl instances create --wait. Votre account team vous prévient également lorsqu’une mise à jour de plateforme est proposée.

   Lisez le bundle mis en attente avant de l’approuver. Il contient le manifest et son sha256.

   VM Linux

   L’executor met le bundle en attente sous forme de fichier, à côté de ses ensembles d’accès sur l’hôte du connector :

   sudo cat /etc/clicklink/access/executor/platform-pending.json
   

   Kubernetes

   Le pod executor met le bundle en attente sur son volume d’état et l’expose via son API locale. Ouvrez un port-forward et lisez-le :

   CONNECTOR_NAMESPACE='clicklink'   # le namespace du connector que vous avez choisi à l'initialisation
   kubectl -n "${CONNECTOR_NAMESPACE}" port-forward deployment/clicklink-connector-executor 9999:9999 &
   curl -s http://127.0.0.1:9999/v1/platform/pending
   

   L’API répond 404 avec no platform bundle is staged jusqu’à l’arrivée de la première proposition. Laissez le port-forward ouvert pour l’étape suivante.

2. Exécuter approve

   approve sans flags lit le bundle mis en attente et le hache, de sorte que vous approuvez exactement ce que l’executor a reçu. La commande effectue le rendu de chaque chart exactement comme le fera l’executor et applique la moitié « permissions » avec le contexte kube que vous choisissez. Elle crée l’identité pcm-platform si nécessaire et génère son jeton. Elle n’émet aucune requête vers votre endpoint de connecteur.

   approve nécessite un contexte kube disposant des droits cluster-admin sur le cluster managé (--context <name> lorsque votre kubeconfig en contient plusieurs) ainsi que les identifiants de registry correspondant au mode de distribution d’images de votre environnement. --dry-run effectue le rendu et liste la moitié « permissions » sans rien appliquer ni générer ; un accès au registry reste nécessaire pour effectuer le rendu des charts.

   VM Linux

   Exécutez la commande sur l’hôte du connecteur, en tant que root, là où l’executor a mis le bundle en attente :

   sudo clicklink clctl platform approve --config /etc/clicklink/config.yaml
   

   approve écrit le jeton dans /etc/clicklink/access/executor/_platform, à côté des autres credentials de l’executor. La commande construit le nouveau bundle à côté du bundle actif et ne le substitue qu’une fois son jeton créé : un approve en échec laisse donc intact un jeton encore valide.

   Kubernetes

   Pour un déploiement avec registry mis en miroir et approbation de plateforme Kubernetes activée, approve lit le bundle mis en attente via le port-forward de l’étape précédente. La commande livre le bundle de jetons sous forme de Secret dans le namespace du connecteur, que le chart monte dans le pod. Exécutez-la depuis un poste de travail dont le kubeconfig atteint le cluster, avec une copie de la configuration du connecteur et un accès au registry. Le chart rend la configuration dans la ConfigMap de l’executor ; approve en a besoin uniquement pour le préfixe de namespace et n’y lit aucun credential.

   CONNECTOR_NAMESPACE='clicklink'   # le namespace de connecteur que vous avez choisi lors de l'init
   kubectl -n "${CONNECTOR_NAMESPACE}" get configmap clicklink-connector-executor \
     -o jsonpath='{.data.config\.yaml}' > clicklink-config.yaml
   clicklink clctl platform approve --config clicklink-config.yaml \
     --secret-namespace "${CONNECTOR_NAMESPACE}"
   

   approve lit par défaut le bundle mis en attente depuis http://127.0.0.1:9999 ; passez --endpoint lorsque votre port-forward utilise un autre port local. Sans port-forward, la commande s’interrompt et affiche la commande kubectl port-forward à lancer. Le bundle atterrit dans le Secret clicklink-platform-bundle (--secret-name pour le modifier, en accord avec le paramètre executor.platformBundleSecret du chart). Le pod de l’executor le voit dès que le kubelet rafraîchit le montage, en une minute environ.

3. Confirmer

   approve se termine par :

   Approved: <n> permission object(s) applied, platform token valid until <expiry>.
   The executor may now apply the <n> workload object(s) of this bundle inside <namespaces>.
   

   Sur Kubernetes, une troisième ligne s’ajoute : Bundle written to Secret <namespace>/<name>; the executor pod sees it once the kubelet refreshes the mount, within about a minute.

   ClickHouse Cloud renvoie la synchronisation dès que le heartbeat suivant de l’executor signale l’approbation. Il patiente jusqu’à 20 minutes lorsqu’une synchronisation est déjà en cours et ignore tout executor dont le dernier heartbeat remonte à plus de 5 minutes. Après 3 tentatives pour un même bundle, il s’arrête et votre account team la relance. L’executor applique la partie charge de travail et signale la plateforme comme synced. Suivez l’aboutissement de la synchronisation avec :

   clicklink clctl commands list --action sync_platform
   

   La commande sync_platform la plus récente passe à l’état completed. L’executor transmet également le statut de la plateforme et les versions des composants à ClickHouse Cloud à chaque heartbeat, de sorte que votre account team constate le même résultat.

​

La fenêtre d’approbation

Une approbation émet un jeton pour l’identity pcm-platform, valable 2 heures par défaut (--ttl permet de modifier cette durée). L’executor ne le renouvelle jamais. Une fois expiré, l’executor ne peut plus agir sur la couche plateforme et refuse la synchronisation de plateforme suivante en affichant de nouveau le message d’approbation. Il s’agit d’un comportement voulu, indépendant de la connectivité : une approbation accordée alors que le connector est hors ligne expire tout de même selon sa propre horloge.

Exécutez de nouveau approve dans les cas suivants :

• le jeton a expiré avant la fin de la synchronisation ;
• ClickHouse Cloud propose un bundle différent. Le sha256 que vous avez approuvé est enregistré sur le ServiceAccount pcm-platform, et l’executor refuse toute synchronisation portant sur un autre bundle tant que vous ne l’avez pas approuvé ;
• la création d’un service signale une définition de custom resource manquante.

Approuver de nouveau le même bundle ne présente aucun risque et remplace le jeton. Le bundle préparé reste en place après la synchronisation : une nouvelle approbation ne nécessite donc aucune nouvelle proposition.

​

Ce qu’accorde l’approbation

Vous appliquez le volet permissions : elle porte donc votre autorité ; l’executor n’en applique aucun élément. approve y appose le sha256 du bundle, et, avant de toucher à quoi que ce soit, l’executor vérifie que chaque objet de permission du bundle qui lui a été transmis est présent et approuvé.

L’executor applique le volet charge de travail en tant que pcm-platform. Cette identity peut créer et mettre à jour des Secrets, ConfigMaps, Services, Deployments, Jobs et PodDisruptionBudgets, uniquement au sein des namespaces de la plateforme, ce qu’impose une politique d’admission. Elle peut lire les objets dont elle a besoin pour son preflight (pods, events, namespaces, ServiceAccounts, les kinds de permission ci-dessus). Elle ne peut pas :

• écrire un kind à portée cluster ni un objet RBAC ;
• effectuer escalate, bind ou impersonate ;
• émettre ni renouveler son propre jeton.

L’identity de cycle de vie des services de l’executor, pcm-executor, est distincte et confinée aux namespaces des services. Elle ne peut pas écrire dans les namespaces de la plateforme ; ses reads, en revanche, ne sont pas limités par la protection par prefix. Pour l’énumération complète des deux identities, consultez le modèle de privilèges.

​

Réinitialiser un cluster de test

clicklink clctl platform reset est destinée aux clusters de test : cette commande désinstalle les composants de la plateforme afin de pouvoir rejouer leur première installation. Avant toute modification, elle liste les clusters ClickHouse présents dans les namespaces appartenant à ce connector et refuse de poursuivre si un service existe.

Sur un cluster vide, elle désinstalle les releases de la plateforme dans l’ordre inverse des dépendances. Elle supprime ensuite le bundle de jetons de plateforme de l’executor : le directory local sur une VM, ou le Secret désigné par --secret-namespace <connector-namespace> sur Kubernetes. Les CustomResourceDefinitions, le RBAC et la StorageClass restent en place. Exécutez de nouveau approve avant la prochaine synchronisation de la plateforme.

sudo clicklink clctl platform reset --bundle <manifest-file> --config /etc/clicklink/config.yaml --dry-run

reset prend le manifeste de plateforme généré sous forme de fichier (--bundle) ; il ne lit pas le bundle préparé. --dry-run vérifie la présence de services et affiche le plan sans modifier le cluster.