Einen Flex-Node-Host und eine Identität vorbereiten (Vorschau)

Important

AKS-Preview-Funktionen stehen auf Selbstbedienungs- und Opt-in-Basis zur Verfügung. Vorschauversionen werden „im Istzustand“ und „wie verfügbar“ bereitgestellt und sind von den Service Level Agreements und der eingeschränkten Garantie ausgeschlossen. AKS-Vorschauversionen werden teilweise vom Kundensupport auf Grundlage der bestmöglichen Leistung abgedeckt. Daher sind diese Funktionen nicht für die Verwendung in der Produktion vorgesehen. Weitere Informationen finden Sie in den folgenden Supportartikeln:

Bevor Sie einen Linux-Host als Flexknoten anfügen, bereiten Sie den Host vor, konfigurieren Sie die identität, die Sie während der Planung ausgewählt haben, und gewähren Sie diesem Identitätszugriff auf den Azure Kubernetes Service (AKS) Cluster.

In diesem Artikel erfahren Sie:

  • Überprüfen Sie die Hostanforderungen, und stellen Sie dann den Linux-Host und dessen Azure Identität bereit oder wählen Sie sie aus.
  • Bereiten Sie den Host vor, prüfen Sie ihn und notieren Sie die im Anbindungsworkflow verwendeten Werte.
  • Weisen Sie den Identitätszugriff im AKS-Clusterbereich zu, und überprüfen Sie diese Identität.

Führen Sie die Verwaltungsbefehle in diesem Artikel in einer linuxkompatiblen Bash-Umgebung aus, die über die erforderlichen Tools und den Netzwerkzugriff verfügt. Dieser Artikel bezeichnet diese Umgebung als Ihre Bash-Umgebung. Der separate Rechner, der dem Cluster beitritt, ist der Flex-Node-Host; führen Sie dort nur dann Befehle aus, wenn Sie in einem Schritt ausdrücklich dazu angewiesen werden.

Bevor Sie anfangen

  • Konfigurieren Sie das Netzwerk, und erstellen Sie einen Flex-Knotenpool in AKS.
  • Überprüfen Sie Identitäts- und Zugriffskonzepte für Flexknoten , und wählen Sie eine Identitätsoption aus.
  • Verwenden Sie ein Azure Konto, das die Hostressource überprüfen und eine Rollenzuweisung im AKS-Clusterbereich erstellen kann. Role Based Access Control Administrator und User Access Administrator sind Beispiele für Rollen, die die Aufgabe erstellen können.
  • Installieren Sie Azure CLI und einen OpenSSH-Client in Ihrer Bash-Umgebung.
  • Bereiten Sie ein SSH-Schlüsselpaar vor, das vom Host akzeptiert wird.

Bereitstellungsumgebung laden

Starten Sie eine neue Bash-Sitzung, identifizieren Sie die Umgebungsdatei aus dem Planungsartikel, und laden Sie sie. Ersetzen Sie <deployment-name> durch Ihre Bereitstellungsbezeichnung.

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

Die Umgebungsdatei stellt die gemeinsamen Bereitstellungswerte bereit, die in diesem Artikel verwendet werden, einschließlich WORK_DIR, also des Verzeichnisses in Ihrer Bash-Umgebung, in dem dieser Artikel heruntergeladene und generierte Dateien speichert. WORK_DIR ist standardmäßig ~/.local/share/aksflexnode/<deployment-name>. Der Artikel leitet alle anderen Variablen ab, die er benötigt. Wenn Sie die Umgebungsdatei noch nicht erstellt haben, führen Sie zuerst Ihre Flex-Knoten-Bereitstellung planen aus.

Wenn die Datei nicht gefunden wird oder nicht geladen werden kann, halten Sie an und kehren Sie zum Planungsartikel zurück, bevor Sie fortfahren.

Legen Sie das aktive Abonnement fest, und bestätigen Sie den ausgewählten Cluster:

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

Fahren Sie fort, wenn die Ressourcen-ID übereinstimmt AKS_RESOURCE_ID und der Bereitstellungsstatus lautet Succeeded.

1. Überprüfen der Hostanforderungen

Verwenden Sie einen dedizierten Host, der die folgenden Anforderungen erfüllt:

  • Ein AMD64- oder ARM64-Host mit Ubuntu 24.04 LTS, Azure Linux 3.x oder Red Hat Enterprise Linux (RHEL) 9 oder 10.
  • Ein eindeutiger Hostname, der ein gültiger DNS-Unterdomänenname ist. Der Agent konvertiert ihn in Kleinbuchstaben, wenn er den Knoten registriert.
  • Mindestens vier vCPUs und mindestens 8 GiB kostenlos unter /var/lib.
  • Ein SSH-Konto mit Root- oder kennwortlosem Zugriff sudo auf den Host.
  • Netzwerkzugriff auf den AKS-API-Server, Azure Resource Manager, Microsoft Entra ID, das ausgewählte Flex Node-Release und Artefaktmirror sowie die erforderlichen Containerregistries.
  • Vorhandene Layer 3-Konnektivität zwischen dem Flexknotenhostnetzwerk und dem AKS-verwalteten Knotennetzwerk. Der Host- und der AKS-Cluster müssen sich nicht in derselben Azure Region befinden.

Ihre Bash-Umgebung muss auch in der Lage sein, über SSH eine Verbindung mit dem Flex-Knotenhost herzustellen. Eine öffentliche IP-Adresse ist nicht erforderlich, wenn Sie über einen anderen genehmigten Verwaltungspfad verfügen.

2. Host und Identität bereitstellen oder auswählen

Füllen Sie nur den Abschnitt für die in den Identitäts- und Zugriffskonzepten für Flexknoten ausgewählte Identitätsoption aus. Konfigurieren Sie nicht mehr als einen dauerhaften Azure Identitätsmodus für denselben Host.

Tip

Verbinden eines Computers außerhalb Azure? Verwenden Sie eine Azure Arc verwaltete Identität, wenn der Computer bereits arcfähig ist, oder verwenden Sie einen Dienstprinzipal. Verwenden Sie Azure verwaltete VM-Identität nur, wenn der Flexknotenhost eine Azure VM ist.

Legen Sie die SSH-Schlüsselpfade fest, die von jeder Identitätsoption verwendet werden:

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

Jede Identitätsoption richtet auch zwei Hostadressen ein. FLEX_HOST_SSH_TARGET ist die Adresse, die von Ihrer Bash-Umgebung verwendet wird. FLEX_HOST_PRIVATE_IP ist die Hostadresse, die über das AKS-verwaltete Knotennetzwerk erreichbar ist. Vergewissern Sie sich bei Ihrem Netzwerkadministrator, dass FLEX_HOST_PRIVATE_IP zu FLEX_HOST_SUBNET_CIDR gehört und die Adresse ist, die vom von AKS verwalteten Knotennetzwerk aus erreichbar ist. Verwenden Sie keine separate öffentliche oder ausschließlich für die Verwaltung genutzte Adresse als Adresse des Flex-Knotens.

Verwenden einer Azure Arc verwalteten Identität

Verwenden Sie diese Option für einen Host, der bereits mit Azure Arc verbunden ist. Befolgen Sie bei Bedarf die Anweisungen unter Hybride Computer mit Azure Arc-fähigen Servern verbinden.

Legen Sie die Arc-Ressourcenwerte und die Hostadressen fest:

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

Abrufen der Ressourcen-ID, des Verbindungsstatus und der Prinzipalobjekt-ID:

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

Fahren Sie fort, wenn StatusConnected ist und PrincipalId gefüllt ist.

Überprüfen Sie den Agent des verbundenen Computers und den Metadatendienst für hybride Instanzen auf dem Host:

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

Vergewissern Sie sich, dass azcmagent show dieselbe Abonnement-ID, dieselbe Ressourcengruppe und denselben Computernamen wie ARC_RESOURCE_ID, ARC_RESOURCE_GROUP und ARC_MACHINE_NAME meldet. Vergewissern Sie sich auch, dass himdsd aktiv ist. Wenn die Ressource nicht übereinstimmt, halten Sie an und korrigieren Sie die Arc-Ressourcenwerte, bevor Sie den Zugriff gewähren.

Notieren Sie die Werte für Arc und Identität:

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

Verwenden eines Dienstprinzipals

Verwenden Sie diese Option für einen anderen unterstützten virtuellen Computer oder Bare-Metal-Host. Bevorzugen Sie zertifikatbasierte Anmeldeinformationen gegenüber einem langlebigen geheimen Clientschlüssel. Die folgenden Schritte erstellen eine dedizierte Anwendung und einen Serviceprinzipal mit einem selbstsignierten Zertifikat zu Evaluierungszwecken. Sie erstellen keinen geheimen Clientschlüssel oder weisen eine Azure Rolle zu. Sie gewähren in Schritt 4 Zugriff auf den Ziel-AKS-Cluster.

Bevor Sie fortfahren:

  • Installieren Sie OpenSSL in Ihrer Bash-Umgebung, und verwenden Sie eine aktuelle Azure CLI, die az login --certificate unterstützt.
  • Melden Sie sich mit einem Konto an, das im Microsoft Entra-Mandanten, der dem Zielabonnement zugeordnet ist, Anwendungen registrieren und Dienstprinzipale erstellen kann. Azure Abonnementbesitz allein gewährt diese Verzeichnisberechtigungen nicht. Wenn Ihr Mandant die Anwendungsregistrierung einschränkt, bitten Sie Ihren Mandantenadministrator um Hilfe. Siehe Erstellen eines Azure Dienstprinzipals mit dem Azure CLI.
  • Vergewissern Sie sich, dass Ihre Organisation selbstsignierte Zertifikate für die Auswertung zulässt. Verwenden Sie für eine vorhandene genehmigte Identität deren Mandanten-ID, die Client-ID der Anwendung, die Objekt-ID des Dienstprinzipals und die geschützte PEM-Datei, und springen Sie zu Notieren der Werte für Dienstprinzipal und Host.

Speichern Sie die Anmeldedaten, den privaten Schlüssel oder den Pfad zu den Anmeldedaten nicht in der gemeinsamen Umgebungsdatei. Drucken Sie die PEM-Datei nicht, oder fügen Sie sie in die Quellcodeverwaltung ein. Die PEM-Datei enthält einen unverschlüsselten privaten Schlüssel, damit sich der Agent ohne interaktive Kennwortaufforderung authentifizieren kann. Schützen Sie sie mit Dateiberechtigungen und genehmigten Hostzugriffssteuerelementen.

Erstellen eines zertifikatbasierten Dienstprinzipals

Führen Sie diese Befehle in Ihrer Bash-Umgebung aus, während Sie mit Ihrem Operatorkonto angemeldet sind.

  1. Bestätigen Sie das Abonnement, den Mandanten und das angemeldete Konto.

    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

    Fahren Sie nur fort, wenn das Abonnement und der Mandant den beabsichtigten Zielen entsprechen.

  2. Wählen Sie einen eindeutigen Anwendungsanzeigenamen aus, und erstellen Sie ein geschütztes Anmeldeinformationsverzeichnis.

    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. Erstellen Sie ein 30-Tage-Zertifikat und eine kombinierte PEM-Datei, die das Zertifikat und den privaten Schlüssel enthält.

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

    Beenden, wenn die Zertifikaterstellung fehlschlägt. Stellen Sie sicher, dass die PEM-Berechtigungen 600 sind. Die Gültigkeit von 30 Tagen ist für die Auswertung vorgesehen, nicht für eine Rotationsrichtlinie. Ersetzen Sie die Anmeldeinformationen gemäß Ihrem genehmigten Verfahren, bevor sie ablaufen, wenn der Host verbunden bleibt.

  4. Erstellen Sie die Anwendung und den Dienstprinzipal, indem Sie nur das öffentliche Zertifikat hochladen.

    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

    Fahren Sie nur fort, wenn der Befehl erfolgreich ist und eine Anwendungsclient-ID zurückgibt. Der Befehl kann angeben, dass er das Enddatum der Anmeldeinformationen an das Ablaufdatum des Zertifikats angepasst hat. Fügen Sie nicht hinzu --role oder --scopes; die spätere Rollenzuweisung ist auf den AKS-Cluster beschränkt. Führen Sie den Erstellungsvorgang für eine bestehende Anwendung nicht erneut aus, um ihre Anmeldeinformationen zu rotieren.

  5. Rufen Sie die Dienstprinzipalobjekt-ID ab, und überprüfen Sie die registrierten Anmeldeinformationen.

    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

    Vergewissern Sie sich, dass die Objekt-ID des Dienstprinzipals angegeben ist, beide Client-IDs mit SP_CLIENT_ID übereinstimmen, PasswordCredentials gleich 0 ist und genau ein Zertifikat mit dem erwarteten Ablauf registriert ist. Wenn die Verzeichnisreplikation die Suche verzögert, warten Sie kurz, und wiederholen Sie den Nachschlagevorgang, anstatt eine andere Anwendung zu erstellen.

Führen Sie für einen reinen Anmeldeinformationstest nur die Zertifikatauthentifizierungsprüfung in Dienstprinzipal überprüfen aus. Sie müssen keine Azure Rolle zuweisen oder einen Host für diese Überprüfung vorbereiten. Wenn der Test abgeschlossen ist, löschen Sie die dedizierte Testanwendung und lokale Anmeldeinformationen.

Notieren Sie die Werte für den Dienstprinzipal und den Host.

Legen Sie die Hostadressen fest. Wenn Sie eine vorhandene Identität ausgewählt haben, legen Sie zuerst SP_TENANT_ID, SP_CLIENT_ID und SP_OBJECT_ID auf ihre Bezeichner fest.

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 ist die Objekt-ID der Enterprise-Anwendung, auch als Dienstprinzipalobjekt-ID bezeichnet. Es handelt sich nicht um die Objekt-ID der App-Registrierung. Vergewissern Sie sich, dass SP_CLIENT_ID, SP_OBJECT_IDund das Zertifikat zum gleichen Dienstprinzipal gehören.

Bootstrap ordnet SP_TENANT_ID und azure.servicePrincipal.tenantId in der generierten Agentenkonfiguration SP_CLIENT_ID und azure.servicePrincipal.clientId zu. SP_OBJECT_IDwird für die Azure Rollenzuweisung verwendet, nicht als Client-ID des Agents. Informationen zum Feld certificate-file, zur vollständigen bereinigten Konfigurationsstruktur und zu sicheren Überprüfungsbefehlen finden Sie unter Die gerenderte Dienstprinzipalkonfiguration prüfen.

Bewahren Sie die geschützte PEM-Datei für die Identitätsüberprüfung und den Host-Bootstrap auf. Machen Sie sie vor dem Anhängen auf dem Host über Ihren genehmigten Prozess zur Verwaltung von Anmeldeinformationen verfügbar. Dokumentieren Sie den Speicherort über Ihren genehmigten Prozess zur Verwaltung von Anmeldeinformationen, nicht in der gemeinsam genutzten Umgebungsdatei. Fahren Sie mit Host vorbereiten und überprüfen fort, und weisen Sie dann die AKS-Rolle zu.

Verwenden Sie eine verwaltete Identität für einen Azure-virtuellen Computer

Verwenden Sie diese Option für einen Azure virtuellen Computer. Erstellen Sie einen virtuellen Computer mithilfe der folgenden Schnellstartanleitung: Erstellen Sie einen virtuellen Linux-Computer mit dem Azure CLI, oder wählen Sie eine vorhandene VM aus. Platzieren Sie den virtuellen Computer in dem für diese Bereitstellung geplanten Flex-Knotenhostnetzwerk. Sie benötigen keine öffentliche IP-Adresse, wenn Ihre Bash-Umgebung über einen anderen genehmigten SSH-Pfad verfügt.

Legen Sie die VM-Werte fest:

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

Rufen Sie die VM-Ressourcen-ID und die Hostadressen ab. Das SSH-Ziel verwendet die öffentliche IP-Adresse, wenn der virtuelle Computer über eine verfügt, und die private Adresse andernfalls:

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

Bestätigen Sie die für den virtuellen Computer zurückgegebene private Adresse:

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

Fahren Sie nur fort, wenn FLEX_HOST_PRIVATE_IP eine einzelne private IP-Adresse enthält, die zu FLEX_HOST_SUBNET_CIDR gehört und vom AKS-verwalteten Knotennetzwerk aus erreichbar ist. Wenn Azure mehrere Adressen zurückgibt, legen Sie diese auf die geplante Flexknotenadresse festFLEX_HOST_PRIVATE_IP, bevor Sie fortfahren.

Wenn die VM keine öffentliche IP-Adresse hat oder Ihre Bash-Umgebung den Host über einen anderen genehmigten Verwaltungspfad erreicht, legen Sie FLEX_HOST_SSH_TARGET diese auf die Adresse oder den Hostnamen fest, die Ihre Bash-Umgebung erreichen kann.

Führen Sie eine der folgenden Optionen für verwaltete Identitäten aus.

Vom System zugewiesene verwaltete Identität

Aktivieren Sie die vom System zugewiesene verwaltete Identität:

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

Rufen Sie seine primäre Objekt-ID ab:

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

Vom Benutzer zugewiesene verwaltete Identität

Erstellen oder wählen Sie eine Identität, indem Sie der Anleitung unter Verwalten benutzerseitig zugewiesene verwalteter Identitäten mit der Azure CLI folgen.

Legen Sie die Identitätswerte fest:

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

Abrufen der Identitäts-IDs:

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

Weisen Sie der VM die Identität zu:

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

Stellen Sie sicher, dass der virtuelle Computer die ausgewählte Identität auflistet:

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

Fahren Sie fort, wenn die Ausgabe USER_ASSIGNED_IDENTITY_RESOURCE_ID enthält.

Aufzeichnen der VM-Identität

Aufzeichnen der VM- und Identitätswerte:

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. Bereiten Sie den Host vor und prüfen Sie ihn.

Stellen Sie eine Verbindung mit dem Host her:

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

Überprüfen Sie auf dem Host das Betriebssystem, die Architektur, den Hostnamen, die CPU und den verfügbaren Speicher:

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

Vergleichen Sie die Ergebnisse mit den Hostanforderungen in Schritt 1. Beheben Sie alle Unterschiede, bevor Sie fortfahren.

Das Bootstrap-Skript erfordert curl, jqund tar auf dem Host und stoppt, wenn eine dieser Skripts fehlt. Der Flex-Node-Agent installiert die verbleibenden Laufzeitpakete während des Bootstrap-Vorgangs.

Installieren Sie eine der drei Elemente, die Ihr Image noch nicht enthält:

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

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

Beenden Sie die Hostsitzung:

exit

Lesen Sie den tatsächlichen Linux-Hostnamen aus Ihrer Bash-Umgebung:

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

Fahren Sie fort, wenn der Befehl den erwarteten Hostnamen zurückgibt.

Rufen Sie den FQDN des AKS-API-Servers ab, und überprüfen Sie die Namensauflösung und HTTPS-Konnektivität vom Host aus:

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

Wenn die Namensauflösung oder die TCP-Verbindung fehlschlägt, korrigieren Sie DNS-, Routing- oder Netzwerksteuerelemente, bevor Sie fortfahren. Ein öffentlicher AKS-Cluster verwendet seinen öffentlichen API-FQDN. Für einen privaten AKS-Cluster muss Ihre Bash-Umgebung und Ihr Flexknotenhostnetzwerk den FQDN der privaten API auflösen und weiterleiten.

Notieren Sie die Hostwerte. Die gemeinsame Umgebungsdatei speichert Pfade und nicht geheime Kennungen, nicht jedoch Schlüssel oder Anmeldedaten.

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. Weisen Sie die AKS-Rolle zu

Der Workflow der aktuellen Vorschauversion verwendet die Azure Kubernetes Service-Rolle „Mitwirkender“ im exakten AKS-Clusterbereich. Alle drei Identitätsoptionen verwenden eine Dienstprinzipalobjekt-ID für Azure rollenbasierte Zugriffssteuerung. Verwenden Sie eine dedizierte Hostidentität, und entfernen Sie diese Zuweisung, wenn Sie den Host entfernen, wie unter "Verwalten und Entfernen von Flexknoten" in AKS beschrieben.

Die ausgewählte Prinzipalobjekt-ID anzeigen:

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

Fahren Sie nur fort, wenn ein Wert eingegeben wurde und dieser zur ausgewählten VM-Identität, zum Arc-Computer oder zum Dienstprinzipal gehört.

Überprüfen Sie, ob die Zuordnung bereits vorhanden ist:

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

Wenn der Befehl keine Zeile zurückgibt, erstellen Sie die Aufgabe:

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

Führen Sie den Listenbefehl erneut aus. Fahren Sie fort, wenn die Prinzipal-ID und der Bereich mit der ausgewählten Identität und der AKS_RESOURCE_ID übereinstimmen. Die Weitergabe der Rollenzuweisung kann mehrere Minuten dauern.

5. Überprüfen der ausgewählten Identität

Bevor Sie den Host bootstrapieren, vergewissern Sie sich, dass die ausgewählte Identität authentifiziert und den genauen Ziel-AKS-Cluster lesen kann. Füllen Sie nur den Abschnitt für Ihre Identitätsoption aus.

Überprüfen einer Azure Arc verwalteten Identität

Übergeben Sie in Ihrer Bash-Umgebung die nicht geheime AKS-Ressourcen-ID an den für Azure Arc aktivierten Server:

[[ "${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"

Fordern Sie auf dem Azure Arc-fähigen Server ein Azure Resource Manager-Token vom Hybridinstanzmetadatendienst (HIMDS) an, und verwenden Sie es zum Lesen der AKS-Ressource. Zum Lesen des Challenge-Tokens ist root oder die Mitgliedschaft in der Gruppe himds erforderlich:

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

Erwartete Ausgabe: AKS_ARM_HTTP=200. Führen Sie den Befehl ausexit, um die Azure Arc-aktivierte Serversitzung zu verlassen.

Überprüfen eines Dienstprinzipals

Verwenden Sie in Ihrer Bash-Umgebung die kombinierte PEM-Datei aus den Vorbereitungsschritten des Dienstprinzipals. Wenn Sie eine neue Sitzung gestartet oder eine vorhandene Identität ausgewählt haben, legen Sie den geschützten Pfad erneut fest:

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

Beenden Sie, wenn die Datei nicht vorhanden ist oder leer ist. Fügen Sie diesen Pfad nicht zur gemeinsamen Umgebungsdatei hinzu.

Überprüfen Sie zuerst die Zertifikatauthentifizierung mit einem isolierten Azure CLI Profil. Die Subshell entfernt ihren temporären Token-Cache auch dann, wenn ein Befehl fehlschlägt, und ändert nichts an Ihrer normalen Azure-CLI-Anmeldung.

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

Vergewissern Sie sich, dass Mandant mit SP_TENANT_ID übereinstimmt und dass das Token nicht abgelaufen ist. Dieser Befehl gibt nur den Mandanten und das Ablaufdatum aus, nicht das Zugriffstoken. --allow-no-subscriptionsermöglicht Es Ihnen, die Authentifizierung zu testen, bevor Sie Azure Zugriff gewähren. Die erfolgreiche Authentifizierung beweist nicht die Berechtigung zum Lesen oder Registrieren beim AKS-Cluster.

Nachdem die AKS-Rollenzuweisung in Schritt 4 verteilt wurde, überprüfen Sie den Zugriff auf den genauen Zielcluster:

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

Fahren Sie nur fort, wenn die zurückgegebene Ressourcen-ID übereinstimmt AKS_RESOURCE_ID und der Bereitstellungsstatus lautet Succeeded. Wenn die Authentifizierung erfolgreich ist, die Clusteranforderung jedoch verweigert wird, überprüfen Sie die Dienstprinzipalobjekt-ID, den genauen Rollenzuweisungsbereich und die Verteilung, bevor Sie den Vorgang wiederholen. Diese Überprüfung bestätigt, dass der Dienstprinzipal und sein Zertifikat Lesezugriff auf den Zielcluster haben. Der Host verwendet die vorbereiteten Anmeldedaten in Anfügen eines Flexknotens an einen AKS-Cluster.

Überprüfen einer verwalteten Identität einer Azure-VM

Übergeben Sie in Ihrer Bash-Umgebung die nicht geheime AKS-Ressourcen-ID und die Client-ID der Identität an die Azure-VM:

[[ "${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"

Fordern Sie auf dem virtuellen Computer Azure ein Azure Resource Manager-Token aus der ausgewählten verwalteten Identität an, und verwenden Sie es, um die AKS-Ressource zu lesen:

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

Erwartete Ausgabe: AKS_ARM_HTTP=200. Bei einer benutzerzugewiesenen Identität verwendet die Anfrage denselben HOST_IDENTITY_CLIENT_ID, den der Anlagenworkflow an --msi-client-id übergibt. Führen Sie exit aus, um die Azure VM-Sitzung zu verlassen.

Der Anbindungsworkflow führt die abschließende End-to-End-Überprüfung durch, wenn der Host die ausgewählte Identität verwendet, um seine Azure Machine-Ressource zu registrieren.

Nächster Schritt

Als Nächstes hängen Sie den vorbereiteten Host als Flexknoten an und überprüfen ihn.

  • Zuletzt aktualisiert um