Preparare l'host e l'identità di un nodo flex (anteprima)

Importante

Le funzionalità in anteprima di AKS sono disponibili in modalità self-service, su base volontaria. Le anteprime vengono fornite "così come sono" e "come disponibili" e sono escluse dai contratti di servizio e dalla garanzia limitata. Le anteprime di AKS sono coperte solo parzialmente dall'assistenza clienti nei limiti del possibile. Di conseguenza, queste funzionalità non sono destinate all'uso in produzione. Per altre informazioni, vedere gli articoli di supporto seguenti:

• Criteri di supporto di AKS
• Domande frequenti sul supporto tecnico di Azure

Prima di collegare un host Linux come nodo flessibile, preparare l'host, configurare l'identità selezionata durante la pianificazione e concedere l'accesso all'identità al cluster Servizio Azure Kubernetes (AKS).

In questo articolo, tu:

• Esaminare i requisiti dell'host e quindi effettuare il provisioning o selezionare l'host Linux e la relativa identità Azure.
• Preparare ed esaminare l'host e registrare i valori usati dal flusso di lavoro degli allegati.
• Assegnare l'accesso all'identità nell'ambito del cluster del servizio Azure Kubernetes e verificare l'identità.

Eseguire i comandi di gestione in questo articolo in un ambiente Bash compatibile con Linux con gli strumenti e l'accesso alla rete necessari. Questo articolo definisce quell'ambiente il tuo ambiente Bash. Il computer separato che si unisce al cluster è l'host del nodo Flex; esegui i comandi lì solo quando un passaggio lo indica esplicitamente.

Prima di iniziare

• Completa Configurare la rete e creare un pool di nodi flex in AKS.
• Esaminare i concetti relativi all'identità e all'accesso per i nodi flex e selezionare un'opzione di identità.
• Usare un account Azure che possa ispezionare la risorsa host e creare un'assegnazione di ruolo nell'ambito del cluster AKS. Role Based Controllo di accesso Administrator e User Access Administrator sono esempi di ruoli che possono creare l'assegnazione.
• Installare interfaccia della riga di comando di Azure e un client OpenSSH nell'ambiente Bash.
• Preparare una coppia di chiavi SSH accettata dall'host.

Caricare l'ambiente di distribuzione

Avviare una nuova sessione Bash, identificare il file di ambiente dall'articolo di pianificazione e caricarlo. Sostituisci <deployment-name> con l'etichetta di distribuzione.

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}"

Il file di ambiente fornisce i valori di distribuzione condivisi letti da questo articolo, inclusa WORK_DIRla directory nell'ambiente Bash in cui questo articolo archivia i file scaricati e generati. Per impostazione predefinita, WORK_DIR è ~/.local/share/aksflexnode/<deployment-name>. L'articolo deriva tutte le altre variabili necessarie. Se non hai ancora creato il file dell'ambiente, completa prima Pianifica la distribuzione dei nodi flessibili.

Se il file non viene trovato o non è possibile caricarlo, interrompere e tornare all'articolo di pianificazione prima di continuare.

Impostare la sottoscrizione attiva e confermare il cluster selezionato:

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

Continua quando l'ID della risorsa corrisponde a AKS_RESOURCE_ID e lo stato del provisioning è Succeeded.

1. Esaminare i requisiti dell'host

Usare un host dedicato che soddisfi i requisiti seguenti:

• Un host AMD64 o ARM64 che esegue Ubuntu 24.04 LTS, Azure Linux 3.x o Red Hat Enterprise Linux (RHEL) 9 o 10.
• Nome host univoco che è un nome di sottodominio DNS valido. L'agente lo converte in minuscolo quando registra il nodo.
• Almeno quattro vCPU e almeno 8 GiB gratis in /var/lib.
• Un account SSH con accesso root o accesso sudo senza password sull'host.
• Accesso di rete al server API di AKS, ad Azure Resource Manager, a Microsoft Entra ID, alla release del nodo flessibile selezionata e al mirror degli artefatti selezionato, nonché ai registri dei contenitori necessari.
• Connettività di livello 3 esistente tra la rete host del nodo flex e la rete del nodo gestita da AKS. L'host e il cluster AKS non devono trovarsi nella stessa area di Azure.

L'ambiente Bash deve anche essere in grado di connettersi all'host del nodo flex tramite SSH. Un indirizzo IP pubblico non è necessario quando si dispone di un altro percorso di gestione approvato.

2. Effettuare il provisioning o selezionare l'host e l'identità

Completare solo la sezione relativa all'opzione Identity selezionata in Concetti di identità e accesso per i nodi flessibili. Non configurare più di una modalità di identità durevole Azure per lo stesso host.

Tip

Connessione di un computer all'esterno di Azure? Usare un'identità gestita di Azure Arc se il computer è già abilitato per Arc o usare un'entità servizio. Usa identità gestita della VM di Azure solo quando l'host del nodo flex è una macchina virtuale di Azure.

Imposta i percorsi delle chiavi SSH utilizzati da ogni opzione di identità:

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

Ogni opzione di identità stabilisce anche due indirizzi host. FLEX_HOST_SSH_TARGET è l'indirizzo usato dall'ambiente Bash. FLEX_HOST_PRIVATE_IP è l'indirizzo host raggiungibile dalla rete dei nodi gestita da AKS. Confermare con l'amministratore di rete che FLEX_HOST_PRIVATE_IP faccia parte di FLEX_HOST_SUBNET_CIDR e che sia l'indirizzo raggiungibile dalla rete di nodi gestita da AKS. Non usare un indirizzo pubblico o esclusivamente per la gestione separato come indirizzo del nodo Flex.

Usare un'identità gestita Azure Arc

Usare questa opzione per un host già connesso a Azure Arc. Se necessario, seguire Connect hybrid machines with Azure Arc-enabled servers (Connettere computer ibridi con server abilitati per Azure Arc).

Impostare i valori delle risorse Arc e gli indirizzi host:

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

Recuperare l'ID risorsa, lo stato della connessione e l'ID oggetto principale:

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

Continuare quando status è Connected e PrincipalId viene popolato.

Verificare l'agente Connected Machine e il servizio metadati dell'istanza ibrida sull'host:

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

Verificare che azcmagent show restituisca lo stesso ID sottoscrizione, gruppo di risorse e nome del computer come ARC_RESOURCE_ID, ARC_RESOURCE_GROUPe ARC_MACHINE_NAME. Verificare anche che himdsd sia attivo. Se la risorsa non corrisponde, interrompere l'operazione e correggere i valori della risorsa Arc prima di assegnare l'accesso.

Annotare i valori di Arc e dell'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 ""

Usare un’entità servizio

Utilizzare questa opzione per un'altra macchina virtuale supportata o un host fisico. Preferire una credenziale basata su certificato rispetto a un segreto client a lunga scadenza. La procedura seguente consente di creare un'applicazione dedicata e un'entità servizio con un certificato autofirmato per la valutazione. Non creano un segreto client o assegnano un ruolo Azure. Concedi l'accesso al cluster AKS di destinazione nella fase 4.

Prima di continuare:

• Installare OpenSSL nell'ambiente Bash e usare un up-to-date interfaccia della riga di comando di Azure che supporta az login --certificate.
• Accedere con un account in grado di registrare applicazioni e creare entità servizio nel tenant di Microsoft Entra associato alla sottoscrizione di destinazione. La sola proprietà della sottoscrizione di Azure non concede queste autorizzazioni della directory. Se il tenant limita la registrazione delle applicazioni, chiedi assistenza all'amministratore del tenant. Vedi Creare un'entità servizio di Azure con l'interfaccia della riga di comando di Azure.
• Verificare che l'organizzazione consenta certificati autofirmato per la valutazione. Per un'identità approvata già esistente, usa l'ID del tenant, l'ID client dell'applicazione, l'ID oggetto del service principal e il file PEM protetto, quindi passa a Registrare il service principal e i valori host.

Non archiviare le credenziali, la chiave privata o il percorso delle credenziali nel file di ambiente condiviso. Non stampare il file PEM o includerlo nel controllo del codice sorgente. Il file PEM contiene una chiave privata non crittografata in modo che l'agente possa eseguire l'autenticazione senza una richiesta interattiva della password. Proteggerlo con autorizzazioni file e controlli di accesso host approvati.

Creare un'entità servizio basata su certificato

Eseguire questi comandi nell'ambiente Bash durante l'accesso con l'account dell'operatore.

1. Verificare la sottoscrizione, il tenant e l'account con cui è stato effettuato l'accesso.

   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
   

   Continuare solo quando la sottoscrizione e il tenant sono le destinazioni desiderate.

2. Scegliere un nome visualizzato univoco per l'applicazione e creare una directory protetta per le credenziali.

   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. Creare un certificato di 30 giorni e un file PEM combinato che contiene il certificato e la chiave privata.

   (
       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}"
   

   Interrompere se la creazione del certificato non riesce. Verificare che le autorizzazioni PEM siano 600. La validità di 30 giorni è per la valutazione, non per i criteri di rotazione. Sostituire le credenziali tramite il processo approvato prima della scadenza se l'host rimane collegato.

4. Crea l'applicazione e l'entità servizio caricando solo il certificato pubblico.

   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
   

   Continuare solo quando il comando ha esito positivo e restituisce un ID client dell'applicazione. Il comando può segnalare che ha modificato la data di fine delle credenziali in modo che corrisponda alla scadenza del certificato. Non aggiungere --role o --scopes; la successiva assegnazione del ruolo è limitata al cluster AKS. Non rieseguire il processo di creazione per un'applicazione esistente per ruotarne le credenziali.

5. Recuperare l'ID oggetto dell'entità servizio ed esaminare le credenziali registrate.

   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
   

   Verificare che l'ID oggetto del service principal sia popolato, che entrambi gli ID client corrispondano a SP_CLIENT_ID, che PasswordCredentials sia 0 e che sia registrato esattamente un solo certificato con la scadenza prevista. Se la replica della directory ritarda la ricerca, attendere brevemente e ripetere la ricerca anziché creare un'altra applicazione.

Per un test basato solo sulle credenziali, esegui solo la verifica dell'autenticazione tramite certificato in Verificare un service principal. Non è necessario assegnare un ruolo Azure o preparare un host per tale controllo. Al termine del test, eliminare l'applicazione di test dedicata e le credenziali locali.

Registrare i valori del service principal e dell'host

Impostare gli indirizzi host. Se hai selezionato un'identità esistente, imposta prima SP_TENANT_ID, SP_CLIENT_ID e SP_OBJECT_ID sui suoi identificatori.

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 è l'ID oggetto dell'applicazione Enterprise, detto anche ID oggetto dell'entità servizio. Non è l'ID oggetto della registrazione dell'app. Verifica che SP_CLIENT_ID, SP_OBJECT_ID e il certificato appartengano alla stessa entità principale del servizio.

Bootstrap associa SP_TENANT_ID e azure.servicePrincipal.tenantId a SP_CLIENT_ID e azure.servicePrincipal.clientId nella configurazione dell'agente generata. SP_OBJECT_IDviene usato per l'assegnazione di ruolo Azure, non come ID client dell'agente. Per il campo del file di certificato, la versione completa della configurazione con dati oscurati e i comandi di verifica sicuri, vedere Esaminare la configurazione generata dell'entità servizio.

Mantenere il file PEM protetto per la verifica dell'identità e il bootstrap dell'host. Renderlo disponibile sull'host secondo il processo approvato di gestione delle credenziali prima del collegamento. Registrare la sua posizione mediante il processo di gestione delle credenziali approvato, non nel file di ambiente condiviso. Procedere con Preparare e ispezionare l'host, quindi assegnare il ruolo AKS.

Usare un'identità gestita per una macchina virtuale di Azure

Usare questa opzione per una macchina virtuale Azure. Creare una macchina virtuale seguendo questa guida introduttiva: Creare una macchina virtuale Linux con il interfaccia della riga di comando di Azure o selezionare una macchina virtuale esistente. Posizionare la macchina virtuale nella rete host del nodo flex pianificata per questa distribuzione. Non è necessario un indirizzo IP pubblico quando l'ambiente Bash ha un altro percorso SSH approvato.

Impostare i valori della macchina virtuale:

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

Recuperare l'ID risorsa della macchina virtuale e gli indirizzi host. La destinazione SSH usa l'indirizzo IP pubblico quando la macchina virtuale ne ha una e l'indirizzo privato in caso contrario:

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}}"

Confermare l'indirizzo privato restituito per la macchina virtuale:

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

Continuare solo quando FLEX_HOST_PRIVATE_IP contiene un singolo indirizzo privato che appartiene a FLEX_HOST_SUBNET_CIDR ed è raggiungibile dalla rete dei nodi gestiti da AKS. Se Azure restituisce più di un indirizzo, impostare FLEX_HOST_PRIVATE_IP sull'indirizzo pianificato del nodo flessibile prima di continuare.

Se la macchina virtuale non ha un indirizzo IP pubblico o l'ambiente Bash raggiunge l'host tramite un altro percorso di gestione approvato, impostare FLEX_HOST_SSH_TARGET l'indirizzo o il nome host che l'ambiente Bash può raggiungere.

Completare una delle opzioni di identità gestite seguenti.

Identità gestita assegnata dal sistema

Abilitare l'identità gestita assegnata dal sistema:

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

Recuperare il relativo ID oggetto principale:

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à gestita assegnata dall'utente

Creare o selezionare un'identità seguendo le istruzioni per gestire le identità gestite assegnate dall'utente usando il interfaccia della riga di comando di Azure.

Impostare i valori di identità:

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

Recuperare gli identificatori di 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

Assegnare l'identità alla macchina virtuale:

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

Verificare che la macchina virtuale elenchi l'identità selezionata:

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

Continua quando l'output contiene USER_ASSIGNED_IDENTITY_RESOURCE_ID.

Registrare l'identità della macchina virtuale

Registrare i valori della macchina virtuale e dell'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. Preparare e ispezionare l'host

Connettersi all'host:

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

Sul host, esaminare il sistema operativo, l'architettura, il nome host, la CPU e lo spazio di archiviazione disponibile:

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

Confrontare i risultati con i requisiti dell'host nel passaggio 1. Risolvere qualsiasi differenza prima di continuare.

Lo script bootstrap richiede curl, jqe tar nell'host e si arresta se uno di essi è mancante. L'agente del nodo flex installa i pacchetti di runtime rimanenti durante il bootstrap.

Installa uno qualsiasi dei tre elementi non già inclusi nella tua immagine:

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

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

Uscire dalla sessione host:

exit

Leggi il nome effettivo dell'host Linux dal tuo ambiente 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}"

Continuare quando il comando restituisce il nome host previsto.

Recupera il FQDN del server API di AKS e verifica la risoluzione dei nomi e la connettività HTTPS dall'host:

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'"

Se la risoluzione dei nomi o la connessione TCP ha esito negativo, correggi le impostazioni DNS, di instradamento o di controllo della rete prima di continuare. Un cluster AKS pubblico usa il proprio FQDN API pubblico. Per un cluster AKS privato, l'ambiente Bash e la rete host del nodo flessibile devono risolvere e instradare verso l'FQDN dell'API privata.

Registrare i valori dell'host. Il file di ambiente condiviso archivia i percorsi e gli identificatori nonsecret, non il contenuto della chiave o delle credenziali.

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. Assegnare il ruolo AKS

L'attuale flusso di lavoro di anteprima usa il ruolo Collaboratore del servizio Azure Kubernetes nell'esatto ambito del cluster AKS. Tutte e tre le opzioni di identità utilizzano un ID oggetto di un'entità servizio per il controllo degli accessi in base al ruolo di Azure. Usa un'identità host dedicata e rimuovi questa assegnazione quando rimuovi l'host, come descritto in Gestire e rimuovere i flex nodes in AKS.

Visualizzare l'ID oggetto principale selezionato:

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

Continuare solo quando il valore viene popolato e appartiene all'identità della macchina virtuale, al computer Arc o all'entità servizio selezionata.

Controllare se l'assegnazione esiste già:

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

Se il comando non restituisce alcuna riga, creare l'assegnazione:

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

Eseguire di nuovo il comando list. Continuare quando l'ID entità e l'ambito corrispondono all'identità selezionata e AKS_RESOURCE_ID. La propagazione dell'assegnazione di ruolo può richiedere alcuni minuti.

5. Verificare l'identità selezionata

Prima di eseguire il bootstrap dell'host, verifica che l'identità selezionata possa autenticarsi e leggere lo specifico cluster AKS di destinazione. Completare solo la sezione relativa all'opzione di identità.

Verificare un'identità gestita di Azure Arc

Nell'ambiente Bash, passa l'ID della risorsa AKS non segreta al server abilitato per 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"

Nel server abilitato per Azure Arc, richiedere un token di Azure Resource Manager dal servizio di metadati dell'istanza ibrida (HIMDS) e utilizzarlo per leggere la risorsa AKS. Per leggere il token di verifica sono necessari i privilegi di root o l'appartenenza al gruppo 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}"

Output previsto: AKS_ARM_HTTP=200. Esegui exit per uscire dalla sessione del server abilitato per Azure Arc.

Verificare un service principal

Nell'ambiente Bash, usare il file PEM combinato ottenuto nei passaggi di preparazione dell'entità servizio. Se è stata avviata una nuova sessione o si è selezionata un'identità esistente, impostare di nuovo il percorso protetto:

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

Interrompi se il file non esiste o è vuoto. Non aggiungere questo percorso al file dell'ambiente condiviso.

Verificare prima di tutto l'autenticazione del certificato con un profilo di interfaccia della riga di comando di Azure isolato. La sottoshell rimuove la cache dei token temporanei anche quando un comando ha esito negativo e non modifica la normale interfaccia della riga di comando di Azure di accesso.

(
    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
)

Verificare che il tenant corrisponda SP_TENANT_ID e che il token non sia scaduto. Questo comando stampa solo il tenant e la scadenza, non il token di accesso. --allow-no-subscriptionsconsente di testare l'autenticazione prima di concedere Azure l'accesso. L'autenticazione riuscita non prova l'autorizzazione a leggere o a registrarsi nel cluster AKS.

Dopo che l'assegnazione di ruolo AKS nel passaggio 4 si è propagata, verificare l'accesso allo specifico cluster di destinazione:

(
    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
)

Continuare solo quando l'ID risorsa restituito corrisponde AKS_RESOURCE_ID e lo stato di provisioning è Succeeded. Se l'autenticazione ha esito positivo ma la richiesta al cluster viene negata, verificare l'ID oggetto dell'entità servizio, l'ambito esatto dell'assegnazione del ruolo e la propagazione prima di riprovare. Questa verifica conferma che il service principal e il relativo certificato possono leggere il cluster di destinazione. L'host usa la credenziale preparata in Collegare un nodo flessibile a un cluster AKS.

Verificare un'identità gestita della macchina virtuale Azure

Nell'ambiente Bash, passa l'ID risorsa non segreto di AKS e l'ID client dell'identità alla VM di 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"

Nella macchina virtuale di Azure, richiedi un token di Azure Resource Manager dall'identità gestita selezionata e usalo per leggere la risorsa 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}"

Output previsto: AKS_ARM_HTTP=200. Per un'identità assegnata dall'utente, la richiesta usa lo stesso HOST_IDENTITY_CLIENT_ID che il flusso di lavoro degli allegati passa a --msi-client-id. Eseguire exit per lasciare la sessione della macchina virtuale Azure.

Il flusso di lavoro degli allegati esegue il controllo end-to-end finale quando l'host usa l'identità selezionata per registrare la risorsa del computer Azure.

Passo successivo

Quindi, collegare e verificare l'host preparato come nodo Flex.