Ref - AWS CloudFormation

Ref

La función intrínseca Ref devuelve el valor de un parámetro, recurso u otra función intrínseca específicos. Esta función se suele utilizar para crear referencias entre los recursos de una plantilla de CloudFormation.

Declaración

JSON

{ "Ref" : "logicalName" }
{ "Ref" : "IntrinsicFunction" }

YAML

Sintaxis del nombre de función completo:

Ref: logicalName
Ref: IntrinsicFunction

Sintaxis de la forma abreviada:

!Ref logicalName
!Ref IntrinsicFunction

Parámetros

logicalName

El nombre lógico del recurso o parámetro del que quiera quitar la referencia.

IntrinsicFunction

La función intrínseca que se resuelve en una cadena válida. Debe contener referencias a parámetros o identificadores, y no debe contener identificadores lógicos de recursos.

Valor devuelto

El valor devuelto de Ref depende del tipo de entidad a la que se hace referencia:

  • Al especificar el nombre lógico de un parámetro, devuelve el valor del parámetro. Para obtener más información, consulte Sintaxis de Parameters de la plantilla de CloudFormation.

  • Al especificar el nombre lógico de un recurso, devuelve un valor que se utiliza para identificar dicho recurso. Normalmente, ese es el nombre del recurso. Sin embargo, para algunos recursos, se devuelve un identificador que tenga otro significado importante en el contexto del recurso. Por ejemplo, el recurso AWS::EC2::EIP devuelve la dirección IP, y AWS::EC2::Instance devuelve el ID de la instancia. Para obtener más información acerca de los valores de devolución de Ref para un recurso, consulte la documentación de dicho recurso en la Referencia de recursos y propiedades.

  • Al especificar una función intrínseca, devuelve la salida de esa función.

Ejemplos

Creación de referencias entre recursos

La siguiente declaración de recursos para una dirección IP elástica necesita el ID de instancia de una instancia de EC2. Utiliza la función Ref para especificar el ID de instancia del recurso MyEC2Instance declarado en otra parte de la plantilla.

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

Devolución de un identificador de recurso como salida de la pila

En los siguientes ejemplos se muestra cómo utilizar la función Ref para devolver el nombre de un bucket de Amazon S3 con el nombre lógico MyBucket como salida de la pila.

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

Uso de la función intrínseca Fn::Join dentro de la función Ref

nota

Cuando utilice la transformación AWS::LanguageExtensions, podrá utilizar Ref en combinación con otras funciones intrínsecas. Para ver las funciones compatibles, consulte Funciones compatibles.

En los siguientes ejemplos se muestra cómo establecer los identificadores de los recursos mediante la función intrínseca Fn::Sub, las condiciones y la entrada del parámetro Stage. A continuación, las funciones Ref y Fn::GetAtt hacen referencia a los valores apropiados, en función de la etapa. Fn::Sub se usa primero con Fn::GetAtt para obtener el ARN de la cola de Amazon SQS adecuada para establecer las dimensiones de la alarma de Amazon CloudWatch. A continuación, Fn::Join se utiliza con Ref para crear el nombre del tema de SNS de la propiedad AlarmActions.

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

Funciones compatibles

Cuando se usa la transformación AWS::LanguageExtensions, se pueden usar las siguientes funciones dentro de la función Ref.