Referenz der AWS CloudFormation-Konfigurationseigenschaften

Wenn Sie eine CodePipeline erstellen, fügen Sie der Pipeline eine Deploy-Aktion mit AWS CloudFormation als Anbieter hinzu. Anschließend müssen Sie die AWS CloudFormation-Aktion, die die Pipeline aufruft, und die Einstellungen der Aktion angeben. In diesem Thema werden die AWS CloudFormation-Konfigurationseigenschaften beschrieben. Zum Angeben von Eigenschaften können Sie die CodePipeline-Konsole verwenden oder ein JSON-Objekt erstellen, das für die AWS CLI, CodePipeline-API oder AWS CloudFormation-Vorlagen verwendet wird.

Konfigurationseigenschaften (Konsole)

Die CodePipeline-Konsole zeigt die Konfigurationseigenschaften und gibt die Eigenschaften an, die basierend auf dem ausgewählten Aktionsmodus erforderlich sind.

Anmerkung

Wenn Sie eine Pipeline erstellen, können Sie nur die Aktionsmodi Create or update a stack (Einen Stack erstellen oder aktualisieren) oder Create or replace a change set (Einen Änderungssatz erstellen oder ersetzen) angeben. Die Eigenschaften im Advanced (Eweitert)-Abschnitt sind nur verfügbar, wenn Sie eine Pipeline bearbeiten.

Action-Modus

Die AWS CloudFormation-Aktion, die CodePipeline beim Verarbeiten der zugehörigen Stufe aufruft. Wählen Sie einen der folgenden Aktionsmodi aus:

• Create or replace a change set 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 or update a stack erstellt oder aktualisiert einen Stack, wenn der angegebene Stack nicht vorhanden ist. Wenn der Stack bereits vorhanden ist, wird er von AWS CloudFormation aktualisiert. Verwenden Sie diese Aktion zum Aktualisieren von bestehenden Stacks. Der Stack wird von CodePipeline nicht ersetzt.

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

• Execute a change set führt einen Änderungssatz aus.

• Replace a failed stack erstellt oder aktualisiert einen Stack, wenn der angegebene Stack nicht vorhanden ist. Ist der Stack vorhanden und befindet sich in einem fehlerhaften Zustand (gemeldet als ROLLBACK_COMPLETE, ROLLBACK_FAILED, CREATE_FAILED, DELETE_FAILED oder UPDATE_ROLLBACK_FAILED), löscht AWS CloudFormation den Stack und erstellt einen neuen. Befindet sich der Stack nicht in einem fehlerhaften Zustand, wird er von AWS CloudFormation aktualisiert. Verwenden Sie diese Aktion, um fehlerhafte Stacks ohne Wiederherstellung oder Fehlerbehebung zu ersetzen. In der Regel wählen Sie diesen Modus für Tests.

Stack name

Der Name, der einem vorhandenen Stack oder einem Stack zugeordnet ist, den Sie erstellen möchten. Der Name muss in der AWS-Region eindeutig sein, in der Sie den Stack erstellen.

Anmerkung

Ein Stack-Name darf nur alphanumerische Zeichen (wobei die Groß- und Kleinschreibung beachtet werden muss) und Bindestriche enthalten. Er muss mit einem alphabetischen Zeichen beginnen und darf nicht mehr als 128 Zeichen umfassen.

Change set name (Name des Änderungssatzes)

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

Vorlage

Der Speicherort einer AWS CloudFormation-Vorlagendatei im Format ArtifactName::TemplateFileName.

Vorlagenkonfiguration

Der Speicherort einer Vorlagenkonfigurationsdatei im Format ArtifactName::TemplateConfigurationFileName. Die Vorlagenkonfigurationsdatei kann Vorlagenparameterwerte, eine Stack-Richtlinie und Tags enthalten. Wenn Sie sensible Daten wie z. B. Passwörter einschließen, sollten Sie den Zugriff auf diese Datei beschränken. Weitere Informationen finden Sie unter AWS CloudFormation-Artefakte.

Funktionen

Bei Stacks mit bestimmten Ressourcen ist die explizite Bestätigung erforderlich, dass AWS CloudFormation diese Ressourcen erstellen oder aktualisieren kann. Sie müssen beispielsweise CAPABILITY_IAM angeben, wenn die Stack-Vorlage AWS Identity and Access Management (IAM)-Ressourcen enthält. Weitere Informationen finden Sie unter CreateStack-Anforderungsparameter.

Wenn Sie IAM-Ressourcen in Ihrer Stack-Vorlage verwenden, müssen Sie diese Eigenschaft angeben.

Sie können mehr als eine Funktion angeben.

Name der Rolle

Der Name der IAM-Servicerolle, die von AWS CloudFormation angenommen wird, wenn Ressourcen im angegebenen Stack verarbeitet werden.

Ausgabedateiname

Im Advanced (Erweitert)-Abschnitt können Sie einen Ausgabedateinamen wie z. B. CreateStackOutput.json angeben, den CodePipeline dem Ausgabeartefakt nach der Ausführung der angegebenen Aktion hinzufügt. Das Ausgabeartefakt enthält eine JSON-Datei mit dem Inhalt des Outputs-Abschnitts der AWS CloudFormation-Vorlage.

Wenn Sie keinen Namen angeben, generiert CodePipeline kein Ausgabeartefakt.

Parameter überschreiben

Parameter werden in Ihrer Vorlage definiert und ermöglichen Ihnen, benutzerdefinierte Werte einzugeben, wenn Sie einen Stack erstellen oder aktualisieren. Sie können ein JSON-Objekt angeben, das Parameterwerte für die Vorlage in der Vorlagenkonfigurationsdatei überschreibt. Alle Parameternamen müssen in der Stack-Vorlage vorhanden sein. Weitere Informationen finden Sie unter Definieren eines Parameters in einer Vorlage.

Anmerkung

Für das JSON-Objekt, das in der Eigenschaft ParameterOverrides gespeichert werden kann, gilt eine Maximalgröße von 1 Kilobyte.

Wir empfehlen, dass Sie die Vorlagenkonfigurationsdatei verwenden, um die meisten Ihrer Parameterwerte anzugeben. Verwenden Sie Parameterüberschreibungen, um nur dynamische Parameterwerte anzugeben. Dynamische Parameter sind unbekannt, bis Sie die Pipeline ausführen.

Das folgende Beispiel definiert einen Wert für den ParameterName-Parameter mithilfe einer Parameterüberschreibungsfunktion. Die Funktion ruft einen Wert von einem CodePipeline-Eingabeartefakt ab. Weitere Informationen zu Parameterüberschreibungsfunktionen finden Sie unter Verwenden von Parameterüberschreibungsfunktionen mit CodePipeline-Pipelines.

{
  "ParameterName" : { "Fn::GetParam" : ["ArtifactName", "config-file-name.json", "ParamName"]}
}

Konfigurationseigenschaften (JSON-Objekt)

Wenn Sie CloudFormation als Anbieter für eine Phasenaktion angeben, definieren Sie die folgenden Eigenschaften in der Configuration-Eigenschaft. Verwenden Sie das JSON-Objekt für die AWS CLI, CodePipeline-API oder AWS CloudFormation-Vorlagen. Beispiele finden Sie unter Walkthrough: Erstellen einer Pipeline für Test- und Produktions-Stacks und Referenz der AWS CloudFormation-Konfigurationseigenschaften.

ActionMode

Die AWS CloudFormation-Aktion, die CodePipeline beim Verarbeiten der zugehörigen Stufe aufruft. Geben Sie nur einen der folgenden Aktionsmodi an:

• CHANGE_SET_EXECUTE führt einen Änderungssatz aus.

• 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 der angegebene Stack noch nicht vorhanden ist. Wenn der Stack bereits vorhanden ist, wird er von AWS CloudFormation aktualisiert. Verwenden Sie diese Aktion zum Aktualisieren von bestehenden Stacks. Der Stack wird von CodePipeline nicht 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, wenn der angegebene Stack noch nicht vorhanden ist. Ist der Stack vorhanden und befindet sich in einem fehlerhaften Zustand (gemeldet als ROLLBACK_COMPLETE, ROLLBACK_FAILED, CREATE_FAILED, DELETE_FAILED oder UPDATE_ROLLBACK_FAILED), löscht AWS CloudFormation den Stack und erstellt einen neuen. Befindet sich der Stack nicht in einem fehlerhaften Zustand, wird er von AWS CloudFormation aktualisiert. Verwenden Sie diese Aktion, um fehlerhafte Stacks automatisch ohne Wiederherstellung oder Fehlerbehebung zu ersetzen. In der Regel wählen Sie diesen Modus für Tests.

Diese Eigenschaft ist erforderlich.

Capabilities

Bei Stacks mit bestimmten Ressourcen ist die explizite Bestätigung erforderlich, dass AWS CloudFormation diese Ressourcen erstellen oder aktualisieren kann. Sie müssen beispielsweise CAPABILITY_IAM angeben, wenn die Stack-Vorlage AWS Identity and Access Management (IAM)-Ressourcen enthält. Weitere Informationen finden Sie unter CreateStack-Anforderungsparameter.

Diese Eigenschaft ist bedingt erforderlich. Wenn Sie IAM-Ressourcen in Ihrer Stack-Vorlage verwenden, müssen Sie diese Eigenschaft angeben.

Sie können mehrere Funktionen angeben. Im folgenden Beispiel werden der Vorlage die Eigenschaften CAPABILITY_IAM und CAPABILITY_AUTO_EXPAND hinzugefügt:

YAML

configuration:
  ActionMode: CHANGE_SET_REPLACE
  Capabilities: CAPABILITY_IAM,CAPABILITY_AUTO_EXPAND
  ChangeSetName: pipeline-changeset
  RoleArn: CloudFormation_Role_ARN
  StackName: my-pipeline-stack
  TemplateConfiguration: 'my-pipeline-stack::template-configuration.json'
  TemplatePath: 'my-pipeline-stack::template-export.yml'

JSON

 "configuration": {
        "ActionMode": "CHANGE_SET_REPLACE",
        "Capabilities": "CAPABILITY_IAM,CAPABILITY_AUTO_EXPAND",
        "ChangeSetName": "pipeline-changeset",
        "RoleArn": "CloudFormation_Role_ARN",
        "StackName": "my-pipeline-stack",
        "TemplateConfiguration": "my-pipeline-stack::template-configuration.json",
        "TemplatePath": "my-pipeline-stack::template-export.yml"
    }

ChangeSetName

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

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

OutputFileName

Ein Name für die Ausgabedatei, z. B. CreateStackOutput.json. CodePipeline fügt die Datei dem Ausgabeartefakt nach der Ausführung der angegebenen Aktion hinzu. Das Ausgabeartefakt enthält eine JSON-Datei mit dem Inhalt des Outputs-Abschnitts der AWS CloudFormation-Vorlage.

Diese Eigenschaft ist optional. Wenn Sie keinen Namen angeben, generiert CodePipeline kein Ausgabeartefakt.

ParameterOverrides

Parameter werden in Ihrer Vorlage definiert und ermöglichen Ihnen, benutzerdefinierte Werte einzugeben, wenn Sie einen Stack erstellen oder aktualisieren. Sie können ein JSON-Objekt angeben, das Parameterwerte für die Vorlage in der Vorlagenkonfigurationsdatei überschreibt. Alle Parameternamen müssen in der Stack-Vorlage vorhanden sein. Weitere Informationen finden Sie unter Definieren eines Parameters in einer Vorlage.

Im folgenden Beispiel werden die Parameterüberschreibungen InstanceType und KeyName zur Vorlage hinzugefügt:

YAML

configuration:
  ActionMode: CHANGE_SET_REPLACE
  Capabilities: CAPABILITY_NAMED_IAM
  ChangeSetName: pipeline-changeset
  ParameterOverrides: '{"InstanceType": "t2.small","KeyName": "my-keypair"}'
  RoleArn: CloudFormation_Role_ARN
  StackName: my-pipeline-stack
  TemplateConfiguration: 'my-pipeline-stack::template-configuration.json'
  TemplatePath: 'my-pipeline-stack::template-export.yml'

JSON

"configuration": {
        "ActionMode": "CHANGE_SET_REPLACE",
        "Capabilities": "CAPABILITY_NAMED_IAM",
        "ChangeSetName": "pipeline-changeset",
        "ParameterOverrides": "{\"InstanceType\": \"t2.small\",\"KeyName\": \"my-keypair\"}",
        "RoleArn": "CloudFormation_Role_ARN",
        "StackName": "my-pipeline-stack",
        "TemplateConfiguration": "my-pipeline-stack::template-configuration.json",
        "TemplatePath": "my-pipeline-stack::template-export.yml"
    }

Anmerkung

Die maximale Größe für das JSON-Objekt, das in der ParameterOverrides-Eigenschaft gespeichert werden kann, beträgt 1 Kilobyte.

Wir empfehlen, dass Sie die Vorlagenkonfigurationsdatei verwenden, um die meisten Ihrer Parameterwerte anzugeben. Verwenden Sie Parameterüberschreibungen, um nur dynamische Parameterwerte anzugeben. Dynamische Parameterwerte sind unbekannt, bis Sie die Pipeline ausführen.

Das folgende Beispiel definiert einen Wert für den ParameterName-Parameter mithilfe einer Parameterüberschreibungsfunktion. Die Funktion ruft einen Wert von einem CodePipeline-Eingabeartefakt ab. Weitere Informationen zu Parameterüberschreibungsfunktionen finden Sie unter Verwenden von Parameterüberschreibungsfunktionen mit CodePipeline-Pipelines.

{
  "ParameterName" : { "Fn::GetParam" : ["ArtifactName", "config-file-name.json", "ParamName"]}
}

Diese Eigenschaft ist optional.

RoleArn

Der Amazon-Ressourcenname (ARN) der IAM-Servicerolle, die von AWS CloudFormation angenommen wird, wenn Ressourcen in einem Stack verarbeitet werden.

Diese Eigenschaft ist für die folgenden Aktionsmodi erforderlich: CREATE_UPDATE, REPLACE_ON_FAILURE, DELETE_ONLY und CHANGE_SET_REPLACE. RoleArn wird nicht angewendet, wenn ein Änderungssatz ausgeführt wird. Wenn Sie CodePipeline nicht verwenden, um den Änderungssatz zu erstellen, stellen Sie sicher, dass dem Änderungssatz oder dem Stack eine Rolle zugewiesen ist.

StackName

Der Name eines vorhandenen Stacks oder eines Stacks, den Sie erstellen möchten.

Die Eigenschaft ist für alle Aktionsmodi erforderlich.

TemplateConfiguration

TemplateConfiguration ist die Vorlagenkonfigurationsdatei. Sie schließen die Datei in ein Eingabeartefakt für diese Aktion ein. 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"

Die Vorlagenkonfigurationsdatei kann Vorlagenparameterwerte und eine Stack-Richtlinie enthalten. Wenn Sie sensible Daten wie z. B. Passwörter einschließen, sollten Sie den Zugriff auf diese Datei beschränken. Für eine Beispiel-Vorlagenkonfigurationsdatei siehe AWS CloudFormation-Artefakte.

Diese Eigenschaft ist optional.

TemplatePath

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.yaml einen TemplatePath-Namen, wie in diesem Beispiel gezeigt:

"TemplatePath": "SourceArtifact::template.yaml"

Die Eigenschaft wird für die folgenden Aktionsmodi benötigt: CREATE_UPDATE, REPLACE_ON_FAILURE und CHANGE_SET_REPLACE. Bei allen anderen Aktionsmodi wird die Eigenschaft ignoriert.

Weitere Informationen finden Sie auch unter

Die folgenden verwandten Ressourcen unterstützen Sie bei der Arbeit mit diesen Parametern.

• Weitere Informationen zu den AWS CloudFormation-Aktionsparametern in CodePipeline enthält die Referenz zu Aktions-Konfigurationen von AWS CloudFormation im Benutzerhandbuch für AWS CodePipeline.

• Beispiels-Vorlagenwerte nach Aktionsanbietern, wie etwa für das Owner-Feld oder die configuration-Felder, finden Sie in der Referenz zur Aktionsstruktur im Benutzerhandbuch für AWS CodePipeline.

• Informationen zum Herunterladen der Beispiele für Pipeline-Stack-Vorlagen im Format YAML oder JSON finden Sie in den Tutorials unter Erstellen einer Pipeline mit AWS CloudFormation im Benutzerhandbuch für AWS CodePipeline.

• Eine Beispiel-Vorlagenkonfigurationsdatei finden Sie unter AWS CloudFormation Artifacts.