Sintaxis de Parameters de la plantilla de CloudFormation - AWS CloudFormation

Sintaxis de Parameters de la plantilla de CloudFormation

Utilice la sección Parameters opcional para personalizar sus plantillas. Con los parámetros, puede ingresar valores personalizados a su plantilla cada vez que crea o actualiza una pila. Al usar parámetros en sus plantillas, puede crear plantillas flexibles y reutilizables que se pueden adaptar a escenarios específicos.

Al definir los parámetros del tipo adecuado, puede elegir de una lista de identificadores de los recursos existentes cuando utilice la consola para crear su pila. Para obtener más información, consulte Referencia a los recursos existentes y a los parámetros de Systems Manager con los tipos de parámetros proporcionados por CloudFormation.

Los parámetros son una forma común de especificar los valores de las propiedades de los recursos de la pila. Sin embargo, es posible que haya ajustes que dependan de la región o sean algo complejos para que los usuarios los averigüen debido a otras condiciones o dependencias. En estos casos, debería incluir algo de lógica en la propia plantilla para que los usuarios puedan especificar valores más sencillos (o ninguno en absoluto) para obtener los resultados que desean. Por ejemplo, puede usar asignaciones. Para obtener más información, consulte Sintaxis de Mappings de la plantilla de CloudFormation.

Sintaxis

Puede declarar parámetros en la sección Parameters de una plantilla, la cual usa la siguiente sintaxis general:

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 parámetro contiene una lista de atributos que definen su valor y limitaciones frente a su valor. El único atributo obligatorio es Type, que puede ser String, Number o un tipo de parámetro proporcionado por CloudFormation. También puede añadir un atributo Description que describe qué tipo de valor debe especificar. El nombre y la descripción del parámetro aparecen en la página Especificar parámetros cuando utiliza la plantilla en el asistente de Crear pila.

nota

De forma predeterminada, la consola de CloudFormation ordena alfabéticamente parámetros de entrada por su ID lógico. Para anular este orden predeterminado y agrupar los parámetros relacionados, puede usar la clave de metadatos AWS::CloudFormation::Interface de su plantilla. Para obtener más información, consulte AWS::CloudFormation::Interface.

Para parámetros con valores predeterminados, CloudFormation utiliza los valores predeterminados a menos que los usuarios especifiquen otro valor. Si omite el atributo predeterminado, los usuarios deben especificar un valor para ese parámetro. Sin embargo, exigir que el usuario ingrese un valor no garantiza que el valor sea válido. Para validar el valor de un parámetro, puede declarar limitaciones o indicar un tipo de parámetro específico de AWS.

En el caso de parámetros sin valores predeterminados, los usuarios deben especificar un valor de nombre de clave al crear la pila. Caso contrario, CloudFormation no logra crear la pila y arroja una excepción:

Parameters: [KeyName] must have values

Propiedades

AllowedPattern

Una expresión regular que representa los patrones que hay que permitir para tipos String o CommaDelimitedList. Cuando se aplica a un parámetro del tipo String, el patrón debe coincidir con todo el valor del parámetro proporcionado. Cuando se aplica a un parámetro del tipo CommaDelimitedList, el patrón debe coincidir con cada valor de la lista.

Obligatorio: no

AllowedValues

Una matriz que contiene la lista de valores permitidos para el parámetro. Cuando se aplica a un parámetro del tipo String, el valor del parámetro debe ser uno de los valores permitidos. Cuando se aplica a un parámetro del tipo CommaDelimitedList, cada valor de la lista debe ser uno de los valores permitidos especificados.

Obligatorio: no

nota

Si usa YAML y quiere usar cadenas Yes y No para AllowedValues, use comillas simples para evitar que el analizador YAML considere estos valores booleanos.

ConstraintDescription

Una cadena que explica una restricción cuando se infringe la restricción. Por ejemplo, sin una descripción de la restricción, un parámetro con un patrón permitido de [A-Za-z0-9]+ muestra el siguiente mensaje de error cuando el usuario especifica un valor no válido:

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

Al añadir una descripción de restricción, como, por ejemplo debe contener únicamente letras (mayúsculas y minúsculas) y números, puede mostrar el siguiente mensaje de error personalizado:

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

Obligatorio: no

Default

Un valor del tipo apropiado para la plantilla que se debe utilizar si no se especifica ningún valor al crear una pila. Si define restricciones para el parámetro, debe especificar un valor que cumpla dichas restricciones.

Obligatorio: no

Description

Una cadena de hasta 4000 caracteres que describe el parámetro.

Obligatorio: no

MaxLength

Cualquier valor entero que determina el mayor número de caracteres que desea permitir para tipos de String.

Obligatorio: no

MaxValue

Un valor numérico que determina el mayor valor numérico que desea permitir para tipos de Number.

Obligatorio: no

MinLength

Un valor entero que determina el menor número de caracteres que desea permitir para tipos de String.

Obligatorio: no

MinValue

Un valor numérico que determina el menor valor numérico que desea permitir para tipos de Number.

Obligatorio: no

NoEcho

Si se va a enmascarar el valor del parámetro para impedir que se muestre en la consola, en las herramientas de línea de comandos o en la API. Si establece el atributo NoEcho en true, CloudFormation devuelve el valor del parámetro enmascarado como asteriscos (*****) para cualquier llamada que describa la pila o los eventos de la pila, excepto para la información almacenada en las ubicaciones especificadas a continuación.

Obligatorio: no

importante

El uso del atributo NoEcho no enmascara ninguna información almacenada en lo que se muestra a continuación:

Recomendamos encarecidamente que no utilice estos mecanismos para incluir información confidencial, como contraseñas o secretos.

importante

En lugar de integrar información confidencial directamente en las plantillas de CloudFormation, se recomienda utilizar parámetros dinámicos en la plantilla de la pila para hacer referencia a la información confidencial almacenada y administrada fuera de CloudFormation, como en AWS Systems Manager Parameter Store o AWS Secrets Manager.

Para obtener más información, consulte las Prácticas recomendadas de No integre credenciales en sus plantillas.

importante

Recomendamos encarecidamente no incluir parámetros NoEcho ni ningún dato confidencial en las propiedades de los recursos que formen parte del identificador principal de un recurso.

Cuando se incluye un parámetro de NoEcho en una propiedad que forma un identificador de recursos principal, CloudFormation puede usar el valor de texto sin formato real en el identificador del recurso principal. Este ID de recurso puede aparecer en cualquier destino o salida derivada.

Para determinar qué propiedades de recursos comprenden el identificador principal de un tipo de recurso, consulte la documentación de referencia de recursos para ese recurso en Referencia de tipos de recursos y propiedades de AWS. En la sección Return values (Valores de devolución), el valor de devolución de la función Ref representa las propiedades del recurso que comprenden el identificador principal del tipo de recurso.

Type

El tipo de datos para el parámetro (DataType).

Obligatorio: sí

CloudFormation es compatible con los siguientes tipos de parámetros:

String

Una cadena literal. Puede usar los siguientes atributos para declarar las limitaciones: MinLength, MaxLength, Default, AllowedValues y AllowedPattern.

Por ejemplo, los usuarios podrían especificar "MyUserName".

Number

Un número entero o float. CloudFormation valida el valor del parámetro como un número; sin embargo, cuando utiliza el parámetro en otro sitio en la plantilla (por ejemplo, mediante el uso de la función intrínseca Ref), el valor del parámetro se convierte en una cadena.

Puede usar los siguientes atributos para declarar las limitaciones: MinValue, MaxValue, Default y AllowedValues.

Por ejemplo, los usuarios podrían especificar "8888".

List<Number>

Una matriz de valores enteros o floats que están separados por comas. CloudFormation valida el valor del parámetro como números; sin embargo, cuando utiliza el parámetro en otro sitio en la plantilla (por ejemplo, mediante el uso de la función intrínseca Ref), el valor del parámetro se convierte en una lista de cadenas.

Por ejemplo, los usuarios podrían especificar "80,20" y una Ref daría lugar a ["80","20"].

CommaDelimitedList

Una matriz de cadenas literales que están separadas por comas. El número total de cadenas debería ser uno más que el número total de comas. Además, en cada cadena de miembro se elimina el espacio.

Por ejemplo, los usuarios podrían especificar "test,dev,prod" y una Ref daría lugar a ["test","dev","prod"].

Tipos de parámetros específicos de AWS

Valores de AWS, como nombres de pares de claves e ID de VPC de Amazon EC2. Para obtener más información, consulte Uso de los tipos de parámetros proporcionados por CloudFormation.

Tipos de parámetros de Systems Manager

Parámetros correspondientes a los parámetros existentes en Administrador de sistemas Parameter Store. Puede especificar una clave de parámetro de Systems Manager como valor del tipo de parámetro de Systems Manager, y CloudFormation recupera el valor más reciente del Almacén de parámetros que se usará para la pila. Para obtener más información, consulte Uso de los tipos de parámetros proporcionados por CloudFormation.

Requisitos generales para los parámetros

Los siguientes requisitos se aplican al usar los parámetros:

  • Puede tener un máximo de 200 parámetros en una plantilla de CloudFormation.

  • Cada parámetro debe recibir un nombre lógico (también llamado ID lógico), que tiene que ser alfanumérico y único entre todos los nombres lógicos dentro de la plantilla.

  • A cada parámetro se le debe asignar un tipo de parámetro compatible con CloudFormation. Para obtener más información, consulte Tipo.

  • A cada parámetro se le debe asignar un valor en tiempo de ejecución para que CloudFormation aprovisione correctamente la pila. Si lo desea, puede especificar un valor predeterminado para que CloudFormation lo use a menos que se proporcione otro valor.

  • Los parámetros se deben declarar y se debe hacer referencia a ellos desde la misma plantilla. Puede hacer referencia a los parámetros en las secciones Resources y Outputs de la plantilla.

Ejemplos

Parámetro de cadena simple

En el siguiente ejemplo se declara un parámetro denominado InstanceTypeParameter de tipo String. Este parámetro le permite especificar el tipo de instancia de Amazon EC2 para la pila. Si no se proporciona ningún valor durante la creación o actualización de la pila, CloudFormation utiliza el valor predeterminado de 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

Parámetro de contraseña

En el siguiente ejemplo se declara un parámetro denominado DBPwd de tipo String con ningún valor predeterminado. La propiedad NoEcho está configurada en true para evitar que el valor del parámetro se muestre en las descripciones de las pilas. La longitud mínima que se puede especificar es 1 y la longitud máxima que se puede especificar es 41. El patrón permite caracteres alfabéticos en mayúsculas y minúsculas, y números. Este ejemplo también ilustra el uso de una expresión regular para la propiedad 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]*$

Parámetros de referencia

Puede usar la función intrínseca Ref para hacer referencia a un parámetro, mientras que CloudFormation utiliza el valor del parámetro para aprovisionar la pila. Puede hacer referencia a los parámetros en las secciones Resources y Outputs de la misma plantilla.

En el siguiente ejemplo, la propiedad InstanceType del recurso de instancia de EC2 hace referencia al valor del parámetro 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

Parámetros de lista delimitada por comas

El tipo de parámetro CommaDelimitedList puede resultar útil cuando se necesitan proporcionar varios valores para una sola propiedad. El siguiente ejemplo declara un parámetro denominado DbSubnetIpBlocks con un valor predeterminado de tres bloques CIDR separados por comas.

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"

Devuelva un valor de un parámetro de lista delimitada por comas

Para consultar un valor específico en una lista delimitada por comas del parámetro, utilice la función intrínseca Fn::Select en la sección Resources de la plantilla. Transfiera el valor de índice del objeto que desea y una lista de objetos, tal y como se muestra en el siguiente ejemplo.

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::Sub": [ "${AWS::Region}${AZ}", { "AZ": { "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: !Sub - ${AWS::Region}${AZ} - AZ: !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 también admite el uso de referencias dinámicas para especificar valores de propiedades de forma dinámica. Por ejemplo, puede que necesite hacer referencia a cadenas seguras almacenadas en el almacén de parámetros de Systems Manager. Para obtener más información, consulte Obtención de valores almacenados en otros servicios con referencias dinámicas.

También puede utilizar pseudoparámetros dentro de una función Ref o Sub para rellenar valores de forma dinámica. Para obtener más información, consulte Referencia de pseudoparámetros.