Ce document a été traduit à l'aide d'une technologie de traduction automatique. Bien que nous nous efforcions de fournir des traductions exactes, nous ne fournissons aucune garantie quant à l'exhaustivité, l'exactitude ou la fiabilité du contenu traduit. En cas de divergence, la version originale anglaise prévaut et fait foi.

Enregistrement des clusters existants

La fonctionnalité d’enregistrement de cluster a remplacé la fonctionnalité d’importation de clusters.

Le contrôle que Rancher a pour gérer un cluster enregistré dépend du type de cluster. Pour plus de détails, voir Capacités de gestion des clusters enregistrés.

Conditions préalables

Kubernetes Node Roles

Les clusters Kubernetes RKE enregistrés doivent avoir les trois rôles de nœuds - etcd, controlplane et worker. Un cluster avec uniquement des composants de controlplane ne peut pas être enregistré dans Rancher.

Pour plus d’informations sur les rôles de nœuds RKE, voir le meilleures pratiques.

Autorisations

Pour enregistrer un cluster dans Rancher, vous devez avoir des privilèges cluster-admin au sein de ce cluster. Si ce n’est pas le cas, accordez ces privilèges à votre utilisateur en exécutant :

kubectl create clusterrolebinding cluster-admin-binding \
  --clusterrole cluster-admin \
  --user [USER_ACCOUNT]

Puisque, par défaut, Google Kubernetes Engine (GKE) n’accorde pas le rôle cluster-admin, vous devez exécuter ces commandes sur les clusters GKE avant de pouvoir les enregistrer. Pour en savoir plus sur le contrôle d’accès en fonction du rôle pour GKE, veuillez consulter la documentation officielle de Google.

Elastic Kubernetes Service (EKS), Azure Kubernetes Service (AKS) et Google Kubernetes Engine (GKE)

Pour importer ou provisionner avec succès des clusters EKS, AKS et GKE depuis Rancher, le cluster doit avoir au moins un groupe de nœuds géré.

Les clusters AKS ne peuvent être importés que si les comptes locaux sont activés. Si un cluster est configuré pour utiliser Microsoft Entra ID pour l’authentification, alors Rancher ne pourra pas l’importer et signalera une erreur.

Les clusters EKS Anywhere peuvent être importés/enregistrés dans Rancher avec une adresse API et des identifiants, comme tout autre cluster en aval. Les clusters EKS Anywhere sont considérés comme des clusters importés et n’ont pas de support complet du cycle de vie de Rancher.

Les clusters GKE Autopilot ne sont pas pris en charge. Voir Comparer GKE Autopilot et Standard pour plus d’informations sur les différences entre les modes GKE.

Enregistrement d’un cluster

  1. Cliquez sur ☰ > Gestion des clusters.

  2. Sur la page Clusters, Importer un cluster existant.

  3. Choisissez le type de cluster.

  4. Utilisez les Rôles de membre pour configurer l’autorisation des utilisateurs pour le cluster. Cliquez sur Ajouter un membre pour ajouter des utilisateurs pouvant accéder au cluster. Utilisez le menu déroulant Rôle pour définir les permissions pour chaque utilisateur.

  5. Si vous importez un cluster Kubernetes générique dans Rancher, effectuez les étapes suivantes pour la configuration :

    1. Cliquez sur Variables d’environnement de l’agent sous Options du cluster pour définir les variables d’environnement pour agent de cluster rancher. Les variables d’environnement peuvent être définies à l’aide de paires clé-valeur. Si l’agent Rancher nécessite l’utilisation d’un proxy pour communiquer avec le serveur Rancher, les variables d’environnement HTTP_PROXY, HTTPS_PROXY et NO_PROXY peuvent être définies à l’aide des variables d’environnement de l’agent.

    2. Activez l’isolement du réseau de projet pour garantir que le cluster prend en charge les ressources Kubernetes NetworkPolicy. Les utilisateurs peuvent sélectionner l’option Isolement du réseau de projet dans le menu déroulant Options avancées pour ce faire.

    3. Configurer la fonctionnalité de gestion des versions pour les clusters RKE2 et K3s importés.

  6. Cliquez sur Create.

  7. Le prérequis pour les privilèges cluster-admin est indiqué (voir Prérequis ci-dessus), y compris une commande d’exemple pour satisfaire le prérequis.

  8. Copiez la commande kubectl dans votre presse-papiers et exécutez-la sur un nœud où kubeconfig est configuré pour pointer vers le cluster que vous souhaitez importer. Si vous n’êtes pas sûr qu’il soit configuré correctement, exécutez kubectl get nodes pour vérifier avant d’exécuter la commande affichée dans Rancher.

  9. Si vous utilisez des certificats auto-signés, vous recevrez le message certificate signed by unknown authority. Pour contourner cette validation, copiez la commande commençant par curl affichée dans Rancher dans votre presse-papiers. Ensuite, exécutez la commande sur un nœud où kubeconfig est configuré pour pointer vers le cluster que vous souhaitez importer.

  10. Lorsque vous avez terminé d’exécuter la ou les commandes sur votre nœud, cliquez sur Terminé.

La variable d’environnement NO_PROXY n’est pas standardisée, et le format accepté de la valeur peut différer entre les applications. Lors de la configuration de la variable NO_PROXY pour Rancher, la valeur doit respecter le format attendu par Golang.

Plus précisément, la valeur doit être une chaîne délimitée par des virgules qui ne contient que des adresses IP, une notation CIDR, des noms de domaine ou des étiquettes DNS spéciales (par exemple *). Pour une description complète du format de valeur attendu, consultez la documentation Golang en amont.

Résultat :

  • Votre cluster est enregistré et a un état de En attente. Rancher déploie des ressources pour gérer votre cluster.

  • Vous pouvez accéder à votre cluster après que son état soit mis à jour à Actif.

  • Les clusters Actifs sont assignés à deux Projets : Default (contenant l’espace de noms default) et System (contenant les espaces de noms cattle-system, traefik, kube-public et kube-system, si présents).

Vous ne pouvez pas réenregistrer un cluster qui est actuellement actif dans une configuration Rancher.

Configuration d’un cluster EKS, AKS ou GKE importé avec Terraform

Vous devez définir uniquement les champs minimaux requis par Rancher lors de l’importation d’un cluster EKS, AKS ou GKE avec Terraform. C’est important car Rancher écrasera ce qui était dans la configuration du cluster avec toute configuration fournie par l’utilisateur.

Même une petite différence entre le cluster actuel et une configuration fournie par l’utilisateur pourrait avoir des résultats inattendus.

Les champs de configuration minimaux requis par Rancher pour importer des clusters EKS avec Terraform en utilisant eks_config_v2 sont les suivants :

  • cloud_credential_id

  • name

  • region

  • importé (ce champ doit toujours être défini sur true pour les clusters importés)

Exemple de configuration YAML pour les clusters EKS importés :

resource "rancher2_cluster" "my-eks-to-import" {
  name        = "my-eks-to-import"
  description = "Terraform EKS Cluster"
  eks_config_v2 {
    cloud_credential_id = rancher2_cloud_credential.aws.id
    name                = var.aws_eks_name
    region              = var.aws_region
    imported            = true
  }
}

Vous pouvez trouver des exemples supplémentaires pour d’autres fournisseurs de cloud dans la documentation du fournisseur Rancher2 Terraform.

Capacités de gestion pour les clusters enregistrés

Le contrôle que Rancher a pour gérer un cluster enregistré dépend du type de cluster.

Fonctionnalités pour tous les clusters enregistrés

Après l’enregistrement d’un cluster, le propriétaire du cluster peut :

Fonctionnalités supplémentaires pour les clusters SUSE® Rancher Prime: RKE2 et SUSE® Rancher Prime: K3s enregistrés

K3s est une distribution Kubernetes légère et entièrement conforme pour les installations en périphérie.

RKE2 est la distribution Kubernetes de nouvelle génération de Rancher pour les installations en datacenter et dans le cloud.

Lorsqu’un cluster RKE2 ou K3s est enregistré dans Rancher, Rancher le reconnaîtra. L’interface utilisateur de Rancher exposera les fonctionnalités disponibles pour tous les clusters enregistrés, ainsi que les options suivantes pour modifier et mettre à niveau le cluster :

Fonctionnalités supplémentaires pour les clusters EKS, AKS et GKE enregistrés

Rancher gère les clusters EKS, AKS ou GKE enregistrés de la même manière que les clusters créés dans Rancher. Cependant, Rancher ne détruit pas les clusters enregistrés lorsque vous les supprimez via l’interface utilisateur de Rancher.

Lorsque vous créez un cluster EKS, AKS ou GKE dans Rancher, puis que vous le supprimez, Rancher détruit le cluster. Lorsque vous supprimez un cluster enregistré via Rancher, le serveur Rancher se déconnecte du cluster. Le cluster reste actif, bien qu’il ne soit plus dans Rancher. Vous pouvez toujours accéder au cluster désenregistré de la même manière que vous l’avez fait avant de l’enregistrer.

Voir Capacités de gestion des clusters par type de cluster pour plus d’informations sur les fonctionnalités disponibles pour la gestion des clusters enregistrés.

Configuration de la gestion des versions pour les clusters SUSE® Rancher Prime: RKE2 et SUSE® Rancher Prime: K3s

Lorsque la gestion des versions est activée pour un cluster importé, le fait de le mettre à niveau en dehors de Rancher peut entraîner des conséquences inattendues.

La fonctionnalité de gestion des versions pour les clusters RKE2 et K3s importés peut être configurée à l’aide de l’une des options suivantes :

  • Par défaut global (par défaut) : Hérite du comportement du paramètre global gestion-des-versions-des-clusters-importés.

  • Vrai : Active la gestion des versions, permettant aux utilisateurs de contrôler la version de Kubernetes et la stratégie de mise à niveau du cluster via Rancher.

  • Faux : Désactive la gestion des versions, permettant aux utilisateurs de gérer la version de Kubernetes du cluster de manière indépendante, en dehors de Rancher.

Vous pouvez définir le comportement par défaut pour les clusters nouvellement créés ou existants réglés sur "Par défaut global" en modifiant le paramètre gestion-des-versions-des-clusters-importés.

Les modifications apportées au paramètre global gestion-des-versions-des-clusters-importés prennent effet lors du prochain cycle de réconciliation du cluster.

Si la gestion des versions est activée pour un cluster, Rancher déploiera l’appli system-upgrade-controller, ainsi que les Plans associés et d’autres ressources Kubernetes requises, sur le cluster. Si la gestion des versions est désactivée, Rancher supprimera ces composants du cluster.

Configuration des mises à niveau de cluster SUSE® Rancher Prime: RKE2 et SUSE® Rancher Prime: K3s

Il est recommandé de sauvegarder le cluster avant de procéder à la mise à niveau, conformément aux meilleures pratiques Kubernetes. Lors de la mise à niveau d’un cluster K3s à haute disponibilité avec une base de données externe, sauvegardez la base de données de la manière recommandée par le fournisseur de base de données relationnelle.

La concurrence est le nombre maximum de nœuds qui peuvent être indisponibles pendant une mise à niveau. Si le nombre de nœuds indisponibles est supérieur à la concurrence, la mise à niveau échouera. Si une mise à niveau échoue, vous devrez peut-être réparer ou supprimer les nœuds défaillants avant que la mise à niveau puisse réussir.

  • Concurrence du plan de contrôle : Le nombre maximum de nœuds serveur à mettre à niveau en une seule fois ; également le nombre maximum de nœuds serveur indisponibles

  • Concurrence des nœuds de travail : Le nombre maximum de nœuds de travail à mettre à niveau en même temps ; également le nombre maximum de nœuds de travail indisponibles

Dans la documentation RKE2 et K3s, les nœuds de plan de contrôle sont appelés nœuds serveur. Ces nœuds exécutent le maître Kubernetes, qui maintient l’état souhaité du cluster. Par défaut, ces nœuds de plan de contrôle peuvent recevoir des charges de travail programmées.

Également dans la documentation RKE2 et K3s, les nœuds avec le rôle de travail sont appelés nœuds agents. Toutes les charges de travail ou pods déployés dans le cluster peuvent être programmés sur ces nœuds par défaut.

Journalisation de débogage et dépannage pour les clusters enregistrés SUSE® Rancher Prime: RKE2 et SUSE® Rancher Prime: K3s

Les nœuds sont mis à niveau par l’Upgrade Controller fonctionnant dans le cluster en aval. En fonction de la configuration du cluster, Rancher déploie deux plans pour mettre à niveau les nœuds : un pour les nœuds de plan de contrôle et un pour les nœuds de travail. L’Upgrade Controller suit les plans et met à niveau les nœuds.

Pour activer la journalisation de débogage sur le déploiement de l’Upgrade Controller, modifiez le configmap pour définir la variable d’environnement de débogage sur true. Ensuite, redémarrez le pod system-upgrade-controller.

Les journaux créés par le system-upgrade-controller peuvent être consultés en exécutant cette commande :

kubectl logs -n cattle-system system-upgrade-controller

L’état actuel des plans peut être consulté avec cette commande :

kubectl get plans -A -o yaml

Si le cluster reste bloqué lors de la mise à niveau, redémarrez le system-upgrade-controller.

Pour éviter des problèmes lors de la mise à niveau, les meilleures pratiques de mise à niveau de Kubernetes doivent être suivies.

Support des points de terminaison de cluster autorisés pour les clusters SUSE® Rancher Prime: RKE2 et SUSE® Rancher Prime: K3s

Rancher prend en charge les points de terminaison de cluster autorisés (ACE) pour les clusters RKE2 et K3s enregistrés. Ce support comprend des étapes manuelles que vous effectuerez sur le cluster en aval pour activer l’ACE. Pour plus d’informations sur le point de terminaison de cluster autorisé, cliquez ici.

Remarques :

  • Ces étapes ne doivent être effectuées que sur les nœuds du plan de contrôle du cluster en aval. Vous devez configurer chaque nœud du plan de contrôle individuellement.

  • Les étapes suivantes fonctionneront à la fois sur les clusters RKE2 et K3s enregistrés dans v2.6.x ainsi que sur ceux enregistrés (ou importés) d’une version précédente de Rancher avec une mise à niveau vers v2.6.x.

  • Ces étapes modifieront la configuration des clusters RKE2 et K3s en aval et déploieront le kube-api-authn-webhook. Si une future mise en œuvre de l’ACE nécessite une mise à jour du kube-api-authn-webhook, cela devra également être fait manuellement. Pour plus d’informations sur ce webhook, cliquez ici.
Étapes manuelles à suivre sur le plan de contrôle de chaque cluster en aval pour activer l’ACE :

  1. Créez un fichier à /var/lib/rancher/{rke2,k3s}/kube-api-authn-webhook.yaml avec le contenu suivant :

     apiVersion: v1
 kind: Config
 clusters:
 ** name: Default
cluster:
  insecure-skip-tls-verify: true
  server: http://127.0.0.1:6440/v1/authenticate
 users:
 ** name: Default
user:
  insecure-skip-tls-verify: true
 current-context: webhook
 contexts:
 ** name: webhook
context:
  user: Default
  cluster: Default

  2. Ajoutez ce qui suit au fichier de configuration (ou créez-en un s’il n’existe pas) ; notez que l’emplacement par défaut est /etc/rancher/{rke2,k3s}/config.yaml :

     kube-apiserver-arg:
     - authentication-token-webhook-config-file=/var/lib/rancher/{rke2,k3s}/kube-api-authn-webhook.yaml

  3. Exécutez les commandes suivantes :

    sudo systemctl stop {rke2,k3s}-server
sudo systemctl start {rke2,k3s}-server

  4. Enfin, vous devez revenir à l’interface utilisateur de Rancher et modifier le cluster importé pour compléter l’activation de l’ACE. Cliquez sur ⋮ > Modifier la configuration, puis cliquez sur l’onglet Réseautage sous Configuration du cluster. Enfin, cliquez sur le bouton Activé pour Point de terminaison autorisé. Une fois l’ACE activé, vous avez alors la possibilité d’entrer un nom de domaine complet (FQDN) et des informations sur le certificat.

Le champ FQDN est optionnel, et s’il est renseigné, il doit pointer vers le cluster en aval. Les informations sur le certificat ne sont nécessaires que s’il y a un équilibreur de charge devant le cluster en aval utilisant un certificat non fiable. Si vous avez un certificat valide, alors rien ne doit être ajouté au champ Certificats CA.

Annotation des clusters enregistrés

Pour tous les types de clusters Kubernetes enregistrés, sauf pour les clusters Kubernetes RKE2 et K3s, Rancher n’a aucune information sur la façon dont le cluster est provisionné ou configuré.

Par conséquent, lorsque Rancher enregistre un cluster, il suppose que plusieurs capacités sont désactivées par défaut. Rancher suppose cela afin d’éviter d’exposer des options de l’interface utilisateur à l’utilisateur même lorsque les capacités ne sont pas activées dans le cluster enregistré.

Cependant, si le cluster a une certaine capacité, un utilisateur de ce cluster pourrait tout de même vouloir sélectionner la capacité pour le cluster dans l’interface utilisateur de Rancher. Pour ce faire, l’utilisateur devra indiquer manuellement à Rancher que certaines capacités sont activées pour le cluster.

En annotant un cluster enregistré, il est possible d’indiquer à Rancher qu’un cluster a reçu des capacités supplémentaires en dehors de Rancher.

L’annotation suivante indique les capacités d’Ingress. Notez que les valeurs des objets non primitifs doivent être encodées en JSON, avec des guillemets échappés.

"capabilities.cattle.io/ingressCapabilities": "[
  {
    "customDefaultBackend":true,
    "ingressProvider":"asdf"
  }
]"

Ces capacités peuvent être annotées pour le cluster :

  • ingressCapabilities

  • loadBalancerCapabilities

  • nodePoolScalingSupported

  • nodePortRange

  • taintSupport

Toutes les capacités et leurs définitions de type peuvent être consultées dans la vue API de Rancher, à [Rancher Server URL]/v3/schemas/capabilities.

Pour annoter un cluster enregistré,

  1. Cliquez sur ☰ > Gestion des clusters.

  2. Sur la page Clusters, allez au cluster personnalisé que vous souhaitez annoter et cliquez sur ⋮ > Modifier la configuration.

  3. Développer la section Labels & Annotations.

  4. Cliquez sur Ajouter une annotation.

  5. Ajoutez une annotation au cluster au format capabilities/<capability>: <value> où value est la capacité du cluster qui sera remplacée par l’annotation. Dans ce scénario, Rancher n’est pas au courant des capacités du cluster tant que vous n’ajoutez pas l’annotation.

  6. Cliquez sur Enregistrer.

Résultat : L’annotation ne donne pas les capacités au cluster, mais elle indique à Rancher que le cluster possède ces capacités.

Dépannage

Cette section répertorie certaines des erreurs les plus courantes qui peuvent survenir lors de l’importation d’un cluster et fournit des étapes pour les résoudre.

AKS

L’erreur suivante peut survenir si les comptes locaux sont désactivés dans votre cluster :

Error: Getting static credential is not allowed because this cluster is set to disable local accounts.

Pour résoudre ce problème, activez les comptes locaux avant d’essayer d’importer le cluster à nouveau :

az aks update --resource-group <resource-group> --name <cluster-name> --enable-local-accounts