Erstellen Sie eine CloudFormation-Makrodefinition - AWS CloudFormation
Ereignis-MappingReaktionsformatErstellen Sie eine MakrodefinitionUmfang der Makro-VorlageMakro-Bewertungsreihenfolge

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.

Erstellen Sie eine CloudFormation-Makrodefinition

Wenn Sie eine Makrodefinition erstellen, macht die Makrodefinition die zugrunde liegende Lambda-Funktion im angegebenen Konto verfügbar, so dass CloudFormation sie zur Verarbeitung der Vorlagen aufruft.

Ereignis-Mapping

Wenn CloudFormation die Lambda-Funktion eines Makros aufruft, sendet es eine Anfrage im JSON-Format mit der folgenden Struktur:

{
    "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 Umfang der Makro-Vorlage.

  • transformId

    Der Name des Makros, das diese Funktion aufruft.

  • params

    Bei Fn::Transform-Funktionsaufrufen alle angegebenen Parameter für die Funktion. 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 im Abschnitt Parameters der Vorlage angegebenen Parameter. CloudFormation wertet diese Parameter aus, bevor sie an die Funktion übergeben werden.

Reaktionsformat

CloudFormation erwartet, dass die Lambda-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 Anfrage-ID übereinstimmen, die von CloudFormation beim Aufruf der Funktion angegeben wurde.

  • status

    Der Status der Anforderung (Groß- und Kleinschreibung wird nicht berücksichtigt). Sollte auf successgesetzt werden. Jede andere Antwort wird von CloudFormation als Fehlschlag behandelt.

  • fragment

    Der verarbeitete Vorlageninhalt, den CloudFormation in die verarbeitete Vorlage aufnehmen soll, einschließlich Geschwister. 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 Inhalt der Vorlage, den CloudFormation an sie weitergibt, nicht wirklich ändert, Sie diesen Inhalt aber dennoch in die verarbeitete Vorlage aufnehmen müssen, muss Ihre Funktion diesen Vorlageninhalt in ihrer Antwort an CloudFormation zurückgeben.

  • errorMessage

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

    Zum Beispiel:

    Error creating change set: Transform
                            AWS-Konto account
                            number::macro name failed with:
                            error message string.

Erstellen Sie eine Makrodefinition

So erstellen Sie eine CloudFormation-Makrodefinition

  1. Erstellen Sie eine Lambda-Funktion die die Verarbeitung der Vorlageninhalte übernimmt. Es kann jeden Teil einer Vorlage verarbeiten, bis hin zur gesamten Vorlage.

  2. Erstellen Sie eine CloudFormation-Vorlage, die einen Ressourcentyp AWS::CloudFormation::Macro enthält, und geben Sie die Eigenschaften Name und FunctionName an. Die Eigenschaft FunctionName muss den ARN der Lambda-Funktion enthalten, die aufgerufen werden soll, wenn CloudFormation das Makro ausführt.

  3. (Optional) Um die Fehlersuche zu erleichtern, können Sie beim Erstellen des Ressourcentyps AWS::CloudFormation::Macro für Ihr Makro auch die Eigenschaften LogGroupName und LogRoleArn angeben. Mit diesen Eigenschaften können Sie die CloudWatch Logs-Protokollgruppe angeben, an die CloudFormation beim Aufruf der dem Makro zugrundeliegenden Lambda-Funktion Informationen zur Fehlerprotokollierung sendet, sowie die Rolle, die CloudFormation beim Senden von Protokolleinträgen an diese Protokolle übernehmen soll.

  4. Erstellen Sie einen Stapel unter Verwendung der Vorlage mit dem Makro in dem Konto, in dem Sie es verwenden möchten. Oder erstellen Sie ein Stack-Set mit selbstverwalteten Berechtigungen unter Verwendung der Vorlage mit dem Makro im Administratorkonto und erstellen Sie dann Stack-Instances in den Zielkonten.

  5. Nachdem CloudFormation die Stapel, die die Makrodefinition enthalten, erfolgreich erstellt 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.

Umfang der Makro-Vorlage

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

Makro-Bewertungsreihenfolge

Sie können mehrere Makros in einer bestimmten Vorlage referenzieren, einschließlich der von CloudFormation gehosteten Transformationen, wie AWS::Include und AWS::Serverless.

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 Beispiel der Vorlage unten wertet CloudFormation zum Beispiel das Makro PolicyAdder zuerst aus, da es das am tiefsten verschachtelte Makro in der Vorlage ist. CloudFormation wertet dann MyMacro vor AWS::Serverless aus, weil es vor AWS::Serverless im Abschnitt 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: amzn-s3-demo-bucket
        Tags: [{"key":"value"}]
        'Fn::Transform':
          - Name: PolicyAdder
        CorsConfiguration: []
    MyEc2Instance:
      Type: AWS::EC2::Instance
      Properties:
        ImageID: ami-1234567890abcdef0