Verwenden von AWS CloudFormation-Makros zum Durchführen der benutzerdefinierten Verarbeitung von Vorlagen

Verwenden Sie Makros, um benutzerdefinierte Verarbeitungen von Vorlagen durchzuführen – von einfachen Aktionen wie Suchen und Ersetzen bis hin zu umfangreichen Transformationen ganzer Vorlagen.

Um sich ein Bild von der Bandbreite der Möglichkeiten zu machen, schauen Sie sich die AWS::Include- und AWS::Serverless-Transformationen an. Diese sind Makros, die von AWS CloudFormation gehostet werden:

• AWS::Include-Transformation ermöglicht es Ihnen, Ausschnitte aus Boilerplate Vorlagen in Ihre Vorlagen einzufügen.

• AWS::Serverless-Transformation nimmt eine komplette Vorlage, die in der AWS Serverless Application Model (AWS SAM)-Syntax geschrieben ist, und transformiert und erweitert sie in eine konforme AWS CloudFormation-Vorlage. (Weitere Informationen zu serverlosen Anwendungen und AWS SAM finden Sie unter Bereitstellen Lambda-basierter Anwendungen im AWS Lambda Developer Guide.)

Funktionsweise von AWS CloudFormation-Makros

Die Bearbeitung von Vorlagen mit Makros besteht aus zwei wesentlichen Schritten: Erstellen des Makros selbst, und dann Verwenden des Makros, um die Verarbeitung Ihrer Vorlagen durchzuführen.

Um eine Makrodefinition zu erstellen, müssen Sie Folgendes erstellen:

• Eine AWS Lambda-Funktion zur Durchführung der Vorlagenbearbeitung. Diese Lambda-Funktion akzeptiert entweder einen Ausschnitt oder eine ganze Vorlage und alle zusätzlichen Parameter, die Sie definieren. Sie gibt den bearbeiteten Vorlagenausschnitt oder die gesamte Vorlage als Antwort zurück.

• Eine Ressource vom Typ AWS::CloudFormation::Macro, die es dem Benutzer ermöglicht, die Lambda-Funktion aus den AWS CloudFormation-Vorlagen heraus aufzurufen. Diese Ressource spezifiziert den ARN der Lambda-Funktion, die für dieses Makro aufgerufen werden soll, und zusätzliche optionale Eigenschaften, die beim Debuggen helfen. Um diese Ressource in einem Konto zu erstellen, erstellen Sie eine Vorlage, die eine AWS::CloudFormation::Macro-Ressource enthält, und erstellen Sie dann entweder einen Stack oder ein Stack-Set mit selbst verwalteten Berechtigungen aus der Vorlage. AWS CloudFormation StackSets unterstützt derzeit nicht das Erstellen oder Aktualisieren von Stack-Sets mit serviceverwalteten Berechtigungen aus Vorlagen, die auf Makros verweisen.

Um ein Makro zu verwenden, referenzieren Sie das Makro in Ihrer Vorlage:

• Um einen Abschnitt oder Ausschnitt einer Vorlage zu bearbeiten, verweisen Sie in einer Fn::Transform-Funktion auf das Makro, das relativ zu dem zu transformierenden Vorlageninhalt angeordnet ist. Bei Verwendung von Fn::Transform können Sie außerdem beliebige Parameter übergeben.

• Um eine gesamte Vorlage zu bearbeiten, referenzieren Sie das Makro im Abschnitt Transform der Vorlage.

Als Nächstes erstellen Sie normalerweise einen Änderungssatz und führen diesen aus. (Verarbeitungsmakros können mehrere Ressourcen hinzufügen, die Ihnen möglicherweise nicht bekannt sind. Um sicherzustellen, dass Sie alle durch Makros eingeführten Änderungen kennen, wird dringend empfohlen, Änderungssätze zu verwenden.) AWS CloudFormation übergibt den angegebenen Vorlageninhalt zusammen mit allen zusätzlich angegebenen Parametern an die in der Makro-Ressource angegebene Lambda-Funktion. Die Lambda-Funktion gibt den bearbeiteten Vorlageninhalt zurück, sei es ein Ausschnitt oder eine ganze Vorlage.

Nachdem alle Makros in der Vorlage aufgerufen wurden, erzeugt AWS CloudFormation einen Änderungssatz, der den bearbeiteten Vorlageninhalt enthält. Nachdem Sie den Änderungssatz überprüft haben, führen Sie ihn aus, um die Änderungen anzuwenden.

Wichtig

Wenn Ihre Stack-Set-Vorlage auf ein oder mehrere Makros verweist, müssen Sie das Stack-Set direkt aus der verarbeiteten Vorlage erstellen, ohne vorher die resultierenden Änderungen in einem Änderungssatz zu überprüfen. Um das Stack-Set direkt zu erstellen oder zu aktualisieren, müssen Sie die Aktion CreateStackSet oder UpdateStackSet verwenden und die CAPABILITY_AUTO_EXPAND-Funktion angeben. Bevor Sie einen Stack-Set aus einer Vorlage erstellen oder aktualisieren, die direkt auf Makros verweist, sollten Sie sicherstellen, dass Sie wissen, welche Verarbeitung die Makros ausführen.

Anmerkung

Wenn Ihnen die direkte Erstellung oder Aktualisierung eines Stacks von einer verarbeiteten Vorlage geläufig ist und Sie die vorgeschlagenen Änderungen nicht vorher in einem Änderungssatz überprüfen müssen, können Sie während einer CreateStack- oder UpdateStack-Anforderung die CAPABILITY_AUTO_EXPAND-Funktion angeben. Sie sollten Stacks nur dann direkt aus einer Vorlage erstellen, die auf mit Makros verweist, wenn Sie wissen, welche Verarbeitungsschritte das Makro ausführt.

Außerdem unterstützen Änderungssätze derzeit keine verschachtelten Stacks. Wenn Sie einen Stack von einer Stack-Vorlage erstellen möchten, die auf Makros verweist und verschachtelte Stacks enthält, müssen Sie den Stack mit dieser Funktion direkt von der Vorlage erstellen.

Weitere Informationen finden Sie unter CreateStack oder UpdateStack im AWS CloudFormation API Reference.

Erstellen einer AWS CloudFormation-Makrodefinition

Wenn Sie eine Makrodefinition erstellen, stellt die Makrodefinition die zugrundeliegende Lambda-Funktion im angegebenen Konto zur Verfügung, sodass AWS CloudFormation sie zur Bearbeitung der Vorlagen aufrufen kann.

AWS CloudFormation-Makro-Funktionsschnittstelle

Bei Makros ruft AWS CloudFormation die zugrundeliegenden Lambda-Funktionen mit der folgenden Ereigniszuordnung auf. AWS CloudFormation sendet seine Anforderung im JSON-Format und erwartet, dass die Funktionsantwort auch als JSON formatiert wird.

{
    "region" : "us-east-1",
    "accountId" : "$ACCOUNT_ID",
    "fragment" : { ... },
    "transformId" : "$TRANSFORM_ID",
    "params" : { ... },
    "requestId" : "$REQUEST_ID",
    "templateParameterValues" : { ... }
}

• region

  Die Region, in der sich das Makro befindet.

• accountId

  Die Konto-ID des Kontos, von dem aus das Makro die Lambda-Funktion aufruft.

• fragment

  Der Vorlageninhalt, der für die benutzerdefinierte Verarbeitung zur Verfügung steht, im JSON-Format.

  • Bei Makros, die im Vorlagenabschnitt Transform enthalten sind, ist dies die gesamte Vorlage mit Ausnahme des Abschnitts Transform.

  • Bei Makros, die in einem intrinsischen Fn::Transform-Funktionsaufruf enthalten sind, sind dies alle Geschwisterknoten (und ihre Unterknoten), basierend auf der Position der intrinsischen Funktion innerhalb der Vorlage, mit Ausnahme der Fn::Transform Funktion. Weitere Informationen finden Sie unter AWS CloudFormation-Makrobereich.

• transformId

  Der Name des Makros, das diese Funktion aufruft.

• params

  Bei Fn::Transform-Funktionsaufrufen alle angegebenen Parameter für die Funktion. AWS CloudFormation wertet diese Parameter nicht aus, bevor sie an die Funktion übergeben werden.

  Für Makros, die im Vorlagenabschnitt Transform enthalten sind, ist dieser Abschnitt leer.

• requestId

  Die ID der Anforderung, die diese Funktion aufruft.

• templateParameterValues

  Alle Parameter, die im Abschnitt Parameter der Vorlage angegeben sind. AWS CloudFormation wertet diese Parameter aus, bevor sie an die Funktion übergeben werden.

AWS CloudFormation erwartet, dass die zugrundeliegende Funktion eine Antwort im folgenden JSON-Format zurückgibt:

{
    "requestId" : "$REQUEST_ID",
    "status" : "$STATUS",
    "fragment" : { ... }
}

• requestId

  Die ID der Anforderung, die diese Funktion aufruft. Diese muss mit der Anforderungs-ID übereinstimmen, die von AWS CloudFormation beim Aufruf der Funktion angegeben wird.

• status

  Der Status der Anforderung (Groß-/Kleinschreibung wird nicht berücksichtigt). Dieser sollte auf success festgelegt werden. AWS CloudFormation behandelt jede andere Antwort als Fehler.

• fragment

  Der Inhalt der verarbeiteten Vorlage für AWS CloudFormation, der in die verarbeitete Vorlage aufgenommen werden soll, einschließlich der Geschwister. AWS CloudFormation ersetzt den Vorlageninhalt, der an die Lambda-Funktion übergeben wird, durch das Vorlagenfragment, das es in der Lambda-Antwort erhält.

  Der Inhalt der verarbeiteten Vorlage muss gültiges JSON sein, und seine Aufnahme in die verarbeitete Vorlage muss zu einer gültigen Vorlage führen.

  Wenn Ihre Funktion den Vorlageninhalt, den AWS CloudFormation an sie übergibt, nicht verändert, Sie diesen Inhalt aber dennoch in die bearbeitete Vorlage aufnehmen müssen, muss Ihre Funktion diesen Vorlageninhalt in ihrer Antwort an AWS CloudFormation zurückgeben.

• errorMessage

  Die Fehlermeldung, die erklärt, warum die Transformation fehlgeschlagen ist. CloudFormation zeigt diese Fehlermeldung im Bereich Ereignisse der Seite Stack-Details für Ihren Stack an.

  Beispiel: „Fehler beim Erstellen des Änderungssatzes: Transform AWS account-Kontonummer::Makroname ist fehlgeschlagen mit: Fehlermeldungszeichenfolge“.

Informationen zu weiteren Überlegungen bei der Erstellung von Makros finden Sie unter Überlegungen zur Erstellung von AWS CloudFormation-Makrodefinitionen.

AWS CloudFormation Umfang und Berechtigungen des Makro-Kontos

Makros können Sie nur in dem Konto verwenden, in dem sie als Ressource angelegt wurden. Der Name des Makros muss innerhalb eines bestimmten Kontos eindeutig sein. Sie können jedoch die gleiche Funktionalität in mehreren Konten zur Verfügung stellen, indem Sie den kontenübergreifenden Zugriff auf die zugrundeliegende Lambda-Funktion aktivieren und dann Makrodefinitionen erstellen, die sich in mehreren Konten auf diese Funktion beziehen. Im folgenden Beispiel enthalten drei Konten Makrodefinitionen, die jeweils auf dieselbe Lambda-Funktion verweisen.

Weitere Informationen finden Sie unter Übersicht über die Verwaltung von Zugriffsberechtigungen für Ihre AWS Lambda-Ressourcen in der AWS Lambda Developer Guide.

Um eine Makrodefinition zu erstellen, muss der Benutzer die Berechtigung haben, einen Stack oder Stack-Set innerhalb des angegebenen Kontos zu erstellen.

Damit AWS CloudFormation ein in einer Vorlage enthaltenes Makro erfolgreich ausführen kann, muss der Benutzer über Invoke-Berechtigungen für die zugrundeliegende Lambda-Funktion verfügen. Um eine mögliche Ausweitung der Berechtigungen zu verhindern, übernimmt AWS CloudFormation die Rolle des Benutzers während der Ausführung des Makros. Weitere Informationen finden Sie unter Lambda-Berechtigungsmodell im AWS Lambda Developer Guide und Aktionen und Bedingungskontextschlüssel für AWS Lambda im IAM-Benutzerhandbuch.

Die Transformationen AWS::Serverless-Transformation und AWS::Include-Transformation sind Makros, die von AWS CloudFormation gehostet werden. Es sind keine besonderen Berechtigungen erforderlich, um sie zu verwenden, und sie sind von jedem Konto in AWS CloudFormation aus verfügbar.

Debuggen von AWS CloudFormation-Makros

Um das Debuggen zu erleichtern, können Sie beim Anlegen des Ressourcentyps AWS::CloudFormation::Macro für Ihr Makro auch die Eigenschaften LogGroupName und LogRoleArn angeben. Diese Eigenschaften ermöglichen es Ihnen, die CloudWatch-Protokollgruppe anzugeben, an die AWS CloudFormation beim Aufruf der dem Makro zugrundeliegenden AWS Lambda-Funktion Fehlerprotokollinformationen sendet, und die Rolle, die AWS CloudFormation beim Senden von Protokolleinträgen an diese Protokolle übernehmen soll.

Fakturierung

Wenn ein Makro ausgeführt wird, werden dem Besitzer der Lambda-Funktion alle mit der Ausführung dieser Funktion verbundenen Kosten in Rechnung gestellt.

Die Transformationen AWS::Serverless-Transformation und AWS::Include-Transformation sind Makros, die von AWS CloudFormation gehostet werden. Ihre Nutzung ist kostenlos.

Überlegungen zur Erstellung von AWS CloudFormation-Makrodefinitionen

Beachten Sie bei der Erstellung von Makrodefinitionen Folgendes:

• Makros werden nur in AWS-Regionen unterstützt, in denen AWS Lambda verfügbar ist. Die Liste der Regionen, in denen Lambda verfügbar ist, finden Sie unter http://docs.aws.amazon.com/general/latest/gr/rande.html#lambda_region.

• Alle verarbeiteten Vorlagenausschnitte müssen gültiges -JSON sein.

• Alle verarbeiteten Vorlagenausschnitte müssen Validierungsprüfungen für eine Stack-Erstellung, Stack-Aktualisierung, Stack-Set-Erstellung oder einen Stack-Set-Aktualisierungs-Vorgang durchlaufen.

• AWS CloudFormation löst zuerst die Makros auf und verarbeitet dann die Vorlage. Die resultierende Vorlage muss gültiger JSON-Code sein und darf nicht größer als das Vorlagengrößenlimit sein.

• Aufgrund der Reihenfolge, in der CloudFormation Elemente in einer Vorlage verarbeitet, kann ein Makro keine Module in den verarbeiteten Vorlageninhalt aufnehmen, den es an CloudFormation zurückgibt. Weitere Informationen zu Modulen finden Sie unter Entwickeln von Modulen im CloudFormation-CLI-Benutzerhandbuch.

• Wenn Sie die Aktualisierungs-Rollback-Funktion nutzen, verwendet AWS CloudFormation eine Kopie der ursprünglichen Vorlage. Es wird ein Rollback auf die ursprüngliche Vorlage ausgeführt, selbst wenn der Codeausschnitt geändert wurde.

• Die Einbindung von Makros in Makros funktioniert nicht, da wir Makros nicht iterativ verarbeiten.

• Die intrinsische Fn::ImportValue-Funktion wird derzeit in Makros nicht unterstützt.

• Die in der Vorlage enthaltenen intrinsischen Funktionen werden nach allen Makros ausgewertet. Daher können die von Ihrem Makro zurückgegebenen verarbeiteten Vorlageninhalte Aufrufe von intrinsischen Funktionen beinhalten, die wie gewohnt ausgewertet werden.

• StackSets unterstützt derzeit nicht das Erstellen oder Aktualisieren von Stack-Sets mit serviceverwalteten Berechtigungen aus Vorlagen, die auf AWS CloudFormation-Makros verweisen.

• Wenn Ihre Stack-Set-Vorlage auf ein oder mehrere Makros verweist, müssen Sie das Stack-Set direkt aus der verarbeiteten Vorlage erstellen oder aktualisieren, ohne vorher die resultierenden Änderungen in einem Änderungssatz zu überprüfen. Um das Stack-Set direkt zu erstellen oder zu aktualisieren, verwenden Sie die Aktion CreateStackSet oder UpdateStackSet und geben Sie die CAPABILITY_AUTO_EXPAND-Funktion an. Verarbeitungsmakros können mehrere Ressourcen hinzufügen, die Ihnen möglicherweise nicht bekannt sind. Bevor Sie einen Stack-Set aus einer Vorlage erstellen oder aktualisieren, die direkt auf Makros verweist, sollten Sie sicherstellen, dass Sie wissen, welche Verarbeitung die Makros ausführen.

• Änderungssätze unterstützen derzeit keine verschachtelten Stacks. Wenn Sie einen Stack mit einer Vorlage erstellen oder aktualisieren möchten, die auf Makros verweist und verschachtelte Stacks enthält, müssen Sie den Stack direkt erstellen oder aktualisieren. Verwenden Sie dazu die Aktion CreateStack oder UpdateStack und geben Sie die CAPABILITY_AUTO_EXPAND-Funktion an.

So erstellen Sie eine AWS CloudFormation-Makrodefinition:

1. Erstellen Sie eine AWS Lambda-Funktion, die AWS CloudFormation-Vorlagen verarbeitet.

   Die von Ihnen erstellte Lambda-Funktion übernimmt die Verarbeitung der Vorlageninhalte. Ihre Funktion kann jeden Teil einer Vorlage bis hin zur gesamten Vorlage bearbeiten. Informationen über die Ereigniszuordnung, an die sich Ihre Funktion halten muss, finden Sie unter AWS CloudFormation-Makro-Funktionsschnittstelle. Informationen zu weiteren Überlegungen bei der Erstellung von Makros finden Sie unter Überlegungen zur Erstellung von AWS CloudFormation-Makrodefinitionen.

2. Erstellen Sie eine Vorlage mit einem Ressourcentyp AWS::CloudFormation::Macro.

   • Sie müssen die Eigenschaften Name und FunctionName angeben. Die Eigenschaft FunctionName gibt den ARN der Lambda-Funktion an, die aufgerufen wird, wenn AWS CloudFormation das Makro ausführt.

   • Um das Debugging zu erleichtern, können Sie zusätzlich die Eigenschaften LogGroupName und LogRoleArn angeben.

3. Erstellen Sie einen Stack aus der Vorlage, die das Makro im gewünschten Konto enthält, oder erstellen Sie ein Stack-Set mit selbstverwalteten Berechtigungen aus der Vorlage, die auf das Makro im Administratorkonto verweist, und erstellen Sie dann Stack-Instances in den gewünschten Zielkonten.

   Nachdem AWS CloudFormation Stacks, der die Makrodefinition enthält, erfolgreich erstellt hat, ist das Makro für die Verwendung innerhalb dieser Kontos verfügbar.

Verwendung von AWS CloudFormation-Makros in Ihren Vorlagen

Nachdem AWS CloudFormation die Stacks, der die Makrodefinition enthält, erfolgreich erstellt hat, ist das Makro für die Verwendung innerhalb dieses Kontos verfügbar. Sie verwenden ein Makro, indem Sie es in einer Vorlage an der Stelle referenzieren, die für die zu bearbeitenden Vorlageninhalte relevant ist.

AWS CloudFormation-Makro-Auswertungsreihenfolge

Sie können mehrere Makros in einer bestimmten Vorlage referenzieren, einschließlich Transformationen, die von AWS CloudFormation gehostet werden, wie beispielsweise AWS::Include-Transformation und AWS::Serverless-Transformation.

Makros werden so ausgewertet, dass sie aufgrund ihrer Position in der Vorlage von den am tiefsten verschachtelten nach außen bis zu den allgemeinsten reichen. Makros an derselben Stelle in der Vorlage werden seriell anhand der Reihenfolge, in der sie aufgelistet sind, ausgewertet.

Transformationen wie AWS::Include und AWS::Transform werden in Bezug auf die Reihenfolge und den Anwendungsbereich wie alle anderen Makros behandelt.

In dem untenstehenden Vorlagenbeispiel wertet AWS CloudFormation beispielsweise zuerst das Makro PolicyAdder aus, da es das am tiefsten verschachtelte Makro in der Vorlage ist. AWS CloudFormation wertet dann MyMacro vor AWS::Serverless aus, da es im Abschnitt AWS::Serverless vor Transform aufgeführt ist.

AWSTemplateFormatVersion: 2010-09-09
 Transform: [MyMacro, AWS::Serverless]
 Resources:
    WaitCondition:
      Type: AWS::CloudFormation::WaitCondition
    MyBucket:
      Type: 'AWS::S3::Bucket'
      Properties:
        BucketName: MyBucket
        Tags: [{"key":"value"}]
        'Fn::Transform':
          - Name: PolicyAdder
        CorsConfiguration:[]
    MyEc2Instance:
      Type: 'AWS::EC2::Instance'
      Properties:
        ImageID: "ami-123"

AWS CloudFormation-Makrobereich

Makros, die im Abschnitt Transform einer Vorlage referenziert werden, können den gesamten Inhalt dieser Vorlage verarbeiten.

Makros, die in einer Fn::Transform-Funktion referenziert werden, können den Inhalt eines beliebigen der Geschwisterelemente (einschließlich untergeordneter) der Fn::Transform-Funktion in der Vorlage verarbeiten.

Beispielsweise kann AWS::Include im untenstehenden Vorlagenbeispiel die MyBucket-Eigenschaften verarbeiten, basierend auf der Position der Fn::Transform-Funktion, die sie enthält. MyMacro kann den Inhalt der gesamten Vorlage verarbeiten, da sie in den Abschnitt Transform aufgenommen wurde.

// Start of processable content for MyMacro
AWSTemplateFormatVersion: 2010-09-09 
 Transform: [MyMacro]
 Resources:
    WaitCondition:
      Type: AWS::CloudFormation::WaitCondition
    MyBucket:
      Type: 'AWS::S3::Bucket'  //Start of processable content for AWS::Include
      Properties:
        BucketName: MyBucket 
        Tags: [{"key":"value"}] 
        'Fn::Transform':
          - Name: 'AWS::Include'
              Parameters:
                Location: s3://MyAmazonS3BucketName/MyFileName.yaml
        CorsConfiguration:[]   //End of processable content for AWS::Include
    MyEc2Instance:
      Type: 'AWS::EC2::Instance' 
      Properties:
        ImageID: "ami-123"
// End of processable content for MyMacro         

Änderungssätze und AWS CloudFormation-Makros

Um einen Stack mit einer Vorlage zu erstellen oder zu aktualisieren, die auf Makros verweist, erstellen Sie normalerweise einen Änderungssatz und führen ihn dann aus. Ein Änderungssatz beschreibt die Aktionen, die CloudFormation basierend auf der verarbeiteten Vorlage ausführen wird. Verarbeitungsmakros können mehrere Ressourcen hinzufügen, die Ihnen möglicherweise nicht bekannt sind. Um sicherzustellen, dass Sie alle Änderungen kennen, die durch Makros eingeführt werden, wird dringend die Verwendung von Änderungssätzen empfohlen. Nachdem Sie den Änderungssatz überprüft haben, können Sie ihn ausführen, um die Änderungen tatsächlich anzuwenden.

Ein Makro kann Ihrer Vorlage IAM-Ressourcen hinzufügen. Für diese Ressourcen erfordert AWS CloudFormation, dass Sie ihre Funktionen angeben. Da AWS CloudFormation nicht wissen kann, welche Ressourcen vor der Bearbeitung Ihrer Vorlage hinzugefügt werden, müssen Sie möglicherweise beim Erstellen des Änderungssatzes die IAM-Funktionen angeben, je nachdem, ob die referenzierten Makros IAM-Ressourcen enthalten. Auf diese Weise hat AWS CloudFormation bei der Ausführung des Änderungssatzes die notwendigen Funktionen, um IAM-Ressourcen zu erstellen.

Wichtig

Wenn Ihre Stack-Set-Vorlage auf ein oder mehrere Makros verweist, müssen Sie das Stack-Set direkt aus der verarbeiteten Vorlage erstellen, ohne vorher die resultierenden Änderungen in einem Änderungssatz zu überprüfen. Um das Stack-Set direkt zu erstellen oder zu aktualisieren, müssen Sie die Aktion CreateStackSet oder UpdateStackSet verwenden und die CAPABILITY_AUTO_EXPAND-Funktion angeben. Bevor Sie einen Stack-Set aus einer Vorlage erstellen oder aktualisieren, die direkt auf Makros verweist, sollten Sie sicherstellen, dass Sie wissen, welche Verarbeitung die Makros ausführen.

Anmerkung

Wenn Ihnen die direkte Erstellung oder Aktualisierung eines Stacks von einer verarbeiteten Vorlage geläufig ist und Sie die vorgeschlagenen Änderungen nicht vorher in einem Änderungssatz überprüfen müssen, können Sie während einer CreateStack- oder UpdateStack-Anforderung die CAPABILITY_AUTO_EXPAND-Funktion angeben. Sie sollten Stacks nur dann direkt von einer Stack-Vorlage mit Makros erstellen, wenn Sie wissen, welche Verarbeitungsschritte das Makro ausführt. Sie können Änderungssätze nicht mit Stack-Set-Makros verwenden; Sie müssen Ihr Stack-Set direkt aktualisieren.

Weitere Informationen finden Sie unter CreateStack oder UpdateStack im AWS CloudFormation API Reference.

Wenn Sie die AWS CLI verwenden, können Sie mit den Befehlen package und deploy die Anzahl der Schritte zum Starten von Stacks aus Vorlagen, die auf Makros verweisen, reduzieren. Weitere Informationen finden Sie unter Deploying Lambda-based Applications im AWS Lambda Developer Guide.

Vorlagenphase und CloudFormation-Makros

Die Stufe einer Vorlage gibt an, ob es sich bei der Vorlage um die ursprünglich vom Benutzer übermittelte Vorlage handelt oder um eine, in der AWS CloudFormation die Makros verarbeitet hat.

• Original: Die Vorlage, die der Benutzer ursprünglich zur Erstellung oder Aktualisierung des Stacks oder Stack-Sets übermittelt hat.

• Processed: Die Vorlage , die AWS CloudFormation nach der Verarbeitung aller referenzierten Makros zur Erstellung oder Aktualisierung des Stacks oder Stack-Sets erstellt hat. Die verarbeitete Vorlage wird als JSON formatiert, auch wenn die ursprüngliche Vorlage als YAML formatiert wurde.

Verwenden Sie die verarbeitete Vorlage, um Stack-Probleme zu beheben. Wenn eine Vorlage keine Makros referenziert, sind die ursprünglichen und verarbeiteten Vorlagen identisch.

Die Phase, in der sich eine Stack-Vorlage befindet, können Sie über die AWS CloudFormation-Konsole oder die AWS CLI abrufen.

Anmerkung

Die maximale Größe für eine verarbeitete Stack-Vorlage beträgt 51.200 Byte, falls sie direkt an eine CreateStack-, UpdateStack- oder ValidateTemplate-Anforderung übergeben wird, oder 460.800 Byte, wenn sie unter Verwendung einer Amazon S3-Vorlagen-URL als S3-Objekt übergeben wird. Bei der Verarbeitung wird der vorübergehende Status der Vorlage jedoch von CloudFormation aktualisiert, während die Makros in der Vorlage nacheinander verarbeitet werden. Daher kann die Vorlage während der Verarbeitung die für eine vollständig verarbeitete Vorlage zulässige Größe zeitweise überschreiten. CloudFormation räumt diesen in Verarbeitung befindlichen Vorlagen jedoch einen gewissen Spielraum ein. Allerdings sollten Sie beim Entwurf Ihrer Vorlagen und Makros immer die maximal zulässige Größe für eine verarbeitete Stack-Vorlage im Blick behalten.

Wenn CloudFormation bei der Verarbeitung der Vorlage einen Transformation data limit exceeded-Fehler zurückgibt, hat Ihre Vorlage die maximale Größe überschritten, die CloudFormation während der Verarbeitung zulässt.

Sie können das Problem u. U. wie folgt beheben:

• Teilen Sie Ihre Vorlage in mehrere Vorlagen auf, um zu vermeiden, dass die maximale Vorlagengröße während der Verarbeitung überschritten wird. Beispiel:

  • Verwenden Sie verschachtelte Stack-Vorlagen, um Teile der Vorlage einzukapseln. Weitere Informationen finden Sie unter Arbeiten mit verschachtelten Stacks.

  • Erstellen Sie mehrere Stacks und verwenden Sie Stack-übergreifende Referenzen, damit Informationen zwischen den Stacks ausgetauscht werden können. Weitere Informationen finden Sie unter Walkthrough: Verweisen auf Ressourcenausgaben in einem anderen AWS CloudFormation-Stack.

• Reduzieren Sie die Größe des von einem bestimmten Makro zurückgegebenen Vorlagenfragments. CloudFormation manipuliert den Inhalt von Fragmenten, die von Makros zurückgegeben werden, nicht.

So verwenden Sie ein AWS CloudFormation-Makro in Ihrer Vorlage

Anmerkung

Damit AWS CloudFormation ein in einer Vorlage referenziertes Makro erfolgreich ausführen kann, muss der Benutzer über Invoke-Berechtigungen für die zugrundeliegende Lambda-Funktion verfügen. Weitere Informationen finden Sie unter Übersicht über die Verwaltung von Zugriffsberechtigungen für Ihre AWS Lambda-Ressourcen in der AWS Lambda Developer Guide.

1. Fügen Sie eine Referenz auf das Makro in die Vorlage ein.

   • Um ein Vorlagenausschnitt zu bearbeiten, referenzieren Sie das Makro in einer Fn::Transform-Funktion, die sich relativ zu dem zu bearbeitenden Vorlageninhalt befindet.

   • Um die gesamte Vorlage zu bearbeiten, referenzieren Sie das Makro im Abschnitt Transform der Vorlage.

2. Erstellen Sie einen Änderungssatz anhand der Vorlage.

   Wichtig

   Wenn Ihre Stack-Set-Vorlage auf ein oder mehrere Makros verweist, müssen Sie das Stack-Set direkt aus der verarbeiteten Vorlage erstellen, ohne vorher die resultierenden Änderungen in einem Änderungssatz zu überprüfen. Um das Stack-Set direkt zu erstellen oder zu aktualisieren, müssen Sie die Aktion CreateStackSet oder UpdateStackSet verwenden und die CAPABILITY_AUTO_EXPAND-Funktion angeben. Bevor Sie einen Stack-Set aus einer Vorlage erstellen oder aktualisieren, die direkt auf Makros verweist, sollten Sie sicherstellen, dass Sie wissen, welche Verarbeitung die Makros ausführen.

3. Überprüfen Sie den Änderungssatz und führen Sie ihn aus.

   Wichtig

   Wenn Ihre Stack-Set-Vorlage auf ein oder mehrere Makros verweist, müssen Sie das Stack-Set direkt aus der verarbeiteten Vorlage erstellen, ohne vorher die resultierenden Änderungen in einem Änderungssatz zu überprüfen. Um das Stack-Set direkt zu erstellen oder zu aktualisieren, müssen Sie die Aktion CreateStackSet oder UpdateStackSet verwenden und die CAPABILITY_AUTO_EXPAND-Funktion angeben. Bevor Sie einen Stack-Set aus einer Vorlage erstellen oder aktualisieren, die direkt auf Makros verweist, sollten Sie sicherstellen, dass Sie wissen, welche Verarbeitung die Makros ausführen.

Makrobeispiele

Zusätzlich zum Walkthrough für Makrobeispiel: Erstellen und Verwenden eines Makros in diesem Handbuch finden Sie im Abschnitt Makrobeispiele des Amazon Web Services - Labs-Repositorys auf GitHub Beispielmakros, einschließlich Quellcode und Vorlagen. Diese Beispiele werden "wie besehen" für Schulungszwecke zur Verfügung gestellt.

Weitere Informationen finden Sie auch unter

AWS::CloudFormation::Macro

Transform

Fn::Transform

AWS::Serverless-Transformation

AWS::Include-Transformation