Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Führen Sie eine benutzerdefinierte Verarbeitung von CloudFormation Vorlagen mit Vorlagenmakros durch

Mit Makros können Sie benutzerdefinierte Verarbeitungsvorgänge für Vorlagen durchfü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 sich die AWS::Serverless Transformationen AWS::Include und die Transformationen ansehen. Dabei handelt es sich um Makros, die von folgenden Anbietern bereitgestellt werden: CloudFormation

Wie funktionieren Makros 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:

Um ein Makro zu verwenden, referenzieren Sie das Makro in Ihrer 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.) 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.

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.

Eine 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 CloudFormation aufgerufen wird.

CloudFormation Schnittstelle für Makrofunktionen

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

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

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"
}

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

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 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.

CloudFormation Um ein in einer Vorlage enthaltenes Makro erfolgreich ausführen 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 CloudFormation Ausführung des Makros die Identität des Benutzers aus. Weitere Informationen finden Sie unter Lambda-Berechtigungsmodell im AWS Lambda Entwicklerhandbuch und Aktionen und Bedingungskontextschlüssel für AWS Lambda im IAMBenutzerhandbuch.

Die AWS::Include-Transformation Transformationen AWS::Serverless-Transformation und sind Makros, die von gehostet werden. CloudFormation Für ihre Verwendung sind keine besonderen Berechtigungen erforderlich, und sie sind von jedem Konto in aus verfügbar. CloudFormation

Makros debuggen CloudFormation

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 Informationen zur Fehlerprotokollierung CloudFormation gesendet werden, wenn die dem Makro zugrunde liegende AWS Lambda Funktion aufgerufen wird, und die Rolle 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. CloudFormation Ihre Nutzung ist kostenlos.

Überlegungen zur Erstellung von CloudFormation -Makrodefinitionen

Beachten Sie bei der Erstellung von Makrodefinitionen Folgendes:

Verwenden von CloudFormation Makros in Ihren Vorlagen

Nachdem 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.

CloudFormation Reihenfolge der Makro-Evaluierung

Sie können in einer bestimmten Vorlage auf mehrere Makros verweisen, einschließlich Transformationen, die von bereitgestellt werden 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 CloudFormation ausgewertet, da es sich dabei um das am tiefsten verschachtelte Makro in der Vorlage handelt. 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: amzn-s3-demo-bucket
        Tags: [{"key":"value"}]
        'Fn::Transform':
          - Name: PolicyAdder
        CorsConfiguration: []
    MyEc2Instance:
      Type: 'AWS::EC2::Instance'
      Properties:
        ImageID: ami-1234567890abcdef0

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: amzn-s3-demo-bucket1
        Tags: [{"key":"value"}] 
        'Fn::Transform':
          - Name: 'AWS::Include'
              Parameters:
                Location: s3://amzn-s3-demo-bucket2/MyFileName.yaml
        CorsConfiguration: []
        # End of processable content for AWS::Include
    MyEc2Instance:
      Type: 'AWS::EC2::Instance' 
      Properties:
        ImageID: ami-1234567890abcdef0
# End of processable content for MyMacro

Änderungssätze und 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, 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 CloudFormation müssen Sie deren Fähigkeiten anerkennen. Da Sie vor der Verarbeitung Ihrer Vorlage nicht wissen CloudFormation können, welche Ressourcen hinzugefügt wurden, müssen Sie möglicherweise bei der Erstellung des Änderungssatzes die IAM Funktionen bestätigen, je nachdem, ob die referenzierten Makros IAM Ressourcen enthalten. Wenn Sie den Änderungssatz ausführen, CloudFormation verfügt er auf diese Weise über die erforderlichen Funktionen, um IAM Ressourcen zu erstellen.

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, die auf Makros verweisen, zu reduzieren. 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 CloudFormation verarbeitet wurden.

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 CloudFormation Konsole verwenden oder AWS CLIum den Status einer Stack-Vorlage zu sehen.

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::: Makro CloudFormation

Transform Abschnitt für CloudFormation Vorlagen

Fn::Transform

AWS::Serverless-Transformation

AWS::Include-Transformation