Créer un cluster dans un réseau privé

Pourquoi

Le cluster de production de Signalements va vivre des années. Or une partie de ce qu'on décide en le créant ne pourra plus changer sans le détruire :

• le réseau privé auquel il est rattaché (« cannot be changed later », dit l'aide de la CLI) ;
• le plugin réseau (CNI) : le fournisseur Terraform prévient qu'une modification de ce champ recrée le cluster ;
• les plages d'adresses des pods et des Services, et l'adresse du DNS interne ;
• la région, le projet, et dans une large mesure le nom (le renommer redéploie le plan de contrôle, leçon 1).

Une plage de pods qui chevauche le réseau d'un client relié par VPN, et c'est un cluster à reconstruire le jour où l'on veut l'interconnecter. Une API laissée ouverte à tout Internet pendant des mois, et c'est une surface d'attaque que personne n'a décidée. Cette leçon passe en revue les choix de création, crée le cluster, récupère le kubeconfig et fait les premiers contrôles. Le dimensionnement des pools est l'objet de la leçon 3 ; ici, un seul pool suffit pour démarrer.

Les concepts

Le réseau privé est obligatoire

Sur Kapsule, tous les clusters neufs sont rattachés à un réseau privé (Private Network) du VPC de Scaleway. Le fournisseur Terraform l'écrit sans ambiguïté (« Private Networks are now mandatory »), et l'aide de la CLI précise que, si vous n'en donnez pas, un réseau privé est créé pour vous. Les nœuds y reçoivent une adresse privée ; les répartiteurs de charge créés par le cluster s'y rattachent pour joindre les nœuds ; les services managés (PostgreSQL de sig-db) y sont joignables sans passer par Internet. Ce rattachement ne peut ni être détaché, ni être déplacé vers un autre réseau.

Pour Signalements, la question est : réseau neuf ou pn-signalements (172.16.20.0/22), qui porte déjà les instances et le point d'accès privé de sig-db ? Réutiliser ce réseau permet aux pods de joindre la base par son adresse privée, et d'intégrer le cluster à ce qui existe. Deux mises en garde : les nœuds consomment des adresses de ce réseau (un /22 en offre un peu plus d'un millier, partagées avec les instances et les répartiteurs), et un réseau partagé lie les cycles de vie, une erreur sur ce réseau touchant tout le monde. Un réseau dédié par cluster reste le plus propre quand les réseaux peuvent être reliés par le routage du VPC (Réseaux avancés).

Isolation contrôlée et isolation complète

Scaleway distingue deux façons d'exposer les nœuds :

D'après la documentation de Scaleway, les adresses publiques de l'isolation contrôlée ne servent qu'au trafic sortant ; aucun service n'y écoute par défaut. L'isolation complète s'active pool par pool (option public-ip-disabled à la création du pool), et l'on peut mélanger les deux modes dans un même cluster. Elle suppose que le réseau privé ait une passerelle publique dans la même région, avec la traduction d'adresses dynamique et la publication de la route par défaut activées (c'est le comportement par défaut), et qu'elle soit de la génération intégrée à IPAM.

Pourquoi choisir l'isolation complète ? Pour une adresse de sortie stable : un partenaire qui filtre les adresses sources (le service qui consomme les signalements d'une métropole, un serveur SMTP) ne peut pas autoriser des nœuds qui changent d'adresse. Et pour réduire la surface : un nœud sans adresse publique ne peut pas être joint de l'extérieur, même par une erreur de règle de pare-feu.

La documentation prévient d'une conséquence : en isolation complète, les nœuds joignent aussi le plan de contrôle par la passerelle. Si les nœuds ne peuvent pas la joindre (panne du réseau privé dans une zone, passerelle détachée), ils deviennent NotReady. Comme il n'y a qu'une passerelle par réseau privé, perdre la zone qui la porte fait perdre tous les nœuds de tous les pools privés, quelle que soit leur zone. L'isolation complète achète une propriété de sécurité, et la paie par un point de défaillance.

Le plugin réseau (CNI)

Le champ cni accepte cilium (valeur par défaut) ou calico pour un cluster Kapsule. L'aide de la CLI énumère aussi kilo (Kosmos), none et cilium_native ; les pages consultées pour cette leçon ne documentent pas ces deux dernières valeurs pour Kapsule, ne les utilisez pas sans confirmation du support. Le cours Les plugins CNI a présenté les familles ; deux raisons de s'en tenir à Cilium sur Kapsule :

• c'est le chemin le mieux outillé : Scaleway l'installe et le met à jour avec le cluster, et les cours Les NetworkPolicies et Diagnostiquer le réseau d'un cluster le prennent pour exemple ;
• Cilium pose lui-même une teinte de démarrage sur les nœuds (la documentation de Kapsule la cite en exemple de startup taint) qu'il retire quand l'initialisation est terminée : aucun pod ne démarre sur un nœud dont le réseau n'est pas prêt.

Choisir Calico se justifie par une équipe qui le maîtrise déjà et par ses NetworkPolicies, pas par une préférence de principe. Le choix est définitif.

Les plages des pods et des Services

Les pods reçoivent leurs adresses d'une plage propre au cluster (pod-cidr), les Services d'une autre (service-cidr), et le DNS interne d'une adresse du service-cidr (service-dns-ip, par défaut l'adresse du réseau plus 10). Toutes trois sont fixées à la création. Ces plages ne sont pas celles du réseau privé : les pods n'y consomment pas d'adresses du /22. Mais elles doivent être disjointes de tout réseau que le cluster devra joindre : le réseau privé, les autres VPC, un VPN vers le réseau de la métropole cliente, l'interconnexion vers un datacenter. Un chevauchement rend un réseau injoignable depuis les pods, sans message d'erreur évident, puisque le noyau route vers la plage locale.

Pour Signalements, avant de créer quoi que ce soit, on dresse le plan d'adressage de tout ce qui doit communiquer. L'exemple ci-dessous utilise des plages de documentation :

Les valeurs par défaut que Scaleway attribue ne sont pas documentées dans les pages consultées : lisez-les sur un cluster existant (scw k8s cluster get), et fixez les vôtres explicitement si le cluster doit être relié à autre chose. Les contraintes de taille que l'API impose se trouvent dans sa documentation ; la taille de la plage de pods limite le nombre de pods (et de nœuds, puisque chaque nœud en reçoit un bloc). Voir Le modèle réseau de Kubernetes.

Les options du plan de contrôle

Quelques réglages du plan de contrôle sont exposés à la création (tous modifiables ensuite, sauf indication) :

• Plugins d'admission (admission-plugins) : une liste de contrôleurs d'admission à activer sur le serveur d'API, parmi ceux que la version propose (la commande scw k8s version list les énumère). Un contrôleur d'admission intercepte une requête après authentification et autorisation, avant l'écriture dans etcd ; l'Admission Controllers Reference détaille ceux de Kubernetes. Un exemple parlant est AlwaysPullImages, qui force le contrôle d'accès au registre à chaque démarrage de pod ;
• Feature gates (feature-gates) : interrupteurs de fonctionnalités de Kubernetes. Beaucoup concernent des fonctions alpha, instables et sans garantie de compatibilité : à ne pas activer en production sans raison précise, et à signaler dans l'architecture ;
• OIDC (open-id-connect-config) : permet de faire authentifier les humains par votre fournisseur d'identité. Les champs : issuer-url (en https:// uniquement), client-id, la revendication utilisée comme nom (username-claim, sub par défaut), un préfixe (username-prefix), les groupes (groups-claim, groups-prefix) et des revendications obligatoires. La leçon 5 l'utilise ;
• Mise à jour automatique (auto-upgrade) : activée, avec une fenêtre de deux heures (heure de début en UTC, jour de la semaine ou any), elle applique les patchs (leçon 6) ;
• Autoscaler (autoscaler-config) : le comportement de la mise à l'échelle des pools (leçon 3) ;
• Étiquettes (tags) : l'étiquette scw-filestorage-csi active le pilote de File Storage (leçon 4).

L'accès à l'API : la liste d'adresses autorisées

Le plan de contrôle est joignable depuis Internet. Scaleway propose donc des ACL (listes de contrôle d'accès) sur l'accès à l'API : seules les adresses ou blocs que vous listez peuvent s'y connecter. L'entrée par défaut, 0.0.0.0/0, autorise tout le monde ; la fonctionnalité est activée par défaut sur les clusters créés après le 8 mars 2025. Restreindre cette liste est la mesure de sécurité la plus rentable de la leçon, mais aussi celle qui peut vous enfermer dehors : voir les pièges.

Le kubeconfig et l'authentification

Pour parler au cluster, kubectl lit un fichier kubeconfig, qui contient l'URL de l'API, le certificat de l'autorité qui la signe et les identifiants. La CLI scw le fabrique, avec trois méthodes (auth-method) :

• cli (défaut) : le kubeconfig désigne la CLI scw comme fournisseur d'identifiants (un credential plugin au sens de Kubernetes : kubectl exécute la commande, qui renvoie un jeton). Aucun secret durable n'est écrit dans le fichier ; en revanche, la commande scw doit être installée et configurée sur toute machine qui l'utilise ;
• copy-cli-token : la clé secrète de la CLI est copiée dans le fichier. Il fonctionne sans la CLI, mais le fichier est alors un secret ;
• legacy : le jeton d'administrateur du cluster est écrit dans le fichier. Le code de la CLI le marque comme obsolète (deprecated).

Les deux dernières méthodes font du fichier un document à protéger comme un mot de passe. Pour un humain, la méthode par défaut est la bonne.

En pratique

Les commandes ci-dessous ont été vérifiées avec l'aide de la CLI 2.62.0. Elles créent des ressources facturées : n'exécutez la création que sur un compte de test, et exécutez la suppression de la fin de la section. Les sorties dépendent de votre compte et ne sont pas reproduites.

Préparer

Relevez l'identifiant du réseau privé, les versions proposées et les types de clusters :

$ PN=$(scw vpc private-network list name=pn-signalements region=fr-par -o json | jq -r '.[] | select(.name=="pn-signalements") | .id')
$ scw k8s version list region=fr-par
$ scw k8s cluster-type list region=fr-par

Le filtre name= des commandes list cherche une sous-chaîne ; le select de jq garde le nom exact. Choisissez une version parmi celles non dépréciées de la leçon 1, et un type de nœud : scw instance server-type list zone=fr-par-1 donne les types d'instances, dont certains sont exclus de Kapsule par manque de mémoire.

Créer le cluster et son premier pool

$ scw k8s cluster create \
    name=signalements-prod description="Signalements, production" \
    type=kapsule version=1.36 cni=cilium \
    private-network-id=$PN \
    pod-cidr=10.48.0.0/16 service-cidr=10.49.0.0/20 \
    tags.0=projet=signalements tags.1=env=prod \
    auto-upgrade.enable=true auto-upgrade.maintenance-window.day=tuesday \
    auto-upgrade.maintenance-window.start-hour=3 \
    pools.0.name=general pools.0.node-type=<type d'instance> pools.0.zone=fr-par-1 \
    pools.0.size=3 pools.0.autohealing=true \
    region=fr-par --wait

• type=kapsule est le plan de contrôle mutualisé ; kapsule-dedicated-4 ou plus pour un dédié (leçon 1).
• version=1.36 : d'après le fournisseur Terraform, une version mineure seule est acceptée quand la mise à jour automatique est active ; sinon, donnez le patch exact lu dans scw k8s version list.
• private-network-id, pod-cidr et service-cidr sont les paramètres que la CLI marque comme non modifiables plus tard.
• tags.N : étiquettes libres du cluster, au format clé=valeur par convention d'équipe.
• auto-upgrade.* : patchs le mardi, fenêtre de deux heures à partir de 3 h UTC.
• pools.0.* : le premier pool. size=3 crée trois nœuds ; autohealing=true active la réparation automatique. L'autoscaling est volontairement absent, la leçon suivante le traite.
• --wait bloque jusqu'à ce que le cluster soit prêt. Sans lui, scw k8s cluster wait <identifiant> fait la même attente, avec wait-for-pools=true pour attendre aussi les nœuds.

Pour savoir ce que vous avez vraiment obtenu (et lire les plages que Scaleway aurait choisies si vous aviez omis les vôtres) :

$ scw k8s cluster get <identifiant> region=fr-par -o json | jq '{name, version, cni, type, private_network_id, pod_cidr, service_cidr, service_dns_ip, apiserver_url, status}'

Récupérer le kubeconfig

$ scw k8s kubeconfig install <identifiant> region=fr-par
$ kubectl config get-contexts

install fusionne le nouveau contexte dans le fichier désigné par KUBECONFIG, ou dans ~/.kube/config si la variable est vide, et en fait le contexte courant. Deux options en découlent :

• keep-current-context=true laisse le contexte courant inchangé, utile quand on a déjà un contexte sur lyneko-apps et qu'on ne veut pas manipuler le mauvais cluster ;
• scw k8s kubeconfig get <identifiant> écrit le fichier sur la sortie standard, sans toucher à vos fichiers : scw k8s kubeconfig get <identifiant> > .tmp/signalements.yaml puis export KUBECONFIG=$PWD/.tmp/signalements.yaml donne un fichier dédié, plus sûr quand on manipule un cluster de production.

Lisez le contexte (kubectl config current-context) avant toute commande destructrice.

Restreindre l'accès à l'API

Lisez l'état actuel, puis posez la liste :

$ scw k8s acl list cluster-id=<identifiant> region=fr-par
$ scw k8s acl set cluster-id=<identifiant> region=fr-par \
    acls.0.ip=198.51.100.0/24 acls.0.description="reseau Lyneko, VPN" \
    acls.1.ip=192.0.2.10/32 acls.1.description="serveur CI"

• set remplace toute la liste ; add ajoute des entrées à la liste existante ; delete en retire une. Utilisez add pour ne pas effacer ce qui existe, set quand la liste est décrite dans un fichier versionné.
• acls.N.ip est un bloc CIDR (/32 pour une adresse seule). acls.N.scaleway-ranges=true autorise toutes les plages d'adresses de Scaleway : c'est l'option qu'il faut quand des composants hébergés chez Scaleway (le service de CI, une fonction, un autre cluster) doivent joindre l'API, mais elle ouvre l'API à tous les clients de Scaleway, pas seulement à vous.
• Ajoutez toujours avant de retirer 0.0.0.0/0 l'adresse d'où vous travaillez, puis testez un kubectl get nodes depuis une seconde fenêtre avant de fermer la première.

Un point que la documentation consultée ne tranche pas : en isolation contrôlée, les nœuds joignent le plan de contrôle par leurs adresses publiques (limite décrite dans la documentation du multi-AZ). Savoir si la liste d'adresses s'applique aussi à eux, et si scaleway-ranges est nécessaire pour que les nœuds restent Ready, n'est pas établi par ces pages. Faites donc l'essai sur un cluster de préproduction : après avoir restreint la liste, les nœuds doivent rester Ready et un nouveau nœud doit pouvoir rejoindre le cluster (augmentez la taille du pool d'une unité).

Les premiers contrôles

Aucun de ces contrôles ne modifie le cluster :

$ kubectl config current-context
$ kubectl cluster-info
$ kubectl auth whoami
$ kubectl get nodes -o wide
$ kubectl get nodes --show-labels
$ kubectl get pods -A
$ kubectl get storageclass

Ce qu'il faut regarder, point par point :

• kubectl auth whoami (commande expérimentale de kubectl, qui interroge l'API d'authentification) montre sous quelle identité vous parlez, avec ses groupes ;
• kubectl get nodes -o wide : trois nœuds Ready, avec une adresse INTERNAL-IP dans 172.16.20.0/22 ; une EXTERNAL-IP en isolation contrôlée, aucune pour un pool en isolation complète ;
• les étiquettes des nœuds contiennent la zone (topology.kubernetes.io/zone) et le nom du pool (k8s.scaleway.com/pool-name, que la documentation de Scaleway utilise pour cibler un pool avec kubectl cordon -l) ;
• kubectl get pods -A : les pods de kube-system de la leçon 1, tous Running ; les agents du CNI y figurent (par exemple un DaemonSet cilium) ; relevez leur liste pour votre dossier d'architecture ;
• kubectl get storageclass : les classes du pilote csi.scaleway.com, dont celle par défaut (leçon 4).

Pour valider le CNI, le cours Les plugins CNI donne la commande de l'agent ; la configuration appliquée par Scaleway se lit dans kubectl -n kube-system get configmap cilium-config -o yaml.

Nettoyer

$ scw k8s cluster delete <identifiant> with-additional-resources=true region=fr-par

Sans with-additional-resources, les volumes et répartiteurs créés par le cluster restent facturés. Avec, ils sont supprimés « au mieux », ainsi que les réseaux privés vides (le réseau pn-signalements, non vide, est conservé).

Sous le capot

Ce que fait kubectl avec le mode cli. Le kubeconfig contient, dans users, une entrée de type exec : un credential plugin du protocole client.authentication.k8s.io. À chaque appel (ou quand le jeton expire), kubectl exécute la commande indiquée, qui écrit sur sa sortie un objet ExecCredential contenant le jeton. Ici la commande est scw, qui lit votre profil. Le fichier peut donc être copié sans fuite de secret, mais ne fonctionne que si scw est présent : l'erreur typique d'un poste sans la CLI est Unable to connect to the server: getting credentials: exec: executable scw not found.

Où s'applique la liste d'adresses. D'après la documentation de la limite multi-AZ, l'accès réseau au plan de contrôle est géré par un répartiteur de charge de la zone principale de la région. Le filtrage a donc lieu en amont du serveur d'API, avant l'authentification : une requête refusée n'atteint jamais Kubernetes, et vous n'avez ni Unauthorized ni Forbidden, mais un délai d'attente.

Pourquoi les plages ne peuvent pas changer. Le CNI découpe la plage des pods en blocs par nœud, les règles de transfert des Services (kube-proxy ou son remplaçant par Cilium) portent les adresses du service-cidr, et l'adresse du DNS est écrite dans la configuration du kubelet. Changer une plage reviendrait à réécrire tout cela à la fois : l'API la déclare non modifiable.

L'isolation complète au démarrage. Un nœud sans adresse publique reçoit une route par défaut vers la passerelle, par laquelle passe tout son trafic sortant. Une passerelle absente ou mal configurée se manifeste par des nœuds qui n'atteignent jamais Ready, et non par une erreur lisible.

Pièges courants

Un chevauchement de plages. Un pod ne joint plus le réseau d'une métropole (dial tcp 203.0.113.20:443: i/o timeout) alors que le même appel passe depuis un nœud : le symptôme ressemble à un pare-feu. La cause est une plage de pods ou de Services qui contient l'adresse cible.

La liste d'adresses et les clients oubliés. On retire 0.0.0.0/0 en oubliant la CI, un poste en télétravail ou un outil de déploiement qui sort par d'autres adresses : Unable to connect to the server: dial tcp <adresse>:443: i/o timeout, sans autre indice. Gardez un moyen de rattrapage : la console permet de modifier la liste.

install change de contexte sans prévenir. Vous consultez un cluster de test, et le kubectl delete suivant s'exécute sur la production. Utilisez keep-current-context=true ou un fichier par cluster.

version=latest dans un script. Le même script crée des clusters différents d'un trimestre à l'autre. Fixez la version.

L'isolation complète sans passerelle fiable. Sans passerelle correcte (même région, route par défaut publiée), les nœuds n'atteignent jamais Ready ; détachée plus tard, elle coupe les nœuds du plan de contrôle. Traitez-la comme un composant du cluster, avec ses alertes.

Le groupe de sécurité partagé. Sans identifiant de groupe, les pools d'une zone utilisent le groupe « Kapsule default security group », partagé par tous les pools de la zone dans le projet : le modifier touche tout le monde. Pour des règles propres à un pool, créez un groupe et passez security-group-id.

Oublier la suppression. Un cluster d'essai, ses nœuds, un répartiteur et un volume sont facturés à l'heure. Mettez la suppression dans le même fichier que la création.

Sécurité

• Fermez l'API dès la création : la liste d'adresses autorisées est la première défense, avant le RBAC.
• Choisissez le kubeconfig selon l'usage : cli pour les humains, une identité d'application pour la CI (leçon 5). copy-cli-token et legacy produisent un fichier secret (le second contient le jeton d'administrateur du cluster) : ne les partagez pas, ne les versionnez pas, révoquez la clé en cas de fuite.
• N'ouvrez pas SSH sur les nœuds. Depuis mai 2023, le groupe de sécurité par défaut refuse tout trafic entrant ; ouvrir le port 22 se fait à la main, sur un bloc restreint, et la documentation « enable or disable SSH » explique comment couper le serveur.
• Isolation complète pour les nœuds qui parlent à des tiers : sortie par une adresse connue, nœud injoignable de l'extérieur.
• OIDC plutôt que jetons d'administration partagés : chacun s'authentifie par son fournisseur d'identité, les départs se règlent en un seul endroit. Choisissez un préfixe de nom (oidc:) pour qu'un utilisateur ne soit pas confondu avec un compte système.
• Plugins d'admission : ils renforcent le cluster sans agent. Vérifiez dans scw k8s version list ceux que la version propose, et dans la référence de Kubernetes ceux qui sont actifs par défaut.
• Feature gates alpha : sans garantie de compatibilité, elles peuvent bloquer une mise à jour. À réserver à un besoin écrit, avec une date de retrait.

En production

• Un plan d'adressage avant le premier cluster : plages des réseaux privés, des pods et des Services de tous les clusters, des VPN et des interconnexions de Lyneko et de ses clients. Chaque nouveau cluster y prend une plage disjointe, seul moyen de relier un jour deux clusters.
• Réseau dédié par cluster quand l'isolation entre environnements importe ; partagé quand les ressources doivent se parler en privé. Dans les deux cas, décrit dans le même code que le cluster (leçon 8).
• Version explicite, patchs automatiques, fenêtre en heures creuses, jamais un jour d'événement (pic d'alertes pendant une intempérie).
• La liste d'adresses est du code : fichier versionné, appliqué par un outil, relu. Elle se périme (prestataire parti, adresse de bureau changée).
• Au moins trois nœuds répartis sur au moins deux zones, recommandation de la documentation de Scaleway (leçon 3).
• Chez Lyneko, ce qui est partagé (Traefik, Argo CD, External Secrets) reste dans lyneko-apps ; Signalements, avec ses plages, son SLA et ses clients, a son cluster.

Exercices

1. Le plan d'adressage (niveau 200). Signalements doit joindre, depuis les pods, le réseau 203.0.113.0/24 d'une métropole par VPN. Un collègue propose pod-cidr=203.0.0.0/16 « parce que cette plage est libre chez nous ». Qu'en pensez-vous, et quelle plage choisir parmi 10.48.0.0/16 et 172.16.21.0/24 ?

2. S'enfermer dehors (niveau 200). Vous lancez scw k8s acl set avec une seule entrée, l'adresse du bureau. Dix minutes plus tard, les déploiements d'Argo CD (qui tourne dans un autre cluster, lyneko-apps) échouent avec i/o timeout vers l'API de signalements-prod. Expliquez, proposez un correctif, et dites ce que vous auriez dû faire avant.

Récapitulatif

• Le réseau privé est obligatoire, rattaché à la création et définitif ; le CNI (Cilium par défaut, Calico en option), les plages de pods et de Services et l'adresse du DNS le sont aussi. Un plan d'adressage disjoint de tout réseau à joindre précède le premier cluster.
• Isolation contrôlée : adresse publique sortante, entrées refusées. Isolation complète, par pool : passerelle publique obligatoire, adresse de sortie stable, mais un point de défaillance unique.
• Les options du plan de contrôle (plugins d'admission, feature gates alpha, OIDC, mise à jour automatique) se fixent à la création ; version vaut latest par défaut : écrivez-la.
• scw k8s cluster create ... --wait crée le cluster et son premier pool ; scw k8s kubeconfig install fusionne le contexte (keep-current-context=true pour ne pas changer de cible) ; par défaut, le kubeconfig appelle la CLI comme fournisseur d'identifiants.
• La liste d'adresses autorisées (scw k8s acl add, set, delete) filtre avant l'authentification : set remplace tout, et un refus se voit comme un délai d'attente.
• Les premiers contrôles : identité, nœuds et adresses, étiquettes de zone et de pool, pods de kube-system, classes de stockage.

Pour aller plus loin

• La page de la documentation sur le réseau privé, pour les prérequis exacts de la passerelle publique en isolation complète.
• La leçon 3 : types de nœuds, pools multiples, autoscaling.
• Le cours Réseaux avancés : relier le réseau du cluster à d'autres réseaux.
• La leçon 5 : OIDC, IAM et RBAC pour les humains et les applications.
• Le cours Sécurité de Kubernetes, pour la politique d'admission et la sécurité des pods.