Verwenden von AWS CloudFormation Makros zur benutzerdefinierten Verarbeitung von Vorlagen

Makros ermöglichen es Ihnen, eine benutzerdefinierte Verarbeitung von Vorlagen durchzuführen, von einfachen Aktionen wie find-and-replace Operationen bis hin zu umfangreichen Transformationen ganzer Vorlagen.

Um sich ein Bild von der Bandbreite der Möglichkeiten zu machen, sollten Sie die AWS::Serverless Transformationen AWS::Include und in Betracht ziehen, bei denen es sich um Makros handelt, die von gehostet werden AWS CloudFormation:

• 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 Serverless-Anwendungen und AWS SAM finden Sie unter Bereitstellen von Lambda-basierten Anwendungen im Benutzerhandbuch fürAWS Lambda .)

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 Vorlagenverarbeitung. 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 Benutzern ermöglicht, die Lambda-Funktion aus 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 innerhalb eines Kontos zu erstellen, erstellen Sie eine Vorlage, die eine -AWS::CloudFormation::MacroRessource enthält, und erstellen Sie dann entweder einen Stack oder ein Stack-Set mit selbstverwalteten 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. (Durch die Verarbeitung von Makros können mehrere Ressourcen hinzugefügt werden, 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, AWS CloudFormation generiert einen Änderungssatz, der den verarbeiteten 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 UpdateStackSet Aktion CreateStackSet oder 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.

Weitere Informationen finden Sie unter CreateStack oder UpdateStack in der APIAWS CloudFormation -Referenz zu .

Erstellen einer - AWS CloudFormation Makrodefinition

Wenn Sie eine Makrodefinition erstellen, stellt die Makrodefinition die zugrunde liegende Lambda-Funktion im angegebenen Konto zur Verfügung, sodass sie zur Verarbeitung der Vorlagen AWS CloudFormation aufruft.

AWS CloudFormation -Makro-Funktionsschnittstelle

Bei Makros AWS CloudFormation ruft die zugrunde liegenden 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 werten alle angegebenen Parameter für die Funktion aus. 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 zugrunde liegende Funktion eine Antwort im folgenden JSON-Format zurückgibt:

{
    "requestId" : "$REQUEST_ID",
    "status" : "$STATUS",
    "fragment" : { ... }
    "errorMessage": "optional error message for failures"
}

• requestId

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

• status

  Der Status der Anforderung (Groß- und 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 , der in die verarbeitete Vorlage aufgenommen werden AWS CloudFormation 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 an sie übergibt, AWS CloudFormation nicht ändert, Sie diesen Inhalt aber trotzdem in die verarbeitete Vorlage aufnehmen müssen, muss Ihre Funktion diesen Vorlageninhalt an AWS CloudFormation in ihrer Antwort 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: Transformation der AWS-Konto -Kontonummer::Makroname ist fehlgeschlagen mit: Fehlermeldungs-Zeichenfolge“.

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

AWS CloudFormation Umfang und Berechtigungen des -Makrokontos

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 im AWS Lambda -Entwicklerhandbuch.

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

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

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

Debuggen von AWS CloudFormation Makros

Um das Debuggen zu erleichtern, können Sie beim Anlegen des Ressourcentyps LogGroupName für Ihr Makro auch die Eigenschaften LogRoleArn und AWS::CloudFormation::Macro angeben. Mit diesen Eigenschaften können Sie die CloudWatch Protokollgruppe angeben, an die Fehlerprotokollierungsinformationen AWS CloudFormation sendet, wenn die dem Makro zugrunde liegende AWS Lambda Funktion aufgerufen wird, und die Rolle AWS CloudFormation sollte beim Senden von Protokolleinträgen an diese Protokolle übernehmen.

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 AWS::Include-Transformation Transformationen AWS::Serverless-Transformation und sind Makros, die von gehostet werden AWS CloudFormation. Ihre Nutzung ist kostenlos.

Überlegungen beim Erstellen von AWS CloudFormation Makrodefinitionen

Beachten Sie bei der Erstellung von Makrodefinitionen Folgendes:

• Makros werden nur in unterstützt, in AWS-Regionen denen verfügbar AWS Lambda ist. Eine Liste der Regionen, in denen Lambda verfügbar ist, finden Sie unter AWS Lambda Endpunkte und Kontingente.

• 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 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 Elemente in einer Vorlage CloudFormation verarbeitet, kann ein Makro keine Module in den verarbeiteten Vorlageninhalt aufnehmen, den es an zurückgibt CloudFormation. Weitere Informationen zu Modulen finden Sie unter Entwickeln von Modulen im CloudFormation CLI-Benutzerhandbuch.

• Bei Verwendung der Update-Rollback-Funktion AWS CloudFormation verwendet 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 UpdateStackSet Aktion CreateStackSet oder 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 UpdateStack Aktion CreateStack oder 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 beim Erstellen von AWS CloudFormation Makrodefinitionen.

2. Erstellen Sie eine Vorlage mit einem -AWS::CloudFormation::MacroRessourcentyp.

   • Sie müssen die Eigenschaften Name und FunctionName angeben. Die -FunctionNameEigenschaft gibt den ARN der Lambda-Funktion an, die aufgerufen werden soll, wenn das Makro AWS CloudFormation 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 erfolgreich Stacks erstellt AWS CloudFormation hat, die die Makrodefinition enthalten, ist das Makro für die Verwendung innerhalb dieser Konten verfügbar.

Verwenden von AWS CloudFormation Makros in Ihren Vorlagen

Nachdem die Stacks, die die Makrodefinition enthalten, erfolgreich erstellt AWS CloudFormation hat, ist das Makro für die Verwendung innerhalb dieser Konten 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-Bewertungsreihenfolge

Sie können auf mehrere Makros in einer bestimmten Vorlage verweisen, einschließlich Transformationen, die von gehostet werden AWS CloudFormation, wie z. B. 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.

Im folgenden Vorlagenbeispiel AWS CloudFormation wertet beispielsweise zuerst das PolicyAdder Makro aus, da es das am tiefsten verschachtelte Makro in der template ist. AWS CloudFormation wertet MyMacro vor aus, AWS::Serverless da es AWS::Serverless im Transform Abschnitt vor 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://DOC-EXAMPLE-BUCKET/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 nicht wissen AWS CloudFormation kann, welche Ressourcen vor der Verarbeitung Ihrer Vorlage hinzugefügt werden, müssen Sie beim Erstellen des Änderungssatzes möglicherweise die IAM-Funktionen bestätigen, je nachdem, ob die referenzierten Makros IAM-Ressourcen enthalten. Auf diese Weise AWS CloudFormation verfügt beim Ausführen des Änderungssatzes über die erforderlichen Funktionen zum Erstellen von IAM-Ressourcen.

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 UpdateStackSet Aktion CreateStackSet oder 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 in der APIAWS CloudFormation -Referenz zu .

Wenn Sie die verwenden AWS CLI, können Sie die deploy Befehle package und verwenden, um die Anzahl der Schritte zum Starten von Stacks aus Vorlagen zu reduzieren, die auf Makros verweisen. Weitere Informationen finden Sie unter Bereitstellen Lambda-basierter Anwendungen im Entwicklerhandbuch fürAWS Lambda .

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 die Makros verarbeitet AWS CloudFormation hat.

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

• Processed: Die Vorlage, die zum Erstellen oder Aktualisieren des Stacks oder Stack-Sets AWS CloudFormation verwendet wird, nachdem alle referenzierten Makros verarbeitet wurden. 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.

Sie können die AWS CloudFormation -Konsole oder verwendenAWS CLI, um die Phase einer Stack-Vorlage anzuzeigen.

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 1 MB, wenn sie unter Verwendung einer Amazon-S3-Vorlagen-URL als S3-Objekt übergeben wird. Während der Verarbeitung CloudFormation aktualisiert jedoch den temporären Status der Vorlage, während sie die in der Vorlage enthaltenen Makros seriell verarbeitet. Aus diesem Grund kann die Größe der Vorlage während der Verarbeitung vorübergehend die zulässige Größe einer vollständig verarbeiteten Vorlage überschreiten. CloudFormation erlaubt einen gewissen Puffer für diese In-Process-Vorlagen. 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 bei der Verarbeitung Ihrer Vorlage einen Transformation data limit exceeded Fehler CloudFormation zurückgibt, hat Ihre Vorlage die maximal CloudFormation zulässige Vorlagengröße während der Verarbeitung überschritten.

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 Vorlagenfragments, das von einem bestimmten Makro zurückgegeben wird. 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 ein in einer Vorlage referenziertes Makro erfolgreich ausführen AWS CloudFormation kann, muss der Benutzer über Invoke Berechtigungen für die zugrunde liegende Lambda-Funktion verfügen. Weitere Informationen finden Sie unter Übersicht über die Verwaltung von Zugriffsberechtigungen für Ihre AWS Lambda-Ressourcen im AWS Lambda -Entwicklerhandbuch.

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 UpdateStackSet Aktion CreateStackSet oder 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 UpdateStackSet Aktion CreateStackSet oder 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 zur Makrobeispiel: Erstellen und Verwenden eines Makros Anleitung in diesem Handbuch finden Sie Beispielmakros, einschließlich Quellcode und Vorlagen, im Abschnitt Makrobeispiele des Amazon Web Services - Labs-Repo auf GitHub. 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