# Usar extensões públicas de terceiros do registro do CloudFormation Para utilizar uma extensão pública de terceiros no seu modelo, primeiro é necessário *ativar* a extensão para a conta e a região nas quais você deseja utilizá-la. A ativação de uma extensão a torna utilizável em operações de pilha na conta e região em que ela está ativada. Quando você ativa uma extensão pública de terceiros, o CloudFormation cria uma entrada no registro de extensões da sua conta para a extensão ativada como uma extensão privada. Isso permite definir as propriedades de configuração incluídas na extensão. As propriedades de configuração definem como essa extensão é configurada para uma determinada região e Conta da AWS. Além de definir as propriedades de configuração, também é possível personalizar a extensão das seguintes formas: + Especifique a função de execução utilizada pelo CloudFormation para ativar a extensão, além de configurar o registro em log para essa extensão. + Especifique se a extensão será atualizada automaticamente quando uma nova versão secundária ou uma versão de patch estiver disponível. + Especifique um alias a ser utilizado em vez do nome da extensão pública de terceiros. Isso pode ajudar a evitar colisões de nomes entre extensões de terceiros. **Topics** + [Configure um perfil de execução com permissões do IAM e uma política de confiança para acesso público à extensão](#registry-public-enable-execution-role) + [Usar novas versões de extensões automaticamente](#registry-public-enable-auto) + [Usar aliases para fazer referência a extensões](#registry-public-enable-alias) + [Comandos da AWS CLI comumente usados para trabalhar com extensões públicas](#registry-commonly-used-commands-public-extensions) + [Ativar uma extensão pública de terceiros em sua conta](registry-public-activate-extension.md) + [Atualizar uma extensão pública de terceiros em sua conta](registry-public-update-extension-console.md) + [Desativar extensões públicas de terceiros em sua conta](registry-public-deactivate-extension.md) ## Configure um perfil de execução com permissões do IAM e uma política de confiança para acesso público à extensão Ao ativar uma extensão pública via registro do CloudFormation, você pode fornecer um perfil de execução que conceda ao CloudFormation as permissões necessárias para invocar essa extensão em sua região e Conta da AWS. As permissões necessárias para o perfil de execução são definidas na seção de manipulador do esquema da extensão. É necessário criar uma política do IAM que conceda as permissões específicas necessárias para a extensão e anexá-la à função de execução. Além da política de permissões, o perfil de execução também deve ter uma política de confiança que permita ao CloudFormation assumir o perfil. Siga as orientações em [Criar um perfil usando políticas de confiança personalizadas](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-custom.html) no *Guia do usuário do IAM* para criar um perfil com uma política de confiança personalizada. ### Relação de confiança A seguir são mostrados exemplos de políticas que você pode usar. Opcionalmente, é possível restringir o escopo da permissão da prevenção do problema "confused deputy" entre serviços usando uma ou mais chaves de contexto de condição global com o campo `Condition`. Para obter mais informações, consulte [Prevenção contra o ataque do “substituto confuso” em todos os serviços](cross-service-confused-deputy-prevention.md). + Defina o valor `aws:SourceAccount` para o ID da sua conta. + Defina o valor `aws:SourceArn` para o ARN da sua extensão. **Exemplo de política de confiança 1** Veja a seguir um exemplo de política de confiança de perfil do IAM para uma extensão de tipo de recurso. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "resources.cloudformation.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "aws:SourceAccount": "123456789012" }, "ArnLike": { "aws:SourceArn": "arn:aws:cloudformation:us-west-2:123456789012:type/resource/Organization-Service-Resource" } } } ] } ``` ------ **Exemplo de política de confiança 2** Veja a seguir um exemplo de política de confiança de perfil do IAM para a extensão de hook. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": [ "resources.cloudformation.amazonaws.com", "hooks.cloudformation.amazonaws.com" ] }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "aws:SourceAccount": "123456789012" }, "ArnLike": { "aws:SourceArn": "arn:aws:cloudformation:us-west-2:123456789012:type/hook/Organization-Service-Hook" } } } ] } ``` ------ ## Usar novas versões de extensões automaticamente Ao ativar uma extensão, você também pode especificar o tipo de extensão para utilizar a versão secundária mais recente. Seu tipo de extensão atualizará a versão secundária sempre que o editor lançar uma nova versão na sua extensão ativada. Por exemplo, da próxima vez em que você executar uma operação de pilha, como criar ou atualizar uma pilha, utilizando um modelo que inclui essa extensão, o CloudFormation usará a nova versão secundária. Atualizar para uma nova versão de extensão, automática ou manualmente, não afeta nenhuma instância de extensão já provisionada em pilhas. O CloudFormation trata as atualizações de versões principais de extensões como contendo potencialmente alterações significativas e, portanto, exige que você atualize manualmente para uma nova versão principal de uma extensão. As extensões publicadas pela AWS são ativadas por padrão para todas as contas e regiões em que estão disponíveis e sempre utilizam a versão mais recente disponível em cada Região da AWS. **Importante** Como você controla se e quando as extensões são atualizadas para a versão mais recente da sua conta, é possível que versões diferentes da mesma extensão sejam implantadas em contas e regiões diferentes. Isso pode gerar resultados inesperados ao utilizar o mesmo modelo, contendo essa extensão, entre essas contas e regiões. ## Usar aliases para fazer referência a extensões Não é possível ativar mais de uma extensão com um determinado nome em uma determinada região e Conta da AWS. Como diferentes editores podem oferecer extensões públicas com o mesmo nome, o CloudFormation permite que você especifique um alias para qualquer extensão pública de terceiros que você ativar. Se você especificar um alias para a extensão, o CloudFormation tratará esse alias como o nome do tipo de extensão dentro da conta e da região. Você deve utilizar o alias para fazer referência à extensão nos seus modelos, chamadas de API e no console do CloudFormation. Aliases de extensão devem ser exclusivos em uma conta e região especificadas. É possível ativar o mesmo recurso público várias vezes na mesma conta e região utilizando apelidos de nomes de tipos diferentes. **Importante** Embora aliases de extensões só precisem ser exclusivos em uma determinada conta e região, sugerimos que os usuários *não* atribuam o mesmo alias a diferentes extensões públicas de terceiros entre contas e regiões. Isso pode gerar resultados inesperados ao utilizar um modelo que contém o alias de extensão em várias contas ou regiões. ## Comandos da AWS CLI comumente usados para trabalhar com extensões públicas Os comandos comumente usados para trabalhar com extensões públicas incluem: + [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/activate-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/activate-type.html) para ativar um módulo ou tipo de recurso público de terceiros em sua conta. + [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-configuration.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-configuration.html) para especificar os dados de configuração para uma extensão na sua conta e para desabilitar e habilitar hooks. + [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-types.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/list-types.html) para listar as extensões na sua conta. + [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/describe-type.html) para devolver informações detalhadas sobre uma extensão específica ou uma versão específica da extensão, incluindo dados de configuração atuais. + [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-default-version.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-default-version.html) para especificar qual versão de uma extensão é a versão padrão. + [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deactivate-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deactivate-type.html) para desativar um módulo ou tipo de recurso público de terceiros que havia sido ativado em sua conta. # Ativar uma extensão pública de terceiros em sua conta O tópico a seguir mostra como ativar uma extensão pública de terceiros em sua conta, o que a torna utilizável na conta e na região em que foi ativada. **nota** Antes de continuar, confirme se você criou o [perfil do IAM](registry-public.md#registry-public-enable-execution-role) que utilizará com essa extensão. **Topics** + [Ativar uma extensão pública (console)](#registry-public-activate-extension-console) + [Ativar uma extensão pública (AWS CLI)](#registry-public-activate-extension-cli) ## Ativar uma extensão pública (console) Siga as etapas nesta seção para usar o console para: + Ativar uma extensão pública de terceiros + Especificar dados de configuração de extensão adicionais para sua conta **Para ativar uma extensão pública para uso em sua conta** 1. Faça login no Console de gerenciamento da AWS e abra o console CloudFormation em [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/). 1. Na barra de navegação na parte superior da tela, escolha sua Região da AWS. 1. No painel de navegação, em **Registro**, selecione **Extensões públicas**. 1. Use a opção **Filtrar** para selecionar o tipo de extensão e selecione **Terceiros**. (Extensões publicadas pela AWS são ativadas por padrão.) 1. Selecione a extensão e depois **Ativar**. Se várias versões de uma extensão estiverem disponíveis, você poderá usar o menu **Versão** para selecionar a versão da extensão que deseja ativar. A versão padrão é a mais atual. 1. Para **Nome da extensão**, você pode manter a opção **Usar padrão** selecionada ou escolher **Substituir padrão** e inserir o alias do tipo de extensão que deseja usar com essa extensão. O alias deve seguir o formato recomendado para o tipo de extensão. Para obter mais informações, consulte [Usar aliases para fazer referência a extensões](registry-public.md#registry-public-enable-alias). 1. Se a extensão que você está ativando for um hook ou um tipo de recurso, para **ARN do perfil de execução**, especifique o perfil do IAM que o CloudFormation deve assumir ao invocar a extensão. Para obter mais informações, consulte [Configure um perfil de execução com permissões do IAM e uma política de confiança para acesso público à extensão](registry-public.md#registry-public-enable-execution-role). 1. Em **Configuração do registro em log**, se desejar, especifique as informações de configuração de registro em log para uma extensão. Por exemplo: ``` { "logRoleArn": "arn:aws:iam::account:role/rolename", "logGroupName": "log-group-name" } ``` As informações de configuração de registro em log não são necessárias, mas são recomendadas para fins de depuração. Para utilizar a configuração de registro em log com hooks, adicione a mesma política de confiança que a função de execução especificada, para que a função de registro em log possa gravar logs no seu grupo de logs. Os nomes de chaves `logRoleArn` e `logGroupName` diferenciam maiúsculas de minúsculas. 1. Em **Versionamento**, **Atualizações automáticas**, escolha como as atualizações serão recebidas. + **On** (Ativado): atualiza automaticamente para a versão secundária mais recente. As versões principais são atualizadas manualmente. + **Off** (Desativado): nunca atualiza automaticamente para a versão mais recente. Todas as versões são atualizadas manualmente. Para obter mais informações, consulte [Usar novas versões de extensões automaticamente](registry-public.md#registry-public-enable-auto). Se a extensão exigir configuração adicional, você terá a opção de especificar os dados de configuração agora ou depois que a extensão tiver sido ativada. **Importante** Se a extensão que você está ativando for um hook, esta etapa será necessária. Você deve especificar `ENABLED` para a propriedade `HookInvocationStatus`. Essa operação ativa as propriedades do hook que são definidas na seção `properties` do esquema do hook. Para obter mais informações, consulte [Hook configuration schema syntax reference](https://docs.aws.amazon.com/cloudformation-cli/latest/hooks-userguide/hook-configuration-schema.html) no *CloudFormation Hooks User Guide*. **Para especificar os dados de configuração.** 1. Em **Configuração**, escolha **Configurar agora** e, em seguida, escolha **Ativar extensão**. O CloudFormation exibe a página **Configure extension** (Configurar extensão). Para visualizar o esquema de configuração atual da extensão, certifique-se de a opção **View configuration schema** (Visualizar esquema de configuração) esteja ativada. 1. Na caixa de texto **Configuration JSON** (Configuração JSON), insira uma string JSON que represente os dados de configuração que você deseja especificar para essa extensão. O JSON especificado deve ser válido em relação ao esquema de configuração da extensão. 1. Escolha **Configurar extensão**. Se preferir configurar a extensão após a ativação, pule essa etapa e forneça os dados de configuração posteriormente. 1. Em **Configuração**, escolha **Configurar mais tarde** e, em seguida, escolha **Ativar extensão**. 1. Depois que a extensão for ativada, você poderá configurá-la navegando até a extensão na página de extensões ativadas e fornecendo os dados de configuração. ## Ativar uma extensão pública (AWS CLI) Siga as etapas nesta seção para usar o AWS CLI para: + Ativar uma extensão pública de terceiros + Especificar dados de configuração de extensão adicionais para sua conta ### Ativar hooks públicos Ao ativar o Hooks na conta, você autoriza um hook a usar permissões definidas em sua Conta da AWS. O CloudFormation remove as permissões não necessárias antes de passar as permissões ao hook. O CloudFormation recomenda que os clientes ou usuários do hook revisem as permissões dele e estejam cientes sobre elas antes de ativar o Hooks na conta. **Para ativar um hook público para uso em sua conta (AWS CLI)** 1. Obtenha o ARN para do hook e salve-o. Você pode obter o ARN de um Hook usando o Console de gerenciamento da AWS ou a AWS CLI. Para obter mais informações, consulte [Visualizar as extensões disponíveis e ativadas no registro do CloudFormation](registry-view.md). ``` export HOOK_TYPE_ARN="arn:aws:cloudformation:us-west-2:123456789012:type/hook/Organization-Service-Hook/" ``` 1. Use o comando [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-configuration.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-configuration.html) para especificar os dados de configuração. O JSON transmitido por você para `--configuration` deverá ser válido em relação ao esquema de configuração do hook. Para ativar o hook para todas as operações de pilha, é necessário definir a propriedade `HookInvocationStatus` como `ENABLED` na seção `HookConfiguration`. ``` aws cloudformation set-type-configuration \ --configuration "{"CloudFormationConfiguration":{"HookConfiguration":{"HookInvocationStatus": "ENABLED", "FailureMode": "FAIL", "Properties":{}}}}" \ --type-arn $HOOK_TYPE_ARN --region us-west-2 ``` Para obter mais informações sobre as opções de configuração de `HookConfiguration`, consulte [Hook configuration schema syntax reference](https://docs.aws.amazon.com/cloudformation-cli/latest/hooks-userguide/hook-configuration-schema.html#) no *CloudFormation Hooks User Guide*. ### Ativar módulos e tipos de recursos públicos **Para ativar uma extensão pública para uso em sua conta (AWS CLI)** + Use [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/activate-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/activate-type.html) para ativar a extensão e especificar se ela deve ser atualizada automaticamente sempre que uma nova versão secundária for publicada. O exemplo abaixo especifica o nome do recurso da Amazon (ARN) público de uma extensão pública a ser ativada para essa conta. Além disso, ele especifica que o CloudFormation deve atualizar a extensão sempre que uma nova versão secundária é publicada. ``` aws cloudformation activate-type \ --public-type-arn public_extension_ARN \ --execution-role-arn arn:aws:iam::123456789012:role/my-execution-role \ --auto-update true --region us-west-2 ``` Esse comando retorna um ARN da extensão ativada. ``` { "Arn": "arn:aws:cloudformation:us-west-2:123456789012:type/resource/My-Resource-Example" } ``` ### Atualizar a versão de uma extensão pública utilizando (AWS CLI) Use [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/activate-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/activate-type.html) para ativar a extensão novamente. Use a opção `--version-bump` para especificar se a extensão deve ser atualizada para a versão `MAJOR` mais recente ou para a versão `MINOR` mais recente. ``` aws cloudformation activate-type --type RESOURCE \ --type-name Example::Test::1234567890abcdef0 \ --type-name-alias Example::Test::Alias \ --version-bump MAJOR --region us-west-2 ``` # Atualizar uma extensão pública de terceiros em sua conta Após ativar uma extensão pública de terceiros, você poderá atualizar a maioria dos detalhes da extensão em sua conta. **Para atualizar uma extensão pública em sua conta (console)** 1. Faça login no Console de gerenciamento da AWS e abra o console CloudFormation em [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/). 1. Na barra de navegação na parte superior da tela, escolha sua Região da AWS. 1. No painel de navegação, em **Registro**, escolha **Extensões ativadas**. 1. Localize e selecione a extensão que você deseja atualizar. Para obter mais informações, consulte [Visualizar as extensões disponíveis e ativadas no registro do CloudFormation](registry-view.md). 1. No menu **Ações**, escolha **Editar** e, em seguida, escolha a opção de edição apropriada: + Para atualizar o esquema de configuração, consulte [Editar dados de configuração para extensões em sua conta](registry-set-configuration.md). + Para ativar ou desativar atualizações automáticas: 1. Escolha **Editar atualizações automáticas**. 1. Escolha **Ativar** ou **Desativar** e, em seguida, escolha **Salvar**. Para obter mais informações, consulte [Usar novas versões de extensões automaticamente](registry-public.md#registry-public-enable-auto). + Para atualizar o perfil de execução: 1. Escolha **Editar perfil de execução**. 1. Especifique o ARN do perfil do IAM que você deseja que o CloudFormation utilize ao invocar essa extensão e, em seguida, escolha **Salvar**. Para obter mais informações, consulte [Configure um perfil de execução com permissões do IAM e uma política de confiança para acesso público à extensão](registry-public.md#registry-public-enable-execution-role). + Para atualizar a configuração de registro em log: 1. Selecione **Editar configuração do registro em log**. 1. Edite o JSON de configuração do registro em log e escolha **Salvar**. # Desativar extensões públicas de terceiros em sua conta Quando você não precisar mais de uma extensão pública de terceiros ativada, use os procedimentos a seguir para desativá-la em sua conta. **Topics** + [Desativar uma extensão pública em sua conta (console)](#registry-public-deactivate-extension-console) + [Desativar uma extensão pública em sua conta (AWS CLI)](#registry-public-deactivate-extension-cli) + [Desabilitar um hook de sua conta (AWS CLI)](#registry-public-deactivate-extension-cli-hook) ## Desativar uma extensão pública em sua conta (console) **Para desativar uma extensão pública em sua conta** 1. Faça login no Console de gerenciamento da AWS e abra o console CloudFormation em [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/). 1. Na barra de navegação na parte superior da tela, escolha sua Região da AWS. 1. No painel de navegação, em **Registro**, escolha **Extensões ativadas**. 1. Localize e selecione a extensão que você deseja desativar. Para obter mais informações, consulte [Visualizar as extensões disponíveis e ativadas no registro do CloudFormation](registry-view.md). 1. No menu **Ações**, escolha **Desativar**. 1. Selecione **Desativar**. ## Desativar uma extensão pública em sua conta (AWS CLI) Use o seguinte comando [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deactivate-type.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/deactivate-type.html): ``` aws cloudformation deactivate-type --type MODULE \ --type-name Example::Test::Type::MODULE \ --region us-west-2 ``` ## Desabilitar um hook de sua conta (AWS CLI) Desabilitar um hook evita que ele seja executado em sua Conta da AWS sem removê-lo. Use o comando [https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-configuration.html](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/set-type-configuration.html) e especifique `HookInvocationStatus` como `DISABLED` para desabilitar um hook. O exemplo a seguir especifica a Região da AWS e o nome do recurso da Amazon (ARN) do hook que está sendo desabilitado. ``` aws cloudformation set-type-configuration \ --configuration "{"CloudFormationConfiguration":{"HookConfiguration":{"HookInvocationStatus": "DISABLED", "FailureMode": "FAIL", "Properties":{}}}}" \ --type-arn "arn:aws:cloudformation:us-west-2:123456789012:type/hook/MyTestHook" --region us-west-2 ``` Para obter mais informações, consulte [Disable and enable CloudFormation Hooks](https://docs.aws.amazon.com/cloudformation-cli/latest/hooks-userguide/hooks-disable-enable.html) no *CloudFormation Hooks User Guide*.