Problembehandlung
In diesem Thema werden häufige Fehlerszenarien bei der Bereitstellung von Codebeamer AI in einer kundenseitig gehosteten Umgebung mit Terraform beschrieben und die richtigen Wiederherstellungsaktionen zu den jeweiligen Fällen erläutert.
Rollback der Terraform-Bereitstellung und Wiederherstellung des Zustands
Wenn Sie Terraform mit einem Remote-Azure Storage-Backend verwenden, können Bereitstellungen aus verschiedenen Gründen fehlschlagen. Es muss festgestellt werden, ob der Terraform-Zustand gültig ist, um den richtigen Wiederherstellungsansatz zu wählen.
In den meisten Fällen ist das Zurücksetzen des Terraform-Codes und erneutes Anwenden der Konfiguration der richtige Ansatz. Die Blob-Versionierung darf nur verwendet werden, wenn die Zustandsdatei selbst beschädigt oder unlesbar wird.
Terraform-Fehlerszenarien und korrekter Wiederherstellungsansatz
Die folgenden Szenarien beschreiben, wie sich Terraform bei Ausfällen verhält und welche Wiederherstellungsmethode korrekt ist.
Szenario
Zustandsstatus
Soll der vorherige Zustand wiederhergestellt werden?
Richtiger Wiederherstellungsansatz
Terraform "apply" schlägt vollständig fehl. Es werden keine Ressourcen erstellt.
Zustand unverändert
Nein
Code zurücksetzen und Terraform "plan" ausführen.
"Apply" ist teilweise erfolgreich, in diesem Fall werden einige Ressourcen erstellt.
Zustand teilweise aktualisiert, aber zutreffend
Nein
Code zurücksetzen und Terraform "apply" erneut ausführen.
"Apply" stürzt während des Zustands-Schreibvorgangs ab.
Zustand beschädigt oder unlesbar
Ja
Vorherige Blob-Version wiederherstellen, und Terraform erneut ausführen.
"Apply" erfolgreich, Bereitstellung muss jedoch rückgängig gemacht werden.
Zustand gültig
Nein
Code zurücksetzen und Terraform "apply" erneut ausführen.
Szenario 1 – Terraform "apply" schlägt vollständig fehl
Terraform versucht, eine Ressource zu erstellen, aber Azure hat die Anforderung abgelehnt, bevor die Ressourcen erstellt wurden.
Häufige Ursachen
Ungültige Konfiguration
Kontingent überschritten
Ungültiger Modellname
Berechtigungsprobleme
Beispielsituation
Komponente
Status
Code
Enthält neue Ressource
Zustand
Unverändert
Azure
Keine Ressource erstellt
Terraform aktualisiert den Zustand nur nach erfolgreichen Operationen, daher bleibt der Zustand unverändert.
Beispiel
Code: gpt-5-nano deployment added
State: V1 (unchanged)
Azure: resource does not exist
Lösung
Machen Sie die Codeänderung rückgängig.
#if using git...
git checkout <earlier_branch/earlier_tag>
terraform plan -var-file=infra.tfvars
Erwartetes Ergebnis: Keine Änderungen
Zustandswiederherstellung erforderlich: Nein
Szenario 2 – Terraform "apply" teilweise erfolgreich
Terraform erstellt erfolgreich einige Ressourcen und schlägt dann fehl. Terraform schreibt den Zustand nach jeder erfolgreichen Operation, sodass der Zustand die bereitgestellten Ressourcen genau widerspiegelt.
Beispielszenario
Komponente
Status
Code
Enthält resource1, resource2, resource3
Zustand
Enthält resource1 und resource2
Azure
resource1 und resource2 sind vorhanden, resource3 wurde nicht erstellt
Zum Beispiel:
Code: resource1, resource2, resource3
State: resource1, resource2
Azure: resource1, resource2
Die Bereitstellung schlug fehl, als Terraform versuchte, resource3 zu erstellen.
Option 1 – Beheben Sie das Problem und führen Sie Terraform erneut aus
Verwenden Sie diese Option, wenn der Fehler durch ein vorübergehendes oder behebbares Problem verursacht wurde, z.B. eine Kontingentgrenze, ein temporärer API-Fehler oder eine fehlerhafte Konfiguration.
terraform apply -var-file=infra.tfvars
Terraform geht dann folgendermaßen vor:
1. Es erkennt, dass resource1 und resource2 bereits im Zustand vorhanden sind.
2. Es überspringt resource1 und resource2.
3. Es versucht, resource3 erneut zu erstellen.
Ergebnis:
Komponente
Status
Zustand
resource1, resource2, resource3
Azure
resource1, resource2, resource3
Dadurch wird die Bereitstellung dort fortgesetzt, wo sie fehlgeschlagen ist.
Option 2 – Code rückgängig machen
Verwenden Sie diese Option, wenn die Bereitstellung selbst fehlerhaft ist. Beispielsweise wurde versehentlich eine Modellbereitstellung hinzugefügt.
#if using git...
git checkout <earlier_branch/earlier_tag>
terraform apply -var-file=infra.tfvars
Daraus ergibt sich der folgende Zustand:
Komponente
Status
Code
resource1 und resource2 entfernt
Zustand
resource1 und resource2 vorhanden
Azure
resource1 und resource2 vorhanden
Terraform erkennt, dass die Ressourcen im Zustand, aber nicht mehr im Code vorhanden sind, und führt daher "destroy" aus.
Terraform "plan" zeigt Folgendes:
- destroy resource1
- destroy resource2
Nach apply lautet das Ergebnis wie folgt:
Komponente
Status
Zustand
bereinigt
Azure
resource1 und resource2 entfernt
Szenario 3 – Wiederherstellung nach beschädigtem Terraform-Zustand mithilfe von Azure Blob-Versionierung
Terraform basiert auf der Zustandsdatei, um Infrastrukturressourcen zuzuordnen. Wenn die Zustandsdatei beschädigt oder unlesbar wird, schlagen Terraform-Befehle wie "plan", "apply" und "destroy" fehl.
Für eine Wiederherstellung aus dieser Situation muss die vorherige Version der Zustandsdatei aus der Azure Blob-Versionierung wiederhergestellt werden. Bei der Blob-Versionierung werden historische Kopien der Zustandsdatei bei jeder Änderung beibehalten, sodass eine sichere Wiederherstellung nach Beschädigung möglich ist.
Mögliche Ursachen
Unterbrechung des Terraform-Prozesses während des Zustands-Schreibvorgangs
Terminalabsturz während terraform apply
Netzwerkunterbrechung während Hochladen des Zustands
Daraus ergibt sich der folgende Zustand:
Komponente
Status
Code
Kann neue Ressourcen enthalten
Zustand
Beschädigt oder unlesbar
Azure
Ressourcen können vorhanden sein oder nicht
Beispiel für Terraform-Fehler
terraform plan -var-file=infra.tfvars

│ Error: Unsupported state file format

│ The version in the state file is string. A positive whole number is required.


│ Error: Unsupported state file format

│ The state file does not have a "version" attribute, which is required to identify the format version.
OR
$ terraform plan -var-file=infra.tfvars
│ Error: Unsupported state file format

│ The state file could not be parsed as JSON: syntax error at
│ byte offset 7805.
Dies gibt an, dass die Zustandsdatei keine gültige JSON-Datei mehr ist.
Wiederherstellungsverfahren
1. Bestätigen Sie die Beschädigung des Zustands.
terraform plan -var-file=infra.tfvars
Erwarteter Fehler:
terraform plan -var-file=infra.tfvars

│ Error: Unsupported state file format

│ The version in the state file is string. A positive whole number is required.


│ Error: Unsupported state file format

│ The state file does not have a "version" attribute, which is required to identify the format version.
OR
$ terraform plan -var-file=infra.tfvars
│ Error: Unsupported state file format

│ The state file could not be parsed as JSON: syntax error at
│ byte offset 7805.
Dies bestätigt, dass die Zustandsdatei beschädigt ist.
2. Listet verfügbare Blob-Versionen auf.
Bei der Blob-Versionierung werden frühere Zustandsdateiversionen automatisch wiederhergestellt.
az storage blob list \
--container-name <container_name>\
--account-name <storage_account_name> \
--include v \
--auth-mode login \
--query "[?name=='terraform.tfstate'].{name:name, Version:versionId, Modified:properties.lastModified}" \
--output table
Beispielausgabe:
Name
Version
Modified
terraform.tfstate
2026-03-13T11:00:00.0000000Z
2026-03-13T11:00:00
terraform.tfstate
2026-03-13T11:05:00.0000000Z
2026-03-13T11:05:00
Identifizieren und kopieren Sie die letzte bekannte fehlerfreie Versions-ID. Die ältere Version ist der gültige Zustand und die neueste Version ist der beschädigte Zustand.
3. Laden Sie die letzte bekannte fehlerfreie Version herunter.
Laden Sie die gültige Zustandsdatei aus der Blob-Versionierung herunter.
az storage blob download \
--container-name <container_name> \
--account-name <storage_account_name> \
--name terraform.tfstate \
--version-id <version_id> \
--file recovered-state.json \
--auth-mode login
4. Stellen Sie die Zustandsdatei wieder her.
Laden Sie die wiederhergestellte Zustandsdatei hoch, um den beschädigten Blob zu ersetzen.
az storage blob upload \
--container-name <container_name> \
--account-name <storage_account_name> \
--name terraform.tfstate \
--file recovered-state.json \
--overwrite \
--auth-mode login
Dadurch wird der funktionierende Terraform-Zustand wiederhergestellt.
5. Verifizieren Sie die Terraform-Operation.
terraform plan -var-file=infra.tfvars
Dies bestätigt, dass die Wiederherstellung des Zustands erfolgreich war.
6. Bestätigen Sie, dass der Versionsverlauf erhalten bleibt.
Listen Sie die Blob-Versionen erneut auf.
az storage blob list \
--container-name <container_name>\
--account-name <storage_account_name> \
--include v \
--auth-mode login \
--query "[?name=='terraform.tfstate'].{name:name, Version:versionId, Modified:properties.lastModified}" \
--output table
Beispiel:
Version
Beschreibung
V1
Ursprünglich gültiger Zustand
V2
Beschädigter Zustand
V3
Gültiger Zustand wiederhergestellt
Bei der Blob-Versionierung wird der gesamte Audit-Trail von Zustandsänderungen beibehalten.
Testvalidierungsergebnisse
Testschritt
Erwartetes Ergebnis
Beschädigte Zustandsdatei
Terraform kann Zustand nicht lesen
Blob-Versionen prüfen
Vorherige Zustandsversion vorhanden
Gültige Version herunterladen
Gültiger JSON-Zustand abgerufen
Zustandsdatei wiederherstellen
Blob erfolgreich ersetzt
Terraform "plan" ausführen
Terraform voll funktionsfähig
Ergebnis: Zustand erfolgreich wiederhergestellt unter Verwendung von Blob-Versionierung ohne manuellen Ressourcenimport.
Szenario 4 – Bereitstellung erfolgreich, muss aber rückgängig gemacht werden
Terraform "apply" erfolgreich, aber die Bereitstellung muss rückgängig gemacht werden.
Beispiel
Komponente
Status
Code
Enthält gpt-5-nano
Zustand
Enthält gpt-5-nano
Azure
gpt-5-nano vorhanden
Lösung
Setzen Sie den Terraform-Code zurück und wenden Sie ihn erneut an.
#if using git...
git checkout <earlier_branch/earlier_tag>
terraform apply -var-file=infra.tfvars
Terraform erkennt, dass die Ressource im Zustand, aber nicht im Code vorhanden ist, und löscht sie.
Szenario 5 – Fehler bei der Zustandssperre
Terraform kann die Zustandssperre nicht setzen, da eine vorherige Operation unterbrochen wurde oder noch läuft.
Benutzer stellen dies normalerweise fest, wenn sie erneut versuchen, "apply" oder "destroy" auszuführen.
Fehlerbeispiel
│Error: Error acquiring the state lock
│ Error message: state blob is already locked
│ Lock Info:
│ ID: 47befb15-5e0e-908e-d1cd-298e3c723f3d
│ Path: tfstate/infra.tfstate
│ Operation: OperationTypePlan
│ Who: user@machine
│ Version: 1.14.0
│ Created: 2026-04-09 07:02:45 +0000 UTC
Mögliche Ursachen
Vorheriger Terraform-Befehl wurde unterbrochen
Terminal- oder SSH-Sitzung stürzte während des Betriebs ab
Unterbrechung der Netzwerkverbindung während des Zustands-Schreibvorgangs
Ein anderer Benutzer oder eine andere Pipeline, der/die gleichzeitig Terraform ausführt
Lösung
1. Lösen Sie die vorhandene Zuordnung auf.
az storage blob lease break \
--account-name "<storage-account>" \
--container-name "<container>" \
--blob-name "<state-file>.tfstate" \
--auth-mode login
2. Führen Sie Terraform erneut aus.
Szenario 6 – Netzwerk- oder TLS-Fehler
Terraform schlägt aufgrund von Netzwerkkonnektivitätsproblemen mit Azure-APIs fehl.
Fehlerbeispiele
TLS-Handshake-Timeout
│ Error: creating Private Endpoint: Put "https://management.azure.com/...": 
│ net/http: TLS handshake timeout
Verbindung zurückgesetzt
│ Error: creating AKS Cluster: HTTP response was nil; connection may have been reset
Kontextgrenze überschritten
│ Error: context deadline exceeded (Client.Timeout exceeded while awaiting headers)
Mögliche Ursachen
Instabile Netzwerkverbindung
VPN- oder Proxy-Interferenzen
Temporäre Azure-API-Probleme
Blockieren durch Unternehmens-Firewalls
Anforderungs-Timeout zu kurz für langsame Operationen
Lösung
Verwenden Sie eine der folgenden geeigneten Lösungen.
Versuchen Sie es erneut. Dies ist die gängigste Lösung.
terraform apply -var-file="infra.tfvars"
Erhöhen Sie die Timeout-Zeit.
$env:ARM_CLIENT_TIMEOUT_SECONDS = "3600"
terraform apply -var-file="infra.tfvars"
Überprüfen Sie das Netzwerk.
Deaktivieren Sie vorübergehend das VPN.
Prüfen Sie die Proxy-Einstellungen.
Überprüfen Sie, ob Firewallregeln Azure-Verwaltungsendpunkte zulassen.
Szenario 7 – Ressource bereits vorhanden
Terraform versucht, eine Ressource zu erstellen, die bereits in Azure vorhanden ist, aber nicht im Zustand verfolgt wird.
Fehlerbeispiel
│ Error: a resource with the ID "/subscriptions/xxx/resourceGroups/my-rg/providers/
│ Microsoft.ContainerService/managedClusters/my-cluster" already exists - to be
│ managed via Terraform this resource needs to be imported into the State.

│ with module.aks.azurerm_kubernetes_cluster.aks,
│ on ../../modules/aks/main.tf line 13, in resource "azurerm_kubernetes_cluster" "aks":
│ 13: resource "azurerm_kubernetes_cluster" "aks" {
Mögliche Ursachen
Vorheriges Terraform "apply" schlug auf halbem Weg fehl. Dies bedeutet, dass die Ressource erstellt, aber der Zustand nicht gespeichert wird.
Ressource manuell im Azure-Portal erstellt
Zustandsdatei ist verloren gegangen, beschädigt oder mit einer älteren Version wiederhergestellt
Ressource in anderen Workspace importiert
Lösung
1. Importieren Sie die vorhandene Ressource in den Zustand.
terraform import -var-file="infra.tfvars" \
"module.aks.azurerm_kubernetes_cluster.aks" \
"/subscriptions/xxx/resourceGroups/my-rg/providers/Microsoft.ContainerService/managedClusters/my-cluster"
2. Fahren Sie mit dem Befehl "apply" fort.
terraform apply -var-file="infra.tfvars"
Szenario 8 – Abonnementkontingent überschritten
Dies geschieht, wenn Azure die Ressourcenerstellung ablehnt, weil das Abonnementkontingent überschritten wird.
Fehlerbeispiel
│ Error: creating Deployment: unexpected status 400 (400 Bad Request) with error: 
│ InsufficientQuota: This operation require 10000 new capacity in quota
│ One Thousand Tokens Per Minute - gpt-5-mini - DataZoneStandard, which is bigger
│ than the current available capacity 3650. The current quota usage is 350 and
│ the quota limit is 4000.
Mögliche Ursachen
Angeforderte Kapazität überschreitet Abonnementkontingentgrenze
Andere Bereitstellungen, die das verfügbare Kontingent verbrauchen
Regionsspezifische Kontingentgrenzen
Neues Abonnement mit standardmäßigen (niedrigen) Kontingenten
Lösung
Verwenden Sie eine der folgenden geeigneten Lösungen.
Reduzieren Sie die Kapazität in infra.tfvars.
openai_gpt5_mini_capacity = 3000 # Reduce to fit quota
Erhöhen Sie das Anfragekontingent.
a. Wechseln Sie zum Azure-Portal, und wählen Sie Quotas aus.
b. Suchen Sie nach dem Ressourcentyp. Beispiel: Cognitive Services.
c. Klicken Sie auf Request Increase.
d. Reichen Sie die Anfrage ein und warten Sie auf Genehmigung.
Verwenden Sie einen anderen Bereich, da einige Bereiche höhere Standardkontingente haben.
Szenario 9 – Fehler bei privaten Endpunkten oder DNS
Anwendungen erhalten HTTP 403-Fehler, wenn sie über einen privaten Endpunkt eine Verbindung mit Azure OpenAI herstellen.
Beispielfehler aus Anwendungsprotokollen
{"error": {"code": "403", "message": "Traffic is not from an approved private endpoint."}}
Mögliche Ursachen
DNS nach neuer Bereitstellung nicht vollständig propagiert.
Die Bereitstellung von PTU hat länger gedauert als erwartet.
Globale SKU (GlobalProvisionedManaged) mit privaten Endpunkten verwendet.
Verbindung mit privatem Endpunkt nicht genehmigt.
VNet-DNS-Verknüpfung nicht abgeschlossen.
Lösung
1. Status des privaten Endpunkts überprüfen.
az network private-endpoint show \
--resource-group "<rg>" \
--name "<pe-name>" \
--query "privateLinkServiceConnections[0].privateLinkServiceConnectionState.status"
Erwartetes Ergebnis: Approved
2. Überprüfen Sie die DNS-Auflösung.
kubectl run dns-test --image=busybox --rm -it --restart=Never -- \
nslookup <account-name>.openai.azure.com
Erwartetes Ergebnis: Aufgelöst zu privater IP 10.x.x.x.
3. Warten Sie auf die DNS-Propagierung.
Warten Sie bei neuen PTU-Bereitstellungen 10 bis 15 Minuten nachdem terraform apply abgeschlossen ist.
4. Verwenden Sie DataZone-SKUs.
Wenn Sie globale SKUs verwenden, wechseln Sie zu DataZone-Varianten.
openai_gpt5_mini_sku_name = "DataZoneProvisionedManaged" # Instead of GlobalProvisionedManaged
Szenario 10 – Löschen der Spillover-Bereitstellung blockiert
Terraform kann Spillover-Bereitstellungen nicht löschen oder ändern, da die PTU-Bereitstellung sie referenziert.
Fehlerbeispiel
│ Error: deleting Deployment: unexpected status 409 (Conflict) with error:
│ DeploymentInUse: The deployment 'gpt-5-mini-2025-08-07-spillover' cannot be
│ deleted because it is referenced by deployment 'gpt-5-mini-2025-08-07' as
│ spillover deployment.
Mögliche Ursachen
Es wird versucht, Spillover-SKU in einem einzigen terraform apply zu ändern.
Die PTU-Bereitstellung referenziert weiterhin den Spillover über spilloverDeploymentName.
Lösung
1. Löschen Sie zuerst die PTU-Bereitstellung, indem Sie den Befehl "destroy" ausführen. Dadurch wird die Spillover-Referenz entfernt.
terraform destroy \
-target="module.cognitive_deployment-gpt5-mini.azapi_resource.deployment_with_spillover[0]" \
-var-file="infra.tfvars"
2. Verwenden Sie den Befehlt "apply" für die Neuerstellung mit der neuen Konfiguration.
terraform apply -var-file="infra.tfvars"
Szenario 11 – Authentifizierungsfehler
Diese treten auf, wenn Terraform keine Authentifizierung mit Azure vornehmen kann.
Fehlerbeispiele
Nicht angemeldet
│ Error: building AzureRM Client: obtain subscription() from Azure CLI: 
│ parsing json result from the Azure CLI: waiting for the Azure CLI:
│ exit status 1: ERROR: Please run 'az login' to setup account.
Token abgelaufen
│ Error: obtaining Authorization Token: AADSTS700024: Client assertion is not 
│ within its valid time range.
Falsches Abonnement
│ Error: Subscription not found: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
Mögliche Ursachen
Nicht bei der Azure CLI angemeldet
Azure CLI-Token abgelaufen
Falsches Abonnement ausgewählt
Dienstprinzipal-Anmeldeinformationen sind abgelaufen
Lösung
1. Melden Sie sich bei Azure an.
az login
2. Legen Sie das richtige Abonnement fest.
az account set --subscription "<subscription-id>"
3. Überprüfen Sie das Abonnement.
az account show
Szenario 12 – Ressource während "destroy" nicht gefunden
Terraform versucht, "destroy" auf eine Ressource auszuführen, die in Azure nicht mehr vorhanden ist.
Fehlerbeispiele
│ Error: deleting Resource Group: the Resource Group was not found

│ Resource Group Name: "my-rg"
Mögliche Ursachen
Ressource manuell im Azure-Portal gelöscht
Ressource von einem anderen Prozess oder einer anderen Pipeline gelöscht
Ressourcenname außerhalb von Terraform geändert
Lösung
1. Entfernen Sie die fehlende Ressource aus dem Zustand.
terraform state rm "azurerm_resource_group.rg"
2. Fahren Sie mit dem Befehl "destroy" fort.
terraform destroy -var-file="infra.tfvars"
War dies hilfreich?