AWS CloudFormation テンプレートリファレンス – 組み込み関数(Intrinsic Function)
- Template Reference - AWS CloudFormation
- CloudFormation | 特集カテゴリー | Developers.IO
- AWS CloudFormationテンプレートリファレンス | シリーズ | Developers.IO
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つのトップレベルキーを持っています。
- トップレベルの各キーは、セカンドレベルのキー、32、64のリストが割り当てられています。これは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ビットインスタンスが指定された場合、FindInMapはami-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 |