Erstellen Sie eine CloudFormation Makrodefinition

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.

Zuordnung von Ereignissen

Wenn die Lambda-Funktion eines Makros CloudFormation aufgerufen wird, sendet es eine Anfrage in einem 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 verfügbar ist, 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 Geltungsbereich der Makrovorlage.

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

• status

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

• fragment

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

  Der verarbeitete Vorlageninhalt muss gültig seinJSON, und seine Aufnahme in die verarbeitete Vorlage muss zu einer gültigen Vorlage führen.

  Wenn Ihre Funktion den Vorlageninhalt, den 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 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.

  Beispielsweise:

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

Erstellen Sie eine Makrodefinition

Um eine CloudFormation Makrodefinition zu erstellen

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

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

3. (Optional) Um das Debuggen zu erleichtern, können Sie auch die LogRoleArn Eigenschaften LogGroupName und angeben, wenn Sie den AWS::CloudFormation::Macro Ressourcentyp für Ihr Makro erstellen. Mit diesen Eigenschaften können Sie die Protokollgruppe CloudWatch Logs angeben, an die Fehlerprotokollierungsinformationen CloudFormation gesendet werden, wenn die dem Makro zugrunde liegende Lambda-Funktion aufgerufen wird, und die Rolle CloudFormation sollte beim Senden von Logeinträgen an diese Logs übernommen werden.

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

5. Nachdem CloudFormation die Stacks, 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.

Geltungsbereich der Makrovorlage

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

Reihenfolge der Makro-Evaluierung

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