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 "k8s.gcr.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 :

  1. 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>.

  2. 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.

  3. 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.

  4. 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.

  5. Applique les étiquettes (labels) et marques (taints) au noeud control-plane afin qu'aucune charge de travail additionnelle ne s'y exécute.

  6. 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.

  7. 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.

  8. 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 k8s.gcr.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 de k8s.gcr.io.
  • régler useHyperKubeImage à true pour utiliser l'image HyperKube.
  • fournir un imageRepository et un imageTag 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 :

  1. Installer l'adaptateur runtime sur chaque noeud, en suivant les instructions d'installation du projet mentionné ci-dessus.

  2. 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 joinpour 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

  1. 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.

  2. Un cluster auto-hébergé ne peut pas être mis à jour via la commande kubeadm upgrade.

  3. 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.

  4. 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 :

  1. 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é.

  2. 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.

  3. Crée des DaemonSets dans le namespace kube-system et attend que les pods ainsi créés soient démarrés.

  4. 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.

  5. 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 k8s.gcr.io/kube-*, k8s.gcr.io/etcd et k8s.gcr.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.

  1. 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

  2. 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 pour kubeadm init que pour kubeadm 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 ou kubeadm join à un noeud
Dernière modification July 29, 2021 at 5:59 PM PST : kubeadm: use k8s-staging-ci-images instead of kubernetes-ci-images (be9926dff)