Felsöka Azure Machine Learning-tillägget

2025-04-10

I den här artikeln får du lära dig hur du felsöker vanliga problem som kan uppstå med distribution av Azure Machine Learning-tillägg i din Azure Kubernetes Service (AKS) eller Arc-aktiverade Kubernetes.

Hur installeras Azure Machine Learning-tillägget

Azure Machine Learning-tillägget släpps som ett helm-diagram och installeras av Helm V3. Alla komponenter i Azure Machine Learning-tillägget installeras i azureml namnområdet. Du kan använda följande kommandon för att kontrollera tilläggsstatusen.

# get the extension status
az k8s-extension show --name <extension-name>

# check status of all pods of Azure Machine Learning extension
kubectl get pod -n azureml

# get events of the extension
kubectl get events -n azureml --sort-by='.lastTimestamp'

Felsöka distributionsfel för Azure Machine Learning-tillägg

Fel: Det går inte att återanvända ett namn som fortfarande används

Det här felet innebär att det tilläggsnamn som du har angett redan finns. Om namnet används av Azure Machine Learning-tillägget måste du vänta i ungefär en timme och försöka igen. Om namnet används av andra helm-scheman måste du använda ett annat namn. Kör helm list -Aa för att visa alla helmchart i ditt kluster.

Fel: En tidigare åtgärd för Helm-diagrammet pågår fortfarande

Du måste vänta i ungefär en timme och försöka igen när den okända åtgärden har slutförts.

Fel: Det går inte att skapa nytt innehåll i namnområdet azureml eftersom det avslutas

Det här felet inträffar när en avinstallationsåtgärd inte har slutförts och en annan installationsåtgärd utlöses. Du kan köra az k8s-extension show kommandot för att kontrollera etableringsstatusen för tillägget och kontrollera att tillägget har avinstallerats innan du vidtar andra åtgärder.

Fel: Det gick inte att ladda ned diagrammet eftersom sökvägen inte hittades

Det här felet inträffar när du anger en felaktig tilläggsversion. Du måste kontrollera att den angivna versionen finns. Om du vill använda den senaste versionen behöver du inte ange --version .

Fel: Det går inte att importera till den aktuella versionen: ogiltiga ägarskapsmetadata

Det här felet innebär att det finns en konflikt mellan befintliga klusterresurser och Azure Machine Learning-tillägget. Ett fullständigt felmeddelande kan se ut ungefär så här:

CustomResourceDefinition "jobs.batch.volcano.sh" in namespace "" exists and cannot be imported into the current release: invalid ownership metadata; label validation error: missing key "app.kubernetes.io/managed-by": must be set to "Helm"; annotation validation error: missing key "meta.helm.sh/release-name": must be set to "amlarc-extension"; annotation validation error: missing key "meta.helm.sh/release-namespace": must be set to "azureml"

Åtgärda problemet med hjälp av följande steg.

Kontrollera vem som äger de problematiska resurserna och om resursen kan tas bort eller ändras.
Om resursen endast används av Azure Machine Learning-tillägget och kan tas bort kan du lägga till etiketter manuellt för att åtgärda problemet. Med föregående felmeddelande som exempel kan du köra kommandon på följande sätt,
```
kubectl label crd jobs.batch.volcano.sh "app.kubernetes.io/managed-by=Helm" 
kubectl annotate crd jobs.batch.volcano.sh "meta.helm.sh/release-namespace=azureml" "meta.helm.sh/release-name=<extension-name>"
```
Genom att ange etiketter och anteckningar till resursen innebär det att Helm hanterar resursen som ägs av Azure Machine Learning-tillägget.
När resursen också används av andra komponenter i klustret och inte kan ändras. Se distribuera Azure Machine Learning-tillägget för att se om det finns en konfigurationsinställning för att inaktivera konfliktresursen.

HealthCheck av tillägget

När installationen misslyckades och inte träffade något av de tidigare felmeddelandena kan du använda det inbyggda hälsokontrolljobbet för att göra en omfattande kontroll av tillägget. Azure Machine Learning-tillägget innehåller ett HealthCheck jobb för att kontrollera klusterberedskapen i förväg när du försöker installera, uppdatera eller ta bort tillägget. HealthCheck-jobbet matar ut en rapport som sparas i en konfigurationskarta med namnet arcml-healthcheck i azureml namnområdet. Felkoderna och möjliga lösningar för rapporten visas i Felkod för HealthCheck.

Kör det här kommandot för att hämta HealthCheck-rapporten.

kubectl describe configmap -n azureml arcml-healthcheck

Hälsokontrollen utlöses när du installerar, uppdaterar eller tar bort tillägget. Hälsokontrollrapporten är strukturerad med flera delar pre-install, pre-rollback, pre-upgradeoch pre-delete.

Om installationen av tillägget misslyckades ska du titta på pre-install och pre-delete.
Om tillägget inte har uppdaterats bör du titta på pre-upgrade och pre-rollback.
Om borttagningen av tillägget misslyckades bör du titta på pre-delete.

När du begär support rekommenderar vi att du kör följande kommando och skickar healthcheck.logs filen till oss, eftersom det kan underlätta för oss att bättre hitta problemet.

kubectl logs healthcheck -n azureml

Extensionsoperatörspodden i namnrymden azure-arc/kube-system kraschar på grund av OOMKill.

Det här problemet uppstår när tilläggets Helm-diagramstorlek är stor och det finns flera Helm-versioner i klustret. Om du vill kontrollera Helm-historiken för Azure ML-tillägget använder du följande kommandon:

# Check if there is a release of the Azure ML extension Helm chart installed on the cluster
# Note: The default namespace for the extension is usually 'azureml'. If you specified a different namespace during installation, replace 'azureml' with your namespace.
helm list -n azureml

# Get helm history 
# Note: <release-name> should be the name of your azure ml extension and can be retrieved from the output of the previous command
helm history -n <extension-namespace> azureml

Det finns en Helm-historikgräns på 10 revisioner, men den här gränsen gäller endast för revisioner i ett icke-tillfälligt tillstånd. Om du ser flera revisioner i tillståndet "väntar på återställning" eller "väntar på uppgradering" i Helm-historikutdata, kör skriptet nedan för att städa upp Helm-historiken i klustret:

#!/bin/bash

# Set release name and namespace
RELEASE_NAME=$1 # release-name is the name of the azure ml extension helm release 
NAMESPACE=$2 # namespace is the azure ml extension's namespace. Default value is azureml 

# Validate input
if [[ -z "$RELEASE_NAME" || -z "$NAMESPACE" ]]; then
    echo "Usage: $0 <release-name> <namespace>"
    exit 1
fi

echo "Fetching Helm history for release: $RELEASE_NAME in namespace: $NAMESPACE"

# Get stuck revisions (PENDING_ROLLBACK or PENDING_UPGRADE) using grep + awk for accurate parsing
STUCK_REVISIONS=$(helm history "$RELEASE_NAME" -n "$NAMESPACE" | grep 'pending-' | awk '{print $1}')

if [[ -z "$STUCK_REVISIONS" ]]; then
    echo "No stuck Helm revisions found. Nothing to delete."
    exit 0
fi

echo "Found stuck Helm revisions: $STUCK_REVISIONS"

# Loop through each stuck revision and delete the corresponding secret
for REVISION in $STUCK_REVISIONS; do
    SECRET_NAME="sh.helm.release.v1.${RELEASE_NAME}.v${REVISION}"
   
    echo "Deleting Helm history secret: $SECRET_NAME"
   
    kubectl delete secret -n "$NAMESPACE" "$SECRET_NAME" --ignore-not-found
done

echo "Cleanup complete. Verify with 'helm history $RELEASE_NAME -n $NAMESPACE'"

exit 0

Så här kör du skriptet:

chmod +x delete_stuck_helm_secrets.sh

./delete_stuck_helm_secrets.sh <release-name> <extension-namespace>

Felkod för HealthCheck

Den här tabellen visar hur du felsöker felkoderna som returneras av HealthCheck-rapporten.

Felkod	Felmeddelande	beskrivning
E40001	LASTBALANSERARE_STÖDS_INTE	Lastbalanserare stöds inte i klustret. Du måste konfigurera lastbalanseraren i klustret eller överväga att ange `inferenceRouterServiceType` till `nodePort` eller `clusterIP`.
E40002	OTILLRÄCKLIG_NOD	Du har aktiverat `inferenceRouterHA` som kräver minst tre noder i klustret. Inaktivera ha om du har färre än tre noder.
E40003	INTERN_LOAD_BALANSERARE_STÖDS_INTE	För närvarande stöder endast AKS den interna lastbalanseraren, och vi stöder `azure` bara typen. Ange `internalLoadBalancerProvider` inte om du inte har något AKS-kluster.
E40007	Ogiltig_SSL-inställning	SSL-nyckeln eller certifikatet är inte giltigt. CNAME ska vara kompatibelt med certifikatet.
E45002	PROMETHEUS_KONFLIKT	Den installerade Prometheus-operatorn är i konflikt med din befintliga Prometheus-operator. Mer information finns i Prometheus-operatorn
E45003	DÅLIG NÄTVERKSANSLUTNING	Du måste uppfylla nätverkskraven.
E45004	AZUREML_FE_ROLLKONFLIKT	Azure Machine Learning-tillägget stöds inte i äldre AKS. Om du vill installera Azure Machine Learning-tillägget måste du ta bort de äldre azureml-fe-komponenterna.
E45005	AZUREML_FE_DEPLOYMENT_CONFLICT	Azure Machine Learning-tillägget stöds inte i äldre AKS. Om du vill installera Azure Machine Learning-tillägget måste du köra kommandot under det här formuläret för att ta bort de äldre azureml-fe-komponenterna. Mer information finns här.

Kommandon för att ta bort äldre azureml-fe-komponenter i AKS-klustret:

kubectl delete sa azureml-fe
kubectl delete clusterrole azureml-fe-role
kubectl delete clusterrolebinding azureml-fe-binding
kubectl delete svc azureml-fe
kubectl delete svc azureml-fe-int-http
kubectl delete deploy azureml-fe
kubectl delete secret azuremlfessl
kubectl delete cm azuremlfeconfig

Integrering av komponenter med öppen källkod

Azure Machine Learning-tillägget använder vissa öppen källkod komponenter, inklusive Prometheus-operatorn, Volcano Scheduler och DCGM-exportören. Om Kubernetes-klustret redan har några av dem installerade kan du läsa följande avsnitt för att integrera dina befintliga komponenter med Azure Machine Learning-tillägget.

Prometheus-operatör

Prometheus-operatorn är ett öppen källkod ramverk som hjälper dig att skapa måttövervakningssystem i kubernetes. Azure Machine Learning-tillägget använder även Prometheus-operatorn för att övervaka resursutnyttjandet av jobb.

Om klustret har Prometheus-operatorn installerad av en annan tjänst kan du ange installPromOp=false att inaktivera Prometheus-operatorn i Azure Machine Learning-tillägget för att undvika en konflikt mellan två Prometheus-operatorer. I det här fallet hanterar den befintliga prometheus-operatorn alla Prometheus-instanser. För att prometheus ska fungera korrekt måste du tänka på följande när du inaktiverar prometheus-operatorn i Azure Machine Learning-tillägget.

Kontrollera om prometheus i azureml-namnområdet hanteras av Prometheus-operatorn. I vissa scenarier är prometheus-operatorn inställd på att endast övervaka vissa specifika namnområden. I så fall kontrollerar du att azureml-namnområdet finns i listan över tillåtna. Mer information finns i kommandoflaggor.
Kontrollera om kubelet-service är aktiverat i prometheus-operatorn. Kubelet-service innehåller alla slutpunkter för kubelet. Mer information finns i kommandoflaggor. Måste också se till att kubelet-service har en etikettk8s-app=kubelet.

Skapa ServiceMonitor för kubelet-service. Kör följande kommando med variabler ersatta:

cat << EOF | kubectl apply -f -
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: prom-kubelet
  namespace: azureml
  labels:
    release: "<extension-name>"     # Please replace to your Azure Machine Learning extension name
spec:
  endpoints:
  - port: https-metrics
    scheme: https
    path: /metrics/cadvisor
    honorLabels: true
    tlsConfig:
      caFile: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
      insecureSkipVerify: true
    bearerTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token
    relabelings:
    - sourceLabels:
      - __metrics_path__
      targetLabel: metrics_path
  jobLabel: k8s-app
  namespaceSelector:
    matchNames:
    - "<namespace-of-your-kubelet-service>"  # Please change this to the same namespace of your kubelet-service
  selector:
    matchLabels:
      k8s-app: kubelet    # Please make sure your kubelet-service has a label named k8s-app and it's value is kubelet

EOF

DCGM-exportör

Dcgm-exporter är det officiella verktyget som rekommenderas av NVIDIA för insamling av GPU-mått. Det är integrerat i Azure Machine Learning-tillägget. Men som standard är dcgm-exporter inte aktiverat och inga GPU-mått samlas in. Du kan ange flaggan på installDcgmExporter för att aktivera den vid true. Eftersom det är NVIDIA:s officiella verktyg kanske du redan har installerat det i ditt GPU-kluster. I så fall kan du ange installDcgmExporter till false, och följa stegen för att integrera din dcgm-exporter i Azure Machine Learning-tillägget. En annan sak att notera är att dcgm-exporter tillåter användaren att konfigurera vilka mått som ska exponeras. För Azure Machine Learning-tillägget kontrollerar du att DCGM_FI_DEV_GPU_UTILmåtten DCGM_FI_DEV_FB_FREE och DCGM_FI_DEV_FB_USED är exponerade.

Se till att du har Aureml-tillägget och dcgm-exporter installerade framgångsrikt. Dcgm-exporter kan installeras med dcgm-exporter helm diagram eller Gpu-operator helm diagram

Kontrollera om det finns en tjänst för dcgm-exporter. Om det inte finns eller om du inte vet hur du kontrollerar det kör du följande kommando för att skapa ett.

cat << EOF | kubectl apply -f -
apiVersion: v1
kind: Service
metadata:
  name: dcgm-exporter-service
  namespace: "<namespace-of-your-dcgm-exporter>" # Please change this to the same namespace of your dcgm-exporter
  labels:
    app.kubernetes.io/name: dcgm-exporter
    app.kubernetes.io/instance: "<extension-name>" # Please replace to your Azure Machine Learning extension name
    app.kubernetes.io/component: "dcgm-exporter"
  annotations:
    prometheus.io/scrape: 'true'
spec:
  type: "ClusterIP"
  ports:
  - name: "metrics"
    port: 9400  # Please replace to the correct port of your dcgm-exporter. It's 9400 by default
    targetPort: 9400  # Please replace to the correct port of your dcgm-exporter. It's 9400 by default
    protocol: TCP
  selector:
    app.kubernetes.io/name: dcgm-exporter  # Those two labels are used to select dcgm-exporter pods. You can change them according to the actual label on the service
    app.kubernetes.io/instance: "<dcgm-exporter-helm-chart-name>" # Please replace to the helm chart name of dcgm-exporter
EOF

Kontrollera om tjänsten i föregående steg har angetts korrekt

kubectl -n <namespace-of-your-dcgm-exporter> port-forward service/dcgm-exporter-service 9400:9400
# run this command in a separate terminal. You will get a lot of dcgm metrics with this command.
curl http://127.0.0.1:9400/metrics

Konfigurera ServiceMonitor för att exponera dcgm-exporter-tjänsten för Azure Machine Learning-tillägget. Kör följande kommando så börjar det gälla om några minuter.

cat << EOF | kubectl apply -f -
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: dcgm-exporter-monitor
  namespace: azureml
  labels:
    app.kubernetes.io/name: dcgm-exporter
    release: "<extension-name>"   # Please replace to your Azure Machine Learning extension name
    app.kubernetes.io/component: "dcgm-exporter"
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: dcgm-exporter
      app.kubernetes.io/instance: "<extension-name>"   # Please replace to your Azure Machine Learning extension name
      app.kubernetes.io/component: "dcgm-exporter"
  namespaceSelector:
    matchNames:
    - "<namespace-of-your-dcgm-exporter>"  # Please change this to the same namespace of your dcgm-exporter
  endpoints:
  - port: "metrics"
    path: "/metrics"
EOF

Vulkanplanerare

Om ditt kluster redan har vulkansviten installerad kan du ange installVolcano=false, så tillägget installerar inte vulkanschemaläggaren. Vulkanschemaläggare och vulkankontrollant krävs för att skicka in och schemalägga träningsjobb.

Konfigurationen för vulkanschemaläggaren som används av Azure Machine Learning-tillägget är:

volcano-scheduler.conf: |
    actions: "enqueue, allocate, backfill"
    tiers:
    - plugins:
        - name: task-topology
        - name: priority
        - name: gang
        - name: conformance
    - plugins:
        - name: overcommit
        - name: drf
        - name: predicates
        - name: proportion
        - name: nodeorder
        - name: binpack

Du måste använda samma konfigurationsinställning och du måste inaktivera job/validate webhook i vulkanantagningen om vulkanversionen är lägre än 1,6, så att Azure Machine Learning-träningsarbetsbelastningar kan utföras korrekt.

Volcano Scheduler-integrering med stöd för autoskalning av kluster

Som diskuterats i den här tråden fungerar inte gang-plugin-programmet bra med klustrets autoskalning (CA) och autoskalningen av noder i AKS.

Om du använder funktionen "Volcano" som medföljer Azure Machine Learning-tillägget via inställningen installVolcano=true, har tillägget en schemaläggarkonfiguration som standard, som konfigurerar pluginsystemet gang för att förhindra att jobb låser sig. Därför stöds inte klustrets autoskalning (CA) i AKS-klustret med vulkanen installerad i tillägg.

Om du i det här fallet föredrar att autoskalning av AKS-kluster fungerar normalt kan du konfigurera den här volcanoScheduler.schedulerConfigMap parametern genom att uppdatera tillägget och ange en anpassad konfiguration av no gang volcano-scheduler till den, till exempel:

volcano-scheduler.conf: |
    actions: "enqueue, allocate, backfill"
    tiers:
    - plugins:
      - name: sla 
        arguments:
          sla-waiting-time: 1m
    - plugins:
      - name: conformance
    - plugins:
        - name: drf
        - name: predicates
        - name: proportion
        - name: nodeorder
        - name: binpack

Om du vill använda den här konfigurationen i ditt AKS-kluster måste du följa följande steg:

Skapa en konfigurationsmappsfil med den tidigare konfigurationen azureml i namnområdet. Det här namnområdet skapas vanligtvis när du installerar Azure Machine Learning-tillägget.
Ange volcanoScheduler.schedulerConfigMap=<configmap name> i tilläggskonfigurationen för att tillämpa detta configmap. Och du måste hoppa över resursverifieringen när du installerar tillägget genom att konfigurera amloperator.skipResourceValidation=true. Till exempel:
```
az k8s-extension update --name <extension-name> --config volcanoScheduler.schedulerConfigMap=<configmap name> amloperator.skipResourceValidation=true --cluster-type managedClusters --cluster-name <your-AKS-cluster-name> --resource-group <your-RG-name>
```

Anteckning

Eftersom grupperingspluggen har tagits bort finns det en möjlighet att ett dödläge kan inträffa när Volcano schemalägger uppgiften.

För att undvika den här situationen kan du använda samma instanstyp i jobben.

Om du använder en annan schemaläggarkonfiguration än standardinställningen som tillhandahålls av Azure Machine Learning-tillägget kanske inte är fullt ut stödd. Var försiktig.

Du måste inaktivera job/validate webhook i Volcano-åtkomsten om din Volcano-version är lägre än 1.6.

Ingress Nginx-kontrollant

Installationen av Azure Machine Learning-tillägget levereras med en ingress nginx-kontrollantklass som k8s.io/ingress-nginx standard. Om du redan har en ingress nginx-styrenhet i klustret måste du använda en annan kontrollantklass för att undvika installationsfel.

Du har två alternativ:

Ändra din befintliga kontrollantklass till något annat än k8s.io/ingress-nginx.
Skapa eller uppdatera vårt Azure Machine Learning-tillägg med en anpassad kontrollantklass som skiljer sig från din genom att följa följande exempel.

Om du till exempel vill skapa tillägget med en anpassad kontrollantklass:

az ml extension create --config nginxIngress.controller="k8s.io/amlarc-ingress-nginx"

Så här uppdaterar du tillägget med en anpassad kontrollantklass:

az ml extension update --config nginxIngress.controller="k8s.io/amlarc-ingress-nginx"

Nginx-ingresskontroller installerad med Azure Machine Learning-tillägget kraschar på grund av minnesbristfel.

Symptom

Nginx-ingresskontrollanten som installerats med Azure Machine Learning-tillägget kraschar på grund av OOM-fel (out-of-memory) även när det inte finns någon arbetsbelastning. Kontrollantloggarna visar ingen användbar information för att diagnostisera problemet.

Möjlig orsak

Det här problemet kan inträffa om nginx-ingresskontrollanten körs på en nod med många processorer. Som standard skapar nginx-ingresskontrollanten arbetsprocesser enligt antalet processorer, vilket kan förbruka fler resurser och orsaka OOM-fel på noder med fler processorer. Det här är ett känt problem som rapporterats på GitHub

Lösning

Du löser problemet genom att:

Justera antalet arbetsprocesser genom att installera tillägget med parametern nginxIngress.controllerConfig.worker-processes=8.
Öka minnesgränsen med hjälp av parametern nginxIngress.resources.controller.limits.memory=<new limit>.

Se till att justera dessa två parametrar enligt dina specifika nodspecifikationer och arbetsbelastningskrav för att optimera dina arbetsbelastningar effektivt.