Ref
The intrinsic function Ref
returns the value of a specified parameter,
resource, or another intrinsic function. This function is commonly used to create references
between resources within a CloudFormation template.
Declaration
JSON
{ "Ref" : "
logicalName
" }
{ "Ref" : "
IntrinsicFunction
" }
YAML
Syntax for the full function name:
Ref:
logicalName
Ref:
IntrinsicFunction
Syntax for the short form:
!Ref
logicalName
!Ref
IntrinsicFunction
Parameters
- logicalName
-
The logical name of the resource or parameter you want to reference.
- IntrinsicFunction
-
The intrinsic function that resolves to a valid string. It should contain references to parameters or identifiers, and should not contain resource logical identifiers.
Return value
The return value of Ref
depends on the type of entity being
referenced:
-
When you specify a parameter's logical name, it returns the value of the parameter. For more information, see CloudFormation template Parameters syntax.
-
When you specify a resource's logical name, it returns a value that you use to identify that resource. Usually, that's the name of the resource. However, for some resources, an identifier is returned that has another significant meaning in the context of the resource. For example, the
AWS::EC2::EIP
resource returns the IP address, and theAWS::EC2::Instance
returns the instance ID. For more information aboutRef
return values for a resource, see the documentation for that resource in the Resource and property reference. -
When you specify an intrinsic function, it returns the output of that function.
Examples
Create references between resources
The following resource declaration for an Elastic IP address needs the instance ID
of an EC2 instance. It uses the Ref
function to specify the instance ID
of the MyEC2Instance
resource declared elsewhere in the
template.
JSON
{ "AWSTemplateFormatVersion":"2010-09-09", "Resources":{
...
"MyEIP":{ "Type":"AWS::EC2::EIP", "Properties":{ "InstanceId":{ "Ref":"MyEC2Instance" } } } } }
YAML
AWSTemplateFormatVersion: 2010-09-09 Resources:
...
MyEIP: Type: "AWS::EC2::EIP" Properties: InstanceId: !Ref MyEC2Instance
Return a resource identifier as stack output
The following examples show how to use the Ref
function to return the
name of an Amazon S3 bucket with the logical name MyBucket
as stack output.
JSON
{ "AWSTemplateFormatVersion":"2010-09-09", "Resources":{ "MyBucket":{ "Type":"AWS::S3::Bucket", "Properties":{ "BucketName":{ "Fn::Sub": "${AWS::StackName}-mybucket" } } } }, "Outputs":{ "BucketNameOutput":{ "Description":"The name of the S3 bucket", "Value":{ "Ref":"MyBucket" } } } }
YAML
AWSTemplateFormatVersion: 2010-09-09 Resources: MyBucket: Type: AWS::S3::Bucket Properties: BucketName: !Sub ${AWS::StackName}-mybucket Outputs: BucketNameOutput: Description: The name of the S3 bucket Value: !Ref MyBucket
Use
Fn::Join
intrinsic function inside Ref
function
Note
When you use the AWS::LanguageExtensions
transform, you can use
Ref
in combination with other intrinsic functions. For
supported functions, see Supported functions.
The following examples show how to set identifiers of resources using the
Fn::Sub
intrinsic function, conditions, and the input for the
Stage
parameter. The Ref
and the
Fn::GetAtt
functions then reference the appropriate values, based
on the stage. Fn::Sub
is first used with Fn::GetAtt
to
obtain the ARN of the appropriate Amazon SQS queue to set the dimensions of the Amazon CloudWatch
alarm. Next, Fn::Join is used with Ref
to
create the name of the SNS topic for the AlarmActions
property.
JSON
{ "AWSTemplateFormatVersion": "2010-09-09", "Transform": "AWS::LanguageExtensions", "Parameters": { "Stage": { "Type": "String", "Default": "Dev", "AllowedValues": [ "Dev", "Prod" ] } }, "Conditions": { "isProd": { "Fn::Equals": [ {"Ref": "Stage"}, "Prod" ] }, "isDev": { "Fn::Equals": [ {"Ref": "Stage"}, "Dev" ] } }, "Resources": { "DevQueue": { "Type": "AWS::SQS::Queue", "Condition": "isDev", "Properties": { "QueueName": {"Fn::Sub": "My${Stage}Queue"} } }, "ProdQueue": { "Type": "AWS::SQS::Queue", "Condition": "isProd", "Properties": { "QueueName": {"Fn::Sub": "My${Stage}Queue"} } }, "DevTopic": { "Condition": "isDev", "Type": "AWS::SNS::Topic" }, "ProdTopic": { "Condition": "isProd", "Type": "AWS::SNS::Topic" }, "MyAlarm": { "Type": "AWS::CloudWatch::Alarm", "Properties": { "AlarmDescription": "Alarm if queue depth grows beyond 10 messages", "Namespace": "AWS/SQS", "MetricName": "ApproximateNumberOfMessagesVisible", "Dimensions":[ { "Name": {"Fn::Sub": "${Stage}Queue"}, "Value": {"Fn::GetAtt": [{"Fn::Sub": "${Stage}Queue"}, "QueueName"]} } ], "Statistic": "Sum", "Period": 300, "EvaluationPeriods": 1, "Threshold": 10, "ComparisonOperator": "GreaterThanThreshold", "AlarmActions": [ { "Ref": {"Fn::Join": ["", [{"Ref": "Stage"}, "Topic"]]} } ] } } } }
YAML
AWSTemplateFormatVersion: 2010-09-09 Transform: AWS::LanguageExtensions Parameters: Stage: Type: String Default: Dev AllowedValues: - Dev - Prod Conditions: isProd: !Equals - !Ref Stage - Prod isDev: !Equals - !Ref Stage - Dev Resources: DevQueue: Type: AWS::SQS::Queue Condition: isDev Properties: QueueName: !Sub My${Stage}Queue ProdQueu: Type: 'AWS::SQS::Queue Condition: isProd Properties: QueueName: !Sub My${Stage}Queue DevTopic: Condition: isDev Type: AWS::SNS::Topic ProdTopic: Condition: isProd Type: AWS::SNS::Topic MyAlarm: Type: 'AWS::CloudWatch::Alarm' Properties: AlarmDescription: Alarm if queue depth grows beyond 10 messages Namespace: AWS/SQS MetricName: ApproximateNumberOfMessagesVisible Dimensions: - Name: !Sub '${Stage}Queue' Value: !GetAtt - !Sub '${Stage}Queue' - QueueName Statistic: Sum Period: 300 EvaluationPeriods: 1 Threshold: 10 ComparisonOperator: GreaterThanThreshold AlarmActions: - !Ref 'Fn::Join': - '' - - !Ref Stage - Topic
Supported functions
When you use the AWS::LanguageExtensions transform, you can use the
following functions within the Ref
function.