AWS CloudFormation

Führt eine Operation für einen AWS CloudFormation-Stack aus. Bei einem Stack handelt es sich um eine Sammlung von AWS-Ressourcen, die Sie als einzelne Einheit verwalten können. Die Ressourcen in einem Stack werden durch die AWS CloudFormation-Vorlage des Stacks definiert. Ein Änderungssatz erstellt einen Vergleich, der angezeigt werden kann, ohne den ursprünglichen Stack zu ändern. Weitere Informationen zu den Arten von AWS CloudFormation-Aktionen, die für Stacks und Änderungssätze ausgeführt werden können, finden Sie unter dem ActionMode-Parameter.

CodePipeline Ruft die AWS CloudFormation DescribeStackEvents API auf, um eine Fehlermeldung für eine AWS CloudFormation Aktion zu erstellen, bei der ein Stack-Vorgang fehlgeschlagen ist. Wenn eine Aktions-IAM-Rolle berechtigt ist, auf diese API zuzugreifen, werden die Details zur ersten ausgefallenen Ressource in die CodePipeline Fehlermeldung aufgenommen. Andernfalls ignoriert die Rollenrichtlinie den Zugriff auf die API und zeigt stattdessen eine allgemeine Fehlermeldung an, CodePipeline wenn die Rollenrichtlinie nicht über die entsprechende Berechtigung verfügt. Dazu muss die cloudformation:DescribeStackEvents Berechtigung der Servicerolle oder anderen IAM-Rollen für die Pipeline hinzugefügt werden.

Wenn Sie nicht möchten, dass die Ressourcendetails in den Pipeline-Fehlermeldungen auftauchen, können Sie diese Berechtigung für die Aktions-IAM-Rolle widerrufen, indem Sie die Berechtigung entfernen. cloudformation:DescribeStackEvents

Aktionstyp

• Kategorie: Deploy

• Eigentümer: AWS

• Anbieter: CloudFormation

• Version: 1

Konfigurationsparameter

ActionMode

Erforderlich: Ja

ActionMode ist der Name der Aktion, die AWS CloudFormation auf einem Stack oder Änderungssatz ausführt. Die folgenden Aktionsmodi sind verfügbar:

• CHANGE_SET_EXECUTE führt einen Änderungssatz für den Ressourcen-Stack aus, der auf einer Reihe von angegebenen Ressourcenaktualisierungen basiert. Mit dieser Aktion beginnt AWS CloudFormation, den Stack zu ändern.

• CHANGE_SET_REPLACE erstellt den Änderungssatz, falls er noch nicht existiert, basierend auf dem Stack-Namen und der Vorlage, die Sie übermitteln. Wenn der Änderungssatz bereits vorhanden ist, wird er von AWS CloudFormation gelöscht und ein neuer erstellt.

• CREATE_UPDATE erstellt den Stack, wenn er nicht vorhanden ist. Wenn der Stack bereits vorhanden ist, wird er von AWS CloudFormation aktualisiert. Verwenden Sie diese Aktion zum Aktualisieren von bestehenden Stacks. Im Gegensatz REPLACE_ON_FAILURE dazu, wenn der Stack vorhanden ist und sich in einem ausgefallenen Zustand befindet, CodePipeline wird der Stapel nicht gelöscht und ersetzt.

• DELETE_ONLY löscht einen Stack. Wenn Sie einen Stack angeben, der nicht vorhanden ist, wird die Aktion ohne Löschen eines Stacks erfolgreich abgeschlossen.

• REPLACE_ON_FAILURE erstellt einen Stack, falls dieser nicht vorhanden ist. Ist der Stack vorhanden und befindet sich in einem fehlerhaften Zustand, löscht AWS CloudFormation den Stack und erstellt dann einen neuen. Befindet sich der Stack nicht in einem fehlerhaften Zustand, wird er von AWS CloudFormation aktualisiert.

  Der Stack befindet sich in einem fehlerhaften Zustand, wenn einer der folgenden Statustypen in AWS CloudFormation angezeigt wird:

  • ROLLBACK_FAILED

  • CREATE_FAILED

  • DELETE_FAILED

  • UPDATE_ROLLBACK_FAILED

  Verwenden Sie diese Aktion, um fehlerhafte Stacks automatisch ohne Wiederherstellung oder Fehlerbehebung zu ersetzen.

  Wichtig

  Wir empfehlen Ihnen, REPLACE_ON_FAILURE nur für Testzwecke zu verwenden, da Ihr Stack dadurch möglicherweise gelöscht wird.

StackName

Erforderlich: Ja

StackName ist der Name eines vorhandenen Stacks oder eines Stacks, den Sie erstellen möchten.

Funktionen

Required: Conditional

Die Verwendung von Capabilities bestätigt, dass die Vorlage möglicherweise über die Funktionen verfügt, einige Ressourcen selbst zu erstellen und zu aktualisieren, und dass diese Funktionen basierend auf den Ressourcentypen in der Vorlage bestimmt werden.

Diese Eigenschaft ist erforderlich, wenn Sie über IAM-Ressourcen in Ihrer Stack-Vorlage verfügen oder einen Stack direkt aus einer Vorlage mit Makros erstellen. Damit die AWS CloudFormation-Aktion erfolgreich auf diese Weise ausgeführt wird, müssen Sie explizit bestätigen, dass Sie dies mit einer der folgenden Funktionen tun möchten:

• CAPABILITY_IAM

• CAPABILITY_NAMED_IAM

• CAPABILITY_AUTO_EXPAND

Sie können mehr als eine Funktion angeben, indem Sie ein Komma (kein Leerzeichen) zwischen den Funktionen verwenden. Das Beispiel in Aktionsdeklaration zeigt einen Eintrag mit den Eigenschaften CAPABILITY_IAM und CAPABILITY_AUTO_EXPAND.

Weitere Informationen Capabilities dazu finden Sie UpdateStackin den Eigenschaften unter der AWS CloudFormationAPI-Referenz.

ChangeSetName

Required: Conditional

ChangeSetName ist der Name eines vorhandenen Änderungssatzes oder eines neuen Änderungssatzes, den Sie für den angegebenen Stack erstellen möchten.

Diese Eigenschaft ist für die folgenden Aktionsmodi erforderlich: CHANGE_SET_REPLACE und CHANGE_SET_EXECUTE. Bei allen anderen Aktionsmodi wird die Eigenschaft ignoriert.

RoleArn

Required: Conditional

RoleArn ist der ARN der IAM-Servicerolle, die AWS CloudFormation annimmt, wenn es mit Ressourcen im angegebenen Stack arbeitet. RoleArn wird nicht angewendet, wenn ein Änderungssatz ausgeführt wird. Wenn Sie den Änderungssatz nicht CodePipeline zur Erstellung verwenden, stellen Sie sicher, dass dem Änderungssatz oder Stack eine zugeordnete Rolle zugewiesen ist.

Anmerkung

Diese Rolle muss sich in demselben Konto befinden wie die Rolle für die Aktion, die gerade ausgeführt wird, wie in der Aktionsdeklaration konfiguriertRoleArn.

Die Eigenschaft ist für die folgenden Aktionsmodi erforderlich:

• CREATE_UPDATE

• REPLACE_ON_FAILURE

• DELETE_ONLY

• CHANGE_SET_REPLACE

Anmerkung

AWS CloudFormationerhält eine mit S3 signierte URL zur Vorlage. Daher ist für diese Vorlage RoleArn keine Zugriffsberechtigung auf den Artefakt-Bucket erforderlich. Die Aktion RoleArn benötigt jedoch die Erlaubnis, auf den Artefakt-Bucket zuzugreifen, um die signierte URL zu generieren.

TemplatePath

Required: Conditional

TemplatePath repräsentiert die AWS CloudFormation-Vorlagendatei. Sie schließen die Datei in ein Eingabeartefakt für diese Aktion ein. Der Dateiname folgt diesem Format:

Artifactname::TemplateFileName

Artifactname ist der Name des Eingabeartefakts, wie er in CodePipeline angezeigt wird. So erstellt eine Quellstufe mit dem Artefaktnamen SourceArtifact und dem Dateinamen template-export.json einen TemplatePath-Namen, wie in diesem Beispiel gezeigt:

"TemplatePath": "SourceArtifact::template-export.json"

Die Eigenschaft ist für die folgenden Aktionsmodi erforderlich:

• CREATE_UPDATE

• REPLACE_ON_FAILURE

• CHANGE_SET_REPLACE

Bei allen anderen Aktionsmodi wird die Eigenschaft ignoriert.

Anmerkung

Die AWS CloudFormation Vorlagendatei, die den Vorlagentext enthält, hat eine Mindestlänge von 1 Byte und eine Höchstlänge von 1 MB. Für AWS CloudFormation Bereitstellungsaktionen in CodePipeline beträgt die maximale Größe des Eingabeartefakts immer 256 MB. Weitere Informationen finden Sie unter Kontingente in AWS CodePipeline und AWS CloudFormation-Limits.

OutputFileName

Erforderlich: Nein

Verwenden Sie diese Option, OutputFileName um einen Namen für die Ausgabedatei anzugeben, z. B.CreateStackOutput.json, der dem Pipeline-Ausgabeartefakt für diese Aktion CodePipeline hinzugefügt wird. Die JSON-Datei enthält den Inhalt des Outputs-Abschnitts aus dem AWS CloudFormation-Stack.

Wenn Sie keinen Namen angeben, wird CodePipeline keine Ausgabedatei oder kein Ausgabeartefakt generiert.

ParameterOverrides

Erforderlich: Nein

Parameter werden in Ihrer Stack-Vorlage definiert und ermöglichen Ihnen, Werte für sie zum Zeitpunkt der Stack-Erstellung oder -Aktualisierung bereitzustellen. Sie können ein JSON-Objekt verwenden, um Parameterwerte in Ihrer Vorlage festzulegen. (Diese Werte überschreiben die in der Vorlagenkonfigurationsdatei festgelegten Werte.) Weitere Informationen zur Verwendung von Parameterüberschreibungen finden Sie unter Konfigurationseigenschaften (JSON-Objekt).

Wir empfehlen Ihnen, die Vorlagenkonfigurationsdatei zu verwenden, um die meisten Ihrer Parameterwerte anzugeben. Verwenden Sie Parameterüberschreibungen nur für Werte, die erst bekannt sind, wenn die Pipeline ausgeführt wird. Weitere Informationen finden Sie im AWS CloudFormationBenutzerhandbuch unter Verwenden von Funktionen zum Überschreiben von Parametern mit CodePipeline Pipelines.

Anmerkung

Alle Parameternamen müssen in der Stack-Vorlage vorhanden sein.

TemplateConfiguration

Erforderlich: Nein

TemplateConfiguration ist die Vorlagenkonfigurationsdatei. Sie schließen die Datei in ein Eingabeartefakt für diese Aktion ein. Sie kann Vorlagenparameterwerte und eine Stack-Richtlinie enthalten. Weitere Informationen zum Format der Vorlagenkonfigurationsdatei finden Sie unter AWS CloudFormationArtifacts.

Der Dateiname der Vorlagenkonfiguration hat das folgende Format:

Artifactname::TemplateConfigurationFileName

Artifactname ist der Name des Eingabeartefakts, wie er in CodePipeline angezeigt wird. So erstellt eine Quellstufe mit dem Artefaktnamen SourceArtifact und dem Dateinamen test-configuration.json einen TemplateConfiguration-Namen, wie in diesem Beispiel gezeigt:

"TemplateConfiguration": "SourceArtifact::test-configuration.json"

Input artifacts (Eingabeartefakte)

• Anzahl der Artefakte: 0 to 10

• Beschreibung: Als Eingabe akzeptiert die AWS CloudFormation-Aktion optional Artefakte für folgende Zwecke:

  • Zur Bereitstellung der auszuführenden Stack-Vorlagendatei. (Weitere Informationen finden Sie unter dem TemplatePath-Parameter.)

  • Zur Bereitstellung der zu verwendenden Vorlagenkonfigurationsdatei. (Weitere Informationen finden Sie unter dem TemplateConfiguration-Parameter.) Weitere Informationen zum Format der Vorlagenkonfigurationsdatei finden Sie unter AWS CloudFormationArtefakte.

  • Zum Bereitstellen des Artefakts für eine Lambda-Funktion, die als Teil des AWS CloudFormation-Stacks bereitgestellt werden soll.

Ausgabeartefakte

• Anzahl der Artefakte: 0 to 1

• Beschreibung: Wenn der OutputFileName-Parameter angegeben ist, wird durch diese Aktion ein Ausgabeartefakt erzeugt, das eine JSON-Datei mit dem angegebenen Namen enthält. Die JSON-Datei enthält den Inhalt des Ausgabeabschnitts aus dem AWS CloudFormation-Stack.

  Weitere Informationen zum Ausgabeabschnitt, den Sie für Ihre AWS CloudFormation-Aktion erstellen können, finden Sie unter Ausgaben.

Ausgabevariablen

Wenn dies konfiguriert ist, werden durch diese Aktion Variablen erzeugt, die von der Aktionskonfiguration einer nachgeschalteten Aktion in der Pipeline referenziert werden können. Sie konfigurieren eine Aktion mit einem Namespace, um diese Variablen für die Konfiguration nachgeschalteter Aktionen zur Verfügung zu stellen.

Für AWS CloudFormation-Aktionen werden Variablen aus beliebigen Werten erzeugt, die im Outputs-Abschnitt einer Stack-Vorlage angegeben sind. Beachten Sie, dass die einzigen CloudFormation Aktionsmodi, die Ausgaben generieren, diejenigen sind, die zur Erstellung oder Aktualisierung eines Stacks führen, wie z. B. die Erstellung von Stacks, Stack-Aktualisierungen und die Ausführung von Änderungssätzen. Die entsprechenden Aktionsmodi, die Variablen generieren, sind:

• CHANGE_SET_EXECUTE

• CHANGE_SET_REPLACE

• CREATE_UPDATE

• REPLACE_ON_FAILURE

Weitere Informationen finden Sie unter Variablen. Ein Tutorial, das Ihnen zeigt, wie Sie eine Pipeline mit einer CloudFormation Bereitstellungsaktion in einer Pipeline erstellen, die CloudFormation Ausgabevariablen verwendet, finden Sie unterTutorial: Erstellen einer Pipeline, die Variablen aus AWS CloudFormation-Bereitstellungsaktionen verwendet.

Aktionsdeklaration

YAML

Name: ExecuteChangeSet
ActionTypeId:
  Category: Deploy
  Owner: AWS
  Provider: CloudFormation
  Version: '1'
RunOrder: 2
Configuration:
  ActionMode: CHANGE_SET_EXECUTE
  Capabilities: CAPABILITY_NAMED_IAM,CAPABILITY_AUTO_EXPAND
  ChangeSetName: pipeline-changeset
  ParameterOverrides: '{"ProjectId": "my-project","CodeDeployRole": "CodeDeploy_Role_ARN"}'
  RoleArn: CloudFormation_Role_ARN
  StackName: my-project--lambda
  TemplateConfiguration: 'my-project--BuildArtifact::template-configuration.json'
  TemplatePath: 'my-project--BuildArtifact::template-export.yml'
OutputArtifacts: []
InputArtifacts:
  - Name: my-project-BuildArtifact

JSON

{
    "Name": "ExecuteChangeSet",
    "ActionTypeId": {
        "Category": "Deploy",
        "Owner": "AWS",
        "Provider": "CloudFormation",
        "Version": "1"
    },
    "RunOrder": 2,
    "Configuration": {
        "ActionMode": "CHANGE_SET_EXECUTE",
        "Capabilities": "CAPABILITY_NAMED_IAM,CAPABILITY_AUTO_EXPAND",
        "ChangeSetName": "pipeline-changeset",
        "ParameterOverrides": "{\"ProjectId\": \"my-project\",\"CodeDeployRole\": \"CodeDeploy_Role_ARN\"}",
        "RoleArn": "CloudFormation_Role_ARN",
        "StackName": "my-project--lambda",
        "TemplateConfiguration": "my-project--BuildArtifact::template-configuration.json",
        "TemplatePath": "my-project--BuildArtifact::template-export.yml"
    },
    "OutputArtifacts": [],
    "InputArtifacts": [
        {
             "Name": "my-project-BuildArtifact"
        }
    ]
},

Weitere Informationen finden Sie auch unter

Die folgenden verwandten Ressourcen bieten Ihnen nützliche Informationen für die Arbeit mit dieser Aktion.

• Referenz zu den Konfigurationseigenschaften — Dieses Referenzkapitel im AWS CloudFormationBenutzerhandbuch enthält weitere Beschreibungen und Beispiele für diese CodePipeline Parameter.

• AWS CloudFormationAPI-Referenz — Der CreateStackParameter in der AWS CloudFormationAPI-Referenz beschreibt Stack-Parameter für AWS CloudFormation Vorlagen.