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 或 CloudFormation 提供的參數類型。您也可以新增 Description 屬性，描述您應該指定的值類型。您使用建立堆疊精靈中的範本時，指定參數頁面上會出現參數的名稱和描述。

注意

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

針對有預設值的參數，除非使用者指定另一個值，否則 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 屬性不會遮罩任何儲存在下列資訊中的資訊：

  • Metadata 範本區段。CloudFormation 不會轉換、修改或標記您在 Metadata 區段中包含的任何資訊。若要取得更多資訊，請參閱中繼資料。

  • Outputs 範本區段。如需詳細資訊，請參閱輸出。

  • 資源定義的 Metadata 屬性。如需詳細資訊，請參閱 Metadata 屬性。

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

重要

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

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

重要

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

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

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

Type

參數的資料類型 (DataType)。

必要：是

CloudFormation 支援下列參數類型：

String

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

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

Number

整數或浮點數。CloudFormation 會將參數值驗證為數字；不過，當您在範本中的其他位置使用參數時 (例如，使用 Ref 內建函數)，參數值會變成字串。

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

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

List<Number>

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

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

CommaDelimitedList

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

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

AWS 特定參數類型

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

Systems Manager 參數類型

對應至 Systems Manager 參數存放區中現有參數的參數。您可以將 Systems Manager 參數索引鍵指定為 Systems Manager 參數類型的值，而 CloudFormation 會擷取參數存放區中的最新值來用於堆疊。如需更多詳細資訊，請參閱 在執行時期指定現有資源。

參數的一般要求

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

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

  • 每個參數都必須獲指定邏輯名稱 (也稱為邏輯 ID)，其必須為英數字元，而且在範本的所有邏輯名稱之間必須是唯一的。

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

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

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

範例

簡單字串參數

下列範例宣告類型 String 名為 InstanceTypeParameter 的參數。此參數可讓您指定堆疊的 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

密碼參數

下列範例宣告類型 String 名為 DBPwd 的參數，沒有預設值。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"

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

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

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 也支援使用動態參考來動態指定屬性值。例如，您可能需要參考在 Systems Manager 參數存放區中儲存的安全字串。如需更多詳細資訊，請參閱 使用動態參考取得存放在其他服務中的值。

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