Syntaxe Parameters du modèle CloudFormation - AWS CloudFormation
SyntaxePropriétésConsignes générales pour les paramètresExemplesRessources connexes

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Syntaxe Parameters du modèle CloudFormation

Utilisez la section Parameters facultative pour personnaliser vos modèles. Les paramètres vous permettent de saisir des valeurs personnalisées dans votre modèle chaque fois que vous créez ou mettez à jour une pile. En utilisant des paramètres dans vos modèles, vous pouvez créer des modèles réutilisables et flexibles qui peuvent être adaptés à des scénarios spécifiques.

En définissant les paramètres du type approprié, vous pouvez choisir parmi une liste d’identificateurs de ressources existantes lorsque vous utilisez la console pour créer votre pile. Pour de plus amples informations, consultez Spécification de ressources existantes à l’exécution avec les types de paramètres fournis par CloudFormation.

Les paramètres sont un moyen courant de spécifier les valeurs des propriétés des ressources de pile. Cependant, certains paramètres peuvent dépendre de la région ou être quelque peu complexes à comprendre pour les utilisateurs en raison d’autres conditions ou dépendances. Dans ces cas, vous pouvez intégrer une logique dans le modèle lui-même afin que les utilisateurs puissent spécifier des valeurs plus simples (ou aucune valeur) pour obtenir les résultats souhaités, par exemple en utilisant un mappage. Pour de plus amples informations, consultez Syntaxe Mappings du modèle CloudFormation.

Syntaxe

Vous déclarez les paramètres dans la section Parameters d’un modèle, qui utilise la syntaxe générale suivante :

JSON

"Parameters" : {
  "ParameterLogicalID" : {
    "Description": "Information about the parameter",
    "Type" : "DataType",
    "Default" : "value",
    "AllowedValues" : ["value1", "value2"]
  }
}

YAML

Parameters:
  ParameterLogicalID:
    Description: Information about the parameter
    Type: DataType
    Default: value
    AllowedValues:
      - value1
      - value2

Un paramètre contient une liste d'attributs qui définissent sa valeur, ainsi que les contraintes de cette valeur. Le seul attribut requis est Type, qui peut être String, Number, ou un type de paramètre fourni par CloudFormation. Vous pouvez également ajouter un attribut Description qui décrit le type de valeur que vous devez spécifier. Le nom et la description du paramètre apparaissent dans la page Spécifier les paramètres lorsque vous utilisez le modèle dans l’assistant Créer une pile.

Note

Par défaut, la console CloudFormation répertorie les paramètres d’entrée par ordre alphabétique en fonction de leur ID logique. Pour annuler cet ordre par défaut et regrouper les paramètres associés, vous pouvez utiliser la clé de métadonnées AWS::CloudFormation::Interface de votre modèle. Pour de plus amples informations, consultez Organisation des CloudFormation paramètres à l'aide de AWS::CloudFormation::Interface métadonnées.

Pour les paramètres contenant des valeurs par défaut, CloudFormation utilise ces valeurs par défaut, sauf si une autre valeur a été définie. Si vous omettez l’attribut par défaut, les utilisateurs doivent spécifier une valeur pour ce paramètre. Cependant, vous ne pouvez pas garantir que cette valeur sera correcte. Pour valider la valeur d'un paramètre, vous pouvez déclarer des contraintes ou spécifier un type de paramètre spécifique à AWS.

Pour les paramètres sans valeur par défaut, les utilisateurs doivent spécifier une valeur de nom de clé lors de la création de la pile. S’il ne le font pas, CloudFormation ne peut pas créer la pile et génère une exception :

Parameters: [KeyName] must have values

Propriétés

AllowedPattern

Une expression régulière qui représente les modèles que vous voulez autoriser pour String ou les types CommaDelimitedList. Lorsqu'il est appliqué à un paramètre de type String, le modèle doit correspondre à la valeur entière du paramètre fournie. Lorsqu'il est appliqué à un paramètre de type CommaDelimitedList, le modèle doit correspondre à chaque valeur de la liste.

Obligatoire : non

AllowedValues

Tableau contenant la liste des valeurs autorisées pour le paramètre. Lorsqu'elle est appliquée à un paramètre de type String, la valeur du paramètre doit être l'une des valeurs autorisées. Lorsqu'elle est appliquée à un paramètre de type CommaDelimitedList, chaque valeur de la liste doit être l'une des valeurs autorisées spécifiées.

Obligatoire : non

Note

Si vous utilisez le format YAML et que vous souhaitez utiliser des chaînes Yes et No pour AllowedValues, utilisez des guillemets simples pour empêcher l'analyseur YAML de prendre en compte ces valeurs booléennes.

ConstraintDescription

Chaîne qui explique la contrainte lorsque celle-ci n'est pas respectée. Par exemple, sans description de contrainte, un paramètre dont le modèle [A-Za-z0-9]+ est autorisé affiche le message d'erreur suivant lorsque l'utilisateur spécifie une valeur non valide :

Malformed input-Parameter MyParameter must match pattern [A-Za-z0-9]+

En ajoutant une description de contrainte, comme doit uniquement contenir des lettres (minuscules et majuscules) et des chiffres, vous pouvez afficher le message d'erreur personnalisé suivant :

Malformed input-Parameter MyParameter must only contain uppercase and lowercase letters and numbers

Obligatoire : non

Default

Valeur correspondant au type approprié de modèle à utiliser si aucune valeur n'est spécifiée lors de la création d'une pile. Si vous avez défini des contraintes pour le paramètre, vous devez spécifier une valeur conforme à ces contraintes.

Obligatoire : non

Description

Chaîne de maximum 4000 caractères qui décrit le paramètre.

Obligatoire : non

MaxLength

Nombre entier qui détermine le nombre maximal de caractères que vous voulez autoriser pour les types String.

Obligatoire : non

MaxValue

Valeur numérique qui détermine la valeur maximale que vous voulez autoriser pour les types Number.

Obligatoire : non

MinLength

Nombre entier qui détermine le nombre minimal de caractères que vous voulez autoriser pour les types String.

Obligatoire : non

MinValue

Valeur numérique qui détermine la valeur minimale que vous voulez autoriser pour les types Number.

Obligatoire : non

NoEcho

Pour masquer la valeur du paramètre et éviter qu’elle ne s’affiche dans la console, les outils de ligne de commande ou l’API. Si vous définissez l'attribut NoEcho sur true, CloudFormation renvoie la valeur du paramètre masquée sous forme d'astérisques (*****) pour tous les appels qui décrivent la pile ou les événements de pile, à l'exception des informations stockées dans les emplacements spécifiés ci-dessous.

Obligatoire : non

Important

L'utilisation de l'attribut NoEcho ne masque aucune information stockée dans les lieux suivants :

  • La section de modèle Metadata CloudFormation ne transforme pas, ne modifie pas, ne rédige aucune information que vous incluez dans la section Metadata. Pour de plus amples informations, veuillez consulter Métadonnées.

  • La section de modèle Outputs Pour de plus amples informations, veuillez consulter Sorties

  • L’attribut Metadata d'une définition de ressource. Pour plus d'informations, voir la section consécrée à l'Attribut Metadata.

Nous vous recommandons vivement de ne pas utiliser ces mécanismes pour inclure des informations sensibles, telles que des mots de passe ou des secrets.

Important

Plutôt que d’intégrer des informations sensibles directement dans vos modèles CloudFormation, nous vous recommandons d’utiliser des paramètres dynamiques dans le modèle de pile pour faire référence aux informations sensibles stockées et gérées en dehors de CloudFormation, par exemple dans AWS Systems Manager Parameter Store ou AWS Secrets Manager.

Pour de plus amples informations, veuillez consulter la bonne pratique N'incorporez pas d'informations d'identification dans vos modèles.

Important

Nous vous déconseillons vivement d'inclure des paramètres NoEcho, ou toute donnée sensible, dans les propriétés des ressources qui font partie de l'identifiant principal d'une ressource.

Lorsqu'un paramètre NoEcho est inclus dans une propriété qui constitue un identifiant de ressource principal, CloudFormation peut utiliser la valeur en texte brut réelle dans l'identifiant de ressource principal. Cet ID de ressource peut apparaître dans toutes les sorties ou destinations dérivées.

Pour déterminer quelles propriétés de ressource constituent l’identifiant principal d’un type de ressource, reportez-vous à la documentation de référence de cette ressource dans la référence des types de ressources et de propriétés AWS. Dans la section Valeurs renvoyées, la valeur de retour de la fonction Ref représente les propriétés de la ressource qui constituent l'identifiant principal du type de ressource.

Type

Type de données du paramètre (DataType).

Obligatoire : oui

CloudFormation prend en charge les types de paramètres suivants :

String

Chaîne littérale. Vous pouvez utiliser les attributs suivants pour déclarer des contraintes : MinLength, MaxLength, Default, AllowedValues, et AllowedPattern.

Par exemple, les utilisateurs peuvent spécifier "MyUserName".

Number

Nombre entier ou valeur flottante. CloudFormation valide la valeur du paramètre en tant que nombre ; cependant, lorsque vous utilisez le paramètre ailleurs dans votre modèle (par exemple, à l’aide de la fonction intrinsèque Ref), la valeur du paramètre devient une chaîne.

Vous pouvez utiliser les attributs suivants pour déclarer des contraintes : MinValue, MaxValue, Default, et AllowedValues.

Par exemple, les utilisateurs peuvent spécifier "8888".

List<Number>

Tableau de nombres entiers ou de nombres flottants séparés par des virgules. CloudFormation valide la valeur du paramètre sous forme de nombres ; cependant, lorsque vous utilisez le paramètre ailleurs dans votre modèle (par exemple, à l’aide de la fonction intrinsèque Ref), la valeur du paramètre devient une liste de chaînes.

Les utilisateurs peuvent par exemple préciser "80,20" et la fonction Ref générera ["80","20"].

CommaDelimitedList

Tableau de chaînes littérales séparées par des virgules. Le nombre total de chaînes doit correspondre au nombre total de virgules, plus un. En outre, les espaces de chaque chaîne de membre sont coupés.

Les utilisateurs peuvent par exemple préciser "test,dev,prod" et la fonction Ref générera ["test","dev","prod"].

AWSTypes de paramètres spécifiques à

Valeurs AWS telles que des noms de paires de clés Amazon EC2 et des ID VPC. Pour de plus amples informations, consultez Spécification de ressources existantes au moment de l’exécution.

Types de paramètres Systems Manager

Paramètres correspondant aux paramètres existants dans Systems Manager Parameter Store. Vous spécifiez une clé de paramètre Systems Manager comme valeur du type de paramètre Systems Manager, et CloudFormation récupère la dernière valeur du magasin de paramètres à utiliser pour la pile. Pour de plus amples informations, consultez Spécification de ressources existantes au moment de l’exécution.

Consignes générales pour les paramètres

Les critères suivants s'appliquent lors de l'utilisation des paramètres :

  • Vous pouvez avoir un maximum de 200 paramètres dans un modèle CloudFormation.

  • Chaque paramètre doit recevoir un nom logique (également appelé ID logique) qui doit être alphanumérique et unique parmi tous les noms logiques du modèle.

  • Chaque paramètre doit être associé à un type de paramètre pris en charge par CloudFormation. Pour plus d'informations, consultez Type.

  • Lors de l’exécution de CloudFormation, une valeur doit être attribuée à chaque paramètre afin de bien approvisionner la pile. Vous pouvez éventuellement spécifier une valeur par défaut que CloudFormation utilisera à moins qu’une autre valeur ne soit fournie.

  • Les paramètres doivent être déclarés et référencés à partir du même modèle. Vous pouvez référencer des paramètres dans les sections Resources et Outputs du modèle.

Exemples

Un paramètre de chaîne simple

L’exemple suivant déclare un paramètre nommé de type InstanceTypeParameter et String. Ce paramètre vous permet de spécifier le type d’instance Amazon EC2 pour la pile. Si aucune valeur n’est fournie lors de la création ou de la mise à jour de la pile, CloudFormation utilise la valeur par défaut t2.micro.

JSON

"Parameters" : {
  "InstanceTypeParameter" : {
    "Description" : "Enter t2.micro, m1.small, or m1.large. Default is t2.micro.",
    "Type" : "String",
    "Default" : "t2.micro",
    "AllowedValues" : ["t2.micro", "m1.small", "m1.large"]
  }
}

YAML

Parameters:
  InstanceTypeParameter:
    Description: Enter t2.micro, m1.small, or m1.large. Default is t2.micro.
    Type: String
    Default: t2.micro
    AllowedValues:
      - t2.micro
      - m1.small
      - m1.large

Paramètre mot de passe

L’exemple suivant déclare un paramètre nommé DBPwd de type String sans valeur par défaut. La propriété NoEcho est définie sur true pour empêcher l’affichage de la valeur du paramètre dans les descriptions de pile. La longueur minimale qui peut être spécifiée s'élève à 1, et la longueur maximale à 41. Le modèle accepte les chiffres et les lettres minuscules et majuscules. Cet exemple illustre également l’utilisation d’une expression régulière pour la propriété AllowedPattern.

JSON

"Parameters" : {
  "DBPwd" : {
    "NoEcho" : "true",
    "Description" : "The database admin account password",
    "Type" : "String",
    "MinLength" : "1",
    "MaxLength" : "41",
    "AllowedPattern" : "^[a-zA-Z0-9]*$"
  }
}

YAML

Parameters: 
  DBPwd: 
    NoEcho: true
    Description: The database admin account password
    Type: String
    MinLength: 1
    MaxLength: 41
    AllowedPattern: ^[a-zA-Z0-9]*$

Paramètres de référencement

Vous utilisez la fonction intrinsèque Ref pour référencer un paramètre, et CloudFormation utilise la valeur du paramètre pour provisionner la pile. Vous pouvez faire référence à des paramètres dans les sections Resources et Outputs du même modèle.

Dans l'exemple suivant, la propriété InstanceType de l'instance EC2 ressource fait référence à la valeur du paramètre InstanceTypeParameter :

JSON

"Ec2Instance" : {
  "Type" : "AWS::EC2::Instance",
  "Properties" : {
    "InstanceType" : { "Ref" : "InstanceTypeParameter" },
    "ImageId" : "ami-0ff8a91507f77f867"
  }
}

YAML

Ec2Instance:
  Type: AWS::EC2::Instance
  Properties:
    InstanceType:
      Ref: InstanceTypeParameter
    ImageId: ami-0ff8a91507f77f867

Paramètre de liste délimité par des virgules

Le type de paramètre CommaDelimitedList peut être utile lorsque vous devez fournir plusieurs valeurs pour une seule propriété. L’exemple suivant déclare un paramètre nommé DbSubnetIpBlocks avec une valeur par défaut de trois blocs CIDR séparés par des virgules.

JSON

"Parameters" : {
  "DbSubnetIpBlocks": {
    "Description": "Comma-delimited list of three CIDR blocks",
    "Type": "CommaDelimitedList",
    "Default": "10.0.48.0/24, 10.0.112.0/24, 10.0.176.0/24"
  }
}

YAML

Parameters: 
  DbSubnetIpBlocks: 
    Description: "Comma-delimited list of three CIDR blocks"
    Type: CommaDelimitedList
    Default: "10.0.48.0/24, 10.0.112.0/24, 10.0.176.0/24"

Renvoi d'une valeur de paramètre de liste séparée par des virgules

Pour faire référence à une valeur spécifique dans une liste de paramètres séparés par des virgules, utilisez la fonction intrinsèque Fn::Select dans la section Resources de votre modèle. Transmettez la valeur d’index de l’objet souhaité et une liste d’objets, comme indiqué dans l’exemple suivant.

JSON

{
    "Parameters": {
        "VPC": {
            "Type": "String",
            "Default": "vpc-123456"
        },
        "VpcAzs": {
            "Type": "CommaDelimitedList",
            "Default": "us-west-2a, us-west-2b, us-west-2c"
        },
        "DbSubnetIpBlocks": {
            "Type": "CommaDelimitedList",
            "Default": "172.16.0.0/26, 172.16.0.64/26, 172.16.0.128/26"
        }
    },
    "Resources": {
        "DbSubnet1": {
            "Type": "AWS::EC2::Subnet",
            "Properties": {
                "AvailabilityZone": {
                    "Fn::Select": [
                      0,
                      { 
                        "Ref": "VpcAzs" 
                      }
                   ]
                },
                "VpcId": {
                    "Ref": "VPC"
                },
                "CidrBlock": {
                    "Fn::Select": [
                        0,
                        { "Ref": "DbSubnetIpBlocks" }
                    ]
                }
            }
        },
        "DbSubnet2": {
            "Type": "AWS::EC2::Subnet",
            "Properties": {
                "AvailabilityZone": {
                    "Fn::Sub": [
                        "${AWS::Region}${AZ}",
                        {
                            "AZ": {
                                "Fn::Select": [
                                    1,
                                    { "Ref": "VpcAzs" }
                                ]
                            }
                        }
                    ]
                },
                "VpcId": {
                    "Ref": "VPC"
                },
                "CidrBlock": {
                    "Fn::Select": [
                        1,
                        { "Ref": "DbSubnetIpBlocks" }
                    ]
                }
            }
        },
        "DbSubnet3": {
            "Type": "AWS::EC2::Subnet",
            "Properties": {
                "AvailabilityZone": {
                    "Fn::Sub": [
                        "${AWS::Region}${AZ}",
                        {
                            "AZ": {
                                "Fn::Select": [
                                    2,
                                    { "Ref": "VpcAzs" }
                                ]
                            }
                        }
                    ]
                },
                "VpcId": {
                    "Ref": "VPC"
                },
                "CidrBlock": {
                    "Fn::Select": [
                        2,
                        { "Ref": "DbSubnetIpBlocks" }
                    ]
                }
            }
        }
    }
}

YAML

Parameters:
  VPC:
    Type: String
    Default: vpc-123456
  VpcAzs:
    Type: CommaDelimitedList
    Default: us-west-2a, us-west-2b, us-west-2c
  DbSubnetIpBlocks:
    Type: CommaDelimitedList
    Default: 172.16.0.0/26, 172.16.0.64/26, 172.16.0.128/26
Resources:
  DbSubnet1:
    Type: AWS::EC2::Subnet
    Properties:
      AvailabilityZone: !Select
        - 0 
        - !Ref VpcAzs
      VpcId: !Ref VPC
      CidrBlock: !Select
        - 0
        - !Ref DbSubnetIpBlocks
  DbSubnet2:
    Type: AWS::EC2::Subnet
    Properties:
      AvailabilityZone: !Sub
        - ${AWS::Region}${AZ}
        - AZ: !Select
            - 1
            - !Ref VpcAzs
      VpcId: !Ref VPC
      CidrBlock: !Select
        - 1
        - !Ref DbSubnetIpBlocks
  DbSubnet3:
    Type: AWS::EC2::Subnet
    Properties:
      AvailabilityZone: !Sub
        - ${AWS::Region}${AZ}
        - AZ: !Select
            - 2
            - !Ref VpcAzs
      VpcId: !Ref VPC
      CidrBlock: !Select
        - 2
        - !Ref DbSubnetIpBlocks

CloudFormation prend également en charge l’utilisation de références dynamiques pour spécifier les valeurs des propriétés de manière dynamique. Par exemple, vous pouvez avoir besoin de référencer des chaînes sécurisées stockées dans le magasin de paramètres Systems Manager. Pour de plus amples informations, consultez Obtenir les valeurs stockées dans d’autres services à l’aide de références dynamiques.

Vous pouvez également utiliser des pseudo-paramètres dans une fonction Ref ou Sub une variable pour remplir dynamiquement des valeurs. Pour de plus amples informations, consultez Obtenir des AWS valeurs à l'aide de pseudo-paramètres.