Erstellen von Wartebedingungen in einer Vorlage - AWS CloudFormation

Erstellen von Wartebedingungen in einer Vorlage

Wichtig

Für Amazon EC2- und Auto Scaling-Ressourcen wird die Verwendung eines CreationPolicy-Attributs anstelle von Wartebedingungen empfohlen. Fügen Sie diesen Ressourcen ein CreationPolicy-Attribut hinzu und verwenden Sie das Hilfsprogramm-Skript "cfn-signal", damit ein Signal gesendet wird, wenn ein Instance-Erstellungsvorgang erfolgreich abgeschlossen wurde.

Weitere Informationen finden Sie unter CreationPolicy oder Bereitstellen von Anwendungen auf Amazon EC2 mit AWS CloudFormation.

Mit der Ressource AWS::CloudFormation::WaitConditionHandle und dem Attribut CreationPolicy können Sie Folgendes tun:

  • Koordinieren der Erstellung von Stack-Ressourcen mit anderen Konfigurationsaktionen, die sich zur Stack-Erstellung extern verhalten

  • Verfolgen des Status eines Konfigurationsvorgangs

Sie können z. B. die Erstellung einer anderen Ressource beginnen, nachdem eine Anwendungskonfiguration teilweise abgeschlossen ist, oder während eines Installations- und Konfigurationsvorgangs Signale senden, um dessen Fortschritt zu überwachen.

Verwenden eines Wartebedingungs-Handles

Anmerkung

Wenn Sie die VPC-Endpunkt-Funktion verwenden, müssen Ressourcen in der VPC, die auf Wartebedingungen reagieren, Zugriff auf AWS CloudFormation-spezifische Amazon Simple Storage Service (Amazon S3)-Buckets haben. Ressourcen müssen Wartebedingungsantworten an eine vorsignierte Amazon S3-URL senden. Wenn sie keine Antworten an Amazon S3 senden können, empfängt AWS CloudFormation keine Antwort und die Stack-Operation schlägt fehl. Weitere Informationen finden Sie unter Einrichten von VPC-Endpunkten für AWS CloudFormation und Beispiel-Bucket-Richtlinien für VPC-Endpunkte für Amazon S3.

Sie können die Wartebedingung und den Wartebedingungs-Handle verwenden, damit AWS CloudFormation die Erstellung eines Stacks anhält und auf ein Signal wartet, bevor mit der Stack-Erstellung fortgefahren wird. Sie können beispielsweise Anwendungen auf eine Amazon EC2-Instance herunterladen und konfigurieren, bevor die Erstellung der Amazon EC2-Instance als abgeschlossen betrachtet wird.

Die folgende Liste enthält eine Zusammenfassung der Funktionsweise einer Wartebedingung mit einem Wartebedingungs-Handle:

  • AWS CloudFormation erstellt eine Wartebedingung wie jede andere Ressource. Wenn AWS CloudFormation eine Wartebedingung erstellt, wird der Status der Wartebedingung als CREATE_IN_PROGRESS gemeldet und gewartet, bis die erforderliche Anzahl Erfolgssignale erhalten wurden oder der Zeitüberschreitungzeitraum der Wartebedingung abgelaufen ist. Wenn AWS CloudFormation die erforderliche Anzahl Erfolgssignale erhält, bevor der Zeitüberschreitungszeitraum abgelaufen ist, wird die Stack-Erstellung fortgesetzt; andernfalls wird der Status der Wartebedingung auf CREATE_FAILED gesetzt und ein Rollback für den Stack durchgeführt.

  • Die Eigenschaft Timeout legt fest, wie lange AWS CloudFormation auf die erforderliche Anzahl von Erfolgssignalen wartet. Timeout ist eine minimal gebundene Eigenschaft, d. h. der Timeout tritt frühestens zu dem von Ihnen angegebenen Zeitpunkt ein, kann aber kurz danach auftreten. Die maximale Zeit, die Sie angeben können, ist 43200 Sekunden (12 Stunden).

  • In der Regel sollte eine Wartebedingung sofort nach der Erstellung einer bestimmten Ressource beginnen, z. B. einer Amazon EC2-Instance, einer RDS DB-Instance oder einer Auto Scaling-Gruppe. Dies geschieht, indem Sie das DependsOn-Attribut zu einer Wartebedingung hinzufügen. Wenn Sie ein DependsOn-Attribut zu einer Wartebedingung hinzufügen, geben Sie an, dass die Wartebedingung erst erstellt wird, nachdem die Erstellung einer bestimmten Ressource abgeschlossen ist. Nach Erstellung der Wartebedingung beginnt AWS CloudFormation den Zeitüberschreitungszeitraum und wartet auf Erfolgssignale.

  • Sie können das DependsOn-Attribut auch für andere Ressourcen verwenden. Beispiel: Sie möchten eine RDS DB-Instance erstellen und auf dieser DB-Instance eine Datenbank konfigurieren, bevor Sie die EC2-Instances erstellen, die die betreffende Datenbank verwenden. In diesem Fall erstellen Sie eine Wartebedingung mit einem DependsOn-Attribut, das die DB-Instance angibt, und Sie erstellen EC2-Instance-Ressourcen mit DependsOn-Attributen, welche die Wartebedingung angeben. Dies würde sicherstellen, dass die EC2-Instances erst unmittelbar nach Abschluss der DB-Instance und der Wartebedingung erstellt werden.

  • AWS CloudFormation muss eine bestimmte Anzahl von Erfolgssignalen für eine Wartebedingung erhalten, bevor der Status dieser Wartebedingung auf CREATE_COMPLETE gesetzt und die Stack-Erstellung fortgesetzt wird. Die Count-Eigenschaft der Wartebedingung gibt die Anzahl der Erfolgssignale an. Wenn keine festgelegt ist, ist der Standardwert 1.

  • Eine Wartebedingung erfordert ein Wartebedingungs-Handle zum Einrichten einer vorsignierten URL, die als Signalmechanismus verwendet wird. Mit der vorsignierten URL können Sie ein Signal senden, ohne dass Sie Ihre AWS-Anmeldeinformationen anzugeben brauchen. Sie verwenden diese vorsignierte URL, um Erfolg oder Misserfolg anzugeben. Sie ist in einer JSON-Anweisung verkapselt. Informationen zum Format der JSON-Anweisung finden Sie unter JSON-Format des Signals einer Wartebedingung.

  • Wenn eine Wartebedingung die erforderliche Anzahl Erfolgssignale (wie in der Count-Eigenschaft definiert) erhält, bevor der Zeitüberschreitungszeitraum abgelaufen ist, kennzeichnet AWS CloudFormation die Wartebedingung als CREATE_COMPLETE und setzt die Stack-Erstellung fort. Andernfalls gibt AWS CloudFormation einen Fehler für die Wartebedingung zurück und führt ein Rollback für den Stack durch (wenn beispielsweise der Zeitüberschreitungszeitraum ohne die erforderlichen Erfolgssignale abläuft oder ein Fehlersignal empfangen wird).

So verwenden Sie eine Wartebedingung in einem Stack:

  1. Deklarieren Sie eine AWS::CloudFormation::WaitConditionHandle-Ressource in der Stack-Vorlage. Ein Wartebedingungs-Handle hat keine Eigenschaften; ein Verweis auf eine WaitConditionHandle-Ressource wird aber zu einer vorsignierten URL aufgelöst, die Sie verwenden können, um der WaitCondition Erfolg oder Fehler zu melden. Beispiel:

    "myWaitHandle" : { "Type" : "AWS::CloudFormation::WaitConditionHandle", "Properties" : { } }
  2. Deklarieren Sie eine AWS::CloudFormation::WaitCondition-Ressource in der Stack-Vorlage. Eine WaitCondition-Ressource verfügt über zwei erforderliche Eigenschaften: „Handle“ ist ein Verweis auf ein in der Vorlage deklariertes WaitConditionHandle, und „Timeout“ ist die Anzahl Sekunden, die AWS CloudFormation warten muss. Sie können optional die Count-Eigenschaft festlegen, die die Anzahl der Erfolgssignale bestimmt, welche die Wartebedingung erhalten muss, bevor AWS CloudFormation die Stack-Erstellung fortsetzen kann.

    Um zu steuern, wann die Wartebedingung ausgelöst wird, legen Sie ein DependsOn-Attribut für die Wartebedingung fest. Eine DependsOn Klausel verknüpft eine Ressource mit der Wartebedingung. Nachdem AWS CloudFormation die DependsOn-Ressource erstellt hat, wird jede weitere Stack-Ressourcenerstellung blockiert, bis eines der folgenden Ereignisse eintritt: a) der Zeitüberschreitungszeitraum läuft ab, b) die erforderliche Anzahl Erfolgssignale wird empfangen, c) ein Fehlersignal wird empfangen.

    Dies ist ein Beispiel für eine Wartebedingung, die nach der erfolgreichen Erstellung der Ec2Instance-Ressource beginnt, die myWaitHandle-Ressource als WaitConditionHandle verwendet, eine Zeitüberschreitung von 4500 Sekunden und eine Standardanzahl von 1 hat (da keine Count-Eigenschaft angegeben ist):

    "myWaitCondition" : { "Type" : "AWS::CloudFormation::WaitCondition", "DependsOn" : "Ec2Instance", "Properties" : { "Handle" : { "Ref" : "myWaitHandle" }, "Timeout" : "4500" } }
  3. Rufen Sie die vorsignierte URL ab, die für Signale verwendet werden soll.

    In der Vorlage kann die vorsignierte URL abgerufen werden, indem der logische Name der AWS::CloudFormation::WaitConditionHandle-Ressource an die intrinsische Ref-Funktion übergeben wird. Beispiel: Sie können die UserData-Eigenschaft von AWS::EC2::Instance-Ressourcen verwenden, um die vorsignierte URL an die Amazon EC2-Instances zu übergeben, damit die Skripts oder Anwendungen, die auf diesen Instances ausgeführt werden, Erfolg oder Fehler an AWS CloudFormation melden können:

    "UserData" : { "Fn::Base64" : { "Fn::Join" : [ "", ["SignalURL=", { "Ref" : "myWaitHandle" } ] ] } }

    Hinweis: In der AWS Management Console oder den AWS CloudFormation-Befehlszeilen-Tools wird die vorsignierte URL als die physische ID der Wartebedingungs-Handle-Ressource angezeigt.

  4. Wählen Sie eine Methode aus, mit der erkannt wird, wann für den Stack die Wartebedingung beginnt.

    Wenn Sie den Stack mit aktivierten Benachrichtigungen erstellen, veröffentlicht AWS CloudFormation eine Benachrichtigung für jedes Stack-Ereignis für das angegebene Thema. Wenn Sie oder Ihre Anwendung dieses Thema abonnieren, können Sie die Benachrichtigungen für das Wartebedingungs-Handle-Erstellungsereignis überwachen und die vorsignierte URL aus der Benachrichtigungsnachricht abrufen.

    Sie können die Ereignisse des Stacks auch mithilfe der AWS Management Console, der AWS CloudFormation-Befehlszeilen-Tools oder der AWS CloudFormation-API überwachen.

  5. Verwenden Sie die vorsignierte URL, um Erfolg oder Fehler anzugeben.

    Um ein Signal zu senden, senden Sie eine HTTP-Anforderungsnachricht mithilfe der vorsignierten URL. Die Anforderungsmethode muss PUT und der Content-Type-Header muss eine leere Zeichenfolge oder nicht angegeben sein. Die Anforderungsnachricht muss eine JSON-Struktur der Form aufweisen, die in JSON-Format des Signals einer Wartebedingung angegeben ist.

    Sie müssen die Anzahl der Erfolgssignale senden, die von der Count-Eigenschaft angegeben werden, damit AWS CloudFormation die Stack-Erstellung fortsetzen kann. Wenn die Anzahl größer als 1 ist, muss der UniqueId-Wert für jedes Signal über alle Signale hinweg, die an eine bestimmte Wartebedingung gesendet werden, eindeutig sein. Die UniqueId ist eine beliebige alphanumerische Zeichenfolge.

    Ein Curl-Befehl ist eine Möglichkeit zum Senden eines Signals. Das folgende Beispiel zeigt eine Curl-Befehlszeile, die für eine Wartebedingung einen Erfolg signalisiert.

    curl -T /tmp/a "https://cloudformation-waitcondition-test.s3.amazonaws.com/arn%3Aaws%3Acloudformation%3Aus-east-2%3A034017226601%3Astack%2Fstack-gosar-20110427004224-test-stack-with-WaitCondition--VEYW%2Fe498ce60-70a1-11e0-81a7-5081d0136786%2FmyWaitConditionHandle?Expires=1303976584&AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE&Signature=ik1twT6hpS4cgNAw7wyOoRejVoo%3D"

    wobei die Datei /tmp/a die folgenden JSON-Struktur enthält:

    { "Status" : "SUCCESS", "Reason" : "Configuration Complete", "UniqueId" : "ID1234", "Data" : "Application has completed configuration." }

    Das folgende Beispiel zeigt eine Curl-Befehlszeile, die dasselbe Erfolgssignal sendet, wobei aber die JSON-Struktur als Parameter in der Befehlszeile gesendet wird.

    curl -X PUT -H 'Content-Type:' --data-binary '{"Status" : "SUCCESS","Reason" : "Configuration Complete","UniqueId" : "ID1234","Data" : "Application has completed configuration."}' "https://cloudformation-waitcondition-test.s3.amazonaws.com/arn%3Aaws%3Acloudformation%3Aus-east-2%3A034017226601%3Astack%2Fstack-gosar-20110427004224-test-stack-with-WaitCondition--VEYW%2Fe498ce60-70a1-11e0-81a7-5081d0136786%2FmyWaitConditionHandle?Expires=1303976584&AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE&Signature=ik1twT6hpS4cgNAw7wyOoRejVoo%3D"

JSON-Format des Signals einer Wartebedingung

Wenn Sie ein Signal an eine Wartebedingung senden, müssen Sie das folgenden JSON-Format verwenden:

{ "Status" : "StatusValue", "UniqueId" : "Some UniqueId", "Data" : "Some Data", "Reason" : "Some Reason" }

Wobei gilt:

StatusValue muss einen der folgenden Werte aufweisen:

  • SUCCESS gibt ein Erfolgssignal an.

  • FAILURE gibt ein Fehlersignal an und löst eine fehlgeschlagene Wartebedingung und das Rollback des Stacks aus.

UniqueId identifiziert das Signal für AWS CloudFormation. Wenn die Count-Eigenschaft der Wartebedingung größer als 1 ist, muss der UniqueId-Wert für jedes Signal über alle Signale hinweg, die an eine bestimmte Wartebedingung gesendet werden, eindeutig sein. Andernfalls betrachtet AWS CloudFormation das Signal als Neuübertragung des zuvor gesendeten Signals mit der gleichen UniqueId und ignoriert das Signal.

Data sind beliebige Informationen, die Sie zusammen mit dem Signal senden möchten. Auf den Data-Wert kann zugegriffen werden, indem Sie die Fn::GetAtt-Funktion innerhalb der Vorlage aufrufen. Wenn Sie z. B. den folgenden Ausgabewert für die Wartebedingung „mywaitcondition“ erstellen, können Sie den Befehl aws cloudformation describe-stacks, die DescribeStacks-Aktion oder die Ausgabe-Registerkarte der CloudFormation-Konsole verwenden, um die von gültigen Signalen an AWS CloudFormation gesendeten Daten anzuzeigen:

"WaitConditionData" : { "Value" : { "Fn::GetAtt" : [ "mywaitcondition", "Data" ]}, "Description" : "The data passed back as part of signalling the WaitCondition" },

Die Fn::GetAtt-Funktion gibt „UniqueId“ und „Data“ als Name-Wert-Paar innerhalb einer JSON-Struktur zurück. Das folgende Beispiel zeigt ein Data-Attribut, das vom WaitConditionData-Ausgabewert wie oben definiert zurückgegeben wird:

{"Signal1":"Application has completed configuration."}

Reason ist eine Zeichenfolge mit keinen anderen Einschränkungen für den Inhalt als der Übereinstimmung mit JSON.