# Sintaxe de Parameters de modelo 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 obter mais informações, consulte [Especificar recursos existentes no runtime com tipos de parâmetros fornecidos pelo CloudFormation](cloudformation-supplied-parameter-types.md). 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 obter mais informações, consulte [Sintaxe de Mappings de modelo do CloudFormation](mappings-section-structure.md). ## 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 obter mais informações, consulte [Organizar parâmetros do CloudFormation com metadados `AWS::CloudFormation::Interface`](aws-cloudformation-interface.md). 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 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 (\$1\$1\$1\$1\$1) para qualquer chamada que descreva a pilha ou os eventos de pilha, exceto informações armazenadas nos locais especificados abaixo. *Obrigatório*: não O uso do atributo `NoEcho` não mascara informações armazenadas no seguinte: + A seção de modelo de `Metadata`. O CloudFormation não transforma, modifica nem edita nenhuma informação incluída na seção `Metadata`. Para obter mais informações, consulte [Metadados](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/metadata-section-structure.html). + A seção de modelo de `Outputs`. Para obter mais informações, consulte [Saídas](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/outputs-section-structure.html). + O atributo `Metadata` de uma definição de recurso. Para obter mais informações, consulte o atributo [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-attribute-metadata.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-attribute-metadata.html). É altamente recomendável não usar esses mecanismos para incluir informações confidenciais, como senhas ou segredos. 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 a prática recomendada [Não incorporar credenciais nos seus modelos](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/security-best-practices.html#creds). É 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 desse recurso na [Referência de tipos de propriedades e recursos da AWS](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-template-resource-type-ref.html). 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` 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"]`. AWSTipos de parâmetros específicos da Os valores da AWS, como nomes de pares de chaves do Amazon EC2 e IDs de VPC. Para obter mais informações, consulte [Especificar recursos existentes no runtime](cloudformation-supplied-parameter-types.md). 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 obter mais informações, consulte [Especificar recursos existentes no runtime](cloudformation-supplied-parameter-types.md). ## 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](#parameters-section-structure-properties-type). + 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 **Topics** + [Parâmetro String simples](#parameters-section-structure-example-1) + [Parâmetro de senha](#parameters-section-structure-example-2) + [Referenciar parâmetros](#parameters-section-structure-example-3) + [Parâmetro de lista delimitada por vírgulas](#parameters-section-structure-example-4) + [Retornar um valor de um parâmetro da lista delimitada por vírgula](#parameters-section-structure-example-5) ### 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::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 ``` ## Recursos relacionados 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 obter mais informações, consulte [Obter valores armazenados em outros serviços usando referências dinâmicas](dynamic-references.md). Você também pode usar pseudoparâmetros em uma `Ref` ou em uma função `Sub` para preencher valores dinamicamente. Para obter mais informações, consulte [Obter valores da AWS usando pseudoparâmetros](pseudo-parameter-reference.md).