Préparer un hôte et une identité pour un nœud Flex (version préliminaire)

Important

Les fonctionnalités d’évaluation AKS sont disponibles en libre-service et font l’objet d’un abonnement. Les versions préliminaires sont fournies « en l’état » et « selon leur disponibilité » et ne sont pas couvertes par les accords de niveau de service ni par la garantie limitée. Les versions préliminaires d’AKS sont partiellement couvertes par le support client, dans la limite du raisonnable. Par conséquent, ces fonctionnalités ne sont pas destinées à une utilisation en production. Pour plus d’informations, consultez les articles de support suivants :

• Stratégies de support AKS
• FAQ du support Azure

Avant d’attacher un hôte Linux en tant que nœud flexible, préparez l’hôte, configurez l’identité que vous avez sélectionnée lors de la planification et accordez à cette identité l’accès au cluster Azure Kubernetes Service (AKS).

Dans cet article, vous :

• Passez en revue les exigences de l’hôte, puis approvisionnez ou sélectionnez l’hôte Linux et son identité Azure.
• Préparez et inspectez l’hôte, puis consignez les valeurs utilisées par le workflow de rattachement.
• Attribuez le rôle d’accès à l’identité au niveau du cluster AKS, puis vérifiez cette identité.

Exécutez les commandes de gestion dans cet article dans un environnement Bash compatible Linux qui dispose des outils et de l’accès réseau requis. Cet article désigne cet environnement comme votre environnement Bash. L’ordinateur distinct qui rejoint le cluster est l’hôte de nœud Flex ; exécutez des commandes sur celui-ci uniquement lorsqu’une étape vous l’indique explicitement.

Avant de commencer

• Configurez la mise en réseau et créez un pool de nœuds flexibles dans AKS.
• Passez en revue les concepts d’identité et d’accès pour les nœuds flexibles et sélectionnez une option d’identité.
• Utilisez un compte Azure qui peut inspecter la ressource hôte et créer une attribution de rôle dans l’étendue du cluster AKS. Role Based Access Control Administrator et User Access Administrator sont des exemples de rôles qui peuvent créer l’attribution.
• Installez Azure CLI et un client OpenSSH dans votre environnement Bash.
• Préparez une paire de clés SSH acceptée par l’hôte.

Charger l’environnement de déploiement

Démarrez une nouvelle session Bash, identifiez le fichier d’environnement à partir de l’article de planification et chargez-le. Remplacez par <deployment-name> votre étiquette de déploiement.

export FLEXNODE_DEPLOYMENT="<deployment-name>"
export FLEXNODE_ENV_FILE="${HOME}/.config/aks-flexnode/${FLEXNODE_DEPLOYMENT}.env"
test -s "${FLEXNODE_ENV_FILE}"
source "${FLEXNODE_ENV_FILE}"

Le fichier d’environnement fournit les valeurs de déploiement partagées lues par cet article, notamment WORK_DIRle répertoire dans votre environnement Bash où cet article stocke les fichiers téléchargés et générés. Par défaut, WORK_DIR est ~/.local/share/aksflexnode/<deployment-name>. L’article dérive toutes les autres variables dont elle a besoin. Si vous n’avez pas encore créé le fichier d’environnement, commencez par planifier votre déploiement de nœuds flexibles .

Si le fichier est introuvable ou ne peut pas être chargé, arrêtez et revenez à l’article de planification avant de continuer.

Définissez l’abonnement actif et confirmez le cluster sélectionné :

az account set --subscription "${SUBSCRIPTION_ID}"

az aks show \
    --resource-group "${RESOURCE_GROUP}" \
    --name "${CLUSTER_NAME}" \
    --query "{Name:name,ResourceId:id,ProvisioningState:provisioningState}" \
    --output table

Continuez lorsque l’ID de ressource correspond AKS_RESOURCE_ID et que l’état d’approvisionnement est Succeeded.

1. Passez en revue les conditions requises pour l’hôte

Utilisez un hôte dédié qui répond aux exigences suivantes :

• Hôte AMD64 ou ARM64 exécutant Ubuntu 24.04 LTS, Azure Linux 3.x ou Red Hat Enterprise Linux (RHEL) 9 ou 10.
• Nom d’hôte unique qui est un nom de sous-domaine DNS valide. L’agent le convertit en minuscules lorsqu’il enregistre le nœud.
• Au moins quatre processeurs virtuels et au moins 8 Gio libres sous /var/lib.
• Un compte SSH avec un accès root ou un accès sans mot de passe sudo sur l’hôte.
• Accès réseau au serveur d’API AKS, à Azure Resource Manager, à Microsoft Entra ID, à la version sélectionnée du nœud flexible et au miroir d’artefacts sélectionné, ainsi qu’aux registres de conteneurs requis.
• Connectivité de couche 3 existante entre le réseau hôte de nœud flexible et le réseau de nœuds géré par AKS. L'hôte et le cluster AKS ne doivent pas être dans la même région Azure.

Votre environnement Bash doit également être en mesure de se connecter à l’hôte de nœud flex via SSH. Une adresse IP publique n’est pas nécessaire lorsque vous disposez d’un autre chemin de gestion approuvé.

2. Configurer ou sélectionner l’hôte et l’identité

Terminez uniquement la section de l’option d’identité sélectionnée dans Les concepts d’identité et d’accès pour les nœuds flexibles. Ne configurez pas plus d’un mode d’identité Azure durable pour le même hôte.

Tip

Connexion d’un ordinateur en dehors de Azure ? Utilisez une identité managée Azure Arc si l’ordinateur est déjà activé par Arc ou utilisez un principal de service. Utilisez Azure identité managée de machine virtuelle uniquement lorsque l’hôte de nœud flex est une machine virtuelle Azure.

Définissez les chemins de clé SSH utilisés par chaque option d’identité :

export SSH_PRIVATE_KEY_PATH="<path-to-private-key>"
export SSH_PUBLIC_KEY_PATH="<path-to-public-key>"

Chaque option d’identité établit également deux adresses hôtes. FLEX_HOST_SSH_TARGET est l’adresse utilisée par votre environnement Bash. FLEX_HOST_PRIVATE_IP est l’adresse de l’hôte accessible à partir du réseau de nœuds géré par AKS. Vérifiez auprès de votre administrateur réseau que FLEX_HOST_PRIVATE_IP appartient à FLEX_HOST_SUBNET_CIDR et correspond à l’adresse accessible à partir du réseau de nœuds gérés par AKS. N’utilisez pas d’adresse publique ou de gestion distincte comme adresse de nœud flex.

Utiliser une identité managée Azure Arc

Utilisez cette option pour un hôte déjà connecté à Azure Arc. Si nécessaire, suivez Connecter des machines hybrides avec des serveurs Azure Arc.

Définissez les valeurs des ressources Arc et les adresses d’hôte :

export ARC_RESOURCE_GROUP="<arc-machine-resource-group>"
export ARC_MACHINE_NAME="<arc-machine-name>"
export FLEX_HOST_SSH_TARGET="<admin-user>@<reachable-host-address>"
export FLEX_HOST_PRIVATE_IP="<private-ip-reachable-from-aks>"

Récupérez l’ID de ressource, l’état de la connexion et l’ID d’objet principal :

ARC_RESOURCE_ID="/subscriptions/${SUBSCRIPTION_ID}/resourceGroups/${ARC_RESOURCE_GROUP}/providers/Microsoft.HybridCompute/machines/${ARC_MACHINE_NAME}"
export ARC_RESOURCE_ID

HOST_PRINCIPAL_OBJECT_ID="$(az resource show \
    --ids "${ARC_RESOURCE_ID}" \
    --query identity.principalId \
    --output tsv)"
export HOST_PRINCIPAL_OBJECT_ID

az resource show \
    --ids "${ARC_RESOURCE_ID}" \
    --query "{Name:name,Status:properties.status,IdentityType:identity.type,PrincipalId:identity.principalId}" \
    --output yaml

Continuez lorsque l’état est Connected et principalId est rempli.

Vérifiez l’agent Connected Machine et le service de métadonnées d’instance hybride sur l’hôte :

ssh -i "${SSH_PRIVATE_KEY_PATH}" "${FLEX_HOST_SSH_TARGET}" \
    'sudo azcmagent show && systemctl is-active himdsd'

Vérifiez que azcmagent show indique le même ID d’abonnement, le même groupe de ressources et le même nom d’ordinateur que ARC_RESOURCE_ID, ARC_RESOURCE_GROUP et ARC_MACHINE_NAME. Vérifiez également que himdsd est actif. Si la ressource ne correspond pas, arrêtez et corrigez les valeurs de ressource Arc avant d’attribuer l’accès.

Enregistrez les valeurs d’Arc et d’identité :

set_flexnode_env ARC_RESOURCE_GROUP "${ARC_RESOURCE_GROUP}"
set_flexnode_env ARC_MACHINE_NAME "${ARC_MACHINE_NAME}"
set_flexnode_env ARC_RESOURCE_ID "${ARC_RESOURCE_ID}"
set_flexnode_env FLEX_HOST_SSH_TARGET "${FLEX_HOST_SSH_TARGET}"
set_flexnode_env FLEX_HOST_PRIVATE_IP "${FLEX_HOST_PRIVATE_IP}"
set_flexnode_env HOST_PRINCIPAL_OBJECT_ID "${HOST_PRINCIPAL_OBJECT_ID}"
set_flexnode_env HOST_IDENTITY_CLIENT_ID ""

Utiliser un principal de service

Utilisez cette option pour une autre machine virtuelle ou un autre hôte bare metal pris en charge. Préférez des informations d’identification basées sur un certificat à un secret client à longue durée de vie. Les étapes suivantes créent une application et un principal de service dédiés avec un certificat auto-signé pour l’évaluation. Ils ne créent pas de secret client et n’attribuent pas de rôle Azure. Vous accordez l’accès au cluster AKS cible à l’étape 4.

Avant de continuer :

• Installez OpenSSL dans votre environnement Bash et utilisez une up-to-date Azure CLI qui prend en charge az login --certificate.
• Connectez-vous avec un compte qui peut inscrire des applications et créer des principaux de service dans le locataire Microsoft Entra associé à l’abonnement cible. Le simple fait d’être propriétaire d’un abonnement Azure ne confère pas ces autorisations de l’annuaire. Si votre tenant restreint l’enregistrement des applications, demandez de l’aide à votre administrateur de tenant. Consultez Créer un principal de service Azure avec le Azure CLI.
• Vérifiez que votre organisation autorise les certificats auto-signés à des fins d’évaluation. Pour une identité approuvée existante, utilisez son ID de locataire, son ID client d’application, l’ID d’objet du principal de service et le fichier PEM protégé, puis passez à Enregistrer le principal de service et les valeurs d’hôte.

Ne stockez pas les informations d’identification, la clé privée ou le chemin d’accès des informations d’identification dans le fichier d’environnement partagé. N’imprimez pas le fichier PEM ni ne l’incluez dans le contrôle de code source. Le fichier PEM contient une clé privée non chiffrée afin que l’agent puisse s’authentifier sans invite de mot de passe interactive. Protégez-le avec les autorisations de fichier et les contrôles d’accès d’hôte approuvés.

Créer un principal de service basé sur un certificat

Exécutez ces commandes dans votre environnement Bash lors de la connexion avec votre compte d’opérateur.

1. Vérifiez l’abonnement, le locataire et le compte avec lequel vous êtes connecté.

   az account set --subscription "${SUBSCRIPTION_ID}"
   az account show \
       --query "{SubscriptionId:id,TenantId:tenantId,Account:user.name}" \
       --output table
   
   SP_TENANT_ID="$(az account show --query tenantId --output tsv)"
   export SP_TENANT_ID
   

   Ne continuez que si l’abonnement et le locataire sont les cibles prévues.

2. Choisissez un nom d’affichage d’application unique et créez un répertoire d’identifiants protégé.

   export SP_DISPLAY_NAME="aks-flexnode-${FLEXNODE_DEPLOYMENT}-$(date -u +%Y%m%dT%H%M%SZ)"
   install -d -m 0700 "${WORK_DIR:?Load the deployment environment first.}"
   SP_CREDENTIAL_DIR="$(mktemp -d "${WORK_DIR}/sp-credential.XXXXXXXX")"
   export SP_CREDENTIAL_DIR
   export SP_CLIENT_CERTIFICATE_FILE="${SP_CREDENTIAL_DIR:?Credential directory wasn't created.}/sp-client.pem"
   

3. Créez un certificat de 30 jours et un fichier PEM combiné qui contient le certificat et la clé privée.

   (
       set -e
       umask 077
   
       openssl req -x509 -newkey rsa:2048 -sha256 -days 30 -nodes \
           -keyout "${SP_CREDENTIAL_DIR}/sp-client.key" \
           -out "${SP_CREDENTIAL_DIR}/sp-client.crt" \
           -subj "/CN=${SP_DISPLAY_NAME}"
   
       cat "${SP_CREDENTIAL_DIR}/sp-client.crt" \
           "${SP_CREDENTIAL_DIR}/sp-client.key" \
           > "${SP_CLIENT_CERTIFICATE_FILE}"
       chmod 0600 "${SP_CLIENT_CERTIFICATE_FILE}"
       rm -f "${SP_CREDENTIAL_DIR}/sp-client.key"
   )
   
   openssl x509 \
       -in "${SP_CREDENTIAL_DIR}/sp-client.crt" \
       -noout -subject -dates
   stat -c '%a %n' "${SP_CLIENT_CERTIFICATE_FILE}"
   

   Arrêtez si la création du certificat échoue. Vérifiez que les autorisations PEM sont 600. La validité de 30 jours est à des fins d’évaluation, et non une stratégie de rotation. Remplacez l’identifiant en suivant votre procédure approuvée avant qu’il n’expire si l’hôte reste rattaché.

4. Créez l’application et le principal de service en chargeant uniquement le certificat public.

   SP_CLIENT_ID="$(az ad sp create-for-rbac \
       --name "${SP_DISPLAY_NAME}" \
       --cert "@${SP_CREDENTIAL_DIR}/sp-client.crt" \
       --query appId \
       --output tsv)"
   export SP_CLIENT_ID
   

   Continuez uniquement lorsque la commande réussit et retourne un ID client d’application. La commande peut signaler qu’elle a ajusté la date de fin des informations d’identification pour qu’elle corresponde à l’expiration du certificat. N’ajoutez pas --role ni --scopes ; l’attribution de rôle ultérieure est limitée au cluster AKS. Ne réexécutez pas la création sur une application existante pour faire pivoter ses informations d’identification.

5. Récupérez l’identifiant d’objet du principal de service et examinez les informations d’identification enregistrées.

   SP_OBJECT_ID="$(az ad sp show \
       --id "${SP_CLIENT_ID}" \
       --query id \
       --output tsv)"
   export SP_OBJECT_ID
   
   az ad sp show \
       --id "${SP_CLIENT_ID}" \
       --query "{ClientId:appId,ServicePrincipalObjectId:id}" \
       --output table
   
   az ad app show \
       --id "${SP_CLIENT_ID}" \
       --query "{ClientId:appId,PasswordCredentials:length(passwordCredentials),Certificates:keyCredentials[].{KeyId:keyId,Expires:endDateTime}}" \
       --output json
   

   Vérifiez que l’ID d’objet du principal de service est renseigné, que les deux ID client sont identiques SP_CLIENT_ID, que PasswordCredentials est 0, et qu’exactement un certificat est enregistré avec l’expiration attendue. Si la réplication d’annuaire retarde la recherche, attendez brièvement et réessayez la recherche plutôt que de créer une autre application.

Pour un test d’informations d’identification uniquement, exécutez uniquement la vérification de l’authentification par certificat dans Vérifier un principal de service. Vous n'avez pas besoin d'attribuer un rôle Azure ou de préparer un hôte pour cette vérification. Une fois le test terminé, supprimez l’application de test dédiée et les informations d’identification locales.

Enregistrer le principal de service et les valeurs d’hôte

Définissez les adresses de l’hôte. Si vous avez sélectionné une identité existante, définissez d’abord SP_TENANT_ID, SP_CLIENT_ID et SP_OBJECT_ID avec ses identifiants.

export FLEX_HOST_SSH_TARGET="<admin-user>@<reachable-host-address>"
export FLEX_HOST_PRIVATE_IP="<private-ip-reachable-from-aks>"

: "${SP_TENANT_ID:?Set the Microsoft Entra tenant ID.}"
: "${SP_CLIENT_ID:?Set the application client ID.}"
: "${SP_OBJECT_ID:?Set the service principal object ID.}"
export HOST_IDENTITY_CLIENT_ID=""
export HOST_PRINCIPAL_OBJECT_ID="${SP_OBJECT_ID}"

set_flexnode_env FLEX_HOST_SSH_TARGET "${FLEX_HOST_SSH_TARGET}"
set_flexnode_env FLEX_HOST_PRIVATE_IP "${FLEX_HOST_PRIVATE_IP}"
set_flexnode_env SP_TENANT_ID "${SP_TENANT_ID}"
set_flexnode_env SP_CLIENT_ID "${SP_CLIENT_ID}"
set_flexnode_env SP_OBJECT_ID "${SP_OBJECT_ID}"
set_flexnode_env HOST_IDENTITY_CLIENT_ID "${HOST_IDENTITY_CLIENT_ID}"
set_flexnode_env HOST_PRINCIPAL_OBJECT_ID "${HOST_PRINCIPAL_OBJECT_ID}"

SP_OBJECT_ID est l’ID d’objet de l’application d’entreprise, également appelé l’ID d’objet du principal de service. Il ne s’agit pas de l’ID d’objet de l’inscription de l’application. Vérifiez que SP_CLIENT_ID, SP_OBJECT_IDet le certificat appartiennent au même principal de service.

Bootstrap mappe SP_TENANT_ID et SP_CLIENT_ID vers azure.servicePrincipal.tenantId et azure.servicePrincipal.clientId dans la configuration de l’agent généré. SP_OBJECT_IDest utilisé pour l'attribution de rôle Azure, et non comme ID client de l'agent. Pour connaître le champ de fichier de certificat, la forme de configuration mise en œuvre complète et les commandes de vérification sécurisée, consultez Inspecter la configuration du principal de service rendu.

Conservez le fichier PEM protégé pour la vérification d’identité et l’amorçage de l’hôte. Mettez-le à disposition sur l’hôte via votre processus approuvé de gestion des informations d’identification avant de l’attacher. Enregistrez son emplacement via votre processus de gestion des informations d’identification approuvés, et non dans le fichier d’environnement partagé. Poursuivez avec Préparer et inspecter l’hôte, puis attribuez le rôle AKS.

Utiliser une identité managée de machine virtuelle Azure

Utilisez cette option pour une machine virtuelle Azure. Créez une machine virtuelle en suivant le guide de démarrage rapide suivant : Créez une machine virtuelle Linux avec le Azure CLI, ou sélectionnez une machine virtuelle existante. Placez la machine virtuelle dans le réseau hôte de nœud flex planifié pour ce déploiement. Vous n’avez pas besoin d’une adresse IP publique lorsque votre environnement Bash a un autre chemin SSH approuvé.

Définissez les valeurs de machine virtuelle :

export VM_RESOURCE_GROUP="<vm-resource-group>"
export VM_NAME="<vm-name>"
export VM_ADMIN_USER="<vm-admin-user>"

Récupérez l’ID de ressource de machine virtuelle et les adresses hôtes. La cible SSH utilise l’adresse IP publique lorsque la machine virtuelle en a une et l’adresse privée sinon :

VM_RESOURCE_ID="$(az vm show \
    --resource-group "${VM_RESOURCE_GROUP}" \
    --name "${VM_NAME}" \
    --query id \
    --output tsv)"
export VM_RESOURCE_ID

FLEX_HOST_PRIVATE_IP="$(az vm show \
    --resource-group "${VM_RESOURCE_GROUP}" \
    --name "${VM_NAME}" \
    --show-details \
    --query privateIps \
    --output tsv)"
export FLEX_HOST_PRIVATE_IP

VM_PUBLIC_IP="$(az vm show \
    --resource-group "${VM_RESOURCE_GROUP}" \
    --name "${VM_NAME}" \
    --show-details \
    --query publicIps \
    --output tsv)"
export VM_PUBLIC_IP

export FLEX_HOST_SSH_TARGET="${VM_ADMIN_USER}@${VM_PUBLIC_IP:-${FLEX_HOST_PRIVATE_IP}}"

Vérifiez l’adresse privée renvoyée pour la VM :

az vm list-ip-addresses \
    --resource-group "${VM_RESOURCE_GROUP}" \
    --name "${VM_NAME}" \
    --query "[0].virtualMachine.{Name:name,PrivateAddresses:network.privateIpAddresses}" \
    --output table

Continuez uniquement lorsque FLEX_HOST_PRIVATE_IP contient une seule adresse privée qui appartient FLEX_HOST_SUBNET_CIDR et est accessible à partir du réseau de nœuds géré par AKS. Si Azure retourne plusieurs adresses, définissez FLEX_HOST_PRIVATE_IP l’adresse de nœud flexible planifiée avant de continuer.

Si la machine virtuelle n’a pas d’adresse IP publique ou si votre environnement Bash atteint l’hôte via un autre chemin de gestion approuvé, définissez FLEX_HOST_SSH_TARGET sur l’adresse ou le nom d’hôte que votre environnement Bash peut atteindre.

Effectuez l’une des options d’identité managée suivantes.

Identité gérée attribuée par le système

Activez l’identité managée affectée par le système :

az vm identity assign \
    --resource-group "${VM_RESOURCE_GROUP}" \
    --name "${VM_NAME}" \
    --output none

Récupérez son ID d’objet principal :

HOST_PRINCIPAL_OBJECT_ID="$(az vm show \
    --resource-group "${VM_RESOURCE_GROUP}" \
    --name "${VM_NAME}" \
    --query identity.principalId \
    --output tsv)"
export HOST_PRINCIPAL_OBJECT_ID

export HOST_IDENTITY_CLIENT_ID=""

Identité gérée attribuée par l’utilisateur

Créez ou sélectionnez une identité en suivant Gérer les identités managées affectées par l’utilisateur à l’aide du Azure CLI.

Définissez les valeurs d’identité :

export USER_ASSIGNED_IDENTITY_RESOURCE_GROUP="<identity-resource-group>"
export USER_ASSIGNED_IDENTITY_NAME="<identity-name>"

Récupérez les identificateurs d’identité :

USER_ASSIGNED_IDENTITY_RESOURCE_ID="$(az identity show \
    --resource-group "${USER_ASSIGNED_IDENTITY_RESOURCE_GROUP}" \
    --name "${USER_ASSIGNED_IDENTITY_NAME}" \
    --query id \
    --output tsv)"
export USER_ASSIGNED_IDENTITY_RESOURCE_ID

HOST_PRINCIPAL_OBJECT_ID="$(az identity show \
    --resource-group "${USER_ASSIGNED_IDENTITY_RESOURCE_GROUP}" \
    --name "${USER_ASSIGNED_IDENTITY_NAME}" \
    --query principalId \
    --output tsv)"
export HOST_PRINCIPAL_OBJECT_ID

HOST_IDENTITY_CLIENT_ID="$(az identity show \
    --resource-group "${USER_ASSIGNED_IDENTITY_RESOURCE_GROUP}" \
    --name "${USER_ASSIGNED_IDENTITY_NAME}" \
    --query clientId \
    --output tsv)"
export HOST_IDENTITY_CLIENT_ID

Affectez l’identité à la machine virtuelle :

az vm identity assign \
    --resource-group "${VM_RESOURCE_GROUP}" \
    --name "${VM_NAME}" \
    --identities "${USER_ASSIGNED_IDENTITY_RESOURCE_ID}" \
    --output none

Vérifiez que la machine virtuelle répertorie l’identité sélectionnée :

az vm identity show \
    --resource-group "${VM_RESOURCE_GROUP}" \
    --name "${VM_NAME}" \
    --query "{Type:type,UserAssignedIdentities:userAssignedIdentities}" \
    --output yaml

Continuez lorsque la sortie inclut USER_ASSIGNED_IDENTITY_RESOURCE_ID.

Enregistrer l’identité de la machine virtuelle

Enregistrez les valeurs de machine virtuelle et d’identité :

set_flexnode_env VM_RESOURCE_GROUP "${VM_RESOURCE_GROUP}"
set_flexnode_env VM_NAME "${VM_NAME}"
set_flexnode_env VM_ADMIN_USER "${VM_ADMIN_USER}"
set_flexnode_env VM_RESOURCE_ID "${VM_RESOURCE_ID}"
set_flexnode_env VM_PUBLIC_IP "${VM_PUBLIC_IP}"
set_flexnode_env FLEX_HOST_SSH_TARGET "${FLEX_HOST_SSH_TARGET}"
set_flexnode_env FLEX_HOST_PRIVATE_IP "${FLEX_HOST_PRIVATE_IP}"
set_flexnode_env HOST_PRINCIPAL_OBJECT_ID "${HOST_PRINCIPAL_OBJECT_ID}"
set_flexnode_env HOST_IDENTITY_CLIENT_ID "${HOST_IDENTITY_CLIENT_ID}"

3. Préparer et inspecter l’hôte

Connectez-vous à l’hôte :

ssh -i "${SSH_PRIVATE_KEY_PATH}" "${FLEX_HOST_SSH_TARGET}"

Sur l’hôte, inspectez le système d’exploitation, l’architecture, le nom d’hôte, le processeur et le stockage disponible :

source /etc/os-release
printf 'Operating system: %s %s\n' "${NAME}" "${VERSION_ID}"
printf 'Architecture: %s\n' "$(uname -m)"
printf 'Host name: %s\n' "$(hostname)"
printf 'vCPUs: %s\n' "$(nproc)"
free -h
df -h /var/lib

Comparez les résultats avec les exigences de l’hôte à l’étape 1. Résolvez toute différence avant de continuer.

Le script d’amorçage nécessite curl, jqet tar sur l’hôte et s’arrête si l’un d’eux est manquant. L’agent de nœud flex installe les packages d’exécution restants pendant le démarrage.

Installez l’un des trois que votre image n’inclut pas déjà :

# Ubuntu
sudo apt-get update && sudo apt-get install -y curl jq tar

# Azure Linux 3
sudo tdnf install -y curl jq tar

Quittez la session hôte :

exit

Lisez le nom d’hôte Linux réel de votre environnement Bash :

FLEX_HOST_NAME="$(ssh \
    -i "${SSH_PRIVATE_KEY_PATH}" \
    "${FLEX_HOST_SSH_TARGET}" \
    hostname)"
export FLEX_HOST_NAME

printf 'Flex host name: %s\n' "${FLEX_HOST_NAME}"

Continuez lorsque la commande retourne le nom d’hôte attendu.

Récupérez le nom de domaine complet du serveur d’API AKS et vérifiez la résolution de noms et la connectivité HTTPS à partir de l’hôte :

AKS_API_FQDN="$(az aks show \
    --resource-group "${RESOURCE_GROUP}" \
    --name "${CLUSTER_NAME}" \
    --query '(privateFqdn || fqdn)' \
    --output tsv)"
export AKS_API_FQDN

ssh -i "${SSH_PRIVATE_KEY_PATH}" "${FLEX_HOST_SSH_TARGET}" \
    "getent hosts '${AKS_API_FQDN}' && \
    timeout 5 bash -c '</dev/tcp/${AKS_API_FQDN}/443'"

Si la résolution de noms ou la connexion TCP échoue, corrigez dns, routage ou contrôles réseau avant de continuer. Un cluster AKS public utilise le FQDN de son API publique. Pour un cluster AKS privé, votre environnement Bash et le réseau hôte du nœud flexible doivent résoudre le nom de domaine complet (FQDN) de l’API privée et assurer le routage vers celui-ci.

Enregistrez les valeurs de l’hôte. Le fichier d’environnement partagé stocke les chemins d’accès et les identificateurs non-secret, et non le contenu des clés ou des informations d’identification.

set_flexnode_env SSH_PRIVATE_KEY_PATH "${SSH_PRIVATE_KEY_PATH}"
set_flexnode_env SSH_PUBLIC_KEY_PATH "${SSH_PUBLIC_KEY_PATH}"
set_flexnode_env FLEX_HOST_NAME "${FLEX_HOST_NAME}"

4. Attribuer le rôle AKS

Le flux de travail de préversion actuel utilise Azure Kubernetes Service rôle contributeur au niveau de l’étendue exacte du cluster AKS. Les trois options d’identité utilisent un ID d’objet principal de service pour Azure contrôle d’accès en fonction du rôle. Utilisez une identité d’hôte dédiée et supprimez cette affectation lorsque vous supprimez l’hôte, comme décrit dans Gérer et supprimer des nœuds flexibles dans AKS.

Affichez l’ID d’objet principal sélectionné :

printf 'Principal object ID: %s\n' "${HOST_PRINCIPAL_OBJECT_ID}"

Continuez uniquement lorsque la valeur est remplie et appartient à l’identité de machine virtuelle sélectionnée, à l’ordinateur Arc ou au principal de service.

Vérifiez si l’affectation existe déjà :

az role assignment list \
    --assignee-object-id "${HOST_PRINCIPAL_OBJECT_ID}" \
    --scope "${AKS_RESOURCE_ID}" \
    --fill-principal-name false \
    --query "[?roleDefinitionName=='Azure Kubernetes Service Contributor Role'].{PrincipalId:principalId,Role:roleDefinitionName,Scope:scope}" \
    --output table

Si la commande ne retourne aucune ligne, créez l’affectation :

az role assignment create \
    --assignee-object-id "${HOST_PRINCIPAL_OBJECT_ID}" \
    --assignee-principal-type ServicePrincipal \
    --role "Azure Kubernetes Service Contributor Role" \
    --scope "${AKS_RESOURCE_ID}" \
    --output none

Réexécutez la commande de liste. Continuez lorsque l’ID principal et l’étendue correspondent à l’identité sélectionnée et AKS_RESOURCE_ID. La propagation de l’attribution de rôle peut prendre plusieurs minutes.

5. Vérifier l’identité sélectionnée

Avant de démarrer l’hôte, vérifiez que l’identité sélectionnée peut s’authentifier et lire le cluster AKS cible exact. Remplissez uniquement la section correspondant à votre option d’identification.

Vérifier une identité managée d’Azure Arc

Dans votre environnement Bash, transmettez l’ID de ressource AKS non-secret au serveur compatible Azure Arc :

[[ "${AKS_RESOURCE_ID}" == /subscriptions/*/providers/Microsoft.ContainerService/managedClusters/* ]]
printf -v AKS_RESOURCE_ID_QUOTED '%q' "${AKS_RESOURCE_ID}"

ssh -t \
    -i "${SSH_PRIVATE_KEY_PATH}" \
    "${FLEX_HOST_SSH_TARGET}" \
    "export AKS_RESOURCE_ID=${AKS_RESOURCE_ID_QUOTED}; \
    exec bash -l"

Sur le serveur compatible Azure Arc, demandez un jeton Azure Resource Manager du service de métadonnées d’instance hybride (HIMDS) et utilisez-le pour lire la ressource AKS. La lecture du jeton de défi nécessite les privilèges root ou l'appartenance au groupe himds :

TOKEN_URL="${IDENTITY_ENDPOINT:-http://127.0.0.1:40342/metadata/identity/oauth2/token}?api-version=2019-11-01&resource=https%3A%2F%2Fmanagement.azure.com"

CHALLENGE_TOKEN_PATH="$(curl --silent --show-error \
    --dump-header - \
    --output /dev/null \
    --header Metadata:true \
    "${TOKEN_URL}" |
    sed -n 's/^[Ww][Ww][Ww]-[Aa]uthenticate: Basic realm=//p' |
    tr -d '\r')"

test -n "${CHALLENGE_TOKEN_PATH}"
CHALLENGE_TOKEN="$(sudo cat "${CHALLENGE_TOKEN_PATH}")"

TOKEN="$(curl --fail --silent --show-error \
    --header Metadata:true \
    --header "Authorization: Basic ${CHALLENGE_TOKEN}" \
    "${TOKEN_URL}" |
    jq -r '.access_token // empty')"

test -n "${TOKEN}"

AKS_ARM_HTTP="$(curl --silent --show-error \
    --output /dev/null \
    --write-out '%{http_code}' \
    --header "Authorization: Bearer ${TOKEN}" \
    "https://management.azure.com${AKS_RESOURCE_ID}?api-version=2025-07-01")"

unset CHALLENGE_TOKEN TOKEN
printf 'AKS_ARM_HTTP=%s\n' "${AKS_ARM_HTTP}"

Sortie attendue : AKS_ARM_HTTP=200. Exécutez exit pour quitter la session de serveur compatible Azure Arc.

Vérifier un principal de service

Dans votre environnement Bash, utilisez le fichier PEM combiné issu des étapes de préparation du principal du service. Si vous avez démarré une nouvelle session ou sélectionné une identité existante, définissez à nouveau son chemin protégé :

export SP_CLIENT_CERTIFICATE_FILE="<protected-path-to-sp-client.pem>"
test -s "${SP_CLIENT_CERTIFICATE_FILE}"

Arrêtez si le fichier n’existe pas ou est vide. N’ajoutez pas ce chemin d’accès au fichier d’environnement partagé.

Commencez par vérifier l’authentification par certificat avec un profil Azure CLI isolé. Le sous-interpréteur de commandes supprime son cache temporaire de jetons même lorsqu’une commande échoue et ne modifie pas votre connexion habituelle à Azure CLI.

(
    set -e
    SP_AZURE_CONFIG_DIR="$(mktemp -d)"
    chmod 0700 "${SP_AZURE_CONFIG_DIR}"
    trap 'rm -rf -- "${SP_AZURE_CONFIG_DIR}"' EXIT
    export AZURE_CONFIG_DIR="${SP_AZURE_CONFIG_DIR}"

    az login \
        --service-principal \
        --username "${SP_CLIENT_ID}" \
        --certificate "${SP_CLIENT_CERTIFICATE_FILE}" \
        --tenant "${SP_TENANT_ID}" \
        --allow-no-subscriptions \
        --output none

    az account get-access-token \
        --resource https://management.azure.com/ \
        --query "{Tenant:tenant,ExpiresOn:expiresOn}" \
        --output table
)

Vérifiez que le locataire correspond à SP_TENANT_ID et que le jeton n’a pas expiré. Cette commande affiche uniquement le tenant et l’expiration, pas le jeton d’accès. --allow-no-subscriptionsvous permet de tester l’authentification avant d’accorder Azure accès. L’authentification réussie ne prouve pas l’autorisation de lire ou d’inscrire auprès du cluster AKS.

Une fois que l’attribution de rôle AKS à l’étape 4 a été propagée, vérifiez l’accès au cluster cible exact :

(
    set -e
    SP_AZURE_CONFIG_DIR="$(mktemp -d)"
    chmod 0700 "${SP_AZURE_CONFIG_DIR}"
    trap 'rm -rf -- "${SP_AZURE_CONFIG_DIR}"' EXIT
    export AZURE_CONFIG_DIR="${SP_AZURE_CONFIG_DIR}"

    az login \
        --service-principal \
        --username "${SP_CLIENT_ID}" \
        --certificate "${SP_CLIENT_CERTIFICATE_FILE}" \
        --tenant "${SP_TENANT_ID}" \
        --output none

    az account set --subscription "${SUBSCRIPTION_ID}"

    az aks show \
        --resource-group "${RESOURCE_GROUP}" \
        --name "${CLUSTER_NAME}" \
        --query "{Name:name,ResourceId:id,ProvisioningState:provisioningState}" \
        --output table
)

Continuez uniquement lorsque l’ID de ressource retourné correspond AKS_RESOURCE_ID et que l’état d’approvisionnement est Succeeded. Si l’authentification réussit, mais que la demande de cluster est refusée, vérifiez l’ID d’objet du principal de service, l’étendue exacte de l’attribution de rôle et la propagation avant de réessayer. Cette vérification prouve que le principal de service et son certificat peuvent lire le cluster cible. L’hôte utilise les informations d’identification préparées dans Attacher un nœud flexible à un cluster AKS.

Vérifier une identité managée de machine virtuelle Azure

Dans votre environnement Bash, transmettez l’ID de ressource AKS non-secret et l’ID client d’identité à la machine virtuelle Azure :

[[ "${AKS_RESOURCE_ID}" == /subscriptions/*/providers/Microsoft.ContainerService/managedClusters/* ]]
printf -v AKS_RESOURCE_ID_QUOTED '%q' "${AKS_RESOURCE_ID}"
printf -v HOST_IDENTITY_CLIENT_ID_QUOTED '%q' "${HOST_IDENTITY_CLIENT_ID}"

ssh -t \
    -i "${SSH_PRIVATE_KEY_PATH}" \
    "${FLEX_HOST_SSH_TARGET}" \
    "export AKS_RESOURCE_ID=${AKS_RESOURCE_ID_QUOTED}; \
    export HOST_IDENTITY_CLIENT_ID=${HOST_IDENTITY_CLIENT_ID_QUOTED}; \
    exec bash -l"

Sur la machine virtuelle Azure, demandez un jeton Azure Resource Manager à partir de l’identité managée sélectionnée et utilisez-la pour lire la ressource AKS :

TOKEN_URL="http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https%3A%2F%2Fmanagement.azure.com%2F"

if [ -n "${HOST_IDENTITY_CLIENT_ID}" ]; then
    ENCODED_CLIENT_ID="$(jq -rn \
        --arg value "${HOST_IDENTITY_CLIENT_ID}" \
        '$value|@uri')"
    TOKEN_URL="${TOKEN_URL}&client_id=${ENCODED_CLIENT_ID}"
fi

TOKEN="$(curl --fail --silent --show-error \
    --header Metadata:true \
    "${TOKEN_URL}" |
    jq -r '.access_token // empty')"

test -n "${TOKEN}"

AKS_ARM_HTTP="$(curl --silent --show-error \
    --output /dev/null \
    --write-out '%{http_code}' \
    --header "Authorization: Bearer ${TOKEN}" \
    "https://management.azure.com${AKS_RESOURCE_ID}?api-version=2025-07-01")"

unset TOKEN
printf 'AKS_ARM_HTTP=%s\n' "${AKS_ARM_HTTP}"

Sortie attendue : AKS_ARM_HTTP=200. Pour une identité affectée par l’utilisateur, la requête utilise le même HOST_IDENTITY_CLIENT_ID que celui que le flux de travail d’attachement transmet à --msi-client-id. Exécutez exit pour quitter la session de machine virtuelle Azure.

Le flux de travail de pièce jointe effectue la dernière vérification de bout en bout lorsque l’hôte utilise l’identité sélectionnée pour inscrire sa ressource machine Azure.

Étape suivante

Ensuite, attachez et vérifiez l’hôte préparé en tant que nœud flexible.