Verwenden von AWS CloudFormation Makros zur benutzerdefinierten Verarbeitung von Vorlagen

Makros ermöglichen Ihnen die benutzerdefinierte Verarbeitung von Vorlagen, 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 sich die AWS::Serverless Transformationen AWS::Include und diese Makros ansehen, die von folgenden Anbietern bereitgestellt werden: AWS CloudFormation

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

• AWS::Serverless-Transformationverwendet eine gesamte Vorlage, die in der AWS SAM-Syntax ( AWS Serverless Application Model) geschrieben ist, transformiert und erweitert sie in eine konforme Vorlage. AWS CloudFormation (Weitere Informationen zu Serverless-Anwendungen und AWS SAM finden Sie unter Bereitstellen von Lambda-basierten Anwendungen im Benutzerhandbuch für AWS Lambda .)

Wie funktionieren Makros AWS CloudFormation

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 TypAWS::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 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 selbstverwalteten Berechtigungen aus der Vorlage. AWS CloudFormation StackSetsunterstützt derzeit nicht das Erstellen oder Aktualisieren von Stack-Sets mit vom Dienst verwalteten Berechtigungen anhand von 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, von denen Sie möglicherweise nichts wissen. Um sicherzustellen, dass Sie über alle durch Makros eingeführten Änderungen informiert sind, empfehlen wir Ihnen dringend, Änderungssätze zu verwenden.) AWS CloudFormation übergibt den angegebenen Vorlageninhalt zusammen mit allen zusätzlichen angegebenen Parametern an die in der Makroressource angegebene Lambda-Funktion. Die Lambda-Funktion gibt den bearbeiteten Vorlageninhalt zurück, sei es ein Ausschnitt oder eine ganze Vorlage.

AWS CloudFormation Generiert nach dem Aufruf aller Makros in der Vorlage 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 UpdateStackSetAktion CreateStackSetoder 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 CreateStackoder UpdateStackin der AWS CloudFormation API-Referenz.

Eine AWS CloudFormation Makrodefinition erstellen

Wenn Sie eine Makrodefinition erstellen, macht die Makrodefinition die zugrunde liegende Lambda-Funktion im angegebenen Konto verfügbar, sodass sie zur Verarbeitung der Vorlagen AWS CloudFormation aufgerufen wird.

AWS CloudFormation Schnittstelle für Makrofunktionen

AWS CloudFormation Ruft für Makros die zugrunde liegenden Lambda-Funktionen mit der folgenden Ereigniszuordnung auf. AWS CloudFormation sendet seine Anfrage im JSON-Format und erwartet, dass die Funktionsantwort ebenfalls im JSON-Format formatiert ist.

{
    "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 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. Dies muss mit der Anforderungs-ID übereinstimmen, die AWS CloudFormation beim Aufrufen der Funktion angegeben wurde.

• status

  Der Status der Anforderung (Groß- und Kleinschreibung wird nicht berücksichtigt). Sollte auf gesetzt sein. success AWS CloudFormation behandelt jede andere Antwort als Fehler.

• fragment

  Der Inhalt der verarbeiteten Vorlage AWS CloudFormation , der in die verarbeitete Vorlage aufgenommen werden soll, einschließlich gleichgeordneter Elemente. AWS CloudFormation ersetzt den Vorlageninhalt, der an die Lambda-Funktion übergeben wird, durch das Vorlagenfragment, das es in der Lambda-Antwort empfängt.

  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 an sie AWS CloudFormation übergebenen Vorlageninhalt nicht wirklich ändert, Sie diesen Inhalt aber dennoch in die verarbeitete Vorlage aufnehmen müssen, muss Ihre Funktion diesen Vorlageninhalt AWS CloudFormation in ihrer Antwort zurückgeben.

• errorMessage

  Die Fehlermeldung, die erklärt, warum die Transformation fehlgeschlagen ist. CloudFormationzeigt diese Fehlermeldung im Bereich Ereignisse der Seite mit den 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 zur Erstellung von AWS CloudFormation -Makrodefinitionen.

AWS CloudFormation Umfang und Berechtigungen für Makrokonten

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 im AWS Lambda Developer Guide unter Überblick über die Verwaltung von Zugriffsberechtigungen für Ihre AWS Lambda-Ressourcen.

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

Um ein in einer Vorlage enthaltenes Makro erfolgreich ausführen AWS CloudFormation zu können, muss der Benutzer über Invoke Berechtigungen für die zugrunde liegende Lambda-Funktion verfügen. Um eine mögliche Eskalation von Berechtigungen zu verhindern, gibt sich bei der AWS CloudFormation Ausführung des Makros die Identität des Benutzers aus. Weitere Informationen finden Sie unter Lambda-Berechtigungsmodell im Entwicklerhandbuch für AWS 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 CloudFormation aus verfügbar.

Makros debuggen AWS CloudFormation

Um das Debuggen zu erleichtern, können Sie auch die LogRoleArn Eigenschaften LogGroupName und angeben, wenn Sie den AWS::CloudFormation::MacroRessourcentyp für Ihr Makro erstellen. Mit diesen Eigenschaften können Sie die CloudWatch Protokollgruppe angeben, an die Informationen zur Fehlerprotokollierung AWS CloudFormation gesendet werden, wenn die dem Makro zugrunde liegende AWS Lambda Funktion aufgerufen wird, und die Rolle AWS CloudFormation soll beim Senden von Protokolleinträgen an diese Protokolle übernommen werden.

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 zur Erstellung von AWS CloudFormation -Makrodefinitionen

Beachten Sie bei der Erstellung von Makrodefinitionen Folgendes:

• Makros werden nur dort unterstützt, AWS-Regionen wo sie AWS Lambda verfügbar sind. 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 werden, kann ein Makro keine Module in den verarbeiteten Vorlageninhalt aufnehmen, zu dem es zurückkehrt. CloudFormation Weitere Informationen zu Modulen finden Sie unter Module entwickeln im CloudFormation CLI-Benutzerhandbuch.

• Wenn Sie die Update-Rollback-Funktion verwenden, AWS CloudFormation wird eine Kopie der Originalvorlage verwendet. 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 vom Service verwalteten Berechtigungen anhand von Vorlagen, die auf Makros verweisen. AWS CloudFormation

• 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 UpdateStackSetAktion CreateStackSetoder 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 UpdateStackAktion CreateStackoder und geben Sie die CAPABILITY_AUTO_EXPAND Fähigkeit 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 Schnittstelle für Makrofunktionen. Informationen zu weiteren Überlegungen bei der Erstellung von Makros finden Sie unter Überlegungen zur Erstellung von AWS CloudFormation -Makrodefinitionen.

2. Erstellen Sie eine Vorlage, die einen AWS::CloudFormation::MacroRessourcentyp enthält.

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

   • 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 erfolgreich Stacks erstellt wurden, die die Makrodefinition enthalten, ist das Makro für die Verwendung in diesen Konten verfügbar.

Verwenden von AWS CloudFormation Makros in Ihren Vorlagen

Nachdem AWS CloudFormation die Stapel, die die Makrodefinition enthalten, erfolgreich erstellt wurden, ist das Makro für die Verwendung in diesen 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 Reihenfolge der Makro-Evaluierung

Sie können in einer bestimmten Vorlage auf mehrere Makros verweisen, einschließlich Transformationen, die von bereitgestellt werden AWS CloudFormation, z. B. AWS::Include-Transformation auf 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 nachfolgenden Vorlagenbeispiel wird beispielsweise das PolicyAdder Makro zuerst AWS CloudFormation ausgewertet, da es sich dabei um das am tiefsten verschachtelte Makro in der Vorlage handelt. AWS CloudFormation führt dann MyMacro vor der Auswertung eine Auswertung durch, AWS::Serverless da es bereits im Abschnitt aufgeführt ist. AWS::Serverless Transform

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         

Sätze und AWS CloudFormation Makros ändern

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, CloudFormation die auf der Grundlage der verarbeiteten Vorlage ausgeführt werden. 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 Sie vor der Verarbeitung Ihrer Vorlage nicht wissen AWS CloudFormation können, welche Ressourcen hinzugefügt wurden, müssen Sie bei der Erstellung des Änderungssatzes möglicherweise die IAM-Funktionen bestätigen, je nachdem, ob die referenzierten Makros IAM-Ressourcen enthalten. Wenn Sie den Änderungssatz ausführen, AWS CloudFormation verfügt er auf diese Weise über die erforderlichen 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 UpdateStackSetAktion CreateStackSetoder 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 CreateStackoder UpdateStackin der AWS CloudFormation API-Referenz.

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

Vorlagenphase und CloudFormation-Makros

Die Phase einer Vorlage gibt an, ob es sich bei der Vorlage um die ursprüngliche Vorlage handelt, die vom Benutzer eingereicht wurde, oder um eine Vorlage, in der die Makros AWS CloudFormation verarbeitet wurden.

• 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 verwendet wurde, um den Stack oder das Stack-Set nach der Verarbeitung aller referenzierten Makros zu erstellen oder zu aktualisieren. 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 verwenden oder AWS CLIum den Status einer Stack-Vorlage zu sehen.

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 wird jedoch der temporäre Status der Vorlage CloudFormation aktualisiert, da die in der Vorlage enthaltenen Makros seriell verarbeitet werden. 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 ermöglicht einen gewissen Puffer für diese in Bearbeitung befindlichen 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 ein Transformation data limit exceeded Fehler CloudFormation zurückgegeben wird, hat Ihre Vorlage die maximale Vorlagengröße überschritten, die während der Verarbeitung CloudFormation zulässig ist.

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 nicht den Inhalt von Fragmenten, die von Makros zurückgegeben werden.

Um ein AWS CloudFormation Makro in Ihrer Vorlage zu verwenden

Anmerkung

Um ein Makro AWS CloudFormation , auf das in einer Vorlage verwiesen wird, erfolgreich ausführen zu können, muss der Benutzer über Invoke Berechtigungen für die zugrunde liegende Lambda-Funktion verfügen. Weitere Informationen finden Sie im AWS Lambda Developer Guide unter Überblick über die Verwaltung von Zugriffsberechtigungen für Ihre AWS Lambda-Ressourcen.

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 UpdateStackSetAktion CreateStackSetoder 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 UpdateStackSetAktion CreateStackSetoder verwenden und die CAPABILITY_AUTO_EXPAND Fähigkeit 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 exemplarischen Vorgehensweise in diesem Handbuch finden Sie in unserem GitHub Repository 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