You are viewing documentation for Kubernetes version: v1.28
Kubernetes v1.28 documentation non maintenue. Vous consultez une version statique. Pour une documentation à jour, veuillez consulter: dernière version.
kubeadm init
Cette commande initialise un noeud Kubernetes control-plane.
Utilisez cette commande afin de configurer le control plane Kubernetes
Synopsis
Utilisez cette commande afin de configurer le control plane Kubernetes
La commande "init" exécute les phases suivantes :
preflight Exécute les vérifications en amont
kubelet-start Sauvegarde les réglages kubelet et (re)démarre kubelet
certs Génération de certificats
/etcd-ca Génère le certificat CA auto signé pour fournir les identités à etcd
/apiserver-etcd-client Génère le certificat que l'apiserver utilisera pour communiquer avec etcd
/etcd-healthcheck-client Génère le certificat pour les sondes de vivacité (liveness) qui contrôlent etcd
/etcd-server Génère le certificat pour l'accès à etcd
/etcd-peer Génère le certificat pour que les noeuds etcd puissent communiquer ensemble
/ca Génère le certificat CA auto signé de Kubernetes pour fournir les identités aux autres composants Kubernetes
/apiserver Génère le certificat pour l'accès à l'API Kubernetes
/apiserver-kubelet-client Génère le certificat pour permettre à l'API server de se connecter à kubelet
/front-proxy-ca Génère le certificat CA auto signé pour fournir les identités au proxy frontal (front proxy)
/front-proxy-client Génère le certificat pour le client du proxy frontal
/sa Génère une clef privée pour signer les jetons ainsi que la clef publique du compte service
kubeconfig Génère tous les fichiers kubeconfig nécessaires pour la création du control plane et du fichier kubeconfig admin
/admin Génère un fichier kubeconfig pour utilisation par l'administrateur et kubeadm
/kubelet Génère un fichier kubeconfig pour utilisation par kubelet seulement à des fins d'installation initiale
/controller-manager Génère un fichier fichier kubeconfig for the controller manager to use
/scheduler Génère un fichier kubeconfig pour utilisation par le scheduler
control-plane Génère tous les manifests de Pod statiques nécessaires à la création du control plane
/apiserver Génère le manifest de Pod statique de l'apiserver
/controller-manager Génère le manifest de Pod statique du kube-controller-manager
/scheduler Génère le manifest de Pod statique du kube-schedule
etcd Génère le manifest de Pod statique pour l'etcd local
/local Génère le manifest de Pod statique pour une instance etcd locale, à un seul noeud
upload-config Téléverse les configurations kubeadm et kubelet vers une ConfigMap
/kubeadm Téléverse la ClusterConfiguration de kubeadm vers une ConfigMap
/kubelet Téléverse la configuration kubelet vers une ConfigMap
upload-certs Téléverse les certificats vers kubeadm-certs
mark-control-plane Marque un noeud en tant que control-plane
bootstrap-token Génère les jetons d'installation utilisés pour faire joindre un noeud à un cluster
addon Installe les extensions requises pour l'exécution des tests de Conformance
/coredns Installe l'extension CoreDNS à un cluster Kubernetes
/kube-proxy Installe l'extension kube-proxy à un cluster Kubernetes
kubeadm init [flags]
Options
--apiserver-advertise-address string L'adresse IP que l'API Server utilisera pour s'annoncer. Si non spécifiée, l'interface réseau par défaut sera utilisée.
--apiserver-bind-port int32 Port d'écoute de l'API Server. (par default 6443)
--apiserver-cert-extra-sans strings Noms alternatifs (Subject Alternative Names ou encore SANs) optionnels, utilisés dans les certificats servis par l'API Server. Peuvent êtres des adresses IPs ou des noms DNS.
--cert-dir string Le répertoire où sauvegarder les certificats. (par défaut "/etc/kubernetes/pki")
--certificate-key string Clef utilisée pour chiffrer les certificats control-plane dans le Secret the kubeadm-certs.
--config string Chemin vers un fichier de configuration kubeadm.
--cri-socket string Chemin vers la socket CRI à laquelle la connexion doit s'effectuer. S'il n'est pas spécifié, kubeadm essaiera de le détecter; utiliser cette option seulement si vous avez plus d'un CRI installé ou si vous utilisez des sockets CRI non standard.
--dry-run N'effectue aucun changement; affiche seulement la sortie standard de ce qui serait effectué.
--feature-gates string Un ensemble de paires clef=valeur qui décrivent l'entrée de configuration pour des fonctionnalités diverses. Il n'y en a aucune dans cette version.
-h, --help aide pour l'initialisation (init)
--ignore-preflight-errors strings Une liste de contrôles dont les erreurs seront catégorisées comme "warnings" (avertissements). Par exemple : 'IsPrivilegedUser,Swap'. La valeur 'all' ignore les erreurs de tous les contrôles.
--image-repository string Choisis un container registry d'où télécharger les images du control plane. (par défaut "registry.k8s.io")
--kubernetes-version string Choisis une version Kubernetes spécifique pour le control plane. (par défaut "stable-1")
--node-name string Spécifie le nom du noeud.
--pod-network-cidr string Spécifie l'intervalle des adresses IP pour le réseau des pods. Si fournie, le control plane allouera automatiquement les CIDRs pour chacun des noeuds.
--service-cidr string Utilise un intervalle différent pour les adresses IP des services prioritaires (VIPs). (par défaut "10.96.0.0/12")
--service-dns-domain string Utilise un domaine alternatif pour les services, par exemple : "myorg.internal". (par défaut "cluster.local")
--skip-certificate-key-print N'affiche pas la clef utilisée pour chiffrer les certificats du control-plane.
--skip-phases strings List des des phases à sauter
--skip-token-print N'affiche pas le jeton par défaut de l'installation qui a été généré lors de 'kubeadm init'.
--token string Le jeton à utiliser pour établir la confiance mutuelle entre les noeuds et les noeuds du control-plane. Le format correspond à la regexp : [a-z0-9]{6}\.[a-z0-9]{16} - par exemple : abcdef.0123456789abcdef
--token-ttl duration La durée au bout de laquelle le jeton sera automatiquement détruit (par exemple : 1s, 2m, 3h). Si réglée à '0', le jeton n'expirera jamais (par défaut 24h0m0s)
--upload-certs Téléverse les certificats du control-plane vers le Secret kubeadm-certs.
Options héritées depuis la commande parent
--rootfs string [EXPERIMENTALE] Le chemin vers la "vraie" racine du système de fichiers de l'hôte.
Séquence d'initialisation
kubeadm init
assemble un noeud Kubernetes control-plane en effectuant les étapes suivantes :
Exécute une série de contrôles pour valider l'état du système avant d'y apporter des changements. Certaines validations peuvent émettre seulement des avertissements (warnings), d'autres peuvent générer des erreurs qui forceront l'interruption de kubeadm jusqu'à ce que le problème soit résolu ou jusqu'à ce que l'utilisateur spécifie
--ignore-preflight-errors=<list-des-erreurs>
.Génère une autorité de certification (CA) auto signée (ou utilise une existante si spécifiée) pour installer les identités de chaque composant du cluster. Si l'utilisateur a fourni son propre certificat et/ou clef de CA en le (la) copiant dans le répertoire des certificats, configuré avec
--cert-dir
(/etc/kubernetes/pki
par défaut) cette étape est sautée comme expliqué dans le document utiliser ses propres certificats. Les certificats de l'API Server auront des entrées SAN additionnelles pour chaque argument--apiserver-cert-extra-sans
.Ecrit les fichiers kubeconfig dans
/etc/kubernetes/
pour kubelet, le controller-manager et l'ordonnanceur (scheduler) qui seront utlisés pour les connexions à l'API server, chacun avec sa propre identité, ainsi qu'un fichier kubeconfig supplémentaire pour l'administration, nomméadmin.conf
.Génère des manifestes statiques de Pod pour l'API server, le controller manager et l'ordonnanceur. Au cas où aucun etcd externe n'est fourni, un manifeste statique de Pod pour etcd est généré.
Les manifestes statiques de Pod sont écrits dans
/etc/kubernetes/manifestes
; kubelet surveille ce répertoire afin que les Pods soient créés au démarrage.Dès lors que les pods de control-plane sont démarrés, la séquence de
kubeadm init
peut alors continuer.Applique les étiquettes (labels) et marques (taints) au noeud control-plane afin qu'aucune charge de travail additionnelle ne s'y exécute.
Génère le jeton que les noeuds additionnels peuvent utiliser pour s'enregistrer avec un control-plane. Il est possible que l'utilisateur fournisse un jeton en utilisant
--token
, comme décrit dans la documentation à propos du jeton kubeadm.Produit tous les fichiers de configuration requis pour autoriser les noeuds à rejoindre le cluster avec les jetons d'assemblage et le mécanisme d'assemblage TLS :
Ecrit une ConfigMap pour produire toute la configuration nécessaire pour rejoindre le cluster et installer les règles d'accès RBAC sous jacentes.
Permet aux jetons d'assemblage d'accéder à l'API CSR (Certificate Signing Request, requête de signature de certificat).
Configure l'acceptation automatique des nouvelles requêtes CSR.
Voir kubeadm join pour de l'information complémentaire.
Installe un serveur DNS (CoreDNS) et les modules de l'extension kube-proxy en utilisant l'API Server. Dans la version 1.11 (et au delà) de Kubernetes, CoreDNS est le serveur DNS par défaut. Pour installer kube-dns au lieu de CoreDNS, l'extension DNS doit être configurée dans la
ClusterConfiguration
de kubeadm. Pour plus d'information, se référer à la section ci-dessous intitulée :Utiliser kubeadm init avec un fichier de configuration
. Vous remarquerez que bien que le serveur DNS soit déployé, il ne sera pas programmé pour exécution avant que le CNI soit installé.
Utiliser les phases d'initialisation avec kubeadm
Kubeadm vous permet de créer un noeud de type control-plane en plusieurs phases. Dans 1.13 la commande kubeadm init phase
a été promue GA (disponibilité générale) alors que précédemment ce n'était qu'une commande alpha : kubeadm alpha phase
.
Pour voir la liste des phases et sous phases dans l'ordre, vous pouvez utiliser kubeadm init --help
. La liste sera affichée en haut de l'écran d'aide et chaque phase aura une description associée.
Bon à savoir : en appelant kubeadm init
toutes les phases et sous phases seront executées dans cet ordre.
Certaines phases ont des options uniques, si vous désirez consulter la liste de ces options, ajoutez --help
, par exemple :
sudo kubeadm init phase control-plane controller-manager --help
Vous pouvez aussi utiliser --help
pour voir la liste des sous-phases pour une phase parent :
sudo kubeadm init phase control-plane --help
kubeadm init
a aussi une option nommée --skip-phases
qui peut être utilisée pour passer outre. Cette option accepte une liste de noms de phases, qui peuvent être retrouvées à partir de la liste ordonée précédente.
Par exemple :
sudo kubeadm init phase control-plane all --config=configfile.yaml
sudo kubeadm init phase etcd local --config=configfile.yaml
# vous pouvez modifier les fichiers manifestes du control-plane et d'etcd
sudo kubeadm init --skip-phases=control-plane,etcd --config=configfile.yaml
Cet exemple écrirait les fichiers manifestes pour le control plane et etcd dans /etc/kubernetes/manifestes
à partir de la configuration dans configfile.yaml
. Cela permet de modifier les fichiers et d'ensuite sauter ces phases en utilisant --skip-phases
. En invoquant la dernière commande, vous créerez un noeud de type control plane avec les les fichiers manifestes personnalisés.
Utiliser kubeadm init avec un fichier de configuration
C'est possible de configurer kubeadm init
avec un fichier de configuration plutôt qu'avec des options en ligne de commande, et certaines fonctionnalités avancées sont d'ailleurs uniquement disponibles en tant qu'options du fichier de configuration. Ce fichier est passé à kubeadm avec l'option --config
.
Dans Kubernetes 1.11 et au delà, la configuration par défaut peut être affichée en utilisant la commande kubeadm config print.
Il est recommandé que vous migriez votre configuration v1alpha3
vers v1beta1
en utilisant
la commande kubeadm config migrate,
car le support de v1alpha3
sera supprimé dans Kubernetes 1.15.
Pour plus de détails à propos de chaque option de la configuration v1beta1
vous pouvez consulter la
référence de l'API.
Ajouter des paramètres kube-proxy
Pour de l'information à propos des paramètres kube-proxy dans la configuration kubeadm, se référer à : kube-proxy
Pour de l'information sur comment activer le mode IPVS avec kubeadm, se référer à : IPVS
Passer des options personnalisées aux composants du control plane
Pour de l'information sur comment passer des options aux composants du control plane, se référer à : control-plane-flags
Utiliser des images personnalisées
Par défaut, kubeadm télécharge les images depuis registry.k8s.io
, à moins que la version demandée de Kubernetes soit une version Intégration Continue (CI). Dans ce cas, gcr.io/k8s-staging-ci-images
est utilisé.
Vous pouvez outrepasser ce comportement en utilisant kubeadm avec un fichier de configuration. Les personnalisations permises sont :
- fournir un
imageRepository
à utiliser à la place deregistry.k8s.io
. - régler
useHyperKubeImage
àtrue
pour utiliser l'image HyperKube. - fournir un
imageRepository
et unimageTag
pour etcd et l'extension (add-on) DNS.
Notez que le champ de configurtation kubernetesVersion
ou l'option ligne de commande --kubernetes-version
affectent la version des images.
Utiliser des certificats personnalisés
Par défaut, kubeadm génère tous les certificats requis pour que votre cluster fonctionne. Vous pouvez outrepasser ce comportement en fournissant vos propres certificats.
Pour ce faire, vous devez les placer dans le répertoire spécifié via l'option --cert-dir
ou spécifié via la propriété CertificatesDir
de votre fichier de configuration.
Par défaut, le répertoire est /etc/kubernetes/pki
.
S'il existe un certificat et une clef privée dans ce répertoire, alors kubeadm sautera l'étape de génération et les fichiers fournis seront utilisés.
Cela signifie que vous pouvez, par exemple, copier un CA (Certificate Authority) existant vers /etc/kubernetes/pki/ca.crt
et /etc/kubernetes/pki/ca.key
, et kubeadm utilisera ce CA pour signer le reste des certificats.
Mode CA externe
Il est aussi possible de fournir seulement le fichier ca.crt
sans le fichier
ca.key
(seulement dans le cas d'un fichier CA racine, pas pour d'autres paires de certificats).
Si tous les certificats et fichiers kubeconfig sont en place, kubeadm activera le mode "CA externe".
Kubeadm continuera sans clef CA locale.
Ou alors, vous pouvez utiliser l'outil controller-manager avec --controllers=csrsigner
en fournissant les emplacements du certificat CA et la clef.
Gérer le fichier kubeadm ad-hoc pour kubelet
Le paquet kubeadm vient avec de la configuration concernant comment kubelet doit se comporter.
Vous remarquerez que la commande CLI kubeadm
ne modifiera jamais ce fichier.
Ce fichier ad-hoc appartient au paquet deb/rpm de kubeadm.
Pour en savoir plus sur comment kubeadm gère kubelet, vous pouvez consulter cette page.
Utilisation de kubeadm avec des runtimes CRI
Depuis la version v1.6.0, Kubernetes a rendu possible par défaut l'utilisation de CRI, Container Runtime Interface.
Le runtime utilisé par défaut est Docker, activé à travers l'adaptateur fourni dockershim
, une implémentation CRI, à l'intérieur de kubelet
.
Parmi les autres runtimes CRI, on retrouvera :
Se référer aux instructions d'installation CRI pour plus d'information.
Après avoir installé kubeadm
et kubelet
, exécuter ces étapes additionnelles :
Installer l'adaptateur runtime sur chaque noeud, en suivant les instructions d'installation du projet mentionné ci-dessus.
Configurer kubelet pour utiliser le runtime CRI distant. Ne pas oublier de modifier
RUNTIME_ENDPOINT
en utilisant la valeur adéquate/var/run/{your_runtime}.sock
:
cat > /etc/systemd/system/kubelet.service.d/20-cri.conf <<EOF
[Service]
Environment="KUBELET_EXTRA_ARGS=--container-runtime=remote --container-runtime-endpoint=$RUNTIME_ENDPOINT"
EOF
systemctl daemon-reload
Maintenant kubelet
est prête à utiliser le runtime CRI spécifié, et vous pouvez reprendre la séquence de déploiement avec kubeadm init
et kubeadm join
pour déployer votre cluster Kubernetes.
Il est aussi possible de configurer --cri-socket
à kubeadm init
et kubeadm reset
lorsque vous utilisez une implémentation CRI externe.
Paramétrer le nom du noeud
Par défaut, kubeadm
donne un nom au noeud en utilisant l'adresse de la machine. Vous pouvez outrepasser ce réglage en utilisant l'option --node-name
.
Cette option se chargera de passer la valeur appropriée pour --hostname-override
à kubelet.
Faîtes attention car forcer un nom d'hôte peut interférer avec les fournisseurs de cloud.
Héberger soi même le control plane Kubernetes
A partir de la version 1.8, vous pouvez expérimentalement créer un control plane Kubernetes auto-hébergé (self-hosted) . Cela signifie que des composants clefs comme le serveur d'API, le controller manager et l'ordonnanceur sont démarrés en tant que pods DaemonSet, configurés via l'API Kubernetes plutôt qu'en tant que pods static configurés avec des fichiers statiques dans kubelet.
Pour créer un cluster auto-hébergé, se référer à la commande kubeadm alpha selfhosting
.
Avertissements
L'auto-hébergement dans la version 1.8 et au delà comporte de sérieuses limitations. En particulier, un cluster auto-hébergé ne peut pas survivre au redémarrage du noeud control plane sans intervention manuelle.
Un cluster auto-hébergé ne peut pas être mis à jour via la commande
kubeadm upgrade
.Par défaut, les Pods d'un control plane auto-hébergé dépendent des identifiants chargés depuis des volumes de type
hostPath
A part pour la création initiale, ces identifiants ne sont pas gérés par kubeadm.La partie auto-hébergée du control plane n'inclut pas etcd, qui fonctionne toujours en tant que Pod statique.
Procédé
Le procédé de démarrage auto-hébergé est documenté dans le document de conception de kubeadm.
En bref, kubeadm alpha selfhosting
fonctionne de la manière suivante :
Attend que le control plane statique soit démarré correctement. C'est la même chose que le procédé
kubeadm init
lorsque non auto-hébergé.Utilise les manifestes du Pod statique du control plane pour construire un ensemble de manifestes DaemonSet qui vont lancer le control plane auto-hébergé. Cela modifie aussi les manifestes si nécessaires, par example pour ajouter des nouveaux volumes pour des secrets.
Crée des DaemonSets dans le namespace
kube-system
et attend que les pods ainsi créés soient démarrés.Une fois que les Pods auto-hébergés sont opérationnels, les Pods statiques qui leurs sont associés sont supprimés et kubeadm installe ensuite le prochain composant. Cela déclenche l'arrêt par kubelet de ces Pods statiques.
Quand le control plane statique d'origine s'arrête, le nouveau control plane auto-hébergé est capable d'écouter sur les mêmes ports et devenir actif.
Utiliser kubeadm sans connexion internet
Pour utiliser kubeadm sans connexion internet, vous devez télécharger les images requises par le control plane à l'avance.
A partir de Kubernetes 1.11, vous pouvez lister et télécharger les images en utilisant les sous commandes à kubeadm config images
:
kubeadm config images list
kubeadm config images pull
A partir de Kubernetes 1.12, les images prefixées par registry.k8s.io/kube-*
, registry.k8s.io/etcd
et registry.k8s.io/pause
ne nécessitent pas un suffix -${ARCH}
.
Automatiser kubeadm
Plutôt que copier sur chaque noeud le jeton que vous avez obtenu avec kubeadm init
, comme décrit dans
le tutoriel basique de kubeadm, vous pouvez paralléliser la distribution du jeton afin d'automatiser cette tâche.
Pour ce faire, vous devez connaître l'adresse IP que le noeud control plane obtiendra après son démarrage.
Générer un jeton. Ce jeton doit avoir correspondre à la chaîne suivante :
<6 caractères>.<16 caractères>
. Plus simplement, il doit correspondre à la regexp suivante :[a-z0-9]{6}\.[a-z0-9]{16}
.kubeadm peut générer un jeton pour vous :
kubeadm token generate
Démarrer en parallèle le noeud control plane et les noeuds worker nodes avec ce jeton. Lors de leurs démarrages, ils devraient pouvoir se trouver les uns les autres et former le cluster. L'option
--token
peut être utilisée aussi bien pourkubeadm init
que pourkubeadm join
.
Une fois que le cluster est correctement démarré, vous pouvez obtenir les identifiants admin depuis le noeud control plane depuis le fichier /etc/kubernetes/admin.conf
et les utiliser pour communiquer avec le cluster.
Vous remarquerez que ce type d'installation présente un niveau de sécurité inférieur puisqu'il ne permet pas la validation du hash du certificat racine avec --discovery-token-ca-cert-hash
(puisqu'il n'est pas généré quand les noeuds sont provisionnés). Pour plus d'information, se référer à kubeadm join.
A suivre
- kubeadm init phase pour mieux comprendre les phases
kubeadm init
- kubeadm join pour amorcer un noeud Kubernetes worker node Kubernetes et le faire joindre le cluster
- kubeadm upgrade pour mettre à jour un cluster Kubernetes vers une version plus récente
- kubeadm reset pour annuler les changements appliqués avec
kubeadm init
oukubeadm join
à un noeud