Usando extensões privadas no CloudFormation - AWS CloudFormation

Usando extensões privadas no CloudFormation

Extensões privadas são as extensões de terceiros que você ativou explicitamente para uso em sua conta. da AWS.

Existem dois tipos de extensões privadas:

  • Extensões privadas ativadas

    Essas são as cópias locais de extensões de terceiros que você ativou para sua conta e região. Quando você ativa uma extensão pública de terceiros, o CloudFormation cria uma cópia local dessa extensão no registro da sua conta.

  • Extensões privadas registradas

    Você também pode ativar extensões privadas que não estão listadas no registro público do CloudFormation. Essas podem ser extensões que você mesmo criou ou compartilhadas com você por sua organização ou por terceiros. Para usar essa extensão privada em sua conta, primeiro você deve registrá-la.

    Para obter informações sobre o desenvolvimento de extensões privadas próprias, consulte Creating resource types (Criar tipos de recursos) no Manual do usuário da interface da linha de comando do CloudFormation.

Registrar extensões privadas

Para usar extensões privadas que não estão listadas no registro do CloudFormation, seja aquelas que você mesmo desenvolve ou compartilhadas com você, você deve primeiro registrá-las no CloudFormation, nas contas e regiões em que deseja usá-las. O registro da extensão faz upload de uma cópia dela no registro do CloudFormation na conta e a ativa. Ao registrar uma extensão privada, ela aparecerá no registro do CloudFormation para a respectiva conta e região, e você poderá usá-la em seus modelos de pilha.

É possível registrar uma extensão usando o comando register-type da CLI da AWS ou o comando submit da CLI do CloudFormation. Para registrar uma extensão usando a CLI do CloudFormation, consulte Registering extensions (Registrar extensões) no Manual do usuário da CLI do CloudFormation.

Permissões do IAM para registrar uma extensão privada

Como parte do registro de uma extensão privada, você especifica um bucket do S3 que contém o pacote do projeto de extensão. Este pacote contém todos os arquivos de origem necessários para a extensão que você deseja registrar. O usuário que registra a extensão deve poder acessar o pacote do projeto nesse bucket do S3. Ou seja, o usuário precisa ter permissões GetObject para o pacote de extensões.

Isso é verdadeiro se você estiver usando o comando register-type da CLI da AWS ou o comando submit da CLI do CloudFormation.

Para obter mais informações, consulte Actions, Resources, and Condition Keys for Amazon S3 (Ações, recursos e chaves de condição para o Amazon S3) no Manual do usuário do AWS Identity and Access Management.

Para registrar um tipo de recurso usando a CLI da AWS

  1. Localize o bucket do S3 que contém o pacote do projeto para a extensão privada que você deseja registrar em sua conta.

  2. Use o comando register-type para registrar a extensão em sua conta:

    RegisterType é uma ação assíncrona e retorna um token de registro que você pode usar para rastrear o progresso da solicitação de registro.

    nota

    Se a extensão chamar as APIs da AWS como parte da funcionalidade dela em qualquer um dos manipuladores, será necessário criar uma função de execução do IAM que inclua as permissões necessárias para chamar essas APIs da AWS e para provisionar essa função de execução em sua conta. Em seguida, você poderá especificar essa função de execução usando o parâmetro --execution-role-arn. Depois, o CloudFormation assumirá essa função de execução para fornecer as credenciais apropriadas para o tipo de recurso.

    Por exemplo, o comando a seguir registra o tipo de recurso My::Resource::Example na conta atual da AWS:

    aws cloudformation register-type --type-name My::Resource::Example --schema-handler-package [s3 object path] --type RESOURCE { "RegistrationToken": "f5525280-104e-4d35-bef5-8f1fexample" }
  3. Opcional: use o token de registro com o comando describe-type-registration para monitorar o andamento da solicitação de registro.

    Quando o CloudFormation concluir a solicitação de registro, ele definirá o status do andamento da solicitação como COMPLETE.

    O exemplo a seguir usa o token de registro retornado pelo comando RegisterType acima para retornar as informações do status do registro.

    aws cloudformation describe-type-registration --registration-token f5525280-104e-4d35-bef5-8f1fexample { "ProgressStatus": "COMPLETE", "TypeArn": "arn:aws:cloudformation:us-east-1:012345678910:type/resource/My-Resource-Example", "Description": "Deployment is currently in DEPLOY_STAGE of status COMPLETED; ", "TypeVersionArn": "arn:aws:cloudformation:us-east-1:012345678910:type/resource/My-Resource-Example/00000001" }

Configurar extensões no nível da conta

Uma extensão pode incluir propriedades de configuração que são aplicadas a todas as instâncias da extensão em uma determinada conta e região. Por exemplo, se a extensão precisar acessar um serviço da Web de terceiros, o autor da extensão pode ter incluído propriedades na definição de configuração de extensão, onde você pode especificar suas credenciais para esse serviço. Quando você define propriedades de configuração, o CloudFormation salva essas informações no nível da conta e da região. A partir daí, o CloudFormation pode acessar essas propriedades de configuração durante as operações que envolvem qualquer instância dessa extensão em sua conta e região. Dessa forma, as propriedades de configuração estão disponíveis para o CloudFormation durante todas as operações de extensão, e não apenas aquelas que envolvem explicitamente um modelo de pilha. Por exemplo, o CloudFormation pode acessar as propriedades de configuração durante read e eventos do list, operações que não envolvem explicitamente o modelo de pilha.

Se as propriedades de configuração de uma extensão incluírem quaisquer propriedades necessárias, você deverá especificar essas propriedades antes de usar a extensão em sua conta e região.

Para obter mais informações sobre como definir os dados de configuração para o desenvolvimento de uma extensão, consulte Defining the account-level configuration of an extension (Definir a configuração no nível da conta de uma extensão) no Manual do usuário da CLI do CloudFormation.

Para especificar as propriedades de configuração para uma extensão no console do CloudFormation

  1. Use o registro do CloudFormation para encontrar a extensão.

  2. Em Actions (Ações), selecioneEdit (Editar) e, em seguida, selecione Edit configuration (Editar configuração).

    CloudFormation exibe a página Configure extension (Configurar extensão). Para exibir o esquema de configuração atual da extensão, verifique se a opção View configuration schema (Visualizar esquema de configuração) está ativada.

  3. Na caixa de texto Configuration JSON (Configurar o JSON), insira uma string JSON que represente o esquema de configuração que você deseja especificar para essa extensão.

  4. Selecione Configure extension (Configurar extensão).

Para especificar propriedades de configuração para uma extensão usando a CLI da AWS

  • Use o comando set-type-configuration para especificar as configurações a serem usadas com a extensão nesta conta e região. O JSON que você passa para especificar as propriedades de configuração deve ser validado em relação ao esquema definido no elemento typeConfiguration do esquema da extensão.

Para exibir os dados de configuração atuais de uma extensão no console do CloudFormation

  1. Use o registro do CloudFormation para encontrar a extensão.

  2. Selecione o nome da extensão para exibir os detalhes dela.

  3. Na página de detalhes da simulação, selecione a guia Configuration (Configuração).

Para exibir os dados de configuração atuais de uma extensão na CLI da AWS

  • Use o comando describe-type para retornar informações detalhadas sobre a extensão. O elemento ConfigurationSchema contém as propriedades de configuração atuais da extensão em uma determinada conta e região.

Especificar qual versão de uma extensão privada deve ser usada

Ao longo do tempo, você pode registrar várias versões da mesma extensão. Você pode especificar qual versão da extensão deseja usar para as operações do CloudFormation.

Para especificar qual versão de uma extensão usar por meio da AWS CLI da AWS

  • Use o comando set-type-default-version para especificar qual versão da extensão será usada nas operações do CloudFormation em sua conta.

    Por exemplo, o comando a seguir define a versão padrão do tipo de recurso My::Resource::Example como 00000003 para a conta atual.

    aws cloudformation set-type-default-version --type RESOURCE --type-name My::Resource::Example --version-id 00000003