共用方式為

針對已連線登錄檔延伸模組進行疑難排解

  • 發行項

本文討論您在安裝或更新已啟用 Arc 的 Kubernetes 叢集已連線登錄檔延伸模組時，可能會收到的一些常見錯誤訊息。

如何安裝已連線登錄檔延伸模組

已連線登錄檔延伸模組會以 Helm 圖表的形式發行，並由 Helm V3 安裝。 已連線登錄檔延伸模組的所有元件都會安裝在 connected-registry 命名空間中。 您可以使用下列命令來檢查延伸模組狀態。

# get the extension status 
az k8s-extension show --name <extension-name>  
# check status of all pods of connected registry extension 
kubectl get pod -n connected-registry    
# get events of the extension 
kubectl get events -n connected-registry   --sort-by='.lastTimestamp'

常見錯誤

錯誤：無法重複使用仍在使用中的名稱

此錯誤表示您指定的延伸模組名稱已經存在。 如果名稱已在使用中，則您必須使用另一個名稱。

錯誤：無法在命名空間 connected-registry 中建立新內容，因為正在終止

當解除安裝作業未完成且觸發另一個安裝作業時，就會發生此錯誤。 您可以執行 az k8s-extension show 命令來檢查延伸模組的佈建狀態，並確定已在採取其他動作之前解除安裝延伸模組。

錯誤：下載圖表時發生錯誤，找不到路徑

當您指定錯誤的延伸模組版本時，就會發生此錯誤。 您必須確定指定的版本存在。 如果要使用最新版本，則不需要指定 --version。

常見案例

案例 1：安裝失敗，但未顯示錯誤訊息

如果您在建立或更新延伸模組時產生錯誤訊息，且未顯示錯誤訊息，您可以執行 az k8s-extension list 命令，檢查建立失敗的位置：

az k8s-extension list \ 
--resource-group <my-resource-group-name> \ 
--cluster-name <my-cluster-name> \ 
--cluster-type connectedClusters

解決方案：重新啟動叢集、註冊服務提供者，或刪除並重新安裝已連線登錄檔

若要解決此問題，請嘗試下列方法：

  • 重新啟動 Arc Kubernetes 叢集。

  • 註冊 KubernetesConfiguration 服務提供者。

  • 強制刪除並重新安裝已連線登錄檔延伸模組。

案例 2：目標已連線登錄檔版本不存在

當您嘗試安裝已連線登錄檔延伸模組以特定版本為目標時，會收到錯誤訊息，指出已連線登錄檔版本不存在。

解決方案：針對支援的已連線登錄檔版本再次安裝

請再試一次，以安裝延伸模組。 請確定您使用支援的已連線登錄檔版本。

常見問題

問題：延伸模組建立停滯在執行狀態

可能性 1：永續性磁碟區宣告 (PVC) 的問題

  • 檢查已連線登錄檔 PVC 的狀態
kubectl get pvc -n connected-registry -o yaml connected-registry-pvc

狀態下的階段值應該繫結。 如果其未從擱置變更，請刪除延伸模組。

  • 檢查所需的儲存類別是否位於儲存體類別清單中：
kubectl get storageclass --all-namespaces
  • 如果沒有，請重新建立延伸模組並新增
--config pvc.storageClassName=”standard”`
  • 或者，這可能是一個沒有足夠 PVC 空間的問題。 使用參數重新建立延伸模組
--config pvc.storageRequest=”250Gi”`

可能性 2：連接字串不正確

  • 檢查已連線登錄檔 Pod 的紀錄：
kubectl get pod -n connected-registry
  • 複製已連線登錄檔 Pod (例如：“connected-registry-8d886cf7f-w4prp") 的名稱，並將其貼到下列命令中：
kubectl logs -n connected-registry connected-registry-8d886cf7f-w4prp
  • 如果您看到下列錯誤訊息，表示已連線登錄檔的連接字串不正確：
Response: '{"errors":[{"code":"UNAUTHORIZED","message":"Incorrect Password","detail":"Please visit https://aka.ms/acr#UNAUTHORIZED for more information."}]}'
  • 確定已建立 protected-settings-extension.json 檔案
cat protected-settings-extension.json
  • 若有需要，請重新產生 protected-settings-extension.json
cat << EOF > protected-settings-extension.json  
{ 
"connectionString": "$(az acr connected-registry get-settings \ 
--name myconnectedregistry \ 
--registry myacrregistry \ 
--parent-protocol https \ 
--generate-password 1 \ 
--query ACR_REGISTRY_CONNECTION_STRING --output tsv --yes)" 
} 
EOF
  • 更新延伸模組以包含新的連接字串
az k8s-extension update \ 
--cluster-name <myarck8scluster> \ 
--cluster-type connectedClusters \ 
--name <myconnectedregistry> \ 
-g <myresourcegroup> \ 
--config-protected-file protected-settings-extension.json

問題：已建立延伸模組，但已連線登錄檔並非「上線」狀態

可能性 1：先前的已連線登錄檔尚未停用

此案例通常發生在先前的已連線登錄檔延伸模組已刪除，且已針對相同的已連線登錄檔建立新的延伸項目時。

  • 檢查已連線登錄檔 Pod 的紀錄：
kubectl get pod -n connected-registry
  • 複製已連線登錄檔 Pod (例如：“connected-registry-xxxxxxxxx-xxxxx") 的名稱，並將其貼到下列命令中：
kubectl logs -n connected-registry connected-registry-xxxxxxxxx-xxxxx
  • 如果您看到下列錯誤訊息，則必須停用已連線登錄檔：

Response: '{"errors":[{"code":"ALREADY_ACTIVATED","message":"Failed to activate the connected registry as it is already activated by another instance. Only one instance is supported at any time.","detail":"Please visit https://aka.ms/acr#ALREADY_ACTIVATED for more information."}]}'

  • 執行下列命令以停用：
az acr connected-registry deactivate -n <myconnectedregistry> -r <mycontainerregistry>

幾分鐘後，應該會重新建立已連線登錄檔 Pod，錯誤應該就會消失。

啟用 記錄

  • 執行 [az acr connected-registry update] 命令，以偵錯記錄層級更新已連線登錄檔延伸模組：
az acr connected-registry update --registry mycloudregistry --name myacrregistry --log-level debug

  • 可套用下列記錄層級以協助進行疑難排解：

    • 偵錯提供偵錯用途的詳細資訊。

    • 資訊提供偵錯用途的一般資訊。

    • 警告表示潛在問題尚未成為錯誤，但如果未採取任何動作，則可能會變成一個錯誤。

    • 錯誤會記錄導致作業無法完成的錯誤。

    • 無會關閉記錄，因此不會寫入任何記錄訊息。

  • 視需要調整記錄層級，以針對問題進行疑難排解。

作用選取範圍會提供更多選項，以在偵錯已連線登錄檔的問題時，調整記錄的詳細程度。 下列是可用的選項：

已連線登錄檔記錄層級專屬於已連線登錄檔的作業，且會判斷已連線登錄檔所處理訊息的嚴重性。 此設定可用來管理已連線登錄檔本身的記錄行為。

--log-level 會設定執行個體上的記錄層級。 記錄層級會判斷記錄器所處理訊息的嚴重性。 您可以設定記錄層級，篩選出低於特定嚴重性的訊息。 例如，如果您將記錄層級設定為「警告」，記錄器就會處理警告、錯誤和重大訊息，但會忽略資訊和偵錯訊息。

az cli 記錄層級會控制 Azure CLI 作業期間輸出訊息的詳細程度。 Azure CLI (az) 針對記錄層級提供數個詳細程度選項，可加以調整，以控制其作業期間的輸出資訊量：

--verbose 可增加記錄的詳細程度。 其提供較預設設定更詳細的資訊，這對於識別問題很有用。

--debug 可啟用完整的偵錯記錄。 偵錯記錄會提供最詳細的資訊，包括「詳細資訊」層級所提供的所有資訊，以及用於診斷問題的其他詳細資料。

下一步

快速入門：部署已連線登錄檔 Arc 延伸模組詞彙表