Sintassi dei Parameters del modello CloudFormation - AWS CloudFormation
SintassiProprietàRequisiti generali per i parametriEsempiRisorse correlate

Sintassi dei Parameters del modello CloudFormation

Utilizza la sezione Parameters opzionale per personalizzare i modelli. Con i parametri, puoi immettere valori personalizzati nel modello ogni volta che crei o aggiorni uno stack. Utilizzando i parametri nei modelli puoi creare modelli riutilizzabili e flessibili che possono essere adattati a scenari specifici.

Definendo i parametri del tipo appropriato, puoi scegliere da un elenco di identificatori di risorse esistenti quando utilizzi la console per creare il tuo stack. Per ulteriori informazioni, consulta Specifica delle risorse esistenti in fase di runtime con i tipi di parametri forniti da CloudFormation.

I parametri sono un metodo comune per specificare i valori delle proprietà delle risorse dello stack. Tuttavia, potrebbero esservi impostazioni dipendenti dalla regione o che gli utenti trovano complessi da individuare a causa di altre condizioni o dipendenze. In questi casi, potresti aggiungere la logica nel modello stesso, in modo che gli utenti possano specificare valori più semplici (o nessuno) per ottenere i risultati desiderati. Per ulteriori informazioni, consulta Sintassi Mappings del modello CloudFormation.

Sintassi

Puoi dichiarare i parametri nella sezione Parameters di un modello, che utilizza la seguente sintassi generale:

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 parametro contiene un elenco di attributi che definiscono il valore e i vincoli rispetto al valore. L’unico attributo richiesto è Type, che può essere String, Number o un tipo di parametro fornito da CloudFormation. Puoi anche aggiungere un attributo Description che descrive il tipo di valore che devi specificare. Il nome e la descrizione del parametro appaiono nella pagina Specifica parametri quando utilizzi il modello nella procedura guidata Creazione di stack.

Nota

Per impostazione predefinita, la console CloudFormation ordina alfabeticamente i parametri di input in base al loro ID logico. Per ignorare questo ordinamento predefinito e raggruppare i parametri correlati, puoi utilizzare la chiave AWS::CloudFormation::Interface dei metadati nel tuo modello. Per ulteriori informazioni, consulta Organizzare i parametri CloudFormation con metadati AWS::CloudFormation::Interface.

Per i parametri con valori predefiniti, CloudFormation utilizza i valori predefiniti, a meno che gli utenti non specifichino un altro valore. Se ometti l’attributo predefinito, gli utenti devono specificare un valore per il parametro. Tuttavia, richiedere all’utente di immettere un valore non garantisce che il valore sia valido. Per convalidare il valore di un parametro, puoi dichiarare i vincoli o specificare un tipo di parametro specifico di AWS.

Per i parametri senza valori predefiniti, gli utenti devono specificare un valore del nome della chiave al momento della creazione dello stack. Se non lo fanno, CloudFormation non riesce a creare lo stack e genera un’eccezione:

Parameters: [KeyName] must have values

Proprietà

AllowedPattern

Una espressione regolare che rappresenta i modelli da consentire per i tipi String o CommaDelimitedList. Se applicato su un parametro di tipo String, lo schema deve corrispondere all’intero valore del parametro fornito. Quando viene applicato a un parametro di tipo CommaDelimitedList, il modello deve corrispondere a ciascun valore nell’elenco.

Required: No

AllowedValues

Matrice contenente l’elenco dei valori consentiti per il parametro. Quando viene applicato a un parametro di tipo String, il valore del parametro deve essere uno dei valori consentiti. Quando viene applicato a un parametro di tipo CommaDelimitedList, ogni valore nell’elenco deve essere uno dei valori consentiti.

Required: No

Nota

Se utilizzi YAML e desideri utilizzare le stringhe Yes e No per AllowedValues, utilizza le virgolette singole per evitare che il parser YAML consideri questi valori booleani.

ConstraintDescription

Stringa che illustra un vincolo in caso di violazione del vincolo. Ad esempio, senza una descrizione del vincolo, un parametro associato al modello consentito [A-Za-z0-9]+ restituisce il seguente messaggio di errore quando l’utente specifica un valore non valido:

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

Se aggiungi una descrizione del vincolo, ad esempio must only contain letters (uppercase and lowercase) and number (solo lettere (maiuscole e minuscole) e numeri), puoi visualizzare il seguente messaggio di errore personalizzato:

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

Required: No

Default

Valore del tipo appropriato per il modello da utilizzare se non viene specificato alcun valore al momento della creazione di uno stack. Se per il parametro definisci vincoli, devi specificare un valore conforme a tali vincoli.

Required: No

Description

Stringa contenente un massimo di 4.000 caratteri che descrive il parametro.

Required: No

MaxLength

Valore intero che determina il numero massimo di caratteri consentiti per i tipi String.

Required: No

MaxValue

Valore numerico che determina il valore numerico massimo consentito per i tipi Number.

Required: No

MinLength

Valore intero che determina il numero minimo di caratteri consentiti per i tipi String.

Required: No

MinValue

Valore numerico che determina il valore numerico minimo consentito per i tipi Number.

Required: No

NoEcho

Indica se mascherare il valore del parametro per impedirne la visualizzazione nella console, negli strumenti a riga di comando o nell’API. Se imposti l’attributo NoEcho su true, CloudFormation restituisce il valore del parametro mascherato come asterischi (*****) per tutte le chiamate che descrivono lo stack o gli eventi stack, ad eccezione delle informazioni archiviate nelle posizioni specificate di seguito.

Required: No

Importante

L’utilizzo dell’attributo NoEcho non maschera le informazioni memorizzate nei seguenti elementi:

  • Sezione dei modelli Metadata. CloudFormation non trasforma, modifica oppure omette le informazioni incluse nella sezione Metadata. Per ulteriori informazioni, vedere Metadati.

  • Sezione dei modelli Outputs. Per ulteriori informazioni, consulta Output.

  • Attributo Metadata di una definizione di risorsa. Per ulteriori informazioni, consulta Attributo Metadata.

Si consiglia vivamente di non utilizzare questi meccanismi per includere informazioni sensibili, come password o segreti.

Importante

Anziché incorporare informazioni sensibili direttamente nei modelli CloudFormation, si consiglia di utilizzare parametri dinamici nel modello stack per fare riferimento alle informazioni riservate archiviate e gestite al di fuori di CloudFormation, ad esempio nell’archivio parametri di AWS Systems Manager o in Gestione dei segreti AWS.

Per ulteriori informazioni, consulta la best practice Non incorporare le credenziali nei modelli.

Importante

Consigliamo vivamente di non includere parametri NoEcho o dati sensibili, nelle proprietà delle risorse che fanno parte dell’identificatore principale di una risorsa.

Quando il parametro NoEcho è incluso in una proprietà che forma un identificatore di risorsa principale, CloudFormation può utilizzare il valore di testo normale effettivo nell’identificatore di risorsa principale. Questo ID risorsa può apparire in qualsiasi output o destinazione derivata.

Per determinare quali proprietà delle risorse comprendono l’identificatore principale di un tipo di risorsa, consulta la documentazione di riferimento delle risorse per la risorsa in questione in AWS resource and property types reference. Nella sezione Return values (Valori restituiti), il valore restituito della funzione Ref rappresenta le proprietà delle risorse che comprendono l’identificatore principale del tipo di risorsa.

Type

Tipo di dati per il parametro (DataType).

Campo obbligatorio: sì

CloudFormation supporta i seguenti tipi di parametro:

String

Stringa letterale. Puoi utilizzare i seguenti attributi per dichiarare i vincoli: MinLength, MaxLength, Default, AllowedValues e AllowedPattern.

Ad esempio, gli utenti possono specificare "MyUserName".

Number

Numero intero o float. CloudFormation convalida il valore del parametro come numero. Tuttavia, quando utilizzi il parametro in una posizione diversa nel modello (ad esempio, utilizzando la funzione intrinseca Ref), il valore del parametro diventa una stringa.

Puoi utilizzare i seguenti attributi per dichiarare i vincoli: MinValue, MaxValue, Default e AllowedValues.

Ad esempio, gli utenti possono specificare "8888".

List<Number>

Matrice di numeri interi o float separati da virgole. CloudFormation convalida il valore del parametro come numeri. Tuttavia, quando utilizzi il parametro in una posizione diversa nel modello (ad esempio, utilizzando la funzione intrinseca Ref), il valore del parametro diventa un elenco di stringhe.

Ad esempio, gli utenti possono specificare "80,20" e Ref restituisce ["80","20"].

CommaDelimitedList

Matrice di stringhe letterali separate da virgole. Il numero totale di stringhe deve corrispondere al numero totale di virgole più uno. Ogni stringa membro non deve includere spazi.

Ad esempio, gli utenti possono specificare "test,dev,prod" e Ref restituisce ["test","dev","prod"].

Tipi di parametri specifici per AWS

Valori AWS, ad esempio i nomi di coppie di chiavi Amazon EC2 e gli ID VPC. Per ulteriori informazioni, consulta Specifica delle risorse esistenti in fase di runtime.

Tipi di parametro di Systems Manager

Parametri che corrispondono ai parametri esistenti in Archivio parametri Systems Manager. Puoi specificare una chiave di parametro Systems Manager come tipo di parametro Systems Manager e CloudFormation recupera il valore più recente dal Parameter Store per utilizzarlo per lo stack. Per ulteriori informazioni, consulta Specifica delle risorse esistenti in fase di runtime.

Requisiti generali per i parametri

Per l’utilizzo dei parametri sono validi i seguenti requisiti:

  • Un modello CloudFormation può contenere un massimo di 200 parametri.

  • A ogni parametro deve essere assegnato un nome logico (definito anche ID logico), che deve essere alfanumerico e univoco rispetto a tutti i nomi logici all’interno del modello.

  • A ogni parametro deve essere assegnato un tipo di parametro supportato da CloudFormation. Per ulteriori informazioni, consulta la sezione Type.

  • A ogni parametro deve essere assegnato un valore di runtime per consentire a CloudFormation di effettuare il provisioning dello stack. Puoi specificare facoltativamente un valore predefinito per CloudFormation, a meno che non venga fornito un altro valore.

  • I parametri e i relativi riferimenti a essi devono essere dichiarati dall’interno dello stesso modello. Puoi fare riferimento ai parametri dalle sezioni Resources e Outputs del modello.

Esempi

Parametro stringa semplice

L’esempio seguente dichiara un parametro denominato InstanceTypeParameter di tipo String. Questo parametro consente di specificare il tipo di istanza Amazon EC2 per lo stack. Se non viene fornito alcun valore durante la creazione o l’aggiornamento dello stack, CloudFormation utilizza il valore predefinito 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

Parametro password

L’esempio seguente dichiara un parametro denominato DBPwd di tipo String senza valore predefinito. La proprietà NoEcho è impostata su true per impedire che il valore del parametro venga visualizzato nelle descrizioni degli stack. La lunghezza minima che può essere specificata è 1e la lunghezza massima che può essere specificata è 41. Il modello consente l’uso di caratteri alfabetici in maiuscolo e minuscolo e di numeri. Questo esempio illustra anche l’uso di un’espressione regolare per la proprietà 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]*$

Riferimento dei parametri

Puoi utilizzare la funzione intrinseca Ref per fare riferimento a un parametro e CloudFormation utilizza il valore del parametro per effettuare il provisioning dello stack. Puoi fare riferimento ai parametri dalle sezioni Resources e Outputs dello stesso modello.

In questo esempio, la proprietà InstanceType della risorsa dell’istanza EC2 fa riferimento al valore del parametro 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

Parametro elenco definito da virgole

Il parametro di tipo CommaDelimitedList può essere utile quando è necessario fornire più valori per una singola proprietà. L’esempio seguente dichiara un parametro denominato DbSubnetIpBlocks con un valore predefinito di tre intervalli CIDR separati da virgole.

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"

Restituzione un valore da un parametro CommaDelimitedList

Per fare riferimento a un valore specifico in un elenco, utilizza la funzione intrinseca Fn::Select nella sezione Resources del modello. Puoi trasmettere il valore di indice dell’oggetto desiderato e un elenco di oggetti, come mostrato nell’esempio seguente.

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 supporta anche l’uso di riferimenti dinamici per specificare dinamicamente i valori delle proprietà. Ad esempio, potrebbe essere necessario fare riferimento di stringhe sicure archiviate in Systems Manager Parameter Store. Per ulteriori informazioni, consulta Ottenimento di valori archiviati in altri servizi utilizzando riferimenti dinamici.

Puoi inoltre utilizzare gli pseudo parametri all’interno di una funzione Ref o Sub per compilare dinamicamente i valori. Per ulteriori informazioni, consulta Ottenimento di valori AWS usando pseudo parametri.