# Criar configurações de recursos reutilizáveis que podem ser incluídas em modelos com os módulos do CloudFormation
Os *módulo*s são uma maneira de empacotar configurações de recursos para inclusão entre modelos de pilha, de modo transparente, gerenciável e repetível. Os módulos podem encapsular configurações comuns de serviço e práticas recomendadas como blocos de construção modulares e personalizáveis para você incluir em seus modelos de pilha. Os módulos permitem que você inclua configurações de recursos que incorporem práticas recomendadas, conhecimento especializado em áreas específicas e diretrizes aceitas (para áreas como segurança, conformidade, governança e regulamentações setoriais) aos seus modelos, sem precisar adquirir conhecimento profundo sobre as complexidades da implementação de recursos.
Por exemplo, um especialista na área de rede pode criar um módulo que contenha grupos de segurança integrados e regras de entrada/saída que sigam as diretrizes de segurança. Em seguida, você pode incluir esse módulo em seu modelo para provisionar infraestrutura de rede segura em sua pilha, sem precisar gastar tempo entendendo o funcionamento de VPCs, sub-redes, grupos de segurança e gateways. Além disso, como os módulos têm versionamento, se houver mudança nas diretrizes de segurança ao longo do tempo, o autor do módulo pode criar uma nova versão do módulo que incorpore essas alterações.
As características do uso de módulos em seus modelos incluem:
+ **Previsibilidade**: um módulo precisa aderir ao esquema em que foi registrado no registro do CloudFormation para que você possa saber para quais recursos ele pode resolver após incluí-lo em seu modelo.
+ **Reutilização**: você pode usar o mesmo módulo em vários modelos e contas.
+ **Rastreabilidade**: o CloudFormation retém o conhecimento sobre quais recursos em uma pilha foram provisionados com base em um módulo, permitindo que você entenda facilmente a origem das alterações de recursos.
+ **Capacidade de gerenciamento**: após registrar um módulo, você pode gerenciá-lo por meio do registro do CloudFormation, incluindo versionamento e disponibilidade de conta e regional.
Um módulo pode conter:
+ Um ou mais recursos a serem provisionados com base no módulo, juntamente com quaisquer dados associados, como saídas ou condições.
+ Qualquer parâmetro de módulo, permitindo que você especifique valores personalizados sempre que o módulo for usado.
Para obter informações sobre como desenvolver módulos, consulte [Desenvolver módulos](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/modules.html) no *Guia do usuário da CLI do CloudFormation*.
**Topics**
+ [Considerações sobre o uso de módulos](#module-considerations)
+ [Entender o versionamento de módulos](module-versioning.md)
+ [Usar módulos do registro privado do CloudFormation](modules-using.md)
+ [Usar parâmetros para especificar valores de módulo](module-using-params.md)
+ [Recursos do módulo de referência nos modelos do CloudFormation](module-ref-resources.md)
## Considerações sobre o uso de módulos
+ Não há cobrança adicional pelo uso de módulos. Você paga apenas pelos recursos para os quais os módulos resolvem em suas pilhas.
+ As cotas do CloudFormation, como o número máximo de recursos permitidos em uma pilha ou o tamanho máximo do corpo do modelo, aplicam-se ao modelo processado independentemente de os recursos incluídos nesse modelo serem ou não provenientes de módulos. Para obter mais informações, consulte [Entender as cotas do CloudFormation](cloudformation-limits.md).
+ As tags especificadas para a pilha são atribuídas aos recursos individuais derivados do módulo.
+ Scripts auxiliares especificados no módulo não se propagam para os recursos individuais contidos no módulo quando o CloudFormation processa o modelo.
+ As saídas especificadas no módulo são propagadas para saídas no modelo.
Cada saída receberá um ID lógico que é uma concatenação do nome lógico do módulo e o nome de saída, conforme definido no módulo. Para obter mais informações, consulte [Obter resultados exportados de uma pilha do CloudFormation implantada](using-cfn-stack-exports.md).
+ Os parâmetros especificados no módulo não são propagados para parâmetros no nível do modelo.
No entanto, você pode criar parâmetros no âmbito de modelos que fazem referência a parâmetros de módulo. Para obter mais informações, consulte [Usar parâmetros para especificar valores de módulo](module-using-params.md).
# Entender o versionamento de módulos
O registro do CloudFormation atua como um repositório onde você pode registrar e gerenciar módulos para uso em sua região e Conta da AWS. Você pode registrar módulos de várias fontes, incluindo AWS, publicadores externos e suas próprias extensões personalizadas, dentro da sua conta e da sua região. Para obter mais informações, consulte [Gerenciar extensões com o registro do CloudFormation](registry.md).
Os módulos podem ter versões diferentes para que você possa especificar qual versão do módulo deseja usar. Esse recurso de versionamento é particularmente útil quando você precisa atualizar ou modificar um módulo sem quebrar as pilhas existentes que dependem dele.
Tenha em mente as seguintes considerações ao usar várias versões de um módulo:
+ Durante operações de pilha, o CloudFormation usa a versão do módulo que está registrada atualmente como padrão na região e na Conta da AWS em que a operação de pilha está sendo executada. Isso inclui módulos que estejam aninhados a outros módulos.
Portanto, lembre-se: se houver versões diferentes do mesmo módulo registradas como a versão padrão em diferentes contas ou regiões, o uso do mesmo modelo pode gerar resultados diferentes.
+ Durante operações de pilha, o CloudFormation usa a versão do recurso que está registrada como a versão padrão na região e na Conta da AWS nas quais a operação de pilha está sendo executada. Isso inclui os recursos gerados pela inclusão de módulos.
+ A alteração da versão padrão de um módulo não inicia nenhuma operação de atualização de pilha. No entanto, na próxima vez que você executar uma operação de pilha com qualquer modelo contendo o respectivo módulo, como uma atualização de pilha, o CloudFormation usará a nova versão padrão na operação.
A única exceção a isso é a execução de uma atualização de pilha com a opção **usar modelo anterior** especificada, conforme descrito abaixo.
+ Para operações de atualização de pilha, se você especificar a opção **usar modelo anterior**, o CloudFormation usará o modelo processado anteriormente para a atualização de pilha e não reprocessará o módulo para nenhuma alteração que você possa ter feito nele.
+ Para garantir resultados uniformes, se estiver incluindo módulos em um modelo de pilha para uso com conjuntos de pilha, certifique-se de que a mesma versão do módulo esteja definida como a versão padrão em todas as contas e regiões nas quais você está planejando implantar suas instâncias de pilha. Isso inclui módulos que estejam aninhados a outros módulos. Para obter mais informações, consulte [Gerenciar pilhas em todas as contas e regiões com StackSets](what-is-cfnstacksets.md).
## Requisitos para ativar módulos públicos de terceiros
Para ativar com êxito um módulo público de terceiros em sua conta e região, o seguinte deve ser verdadeiro para cada extensão pública de terceiros (recurso ou módulo) incluída nesse módulo:
+ **Ativação da extensão**: a extensão deve estar ativada na conta e na região em que você deseja usá-la. Para obter mais informações, consulte [Usar extensões públicas de terceiros do registro do CloudFormation](registry-public.md).
+ **Registro do alias**: se a extensão no módulo utilizar um alias de nome de tipo, ela deverá ser registrada na sua conta e região utilizando o mesmo alias de nome de tipo. Para obter mais informações, consulte [Usar aliases para fazer referência a extensões](registry-public.md#registry-public-enable-alias).
+ **Compatibilidade de versões**: a versão da extensão ativada no momento deve ser uma das principais versões com suporte dessa extensão especificada no módulo.
Se você não tiver as extensões públicas de terceiros corretas e versões de extensão ativadas, o CloudFormation falhará na operação com um erro listando as extensões e versões que precisam ser ativadas antes que o módulo possa ser ativado com êxito.
# Usar módulos do registro privado do CloudFormation
Este tópico explica como usar módulos em modelos do CloudFormation. Pense nos módulos como pacotes predefinidos de recursos que você pode adicionar aos seus modelos.
Para usar um módulo, as etapas são as seguintes:
+ **Registre o módulo**: registre módulos no registro do CloudFormation como extensões privadas. Verifique se ele está registrado na região e na Conta da AWS em que você está trabalhando. Para obter mais informações, consulte [Conceitos do registro do CloudFormation](registry-concepts.md).
+ **Inclua-o em seu modelo**: adicione o módulo à seção [Resources](resources-section-structure.md) do seu modelo do CloudFormation, assim como você faria com outros recursos. Você também precisará fornecer todas as propriedades necessárias para o módulo.
+ **Crie ou atualize a pilha**: quando você inicia uma operação de pilha, o CloudFormation gera um modelo processado que resolve todos os módulos incluídos nos recursos apropriados.
+ **Pré-visualize as alterações**: antes de fazer alterações, você pode usar um conjunto de alterações para ver quais recursos serão adicionados ou alterados. Para obter mais informações, consulte [Atualizar pilhas do CloudFormation usando conjuntos de alterações](using-cfn-updating-stacks-changesets.md).
Considere o exemplo a seguir: você tem um modelo que contém recursos e módulos. O modelo contém um recurso individual, `ResourceA`, e um módulo, `ModuleParent`. Esse módulo contém dois recursos, `ResourceB` e `ResourceC`, bem como um módulo aninhado, `ModuleChild`. `ModuleChild` contém um único recurso, `ResourceD`. Se você criar uma pilha com base nesse modelo, o CloudFormation o processará e resolverá os módulos para os recursos apropriados. A pilha resultante tem quatro recursos: `ResourceA`, `ResourceB`, `ResourceC` e `ResourceD`.
![\[Durante uma operação de pilha, o CloudFormation resolve os dois módulos incluídos no modelo de pilha nos quatro recursos adequados.\]](http://docs.aws.amazon.com/pt_br/AWSCloudFormation/latest/UserGuide/images/modules-resource-inclusion.png)
O CloudFormation acompanha quais recursos em uma pilha foram criados com base em módulos. Você pode visualizar essas informações nas guias **Events** (Eventos), **Resources** (Recursos) e **Drifts** (Desvios) de uma determinada pilha. Elas também estão incluídas nas visualizações do conjunto de alterações.
É possível fazer a distinção entre módulos e recursos em um modelo porque eles aderem à seguinte convenção de nomenclatura com quatro partes, em contraste com a convenção habitual de três partes usada por recursos:
```
organization::service::use-case::MODULE
```
# Usar parâmetros para especificar valores de módulo
No CloudFormation, é possível usar parâmetros de modelos para personalizar suas pilhas ao fornecer valores de entrada durante a criação ou atualização da pilha. Esses parâmetros permitem que você altere certos aspectos da pilha com base em suas necessidades. Para obter mais informações sobre a definição de parâmetros do modelo, consulte [Sintaxe de Parameters de modelo do CloudFormation](parameters-section-structure.md).
Da mesma forma, os módulos também podem ter parâmetros. Esses parâmetros de módulo permitem que você insira valores personalizados no módulo com base no modelo (ou outro módulo) que o está usando. Assim, o módulo pode usar esses valores personalizados para definir as propriedades dos recursos nele contidos.
Você também pode definir parâmetros de modelo que definem propriedades de módulo para poder inserir valores que são passados para o módulo no momento da operação de pilha.
Se um módulo contiver um módulo aninhado que possua seus próprios parâmetros do módulo, você poderá:
+ Especificar os valores para os parâmetros do módulo aninhado diretamente no módulo pai.
+ Definir os parâmetros correspondentes do módulo no módulo pai que permitem que os parâmetros do módulo aninhado sejam definidos pelo modelo (ou módulo) no qual o módulo pai está contido.
## Como usar parâmetros de modelo para especificar valores de parâmetro de módulo
O exemplo a seguir mostra como definir parâmetros de modelo que repassam valores para um módulo.
Este modelo que contém `My::S3::SampleBucket::MODULE` define um parâmetro de modelo, `BucketName`, que permite que o usuário especifique um nome de bucket do S3 durante a operação de pilha.
```
# Template containing My::S3::SampleBucket::MODULE
Parameters:
BucketName:
Description: Name for your sample bucket
Type: String
Resources:
MyBucket:
Type: 'My::S3::SampleBucket::MODULE'
Properties:
BucketName: !Ref BucketName
```
## Como especificar propriedades em recursos em um módulo filho com base no módulo pai
O exemplo a seguir ilustra como especificar valores de parâmetro em um módulo que esteja aninhado dentro de outro módulo.
Este primeiro módulo, `My::S3::SampleBucketPrivate::MODULE`, será o módulo filho. Ele define dois parâmetros: `BucketName` e `AccessControl`. Os valores especificados para esses parâmetros são usados para especificar as propriedades `BucketName` e `AccessControl` do recurso `AWS::S3::Bucket` que o módulo contém. Abaixo apresentamos o fragmento de modelo para `My::S3::SampleBucketPrivate::MODULE`.
```
# My::S3::SampleBucketPrivate::MODULE
AWSTemplateFormatVersion: 2010-09-09
Description: A sample S3 Bucket with Versioning and DeletionPolicy.
Parameters:
BucketName:
Description: Name for the bucket
Type: String
AccessControl:
Description: AccessControl for the bucket
Type: String
Resources:
S3Bucket:
Type: AWS::S3::Bucket
Properties:
BucketName: !Ref BucketName
AccessControl: !Ref AccessControl
DeletionPolicy: Retain
VersioningConfiguration:
Status: Enabled
```
Em seguida, o módulo anterior é aninhado em um módulo pai, `My::S3::SampleBucket::MODULE`. O módulo pai, `My::S3::SampleBucket::MODULE`, define os parâmetros do módulo filho das seguintes maneiras:
+ Ele define o parâmetro `AccessControl` de `My::S3::SampleBucketPrivate::MODULE` para `Private`.
+ Para `BucketName`, ele define um parâmetro de módulo, que permitirá que o nome do bucket seja especificado no modelo (ou módulo) que contém `My::S3::SampleBucket::MODULE`.
```
# My::S3::SampleBucket::MODULE
AWSTemplateFormatVersion: 2010-09-09
Description: A sample S3 Bucket. With Private AccessControl.
Parameters:
BucketName:
Description: Name for your sample bucket
Type: String
Resources:
MyBucket:
Type: 'My::S3::SampleBucketPrivate::MODULE'
Properties:
BucketName: !Ref BucketName
AccessControl: Private
```
## Como especificar restrições para parâmetros de módulo
Os parâmetros de módulo não são compatíveis com a imposição de restrições. Para executar a verificação de restrição em um parâmetro de módulo, crie um parâmetro de modelo com as restrições desejadas. Em seguida, faça referência a esse parâmetro de modelo no seu parâmetro de módulo. Para obter mais informações sobre a definição de parâmetros do modelo, consulte [Sintaxe de Parameters de modelo do CloudFormation](parameters-section-structure.md).
# Recursos do módulo de referência nos modelos do CloudFormation
Nos modelos do CloudFormation, muitas vezes é necessário definir as propriedades em um recurso com base no nome ou na propriedade de outro recurso. Para obter mais informações, consulte [Fazer referência a recursos](resources-section-structure.md#using-cross-resource-references).
Para fazer referência um recurso contido em um módulo em seu modelo do CloudFormation, é necessário combinar dois nomes lógicos:
+ O nome lógico que você atribuiu ao próprio módulo ao incluí-lo em seu modelo.
+ O nome lógico do recurso específico nesse módulo.
É possível combinar esses dois nomes lógicos usando ou não um ponto (.) entre eles. Por exemplo, se o nome lógico do módulo for `MyModule` e o nome lógico do recurso for `MyBucket`, você poderá se referir a esse recurso como `MyModule.MyBucket` ou `MyModuleMyBucket`.
Para encontrar os nomes lógicos dos recursos dentro de um módulo, é possível consultar o esquema do módulo, que está disponível no registro do CloudFormation, ou via operação [https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_DescribeType.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_DescribeType.html). O esquema lista todos os recursos e seus nomes lógicos que fazem parte do módulo.
Depois de ter o nome lógico completo, você pode usar funções do CloudFormation, `GetAtt` como `Ref` e, para acessar valores de propriedade em recursos do módulo.
Por exemplo, você tem um módulo `My::S3::SampleBucket::MODULE` que contém um recurso `AWS::S3::Bucket` com o nome lógico `S3Bucket`. Para se referir ao nome desse bucket usando a função `Ref`, combine o nome do módulo em seu modelo (`MyBucket`) com o nome lógico do recurso no módulo (`S3Bucket`). O nome lógico completo é `MyBucket.S3Bucket` ou `MyBucketS3Bucket`.
**Exemplo de modelo**
O modelo de exemplo a seguir cria um bucket do S3 usando o módulo `My::S3::SampleBucket::MODULE`. Ele também cria uma fila do Amazon SQS e define seu nome para ser igual ao nome do bucket do módulo. Além disso, o modelo produz o nome do recurso da Amazon (ARN) do bucket de S3 criado.
```
# Template that uses My::S3::SampleBucket::MODULE
Parameters:
BucketName:
Description: Name for your sample bucket
Type: String
Resources:
MyBucket:
Type: My::S3::SampleBucket::MODULE
Properties:
BucketName: !Ref BucketName
exampleQueue:
Type: AWS::SQS::Queue
Properties:
QueueName: !Ref MyBucket.S3Bucket
Outputs:
BucketArn:
Value: !GetAtt MyBucket.S3Bucket.Arn
```