Saiba mais sobre noções básicas de modelo

Em Conceitos básicos, você aprendeu a usar um modelo para criar uma pilha. Você viu recursos declarados em um modelo e como eles mapeiam os recursos na pilha. Também abordamos parâmetros de entrada e como eles permitem que você passe em valores específicos ao criar uma pilha a partir de um modelo. Nesta seção, vamos detalhar os recursos e os parâmetros. Também abordaremos os outros componentes de modelos para que você saiba como usar esses componentes em conjunto e criar modelos que produzem os recursos da AWS que você deseja.

O que é um modelo do AWS CloudFormation?

Um modelo é uma declaração de recursos da AWS que compõem uma pilha. O modelo é armazenado como um arquivo de texto cujo formato está em conformidade com o JavaScript Object Notation (JSON) ou YAML padrão. Como são apenas arquivos de texto, você pode criar e editá-los em qualquer editor de texto e gerenciá-los em seu sistema de controle de fonte com o restante do seu código-fonte. Para obter mais informações sobre os formatos de modelos, consulte Formatos de modelo do AWS CloudFormation.

No modelo, você declara os recursos da AWS que deseja criar e configurar. Você pode declarar um objeto como um par nome/valor ou um par de um nome com um conjunto de objetos filho incluído. A sintaxe depende do formato que você usa. Para obter mais informações, consulte a Anatomia do modelo. O único objeto de nível superior necessário é o objeto Resources, que deve declarar pelo menos um recurso. Vamos começar com o modelo mais básico que contém apenas um objeto Resources, o qual apresenta uma única declaração de recurso.

Resources: Hello Bucket!

O objeto Resources contém uma lista de objetos de recurso. Uma declaração de recursos contém os atributos do recurso, que são declarados como objetos filho. Um recurso deve ter um atributo Type, que define o tipo de recurso da AWS que você deseja criar. O atributo Type tem um formato especial:

AWS::ProductIdentifier::ResourceType

Por exemplo, o tipo de recurso para um bucket do Amazon S3 é AWS::S3::Bucket. Para conhecer uma lista completa de tipos de recursos, consulte Referência do modelo.

Vamos dar uma olhada em um modelo básico. O modelo a seguir declara um único recurso do tipo AWS::S3::Bucket: com o nome HelloBucket.

JSON

{
    "Resources": {
        "HelloBucket": {
            "Type": "AWS::S3::Bucket"
        }
    }
}

YAML

Resources:
  HelloBucket:
    Type: 'AWS::S3::Bucket'

Se você usar esse modelo para criar uma pilha, o AWS CloudFormation criará um bucket do Amazon S3. A criação de um bucket é simples, pois o CloudFormation pode criar um bucket com configurações padrão. Para outros recursos, como um grupo do Amazon EC2 Auto Scaling ou instância EC2, o CloudFormation requer mais informações. As declarações do recurso usam um atributo Properties para especificar as informações usadas para criar um recurso.

Dependendo do tipo de recurso, algumas propriedades são necessárias, como a propriedade ImageId para um recurso AWS::EC2::Instance e outras são opcionais. Algumas propriedades têm valores padrão, como a propriedade AccessControl do recurso AWS::S3::Bucket, portanto, especificar um valor para essas propriedades é opcional. Outras propriedades não são necessárias, mas você poderá adicionar as funcionalidades desejadas, como a propriedade WebsiteConfiguration do recurso AWS::S3::Bucket. Especificar um valor para essas propriedades é totalmente opcional e com base em suas necessidades. No exemplo acima, como o recurso AWS::S3::Bucket tem apenas propriedades opcionais e nós não precisamos de qualquer um dos recursos opcionais, podemos aceitar os padrões e omitir o atributo Properties.

Para visualizar as propriedades de cada tipo de recurso, consulte os tópicos em Referência de tipos de propriedades e recursos da AWS.

Propriedades de recurso e uso de recursos em conjunto

Em geral, uma propriedade para um recurso é simplesmente um valor de string. Por exemplo, o modelo a seguir especifica uma ACL (PublicRead) pré-configurada para a propriedade AccessControl do bucket.

JSON

{
    "Resources": {
        "HelloBucket": {
            "Type": "AWS::S3::Bucket",
            "Properties": {
                "AccessControl": "PublicRead"
            }
        }
    }
}

YAML

Resources:
  HelloBucket:
    Type: 'AWS::S3::Bucket'
    Properties:
      AccessControl: PublicRead

Alguns recursos podem ter várias propriedades e algumas propriedades podem ter uma ou mais subpropriedades. Por exemplo, o recurso AWS::S3::Bucket tem duas propriedades, AccessControl e WebsiteConfiguration. A propriedade WebsiteConfiguration tem duas subpropriedades, IndexDocuments e ErrorDocument. O modelo a seguir mostra nosso recurso do bucket original com as propriedades adicionais.

JSON

{
    "Resources": {
        "HelloBucket": {
            "Type": "AWS::S3::Bucket",
            "Properties": {
                "AccessControl": "PublicRead",
                "WebsiteConfiguration": {
                    "IndexDocument": "index.html",
                    "ErrorDocument": "error.html"
                }
            }
        }
    }
}

YAML

Resources:
  HelloBucket:
    Type: 'AWS::S3::Bucket'
    Properties:
      AccessControl: PublicRead
      WebsiteConfiguration:
        IndexDocument: index.html
        ErrorDocument: error.html

Um dos maiores benefícios de modelos e do CloudFormation é a capacidade de criar um conjunto de recursos que funcionam em conjunto para criar um aplicativo ou uma solução. O nome usado para um recurso no modelo é um nome lógico. Quando o CloudFormation cria o recurso, ele gera um nome físico baseado na combinação do nome lógico, no nome da pilha e em um ID exclusivo.

Você está provavelmente pensando em como você definir as propriedades em um recurso baseado no nome ou na propriedade de outro recurso. Por exemplo, você pode criar uma distribuição do CloudFront com suporte de um bucket S3 ou uma instância do EC2 que usa grupos de segurança do EC2, e todos esses recursos podem ser criados no mesmo modelo. O CloudFormation tem uma série de funções intrínsecas que você pode usar para fazer referência a outros recursos e suas propriedades. Você pode usar a função Ref para fazer referência a uma propriedade de identificação de um recurso. Frequentemente, este é o nome físico do recurso; no entanto, às vezes pode ser um identificador, como o endereço IP para um recurso AWS::EC2::EIP ou um Nome de recurso da Amazon (ARN) para um tópico do Amazon SNS. Para obter uma lista de valores retornados pela função Ref, consulte Função Ref. O modelo a seguir contém o recurso AWS::EC2::Instance. A propriedade SecurityGroups do recurso chama a função Ref para fazer referência a InstanceSecurityGroup do recurso AWS::EC2::SecurityGroup.

JSON

{
    "Resources": {
        "Ec2Instance": {
            "Type": "AWS::EC2::Instance",
            "Properties": {
                "SecurityGroups": [
                    {
                        "Ref": "InstanceSecurityGroup"
                    }
                ],
                "KeyName": "mykey",
                "ImageId": ""
            }
        },
        "InstanceSecurityGroup": {
            "Type": "AWS::EC2::SecurityGroup",
            "Properties": {
                "GroupDescription": "Enable SSH access via port 22",
                "SecurityGroupIngress": [
                    {
                        "IpProtocol": "tcp",
                        "FromPort": 22,
                        "ToPort": 22,
                        "CidrIp": "0.0.0.0/0"
                    }
                ]
            }
        }
    }
}

YAML

Resources:
  Ec2Instance:
    Type: 'AWS::EC2::Instance'
    Properties:
      SecurityGroups:
        - !Ref InstanceSecurityGroup
      KeyName: mykey
      ImageId: ''
  InstanceSecurityGroup:
    Type: 'AWS::EC2::SecurityGroup'
    Properties:
      GroupDescription: Enable SSH access via port 22
      SecurityGroupIngress:
        - IpProtocol: tcp
          FromPort: 22
          ToPort: 22
          CidrIp: 0.0.0.0/0

A propriedade SecurityGroups é uma lista de security groups e, no exemplo anterior, temos somente um item na lista. O modelo a seguir tem um item adicional na lista de propriedades SecurityGroups.

JSON

{
    "Resources": {
        "Ec2Instance": {
            "Type": "AWS::EC2::Instance",
            "Properties": {
                "SecurityGroups": [
                    {
                        "Ref": "InstanceSecurityGroup"
                    },
                    "MyExistingSecurityGroup"
                ],
                "KeyName": "mykey",
                "ImageId": "ami-7a11e213"
            }
        },
        "InstanceSecurityGroup": {
            "Type": "AWS::EC2::SecurityGroup",
            "Properties": {
                "GroupDescription": "Enable SSH access via port 22",
                "SecurityGroupIngress": [
                    {
                        "IpProtocol": "tcp",
                        "FromPort": 22,
                        "ToPort": 22,
                        "CidrIp": "0.0.0.0/0"
                    }
                ]
            }
        }
    }
}

YAML

Resources:
  Ec2Instance:
    Type: 'AWS::EC2::Instance'
    Properties:
      SecurityGroups:
        - !Ref InstanceSecurityGroup
        - MyExistingSecurityGroup
      KeyName: mykey
      ImageId: ami-7a11e213
  InstanceSecurityGroup:
    Type: 'AWS::EC2::SecurityGroup'
    Properties:
      GroupDescription: Enable SSH access via port 22
      SecurityGroupIngress:
        - IpProtocol: tcp
          FromPort: 22
          ToPort: 22
          CidrIp: 0.0.0.0/0

MyExistingSecurityGroup é uma string que se refere a um security group EC2 já existente em vez de um security group declarado em um modelo. Você pode usar strings literais para fazer referência a recursos da AWS existentes.

No exemplo acima, a propriedade KeyName de AWS::EC2::Instance é a string literal mykey. Isso significa que um par de chaves com o nome mykey deve existir na região em que a pilha está sendo criada; caso contrário, a criação da pilha falhará porque o par de chaves não existe. O par de chaves que você usa pode variar de acordo com a região em que você está criando a pilha, ou você pode compartilhar o modelo com outra pessoa para que ela possa usá-lo com a conta da AWS. Se esse for o caso, você poderá usar um parâmetro de entrada para que o nome do par de chaves possa ser especificado quando a pilha for criada. A função Ref pode fazer referência a parâmetros de entrada especificados no momento de criação da pilha. O modelo a seguir adiciona o objeto Parâmetros que contém o parâmetro KeyName, que é usado para especificar a propriedade KeyName para o recurso AWS::EC2::Instance. O tipo de parâmetro é AWS::EC2::KeyPair::KeyName, o que garante a um usuário especificar um nome válido de par de chaves em sua conta e na região em que a pilha está sendo criada.

JSON

{
  "Parameters": {
    "KeyName": {
      "Description": "The EC2 Key Pair to allow SSH access to the instance",
      "Type": "AWS::EC2::KeyPair::KeyName"
    }
  },
  "Resources": {
    "Ec2Instance": {
      "Type": "AWS::EC2::Instance",
      "Properties": {
        "SecurityGroups": [
          {
            "Ref": "InstanceSecurityGroup"
          },
          "MyExistingSecurityGroup"
        ],
        "KeyName": {
          "Ref": "KeyName"
        },
        "ImageId": "ami-7a11e213"
      }
    },
    "InstanceSecurityGroup": {
      "Type": "AWS::EC2::SecurityGroup",
      "Properties": {
        "GroupDescription": "Enable SSH access via port 22",
        "SecurityGroupIngress": [
          {
            "IpProtocol": "tcp",
            "FromPort": 22,
            "ToPort": 22,
            "CidrIp": "0.0.0.0/0"
          }
        ]
      }
    }
  }
}

YAML

Parameters:
  KeyName:
    Description: The EC2 Key Pair to allow SSH access to the instance
    Type: 'AWS::EC2::KeyPair::KeyName'
Resources:
  Ec2Instance:
    Type: 'AWS::EC2::Instance'
    Properties:
      SecurityGroups:
        - !Ref InstanceSecurityGroup
        - MyExistingSecurityGroup
      KeyName: !Ref KeyName
      ImageId: ami-7a11e213
  InstanceSecurityGroup:
    Type: 'AWS::EC2::SecurityGroup'
    Properties:
      GroupDescription: Enable SSH access via port 22
      SecurityGroupIngress:
        - IpProtocol: tcp
          FromPort: 22
          ToPort: 22
          CidrIp: 0.0.0.0/0

A função Ref é útil se o parâmetro ou o valor retornado para um recurso é exatamente o que você deseja; no entanto, você pode precisar de outros atributos de um recurso. Por exemplo, se você deseja criar uma distribuição do CloudFront com uma origem do S3, especifique o local do bucket usando um endereço no estilo de DNS. Diversos recursos têm atributos adicionais cujos valores você pode usar em seu modelo. Para obter esses atributos, você deve usar a função Fn::GetAtt. O modelo a seguir cria um recurso de distribuição do CloudFront que especifica o nome DNS de um recurso do bucket S3 usando a função Fn::GetAtt função para obter o atributo DomainName do bucket.

JSON

{
  "Resources": {
    "myBucket": {
      "Type": "AWS::S3::Bucket"
    },
    "myDistribution": {
      "Type": "AWS::CloudFront::Distribution",
      "Properties": {
        "DistributionConfig": {
          "Origins": [
            {
              "DomainName": {
                "Fn::GetAtt": [
                  "myBucket",
                  "DomainName"
                ]
              },
              "Id": "myS3Origin",
              "S3OriginConfig": {}
            }
          ],
          "Enabled": "true",
          "DefaultCacheBehavior": {
            "TargetOriginId": "myS3Origin",
            "ForwardedValues": {
              "QueryString": "false"
            },
            "ViewerProtocolPolicy": "allow-all"
          }
        }
      }
    }
  }
}

YAML

Resources:
  myBucket:
    Type: 'AWS::S3::Bucket'
  myDistribution:
    Type: 'AWS::CloudFront::Distribution'
    Properties:
      DistributionConfig:
        Origins:
          - DomainName: !GetAtt 
              - myBucket
              - DomainName
            Id: myS3Origin
            S3OriginConfig: {}
        Enabled: 'true'
        DefaultCacheBehavior:
          TargetOriginId: myS3Origin
          ForwardedValues:
            QueryString: 'false'
          ViewerProtocolPolicy: allow-all

A função Fn::GetAtt utiliza dois parâmetros, o nome lógico do recurso e o nome do atributo para ser recuperado. Para obter uma lista completa de atributos disponíveis para recursos, consulte Fn::GetAtt. Você verá que a função Fn::GetAtt lista os dois parâmetros em uma matriz. Para as funções que usam vários parâmetros, você deve usar uma matriz para especificá-los.

Receber entrada do usuário usando parâmetros de entrada

Até agora, você aprendeu sobre recursos e um pouco sobre como usá-los juntos em um modelo. Você aprendeu como consultar fazer referência a parâmetros de entrada, mas ainda não analisamos como definir os próprios parâmetros de entrada. Vamos dar uma olhada em declarações de parâmetros e como você pode restringir e validar a entrada do usuário.

Você deve declarar parâmetros em um objeto Parâmetros do modelo. 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, número ou um tipo específico da AWS. Você também pode adicionar um atributo Descrição que informa a um usuário sobre que tipo de valor ele deve especificar. 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 de criação de pilha.

O modelo de estilhaço a seguir é um objeto Parâmetros que declara os parâmetros usados na página Especificar parâmetros acima.

JSON

  "Parameters": {
    "KeyName": {
      "Description" : "Name of an existing EC2 KeyPair to enable SSH access into the WordPress web server",
      "Type": "AWS::EC2::KeyPair::KeyName"
    },
    "WordPressUser": {
      "Default": "admin",
      "NoEcho": "true",
      "Description" : "The WordPress database admin account user name",
      "Type": "String",
      "MinLength": "1",
      "MaxLength": "16",
      "AllowedPattern" : "[a-zA-Z][a-zA-Z0-9]*"
    },
    "WebServerPort": {
      "Default": "8888",
      "Description" : "TCP/IP port for the WordPress web server",
      "Type": "Number",
      "MinValue": "1",
      "MaxValue": "65535"
    }
  }

YAML

Parameters:
  KeyName:
    Description: Name of an existing EC2 KeyPair to enable SSH access into the WordPress web server
    Type: AWS::EC2::KeyPair::KeyName
  WordPressUser:
    Default: admin
    NoEcho: true
    Description: The WordPress database admin account user name
    Type: String
    MinLength: 1
    MaxLength: 16
    AllowedPattern: "[a-zA-Z][a-zA-Z0-9]*"
  WebServerPort:
    Default: 8888
    Description: TCP/IP port for the WordPress web server
    Type: Number
    MinValue: 1
    MaxValue: 65535

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 devem 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.

Você verá que o parâmetro KeyName não tem nenhum atributo Default e os outros parâmetros têm. Por exemplo, o parâmetro WordPressUser tem o atributo Default: admin, mas o parâmetro KeyName não tem nenhum. Os usuários devem especificar o valor do nome de uma chave na criação da pilha. Se não eles não o fizerem, o CloudFormation falhará ao criar a pilha e lançará uma exceção: Parameters: [KeyName] must have values.

Para os tipos de parâmetros específicos da AWS, o CloudFormation valida os valores de entrada em relação aos valores já existentes na conta da AWS do usuário e na região em que ele está criando a pilha antes de criar quaisquer recursos de pilha. No modelo de amostra, o parâmetro KeyName é um tipo de parâmetro específico da AWS de AWS::EC2::KeyPair::KeyName. O CloudFormation verifica se os usuários especificaram um nome válido para o par de chaves EC2 antes de criar a pilha. Outro exemplo de um tipo de parâmetro específico da AWS é AWS::EC2::VPC::Id, que requer que os usuários especifiquem um ID de VPC válido. Além da validação inicial, o console da AWS mostra uma lista suspensa de valores válidos para tipos de parâmetros específicos da AWS, como, por exemplo, nomes válidos de pares de chave do EC2 ou IDs de VPC, quando os usuários usam o assistente de criação de pilha.

Para o tipo String, você pode usar os seguintes atributos para declarar restrições: MinLength, MaxLength, Default, AllowedValues e AllowedPattern. No exemplo acima, o parâmetro WordPressUser tem três restrições: o valor de parâmetro deve ter de 1 a 16 caracteres (MinLength, MaxLength) e deve começar com uma letra seguida por qualquer combinação de letras e números (AllowedPattern).

Para o tipo Number, você pode declarar as seguintes restrições: MinValue, MaxValue, Default e AllowedValues. O número pode ser um número inteiro ou um valor flutuante. No exemplo acima, o parâmetro WebServerPort deve ser um número entre 1 e 65535 inclusive (MinValue, MaxValue).

Anteriormente nesta seção, mencionamos que os parâmetros são uma boa maneira de especificar dados confidenciais ou específicos para implementação, como senhas ou nomes de usuário, que você precisa usar, mas não deseja incorporar no modelo. 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. No exemplo acima, o valor do parâmetro WordPressUser não está visível para qualquer pessoa que visualize as configurações da pilha e seu valor é retornado como asteriscos.

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ção Metadata. Para ter mais informações, consulte Metadados.

• A seção de modelo de Outputs. Para ter mais informações, consulte Outputs.

• O atributo Metadata de uma definição de recurso. Para ter 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.

Especificar valores condicionais usando mapeamentos

Os parâmetros são uma ótima maneira de permitir que os usuários especifiquem valores confidenciais ou exclusivos para uso em propriedades de recursos de pilha. No entanto, pode haver configurações dependentes de região ou um pouco complexas para os usuários descobrirem devido a outras condições ou dependências. Nesses casos, é possível 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. Em um exemplo anterior, nós codificamos o ID da AMI para a propriedade ImageId de nossa instância do EC2. Isso funciona bem na região leste dos EUA, onde representa a AMI que desejamos. No entanto, se o usuário tentar construir a pilha em uma região diferente, obterá o AMI errado ou nenhum AMI. (IDs de AMI são exclusivos para uma região, de modo que o mesmo ID de AMI em uma região diferente pode não representar qualquer AMI ou, então, uma AMI completamente diferente.)

Para evitar esse problema, você precisa de uma maneira de especificar o ID da AMI com base em uma entrada condicional (neste exemplo, a região em que a pilha é criada). Há dois recursos de modelo que podem ajudar: o objetos Mapeamentos e o pseudoparâmetro AWS::Region.

O pseudoparâmetro AWS::Region é um valor que o CloudFormation resolve como a região em que a pilha é criada. Os pseudoparâmetros são resolvidos pelo CloudFormation quando você cria a pilha. Os mapeamentos permitem que você use um valor de entrada como uma condição que determina outro valor. Semelhante a uma declaração de troca, um mapeamento associa um conjunto de valores a outro. Usando o parâmetro AWS::Region juntamente com um mapeamento, você pode garantir que um ID da AMI apropriada para a região seja especificada. O modelo a seguir contém um objeto Mapeamentos com um mapeamento denominado RegionMap que é usado para mapear um ID da AMI para a região apropriada.

JSON

{
  "Parameters": {
    "KeyName": {
      "Description": "Name of an existing EC2 KeyPair to enable SSH access to the instance",
      "Type": "String"
    }
  },
  "Mappings": {
    "RegionMap": {
      "us-east-1": {
        "AMI": "ami-76f0061f"
      },
      "us-west-1": {
        "AMI": "ami-655a0a20"
      },
      "eu-west-1": {
        "AMI": "ami-7fd4e10b"
      },
      "ap-southeast-1": {
        "AMI": "ami-72621c20"
      },
      "ap-northeast-1": {
        "AMI": "ami-8e08a38f"
      }
    }
  },
  "Resources": {
    "Ec2Instance": {
      "Type": "AWS::EC2::Instance",
      "Properties": {
        "KeyName": {
          "Ref": "KeyName"
        },
        "ImageId": {
          "Fn::FindInMap": [
            "RegionMap",
            {
              "Ref": "AWS::Region"
            },
            "AMI"
          ]
        },
        "UserData": {
          "Fn::Base64": "80"
        }
      }
    }
  }
}

YAML

Parameters:
  KeyName:
    Description: Name of an existing EC2 KeyPair to enable SSH access to the instance
    Type: String
Mappings:
  RegionMap:
    us-east-1:
      AMI: ami-76f0061f
    us-west-1:
      AMI: ami-655a0a20
    eu-west-1:
      AMI: ami-7fd4e10b
    ap-southeast-1:
      AMI: ami-72621c20
    ap-northeast-1:
      AMI: ami-8e08a38f
Resources:
  Ec2Instance:
    Type: 'AWS::EC2::Instance'
    Properties:
      KeyName: !Ref KeyName
      ImageId: !FindInMap 
        - RegionMap
        - !Ref 'AWS::Region'
        - AMI
      UserData: !Base64 '80'

No RegionMap, cada região é mapeado para um par de nome/valor. O par de nome/valor é um rótulo e o valor para mapear. No RegionMap, a AMI é o rótulo e o ID da AMI é o valor. Para usar um mapa para retornar um valor, use a função Fn::FindInMap, transmitindo o nome do mapa, o valor usado para localizar o valor mapeado e o rótulo do valor mapeado que você deseja retornar. No exemplo acima, a propriedade ImageId do recurso Ec2Instance usa a função Fn::FindInMap para determinar seu valor especificando RegionMap como o mapa a ser usado, AWS::Region como o valor de entrada para mapear e AMI como o rótulo para identificar o valor para mapear. Por exemplo, se esse modelo foi usado para criar uma pilha na região Oeste dos EUA (N. da Califórnia), ImageId seria definido como ami-655a0a20.

dica

O pseudoparâmetro AWS::Region permite que você obtenha a região em que a pilha é criada. Alguns recursos, como a AWS::EC2::Instance, AWS::AutoScaling::AutoScalingGroupe AWS::ElasticLoadBalancing::LoadBalancer, têm uma propriedade que especifica as zonas de disponibilidade. Você pode usar a função Fn::GetAZs para obter a lista de todas as zonas de disponibilidade em uma região.

Valores construídos e valores de saída

Parâmetros e mapeamentos são uma excelente maneira de transmitir ou determinar valores específicos no momento de criação da pilha, mas pode haver situações em que o valor de um parâmetro ou outro atributo de recurso é apenas uma parte do valor de que você precisa. Por exemplo, no seguinte estilhaço do modelo WordPress, a função Fn::Join cria a subpropriedade Target da propriedade HealthCheck do recurso ElasticLoadBalancer, concatenando o parâmetro WebServerPort com outras strings literais para formar o valor necessário.

JSON

{
  "Resources": {
    "ElasticLoadBalancer": {
      "Type": "AWS::ElasticLoadBalancing::LoadBalancer",
      "Properties": {
        "AvailabilityZones": {
          "Fn::GetAZs": ""
        },
        "Instances": [
          {
            "Ref": "Ec2Instance1"
          },
          {
            "Ref": "Ec2Instance2"
          }
        ],
        "Listeners": [
          {
            "LoadBalancerPort": "80",
            "InstancePort": {
              "Ref": "WebServerPort"
            },
            "Protocol": "HTTP"
          }
        ],
        "HealthCheck": {
          "Target": {
            "Fn::Join": [
              "",
              [
                "HTTP:",
                {
                  "Ref": "WebServerPort"
                },
                "/"
              ]
            ]
          },
          "HealthyThreshold": "3",
          "UnhealthyThreshold": "5",
          "Interval": "30",
          "Timeout": "5"
        }
      }
    }
  }
}

YAML

Resources:
  ElasticLoadBalancer:
    Type: 'AWS::ElasticLoadBalancing::LoadBalancer'
    Properties:
      AvailabilityZones: !GetAZs ''
      Instances:
        - !Ref Ec2Instance1
        - !Ref Ec2Instance2
      Listeners:
        - LoadBalancerPort: '80'
          InstancePort: !Ref WebServerPort
          Protocol: HTTP
      HealthCheck:
        Target: !Join 
          - ''
          - - 'HTTP:'
            - !Ref WebServerPort
            - /
        HealthyThreshold: '3'
        UnhealthyThreshold: '5'
        Interval: '30'
        Timeout: '5'

A função Fn:Join usa dois parâmetros; um delimitador que separa os valores que você deseja concatenar e uma matriz de valores na ordem desejada para exibição. No exemplo acima, a função Fn::Join especifica uma string vazia como o delimitador e HTTP:, o valor do parâmetro WebServerPort e um caractere / como os valores para concatenar. Se WebServerPort tinha um valor de 8888, a propriedade Destino seria definido com o seguinte valor:

HTTP:8888/

A função Fn::Join também é útil para declarar valores de saída para a pilha. O objeto Saídas no modelo contém declarações para os valores que você deseja ter disponíveis depois que a pilha for criada. Uma saída é uma forma conveniente de coletar informações importantes sobre os recursos ou parâmetros de entrada. Por exemplo, no modelo WordPress, declaramos o objeto Saídas a seguir.

JSON

{
    "Outputs": {
        "InstallURL": {
            "Value": {
                "Fn::Join": [
                    "",
                    [
                        "http://",
                        {
                            "Fn::GetAtt": [
                                "ElasticLoadBalancer",
                                "DNSName"
                            ]
                        },
                        "/wp-admin/install.php"
                    ]
                ]
            },
            "Description": "Installation URL of the WordPress website"
        },
        "WebsiteURL": {
            "Value": {
                "Fn::Join": [
                    "",
                    [
                        "http://",
                        {
                            "Fn::GetAtt": [
                                "ElasticLoadBalancer",
                                "DNSName"
                            ]
                        }
                    ]
                ]
            }
        }
    }
}

YAML

Outputs:
  InstallURL:
    Value: !Join 
      - ''
      - - 'http://'
        - !GetAtt 
          - ElasticLoadBalancer
          - DNSName
        - /wp-admin/install.php
    Description: Installation URL of the WordPress website
  WebsiteURL:
    Value: !Join 
      - ''
      - - 'http://'
        - !GetAtt 
          - ElasticLoadBalancer
          - DNSName

Cada valor de saída tem um nome, um atributo Valor que contém declaração do valor retornado como o valor de saída e, opcionalmente, uma descrição do valor. No exemplo anterior, InstallURL é a string retornada por uma chamada da função Fn::Join que concatena http://, o nome DNS do recurso ElasticLoadBalancer e /wp-admin/install.php. O valor de saída seria semelhante ao seguinte:

http://mywptests-elasticl-1gb51l6sl8y5v-206169572.us-east-2.elb.amazonaws.com/wp-admin/install.php

No tutorial de Conceitos básicos, usamos esse link para acessar a página de instalação de forma conveniente para o blog WordPress que criamos. O CloudFormation gera os valores de saída após o término de criação da pilha. Você pode visualizar os valores de saída na guia Outputs do console do CloudFormation ou usando o comando aws cloudformation describe-stacks.

Próximas etapas

Nós apenas que descrevemos as partes básicas de um modelo e como usá-las. Você aprendeu o seguinte sobre os modelos:

• Declaração de recursos e suas propriedades.

• Referência a outros recursos com a função Ref e os atributos do recurso usando a função Fn::GetAtt.

• Uso de parâmetros para permitir que os usuários especifiquem valores no momento de criação da pilha e uso de restrições para validar a entrada de parâmetros.

• Uso de mapeamentos para determinar valores condicionais.

• Uso da função Fn::Join para construir valores com base em parâmetros, atributos de recursos e outras strings.

• Uso de valores de saída para capturar informações sobre os recursos da pilha.

Não vamos abordar dois objetos de nível superior em um modelo: AWSTemplateFormatVersion e Descrição. AWSTemplateFormatVersion é simplesmente a versão do formato de modelo. Se você não a especificar, o CloudFormation usará a versão mais recente.

Descrição é qualquer string JSON ou YAML válida. Essa descrição é exibida na página Especificar parâmetros do assistente de criação de pilha. Para obter mais informações, consulte Versão do formato e Descrição.

É claro que há mais recursos avançados de modelo e pilha. Veja aqui uma lista com alguns recursos importantes sobre os quais você precisará saber mais:

Atributos opcionais que podem ser usados com qualquer recurso:

• Atributo DependsOn permite especificar que um recurso deve ser criado após outro.

• O Atributo DeletionPolicy permite especificar como o CloudFormation deve lidar com a exclusão de um recurso.

• O atributo Metadata permite que você especifique dados estruturados com um recurso.

AWS::CloudFormation::Stack permite aninhar outra pilha como um recurso em seu modelo.