AWS CloudFormation テンプレートリファレンス – 組み込み関数(Intrinsic Function)

2013.11.03

AWS CloudFormationテンプレートリファレンス、第2弾は。『組み込み関数(Intrinsic Function)』。普段使っているテンプレートの中にもバンバン出て来ます。適切な形で使うととても効果的です。


AWS CloudFormationでは、幾つかの便利なビルトイン関数を提供しています。

目次

 

Fn::Base64

組み込み関数FN::Base64は、入力文字列をBase64表現で返します。この機能は、通常、UserDataプロパティを経由してAmazon EC2インスタンスにエンコードされたデータを渡すために使用されます。

宣言例

{ "Fn::Base64" : valueToEncode }

パラメータ

valueToEncode
Base64形式で変換させたい文字列値。

リターン値

Base64で変換された文字列値を返します。

記述例

{ "Fn::Base64" : "AWS CloudFormation" }

 

Fn::FindInMap

組み込み関数Fn:FindInMapはマッピングセクションで宣言されている2つのレベルのマップで宣言されたキーに対応する値を返します。

宣言例

"Fn::FindInMap" : [ "MapName", "TopLevelKey", "SecondLevelKey"]

パラメータ

MapName
keyとvalueを含む、マッピングセクションで宣言されているマッピングの論理名。
TopLevelKey
トップレベルのキー名。この値はkey-valueペアのリストが返ってきます。
SecondLevelKey
セカンドレベルのキー名。TopLevelKeyに割り当てられたリストから、キーのいずれかに設定されているもの。

リターン値

SecondLevelKeyに割り当てられている値を返します。

記述例

以下例では、AMIの情報とリージョンを紐付けた単一のマップ:RegionMapのマッピングセクションを持つテンプレートで、Fn:FindInMapを使う方法を示しています。

  • マップは様々なAWSのリージョンに対応する5つのトップレベルキーを持っています。
  • トップレベルの各キーは、セカンドレベルのキー、3264のリストが割り当てられています。これはAMIのアーキテクチャに対応したものです。
  • セカンドレベルキーの値にはそれぞれ、対応した適切なAMI名が割り当てられています。
{
  ...
  "Mappings" : {
    "RegionMap" : {
      "us-east-1" : { "32" : "ami-6411e20d", "64" : "ami-7a11e213" },
      "us-west-1" : { "32" : "ami-c9c7978c", "64" : "ami-cfc7978a" },
      "eu-west-1" : { "32" : "ami-37c2f643", "64" : "ami-31c2f645" },
      "ap-southeast-1" : { "32" : "ami-66f28c34", "64" : "ami-60f28c32" },
      "ap-northeast-1" : { "32" : "ami-9c03a89d", "64" : "ami-a003a8a1" }
    }
  },

  "Resources" : {
     "myEC2Instance" : {
        "Type" : "AWS::EC2::Instance",
        "Properties" : {
           "ImageId" : { "Fn::FindInMap" : [ "RegionMap", { "Ref" : "AWS::Region" }, "32"]},
           "InstanceType" : "m1.small"
        }
     }
 }
}

上記例のテンプレートは、イメージIDプロパティがFindMap関数によって設定されるAWS::EC2::Instanceリソースを含んでいます。

  • MapNameは、この例ではRegionMapに設定されています。
  • TopLevelKeyは、スタックが作成されるリージョンに設定されています。この値は、擬似パラメータ:AWS::Regionを使う事によって決定されます。
  • SecondLevelKeyは、利用したいアーキテクチャを指定しています。この例では32が設定されています。

FindInMapは、対応付けられているMapから得られるAMIの値を返します。us-east-1で32ビットインスタンスが指定された場合、FindInMapami-6411e20dを返します。

 

Fn::GetAtt

組み込み関数:Fn:GetAttはテンプレートのリソースの指定した属性値を返します。

宣言例

"Fn::GetAtt" : [ "logicalNameOfResource", "attributeName" ]

パラメータ

logicalNameOfResource
取得したい値が含まれているリソースの論理名。
attributeName
取得したい値を指し示すリソース属性名。リソースタイプの使用可能な属性の詳細については、リソースのリファレンスページをご参照ください。

リターン値

指定した情報に対応する値。

記述例

以下例は論理名:MyLBを持つロードバランサーのDNS名("DNSName")を指定しています。

"Fn::GetAtt" : [ "MyLB" , "DNSName" ]

取得可能な属性一覧

Fn:GetAttを使って取得出来る要素は以下の通り。

リソース型名 属性 詳細
AWS::CloudFormation::WaitCondition Data 指定されたWait Conditonの信号(signals)からのUniqueIDとデータ値を含むJSON形式の文字列。詳細についてはCreating Wait Conditions in a Templateをご参照ください。
例): {"Signal1":"Step 1 complete.","Signal2":"Step 2 complete."}
AWS::CloudFormation::Stack Outputs.NestedStackOutputName 指定したネストしているスタックからのOutput値を返します。
NestedStackOutputNameは出力させたい値の名前になります。
AWS::CloudFront::Distribution DomainName CloudFrontのドメイン名を返します。
例: http://d2fadu0nynjpfn.
cloudfront.net/
AWS::EC2::EIP AllocationId 使っているVPCに対するAWSがアサインしている現在のアドレスのIDを返します。VPCはElastic IPアドレスのみ返します。
例: eipalloc-5723d13e
AWS::EC2::Instance AvailabilityZone 指定したインスタンスが起動しているアベイラビリティゾーンを返します。
例: us-east-1b
AWS::EC2::Instance PrivateDnsName 指定したインスタンスのプライベートDNS名を返します。
例: ip-10-24-34-0.ec2.internal
AWS::EC2::Instance PublicDnsName 指定したインスタンスのDNS名を返します。
例: ec2-107-20-50-45.compute-1.amazonaws.com
AWS::EC2::Instance PrivateIp 指定したインスタンスのプライベートIPアドレスを返します。
例: 10.24.34.0
AWS::EC2::Instance PublicIp 指定したインスタンスのパブリックIPアドレスを返します。
例: 192.0.2.0
AWS::EC2::NetworkInterface PrimaryPrivateIpAddress 指定したネットワークインタフェースのプライマリープライベートIPアドレスを返します。
例: 10.0.0.192
AWS::EC2::NetworkInterface SecondaryPrivateIpAddresses 指定したネットワークインタフェースのセカンダリープライベートIPアドレスを返します。
例: ["10.0.0.161", "10.0.0.162", "10.0.0.163"]
AWS::EC2::SubnetNetworkAclAssociation AssociationId サブネットに割り当てられたネットワークACLのIDを返します。
AWS::ElastiCache::CacheCluster ConfigurationEndpoint.Address キャッシュクラスタのエンドポイントURLのDNS名を返します。
AWS::ElastiCache::CacheCluster ConfigurationEndpoint.Port キャッシュクラスタのエンドポイントURLの接続ポートを返します。
AWS::ElasticBeanstalk::Environment EndpointURL AWS環境に対するロードバランサーのエンドポイントURLを返します。
例: awseb-myst-myen-132MQC4KRLAMD-1371280482.us-east-1.elb.amazonaws.com
AWS::ElasticLoadBalancing::LoadBalancer CanonicalHostedZoneName ロードバランサーに関連するRoute53のHosted Zoneの名称を返します。
例: mystack-myelb-15HMABG9ZCN57-1013119603.us-east-1.elb.amazonaws.com
AWS::ElasticLoadBalancing::LoadBalancer CanonicalHostedZoneNameID ロードバランサーに関連するRoute53のHosted ZoneのIDを返します。
例: Z3DZXE0Q79N41H
AWS::ElasticLoadBalancing::LoadBalancer DNSName ロードバランサーのDNS名を返します。
例: mystack-myelb-15HMABG9ZCN57-1013119603.us-east-1.elb.amazonaws.com
AWS::ElasticLoadBalancing::LoadBalancer SourceSecurityGroup.GroupName ロードバランサーのバックエンドにあるEC2アプリケーションインスタンスのインバウンドルールの一部として使用する事が出来る、セキュリティグループの名称を返します。
例: amazon-elb
AWS::ElasticLoadBalancing::LoadBalancer SourceSecurityGroup.OwnerAlias 対象セキュリティグループのオーナー情報を返します。
例: amazon-elb-sg
AWS::IAM::AccessKey SecretAccessKey 指定アクセスキーに対応するシークレットアクセスキー情報を返します。
例: wJalrXUtnFEMI/
K7MDENG/bPxRfiCYzEX
AMPLEKEY
AWS::IAM::Group Arn 指定IAMユーザーのARNを返します。
例: arn:aws:iam::123456789012:
group/mystack-mygroup-1DZETITOWEKVO
AWS::IAM::User Arn 指定IAMユーザーのARNを返します。
例: arn:aws:iam::123456789012:
group/mystack-myuser-1CCXAFG2H2U4D
AWS::RDS::DBInstance Endpoint.Address DBの接続エンドポイントを返します。
例: mystack-mydb-1apw1j4phylrk.cg034hpkmmjt.us-east-1.rds.amazonaws.com
AWS::RDS::DBInstance Endpoint.Port DBが受け入れる接続ポート番号を返します。
例: 3306
AWS::S3::Bucket DomainName 指定バケットのDNS名を返します。
例: mystack-mybucket-kdwwxmddtr2g.s3.amazonaws.com
AWS::S3::Bucket WebsiteURL 指定バケットのAmazon S3 ウェブサイトエンドポイントを返します。
例: http://mystack-mybucket-kdwwxmddtr2g.s3-website-us-east-1.amazonaws.com/
AWS::S3::Bucket Arn 指定バケットのARNを返します。
例: arn:aws:s3:::myAWSBucket
AWS::SQS::Queue Arn 指定キューのARNを返します。
例: arn:aws:sqs:us-east-1:123456789012:mystack-myqueue-15PG5C2FC1CW8
AWS::SQS::Queue QueueName 指定キューの名称を返します。
例: mystack-myqueue-1VF9BKQH5BJVI

 

Fn::GetAZs

組み込み関数Fn::GetAZsは指定リージョンに該当するアベイラビリティゾーン(AZ)のリストを返します。

利用者は別のAZへのアクセス権を持っているので、組み込み関数Fn::GetAZsを使う事でテンプレート作者が呼び出し側のユーザーアクセスに適用したテンプレートを書けるようになります。この事で、指定リージョンに対応するAZの完全なリストをハードコードしなくて済むようになります。

宣言例

"Fn::GetAZs" : "region"

パラメータ

region
AZを取得したいリージョン名。スタックが作成されたリージョンを指定する際は、擬似パラメータ:AWS::Regionを使う事が出来ます。空文字列を指定した場合、この擬似パラメータが扱われます。

リターン値

リージョンに対応するAZのリストを返します。

記述例

{ "Fn::GetAZs" : "" }
{ "Fn::GetAZs" : "us-east-1" }

上記2つの例に対して、AWS CloudFormationはFn::GetAZsを評価し、ユーザーが、us-east-1のリージョンでスタックを作成したと仮定、対応した以下の配列を返します。

[ "us-east-1a", "us-east-1b", "us-east-1c" ]

 

Fn::Join

組み込み関数Fn::Joinは指定された区切り文字(delimiter)で複数の値を連結し、1つの値を返します。区切り文字が空の場合、それらの値は区切り文字無しでそのまま連結されます。

宣言例

"Fn::Join" : [ "delimiter", [ comma-delimited list of values ] ]

パラメータ

delimiter
リスト要素の間に埋め込む値。リスト要素間のみに連結され、データ末尾には付きません。
listOfValues
連結させたい要素の配列。

リターン値

連結された文字列を返します。

記述例

以下例では、"a:b:c"が返ります。

"Fn::Join" : [ ":", [ "a", "b", "c" ] ]

 

Fn::Select

組み込み関数Fn::Selectは、リスト要素に対してインデックス指定をする事で単一の値を返します。

重要:
Fn::Selectはnull値や配列指定範囲外のインデックス等をチェックしていません。該当した場合はエラーが発生しますので、事前にそれらのチェックは必要です。

宣言例

{ "Fn::Select" : [ index, listOfObjects ] }

パラメータ

index
取得したい要素のインデックス値。N個の要素配列の場合、入る値は『0』から『N-1』の範囲内で無ければなりません。
listOfObjects
取得したい要素を含む配列。NULL値が含まれていてはなりません。

リターン値

選択したインデックス要素の値。

記述例

下記例で得られる値はgrapesです。

{ "Fn::Select" : [ "1", [ "apples", "grapes", "oranges", "mangoes" ] ] }

 

Ref

組み込み関数Refは、指定されたパラメータまたはリソースの値を返します。

  • パラメータの論理名を指定すると、パラメータの値を返します。
  • リソースの論理名を指定した場合、一般的に参照用に使用出来る値(※後述一覧参照)を返します。

テンプレートにリソースを宣言していて、名称で別のテンプレートリソースを指定する必要が有る時は、それらのリソースを参照するためにRefを使用する事が出来ます。一般的には、Refはリソースの名前を返します。例えば、AWS::AutoScaling::AutoScalingGroupはオートスケーリンググループのリソースの名前を返します。

幾つかのリソースについては、リソースコンテキスト内に於ける別の重要な意味を持つ情報を返す事があります。AWS::EC2::EIPリソースはインスタンスに対するIPアドレスを返し、AWS::EC2::InstanceはインスタンスIDを返します。

Refが返す値については後述する表にて詳細をご参照ください。また、Ref関数の出力内容はOutputメッセージにRefを追加する事で確認する事が出来ます。

宣言例

"Ref" : "logicalName"

パラメータ

logicalName
参照したいリソースまたはパラメータの論理名。

リターン値

参照した要素が返す値。

記述例

EC2のインスタンスIDを必要としている以下Elastic IPのリソース宣言では、MyEC2InstanceリソースのインスタンスIDを参照するためにRef関数を使用しています。

"MyEIP" : {
   "Type" : "AWS::EC2::EIP",
   "Properties" : {
      "InstanceId" : { "Ref" : "MyEC2Instance" }
   }
}

Ref関数で得られるリソースのリターン値一覧

リソースタイプ 参照値 リターン値の例
AWS::AutoScaling::AutoScalingGroup Name mystack-myasgroup-NT5EUXTNTXXD
AWS::AutoScaling::LaunchConfiguration Name mystack-mylaunchconfig-1DDYF1E3B3I
AWS::AutoScaling::ScalingPolicy Name mystack-myaspolicy-1DDYF1E3B3I
AWS::AutoScaling::Trigger Name mystack-mytrigger-7GQPDS5YHI5B
AWS::CloudFormation::Stack Stack ID arn:aws:cloudformation:us-east-1:
803981987763:stack/
mystack-mynestedstack-sggfrhxhum7w/
f449b250-b969-11e0-a185-5081d0136786
AWS::CloudFormation::WaitCondition Name arn:aws:cloudformation:us-east-1:
803981987763:stack/mystack/
c325e210-bdf2-11e0-9638-
50690880c386/mywaithandle
AWS::CloudFormation::WaitConditionHandle Wait Condition Signal URL https://cloudformation-waitcondition-us-east-1.
s3.amazonaws.com/
arn%3Aaws%3Acloudformation%3Aus-east-1%3
A803981987763%3Astack%2Fwaittest%
2F054a33d0-bdee-11e0-8816-
5081c490a786%2FmyWaitHandle?
Expires=1312475488&
AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE&
Signature=tUsrW3WvWVT46K
69zMmgbEkwVGo%3D
AWS::CloudFront::Distribution Distribution ID E27LVI50CSW06W
AWS::CloudWatch::Alarm Name mystack-myalarm-3AOHFRGOXR5T
AWS::EC2::Volume Volume ID vol-3cdd3f56
AWS::EC2::VolumeAttachment Name mystack-myvola-ERXHJITXMRLT
AWS::EC2::EIP Elastic IP Address 192.0.2.0
AWS::EC2::EIPAssociation Name mystack-myeipa-1NU3IL8LJ313N
AWS::EC2::Instance Instance ID i-636be302
AWS::EC2::SecurityGroup Name mystack-mysecuritygroup-QQB406M8FISX
AWS::EC2::SecurityGroupIngress Name mysecuritygroupingress
AWS::EC2::Subnet Name subnet-e19f0178
AWS::ElastiCache::SubnetGroup Name myCachesubnetgroup
AWS::ElasticLoadBalancing::LoadBalancer Name mystack-myelb-1WQN7BJGDB5YQ
AWS::ElasticBeanstalk::Application Name mystack-myapplication-FM6BIXY7U8PK
AWS::ElasticBeanstalk::Environment Name mystack-myenv-LKGNQSFHO1DB
AWS::IAM::AccessKey AccessKeyId AKIAIOSFODNN7EXAMPLE
AWS::IAM::Group GroupName mystack-mygroup-1DZETITOWEKVO
AWS::IAM::User UserName mystack-myuser-1CCXAFG2H2U4D
AWS::RDS::DBInstance Name mystack-mydb-ea5ugmfvuaxg
AWS::RDS::DBSecurityGroup Name mystack-mydbsecuritygroup-1k5u5dxjb0nxs
AWS::S3::Bucket Name mystack-mys3bucket-1hbsmonr9mytq
AWS::SDB::Domain Name mystack-mysdbdomain-IVNAOZTDFVXL
AWS::SNS::Topic Topic ARN arn:aws:sns:us-east-1:
123456789012:mystack-mytopic-NZJ5JSMVGFIE
AWS::SQS::Queue Queue URL https://sqs.us-east-1.amazonaws.com/
803981987763/aa4-MyQueue-Z5NOSZO2PZE9
Pseudo Parameter AWS::Region us-east-1
Pseudo Parameter AWS::StackName MyStack