AWS CloudFormation
ユーザーガイド (API バージョン 2010-05-15)

Parameters

オプションの Parameters セクションを使用して、テンプレートをカスタマイズします。パラメーターを使用すると、スタックを作成または更新するたびにテンプレートにカスタム値を入力できます。

テンプレートでのパラメーターの定義

以下の例では、InstanceTypeParameter というパラメーターを宣言します。このパラメーターを使用すると、スタックの作成または更新時に使用するスタックの Amazon EC2 インスタンスタイプを指定できます。

InstanceTypeParameter には、t2.micro のデフォルトの値があることに注意してください。これは、別の値が用意されていない限り、AWS CloudFormation がスタックをプロビジョニングするために使用する値です。

JSON

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

YAML

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

テンプレート内でのパラメーターの参照

パラメーターを参照するには、Ref 組み込み関数を使用します。AWS CloudFormation は、パラメーターの値を使用してスタックをプロビジョニングします。同じテンプレートの Resources および Outputs セクションのパラメーターを参照できます。

次の例では、EC2 インスタンスリソースの InstanceType プロパティが InstanceTypeParameter パラメーター値を参照します。

JSON

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

YAML

Ec2Instance: Type: AWS::EC2::Instance Properties: InstanceType: Ref: InstanceTypeParameter ImageId: ami-2f726546

パラメーターの一般要件

パラメーターを使用するときに以下の要件が適用されます。

  • AWS CloudFormation テンプレートに指定できるパラメーターは最大 60 個です。

  • 各パラメーターには、英数字でテンプレート内のどの論理名とも重複しない論理名 (論理 ID と呼ばれます) を指定する必要があります。

  • 各パラメーターには、AWS CloudFormation でサポートされているパラメータータイプを割り当てることができます。詳細については、「 Type」を参照してください。

  • AWS CloudFormation がスタックを正常にプロビジョニングするには、各パラメーターに実行時に値を割り当てる必要があります。別の値が指定されている場合を除き、必要に応じて、使用する AWS CloudFormation のデフォルト値を指定できます。

  • パラメーターは、同じテンプレート内から宣言および参照する必要があります。テンプレートの Resources および Outputs セクションのパラメーターを参照できます。

構文

Parameters セクションは、キー名 Parameters で構成されます。セクション内のパラメーターごとに、論理的な名前とタイプを宣言する必要があります。必要に応じて、追加のプロパティも指定できます。

AWS CloudFormation は、パラメータータイプ StringNumberList<Number>CommaDelimitedList、AWS 固有のタイプ、または SSM パラメータータイプをサポートします。詳細については、「 Type」を参照してください。

重要

重要なパラメーター値 (パスワードなど) の場合は、NoEcho プロパティを true に設定します。これにより、他のユーザーがスタックの詳細を取得すると、このパラメーター値は必ずアスタリスク (*****) として表示されるようになります。

JSON

"Parameters" : { "ParameterLogicalID" : { "Type" : "DataType", "ParameterProperty" : "value" } }

YAML

Parameters: ParameterLogicalID: Type: DataType ParameterProperty: value

プロパティ

AllowedPattern

String 型に使用できるパターンを表す正規表現。

Required: No

AllowedValues

パラメーターに許容される一連の値を含む配列。

Required: No

ConstraintDescription

制約が違反された場合に、制約について説明する文字列。たとえば、制約の説明を指定しないとき、許容されているパターンが [A-Za-z0-9]+ であるパラメーターの場合、ユーザーが無効な値を指定すると次のエラーメッセージが表示されます。

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

must only contain upper and lowercase letters, and numbers などの制約の説明を追加することによって、次のようにカスタマイズされたエラーメッセージを表示することができます。

Malformed input-Parameter MyParameter must only contain upper and lower case letters and numbers

Required: No

Default

スタックの作成時に値を指定しなかった場合に、テンプレートで使用される適切な型の値。パラメーターの制約を定義する場合は、これらの制約に従う値を指定する必要があります。

Required: No

Description

パラメーターについて説明する最大 4000 文字の文字列。

Required: No

MaxLength

String 型に使用できる最大文字数を決定する整数値。

Required: No

MaxValue

Number 型に使用できる数値の最大値を決定する数値。

Required: No

MinLength

String 型に使用できる最小文字数を決定する整数値。

Required: No

MinValue

Number 型に使用できる数値の最小値を決定する数値。

Required: No

NoEcho

スタックの詳細を取得する呼び出しが作成された場合に、必ずパラメーター値をマスクするかどうか。値を true に設定すると、パラメーター値はアスタリスク (*****) でマスクされます。

Required: No

Type

パラメーターのデータ型 (DataType)。

Required: Yes

AWS CloudFormation では次のパラメータータイプをサポートしています。

String

リテラル文字列。

たとえば、次のように指定します。"MyUserName"

Number

整数または浮動小数点値。AWS CloudFormation は、この型のパラメーターを数値として検証しますが、テンプレート内の他の場所で使用した場合には (Ref 組み込み関数を使用した場合など) 文字列として扱います。

たとえば、次のように指定します。"8888"

List<Number>

カンマで区切られた整数または浮動小数点値の配列。AWS CloudFormation は、この型のパラメーターを数値として検証しますが、テンプレート内の他の場所で使用した場合には (Ref 組み込み関数を使用した場合など) 一連の文字列として扱います。

たとえば、"80,20" と指定し、Ref を使用した場合には ["80","20"] となります。

CommaDelimitedList

カンマで区切られたリテラル文字列の配列。文字列の合計数は、カンマの合計数よりも 1 つ多いはずです。また、各メンバー文字列の前後の空白は削除されます。

たとえば、"test,dev,prod" と指定し、Ref を使用した場合には ["test","dev","prod"] となります。

AWS 固有のパラメーター型

Amazon EC2 キーペアの名前や VPC の ID などの AWS の値です。詳細については、「AWS 固有のパラメーター型」を参照してください。

SSM パラメータータイプ

AWS Systems Managerパラメーターストア内の既存のパラメーターに対応するパラメーター。Systems Manager パラメーターキーは SSM パラメーターの値として指定します。AWS CloudFormation は、スタックに使用するパラメーターストアから最新の値を取得します。詳細については、「SSM パラメータータイプ」を参照してください。

注記

AWS CloudFormation は現在のところ SecureString Systems Manager パラメータータイプをサポートしていません。

AWS 固有のパラメーター型

AWS 固有のパラメーター型については、テンプレートのユーザーはアカウントにある既存の AWS 値を指定する必要があります。AWS CloudFormation は、ユーザーの AWS アカウントの既存の値に対して、これらのパラメーター値を検証します。AWS 固有のパラメータータイプは、スタックの作成または更新の開始時に無効な値を見つけるのに役立ちます。

AWS CloudFormation は、ユーザーアカウントの既存の値と照らしてこれらの型の入力値を検証します。たとえば、AWS::EC2::VPC::Id 型の場合、ユーザーはアカウント内およびスタックを作成しているリージョン内に存在する既存の VPC ID を入力する必要があります。

サポートされている AWS 固有のパラメータータイプ

AWS CloudFormation では次の AWS 固有型をサポートしています。

AWS::EC2::AvailabilityZone::Name

アベイラビリティーゾーン名 (us-west-2a など)。

AWS::EC2::Image::Id

Amazon EC2 イメージ ID (ami-ff527ecf など)。AWS CloudFormation コンソールには、このパラメータータイプの値のドロップダウンリストが表示されないことに注意してください。

AWS::EC2::Instance::Id

Amazon EC2 インスタンス ID (i-1e731a32 など)。

AWS::EC2::KeyPair::KeyName

Amazon EC2 のキーペア名。

AWS::EC2::SecurityGroup::GroupName

EC2-Classic またはデフォルトの VPC セキュリティグループ名 (my-sg-abc など)。

AWS::EC2::SecurityGroup::Id

セキュリティグループ ID (sg-a123fd85 など)。

AWS::EC2::Subnet::Id

サブネット ID (subnet-123a351e など)。

AWS::EC2::Volume::Id

Amazon EBS ボリューム ID (vol-3cdd3f56 など)。

AWS::EC2::VPC::Id

VPC ID (vpc-a123baa3 など)。

AWS::Route53::HostedZone::Id

Amazon Route 53 ホストゾーン ID (Z23YXV4OVPL04A など)。

List<AWS::EC2::AvailabilityZone::Name>

リージョンのアベイラビリティーゾーンの配列 (us-west-2a, us-west-2b など)。

List<AWS::EC2::Image::Id>

Amazon EC2 イメージ ID の配列 (ami-ff527ecf, ami-e7527ed7 など)。AWS CloudFormation コンソールには、このパラメータータイプの値のドロップダウンリストが表示されないことに注意してください。

List<AWS::EC2::Instance::Id>

Amazon EC2 インスタンス ID の配列 (i-1e731a32, i-1e731a34 など)。

List<AWS::EC2::SecurityGroup::GroupName>

EC2-Classic またはデフォルトの VPC セキュリティグループ名の配列 (my-sg-abc, my-sg-def など)。

List<AWS::EC2::SecurityGroup::Id>

セキュリティグループ ID の配列 (sg-a123fd85, sg-b456fd85 など)。

List<AWS::EC2::Subnet::Id>

サブネット ID の配列 (subnet-123a351e, subnet-456b351e など)。

List<AWS::EC2::Volume::Id>

Amazon EBS ボリューム ID の配列 (vol-3cdd3f56, vol-4cdd3f56 など)。

List<AWS::EC2::VPC::Id>

VPC ID の配列 (vpc-a123baa3, vpc-b456baa3 など)。

List<AWS::Route53::HostedZone::Id>

Amazon Route 53 ホストゾーン ID の配列 (Z23YXV4OVPL04A, Z23YXV4OVPL04B など)。

SSM パラメータータイプ

SSM パラメータータイプは、Systems Manager パラメーターストア内の既存のパラメーターに対応します。Systems Manager パラメーターキーは SSM パラメーターの値として指定します。AWS CloudFormation は、スタックに使用するパラメーターストアから最新の値を取得します。Systems Manager パラメーターの詳細については、AWS Systems Manager ユーザーガイド の「Systems Manager パラメーターストア」を参照してください。

スタックを作成または更新して変更セットを作成すると、AWS CloudFormation はオペレーションの実行時点でパラメーターストアに存在する任意の値を使用します。指定されたパラメーターが、呼び出し元の AWS アカウントの下のパラメーターストアに存在しない場合、AWS CloudFormation は検証エラーを返します。

変更セットを実行すると、AWS CloudFormation は変更セットで指定されている値を使用します。これらの値は、変更セットの作成時と実行時においてパラメーターストアで変化する可能性があるため、変更セットを実行する前に確認してください。

ヒント

SSM パラメーターの解決された値 は、コンソールのスタックの [Parameters] タブで確認するか、describe-stacks または describe-change-set を実行することにより確認できます。これらは、対応する Systems Manager パラメーターキーのスタック定義で現在使用されている値です。これらの値は、スタックが作成または更新される時に設定されるため、パラメーターストアにおける最新の値とは異なる場合がある点に注意してください。

SSM パラメーターの値は Systems Manager パラメーターキーであるため、以下の動作にも注意してください。

  • スタックの更新の場合、コンソールの [Use existing value] オプションと update-stackUsePreviousValue 属性は、値ではなく既存の Systems Manager パラメーターキーを使用するように AWS CloudFormation に指示します。AWS CloudFormation は、スタックの更新時にパラメーターストアから常に最新の値を取得します。

  • AWS CloudFormation は、対応する値ではなく Systems Manager パラメーターキーで検証を実行できます。検証のため、パラメーターキーを文字列として扱うことができます。パラメーターストアでは、Systems Manager パラメーター値の検証を実行する必要があります。

SSM パラメータータイプの例については、「SSM パラメータータイプ」を参照してください。

サポートされている SSM パラメータータイプ

AWS CloudFormation では次の SSM パラメータータイプをサポートしています。

AWS::SSM::Parameter::Name

Systems Manager パラメーターキーの名前。

パラメーターキーを渡す場合は、このパラメーターを使用します。たとえば、このタイプを使用してパラメーターが存在するかどうかを確認できます。

AWS::SSM::Parameter::Value<String>

値が文字列の Systems Manager パラメーター。これは、パラメーターストア内の String パラメータータイプに対応します。

AWS::SSM::Parameter::Value<List<String>> または AWS::SSM::Parameter::Value<CommaDelimitedList>

値が文字列のリストである Systems Manager パラメーター。これは、パラメーターストア内の StringList パラメータータイプに対応します。

AWS::SSM::Parameter::Value<AWS-specific parameter type>

値が AWS 固有のパラメータータイプである Systems Manager パラメーター。たとえば、次の例は AWS::EC2::KeyPair::KeyName タイプを指定します。

AWS::SSM::Parameter::Value<AWS::EC2::KeyPair::KeyPairName>

AWS::SSM::Parameter::Value<List<AWS-specific parameter type>>

値が AWS 固有のパラメータータイプのリストである Systems Manager パラメーター。たとえば、次の例は AWS::EC2::KeyPair::KeyName タイプのリストを指定します。

AWS::SSM::Parameter::Value<List<AWS::EC2::KeyPair::KeyPairName>>

サポートされていない SSM パラメータータイプ

AWS CloudFormation では次の SSM パラメータータイプをサポートしていません。

  • SecureString Systems Manager パラメータータイプ

  • SSM パラメータータイプのリスト — 例: List<AWS::SSM::Parameter::Value<String>>

AWS CloudFormation コンソールでのパラメーターのグループ化およびソート

AWS CloudFormation コンソールを使用してスタックを作成または更新すると、コンソールに論理 ID により入力パラメーターがアルファベット順に並べられてリストされます。デフォルトの順序を上書きするには、AWS::CloudFormation::Interface メタデータキーを使用できます。パラメーターをグループ化および順序付けすることで、ユーザーがパラメーター値をさらに指定しやすくなります。たとえば、VPC 関連のすべてのパラメーターをグループ化し、アルファベットリスト全体に分散しないようにするとします。

メタデータキーで、作成するグループ、各グループに含めるパラメーター、コンソールで各パラメーターがそのグループ内に表示される順序を指定できます。コンソールで論理 ID の代わりにわかりやすい名前が表示されるように、フレンドリパラメーター名を定義することもできます。メタデータキーで参照するすべてのパラメーターは、テンプレートの Parameters セクションで宣言する必要があります。

AWS::CloudFormation::Interface メタデータキーの詳細と例については、「AWS::CloudFormation::Interface」を参照してください。

基本的な入力パラメーター

以下の例では、Parameters セクションに 2 つのパラメーターが宣言されています。DBPort パラメーターの型は Number で、デフォルトは 3306 です。指定できる最小値は 65535、最大値は 1150 です。DBPwd パラメーターの型は String で、デフォルト値はありません。NoEcho プロパティは、スタックの説明の呼び出し (aws cloudformation describe-stacks AWS CLI コマンドなど) によってパラメーター値が返されるのを防ぐために、true に設定されています。指定できる最小値は 1、最大値は 41 です。パターンには、英文字の大文字と小文字、および数字を使用できます。

JSON

"Parameters" : { "DBPort" : { "Default" : "3306", "Description" : "TCP/IP port for the database", "Type" : "Number", "MinValue" : "1150", "MaxValue" : "65535" }, "DBPwd" : { "NoEcho" : "true", "Description" : "The database admin account password", "Type" : "String", "MinLength" : "1", "MaxLength" : "41", "AllowedPattern" : "^[a-zA-Z0-9]*$" } }

YAML

Parameters: DBPort: Default: 3306 Description: TCP/IP port for the database Type: Number MinValue: 1150 MaxValue: 65535 DBPwd: NoEcho: true Description: The database admin account password Type: String MinLength: 1 MaxLength: 41 AllowedPattern: ^[a-zA-Z0-9]*$

AWS 固有のパラメーター型

AWS 固有のパラメーター型を使用する場合、スタックを作成または更新するためにテンプレートを使用するユーザーは、必ず自分のアカウントおよび現在のスタックのリージョンにある既存の AWS 値を指定する必要があります。AWS 固有のパラメーター型は、AWS CloudFormation がリソースを作成または更新する前に、これらの型の入力値が存在し、正しい値であることを確認するのに役立ちます。たとえば、AWS::EC2::KeyPair::KeyName パラメーター型を使用すると、AWS CloudFormation はリソース (Amazon EC2 インスタンスなど) を作成する前に、入力値をユーザーの既存のキーペア名に照らして検証します。

ユーザーが AWS マネジメントコンソール を使用している場合、AWS CloudFormation によって AWS 固有のパラメーター型に有効な値が事前に設定されます。そのため、ユーザーは特定の名前や ID を記憶したり、正確に入力したりする必要がありません。ドロップダウンリストから 1 つ以上の値を選択するだけです。また、パラメータータイプに応じて、ユーザーは ID、名前、Name タグ値で値を検索することもできます。詳細については、「 スタック名とパラメーターを指定します。」を参照してください。

以下の例では、AWS::EC2::KeyPair::KeyName および AWS::EC2::Subnet::Id の型の 2 つのパラメーターが宣言されています。これらの型では、有効な値は既存のキーペア名およびサブネット ID に制限されています。mySubnetIDs パラメーターがリストとして指定されているので、ユーザーは 1 つ以上のサブネット ID を指定できます。

JSON

"Parameters" : { "myKeyPair" : { "Description" : "Amazon EC2 Key Pair", "Type" : "AWS::EC2::KeyPair::KeyName" }, "mySubnetIDs" : { "Description" : "Subnet IDs", "Type" : "List<AWS::EC2::Subnet::Id>" } }

YAML

Parameters: myKeyPair: Description: Amazon EC2 Key Pair Type: "AWS::EC2::KeyPair::KeyName" mySubnetIDs: Description: Subnet IDs Type: "List<AWS::EC2::Subnet::Id>"

AWS CLI と API のサポート

現時点では、AWS CLI または AWS CloudFormation API を使用して、AWS 固有のパラメーターの有効な値のリストを表示することはできませんが、aws cloudformation get-template-summary コマンドまたは GetTemplateSummary API を使用して、パラメーター型などの各パラメーターの情報を表示することは可能です。

カンマ区切りリストのパラメーター型

単一のパラメーターに複数の文字列値を指定するには、CommaDelimitedList パラメーター型を使用します。このように、さまざまなパラメーターの多数使用するのではなく、単一のパラメーターを使用することで、複数の値を指定することができます。たとえば、独自の CIDR ブロックで 3 種類のサブネットを作成した場合に、3 つの異なるパラメーターを使って 3 種類の CIDR ブロックを指定することは可能です。しかし、3 つの CIDR ブロックを指定するパラメーターを 1 つだけ使った方が簡潔に記述できます。その例を次に示します。

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
"DbSubnet1" : { "Type" : "AWS::EC2::Subnet", "Properties" : { "AvailabilityZone" : {"Fn::Join" : ["",[ { "Ref" : "AWS::Region" }, { "Fn::Select" : [ "0", {"Ref" : "VpcAzs"} ] } ] ]} , "VpcId" : { "Ref" : "VPC" }, "CidrBlock" : { "Fn::Select" : [ "0", {"Ref" : "DbSubnetIpBlocks"} ] } } }, "DbSubnet2" : { "Type" : "AWS::EC2::Subnet", "Properties" : { "AvailabilityZone" : {"Fn::Join" : ["",[ { "Ref" : "AWS::Region" }, { "Fn::Select" : [ "1", {"Ref" : "VpcAzs"} ] } ] ]} , "VpcId" : { "Ref" : "VPC" }, "CidrBlock" : { "Fn::Select" : [ "1", {"Ref" : "DbSubnetIpBlocks"} ] } } }, "DbSubnet3" : { "Type" : "AWS::EC2::Subnet", "Properties" : { "AvailabilityZone" : {"Fn::Join" : ["",[ { "Ref" : "AWS::Region" }, { "Fn::Select" : [ "2", {"Ref" : "VpcAzs"} ] } ] ]} , "VpcId" : { "Ref" : "VPC" }, "CidrBlock" : { "Fn::Select" : [ "2", {"Ref" : "DbSubnetIpBlocks"} ] } } }
YAML
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]

SSM パラメータータイプ

AWS::SSM::Parameter::Value<String> type

以下のテンプレートでは、AWS::SSM::Parameter::Value<String> パラメータータイプを宣言します。

JSON
{ "Parameters": { "InstanceType": { "Type": "AWS::SSM::Parameter::Value<String>" } }, "Resources": { "Instance": { "Type": "AWS::EC2::Instance", "Properties": { "InstanceType": { "Ref": "InstanceType" } } } } }
YAML
Parameters: InstanceType: Type: 'AWS::SSM::Parameter::Value<String>' Resources: Instance: Type: 'AWS::EC2::Instance' Properties: InstanceType: !Ref InstanceType

次のコマンドは、サンプルテンプレートに基づいてスタックを作成します。InstanceType テンプレートパラメーターの値として Systems Manager パラメーターキー (myInstanceType) を指定します。これは、myInstanceType パラメーターが呼び出し元の AWS アカウントの下のパラメーターストアに存在することを前提としています。

aws cloudformation create-stack --stack-name S1 --template-body example template --parameters ParameterKey=InstanceType,ParameterValue=myInstanceType

 

AWS::SSM::Parameter::Value<AWS::EC2::Image::Id> type

以下のテンプレートでは、AWS::SSM::Parameter::Value<AWS::EC2::Image::Id> パラメータータイプを宣言します。

JSON
{ "Parameters": { "ImageId": { "Type": "AWS::SSM::Parameter::Value<AWS::EC2::Image::Id>" } }, "Resources": { "Instance": { "Type": "AWS::EC2::Instance", "Properties": { "ImageId": { "Ref": "ImageId" } } } } }
YAML
Parameters: ImageId: Type: 'AWS::SSM::Parameter::Value<AWS::EC2::Image::Id>' Resources: Instance: Type: 'AWS::EC2::Instance' Properties: ImageId: !Ref ImageId

次のコマンドは、サンプルテンプレートに基づいてスタックを作成します。ImageId テンプレートパラメーターの値として Systems Manager パラメーターキー (myLatestAMI) を指定します。これは、myLatestAMI パラメーターが呼び出し元の AWS アカウントの下のパラメーターストアに存在することを前提としています。

aws cloudformation create-stack --stack-name S2 --template-body example template --parameters ParameterKey=ImageId,ParameterValue=myLatestAMI