疑難排解支援 Azure Arc 之 Kubernetes 叢集擴充功能問題

本文針對 Azure 或 Open Service Mesh (OSM) 中 GitOps (Flux v2) 等叢集擴充功能的常見問題，提供疑難排解建議。

如需一般性的支援 Azure Arc 之 Kubernetes 疑難排解協助，請參閱疑難排解支援 Azure Arc 之 Kubernetes 問題。

GitOps （Flux v2）

如要在使用 fluxConfigurations 資源時進行疑難排解，請使用 Azure CLI 並加上 --debug 參數執行下列指令。

az provider show -n Microsoft.KubernetesConfiguration --debug
az k8s-configuration flux create <parameters> --debug

Helm chart 組態設定錯誤

您可能會看到顯示為「Unable to render the Helm chart with the provided config settings and config protected settings : Recommendation Please check if the values provided to the config settings and the config protected settings are valid for this extension type : InnerError [template: azure-k8s-flux/templates/source-controller.yaml:100:24: executing "azure-k8s-flux/templates/source-controller.yaml" at <index (lookup "v1" "ConfigMap" "kube-system" "extension-manager-config").data "AZURE_TENANT_ID">: error calling index: index of untyped nil]」的錯誤訊息。

若要解決此問題：

• 如果您執行 microsoft.flux 1.15.1 版或更早版本，請升級至 1.15.2 版或更新版本。
• 如果您在美國中西部、法國中部、英國南部或西歐區域中執行 microsoft.flux 1.16.2 版，請升級至 1.16.3 版或更新版本。

Webhook 模擬執行錯誤

Flux 可能會失敗並顯示類似 dry-run failed, error: admission webhook "<webhook>" does not support dry run 的錯誤 要解決此問題，請前往 ValidatingWebhookConfiguration 或 MutatingWebhookConfiguration。 在組態中，將 sideEffects 的值設為 None 或 NoneOnDryRun。

如需更多資訊，請參閱如何解決「webhook 不支援試執行」錯誤？。

安裝 microsoft.flux 擴充功能錯誤

此 microsoft.flux 延伸模組會在已啟用 Azure Arc 的 Kubernetes 叢集或 AKS 叢集中安裝 Flux 控制器和 Azure GitOps 代理程式。 如果該擴充功能尚未安裝在叢集中，且您建立 GitOps 組態資源供叢集使用，則會自動安裝該擴充功能。

如果在安裝過程中發生錯誤或擴充功能顯示 Failed 狀態，請確保叢集中沒有任何限制建立 flux-system 命名空間或該命名空間中任何資源的原則。

對於 AKS 叢集，請確保在 Azure 訂閱中已啟用 Microsoft.ContainerService/AKS-ExtensionManager 功能旗標：

az feature register --namespace Microsoft.ContainerService --name AKS-ExtensionManager

接下來，執行下列命令以確認是否存在其他問題 將叢集類型參數 (-t) 設定為 connectedClusters 以支援 Azure Arc 的叢集，或設定為 managedClusters 以支援 AKS 叢集。 如果在建立 GitOps 組態時自動安裝了該擴充功能，則 microsoft.flux 擴充功能的名稱為 flux。

az k8s-extension show -g <RESOURCE_GROUP> -c <CLUSTER_NAME> -n flux -t <connectedClusters or managedClusters>

輸出結果可協助您識別問題以及如何解決 可能的修復措施包括

• 透過執行 az k8s-extension delete --force -g <RESOURCE_GROUP> -c <CLUSTER_NAME> -n flux -t <managedClusters OR connectedClusters> 強制刪除擴充功能。
• 透過執行 helm uninstall flux -n flux-system 解除安裝 Helm 發行項目。
• 透過執行 kubectl delete namespaces flux-system 從叢集中刪除 flux-system 命名空間。

然後，您可以建立新的 Flux 組態，自動安裝 microsoft.flux 擴充功能，或手動安裝 Flux 擴充功能。

在擁有 Microsoft Entra Pod 受控識別的叢集中安裝 microsoft.flux 擴充功能錯誤

如果您嘗試在擁有 Microsoft Entra Pod 受控識別的叢集中安裝 Flux 擴充功能，可能會在 extension-agent Pod 中發生錯誤 輸出結果類似以下範例

{"Message":"2021/12/02 10:24:56 Error: in getting auth header : error {adal: Refresh request failed. Status Code = '404'. Response body: no azure identity found for request clientID <REDACTED>\n}","LogType":"ConfigAgentTrace","LogLevel":"Information","Environment":"prod","Role":"ClusterConfigAgent","Location":"westeurope","ArmId":"/subscriptions/<REDACTED>/resourceGroups/<REDACTED>/providers/Microsoft.Kubernetes/managedclusters/<REDACTED>","CorrelationId":"","AgentName":"FluxConfigAgent","AgentVersion":"0.4.2","AgentTimestamp":"2021/12/02 10:24:56"}

擴充功能狀態顯示為 Failed：

"{\"status\":\"Failed\",\"error\":{\"code\":\"ResourceOperationFailure\",\"message\":\"The resource operation completed with terminal provisioning state 'Failed'.\",\"details\":[{\"code\":\"ExtensionCreationFailed\",\"message\":\" error: Unable to get the status from the local CRD with the error : {Error : Retry for given duration didn't get any results with err {status not populated}}\"}]}}",

此時，extension-agent Pod 嘗試從叢集上的 Azure Instance Metadata Service 取得其詞元，但詞元請求被 Pod 身分識別攔截。 要解決此問題，請升級至最新版本的 microsoft.flux 擴充功能

安裝 microsoft.flux 擴充功能的記憶體與 CPU 資源需求

在 Kubernetes 叢集中安裝 microsoft.flux 擴充功能時，所安裝的控制器必須具有足夠的 CPU 與記憶體資源，以便能正確排程至 Kubernetes 叢集節點 請確保叢集符合最低記憶體與 CPU 資源需求

下表列出此情境下可能的 CPU 與記憶體資源需求的最小與最大限制

如果您啟用了自訂或內建的 Azure Policy Gatekeeper 原則，限制 Kubernetes 叢集上容器的資源，請確保原則中的資源限制大於前表中顯示的限制，或 flux-system 命名空間已包含在原則指派的 excludedNamespaces 參數中。 在這種情況下，Kubernetes cluster containers CPU and memory resource limits should not exceed the specified limits 原則就是一個例子。

Azure 監視器 Container Insights

本節提供有關支援 Azure Arc 的 Kubernetes 叢集中 Azure 監視器容器深入解析問題的疑難排解協助。

為 Canonical Charmed Kubernetes 叢集啟用特殊權限模式

Azure 監視器 Container Insights 需要其 Kubernetes DaemonSet 在特殊權限模式下執行。 若要成功設定 Canonical Charmed Kubernetes 叢集以進行監控，請執行以下命令：

juju config kubernetes-worker allow-privileged=true

無法在 Oracle Linux 9.x 上安裝 AMA Pod

如果您嘗試在 Oracle Linux (Red Hat Enterprise Linux (RHEL) ) 9.x Kubernetes 叢集上安裝 Azure 監視器 Agent (AMA)，AMA Pod 和 AMA-RS Pod 可能因 Pod 中的 addon-token-adapter 容器而無法正常運作。 當您檢查 ama-logs-rs Pod 的記錄，在 addon-token-adapter container 中，您會看到類似以下範例的輸出：

Command: kubectl -n kube-system logs ama-logs-rs-xxxxxxxxxx-xxxxx -c addon-token-adapter
 
Error displayed: error modifying iptable rules: error adding rules to custom chain: running [/sbin/iptables -t nat -N aad-metadata --wait]: exit status 3: modprobe: can't change directory to '/lib/modules': No such file or directory

iptables v1.8.9 (legacy): can't initialize iptables table `nat': Table does not exist (do you need to insmod?)

Perhaps iptables or your kernel needs to be upgraded.

此錯誤發生的原因是安裝擴充需要 iptable_nat 模組，但 Oracle Linux (RHEL) 9.x 發行版中不會自動載入此模組。

要解決此問題，您必須在叢集中的每個節點上明確載入 iptables_nat 模組。 使用 modprobe 命令 sudo modprobe iptables_nat。 登入每個節點並手動新增 iptable_nat 模組之後，請重試 AMA 安裝。

支援 Azure Arc 之 Open Service Mesh

本節示範您可以使用的命令，以驗證和疑難排解 Open Service Mesh (OSM) 擴充元件在叢集上的部署。

檢查 OSM 控制器部署

kubectl get deployment -n arc-osm-system --selector app=osm-controller

如果 OSM 控制器狀態正常，您會看到類似以下的輸出：

NAME             READY   UP-TO-DATE   AVAILABLE   AGE
osm-controller   1/1     1            1           59m

檢查 OSM 控制器 Pod

kubectl get pods -n arc-osm-system --selector app=osm-controller

如果 OSM 控制器狀態正常，會出現類似以下範例的輸出：

NAME                            READY   STATUS    RESTARTS   AGE
osm-controller-b5bd66db-wglzl   0/1     Evicted   0          61m
osm-controller-b5bd66db-wvl9w   1/1     Running   0          31m

即使某個控制器在某個時間點的狀態為 Evicted，另一個控制器的 READY狀態仍為 1/1 並且 Running，且重新啟動次數為 0。 如果 READY 狀態不是 1/1，服務網格處於損壞狀態。 如果 READY 為 0/1，控制平面容器正在當機。

使用以下命令檢查 控制器記錄：

kubectl logs -n arc-osm-system -l app=osm-controller

如果 READY 狀態在斜線 (/) 後的數字大於 1，表示輔助容器已安裝。 OSM 控制器通常在附加輔助容器時無法正常運作。

檢查 OSM 控制器服務

要檢查 OSM 控制器服務，請執行此命令：

kubectl get service -n arc-osm-system osm-controller

如果 OSM 控制器狀態正常，會出現類似以下範例的輸出：

NAME             TYPE        CLUSTER-IP    EXTERNAL-IP   PORT(S)              AGE
osm-controller   ClusterIP   10.0.31.254   <none>        15128/TCP,9092/TCP   67m

檢查 OSM 控制器端點

kubectl get endpoints -n arc-osm-system osm-controller

如果 OSM 控制器狀態正常，會出現類似以下範例的輸出：

NAME             ENDPOINTS                              AGE
osm-controller   10.240.1.115:9092,10.240.1.115:15128   69m

如果叢集中沒有 ENDPOINTS，且其值為 osm-controller，控制平面處於不健康狀態。 此不健康狀態表示控制器 Pod 當機或從未正確部署。

檢查 OSM 注入器部署

kubectl get deployments -n arc-osm-system osm-injector

如果 OSM 注入器狀態正常，會出現類似以下範例的輸出：

NAME           READY   UP-TO-DATE   AVAILABLE   AGE
osm-injector   1/1     1            1           73m

檢查 OSM 注入器 Pod

kubectl get pod -n arc-osm-system --selector app=osm-injector

如果 OSM 注入器狀態正常，會出現類似以下範例的輸出：

NAME                            READY   STATUS    RESTARTS   AGE
osm-injector-5986c57765-vlsdk   1/1     Running   0          73m

READY 狀態必須為 1/1。 任何其他值表示 OSM 注入器 Pod 不健康。

檢查 OSM 注入器服務

kubectl get service -n arc-osm-system osm-injector

如果 OSM 注入器狀態正常，會出現類似以下範例的輸出：

NAME           TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)    AGE
osm-injector   ClusterIP   10.0.39.54   <none>        9090/TCP   75m

確定針對 osm-injector 服務列出的 IP 位址為 9090。 EXTERNAL-IP 不應有值。

檢查 OSM 注入器端點

kubectl get endpoints -n arc-osm-system osm-injector

如果 OSM 注入器狀態正常，會出現類似以下範例的輸出：

NAME           ENDPOINTS           AGE
osm-injector   10.240.1.172:9090   75m

OSM 運作至少需要一個 osm-injector 端點。 OSM 注入器端點的 IP 地址可能不同，但連接埠值 9090 必須相同。

檢查 Webhook：驗證與變更

使用以下命令檢查 Validating Webhook：

kubectl get ValidatingWebhookConfiguration --selector app=osm-controller

如果 Validating Webhook 狀態正常，會出現類似以下範例的輸出：

NAME                     WEBHOOKS   AGE
osm-validator-mesh-osm   1          81m

使用以下命令檢查 Mutating Webhook：

kubectl get MutatingWebhookConfiguration --selector app=osm-injector

如果 Mutating Webhook 狀態正常，會出現類似以下範例的輸出：

NAME                  WEBHOOKS   AGE
arc-osm-webhook-osm   1          102m

使用此命令檢查 Validating Webhook 的服務與憑證授權 (CA) 套件：

kubectl get ValidatingWebhookConfiguration osm-validator-mesh-osm -o json | jq '.webhooks[0].clientConfig.service'

正確設定的 Validating Webhook 會有類似以下範例的輸出：

{
  "name": "osm-config-validator",
  "namespace": "arc-osm-system",
  "path": "/validate",
  "port": 9093
}

使用以下命令檢查 Mutating Webhook 的服務與 CA 套件：

kubectl get MutatingWebhookConfiguration arc-osm-webhook-osm -o json | jq '.webhooks[0].clientConfig.service'

正確配置的 Mutating Webhook 會有類似以下範例的輸出：

{
  "name": "osm-injector",
  "namespace": "arc-osm-system",
  "path": "/mutate-pod-creation",
  "port": 9090
}

使用以下命令檢查 OSM 控制器是否提供 Validating (或 Mutating) Webhook 的 CA 套件：

kubectl get ValidatingWebhookConfiguration osm-validator-mesh-osm -o json | jq -r '.webhooks[0].clientConfig.caBundle' | wc -c

kubectl get MutatingWebhookConfiguration arc-osm-webhook-osm -o json | jq -r '.webhooks[0].clientConfig.caBundle' | wc -c

範例輸出︰

1845

輸出中的數字表示 CA 套件的位元組數或大小。 如果輸出為空、0 或小於 1,000，表示 CA 套件未正確佈建。 沒有正確的 CA 套件，ValidatingWebhook 會拋出錯誤。

檢查 osm-mesh-config 資源

檢查資源是否存在：

kubectl get meshconfig osm-mesh-config -n arc-osm-system

檢查 OSM meshconfig 設定的值：

kubectl get meshconfig osm-mesh-config -n arc-osm-system -o yaml

尋找類似以下範例的輸出：

apiVersion: config.openservicemesh.io/v1alpha1
kind: MeshConfig
metadata:
  creationTimestamp: "0000-00-00A00:00:00A"
  generation: 1
  name: osm-mesh-config
  namespace: arc-osm-system
  resourceVersion: "2494"
  uid: 6c4d67f3-c241-4aeb-bf4f-b029b08faa31
spec:
  certificate:
    certKeyBitSize: 2048
    serviceCertValidityDuration: 24h
  featureFlags:
    enableAsyncProxyServiceMapping: false
    enableEgressPolicy: true
    enableEnvoyActiveHealthChecks: false
    enableIngressBackendPolicy: true
    enableMulticlusterMode: false
    enableRetryPolicy: false
    enableSnapshotCacheMode: false
    enableWASMStats: true
  observability:
    enableDebugServer: false
    osmLogLevel: info
    tracing:
      enable: false
  sidecar:
    configResyncInterval: 0s
    enablePrivilegedInitContainer: false
    logLevel: error
    resources: {}
  traffic:
    enableEgress: false
    enablePermissiveTrafficPolicyMode: true
    inboundExternalAuthorization:
      enable: false
      failureModeAllow: false
      statPrefix: inboundExtAuthz
      timeout: 1s
    inboundPortExclusionList: []
    outboundIPRangeExclusionList: []
    outboundPortExclusionList: []
kind: List
metadata:
  resourceVersion: ""
  selfLink: ""

下表列出 osm-mesh-config 資源值：

檢查命名空間

您可以使用 osm namespace add 命令將命名空間加入特定服務網格。 當 Kubernetes 命名空間成為網格的一部分時，完成以下步驟以確認符合需求。

查看 bookbuyer 命名空間的註解：

kubectl get namespace bookbuyer -o json | jq '.metadata.annotations'

必須存在以下註解：

{
  "openservicemesh.io/sidecar-injection": "enabled"
}

查看 bookbuyer 命名空間的標籤：

kubectl get namespace bookbuyer -o json | jq '.metadata.labels'

必須存在以下標籤：

{
  "openservicemesh.io/monitored-by": "osm"
}

如果您未使用 osm CLI，可手動將這些註解加入命名空間。 如果命名空間未註解 "openservicemesh.io/sidecar-injection": "enabled"，或未標記 "openservicemesh.io/monitored-by": "osm"，OSM 注入器不會添加 Envoy 輔助容器。

驗證 SMI CRD

對於 OSM 服務網格介面 (SMI)，檢查叢集是否有所需的自訂資源定義 (CRD)：

kubectl get crds

確保 CRD 對應到發行分支中可用的版本。 要確認使用中的 CRD 版本，請參閱 SMI 支援版本並在發行版本功能表中選擇您的版本。

使用以下命令取得已安裝 CRD 的版本：

for x in $(kubectl get crds --no-headers | awk '{print $1}' | grep 'smi-spec.io'); do
    kubectl get crd $x -o json | jq -r '(.metadata.name, "----" , .spec.versions[].name, "\n")'
done

如果缺少 CRD，使用以下命令在叢集上安裝。 根據需要替換命令中的版本 (例如，您可能使用 release-v1.1 取代 v1.1.0)。

kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm/release-v1.0/cmd/osm-bootstrap/crds/smi_http_route_group.yaml

kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm/release-v1.0/cmd/osm-bootstrap/crds/smi_tcp_route.yaml

kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm/release-v1.0/cmd/osm-bootstrap/crds/smi_traffic_access.yaml

kubectl apply -f https://raw.githubusercontent.com/openservicemesh/osm/release-v1.0/cmd/osm-bootstrap/crds/smi_traffic_split.yaml

要查看 CRD 版本在不同發行之間的變化，請參閱 OSM 發行說明。

疑難排解憑證管理

有關 OSM 如何向在應用程式 Pod 上運行的 Envoy Proxy 簽發與管理憑證，請參閱 OSM 文件。

升級 Envoy

當新 Pod 在受附加元件監控的命名空間中建立時，OSM 會在該 Pod 中注入 Envoy Proxy 輔助容器。 如果需要更新 Envoy 版本，請依照 OSM 文件中的升級指南步驟操作。

Azure Kubernetes 機群管理員

視您的環境和設定而定，將已啟用 Arc 的 Kubernetes 叢集連線到 Azure Kubernetes Fleet Manager 中樞時，可能會套用某些限制。 請參閱 Azure Kubernetes Fleet Manager 對啟用 Arc 的 Kubernetes 叢集成員的重要考量 ，以獲得完整的需求與考量清單。

相關內容

• 進一步了解叢集擴充功能。
• 查看支援 Arc 之 Kubernetes 叢集的一般疑難排解技巧。