準備 Flex 節點主機與身分識別（預覽）

Important

AKS 預覽功能以自助方式提供，並採選擇加入制。預覽版本係依「現狀」及「可用情況」提供，且不適用於服務等級協定與有限保固。客戶支援部門會盡最大努力，部分支援 AKS 預覽。因此，這些功能不適合實際執行用途。如需詳細資訊，請參閱下列支援文章：

在你將 Linux 主機作為彈性節點連接之前，先準備好主機，設定你在規劃時選擇的身份，並授權該身份存取 Azure Kubernetes Service （AKS）叢集。

在本文中，您可以：

檢視主機需求，然後配置或選擇 Linux 主機及其 Azure 身份。
準備並檢查主機，並記錄附件工作流程所使用的數值。
在 AKS 叢集範圍指派身份存取權，並驗證該身份。

請在具備所需工具與網路存取的 Linux 相容 Bash 環境中執行本文中的管理指令。本文稱這個環境為你的 Bash 環境。加入叢集的獨立機器是 彈性節點主機;只有當步驟明確指示你時，才會在那裡執行指令。

開始之前

完成設定網路並在 AKS 中建立一個彈性節點池。
檢視彈性節點的身份與存取概念，並選擇一個身份選項。
使用一個 Azure 帳號，可以檢查主機資源並在 AKS 叢集範圍內建立角色指派。 Role Based 存取控制 Administrator 和 User Access Administrator 是可建立該指派的角色範例。
在你的 Bash 環境中安裝 Azure CLI 和 OpenSSH 用戶端。
準備一組主機接受的 SSH 金鑰對。

載入部署環境

啟動新的 Bash 會議，從規劃文章中辨識環境檔案，並載入它。換 <deployment-name> 成你的部署標籤。

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

環境檔案提供本文會讀取的共用部署值，包括 WORK_DIR，也就是本文在 Bash 環境中用來儲存下載內容和產生檔案的目錄。根據預設，WORK_DIR 是 ~/.local/share/aksflexnode/<deployment-name>。文章會推導出所需的其他變數。如果你還沒建立環境檔案，先完成 Plan 你的 Flex 節點部署。

如果找不到檔案或無法載入，請暫停並回到規劃文章再繼續。

設定有效訂閱並確認所選叢集：

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

當資源 ID 匹配 AKS_RESOURCE_ID 且配置狀態為 Succeeded時繼續。

1. 檢視主機需求

請使用符合以下需求的專用主機：

一台運行 Ubuntu 24.04 LTS、Azure Linux 3.x 或 Red Hat Enterprise Linux （RHEL） 9 或 10 的 AMD 64 或 ARM64 主機。
一個獨特的主機名稱，且是有效的 DNS 子網域名稱。代理在註冊該節點時會將其轉換為小寫。
至少 4 個 vCPU，且在 /var/lib 之下至少有 8 GiB 的可用記憶體。
一個主機上有 root 或無 sudo 密碼存取權限的 SSH 帳號。
對 AKS API 伺服器、Azure Resource Manager、Microsoft Entra ID、所選彈性節點發行與成品鏡像，以及所需容器登錄的網路存取權。
彈性節點主機網路與 AKS 管理節點網路之間的現有第三層連接。主機和 AKS 叢集不一定要在同一 Azure 區域。

你的 Bash 環境也必須能透過 SSH 連接到 flex node 主機。當你有其他核准的管理路徑時，就不需要公共 IP 位址。

2. 配置或選擇主機與身份

僅完成彈性節點的身分識別與存取概念中所選身分識別選項的章節。不要為同一主機設定超過一個持久的 Azure 身份模式。

Tip

在 Azure 之外連接機器？ 如果機器已經啟用 Arc，請使用 Azure Arc 管理身份，或使用服務主體。只有當 flex node 主機是 Azure 虛擬機時，才使用 Azure VM 管理身份。

設定每個身份選項所使用的 SSH 金鑰路徑：

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

每個身份選項也會建立兩個主機位址。 FLEX_HOST_SSH_TARGET 是你 Bash 環境使用的位址。 FLEX_HOST_PRIVATE_IP 是 AKS 管理的節點網路可達的主機位址。請向您的網路管理員確認，FLEX_HOST_PRIVATE_IP 屬於 FLEX_HOST_SUBNET_CIDR，且是可從 AKS 管理的節點網路存取的位址。不要用獨立的公共或僅管理的位址作為彈性節點位址。

使用 Azure Arc 受控識別

如果主機已連線至 Azure Arc，請使用此選項。如有需要，請參閱使用已啟用 Azure Arc 的伺服器來連線混合式機器。

設定 Arc 資源值及主機位址：

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

取得資源 ID、連線狀態及主物件 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

當狀態為 Connected 且 PrincipalId 已填入時繼續。

驗證主機上的連接機器代理與混合實例元資料服務：

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

確認 azcmagent show 回報的訂用帳戶 ID、資源群組和機器名稱與 ARC_RESOURCE_ID、ARC_RESOURCE_GROUP 和 ARC_MACHINE_NAME 相同。也要確認 himdsd 已啟用。如果資源不匹配，請在分配存取權前先停止並修正 Arc 資源的數值。

記錄弧線與身份值：

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

使用服務主體

請針對其他支援的虛擬機器或裸機主機使用此選項。優先使用憑證認證，而非長期有效的用戶端密碼。以下步驟建立專用應用程式與服務主體，並附有自簽憑證供評估。他們不會建立客戶端秘密，也不會指派 Azure 角色。你在第 4 步授權目標 AKS 叢集的存取權限。

在你繼續之前：

在您的 Bash 環境中安裝 OpenSSL，並使用支援 az login --certificate 的最新版 Azure CLI。
請使用一個帳號登入，該帳號能註冊應用程式並在與目標訂閱綁定的 Microsoft Entra 租戶中建立服務主體。僅靠 Azure 訂閱擁有權並不會授予這些目錄權限。如果你的房客限制申請註冊，請向你的房客管理員求助。請參閱使用 Azure CLI 建立 Azure 服務主體。
確認您的組織允許自行簽署的證書進行審核。對於已核准的身份，請使用其租戶 ID、應用程式用戶端 ID、服務主體物件 ID 及受保護的 PEM 檔案，並跳過至 「記錄服務主體」與「主機值」。

不要把憑證、私鑰或憑證路徑存進共享環境檔案。不要列印 PEM 檔案，也不要把它納入原始碼控制。 PEM 檔案包含未加密的私鑰，讓代理人能在無需互動式密碼提示的情況下進行驗證。用檔案權限和經核准的主機存取控制來保護它。

建立基於憑證的服務主體

在你的 Bash 環境中，使用你的營運者帳號登入時執行這些指令。

確認訂閱、租戶和登入帳號。

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

只有當訂閱者和租戶是目標時才繼續。

選擇一個唯一的應用程式顯示名稱，並建立受保護的憑證目錄。

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"

建立一份 30 天的憑證，以及包含憑證與私鑰的合併 PEM 檔案。

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

如果憑證建立失敗，就停止。確認 PEM 權限為 600。 30天有效期是用來評估，不是輪調政策。如果主機仍然連線，請在憑證過期前透過核准流程替換。

建立應用程式與服務主體時，僅上傳公開憑證。
```
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
```
只有當指令成功並回傳應用程式客戶端 ID 時，才繼續。指令可以回報已調整憑證結束日期以符合證書的到期日。不要加上 --role 或 --scopes;後面的角色分配僅限於AKS群組。不要針對現有應用程式重新執行建立作業來輪替其認證資料。

取得服務主體物件 ID 並檢查已註冊的憑證。

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

確認服務主體物件 ID 已填入，兩個用戶端 ID 是否相符 SP_CLIENT_ID，密碼 憑證（PasswordCredentials ）是 0，且正確註冊了一張預期到期的憑證。如果目錄複製延遲查詢，請稍作等待並重新嘗試查詢，而非建立其他應用程式。

僅用憑證測試時，只需在 Verify a service principal 中執行憑證驗證檢查。你不需要指派 Azure 角色或準備主機來檢查。測試完成後，刪除專用的測試應用程式和本地憑證。

記錄服務主體與主機值

設定主機位址。如果你選擇了現有的身份，首先設定 SP_TENANT_ID、 SP_CLIENT_ID，並 SP_OBJECT_ID 設定為其識別碼。

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 是 企業應用程式的物件 ID，也稱為服務主體物件 ID。它不是應用程式註冊的物件 ID。確認 SP_CLIENT_ID、 SP_OBJECT_ID，且憑證屬於同一服務主體。

Bootstrap 會在產生的代理程式設定中，將 SP_TENANT_ID 和 SP_CLIENT_ID 對應到 azure.servicePrincipal.clientId 和 azure.servicePrincipal.tenantId。 SP_OBJECT_ID用於 Azure 角色指派，而非代理的客戶端 ID。關於憑證檔案欄位、完整塗黑配置形狀及安全驗證指令，請參見「檢查已交付的服務主體設定」。

保留受保護的 PEM 檔案作為身份驗證和主機啟動工具。在附加之前，請先透過經核准的憑證管理流程，使其可在主機上使用。請透過你核准的憑證管理流程記錄其位置，而非共用環境檔案。繼續執行 準備並檢查主機，然後指派 AKS 角色。

使用 Azure 虛擬機器受控識別

用這個選項來管理 Azure 虛擬機。請依照快速啟動方式建立虛擬機：使用Azure CLI建立Linux虛擬機，或選擇現有虛擬機。將虛擬機置入本次部署計畫中的彈性節點主機網路。當你的 Bash 環境有另一條核准的 SSH 路徑時，你就不需要公共 IP 位址。

設定虛擬機數值：

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

取得虛擬機資源 ID 和主機位址。當虛擬機有公網 IP 時，SSH 目標會使用公網 IP，否則則使用私人位址：

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

確認虛擬機回傳的私有位址：

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

只有當 FLEX_HOST_PRIVATE_IP 包含 FLEX_HOST_SUBNET_CIDR 屬於且可從 AKS 管理的節點網路存取的單一私有位址時，才繼續。如果 Azure 回傳多個位址，請先設定FLEX_HOST_PRIVATE_IP為計畫中的彈性節點位址再繼續。

如果虛擬機沒有公共 IP 位址，或你的 Bash 環境透過其他核准的管理路徑連接到主機，請設定 FLEX_HOST_SSH_TARGET 為 Bash 環境能到達的位址或主機名稱。

請完成以下其中一個管理身份選項。

系統指派的管理身份識別

啟用系統指派的管理身份：

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

取得其主要物件 ID：

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

使用者指派的受控識別

請依照以下方式建立或選擇身份，使用 Azure CLI 管理使用者指派的受管理身份。

設定身份值：

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

取得身份識別碼：

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

將身份指派給虛擬機：

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

確認虛擬機是否列出所選的身份：

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

當輸出包含 USER_ASSIGNED_IDENTITY_RESOURCE_ID時繼續。

記錄虛擬機身份

記錄虛擬機與身份值：

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. 準備並檢查主機

連線到主機：

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

在主機上檢查作業系統、架構、主機名稱、CPU 及可用儲存空間：

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

將結果與第一步的主機需求做比較。在繼續之前，先解決任何分歧。

bootstrap 指令碼需要主機上有 curl、jq 和 tar，如果缺少其中任何一項就會停止。 flex node agent 會在開機期間安裝剩餘的執行時套件。

安裝你映像檔中還沒包含的三個模組中的任一個：

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

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

退出主機工作階段：

exit

從你的 Bash 環境讀取實際的 Linux 主機名稱：

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

當指令回傳預期的主機名稱時繼續。

取得 AKS API 伺服器 FQDN，並從主機確認名稱解析與 HTTPS 連線性：

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

如果名稱解析或 TCP 連線失敗，請在繼續前修正 DNS、路由或網路控制。公共 AKS 叢集使用其公開 API FQDN。對於私有 AKS 叢集，你的 Bash 環境和 flex node 主機網路必須解析並路由到私有 API FQDN。

記錄主機的數值。共享環境檔案儲存的是路徑與非秘密識別碼，而非金鑰或憑證內容。

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. 指派AKS角色

目前的預覽工作流程會在 AKS 叢集的確切範圍內使用 Azure Kubernetes Service Contributor Role。這三種身份選項都使用服務主體物件 ID 來執行 Azure 角色基礎存取控制。使用專用主機身份，並在移除主機時移除此指派，如 AKS 中的「管理與移除彈性節點」中所述。

顯示所選的主要物件 ID：

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

只有當該值已填入且屬於所選虛擬機身份、Arc 機器或服務主體時，才繼續執行。

檢查該指派是否已經存在：

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

如果該命令未傳回任何資料列，則建立指派：

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

再執行一次 list 指令。當主體 ID 和範圍與所選身分識別及 AKS_RESOURCE_ID 相符時，請繼續。角色指派的傳播可能需要幾分鐘的時間。

5. 驗證所選身份

在啟動主機前，先確認所選身份能驗證並讀取精確的目標 AKS 叢集。請僅填寫與您的身份選項對應的部分。

驗證 Azure Arc 受控識別

在你的 Bash 環境中，將非秘密的 AKS 資源 ID 傳給支援 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"

在啟用 Azure Arc 的伺服器上，向混合實例元資料服務（HIMDS）請求 Azure Resource Manager 令牌，並用它讀取 AKS 資源。讀取挑戰權杖需要 root 權限，或屬於 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}"

預期輸出： AKS_ARM_HTTP=200。若要離開已啟用 Azure Arc 的伺服器工作階段，請執行 exit。

驗證服務主體

在你的 Bash 環境中，使用服務主體準備步驟中的合併 PEM 檔案。如果你開始新工作階段或選擇了現有的身份，請重新設定它的受保護路徑：

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

如果檔案不存在或是空的，就停止。不要把這條路徑加到共用環境檔案裡。

首先，請用隔離的 Azure CLI 設定檔驗證憑證認證。子殼層即使在指令失敗時，也會移除其暫時的權杖快取，且不會變更您一般的 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
)

確認租戶是否符合 SP_TENANT_ID ，且令牌沒有過期。此指令僅顯示租用戶和到期時間，不會顯示存取權杖。 --allow-no-subscriptions讓你在授權 Azure 存取前先測試認證。成功的認證並不代表你有權限讀取或註冊到 AKS 叢集。

在步驟 4 的 AKS 角色指派已生效後，請驗證是否可存取確切的目標叢集：

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

只有當回傳的資源 ID 相符 AKS_RESOURCE_ID 且配置狀態為 Succeeded時，才繼續。若認證成功但叢集請求被拒絕，請在重試前確認服務主體物件 ID、精確的角色指派範圍及傳播情況。此檢查證明服務主體及其憑證能讀取目標叢集。主機會在將彈性節點附加到 AKS 叢集中使用預先準備好的認證資訊。

驗證 Azure VM 受控識別

在你的 Bash 環境中，將非秘密的 AKS 資源 ID 和身份用戶端 ID 傳給 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"

在 Azure 虛擬機上，從所選的管理身份請求 Azure Resource Manager 令牌，並用它讀取 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}"

預期輸出： AKS_ARM_HTTP=200。對於使用者指派的身份，請求使用與附件工作流程傳遞的--msi-client-id相同的HOST_IDENTITY_CLIENT_ID資料。執行 exit 以離開 Azure VM 工作階段。

當主機使用所選身份註冊其 Azure Machine 資源時，附件工作流程會執行最終的端對端檢查。

後續步驟

接著，將已準備好的主機連接並驗證為彈性節點。

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-09-22