CloudFormation Vorlage Parameters-Syntax - AWS CloudFormation
SyntaxEigenschaftenAllgemeine Anforderungen für ParameterBeispieleZugehörige Ressourcen

CloudFormation Vorlage Parameters-Syntax

Mit dem optionalen Abschnitt Parameters können Sie Ihre Vorlagen anpassen. Mit Parametern können Sie jedes Mal, wenn Sie einen Stapel erstellen oder aktualisieren, benutzerdefinierte Werte in Ihre Vorlage eingeben. Durch die Verwendung von Parametern in Ihren Vorlagen können Sie wiederverwendbare und flexible Vorlagen erstellen, die auf bestimmte Szenarien zugeschnitten werden können.

Durch die Definition von Parametern des entsprechenden Typs können Sie aus einer Liste von Bezeichnern vorhandener Ressourcen wählen, wenn Sie die Konsole zur Erstellung Ihres Stapels verwenden. Weitere Informationen finden Sie unter Spezifizieren Sie vorhandene Ressourcen zur Laufzeit mit von CloudFormation bereitgestellten Parametertypen.

Parameter sind eine beliebte Methode, um Eigenschaftswerte von Stack-Ressourcen anzugeben. Es kann jedoch Einstellungen geben, die von der Region abhängen oder die für den Benutzer aufgrund anderer Bedingungen oder Abhängigkeiten etwas kompliziert zu verstehen sind. In diesen Fällen möchten Sie vielleicht eine Logik in die Vorlage selbst einbauen, damit die Benutzer einfachere Werte (oder gar keine) angeben können, um die gewünschten Ergebnisse zu erhalten, z. B. durch Verwendung einer Zuordnung. Weitere Informationen finden Sie unter CloudFormation Vorlage Mappings-Syntax.

Syntax

Sie deklarieren Parameter im Abschnitt Parameters einer Vorlage, der die folgende allgemeine Syntax verwendet:

JSON

"Parameters" : {
  "ParameterLogicalID" : {
    "Description": "Information about the parameter",
    "Type" : "DataType",
    "Default" : "value",
    "AllowedValues" : ["value1", "value2"]
  }
}

YAML

Parameters:
  ParameterLogicalID:
    Description: Information about the parameter
    Type: DataType
    Default: value
    AllowedValues:
      - value1
      - value2

Ein Parameter enthält eine Liste von Attributen, die seinen Wert sowie Einschränkungen für diesen Wert definieren. Das einzige erforderliche Attribut ist,Type das,String Numberoder ein von CloudFormation bereitgestellter Parametertyp sein kann. Sie können auch ein Description-Attribut hinzufügen, das beschreibt, welche Art von Wert Sie angeben sollten. Der Name und die Beschreibung des Parameters erscheinen auf der Seite Parameter angeben wenn Sie die Vorlage im Assistenten Stapel erstellen verwenden.

Anmerkung

Standardmäßig listet die CloudFormation-Konsole die Eingabeparameter alphabetisch nach ihrer logischen ID auf. Um diese Standardreihenfolge außer Kraft zu setzen und verwandte Parameter zu gruppieren, können Sie den Metadatenschlüssel AWS::CloudFormation::Interface in Ihrer Vorlage verwenden. Weitere Informationen finden Sie unter Organisieren von CloudFormation-Parametern mit AWS::CloudFormation::Interface-Metadaten.

Bei Parametern mit Standardwerten verwendet CloudFormation die Standardwerte, es sei denn, der Benutzer gibt einen anderen Wert an. Wenn Sie das Standardattribut weglassen, müssen die Benutzer einen Wert für diesen Parameter angeben. Die Aufforderung an den Benutzer, einen Wert einzugeben, stellt jedoch nicht sicher, dass der Wert gültig ist. Um einen Wert eines Parameters zu überprüfen, können Sie Einschränkungen definieren oder einen AWS-spezifischen Parametertyp festlegen.

Für Parameter ohne Standardwerte müssen die Benutzer bei der Stack-Erstellung einen Wert für den Schlüsselnamen angeben. Wenn dies nicht der Fall ist, kann CloudFormation den Stack nicht erstellen und löst eine Ausnahme aus:

Parameters: [KeyName] must have values

Eigenschaften

AllowedPattern

Gibt einen regulären Ausdruck an, der die zulässigen Muster für String- oder CommaDelimitedList-Typen beschreibt. Bei der Anwendung auf einen Parameter des Typs String muss das Muster mit dem gesamten angegebenen Parameterwert übereinstimmen. Wenn das Muster auf einen Parameter des Typs CommaDelimitedList angewendet wird, muss es mit jedem Wert in der Liste übereinstimmen.

Required: No

AllowedValues

Gibt ein Array mit einer Liste der für den Parameter zulässigen Werte an. Wenn der Parameterwert auf einen Parameter des Typs String angewendet wird, muss er einer der zulässigen Werte sein. Wenn der Parameterwert auf einen Parameter des Typs CommaDelimitedList angewendet wird, muss jeder Wert in der Liste einer der ausgewählten zulässigen Werte sein.

Required: No

Anmerkung

Wenn Sie YAML verwenden und Yes- und No-Zeichenfolgen für AllowedValues nutzen möchten, geben Sie einfache Anführungszeichen ein, um zu verhindern, dass diese booleschen Werte vom YAML-Parser berücksichtigt werden.

ConstraintDescription

Gibt eine Zeichenfolge als Beschreibung für eine Einschränkung an. Diese Beschreibung wird bei Verstößen gegen die Einschränkung angezeigt. Für einen Parameter mit einem zulässigen Muster [A-Za-z0-9]+ beispielsweise wird ohne Einschränkungsbeschreibung die folgende Fehlermeldung angezeigt, wenn der Benutzer einen ungültigen Wert angibt:

Malformed input-Parameter MyParameter must match pattern [A-Za-z0-9]+

Durch das Hinzufügen der Beschreibung einer Einschränkung, wie z. B. dürfen nur Groß- und Kleinbuchstaben und Zahlen enthalten, können Sie die folgende benutzerdefinierte Fehlermeldung anzeigen:

Malformed input-Parameter MyParameter must only contain uppercase and lowercase letters and numbers

Required: No

Default

Gibt einen Wert des entsprechenden Typs an, den die Vorlage nutzen soll, wenn zum Zeitpunkt der Stack-Erstellung kein Wert angegeben wird. Wenn Sie Einschränkungen für den Parameter definieren, müssen Sie einen Wert angeben, der diese Einschränkungen einhält.

Required: No

Description

Gibt eine Zeichenfolge mit maximal 4 000 Zeichen an, die den Parameter beschreibt.

Required: No

MaxLength

Gibt einen Ganzzahlwert an, der festlegt, wie viele Zeichen maximal für String-Typen zulässig sind.

Required: No

MaxValue

Gibt einen numerischen Wert an, der den zulässigen numerischen Maximalwert für Number-Typen definiert.

Required: No

MinLength

Gibt einen Ganzzahlwert an, der die zulässige Mindestzeichenzahl für String-Typen definiert.

Required: No

MinValue

Gibt einen numerischen Wert an, der den zulässigen numerischen Mindestwert für Number-Typen definiert.

Required: No

NoEcho

Gibt an, ob der Parameterwert maskiert werden soll, damit er in der Konsole, in Befehlszeilen-Tools und in der API nicht angezeigt wird. Wenn Sie das NoEcho-Attribut auf true festlegen, gibt CloudFormation für alle Aufrufe, die den Stack oder die Stapelereignisse beschreiben, den als Sternchen (*****) maskierten Parameterwert zurück, mit Ausnahme der Informationen, die an den folgenden Speicherorten gespeichert sind.

Required: No

Wichtig

Durch die Verwendung des NoEcho-Attributs werden keine Informationen maskiert, die im Folgenden gespeichert sind:

  • Der Metadata-Vorlagenabschnitt. CloudFormation transformiert, ändert oder überarbeitet keine Informationen, die Sie im Metadata-Abschnitt einfügen. Weitere Informationen finden Sie unter Metadaten.

  • Der Outputs-Vorlagenabschnitt. Weitere Informationen finden Sie unter Ausgaben:

  • Das Metadata-Attribut einer Ressourcendefinition. Weitere Informationen finden Sie unter Metadata-Attribut.

Es wird dringend empfohlen, diese Mechanismen nicht zu verwenden, um vertrauliche Informationen wie Passwörter oder Geheimnisse einzugeben.

Wichtig

Anstatt vertrauliche Informationen direkt in Ihre CloudFormation-Vorlagen einzubetten, sollten Sie dynamische Parameter in der Stack-Vorlage verwenden, um auf vertrauliche Informationen zu verweisen, die außerhalb von CloudFormation gespeichert und verwaltet werden, z. B. im AWS Systems Manager-Parameterspeicher oder AWS Secrets Manager.

Weitere Informationen finden Sie in den bewährten Methoden zu Keine Anmeldeinformationen in Ihre Vorlagen einbetten.

Wichtig

Wir empfehlen dringend davon ab, NoEcho-Parameter oder vertrauliche Daten in Ressourceneigenschaften, die Teil der primären ID einer Ressource sind.

Wenn ein NoEcho-Parameter in einer Eigenschaft enthalten ist, die eine primäre Ressourcen-Kennung bildet, kann CloudFormation den tatsächlichen Klartext-Wert in der primären Ressourcen-Kennung verwenden. Diese Ressourcen-ID kann in allen abgeleiteten Ausgaben oder Zielen vorkommen.

Um festzustellen, welche Ressourceneigenschaften den primären Bezeichner eines Ressourcentyps umfassen, lesen Sie die Dokumentation der Ressourcenreferenz für diese Ressource in der AWS Ressourcen- und Eigenschaftstypenreferenz. Im Abschnitt Return values (Rückgbewerte) stellt der Rückgabewert der Ref-Funktion die Ressourceneigenschaften dar, welche die primäre Kennung des Ressourcentyps bilden.

Type

Gibt den Datentyp des Parameters an (DataType).

Erforderlich: Ja

CloudFormation unterstützt die folgenden Parametertypen:

String

Gibt eine Literalzeichenfolge an. Sie können die folgenden Attribute verwenden, um Constraints zu deklarieren:,MinLength,MaxLength,Default AllowedValuesund AllowedPattern.

Zum Beispiel könnten Benutzer angeben "MyUserName".

Number

Eine Ganzzahl oder ein Float. CloudFormation validiert den Parameterwert als Zahl. Wenn Sie den Parameter jedoch an anderer Stelle in Ihrer Vorlage verwenden (z. B. mithilfe der intrinsischen Funktion Ref), wird der Parameterwert zu einer Zeichenfolge.

Sie können die folgenden Attribute verwenden, um Beschränkungen zu deklarieren:,MinValue,MaxValue Defaultund AllowedValues.

Zum Beispiel könnten Benutzer angeben "8888".

List<Number>

Ein Array von Ganzzahlen oder Fließkommazahlen, die durch Kommas getrennt sind. CloudFormation validiert den Parameterwert als Zahlen. Wenn Sie den Parameter jedoch an anderer Stelle in Ihrer Vorlage verwenden (z. B. mithilfe der intrinsischen Funktion Ref), wird der Parameterwert zu einer Liste an Zeichenfolgen.

Zum Beispiel könnten Benutzer "80,20" angeben. Ref würde dann ["80","20"] zurückgeben.

CommaDelimitedList

Gibt ein Array von Literalzeichenfolgen an, jeweils durch Komma getrennt. Die Gesamtanzahl von Zeichenfolgen sollte um 1 höher sein als die Gesamtanzahl von Kommas. Jede Mitgliedszeichenfolge wird zudem gekürzt.

Zum Beispiel könnten Benutzer "test,dev,prod" angeben. Ref würde dann ["test","dev","prod"] zurückgeben.

AWS-spezifische Parametertypen

AWS-Werte wie die Namen von Amazon-EC2-Schlüsselpaaren und VPC-IDs. Weitere Informationen finden Sie unter Vorhandene Ressourcen zur Laufzeit spezifizieren.

Systems Manager Parameter-Typen

Parameter, die vorhandenen Parametern im Systems Manager Parameter Store entsprechen. Sie geben einen Systems Manager-Parameterschlüssel als Wert des Systems Manager-Parametertyps an, und CloudFormation ruft den neuesten Wert aus dem Parameter Store ab, der für den Stack verwendet werden soll. Weitere Informationen finden Sie unter Vorhandene Ressourcen zur Laufzeit spezifizieren.

Allgemeine Anforderungen für Parameter

Die folgenden Anforderungen gelten bei der Verwendung von Parametern:

  • Sie können maximal 200 Parameter in einer CloudFormation-Vorlage haben.

  • Jedem Parameter muss ein logischer Name (auch logische ID genannt) gegeben werden, der alphanumerisch und unter allen logischen Namen innerhalb der Vorlage eindeutig sein muss.

  • Jedem Parameter muss ein Parametertyp zugewiesen werden, der von CloudFormation unterstützt wird. Weitere Informationen finden Sie unter Type.

  • Jedem Parameter muss zur Laufzeit ein Wert zugewiesen werden, damit CloudFormation den Stack erfolgreich bereitstellen kann. Sie können optional einen Standardwert angeben, den CloudFormation verwenden soll, wenn kein anderer Wert angegeben wird.

  • Die Parameter innerhalb derselben Vorlage deklariert und referenziert werden. Sie können Parameter aus den Vorlagenabschnitten Resources und Outputs der Vorlage referenzieren.

Beispiele

Einfacher String-Parameter

Das folgende Beispiel deklariert einen Parameter mit dem Namen InstanceTypeParameter vom Typ String. Mit diesem Parameter können Sie den Amazon EC2-Instancetyp für den Stack angeben. Wenn bei der Stack-Erstellung oder Aktualisierung kein Wert angegeben wird, verwendet CloudFormation den Standardwert t2.micro.

JSON

"Parameters" : {
  "InstanceTypeParameter" : {
    "Description" : "Enter t2.micro, m1.small, or m1.large. Default is t2.micro.",
    "Type" : "String",
    "Default" : "t2.micro",
    "AllowedValues" : ["t2.micro", "m1.small", "m1.large"]
  }
}

YAML

Parameters:
  InstanceTypeParameter:
    Description: Enter t2.micro, m1.small, or m1.large. Default is t2.micro.
    Type: String
    Default: t2.micro
    AllowedValues:
      - t2.micro
      - m1.small
      - m1.large

Parameter Passwort

Das folgende Beispiel deklariert einen Parameter namens DBPwd vom Typ String ohne Standardwert. Die Eigenschaft NoEcho wird auf true gesetzt, um zu verhindern, dass der Parameterwert in Stapelbeschreibungen angezeigt wird. Die zulässige Mindestlänge ist 1, die zulässige Maximallänge 41. Das Muster erlaubt die Verwendung von Klein- und Großbuchstaben sowie Ziffern. Dieses Beispiel veranschaulicht auch die Verwendung eines regulären Ausdrucks für die Eigenschaft AllowedPattern .

JSON

"Parameters" : {
  "DBPwd" : {
    "NoEcho" : "true",
    "Description" : "The database admin account password",
    "Type" : "String",
    "MinLength" : "1",
    "MaxLength" : "41",
    "AllowedPattern" : "^[a-zA-Z0-9]*$"
  }
}

YAML

Parameters: 
  DBPwd: 
    NoEcho: true
    Description: The database admin account password
    Type: String
    MinLength: 1
    MaxLength: 41
    AllowedPattern: ^[a-zA-Z0-9]*$

Parameter referenzieren

Sie verwenden die intrinsische Funktion Ref, um auf einen Parameter zu verweisen, und CloudFormation verwendet den Wert des Parameters zur Bereitstellung des Stacks. Sie können Parameter aus den Vorlagenabschnitten Resources und Outputs derselben Vorlage referenzieren.

Im folgenden Beispiel referenziert die Eigenschaft InstanceType der EC2-Instance-Ressource den Parameterwert InstanceTypeParameter:

JSON

"Ec2Instance" : {
  "Type" : "AWS::EC2::Instance",
  "Properties" : {
    "InstanceType" : { "Ref" : "InstanceTypeParameter" },
    "ImageId" : "ami-0ff8a91507f77f867"
  }
}

YAML

Ec2Instance:
  Type: AWS::EC2::Instance
  Properties:
    InstanceType:
      Ref: InstanceTypeParameter
    ImageId: ami-0ff8a91507f77f867

Komma-getrennte Listenparameter

Der Parametertyp CommaDelimitedList kann nützlich sein, wenn Sie mehrere Werte für eine einzelne Eigenschaft angeben müssen. Das folgende Beispiel deklariert einen Parameter namens DbSubnetIpBlocks mit einem Standardwert von drei durch Kommas getrennten CIDR-Blöcken.

JSON

"Parameters" : {
  "DbSubnetIpBlocks": {
    "Description": "Comma-delimited list of three CIDR blocks",
    "Type": "CommaDelimitedList",
    "Default": "10.0.48.0/24, 10.0.112.0/24, 10.0.176.0/24"
  }
}

YAML

Parameters: 
  DbSubnetIpBlocks: 
    Description: "Comma-delimited list of three CIDR blocks"
    Type: CommaDelimitedList
    Default: "10.0.48.0/24, 10.0.112.0/24, 10.0.176.0/24"

Zurückgeben eines Werts aus einem Parameter für Komma-getrennte Listen

Um auf einen bestimmten Wert in der kommagetrennten Liste eines Parameters zu verweisen, verwenden Sie die intrinsische Funktion Fn::Select im Abschnitt Resources Ihrer Vorlage. Übergeben Sie den Indexwert des gewünschten Objekts und eine Liste von Objekten, wie im folgenden Beispiel gezeigt.

JSON

{
    "Parameters": {
        "VPC": {
            "Type": "String",
            "Default": "vpc-123456"
        },
        "VpcAzs": {
            "Type": "CommaDelimitedList",
            "Default": "us-west-2a, us-west-2b, us-west-2c"
        },
        "DbSubnetIpBlocks": {
            "Type": "CommaDelimitedList",
            "Default": "172.16.0.0/26, 172.16.0.64/26, 172.16.0.128/26"
        }
    },
    "Resources": {
        "DbSubnet1": {
            "Type": "AWS::EC2::Subnet",
            "Properties": {
                "AvailabilityZone": {
                    "Fn::Select": [
                      0,
                      { 
                        "Ref": "VpcAzs" 
                      }
                   ]
                },
                "VpcId": {
                    "Ref": "VPC"
                },
                "CidrBlock": {
                    "Fn::Select": [
                        0,
                        { "Ref": "DbSubnetIpBlocks" }
                    ]
                }
            }
        },
        "DbSubnet2": {
            "Type": "AWS::EC2::Subnet",
            "Properties": {
                "AvailabilityZone": {
                    "Fn::Sub": [
                        "${AWS::Region}${AZ}",
                        {
                            "AZ": {
                                "Fn::Select": [
                                    1,
                                    { "Ref": "VpcAzs" }
                                ]
                            }
                        }
                    ]
                },
                "VpcId": {
                    "Ref": "VPC"
                },
                "CidrBlock": {
                    "Fn::Select": [
                        1,
                        { "Ref": "DbSubnetIpBlocks" }
                    ]
                }
            }
        },
        "DbSubnet3": {
            "Type": "AWS::EC2::Subnet",
            "Properties": {
                "AvailabilityZone": {
                    "Fn::Sub": [
                        "${AWS::Region}${AZ}",
                        {
                            "AZ": {
                                "Fn::Select": [
                                    2,
                                    { "Ref": "VpcAzs" }
                                ]
                            }
                        }
                    ]
                },
                "VpcId": {
                    "Ref": "VPC"
                },
                "CidrBlock": {
                    "Fn::Select": [
                        2,
                        { "Ref": "DbSubnetIpBlocks" }
                    ]
                }
            }
        }
    }
}

YAML

Parameters:
  VPC:
    Type: String
    Default: vpc-123456
  VpcAzs:
    Type: CommaDelimitedList
    Default: us-west-2a, us-west-2b, us-west-2c
  DbSubnetIpBlocks:
    Type: CommaDelimitedList
    Default: 172.16.0.0/26, 172.16.0.64/26, 172.16.0.128/26
Resources:
  DbSubnet1:
    Type: AWS::EC2::Subnet
    Properties:
      AvailabilityZone: !Select
        - 0 
        - !Ref VpcAzs
      VpcId: !Ref VPC
      CidrBlock: !Select
        - 0
        - !Ref DbSubnetIpBlocks
  DbSubnet2:
    Type: AWS::EC2::Subnet
    Properties:
      AvailabilityZone: !Sub
        - ${AWS::Region}${AZ}
        - AZ: !Select
            - 1
            - !Ref VpcAzs
      VpcId: !Ref VPC
      CidrBlock: !Select
        - 1
        - !Ref DbSubnetIpBlocks
  DbSubnet3:
    Type: AWS::EC2::Subnet
    Properties:
      AvailabilityZone: !Sub
        - ${AWS::Region}${AZ}
        - AZ: !Select
            - 2
            - !Ref VpcAzs
      VpcId: !Ref VPC
      CidrBlock: !Select
        - 2
        - !Ref DbSubnetIpBlocks

CloudFormation unterstützt auch die Verwendung von dynamischen Referenzen, um Eigenschaftswerte dynamisch festzulegen. Sie müssen zum Beispiel auf sichere Strings verweisen, die im Systems Manager Parameter Store gespeichert sind. Weitere Informationen finden Sie unter Abrufen von in anderen Diensten gespeicherten Werten mit Hilfe von dynamischen Referenzen.

Sie können auch Pseudoparameter innerhalb einer Ref- oder Sub-Funktion verwenden, um Werte dynamisch zu füllen. Weitere Informationen finden Sie unter Erhalten Sie AWS-Werte mit Pseudo-Parametern.