Parámetros

Utilice la sección Parameters opcional para personalizar sus plantillas. Los parámetros le permiten introducir valores personalizados a su plantilla cada vez que crea o actualiza una pila.

Definición de un parámetro en una plantilla

En el siguiente ejemplo se declara un parámetro denominado InstanceTypeParameter. Este parámetro le permite especificar el tipo de instancia Amazon EC2 para la pila que se usará al crear o actualizar la pila.

Tenga en cuenta que InstanceTypeParameter tiene un valor predeterminado de t2.micro. Este es el valor que AWS CloudFormation usa para aprovisionar la pila a menos que se proporcione otro valor.

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

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

Referencia a un parámetro dentro de una plantilla

Puede usar la función intrínseca Ref para hacer referencia a un parámetro, mientras que AWS 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:

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

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

Requisitos generales para los parámetros

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

"Parameters" : {
  "ParameterLogicalID" : {
    "Type" : "DataType",
    "ParameterProperty" : "value"
  }
}

Parameters:
  ParameterLogicalID:
    Type: DataType
    ParameterProperty: value

Propiedades

Tipos de parámetros específicos de AWS

Los tipos de parámetros específicos de AWS son útiles para la captura de valores no válidos al comienzo de la creación o actualización de una pila. Para especificar parámetros con tipos específicos de AWS, un usuario de plantilla debe escribir valores existentes de AWS que estén en la cuenta de AWS. AWS CloudFormation valida dichos valores de entrada y los compara con los valores existentes en la cuenta. Por ejemplo, con el tipo de parámetro AWS::EC2::VPC::Id, un usuario debe escribir un ID de VPC existente que está en la cuenta y en la región en la que está creando la pila.

Si desea permitir que los usuarios de la plantilla introduzcan valores de entrada de diferentes cuentas de AWS, no defina parámetros con tipos específicos de AWS; en su lugar, defina los parámetros de tipo String (o CommaDelimitedList).

Tipos de parámetros específicos de AWS compatibles

AWS CloudFormation es compatible con los siguientes tipos específicos de AWS:

Tipos de parámetros de SSM

Los tipos de parámetros SSM corresponden a parámetros existentes en el Systems Manager Parameter Store. Puede especificar una clave de Systems Manager como el valor del parámetro SSM y AWS CloudFormation recupera el valor más reciente de Parameter Store que se usará para la pila. Para los parámetros SSM almacenados en el mismo Cuenta de AWS, introduzca el nombre del parámetro. Para los parámetros SSM compartidos por otra Cuenta de AWS, introduzca el ARN completo del parámetro. Para obtener más información acerca de los parámetros de Systems Manager, consulte Systems Manager Parameter Store y Trabajar con parámetros compartidos en la Guía del usuario de AWS Systems Manager.

También puede usar el patrón de parámetro dinámico ssm o ssm-secure para especificar valores de parámetros en su plantilla. Para obtener más información, consulte Uso de referencias dinámicas para especificar valores de plantillas.

Al crear o actualizar pilas y crear conjuntos de cambios, AWS CloudFormation usa los valores que existan en Parameter Store en el momento de la ejecución de la operación. Si un parámetro especificado no existe en Parameter Store con la cuenta de AWS del intermediario, AWS CloudFormation devuelve un error de validación.

Al ejecutar un conjunto de cambios, AWS CloudFormation usa los valores que es especifican en el conjunto de cambios. Debe revisar estos valores antes de ejecutar el conjunto de cambios porque pueden cambiar en el almacén de parámetros entre el momento de la creación del conjunto de cambios y su ejecución.

Como el valor de un parámetro SSM es una clave de parámetro de Administrador de sistemas, debe tener en cuenta el siguiente comportamiento:

Consulte Tipos de parámetros de SSM para ver ejemplos de uso de los tipos de parámetros SSM.

Tipos de parámetros SSM admitidos

AWS CloudFormation admite los siguientes tipos de parámetros SSM:

Tipos de parámetros SSM no admitidos

AWS CloudFormation no admite los siguientes tipos de parámetros SSM:

Además, AWS CloudFormation no es compatible con la definición de parámetros de plantillas como tipos de parámetros de Systems Manager SecureString. Sin embargo, también puede especificar SecureString como valores de parámetros para algunos recursos, usando patrones de parámetros dinámicos. Para obtener más información, consulte Uso de referencias dinámicas para especificar valores de plantillas.

Agrupación y orden de parámetros en la consola de AWS CloudFormation

Cuando utiliza la consola de AWS CloudFormation para crear o actualizar una pila, la consola muestra alfabéticamente parámetros de entrada por su ID lógico. Para anular el orden predeterminado, puede utilizar la clave de metadatos AWS::CloudFormation::Interface. Al agrupar y ordenar parámetros, facilita a los usuarios la especificación de los valores de los parámetros. Por ejemplo, puede agrupar todos los parámetros relacionados con la VPC de forma que no estén diseminados en una lista alfabética.

En la clave de metadatos, puede especificar los grupos que desea crear, los parámetros que desea incluir en cada grupo y el orden en el que la consola muestra cada parámetro dentro de su grupo. También puede definir nombres de parámetros fáciles de recordar, de forma que la consola muestre nombres descriptivos en lugar de los ID lógicos. Todos los parámetros a los que se hace referencia en la clave de metadatos deben declararse en la sección Parameters de la plantilla.

Para obtener más información y un ejemplo de la clave de metadatos AWS::CloudFormation::Interface, consulte AWS::CloudFormation::Interface.

Ejemplos

Parámetros de entrada básica

La siguiente sección Parameters de ejemplo declara dos parámetros. El parámetro DBPort es de tipo Number con un valor predeterminado de 3306. El valor mínimo que se puede especificar es 1150 y el valor máximo que se puede especificar es 65535. El parámetro DBPwd es de tipo String sin valor predeterminado. La propiedad NoEcho se establece en true para impedir que las llamadas describe stack, como el comando aws cloudformation describe-stacks de la AWS CLI, devuelvan el valor del parámetro. 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.

"Parameters" : {
  "DBPort" : {
    "Default" : "3306",
    "Description" : "TCP/IP port for the database",
    "Type" : "Number",
    "MinValue" : "1150",
    "MaxValue" : "65535"
  },
  "DBPwd" : {
    "NoEcho" : "true",
    "Description" : "The database admin account password",
    "Type" : "String",
    "MinLength" : "1",
    "MaxLength" : "41",
    "AllowedPattern" : "^[a-zA-Z0-9]*$"
  }
}

Parameters: 
  DBPort: 
    Default: 3306
    Description: TCP/IP port for the database
    Type: Number
    MinValue: 1150
    MaxValue: 65535
  DBPwd: 
    NoEcho: true
    Description: The database admin account password
    Type: String
    MinLength: 1
    MaxLength: 41
    AllowedPattern: ^[a-zA-Z0-9]*$

Tipos de parámetros específicos de AWS

Cuando se utilizan tipos de parámetros específicos de AWS, un usuario que utilice la plantilla para crear o actualizar una pila debe especificar valores de AWS existentes que estén en la cuenta del usuario y en la región de la pila actual. Los tipos de parámetros específicos de AWS ayudan a garantizar que los valores de entrada para estos tipos de parámetros existan y sean correctos antes de que AWS CloudFormation cree o actualice cualquier recurso. Por ejemplo, si utiliza el tipo de parámetro AWS::EC2::KeyPair::KeyName, AWS CloudFormation valida el valor de entrada frente a los nombres de pares de clave existentes de los usuarios antes de crear cualquier recurso, como instancias de Amazon EC2.

Si un usuario utiliza la AWS Management Console, AWS CloudFormation rellena previamente los tipos de parámetros específicos de AWS con valores válidos. De esta forma el usuario no tiene que recordar y escribir correctamente un nombre específico o ID. Simplemente seleccionarían uno o más valores de una lista desplegable. Además, en función del tipo de parámetro, los usuarios pueden buscar valores por ID, nombre o el valor de la etiqueta del nombre. Para obtener más información, consulte Especificación del nombre de pila y los parámetros.

El siguiente ejemplo declara dos parámetros con los tipos AWS::EC2::KeyPair::KeyName y AWS::EC2::Subnet::Id. Estos tipos limitan los valores válidos a nombres de pares de claves existentes y los ID de subred. Dado que el parámetro mySubnetIDs se especifica como una lista, un usuario puede especificar uno o varios ID de subred.

"Parameters" : {
  "myKeyPair" : {
    "Description" : "Amazon EC2 Key Pair",
    "Type" : "AWS::EC2::KeyPair::KeyName"
  },
  "mySubnetIDs" : {
    "Description" : "Subnet IDs",
    "Type" : "List<AWS::EC2::Subnet::Id>"
  }
}

Parameters: 
  myKeyPair: 
    Description: Amazon EC2 Key Pair
    Type: "AWS::EC2::KeyPair::KeyName"
  mySubnetIDs: 
    Description: Subnet IDs
    Type: "List<AWS::EC2::Subnet::Id>"

Compatibilidad con la AWS CLI y la API

En la actualidad, los usuarios no pueden utilizar la AWS CLI o la API de AWS CloudFormation a fin de ver una lista de los valores válidos para los parámetros específicos de AWS. Sin embargo, pueden ver información sobre cada uno de los parámetros, como el tipo de parámetros, ejecutando el comando aws cloudformation get-template-summary o la API GetTemplateSummary.

Tipo de parámetros de lista delimitados por comas

Puede utilizar el tipo de parámetro CommaDelimitedList para especificar múltiples valores de cadena en un único parámetro. De esta forma, puede utilizar un único parámetro en lugar de diferentes parámetros para especificar múltiples valores. Por ejemplo, si crea tres subredes diferentes con sus propios bloques de CIDR, podría utilizar tres parámetros diferentes para especificar tres bloques de CIDR diferentes. Sin embargo, es más sencillo utilizar un único parámetro que toma una lista de tres bloques de CIDR, tal y como se muestra en el siguiente fragmento de código:

"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"
  }
}

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, utilice la función intrínseca Fn::Select en la sección Resources de la plantilla. Puede transferir el valor de índice del objeto que desea y una lista de objetos, tal y como se muestra en el siguiente fragmento de código:

"DbSubnet1" : {
  "Type" : "AWS::EC2::Subnet",
  "Properties" : {
    "AvailabilityZone" : {"Fn::Join" : ["",[ { "Ref" : "AWS::Region" }, { "Fn::Select" : [ "0", {"Ref" : "VpcAzs"} ] } ] ]} ,
    "VpcId" :  { "Ref" : "VPC" },
    "CidrBlock" : { "Fn::Select" : [ "0", {"Ref" : "DbSubnetIpBlocks"} ] }
  }
},
"DbSubnet2" : {
  "Type" : "AWS::EC2::Subnet",
  "Properties" : {
    "AvailabilityZone" : {"Fn::Join" : ["",[ { "Ref" : "AWS::Region" }, { "Fn::Select" : [ "1", {"Ref" : "VpcAzs"} ] } ] ]} ,
    "VpcId" : { "Ref" : "VPC" },
    "CidrBlock" : { "Fn::Select" : [ "1", {"Ref" : "DbSubnetIpBlocks"} ] }
  }
},
"DbSubnet3" : {
  "Type" : "AWS::EC2::Subnet",
  "Properties" : {
    "AvailabilityZone" : {"Fn::Join" : ["",[ { "Ref" : "AWS::Region" }, { "Fn::Select" : [ "2", {"Ref" : "VpcAzs"} ] } ] ]} ,
    "VpcId" : { "Ref" : "VPC" },
    "CidrBlock" : { "Fn::Select" : [ "2", {"Ref" : "DbSubnetIpBlocks"} ] }
  }
}

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]

Tipos de parámetros de SSM

Tipo AWS::SSM::Parameter::Value<String>

En la siguiente plantilla se declara un tipo de parámetro AWS::SSM::Parameter::Value<String>.

{
  "Parameters": {
    "InstanceType": {
      "Type": "AWS::SSM::Parameter::Value<String>"
    }
  },
  "Resources": {
    "Instance": {
      "Type": "AWS::EC2::Instance",
      "Properties": {
        "InstanceType": {
          "Ref": "InstanceType"
        }
      }
    }
  }
}

Parameters: 
  InstanceType: 
    Type: 'AWS::SSM::Parameter::Value<String>'
Resources: 
  Instance: 
    Type: 'AWS::EC2::Instance'
    Properties: 
      InstanceType: !Ref InstanceType

El siguiente comando crea una pila basada en la plantilla de ejemplo. Proporciona la clave de parámetro de Systems Manager (myInstanceType) como valor del parámetro de la plantilla InstanceType. Se presupone que el parámetro myInstanceType existe en Parameter Store en la cuenta de AWS del intermediario.

aws cloudformation create-stack --stack-name S1 --template-body example template --parameters ParameterKey=InstanceType,ParameterValue=myInstanceType

Tipo AWS::SSM::Parameter::Value<AWS::EC2::Image::Id>

En la siguiente plantilla se declara un tipo de parámetro AWS::SSM::Parameter::Value<AWS::EC2::Image::Id>.

{
  "Parameters": {
    "ImageId": {
      "Type": "AWS::SSM::Parameter::Value<AWS::EC2::Image::Id>"
    }
  },
  "Resources": {
    "Instance": {
      "Type": "AWS::EC2::Instance",
      "Properties": {
        "ImageId": {
          "Ref": "ImageId"
        }
      }
    }
  }
}

Parameters: 
  ImageId: 
    Type: 'AWS::SSM::Parameter::Value<AWS::EC2::Image::Id>'
Resources: 
  Instance: 
    Type: 'AWS::EC2::Instance'
    Properties:
      ImageId: !Ref ImageId

El siguiente comando crea una pila basada en la plantilla de ejemplo. Proporciona la clave de parámetro de Systems Manager (myLatestAMI) como valor del parámetro de la plantilla ImageId. Se presupone que el parámetro myLatestAMI existe en Parameter Store en la cuenta de AWS del intermediario.

aws cloudformation create-stack --stack-name S2 --template-body example template --parameters ParameterKey=ImageId,ParameterValue=myLatestAMI