Fn::Sub - AWS CloudFormation
DeclaraciónParámetrosValor devueltoEjemplosFunciones compatibles

Fn::Sub

La función intrínseca Fn::Sub sustituye variables en una cadena de entrada por los valores que especifique. En las plantillas, puede utilizar esta función para construir comandos o salidas que incluyen valores que no están disponibles hasta que crea o actualiza una pila.

Declaración

En las secciones siguientes se muestra la sintaxis de la función.

JSON

{ "Fn::Sub" : [ String, { Var1Name: Var1Value, Var2Name: Var2Value } ] }

Si está sustituyendo solamente parámetros de plantilla, ID lógicos de recursos o atributos de recursos en el parámetro String, no especifique un mapa de variables.

{ "Fn::Sub" : String }

YAML

Sintaxis del nombre de función completo:

Fn::Sub:
  - String
  - Var1Name: Var1Value
    Var2Name: Var2Value

Sintaxis de la forma abreviada:

!Sub
  - String
  - Var1Name: Var1Value
    Var2Name: Var2Value

Si está sustituyendo solamente parámetros de plantilla, ID lógicos de recursos o atributos de recursos en el parámetro String, no especifique un mapa de variables.

Sintaxis del nombre de función completo:

Fn::Sub: String

Sintaxis de la forma abreviada:

!Sub String

Parámetros

String

Una cadena con variables que AWS CloudFormation sustituye por los valores asociados durante el tiempo de ejecución. Escriba variables como ${MyVarName}. Las variables pueden ser los nombres de parámetros de plantilla, ID lógicos de recursos, atributos de recursos o una asignación clave-valor. Si especifica únicamente nombres de parámetros de plantilla, ID de recursos lógicos y atributos de recursos, no especifique una asignación clave-valor.

Si especifica nombres de parámetros de plantilla o ID lógicos de recursos, como por ejemplo ${InstanceTypeParameter}, CloudFormation devuelve los mismos valores que si utiliza la función intrínseca Ref. Si especifica atributos de recursos, como por ejemplo ${MyInstance.PublicIp}, CloudFormation devuelve los mismos valores que si utiliza la función intrínseca Fn::GetAtt.

Para escribir un símbolo de dólar y llaves (${}) literalmente, agregue una exclamación (!) después de la llave de apertura, como, por ejemplo, ${!Literal}. CloudFormation resuelve este texto como ${Literal}.

VarName

El nombre de una variable que incluyó en el parámetro String.

VarValue

El valor que CloudFormation sustituye para el nombre de variable asociada durante el tiempo de ejecución.

Valor devuelto

CloudFormation devuelve la cadena original y sustituye los valores para todas las variables.

Ejemplos

Los siguientes ejemplos muestran cómo utilizar la función Fn::Sub.

Uso de Fn::Sub sin una asignación de clave-valor

En este sencillo ejemplo, la descripción del recurso InstanceSecurityGroup se crea dinámicamente con el pseudoparámetro AWS::StackName. Por ejemplo, si el nombre de la pila es “VPC-EC2-ALB-Stack”, la descripción resultante es “SSH security group for VPC-EC2-ALB-Stack”.

JSON

"InstanceSecurityGroup" : {
    "Type" : "AWS::EC2::SecurityGroup",
    "Properties" : {
        "GroupDescription" : {"Fn::Sub": "SSH security group for ${AWS::StackName}"}
}}

YAML

InstanceSecurityGroup:
  Type: AWS::EC2::SecurityGroup
  Properties:
    GroupDescription: !Sub "SSH security group for ${AWS::StackName}"

Uso de Fn::Sub con una asignación de clave-valor

En este ejemplo, el nombre del recurso WWWBucket se crea dinámicamente con una asignación de clave-valor. La función Fn::Sub sustituye a ${Domain} en la cadena de entrada www.${Domain} por el valor de una función Ref que hace referencia al parámetro RootDomainName definido en la misma plantilla de pila. Por ejemplo, si el nombre del dominio raíz es “mydomain.com”, el nombre resultante de este recurso es “www.mydomain.com”.

JSON

"WWWBucket":{
  "Type":"AWS::S3::Bucket",
  "Properties":{
    "BucketName":{
      "Fn::Sub":[
        "www.${Domain}",
        {
          "Domain":{
            "Ref":"RootDomainName"
          }
        }
      ]
    }
  }
}

YAML

  WWWBucket:
    Type: AWS::S3::Bucket
    Properties:
      BucketName: !Sub
        - 'www.${Domain}'
        - Domain: !Ref RootDomainName

Uso de diversas variables para construir los ARN

En el siguiente ejemplo se utiliza Fn::Sub con los pseudoparámetros AWS::Region y AWS::AccountId, y el ID lógico de recurso vpc para crear un nombre de recurso de Amazon (ARN) de una VPC.

JSON

{ "Fn::Sub": "arn:aws:ec2:${AWS::Region}:${AWS::AccountId}:vpc/${vpc}" }

YAML

!Sub 'arn:aws:ec2:${AWS::Region}:${AWS::AccountId}:vpc/${vpc}'

Transferencia de los valores de los parámetros a los scripts de datos de usuario

En el siguiente ejemplo, se utiliza Fn::Sub para sustituir los pseudoparámetros AWS::StackName y AWS::Region del nombre de pila real, y la región durante el tiempo de ejecución.

JSON

Por ejemplo, el ejemplo de JSON utiliza la función Fn::Join para separar cada comando, en lugar de especificar la totalidad del script de datos del usuario en un valor de cadena individual.

"UserData": { "Fn::Base64": { "Fn::Join": ["\n", [
  "#!/bin/bash -xe",
  "yum update -y aws-cfn-bootstrap",
  { "Fn::Sub": "/opt/aws/bin/cfn-init -v --stack ${AWS::StackName} --resource LaunchConfig --configsets wordpress_install --region ${AWS::Region}" },
  { "Fn::Sub": "/opt/aws/bin/cfn-signal -e $? --stack ${AWS::StackName} --resource WebServerGroup --region ${AWS::Region}" }]]
}}

YAML

El ejemplo de YAML utiliza un bloque literal para especificar el script de datos del usuario.

UserData:
  Fn::Base64:
    !Sub |
      #!/bin/bash -xe
      yum update -y aws-cfn-bootstrap
      /opt/aws/bin/cfn-init -v --stack ${AWS::StackName} --resource LaunchConfig --configsets wordpress_install --region ${AWS::Region}
      /opt/aws/bin/cfn-signal -e $? --stack ${AWS::StackName} --resource WebServerGroup --region ${AWS::Region}

Especificación de valores condicionales con asignaciones

En este ejemplo, el nombre del recurso de myLogGroup se crea dinámicamente mediante la sustitución de la variable log_group_name por el valor resultante de la función Fn::FindInMap.

JSON

{
  "Mappings": {
    "LogGroupMapping": {
      "Test": {
        "Name": "test_log_group"
      },
      "Prod": {
        "Name": "prod_log_group"
      }
    }
  },
  "Resources": {
    "myLogGroup": {
      "Type": "AWS::Logs::LogGroup",
      "Properties": {
        "LogGroupName": {
          "Fn::Sub": [
            "cloud_watch_${log_group_name}",
            {
              "log_group_name": {
                "Fn::FindInMap": [
                  "LogGroupMapping",
                  "Test",
                  "Name"
                ]
              }
            }
          ]
        }
      }
    }
  }
}

YAML

Mappings:
  LogGroupMapping:
    Test:
      Name: test_log_group
    Prod:
      Name: prod_log_group
Resources:
  myLogGroup:
    Type: 'AWS::Logs::LogGroup'
    Properties:
      LogGroupName: !Sub 
        - 'cloud_watch_${log_group_name}'
        - log_group_name: !FindInMap 
            - LogGroupMapping
            - Test
            - Name

Funciones compatibles

Para el parámetro String, no se puede usar ninguna función. Debe especificar un valor de cadena.

Para los parámetros VarName y VarValue, puede utilizar las siguientes funciones: