Ref - AWS CloudFormation
DeclarationParametersReturn valueExamplesSupported functions

Ref

The intrinsic function Ref returns the value of the specified parameter or resource. When the AWS::LanguageExtensions transform transform is used, you can use intrinsic functions as a parameter to Ref and Fn::GetAtt.

  • When you specify a parameter's logical name, it returns the value of the parameter.

  • When you specify a resource's logical name, it returns a value that you can typically use to refer to that resource, such as a physical ID.

  • When you specify an intrinsic function, it returns the output of that function.

When you are declaring a resource in a template and you need to specify another template resource by name, you can use the Ref to refer to that other resource. In general, Ref returns the name of the resource. For example, a reference to an AWS::AutoScaling::AutoScalingGroup returns the name of that Auto Scaling group resource.

For some resources, an identifier is returned that has another significant meaning in the context of the resource. An AWS::EC2::EIP resource, for instance, returns the IP address, and an AWS::EC2::Instance returns the instance ID.

Tip

You can also use Ref to add values to Outputs messages.

For more information about Ref return values for a particular resource or property, refer to the documentation for that resource or property in the Resource and property reference.

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

When the parameter is a logicalName, the return value is the physical ID of the resource or the value of the parameter.

When the parameter is an IntrinsicFunction, the return value is the return value from the intrinsic function

Examples

Example

The following resource declaration for an Elastic IP address needs the instance ID of an EC2 instance and uses the Ref function to specify the instance ID of the MyEC2Instance resource:

JSON

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

YAML

MyEIP:
  Type: "AWS::EC2::EIP"
  Properties:
    InstanceId: !Ref MyEC2Instance

Example generating identifier for multiple stages

This example demonstrates how to use the Fn::Sub intrinsic function to substitute values for the Identifier for different stages. The Ref and the Fn::GetAtt functions can then be used to reference the appropriate values, based on the input for 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 logical ID string of the Stage parameter.

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'
  ProdQueue:
    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

Example use Fn::Sub intrinsic function inside Ref function

This example demonstrates how to use the Fn::Sub intrinsic function to substitute values for the Ref function. The Ref and the Fn::GetAtt functions can then be used to reference the appropriate values, based on the input for the stage. Fn::Sub is first used to obtain the ARN of the appropriate Amazon SNS topic to set the dimensions of the Amazon CloudWatch alarm. Next, Fn::Join is used with Ref to create the logical ID string of the Stage parameter.

JSON

{
    "AWSTemplateFormatVersion": "2010-09-09",
    "Transform": "AWS::LanguageExtensions",
    "Parameters": {
        "Stage": {
            "Type": "String",
            "Default": "Dev",
            "AllowedValues": [
                "Dev",
                "Prod"
            ]
        }
    },
    "Resources": {
        "TopicDev": {
            "Type": "AWS::SNS::Topic",
            "Properties": {
                "TopicName": "MyTopic"
            }
        }
    },
    "Outputs": {
        "stageOutput": {
            "Value": {
                "Ref": {
                    "Fn::Sub": "Topic${Stage}"
                }
            }
        }
    }
}

YAML

AWSTemplateFormatVersion: 2010-09-09
Transform: 'AWS::LanguageExtensions'
Parameters:
  Stage:
    Type: String
    Default: Dev
    AllowedValues:
      - Dev
      - Prod
Resources:
  TopicDev:
    Type: 'AWS::SNS::Topic'
    Properties:
      TopicName: MyTopic
Outputs:
  stageOutput:
    Value: !Ref 
      'Fn::Sub': 'Topic${Stage}'

Supported functions

When the AWS::LanguageExtensions transform transform is used, within the Ref function, you can use the following functions.