CloudFormation ROLLBACK_COMPLETE: Stack-Fehler verstehen und beheben

Sie führen aws cloudformation create-stack aus und warten. Die Stack-Erstellung beginnt, Ressourcen werden provisioniert, und dann stoppt alles. Der Stack-Status wechselt zu ROLLBACK_IN_PROGRESS und landet schließlich bei ROLLBACK_COMPLETE. Ihr Stack existiert, enthält aber keine Ressourcen. Sie können ihn nicht aktualisieren. Sie können die Erstellung nicht wiederholen. Er sitzt einfach da — ein Denkmal für etwas, das schiefgelaufen ist.

Dies ist einer der frustrierendsten Zustände in ganz AWS. Ein Stack im Status ROLLBACK_COMPLETE kann nicht aktualisiert werden — er kann nur gelöscht und neu erstellt werden. Aber bevor Sie ihn blind löschen und es erneut versuchen, müssen Sie verstehen, was schiefgelaufen ist. Sonst landen Sie fünf Minuten später im selben Zustand.

So extrahieren Sie aussagekräftige Fehlerinformationen aus einem fehlgeschlagenen Stack, verstehen die häufigsten Ursachen und erholen sich effizient.

Die eigentliche Fehlermeldung extrahieren

CloudFormation vergräbt die tatsächlichen Fehlermeldungen in den Stack-Events. Der Stack-Status selbst sagt nur ROLLBACK_COMPLETE, was Ihnen nichts über die Ursache verrät. Die Details stecken in den einzelnen Ressourcen-Events.

# Alle Events des fehlgeschlagenen Stacks abrufen
aws cloudformation describe-stack-events \
  --stack-name my-failed-stack \
  --query 'StackEvents[?ResourceStatus==`CREATE_FAILED`].{
    Resource: LogicalResourceId,
    Type: ResourceType,
    Reason: ResourceStatusReason,
    Timestamp: Timestamp
  }' \
  --output table

Dies filtert den Event-Stream, um nur die Ressourcen anzuzeigen, die tatsächlich fehlgeschlagen sind, zusammen mit dem Grund. Das erste CREATE_FAILED-Event ist normalerweise die Grundursache — nachfolgende Fehler sind oft Kaskadenwirkungen des ersten Fehlers.

Für ein vollständigeres Bild der Zeitleiste:

# Die vollständige Event-Zeitleiste abrufen
aws cloudformation describe-stack-events \
  --stack-name my-failed-stack \
  --query 'StackEvents[*].{
    Time: Timestamp,
    Resource: LogicalResourceId,
    Status: ResourceStatus,
    Reason: ResourceStatusReason
  }' \
  --output table

Lesen Sie die Events von unten (älteste) nach oben (neueste), um die Abfolge zu verstehen: welche Ressource zuerst fehlschlug, was der Fehler war und wie sich der Rollback ausbreitete.

Ursache 1: Unzureichende IAM-Berechtigungen

Die häufigste Ursache für Stack-Fehler ist, dass die CloudFormation-Service-Rolle (oder der IAM-Benutzer/die Rolle, die den Befehl ausführt) keine Berechtigungen hat, die Ressourcen im Template zu erstellen.

Die Fehlermeldung sieht so aus:

API: ec2:CreateSecurityGroup You are not authorized to perform this operation.
Encoded authorization failure message: ...

Das Berechtigungsproblem diagnostizieren:

Wenn der Fehler eine kodierte Autorisierungsfehlermeldung enthält, dekodieren Sie sie:

aws sts decode-authorization-message \
  --encoded-message "LANGER_KODIERTER_STRING_HIER" \
  --query 'DecodedMessage' \
  --output text | python3 -m json.tool

Die dekodierte Nachricht zeigt genau, welche IAM-Aktion verweigert wurde, auf welcher Ressource und welche Policy-Bedingungen ausgewertet wurden.

Die Lösung: Fügen Sie die erforderlichen Berechtigungen zur CloudFormation-Service-Rolle hinzu:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:CreateSecurityGroup",
        "ec2:DeleteSecurityGroup",
        "ec2:AuthorizeSecurityGroupIngress",
        "ec2:AuthorizeSecurityGroupEgress",
        "ec2:RevokeSecurityGroupIngress",
        "ec2:RevokeSecurityGroupEgress",
        "ec2:DescribeSecurityGroups"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "aws:RequestedRegion": "us-east-1"
        }
      }
    }
  ]
}

Beachten Sie, dass CloudFormation sowohl Erstell- als auch Löschberechtigungen für jeden Ressourcentyp benötigt. Wenn es eine Ressource erstellen, aber nicht löschen kann, scheitert der Rollback selbst, was Sie in den noch schlimmeren Zustand ROLLBACK_FAILED versetzt.

Ursache 2: Ressourcenlimit überschritten

Jedes AWS-Konto hat Service-Quotas. Wenn Ihr Template versucht, eine Ressource zu erstellen, die ein Quota überschreiten würde, scheitert die Erstellung.

Häufige Beispiele:

The maximum number of VPCs has been reached. (Service: AmazonEC2; Status Code: 400)

Cannot create more than 200 security groups for vpc-0abc123

Aktuelle Quotas prüfen:

# Alle EC2-Quotas mit aktueller Nutzung auflisten
aws service-quotas list-service-quotas \
  --service-code ec2 \
  --query 'Quotas[?UsageMetric].{
    Name: QuotaName,
    Value: Value,
    Adjustable: Adjustable
  }' \
  --output table

Die Lösung: Entweder eine Quota-Erhöhung beantragen oder das Template umgestalten:

# Quota-Erhöhung beantragen
aws service-quotas request-service-quota-increase \
  --service-code ec2 \
  --quota-code L-0263D0A3 \
  --desired-value 10

Ursache 3: Ungültige Eigenschaftswerte

Die Template-Validierung fängt Syntaxfehler ab, kann aber nicht validieren, ob ein Eigenschaftswert in Ihrem Konto und Ihrer Region tatsächlich gültig ist:

The subnet ID 'subnet-0abc123' does not exist (Service: AmazonEC2)

The key pair 'my-keypair' does not exist (Service: AmazonEC2)

The AMI ID 'ami-0abc123' does not exist

Diese Fehler treten auf, wenn:

Sie ein Template von einem Konto oder einer Region in ein anderes kopieren, ohne Ressourcenreferenzen zu aktualisieren
Eine referenzierte Ressource (Subnet, Key Pair, AMI) gelöscht wurde, nachdem das Template geschrieben wurde
Sie hartcodierte Ressourcen-IDs anstelle von Parametern verwenden

Die Lösung: Verwenden Sie Parameter für alle umgebungsspezifischen Werte und validieren Sie sie vor der Stack-Erstellung:

# Template-Syntax validieren
aws cloudformation validate-template \
  --template-body file://template.yaml

# Referenzierte Ressourcen verifizieren
aws ec2 describe-subnets --subnet-ids subnet-0abc123
aws ec2 describe-key-pairs --key-names my-keypair
aws ec2 describe-images --image-ids ami-0abc123

Ursache 4: Ressource existiert bereits

Wenn Ihr Template einen physischen Ressourcennamen angibt (wie einen DynamoDB-Tabellennamen oder S3-Bucket-Namen) und diese Ressource bereits existiert, scheitert die Erstellung:

my-table already exists in stack arn:aws:cloudformation:us-east-1:123456789:stack/other-stack/abc123

my-bucket already exists

Dies passiert häufig, wenn Sie einen Stack löschen und neu erstellen, weil einige Ressourcen (wie S3-Buckets mit Daten) bei der Stack-Löschung beibehalten werden.

Finden, welcher Stack eine Ressource besitzt:

# Ressource über alle Stacks hinweg suchen
aws cloudformation list-stack-resources \
  --stack-name other-stack \
  --query 'StackResourceSummaries[?PhysicalResourceId==`my-table`]'

Die Lösung: Entweder die Ressource im Template umbenennen, die bestehende Ressource in Ihren Stack importieren oder die verwaiste Ressource zuerst löschen:

# Verwaisten S3-Bucket leeren und löschen
aws s3 rm s3://my-bucket --recursive
aws s3api delete-bucket --bucket my-bucket

Ursache 5: Zirkuläre Abhängigkeiten

CloudFormation löst die Reihenfolge der Ressourcenerstellung basierend auf Abhängigkeitsreferenzen auf (Ref, Fn::GetAtt, DependsOn). Wenn Ressource A auf Ressource B verweist und Ressource B auf Ressource A, kann CloudFormation nicht bestimmen, welche zuerst erstellt werden soll:

Circular dependency between resources: [SecurityGroup, LaunchTemplate]

Die Lösung: Brechen Sie den Zyklus auf, indem Sie die Ressourcen trennen. Für die häufige Security-Group-zirkuläre-Abhängigkeit verwenden Sie separate Security-Group-Regel-Ressourcen:

SecurityGroupA:
  Type: AWS::EC2::SecurityGroup
  Properties:
    GroupDescription: Group A

SecurityGroupB:
  Type: AWS::EC2::SecurityGroup
  Properties:
    GroupDescription: Group B

# Ingress-Regeln als separate Ressourcen, um den Zyklus zu brechen
IngressAFromB:
  Type: AWS::EC2::SecurityGroupIngress
  Properties:
    GroupId: !Ref SecurityGroupA
    SourceSecurityGroupId: !Ref SecurityGroupB
    IpProtocol: tcp
    FromPort: 443
    ToPort: 443

IngressBFromA:
  Type: AWS::EC2::SecurityGroupIngress
  Properties:
    GroupId: !Ref SecurityGroupB
    SourceSecurityGroupId: !Ref SecurityGroupA
    IpProtocol: tcp
    FromPort: 443
    ToPort: 443

Wiederherstellung aus ROLLBACK_COMPLETE

Ein Stack im Status ROLLBACK_COMPLETE kann nicht aktualisiert werden. Ihre einzige Option ist, ihn zu löschen und es erneut zu versuchen:

# Den fehlgeschlagenen Stack löschen
aws cloudformation delete-stack \
  --stack-name my-failed-stack

# Auf den Abschluss der Löschung warten
aws cloudformation wait stack-delete-complete \
  --stack-name my-failed-stack

Beheben Sie vor der Neuerstellung die in den Stack-Events identifizierte Grundursache. Erstellen Sie dann mit dem korrigierten Template neu.

Wiederherstellung aus ROLLBACK_FAILED und DELETE_FAILED

Manchmal scheitert der Rollback selbst — vielleicht hat CloudFormation eine Ressource erstellt, kann sie aber nicht löschen. Der Stack wechselt in ROLLBACK_FAILED oder DELETE_FAILED.

Für ROLLBACK_FAILED:

# Rollback fortsetzen, problematische Ressourcen überspringen
aws cloudformation continue-update-rollback \
  --stack-name my-stuck-stack \
  --resources-to-skip "MyS3Bucket" "MyDynamoTable"

Für DELETE_FAILED:

# Erzwungenes Löschen, nicht löschbare Ressourcen beibehalten
aws cloudformation delete-stack \
  --stack-name my-stuck-stack \
  --retain-resources "MyS3Bucket" "MyDynamoTable"

--disable-rollback zum Debuggen verwenden

Wenn Sie ein Template debuggen, das immer wieder fehlschlägt, ist der automatische Rollback kontraproduktiv — er zerstört die Ressourcen, bevor Sie sie untersuchen können:

aws cloudformation create-stack \
  --stack-name my-debug-stack \
  --template-body file://template.yaml \
  --disable-rollback \
  --parameters ParameterKey=Environment,ParameterValue=dev

Wenn der Stack fehlschlägt, wechselt er in CREATE_FAILED statt ROLLBACK_COMPLETE. Die erfolgreich erstellten Ressourcen bleiben bestehen, und Sie können sie untersuchen.

Wichtig: Verwenden Sie --disable-rollback niemals in Produktions-Pipelines. Es ist nur ein Debugging-Werkzeug.

Drift-Erkennung: Warum Updates bei bestehenden Stacks fehlschlagen

Manchmal scheitert ein Stack, der monatelang gut funktioniert hat, plötzlich bei einem Update. Die Ursache ist oft Drift — jemand hat eine vom Stack verwaltete Ressource direkt über die Konsole oder CLI geändert.

# Drift-Erkennung starten
aws cloudformation detect-stack-drift \
  --stack-name my-stack

# Drift-Erkennungsstatus prüfen
aws cloudformation describe-stack-drift-detection-status \
  --stack-drift-detection-id "detection-id-here"

# Gedriftete Ressourcen anzeigen
aws cloudformation describe-stack-resource-drifts \
  --stack-name my-stack \
  --stack-resource-drift-status-filters MODIFIED DELETED \
  --query 'StackResourceDrifts[*].{
    Resource: LogicalResourceId,
    Status: StackResourceDriftStatus,
    Differences: PropertyDifferences
  }'

Wenn Drift erkannt wird, müssen Sie entweder das Template aktualisieren, um den aktuellen Zustand wiederzugeben, oder die gedrifteten Ressourcen manuell auf den Template-Zustand zurücksetzen.

Best Practices zur Prävention

Immer validate-template vor create-stack ausführen — Syntaxfehler frühzeitig abfangen
Change Sets für Updates verwenden — überprüfen, was CloudFormation plant, bevor es es tut:

aws cloudformation create-change-set \
  --stack-name my-stack \
  --template-body file://template.yaml \
  --change-set-name my-changes

aws cloudformation describe-change-set \
  --stack-name my-stack \
  --change-set-name my-changes \
  --query 'Changes[*].ResourceChange.{
    Action: Action,
    Resource: LogicalResourceId,
    Replacement: Replacement
  }'

Hartcodierte Ressourcennamen vermeiden — lassen Sie CloudFormation automatisch Namen generieren
Stack-Policies verwenden, um versehentliches Löschen kritischer Ressourcen zu verhindern
Zuerst in einem Nicht-Produktionskonto testen — Berechtigungs- und Quota-Probleme erkennen, bevor sie die Produktion betreffen

Wenn CloudFormation-Probleme chronisch werden

Wenn Ihr Team regelmäßig mit CloudFormation-Fehlern kämpft, liegt das Problem normalerweise nicht bei CloudFormation selbst — es ist die Template-Architektur, das Berechtigungsmodell oder der Deployment-Prozess. Schlecht strukturierte Templates mit Hunderten von Ressourcen, unzureichende Service-Rollen-Berechtigungen und manuelle Deployments ohne Change Sets sind Rezepte für wiederholte Fehler.

Wir helfen Teams, ihre CloudFormation-Templates in handhabbare, verschachtelte Stacks mit ordnungsgemäßem Abhängigkeitsmanagement umzustrukturieren, CI/CD-Pipelines mit automatisierter Change-Set-Überprüfung zu implementieren und Service-Rollen mit Least-Privilege-Berechtigungen aufzubauen. Kontaktieren Sie uns für eine kostenlose AWS-Beratung und lassen Sie uns Ihnen helfen, einen Deployment-Prozess aufzubauen, der zuverlässig funktioniert.