Onboarding

​

Prérequis

​

Enregistrer votre environnement

• l’identifiant de votre AWS account, la région et le nom de votre EKS cluster
• si le connector s’exécute sur une VM Linux ou dans le cluster
• le node group dédié aux composants de la plateforme
• le préfixe de namespace des services (ns- par défaut)
• la manière dont votre cluster récupère les images ClickHouse : via l’accès au registry que ClickHouse Cloud configure pour votre compte, ou via votre propre mirror

​

Pour toute installation

• Connector v0.17.0 ou ultérieur. Les versions antérieures ne disposent ni du mode managé, ni des commandes platform, ni de instances create. L’installateur propose la dernière version, sauf si vous passez --version.
• Votre connector endpoint et votre jeton d’inscription, fournis lors de l’enregistrement.
• Un egress sur le port 443 vers https://<subdomain>.<connector-domain> et https://<subdomain>.enroll.<connector-domain>, ainsi que vers releases.clicklink.clickhouse.com et Amazon ECR Public au moment de l’installation. En mode managé, l’executor contacte également Amazon ECR et STS lorsqu’une synchronisation ou une création de plateforme récupère un chart depuis ECR. Si l’un de ces éléments est inaccessible, consultez installations isolées et mises en miroir.
• Un EKS cluster Amazon pour le mode managé. init refuse le mode managé sur tout autre cluster et indique --no-managed pour une installation sans l’executor. Terraform sur AWS fournit des modules racines pour un nouveau cluster comme pour un cluster que vous exploitez déjà, ainsi que la commande init qui installe la couche plateforme par-dessus.
• Les droits d’administration du cluster pour le grant de l’executor. Le grant crée un ClusterRole, un ClusterRoleBinding et une ValidatingAdmissionPolicy qui confinent l’executor aux namespaces situés sous votre préfixe. Sur Kubernetes, le kubeconfig avec lequel vous exécutez init doit disposer de ces droits. Sur une VM, c’est le kubeconfig de l’hôte qui doit en disposer ; si l’hôte ne les possède pas, init affiche la commande à exécuter depuis un hôte qui en dispose.
• Pas encore de ClickHouse. Une installation managed démarre sans aucun service ; ceux que l’executor crée s’enregistrent d’eux-mêmes. En mode managé, init n’enregistre aucun ClickHouse que vous exécutez vous-même (sur Kubernetes, il refuse --instance et --instance-namespace). Pour observer un tel cluster, installez un déploiement de connector distinct avec --no-managed. --ch-user-suffix permet aux deux déploiements de partager une instance sans entrer en conflit sur les utilisateurs du connector. Ce déploiement nécessite un listener native joignable, 9440 sécurisé ou 9000 en plaintext, détecté automatiquement sur Kubernetes. Il nécessite également un accès ClickHouse admin pour le provisioning : un utilisateur default sans password, un password transmis via --ch-admin-password-stdin ou saisi à l’invite, ou une injection de CR pour les instances gérées par un opérateur.
• cosign partout où vous téléchargez des artefacts de version. L’installateur vérifie toujours le checksum SHA-256. Si cosign est installé, il vérifie en outre la signature de la version, et avec CLICKLINK_REQUIRE_COSIGN=1 il refuse de poursuivre sans cosign.

​

Pour les installations Kubernetes (Helm)

• Un kubeconfig dont le contexte courant pointe vers l’EKS cluster. Il doit pouvoir créer et lire le namespace du connector, appliquer des Secrets, créer des ServiceAccounts, des Roles et des RoleBindings, installer le chart et accorder à l’executor son accès cluster-wide.
• Des AWS identifiants sur le poste de travail (environnement ou profil) disposant de eks:DescribeCluster et ec2:DescribeVpcs. init s’en sert pour lire les blocs CIDR du VPC de votre cluster nécessaires à la NetworkPolicy. Si la lookup échoue, un avertissement est émis et la liste reste à compléter par vos soins.
• Les CIDR situés derrière votre connector endpoint, afin d’activer dès l’installation la NetworkPolicy du chart en refus par défaut. Sans eux, init prépare la policy en mode disabled et indique comment l’activer ultérieurement.
• Une StorageClass par défaut, ou une classe à transmettre via --storage-class ; le troubleshooter et l’executor conservent leur état sur des PersistentVolumeClaims.
• Un accès au pull d’images : les nœuds du cluster doivent pouvoir récupérer l’image ECR publique, ou un mirror que vous hébergez.

​

Pour les installations sur VM Linux (systemd)

• N’importe quel hôte Linux avec systemd, amd64 ou arm64. Les builds Linux s’exécutent en mode FIPS.
• Accès root pour l’installeur et pour init.
• Ports libres 8082, 8084 et 8086 pour la health et les metrics, 9999 sur l’interface de loopback pour l’API locale de l’executor, et 8443 lorsque la passerelle de sessions de support est activée.
• Accès Admin au Kubernetes API server pour le provisioning et le grant de l’executor : un kubeconfig sur l’hôte, --server et --ca-data, ou les prompts. Les ensembles d’accès sont ancrés à des ServiceAccounts Kubernetes sur les deux targets. En mode managé, le contexte courant du kubeconfig doit pointer vers l’EKS cluster que vous gérez ; init refuse d’accorder le grant via tout autre contexte.

​

Installer et enregistrer

https://<subdomain>.<connector-domain>

curl -fsSL https://releases.clicklink.clickhouse.com/install.sh | bash

curl -fsSL https://releases.clicklink.clickhouse.com/install.sh | sudo bash -s -- --host

clicklink clctl init --enroll https://<subdomain>.<connector-domain> --target helm --managed

clicklink clctl init --handoff handoff.yaml --target helm --managed \
  --egress-cidrs 203.0.113.0/24 \
  --operators '<operator-email-1>,<operator-email-2>' \
  --storage-class <storage-class>

sudo clicklink clctl init --enroll https://<subdomain>.<connector-domain> --managed

CONNECTOR_NAMESPACE='clicklink'   # the connector namespace you chose at init
kubectl get pods -n "${CONNECTOR_NAMESPACE}"

sudo clicklink clctl preflight

rm handoff.yaml        # workstation (Kubernetes installs)
sudo rm handoff.yaml   # VM host (init ran as root, so the file is root-owned)

​

Installations isolées et mises en miroir

​

Téléchargement et vérification manuels

CLICKLINK_VERSION="$(curl -fsSL https://releases.clicklink.clickhouse.com/latest-version.txt)"
# Or pin a specific release: CLICKLINK_VERSION='v0.17.0'
CLICKLINK_TARBALL="clicklink-${CLICKLINK_VERSION}-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/').tar.gz"
for suffix in '' .sha256 .sig .crt; do
  curl -fsSLO "https://releases.clicklink.clickhouse.com/${CLICKLINK_TARBALL}${suffix}"
done
if command -v sha256sum >/dev/null; then
  sha256sum -c "${CLICKLINK_TARBALL}.sha256"
else
  shasum -a 256 -c "${CLICKLINK_TARBALL}.sha256"
fi

cosign verify-blob \
  --certificate "${CLICKLINK_TARBALL}.crt" \
  --signature "${CLICKLINK_TARBALL}.sig" \
  --certificate-identity-regexp "^https://github\.com/ClickHouse/data-plane-clicklink/\.github/workflows/release\.yaml@refs/tags/v" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  "${CLICKLINK_TARBALL}"

tar -xzf "${CLICKLINK_TARBALL}"
sudo install -m 0755 clicklink /usr/local/bin/clicklink

​

En cas d’échec

• Sur une VM, init n’échoue pas. La commande prépare le bundle et affiche un avertissement indiquant la commande exacte à exécuter depuis un kubeconfig disposant des droits d’admin du cluster. Le preflight de vérification signale l’état de l’executor tel quel. Exécutez la commande affichée, puis relancez la même commande init pour vérifier :

sudo env KUBECONFIG=<path> clicklink clctl executor access apply --cluster --config /etc/clicklink/config.yaml

• Sur Kubernetes, un grant refusé interrompt init avant le déploiement du chart, car l’executor se lie (bind) au ServiceAccount accordé et ne peut pas démarrer sans lui. La superposition de values préparée, les Secrets et la CSR sont conservés, et init affiche les deux commandes à exécuter depuis un host disposant des droits d’admin sur le cluster. Exécutez-les, puis relancez la même commande init pour continuer :

clicklink clctl executor access grant --cluster --sa-namespace <connector-namespace> --server <kubernetes-api-server-url> --output-dir <dir>
clicklink clctl executor access apply --cluster --output-dir <dir>