Como usar módulos para encapsular e reutilizar configurações de recursos

Os módulos 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 no qual ele tenha sido registrado no registro do CloudFormation. Dessa maneira, você sabe 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 região.

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 informações sobre como desenvolver tipos de módulo, consulte Como desenvolver tipos de módulo no Guia do usuário da interface de linhas de comando do CloudFormation.

Como usar módulos em um modelo

Para usar um módulo, verifique se ele está registrado na conta e região nas quais deseja usá-lo. Para ter mais informações, consulte Extensões públicas e privadas. Você registra módulos no registro do CloudFormation como extensões privadas. Portanto, trate-o como faria com um recurso individual:

• Inclua-o na seção Recursos do seu modelo.

• Especifique qualquer propriedade necessária para o módulo.

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. Use conjuntos de alterações para visualizar os recursos a serem adicionados ou atualizados antes de realmente executar a operação de pilha. Para ter mais informações, consulte Atualizar pilhas usando conjuntos de alterações.

Considere o exemplo a seguir: você tem um modelo que contém recursos e módulos. O modelo contém um recurso individual, ResourceA, bem como 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.

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

Como usar parâmetros para especificar valores de módulo

Os módulos podem incluir parâmetros de módulo. Assim como os parâmetros de modelo, os parâmetros de módulo permitem que você insira valores personalizados para o módulo com base no modelo (ou módulo) que o contém. Assim, o módulo pode usar esses valores para definir as propriedades dos recursos contidos nele.

Você também pode definir parâmetros de modelo que, por sua vez, definem as propriedades de módulo, para que os usuários possam inserir valores que são passados para o módulo no momento da operação de pilha. Para obter mais informações sobre a definição de parâmetros do modelo, consulte Parâmetros.

Da mesma forma, se um módulo contiver um módulo aninhado que inclua parâmetros de módulo, você pode:

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

Aqui, o 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 ter mais informações, consulte Propriedades. 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 e faça referência a esse parâmetro de modelo no parâmetro do seu módulo.

Como fazer referência a recursos em um módulo

É possível fazer referência aos recursos em um módulo por nome lógico. É possível construir o nome lógico totalmente qualificado de um recurso contido em um módulo combinando:

• O nome lógico especificado para o módulo no modelo que o contém (ou no módulo que o contém).

• O nome lógico do recurso, especificado no módulo.

O nome lógico totalmente qualificado para o recurso pode ser especificado com ou sem o uso de um período como delimitador. Por exemplo, ambos os nomes lógicos abaixo são válidos e funcionalmente equivalentes:

• ModuleLogicalName.ResourceLogicalName

• ModuleLogicalNameResourceLogicalName

Dessa forma, você pode usar funções intrínsecas GetAtt e Ref para acessar valores de propriedade em recursos do módulo.

No exemplo a seguir, o modelo faz referência a uma propriedade em um módulo para definir uma propriedade correspondente em um recurso no próprio modelo.

Suponha que o módulo My::S3::SampleBucket::MODULE contenha um recurso AWS::S3::Bucket com o nome lógico de S3Bucket. Para fazer referência ao nome do bucket desse recurso usando a função intrínseca Ref, combine o nome lógico dado ao módulo no modelo, MyBucket, com o nome lógico do recurso no módulo, S3Bucket, para obter o nome lógico totalmente qualificado do recurso: MyBucket.S3Bucket ou MyBucketS3Bucket.

Os nomes lógicos dos recursos contidos em um módulo são especificados no esquema do módulo. Você pode acessar esse esquema das seguintes maneiras:

• Encontrando o módulo no registro do CloudFormation. A guia Schema (Esquema) exibe o esquema do módulo.

• Usando a operação DescribeType para retornar os detalhes do módulo, que incluem o esquema.

// 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": {
          "Fn::GetAtt": [
             "MyBucket",
             "S3Bucket.Arn"
          ]
      }
    }
  }
}

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

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 ter mais informações, consulte Cotas do AWS CloudFormation.

• 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 sobre saídas, consulte Outputs.

• 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 ter mais informações, consulte Como usar parâmetros para especificar valores de módulo.

Cadastro e versionamento de módulo

Você registra e gerencia os módulos em sua conta e região usando o registro do CloudFormation. Para ter mais informações, consulte Como usar o registro do AWS CloudFormation.

Você pode registrar várias versões do mesmo módulo em uma determinada conta e região. Lembre-se dos seguintes fatores:

• Um módulo deve ser registrado na conta e na região nas quais você deseja usá-lo.

• Durante operações de pilha, o CloudFormation usa a versão do módulo que estiver registrada atualmente como padrão na conta e região nas quais a operação de pilha está sendo executada. Isso inclui módulos que estejam aninhados a outros módulos.

  Portanto, não esqueça que se tiver 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.

  Para ter mais informações, consulte Especificar uma versão de uma extensão privada para usar com a AWS CLI.

• Durante operações de pilha, o CloudFormation usa a versão do recurso que estiver registrada como a versão padrão na conta e região 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 sobre conjuntos de pilhas, consulte Trabalhar com o AWS CloudFormation StackSets.

Para obter mais informações sobre como registrar novas versões de um módulo, ou alterar a versão padrão de um módulo, consulte Como usar o registro do AWS CloudFormation.

Ativar módulos públicos para uso na sua conta

Para ativar com êxito um módulo público na 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:

• A extensão já deve estar ativada na sua conta e região.

  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 ter mais informações, consulte Especificar aliases para fazer referência a extensões.

• A versão da extensão atualmente ativada deve ser uma das principais versões com suporte dessa extensão especificada no módulo. Para saber mais, consulte Requisitos de módulos para publicar um módulo público, no Guia do usuário da CLI do CloudFormation.

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/ou versões que precisam ser ativadas antes que o módulo possa ser ativado com êxito.