CloudFormation 範本 Parameters 語法 - AWS CloudFormation
語法屬性參數的一般要求範例相關資源

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

CloudFormation 範本 Parameters 語法

使用選用的 Parameters 區段自訂您的範本。您可以使用 參數，在每次建立或更新堆疊時，將自訂值輸入範本。透過在範本中使用參數，您可以建置可重複使用且彈性的範本，可根據特定案例量身打造。

透過定義適當類型的參數，您可以在使用主控台建立堆疊時，從現有資源的識別符清單中選擇。如需詳細資訊，請參閱使用 CloudFormation 提供的參數類型在執行時間指定現有的資源。

參數是指定堆疊資源屬性值的熱門方式。不過，可能有些設定取決於區域，或有些複雜，讓使用者因為其他條件或依存性而無法找出。在這些情況下，您可能想要將一些邏輯放入範本本身，讓使用者可以指定更簡單的值 （或完全不指定），以取得他們想要的結果，例如使用映射。如需詳細資訊，請參閱CloudFormation 範本 Mappings 語法。

語法

您可以在範本的 Parameters區段中宣告參數，該區段使用下列一般語法：

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

參數包含定義其值的屬性清單以及針對其值的限制條件。唯一需要的屬性是 Type，可以是 String、 Number或 a CloudFormation提供的參數類型。您也可以新增Description屬性，描述您應該指定的值類型。當您在建立堆疊精靈中使用範本時，參數的名稱和描述會出現在指定參數頁面中。

注意

根據預設， CloudFormation 主控台會依其邏輯 ID 字母順序列出輸入參數。若要覆寫此預設排序並將相關參數分組在一起，您可以使用範本中的AWS::CloudFormation::Interface中繼資料金鑰。如需詳細資訊，請參閱AWS::CloudFormation::Interface。

對於具有預設值的參數，除非使用者指定另一個值，否則 CloudFormation 會使用預設值。如果您省略預設屬性，使用者必須指定該參數的值。不過，要求使用者輸入值並不保證該值有效。若要驗證參數的值，您可以宣告限制條件或指定 AWS特定的參數類型。

對於沒有預設值的參數，使用者必須在建立堆疊時指定金鑰名稱值。如果沒有，則 CloudFormation 無法建立堆疊並擲回例外狀況：

Parameters: [KeyName] must have values

屬性

AllowedPattern

規則表達式，代表 String 或 CommaDelimitedList 類型允許的模式。當套用於類型 String 參數時，模式必須匹配提供的整個參數值。當套用於類型 CommaDelimitedList 參數時，模式必須匹配清單中的每個值。

必要：否

AllowedValues

陣列，包含參數的允許值清單。當套用於類型 String 參數時，參數值必須是允許值之一。當套用於類型 CommaDelimitedList 參數時，清單中的每個值必須是指定的允許值之一。

必要：否

注意

如果您使用的是 ，YAML而且想要使用 的 Yes和 No字串AllowedValues，請使用單引號來防止YAML剖析器考慮這些布林值。

ConstraintDescription

字串，說明違反限制時的限制。例如，具有允許模式 [A-Za-z0-9]+ 的參數會在使用者指定無效值時顯示下列錯誤訊息，但沒有限制描述：

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

透過新增限制描述，例如只能包含字母 (大寫和小寫) 及數字，您可以顯示下列自訂錯誤訊息：

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

必要：否

Default

建立堆疊時，範本要在未指定值時使用的適當類型值。如果您定義參數的限制，則必須指定遵循這些限制的值。

必要：否

Description

多達 4000 個字元的字串，可說明參數。

必要：否

MaxLength

整數值，決定您想要針對 String 類型允許的最大字元數。

必要：否

MaxValue

數值，決定您想要針對 Number 類型允許的最大數值。

必要：否

MinLength

整數值，決定您想要針對 String 類型允許的最小字元數。

必要：否

MinValue

數值，決定您想要針對 Number 類型允許的最小數值。

必要：否

NoEcho

是否要遮罩參數值，以防止其顯示在主控台、命令列工具或 中API。如果您將 NoEcho 屬性設定為 true， 會針對描述堆疊或堆疊事件的任何呼叫 CloudFormation 傳回遮罩為星號 (*****) 的參數值，但存放在下列指定位置的資訊除外。

必要：否

重要

使用 NoEcho 屬性不會遮罩任何儲存在下列資訊中的資訊：

我們強烈建議您不要使用這些機制來包含敏感資訊，例如密碼或秘密。

重要

我們建議您不要直接在 CloudFormation 範本中嵌入敏感資訊，而是在堆疊範本中使用動態參數，以參考存放在 外部和管理的敏感資訊 CloudFormation，例如在 AWS Systems Manager 參數存放區或 中 AWS Secrets Manager。

如需詳細資訊，請參閱請勿在您的範本中內嵌憑證最佳實務。

重要

強烈建議不要在作為資源主要識別碼一部分的資源屬性中包含 NoEcho 參數或任何敏感資料。

當NoEcho參數包含在形成主要資源識別符的 屬性中時， CloudFormation 可以使用主要資源識別符中的實際純文字值。此資源 ID 可能會出現在任何衍生輸出或目的地中。

若要判斷哪些資源屬性包含資源類型的主要識別符，請參閱 中該資源的資源參考文件AWS 資源和屬性類型參考。在 Return values (傳回值) 區段中，Ref 函數傳回值表示組成資源類型主要識別碼的資源屬性。

Type

參數的資料類型 (DataType)。

必要：是

CloudFormation 支援下列參數類型：

String

常值字串。您可以使用下列屬性來宣告限制條件：MinLength、MaxLength、AllowedValues、 Default和 AllowedPattern。

例如，使用者可以指定 "MyUserName"。

Number

整數或 float. CloudFormation validation 參數值作為數字；不過，當您在範本的其他位置使用 參數 （例如，使用Ref內部 函數） 時， 參數值會變成字串。

您可以使用下列屬性來宣告限制條件：MinValue、Default、 MaxValue和 AllowedValues。

例如，使用者可以指定 "8888"。

List<Number>

以逗號分隔的整數或浮點數陣列。 CloudFormation 會將參數值驗證為數字；不過，當您在範本中的其他位置使用參數時 (例如，使用 Ref 內部函數)，參數值會變成字串清單。

例如，使用者可以指定 "80,20"，而 Ref 會產生 ["80","20"]。

CommaDelimitedList

以逗號分隔的常值字串陣列。字串總數應該比逗號總數多一個。此外，還會裁剪每個成員字串的空格。

例如，使用者可以指定 "test,dev,prod"，而 Ref 會產生 ["test","dev","prod"]。

AWS特定參數類型

AWS 值，例如 Amazon EC2金鑰對名稱和 VPC IDs。如需詳細資訊，請參閱在執行時間指定現有資源。

Systems Manager 參數類型

對應至 Systems Manager 參數存放區中現有參數的參數。您可以指定 Systems Manager 參數金鑰做為 Systems Manager 參數類型的值，並從參數存放區 CloudFormation 擷取要用於堆疊的最近值。如需詳細資訊，請參閱在執行時間指定現有資源。

參數的一般要求

以下是使用參數時適用的要求：

  • 範本中最多可以有 200 個參數 CloudFormation 。

  • 每個參數都必須指定一個邏輯名稱 （也稱為邏輯 ID)，該名稱在範本中的所有邏輯名稱中必須是英數字元且是唯一的。

  • 必須為每個參數指派一個 支援的參數類型 CloudFormation。如需詳細資訊，請參閱類型。

  • 每個參數都必須在執行時間指派一個值 CloudFormation ，才能成功佈建堆疊。除非提供另一個值，否則您可以選擇指定預設值 CloudFormation 供 使用。

  • 參數必須在相同的範本內宣告和參考。您可以參考範本之 Resources 和 Outputs 區段中的參數。

範例

簡單字串參數

下列範例宣告名為 InstanceTypeParameter類型的參數String。此參數可讓您指定堆疊的 Amazon EC2執行個體類型。如果在堆疊建立或更新期間未提供任何值， CloudFormation 會使用預設值 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

密碼參數

下列範例宣告名為 DBPwd 類型的參數String，沒有預設值。NoEcho 屬性設定為 true，以防止參數值顯示在堆疊描述中。可指定的最小長度為 1，而可指定的最大長度為 41。此模式允許大小寫字母字元和數字。此範例也說明 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]*$

參考參數

您可以使用 Ref 內部函數來參考參數，而 CloudFormation 使用參數值來佈建堆疊。您可以參考相同範本之 Resources 和 Outputs 區段中的參數。

在下列範例中，EC2執行個體資源的 InstanceType 屬性參考 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

逗號分隔清單參數

當您需要為單一屬性提供多個值時， CommaDelimitedList 參數類型會很有用。下列範例宣告名為 的參數DbSubnetIpBlocks，預設值為以逗號分隔的三個CIDR區塊。

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"

逗號分隔清單參數的傳回值

若要參考參數逗號分隔清單中的特定值，請使用範本 Resources區段中的Fn::Select內部函數。傳遞您想要的物件索引值和物件清單，如下列範例所示。

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::Sub": [
                        "${AWS::Region}${AZ}",
                        {
                            "AZ": {
                                "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: !Sub
        - ${AWS::Region}${AZ}
        - AZ: !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 也支援使用動態參考動態指定屬性值。例如，您可能需要參考存放在 Systems Manager 參數存放區中的安全字串。如需詳細資訊，請參閱使用動態引用獲取存儲在其他服務中的值。

您也可以在 Ref或 Sub函數中使用虛擬參數來動態填入值。如需詳細資訊，請參閱虛擬參數參考。