Referência de sintaxe de seção Parameters para modelos do CloudFormation - AWS CloudFormation
SintaxePropriedadesRequisitos gerais de parâmetrosExemplosRecursos relacionados

Referência de sintaxe de seção Parameters para modelos do CloudFormation

Use seção opcional Parameters para personalizar os modelos. Com os parâmetros, é possível inserir valores personalizados no modelo toda vez que criar ou atualizar uma pilha. Ao usar parâmetros nos modelos, é possível criar modelos reutilizáveis e flexíveis que podem ser personalizados para cenários específicos.

Ao definir parâmetros do tipo apropriado, você pode escolher entre uma lista de identificadores de recursos existentes ao usar o console para criar sua pilha. Para ter mais informações, consulte Faça referência aos recursos existentes e aos parâmetros do Systems Manager com os tipos de parâmetros fornecidos pelo CloudFormation.

Os parâmetros são uma forma popular de especificar valores de propriedades de recursos de pilha. No entanto, pode haver configurações dependentes de região ou um pouco complexas para os usuários entenderem devido a outras condições ou dependências. Nesses casos, talvez você queira colocar alguma lógica no modelo em si de modo que os usuários possam especificar valores mais simples (ou não) para obter os resultados desejados, por exemplo, usando um mapeamento. Para ter mais informações, consulte Referência de sintaxe de seção Mappings para modelos do CloudFormation.

Sintaxe

Você declara parâmetros em uma seção Parameters do modelo, que usa a seguinte sintaxe geral:

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

Um parâmetro contém uma lista de atributos que definir o valor e as restrições em relação ao seu valor. O único atributo obrigatório é Type, que pode ser String, Number ou um tipo de parâmetro fornecido pelo CloudFormation. Também é possível adicionar um atributo Description que descreve que tipo de valor deve ser especificado. O nome e a descrição do parâmetro são exibidos na página Especificar parâmetros quando um usuário usa o modelo no assistente Criar pilha.

nota

Por padrão, o console do CloudFormation lista os parâmetros de entrada em ordem alfabética por ID lógico. Para substituir essa ordem padrão e agrupar os parâmetros relacionados, use a chave de metadados AWS::CloudFormation::Interface no modelo. Para ter mais informações, consulte AWS::CloudFormation::Interface.

Para parâmetros com valores padrão, o CloudFormation usa os valores padrão, a menos que os usuários especifiquem outro valor. Se você omitir o atributo padrão, os usuários deverão especificar um valor para esse parâmetro. No entanto, exigir que o usuário insira um valor não garante que o valor seja válido. Para validar o valor de um parâmetro, você pode declarar restrições ou especificar um tipo de parâmetro específico da AWS.

Para parâmetros sem valores padrão, os usuários devem especificar o valor do nome de uma chave na criação da pilha. Se isso não for feito, o CloudFormation falhará ao criar a pilha e lançará uma exceção:

Parameters: [KeyName] must have values

Propriedades

AllowedPattern

Uma expressão regular que representa os padrões a serem permitidos para tipos String ou CommaDelimitedList. Quando aplicado a um parâmetro do tipo String, o padrão deve corresponder ao valor de parâmetro inteiro fornecido. Quando aplicado a um parâmetro do tipo CommaDelimitedList, o padrão deve corresponder a cada valor da lista.

Obrigatório: não

AllowedValues

Uma matriz que contém a lista de valores permitidos para o parâmetro. Quando aplicado a um parâmetro do tipo String, o valor do parâmetro deve ser um dos valores permitidos. Quando aplicado a um parâmetro do tipo CommaDelimitedList, cada valor da lista deve ser um dos valores permitidos especificados.

Obrigatório: não

nota

Se você estiver usando YAML e quiser usar as strings Yes e No para AllowedValues, use aspas simples para evitar que o analisador YAML considere esses valores como booleanos.

ConstraintDescription

Uma sequência que explica uma restrição quando a restrição é violada. Por exemplo, sem uma descrição da restrição, um parâmetro que tem um padrão permitido de [A-Za-z0-9]+ exibe a seguinte mensagem de erro quando o usuário especifica um valor inválido:

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

Ao adicionar uma descrição de restrição, como deve conter apenas letras (maiúsculas e minúsculas) e números, você pode exibir a seguinte mensagem de erro personalizada:

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

Obrigatório: não

Default

Um valor do tipo apropriado para o modelo a ser usado se nenhum valor for especificado quando uma pilha é criada. Se definir restrições para o parâmetro, você deverá especificar um valor que esteja de acordo com essas restrições.

Obrigatório: não

Description

Uma sequência de até 4000 caracteres que descreve o parâmetro.

Obrigatório: não

MaxLength

Um valor inteiro que determina o maior número de caracteres que você deseja permitir para tipos String.

Obrigatório: não

MaxValue

Um valor numérico que determina o maior valor numérico que você deseja permitir para tipos Number.

Obrigatório: não

MinLength

Um valor inteiro que determina o menor número de caracteres que você deseja permitir para tipos String.

Obrigatório: não

MinValue

Um valor numérico que determina o menor valor numérico que você deseja permitir para tipos Number.

Obrigatório: não

NoEcho

Se o valor do parâmetro deve ser mascarado para impedir que ele seja exibido no console, nas ferramentas de linha de comando ou na API. Se você definir o atributo NoEcho como true, o CloudFormation retornará o valor do parâmetro mascarado como asteriscos (*****) para qualquer chamada que descreva a pilha ou os eventos de pilha, exceto informações armazenadas nos locais especificados abaixo.

Obrigatório: não

Importante

O uso do atributo NoEcho não mascara informações armazenadas no seguinte:

É altamente recomendável não usar esses mecanismos para incluir informações confidenciais, como senhas ou segredos.

Importante

Em vez de incorporar informações confidenciais diretamente em modelos do CloudFormation, recomendamos usar os parâmetros dinâmicos no modelo da pilha para fazer referência a informações confidenciais que são armazenadas e gerenciadas de forma externa ao CloudFormation, como no AWS Systems Manager Parameter Store ou no AWS Secrets Manager.

Para obter mais informações, consulte as práticas recomendadas do Não incorporar credenciais em seus modelos.

Importante

É altamente recomendável evitar parâmetros NoEcho, ou dados confidenciais, nas propriedades do recurso que fazem parte do identificador primário de um recurso.

Quando um parâmetro NoEcho está incluído em uma propriedade que forma um identificador de recurso primário, o CloudFormation pode utilizar o valor de texto sem formatação real no identificador do recurso primário. Esse ID de recurso pode aparecer em quaisquer saídas ou destinos derivados.

Para determinar quais propriedades de recursos compreendem o identificador primário de um tipo de recurso, consulte a documentação de referência de recursos para esse recurso específico em Referência de tipos de propriedades e recursos da AWS. Na seção Return values (Valores de retorno), o valor de retorno da função Ref representa as propriedades do recurso que compõem o identificador primário do tipo de recurso.

Type

O tipo de dados para o parâmetro (DataType).

Obrigatório: Sim

O CloudFormation oferece suporte aos seguintes tipos de parâmetros:

String

Uma sequência literal. É possível usar os seguintes atributos para declarar restrições: MinLength, MaxLength, Default, AllowedValues e AllowedPattern.

Por exemplo, os usuários podem especificar "MyUserName".

Number

Um inteiro ou flutuante. O CloudFormation valida o valor do parâmetro como um número. No entanto, quando você usa o parâmetro em outro lugar no modelo (por exemplo, usando a função intrínseca Ref), o valor do parâmetro se torna uma string.

É possível usar os seguintes atributos para declarar restrições: MinValue, MaxValue, Default e AllowedValues.

Por exemplo, os usuários podem especificar "8888".

List<Number>

Uma matriz de inteiros ou floats que são separados por vírgulas. O CloudFormation valida o valor do parâmetro como números. No entanto, quando você usa o parâmetro em outro lugar no modelo (por exemplo, usando a função intrínseca Ref), o valor do parâmetro se torna uma lista de strings.

Por exemplo, os usuários poderiam especificar "80,20", e uma Ref resultaria em ["80","20"].

CommaDelimitedList

Uma matriz de sequências literais que são separadas por vírgulas. O total de sequências deve ser um número a mais que o número total de vírgulas. Além disso, cada sequência membro é truncado por espaço.

Por exemplo, os usuários poderiam especificar "test,dev,prod", e uma Ref resultaria em ["test","dev","prod"].

Tipos de parâmetros específicos da AWS

Os valores da AWS, como nomes de pares de chaves do Amazon EC2 e IDs de VPC. Para ter mais informações, consulte Usar tipos de parâmetros fornecidos pelo CloudFormation.

Tipos de parâmetros do Systems Manager

Parâmetros que correspondem a parâmetros existentes no Armazenamento de parâmetros do Systems Manager. Você especifica uma chave de parâmetro do Systems Manager como o valor do tipo de parâmetro do Systems Manager e o CloudFormation recupera o valor mais recente no Parameter Store para usá-lo na pilha. Para ter mais informações, consulte Usar tipos de parâmetros fornecidos pelo CloudFormation.

Requisitos gerais de parâmetros

Os seguintes requisitos se aplicam ao usar parâmetros:

  • É possível ter no máximo 200 parâmetros em um modelo do CloudFormation.

  • Cada parâmetro deve receber um nome lógico (também chamado de ID lógico), que deve ser alfanumérico e exclusivo entre todos os nomes lógicos no modelo.

  • A cada parâmetro deve ser atribuído um tipo de parâmetro compatível com o CloudFormation. Para obter mais informações, consulte Tipo.

  • A cada parâmetro deve ser atribuído um valor em runtime para que o CloudFormation provisione a pilha com êxito. Se preferir, especifique um valor padrão para o CloudFormation usar, a menos que outro valor seja fornecido.

  • Os parâmetros devem ser declarados e referenciados no mesmo modelo. Você pode fazer referência a parâmetros nas seções Resources e Outputs do modelo.

Exemplos

Parâmetro String simples

O exemplo a seguir declara um parâmetro chamado InstanceTypeParameter do tipo String. Esse parâmetro permite que você especifique o tipo de instância do Amazon EC2 para a pilha. Se nenhum valor for fornecido durante a criação ou atualização da pilha, o CloudFormation usará o valor padrão 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 senha

O exemplo a seguir declara um parâmetro chamado DBPwd do tipo String sem valor padrão. A propriedade NoEcho é definida como true para evitar que o valor do parâmetro seja exibido nas descrições da pilha. O comprimento mínimo que pode ser especificado é 1, e o valor máximo é 41. O padrão permite caracteres alfabéticos maiúsculos e minúsculos e numerais. Esse exemplo também ilustra o uso de uma expressão regular para a propriedade 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]*$

Referenciar parâmetros

Você usa a função intrínseca Ref para fazer referência a um parâmetro, e o CloudFormation usa o valor do parâmetro para provisionar a pilha. Você pode fazer referência a parâmetros nas seções Resources e Outputs do mesmo modelo.

No exemplo a seguir, a propriedade InstanceType do recurso da instância do EC2 faz referência ao valor do 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âmetro de lista delimitada por vírgulas

O tipo de parâmetro CommaDelimitedList pode ser útil quando você precisa fornecer vários valores para uma única propriedade. O exemplo a seguir declara um parâmetro chamado DbSubnetIpBlocks com um valor padrão de três blocos CIDR separados por vírgulas.

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"

Retornar um valor de um parâmetro da lista delimitada por vírgula

Para fazer referência a um valor específico em uma lista delimitada por vírgulas de um parâmetro, use a função intrínseca Fn::Select na seção Resources do modelo. Passe o valor do índice do objeto que você deseja e uma lista de objetos, conforme mostrado no exemplo a seguir.

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

O CloudFormation também permite o uso de referências dinâmicas para especificar valores de propriedades dinamicamente. Por exemplo, talvez você precise fazer referência a strings seguras armazenadas no Systems Manager Parameter Store. Para ter mais informações, consulte Obter valores armazenados em outros serviços usando referências dinâmicas.

Você também pode usar pseudoparâmetros em uma Ref ou em uma função Sub para preencher valores dinamicamente. Para ter mais informações, consulte Referência de pseudoparâmetros.