針對已啟用 Azure Arc 的 Kubernetes 叢集擴充功能問題進行疑難排解

  • 發行項

本檔提供叢集擴充 功能相關問題 的疑難排解秘訣，例如 GitOps （Flux v2） 和 Open Service Mesh。

如需針對已啟用 Azure Arc 的 Kubernetes 一般問題進行疑難排解的說明，請參閱 針對已啟用 Azure Arc 的 Kubernetes 問題 進行疑難排解。

GitOps （Flux v2）

注意

Flux v2 擴充功能可用於已啟用 Azure Arc 的 Kubernetes 叢集或 Azure Kubernetes Service （AKS） 叢集中。 無論叢集類型為何，這些疑難排解秘訣通常會套用。

如需對資源問題進行疑難排解的 fluxConfigurations 一般協助，請使用指定的 參數執行下列 Azure CLI 命令 --debug ：

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

Webhook/幹執行錯誤

如果您看到 Flux 無法與之類的 dry-run failed, error: admission webhook "<webhook>" does not support dry run 錯誤協調，您可以藉由尋找 ValidatingWebhookConfiguration 或 MutatingWebhookConfiguration ，並將 sideEffects 設定為 None 或 NoneOnDryRun 來解決此問題：

如需詳細資訊，請參閱 如何?解決 webhook does not support dry run 錯誤？

安裝 microsoft.flux 擴充功能時發生錯誤

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

如果您在安裝期間遇到錯誤，或擴充功能處於失敗狀態，請確定叢集沒有任何原則可限制在該命名空間中建立 flux-system 命名空間或資源。

針對 AKS 叢集，請確定訂用帳戶已啟用 Microsoft.ContainerService/AKS-ExtensionManager 功能旗標。

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

之後，請執行此命令來判斷是否有其他問題。 將已啟用 Arc 的叢集或 managedClusters AKS 叢集的叢集類型 （ -t ） 參數 connectedClusters 設定為 。 如果擴充功能是在建立 GitOps 組態期間自動安裝擴充功能 microsoft.flux ，則此延伸模組的名稱為「flux」。 如需相關資訊，請查看 statuses 物件。

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 版本 helm uninstall flux -n flux-system
  • 執行 以 flux-system 從叢集刪除命名空間 kubectl delete namespaces flux-system

之後，您可以 重新建立可自動安裝延伸模組的 microsoft.flux 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}}\"}]}}",

在此情況下，擴充代理程式 Pod 會嘗試從叢集上的 IMDS 取得其權杖。 但 Pod 身分識別 會 攔截權杖要求。 若要修正此問題，請 升級至最新版本 的 microsoft.flux 擴充功能。

在 AKS 叢集中安裝 microsoft.flux 擴充功能時，kubelet 身分識別的問題

使用 AKs 叢集時，其中一個驗證選項是 使用使用者指派的受控識別的 kubelet 身分識別。 使用 kubelet 身分識別可降低作業額外負荷，並在連線到 Azure Container Registry 等 Azure 資源時提高安全性。

若要讓 Flux 使用 kubelet 身分識別，請在安裝 Flux 擴充功能時新增 參數 --config useKubeletIdentity=true 。

az k8s-extension create --resource-group <resource-group> --cluster-name <cluster-name> --cluster-type managedClusters --name flux --extension-type microsoft.flux --config useKubeletIdentity=true

確保符合擴充功能 microsoft.flux 安裝的記憶體和 CPU 需求

使用擴充功能安裝在 Kubernetes 叢集中的 microsoft.flux 控制器需要 CPU 和記憶體資源，才能在 Kubernetes 叢集節點上正確排程。 請確定您的叢集能夠符合可能要求的最小記憶體和 CPU 資源。 另請注意，這裡顯示的潛在 CPU 和記憶體資源需求上限。

容器名稱 最小 CPU 最小記憶體 CPU 限定 記憶體上限
fluxconfig-agent 5 米 30 米 50 米 150 米
fluxconfig-controller 5 米 30 米 100 m 150 米
fluent-bit 5 米 30 米 20 m 150 米
helm-controller 100 m 64 米 1000 米 1 Gi
source-controller 50 米 64 米 1000 米 1 Gi
kustomize-controller 100 m 64 米 1000 米 1 Gi
notification-controller 100 m 64 米 1000 米 1 Gi
image-automation-controller 100 m 64 米 1000 米 1 Gi
image-reflector-controller 100 m 64 米 1000 米 1 Gi

如果您啟用自訂或內建的 Azure Gatekeeper 原則來限制 Kubernetes 叢集上容器的資源，例如 Kubernetes cluster containers CPU and memory resource limits should not exceed the specified limits ，請確定原則上的資源限制大於此處所顯示的限制，或 flux-system 命名空間是原則指派中參數的 excludedNamespaces 一部分。

Flux v1

注意

建議您 儘快移轉至 Flux v2 。 支援在 2024 年 1 月 1 日之前建立的 Flux v1 型叢集設定資源，將于 2025 年 5 月 24 日 結束。 從 2024 年 1 月 1 日起，您將無法建立新的 Flux v1 型叢集組態資源。

若要協助針對 Flux v1 中資源的問題 sourceControlConfigurations 進行疑難排解，請使用指定的參數執行下列 Azure CLI 命令 --debug ：

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

Azure 監視器容器深入解析

本節提供針對已啟用 Azure Arc 的 Kubernetes 叢集 之 Azure 監視器 Container Insights 問題進行疑難排解的協助。

啟用標準魅力 Kubernetes 叢集的特殊許可權模式

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

juju config kubernetes-worker allow-privileged=true

無法在 Oracle Linux 9.x 上安裝 Azure 監視器代理程式 （AMA）

嘗試在 Oracle Linux （RHEL） 9.x Kubernetes 叢集上安裝 Azure 監視器代理程式 （AMA）時，AMA Pod 和 AMA-RS Pod 可能無法正常運作，因為 addon-token-adapter Pod 中的容器。 發生此錯誤時，檢查 Pod 的 ama-logs-rs 記錄檔時， 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 發行版本中自動載入。

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

注意

執行此步驟並不會讓 iptables_nat 模組持續運作。

已啟用 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

即使某個控制器在某個時間點被 收回，也有另一個控制器 READY 1/1Running0 是重新開機。 如果資料行 READY 不是 ， 1/1 則服務網狀結構處於中斷狀態。 具有 的資料 0/1 行 READY 表示控制平面容器正在當機。

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

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

資料行 READY 的數位高於 1 之後 / ，表示已安裝側車。 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

注意

CLUSTER-IP會不同。 服務 NAME ，應該 PORT(S) 符合此處顯示的內容。

檢查 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

kubectl get ValidatingWebhookConfiguration --selector app=osm-controller

如果驗證 Webhook 狀況良好，您會看到類似下列的輸出：

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

kubectl get MutatingWebhookConfiguration --selector app=osm-injector

如果變動 Webhook 狀況良好，您會看到類似下列的輸出：

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

使用此命令檢查驗證 Webhook 的服務與 CA 套件組合 ：

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

已正確 設定的 驗證 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 控制器是否已為 CA 套件組合提供 驗證 （或 Mutating ） Webhook：

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 或低於 1000 的數位，則 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 資源值：

機碼 類型 預設值 Kubectl Patch 命令範例
spec.traffic.enableEgress bool false kubectl patch meshconfig osm-mesh-config -n arc-osm-system -p '{"spec":{"traffic":{"enableEgress":false}}}' --type=merge
spec.traffic.enablePermissiveTrafficPolicyMode bool true kubectl patch meshconfig osm-mesh-config -n arc-osm-system -p '{"spec":{"traffic":{"enablePermissiveTrafficPolicyMode":true}}}' --type=merge
spec.traffic.outboundPortExclusionList 陣列 [] kubectl patch meshconfig osm-mesh-config -n arc-osm-system -p '{"spec":{"traffic":{"outboundPortExclusionList":[6379,8080]}}}' --type=merge
spec.traffic.outboundIPRangeExclusionList 陣列 [] kubectl patch meshconfig osm-mesh-config -n arc-osm-system -p '{"spec":{"traffic":{"outboundIPRangeExclusionList":["10.0.0.0/32","1.1.1.1/24"]}}}' --type=merge
spec.traffic.inboundPortExclusionList 陣列 [] kubectl patch meshconfig osm-mesh-config -n arc-osm-system -p '{"spec":{"traffic":{"inboundPortExclusionList":[6379,8080]}}}' --type=merge
spec.certificate.serviceCertValidityDuration string "24h" kubectl patch meshconfig osm-mesh-config -n arc-osm-system -p '{"spec":{"certificate":{"serviceCertValidityDuration":"24h"}}}' --type=merge
spec.observability.enableDebugServer bool false kubectl patch meshconfig osm-mesh-config -n arc-osm-system -p '{"spec":{"observability":{"enableDebugServer":false}}}' --type=merge
spec.observability.osmLogLevel string "info" kubectl patch meshconfig osm-mesh-config -n arc-osm-system -p '{"spec":{"observability":{"tracing":{"osmLogLevel": "info"}}}}' --type=merge
spec.observability.tracing.enable bool false kubectl patch meshconfig osm-mesh-config -n arc-osm-system -p '{"spec":{"observability":{"tracing":{"enable":true}}}}' --type=merge
spec.sidecar.enablePrivilegedInitContainer bool false kubectl patch meshconfig osm-mesh-config -n arc-osm-system -p '{"spec":{"sidecar":{"enablePrivilegedInitContainer":true}}}' --type=merge
spec.sidecar.logLevel string "error" kubectl patch meshconfig osm-mesh-config -n arc-osm-system -p '{"spec":{"sidecar":{"logLevel":"error"}}}' --type=merge
spec.featureFlags.enableWASMStats bool "true" kubectl patch meshconfig osm-mesh-config -n arc-osm-system -p '{"spec":{"featureFlags":{"enableWASMStats":"true"}}}' --type=merge
spec.featureFlags.enableEgressPolicy bool "true" kubectl patch meshconfig osm-mesh-config -n arc-osm-system -p '{"spec":{"featureFlags":{"enableEgressPolicy":"true"}}}' --type=merge
spec.featureFlags.enableMulticlusterMode bool "false" kubectl patch meshconfig osm-mesh-config -n arc-osm-system -p '{"spec":{"featureFlags":{"enableMulticlusterMode":"false"}}}' --type=merge
spec.featureFlags.enableSnapshotCacheMode bool "false" kubectl patch meshconfig osm-mesh-config -n arc-osm-system -p '{"spec":{"featureFlags":{"enableSnapshotCacheMode":"false"}}}' --type=merge
spec.featureFlags.enableAsyncProxyServiceMapping bool "false" kubectl patch meshconfig osm-mesh-config -n arc-osm-system -p '{"spec":{"featureFlags":{"enableAsyncProxyServiceMapping":"false"}}}' --type=merge
spec.featureFlags.enableIngressBackendPolicy bool "true" kubectl patch meshconfig osm-mesh-config -n arc-osm-system -p '{"spec":{"featureFlags":{"enableIngressBackendPolicy":"true"}}}' --type=merge
spec.featureFlags.enableEnvoyActiveHealthChecks bool "false" kubectl patch meshconfig osm-mesh-config -n arc-osm-system -p '{"spec":{"featureFlags":{"enableEnvoyActiveHealthChecks":"false"}}}' --type=merge

檢查命名空間

注意

arc-osm-system 命名空間永遠不會參與服務網格，且永遠不會加上標籤或標注此處所示的索引鍵/值。

我們使用 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 側車。

注意

呼叫 之後 osm namespace add ，只有 新的 Pod 會插入 Envoy 側車。 現有的 Pod 必須使用 命令重新開機 kubectl rollout restart deployment 。

確認 SMI CRD

使用下列命令檢查叢集是否有必要的自訂資源定義 （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，請使用下列命令在叢集上安裝它們。 視需要取代這些命令中的版本（例如，v1.1.0 會是 release-v1.1）。

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 Sidecar 。 如果需要更新 Envoy 版本，請遵循 OSM 檔網站上的升級指南 中的 步驟。

下一步