針對已啟用 Azure Arc 的 Kubernetes 叢集延伸模組問題進行疑難排解
本文說明 Azure 或 Open Service Mesh (OSM) 中 GitOps (Flux v2) 等叢集擴充功能相關問題的疑難解答秘訣。
如需針對已啟用 Azure Arc 的 Kubernetes 問題進行疑難解答的協助,請參閱 針對已啟用 Azure Arc 的 Kubernetes 問題進行疑難解答。
GitOps (Flux v2)
注意
您可以在已啟用 Azure Arc 的 Kubernetes 叢集或 Azure Kubernetes Service (AKS) 叢集中使用 Flux v2 擴充功能。 這些疑難解答秘訣通常適用於所有叢集類型。
如需使用資源時 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 不支援幹執行」錯誤?。
安裝 microsoft.flux 擴充功能時發生錯誤
此 microsoft.flux
延伸模組會在已啟用 Azure Arc 的 Kubernetes 叢集或 Azure Kubernetes Service (AKS) 叢集中安裝 Flux 控制器和 Azure GitOps 代理程式。 如果擴充功能尚未安裝在叢集中,而且您 為叢集建立 GitOps 組態資源 ,則會自動安裝擴充功能。
如果您在安裝期間發生錯誤,或擴充功能顯示 Failed
狀態,請確定叢集沒有任何原則限制建立 flux-system
命名空間或該命名空間中的任何資源。
針對 AKS 叢集,請確定 Microsoft.ContainerService/AKS-ExtensionManager
已在 Azure 訂用帳戶中啟用功能旗標:
az feature register --namespace Microsoft.ContainerService --name AKS-ExtensionManager
接下來,執行下列命令來判斷是否有其他問題。 針對已啟用 Azure Arc 的叢集,或將 AKS 叢集的叢集類型參數 (-t
) connectedClusters
設定為 managedClusters
。 如果您在建立 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 擴充功能,則 Pod 中可能會發生 extension-agent
錯誤。 輸出看起來類似下列範例:
{"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 實例元數據服務取得其令牌,但 Pod 身分識別會攔截令牌要求。 若要修正此問題, 請升級至最新版本 的 microsoft.flux
擴充功能。
安裝 microsoft.flux 擴充功能的記憶體和 CPU 資源需求
當您安裝 microsoft.flux
擴充功能時,安裝在 Kubernetes 叢集中的控制器必須有足夠的 CPU 和記憶體資源,才能在 Kubernetes 叢集節點上正確排程。 請確定您的叢集符合最小記憶體和 CPU 資源需求。
下表列出此案例的潛在CPU和記憶體資源需求下限和上限:
容器名稱 | 最小 CPU | 最小記憶體 | 最大 CPU | 記憶體上限 |
---|---|---|---|---|
fluxconfig-agent |
5 公尺 | 30 Mi | 50 m | 150 Mi |
fluxconfig-controller |
5 公尺 | 30 Mi | 100 m | 150 Mi |
fluent-bit |
5 公尺 | 30 Mi | 20 m | 150 Mi |
helm-controller |
100 m | 64 Mi | 1,000 米 | 1 Gi |
source-controller |
50 m | 64 Mi | 1,000 米 | 1 Gi |
kustomize-controller |
100 m | 64 Mi | 1,000 米 | 1 Gi |
notification-controller |
100 m | 64 Mi | 1,000 米 | 1 Gi |
image-automation-controller |
100 m | 64 Mi | 1,000 米 | 1 Gi |
image-reflector-controller |
100 m | 64 Mi | 1,000 米 | 1 Gi |
如果您啟用限制 Kubernetes 叢集上容器資源的自定義或內建 Azure 原則 Gatekeeper 原則,請確定原則上的資源限制大於上表所示的限制,或flux-system
命名空間是原則指派中參數的excludedNamespaces
一部分。 此案例中原則的範例為 Kubernetes cluster containers CPU and memory resource limits should not exceed the specified limits
。
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 flux create <parameters> --debug
Azure 監視器容器深入解析
本節提供針對已啟用 Azure Arc 的 Kubernetes 叢集之 Azure 監視器中容器深入解析問題進行疑難解答的協助。
啟用標準魅力 Kubernetes 叢集的特殊許可權模式
Azure 監視器容器深入解析需要其 Kubernetes DaemonSet 以特殊許可權模式執行。 若要成功設定 Canonical Charmed Kubernetes 叢集以進行監視,請執行下列命令:
juju config kubernetes-worker allow-privileged=true
無法在 Oracle Linux 9.x 上安裝 AMA Pod
如果您嘗試在 Oracle Linux 上安裝 Azure 監視器代理程式 (AMA)(Red Hat Enterprise Linux (RHEL)) 9.x Kubernetes 叢集,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 發行版本中自動載入。
若要修正此問題,您必須在叢集中的每個節點上明確載入 iptables_nat
模組。 modprobe
使用 指令 sudo modprobe 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
即使某個控制器在某個時間點的狀態為 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
注意
的實際值 CLUSTER-IP
會與這個範例不同。 和 PORT(S)
的值應該符合此範例中顯示的值NAME
。
檢查 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:驗證和變動
執行下列命令來檢查驗證 Webhook:
kubectl get ValidatingWebhookConfiguration --selector app=osm-controller
如果驗證 Webhook 狀況良好,則會出現類似下列範例的輸出:
NAME WEBHOOKS AGE
osm-validator-mesh-osm 1 81m
執行下列命令來檢查變動 Webhook:
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
}
使用下列命令,檢查變動 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 或低於 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
資源值:
機碼 | 類型 | 預設值 | 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 |
字串 | "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 |
字串 | "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 |
字串 | "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 Sidecar。 現有的 Pod 必須使用 命令重新啟動 kubectl rollout restart deployment
。
驗證 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,請使用下列命令來在叢集上安裝。 視需要取代這些命令中的版本(例如,而不是 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 檔。
升級 Enovy
在附加元件監視的命名空間中建立新的 Pod 時,OSM 會在該 Pod 中插入 Envoy Proxy Sidecar 。 如果需要更新 Envoy 版本,請遵循 OSM 檔中的升級指南中的步驟。
相關內容
- 深入了解叢集延伸模組。
- 檢視一般已啟用 Arc 的 Kubernetes 叢集的疑難排解秘訣。