Fn::Sub

La fonction intrinsèque Fn::Sub permet de remplacer les variables contenues dans une chaîne d'entrée par des valeurs que vous spécifiez. Dans vos modèles, vous pouvez utiliser cette fonction pour construire des commandes ou des sorties qui incluent des valeurs qui ne sont pas disponibles tant que vous ne créez ou ne mettez à jour une pile.

Déclaration

Les sections suivantes présentent la syntaxe de la fonction.

JSON

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

Si vous remplacez uniquement des paramètres de modèle, une logique IDs de ressource ou des attributs de ressource dans le String paramètre, ne spécifiez pas de carte variable.

{ "Fn::Sub" : String }

YAML

Syntaxe pour le nom complet de la fonction :

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

Syntaxe pour la forme courte :

!Sub
  - String
  - Var1Name: Var1Value
    Var2Name: Var2Value

Si vous remplacez uniquement des paramètres de modèle, une logique IDs de ressource ou des attributs de ressource dans le String paramètre, ne spécifiez pas de carte variable.

Syntaxe pour le nom complet de la fonction :

Fn::Sub: String

Syntaxe pour la forme courte :

!Sub String

Paramètres

String

Chaîne contenant des variables qui sont AWS CloudFormation remplacées par leurs valeurs associées lors de l'exécution. Les variables s'écrivent sous la forme ${MyVarName}. Les variables peuvent être des noms de paramètres de modèle, une logique de ressource IDs, des attributs de ressources ou une variable dans une carte clé-valeur. Si vous spécifiez uniquement les noms des paramètres du modèle, la logique IDs des ressources et les attributs des ressources, ne spécifiez pas de mappage clé-valeur.

Si vous spécifiez des noms de paramètres de modèle ou une logique IDs de ressource${InstanceTypeParameter}, par exemple, CloudFormation renvoie les mêmes valeurs que si vous utilisiez la fonction Ref intrinsèque. Si vous spécifiez des attributs de ressource, tels que${MyInstance.PublicIp}, CloudFormation renvoie les mêmes valeurs que si vous utilisiez la fonction Fn::GetAtt intrinsèque.

Pour écrire littéralement un symbole dollar et des accolades (${}), ajoutez un point d'exclamation (!) après l'orthèse bouclée ouverte, par exemple. ${!Literal} CloudFormation résout ce texte en tant que${Literal}.

Si vous utilisez un modèle de lancement, ajoutez une barre oblique inversée \ avant le signe du dollar, par exemple\${!Literal}, sinon le littéral se résoudra sous la forme d'une chaîne vide.

VarName

Nom d'une variable que vous avez incluse dans le paramètre String.

VarValue

La valeur qui CloudFormation remplace le nom de variable associé lors de l'exécution.

Valeur renvoyée

CloudFormation renvoie la chaîne d'origine en remplaçant les valeurs de toutes les variables.

Exemples

Les exemples suivants montrent comment utiliser la fonction Fn::Sub.

À utiliser Fn::Sub sans carte clé-valeur

Dans cet exemple simple, la description de la InstanceSecurityGroup ressource est créée dynamiquement avec le AWS::StackName pseudo-paramètre. Par exemple, si le nom de la pile est »VPC-EC2-ALB-Stack«, la description qui en résulte est »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}"

À utiliser Fn::Sub avec une carte clé-valeur

Dans cet exemple, le nom de la WWWBucket ressource est créé dynamiquement à l'aide d'une carte clé-valeur. La Fn::Sub fonction remplace ${Domain} dans la chaîne www.${Domain} d'entrée la valeur d'une Ref fonction qui fait référence au RootDomainName paramètre défini dans le même modèle de pile. Par exemple, si le nom de domaine racine est »mydomain.com«, le nom obtenu pour cette ressource est »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

Utiliser plusieurs variables pour construire ARNs

L'exemple suivant utilise Fn::Sub les AWS::AccountId pseudo-paramètres AWS::Region et et l'ID logique de vpc ressource pour créer un Amazon Resource Name (ARN) pour un VPC.

JSON

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

YAML

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

Transmettre des valeurs de paramètres dans des scripts de données utilisateur

L’exemple suivant utilise Fn::Sub pour remplacer les pseudo-paramètres AWS::StackName et AWS::Region par le nom de la pile et la région au moment de l’exécution.

JSON

Pour plus de lisibilité, l'exemple JSON utilise la fonction Fn::Join pour séparer chaque commande, au lieu de spécifier l'intégralité du script de données utilisateur dans une même valeur de chaîne.

"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

L'exemple YAML utilise un bloc littéral pour spécifier le script de données utilisateur.

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}

Spécifier des valeurs conditionnelles à l'aide de mappages

Dans cet exemple, le nom de la myLogGroup ressource est créé dynamiquement en remplaçant la log_group_name variable par la valeur résultante de la Fn::FindInMap fonction.

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

Fonctions prises en charge

Pour le paramètre String, vous ne pouvez pas utiliser de fonction. Vous devez spécifier une valeur de type chaîne.

Pour les paramètres VarName et VarValue, vous pouvez utiliser les fonctions suivantes :

• Fn::Base64

• Fn::FindInMap

• Fn::GetAtt

• Fn::GetAZs

• Fn::If

• Fn::ImportValue

• Fn::Join

• Fn::Select

• Fn::Sub

• Ref