排除 Azure Kubernetes Service (AKS) 的代理命令列介面問題（預覽版）

Docker 相關問題

錯誤：Docker 守護程序未執行

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

1. 如果您收到錯誤訊息顯示 Docker 後台程序未執行，請依照您的作業系統的適當步驟來確保 Docker 服務已啟動：

   • macOS / Windows：

     • 從你的應用程式啟動 Docker Desktop。
     • 等 Docker 開始。

   • Linux:

     • 請使用以下指令啟動 Docker 服務：

       sudo systemctl start docker
       sudo systemctl enable docker  # Enable Docker to start on boot
       

2. 請使用以下指令驗證 Docker 是否執行：

   docker info
   

錯誤：Docker 權限被拒絕

Got permission denied while trying to connect to the Docker daemon socket

要解決 Docker 權限問題，請確保你的使用者擁有訪問 Docker 守護程序所需的權限，並按照你的作業系統提供的步驟進行操作：

• macOS / Windows：

  • 重新啟動 Docker Desktop 以確保它擁有必要的權限。

• Linux:

  • 請將使用者加入 docker 群組，允許非 root 使用者使用 docker，使用以下指令：

  sudo usermod -aG docker $USER
  newgrp docker  # Apply group changes immediately
  

錯誤：Docker 拉取映像失敗

Error response from daemon: pull access denied for aks-agent, repository does not exist or may require 'docker login'

要解決 Docker 拉取映像失敗，請嘗試以下步驟：

• 確保你有網路連線。
• 檢查企業防火牆是否阻擋 Docker 登錄檔存取。
• 再試著用 az aks agent-init初始化代理。

Azure 資格證書問題

錯誤：Azure 認證失敗

要解決 Azure 認證問題，請確保您的 Azure CLI 已正確認證，並透過以下步驟取得所需資源：

1. 請用這個 az account show 指令確認你的 Azure 憑證設定正確。

   az account show
   

2. 如有需要，請再次使用該 az login 指令登入。

   az login
   

服務帳戶與 RBAC 問題

錯誤：找不到服務帳號

Error: service account "aks-mcp" not found in namespace "default"

要解決服務帳號問題，請確保 Kubernetes 服務帳號已正確建立並配置，步驟如下：

1. 請使用以下指令驗證該服務帳號的存在：

   kubectl get serviceaccount aks-mcp --namespace $NAMESPACE
   

2. 如果找不到服務帳戶，請依照為適用於 Azure Kubernetes Service (AKS) 的 Agentic CLI 建立服務帳戶並設定工作負載識別 (預覽版) 中的步驟建立一個。

錯誤：權限遭拒

Error: forbidden: User "system:serviceaccount:<namespace>:aks-mcp" cannot get resource "pods" in API group "" in the namespace "<namespace>"

要解決權限被拒錯誤，請透過以下步驟確保 Kubernetes 服務帳號擁有必要的 RBAC 權限：

1. 請使用以下指令確認 RBAC 權限設定正確：

   kubectl get role aks-mcp-role --namespace $NAMESPACE
   kubectl get rolebinding aks-mcp-rolebinding --namespace $NAMESPACE
   

2. 請使用以下指令檢查 RoleBinding 是否將正確的服務帳號與該角色關聯起來：

   kubectl describe rolebinding aks-mcp-rolebinding --namespace $NAMESPACE
   

工作負載識別問題

錯誤：工作負載識別碼未啟用

Error: workload identity is not enabled on this cluster

如果你收到錯誤提示工作負載身份未啟用，請透過以下步驟確認你的 AKS 叢集是否啟用了工作負載身份：

1. 用指令 az aks show 檢查你的 AKS 叢集是否啟用了工作負載身份。

   az aks show --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --query "securityProfile.workloadIdentity.enabled"
   

2. 如果沒有啟用工作負載身份，請依照 建立服務帳號的步驟，並為 Azure Kubernetes Service 代理 CLI （AKS）（預覽版）設定工作負載身份 ，以啟用叢集上的工作負載身份。

錯誤：缺少註解

Error: service account does not have workload identity annotation

要解決缺少的註解錯誤，請透過以下步驟確認 Kubernetes 服務帳號擁有正確的工作負載身份標註：

1. 請使用以下指令檢查服務帳號是否存在該註解：

   kubectl describe serviceaccount aks-mcp --namespace $NAMESPACE
   

2. 如果缺少註解，請使用以下指令新增。 務必將 $CLIENT_ID 替換為聯邦身份憑證的實際客戶 ID。

   kubectl annotate serviceaccount aks-mcp --namespace $NAMESPACE azure.workload.identity/client-id="$CLIENT_ID" --overwrite
   

錯誤：聯邦憑證傳播延遲

如果你收到與聯邦身份憑證找不到相關的錯誤或認證失敗，可能是因為在 Azure 建立聯邦身份憑證後，傳播延遲所致。 若要解決此問題，請嘗試以下步驟：

1. 等幾分鐘，讓聯邦身份憑證在 Azure 服務間傳播。
2. 請使用指令 az identity federated-credential list 驗證聯邦身份憑證的存在。

az identity federated-credential list --identity-name $IDENTITY_NAME --resource-group $RESOURCE_GROUP