Parameters
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.
É possível criar seus próprios parâmetros personalizados do zero ou usar um tipo de parâmetro fornecido pelo CloudFormation. Para obter mais informações, consulte Usar 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 obter mais informações, consulte Mappings.
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 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 com 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
ouCommaDelimitedList
. Quando aplicado a um parâmetro do tipoString
, o padrão deve corresponder ao valor de parâmetro inteiro fornecido. Quando aplicado a um parâmetro do tipoCommaDelimitedList
, 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 tipoCommaDelimitedList
, 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
eNo
paraAllowedValues
, 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
comotrue
, 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:-
A seção de modelo de
Metadata
. O CloudFormation não transforma, modifica nem edita nenhuma informação incluída na seçãoMetadata
. Para obter mais informações, consulte Metadata. -
A seção de modelo de
Outputs
. Para obter mais informações, consulte Outputs. -
O atributo
Metadata
de uma definição de recurso. Para obter mais informações, consulte Atributo Metadata.
É 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
eAllowedPattern
.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
eAllowedValues
.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 umaRef
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 umaRef
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 obter mais informações, consulte Referêncas de tipos de parâmetros específicos da AWS.
- 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 busca o valor mais recente no Parameter Store para usá-lo na pilha. Para obter mais informações, consulte Referência de tipos de parâmetros do Systems Manager.
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
eOutputs
do modelo.
Exemplos
Tópicos
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
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.
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 Referência de pseudoparâmetros.