Importar recursos existentes para uma pilha

Este tópico mostra como importar recursos existentes da AWS para uma pilha existente, descrevendo-os em um modelo. Para, em vez disso, verificar os recursos existentes e gerar automaticamente um modelo que você possa usar para importar recursos existentes para o CloudFormation ou replicar os recursos em uma nova conta, consulte Gerar modelos a partir de recursos existentes com o gerador de IaC.

Pré-requisitos

Antes de começar, você deve ter o seguinte:

• Um modelo que descreva toda a pilha, incluindo tanto os recursos que já fazem parte da pilha quanto os recursos a serem importados. Salve o modelo do localmente ou em um bucket do Amazon S3.

  Para obter uma cópia de um modelo de pilha em execução

  1. Abra o console do CloudFormation em https://console.aws.amazon.com/cloudformation/.

  2. Na lista de pilhas, escolha a pilha da qual deseja recuperar o modelo.

  3. No painel de detalhes da pilha, escolha a guia Modelo e escolha Copiar para a área de transferência.

  4. Cole o código em um editor de texto para começar a adicionar outros recursos ao modelo.

• Para cada recurso que você desejar importar, inclua o seguinte:

  • as propriedades e os valores das propriedades que definem a configuração atual do recurso.

  • o identificador exclusivo do recurso, como seu nome. Para ter mais informações, consulte Identificadores de recursos.

  • a Atributo DeletionPolicy.

Exemplo de modelo

Nesta demonstração, partimos do pressuposto de que você esteja usando o exemplo de modelo a seguir, denominado TemplateToImport.json, que especifica duas tabelas do DynamoDB. A ServiceTable faz parte da pilha atualmente e a GamesTable é a tabela que você deseja importar.

nota

Este modelo serve apenas de exemplo. Para usá-lo em seus próprios testes, substitua os recursos do exemplo por recursos da sua conta.

{
    "AWSTemplateFormatVersion": "2010-09-09",
    "Description": "Import test",
    "Resources": {
        "ServiceTable": {
            "Type": "AWS::DynamoDB::Table",
            "Properties": {
                "TableName": "Service",
                "AttributeDefinitions": [
                    {
                        "AttributeName": "key",
                        "AttributeType": "S"
                    }
                ],
                "KeySchema": [
                    {
                        "AttributeName": "key",
                        "KeyType": "HASH"
                    }
                ],
                "ProvisionedThroughput": {
                    "ReadCapacityUnits": 5,
                    "WriteCapacityUnits": 1
                }
            }
        },
        "GamesTable": {
            "Type": "AWS::DynamoDB::Table",
            "DeletionPolicy": "Retain",
            "Properties": {
                "TableName": "Games",
                "AttributeDefinitions": [
                    {
                        "AttributeName": "key",
                        "AttributeType": "S"
                    }
                ],
                "KeySchema": [
                    {
                        "AttributeName": "key",
                        "KeyType": "HASH"
                    }
                ],
                "ProvisionedThroughput": {
                    "ReadCapacityUnits": 5,
                    "WriteCapacityUnits": 1
                }
            }
        }
    }
}

Importar um recurso existente para a pilha usando a AWS Management Console

nota

O console do AWS CloudFormation não oferece suporte ao uso da função intrínseca Fn::Transform ao importar recursos. É possível usar o AWS Command Line Interface para importar recursos que usem a função intrínseca Fn::Transform.

1. Faça login no AWS Management Console e abra o console AWS CloudFormation em https://console.aws.amazon.com/cloudformation.

2. Na página Stacks (Pilhas), escolha a pilha para a qual deseja importar os recursos.

3. Escolha Stack actions (Ações da pilha) e Import resources into stack (Importar recursos para a pilha).

   

4. Consulte a página Import overview (Visão geral da importação) e escolha Next (Próximo).

5. Na páginaSpecify template (Especificar modelo), forneça o modelo atualizado usando um dos métodos a seguir e escolha Next (Próximo).

   • Escolha Amazon S3 URL (URL do Amazon S3) e especifique o URL do modelo na caixa de texto.

   • Escolha Upload a template file (Fazer upload de um arquivo de modelo) e procure o arquivo de modelo.

6. Na página Identify resources (Identificar recursos), identifique todos os recursos de destino. Para ter mais informações, consulte Identificadores de recursos.

   1. Em Identifier property (Propriedade do identificador), escolha o tipo de identificador do recurso. Por exemplo, o recurso AWS::DynamoDB::Table pode ser identificado usando a propriedade TableName.

   2. Em Identifier value (Valor do identificador), digite o valor real da propriedade. Por exemplo, o TableName para o recurso GamesTable no modelo de exemplo é Games.

   3. Escolha Próximo.

7. Na página Specify stack details (Especificar detalhes da pilha), atualize os parâmetros e escolha Next (Próximo). Isso cria automaticamente um conjunto de alterações.

   nota

   A operação de importação falhará se você modificar os parâmetros existentes que iniciam uma operação de criação, atualização ou exclusão.

8. Na página Review stack-name (Revisar nome-pilha), revise os recursos a serem importados e escolha Import resources (Importar recursos). Isso executa automaticamente o conjunto de alterações criado na última etapa. As tags no nível da pilha são aplicadas aos recursos importados no momento. Para ter mais informações, consulte Configurar opções da pilha.

   A página Events (Eventos) da pilha é exibida.

   

9. (Opcional) Execute a detecção de desvios na pilha para garantir que o modelo e a configuração real dos recursos importados sejam correspondentes. Para obter mais informações sobre como detectar desvios, consulte Detectar desvio em uma pilha inteira do CloudFormation.

10. (Opcional) Se os recursos importados não corresponderem às configurações de modelo esperadas, corrija as configurações do modelo ou atualize diretamente os recursos. Para obter mais informações sobre como importar recursos com desvio, consulte Resolver o desvio com uma operação de importação.

Importar um recurso existente para a pilha usando a AWS CLI

1. Para saber quais propriedades identificam cada tipo de recurso no modelo, execute o comando get-template-summary, especificando o URL do S3 do modelo. Por exemplo, o recurso AWS::DynamoDB::Table pode ser identificado usando a propriedade TableName. Para o recurso GamesTable no modelo de exemplo, o valor de TableName é Games. Você precisará dessas informações na próxima etapa.

   aws cloudformation get-template-summary \
       --template-url https://amzn-s3-demo-bucket.s3.us-west-2.amazonaws.com/TemplateToImport.json

   Para ter mais informações, consulte Identificadores de recursos.

2. Componha uma lista com os recursos reais a serem importados e os identificadores exclusivos no formato de string JSON apresentado a seguir.

   [{"ResourceType":"AWS::DynamoDB::Table","LogicalResourceId":"GamesTable","ResourceIdentifier":{"TableName":"Games"}}]

   Como alternativa, é possível especificar os parâmetros formatados em JSON em um arquivo de configuração.

   Por exemplo, para importar GamesTable, é possível criar um arquivo ResourcesToImport.txt que contém a configuração apresentada a seguir.

   [
     {
         "ResourceType":"AWS::DynamoDB::Table",
         "LogicalResourceId":"GamesTable",
         "ResourceIdentifier": {
           "TableName":"Games"
         }
     }
   ]

3. Para criar um conjunto de alterações, use o comando create-change-set, apresentado a seguir, e substitua o texto do espaço reservado. Para a opção,--change-set-type especifique um valor de IMPORT. Para a opção --resources-to-import, substitua a string JSON de exemplo pela string JSON real que você acabou de criar.

   aws cloudformation create-change-set \
       --stack-name TargetStack --change-set-name ImportChangeSet \
       --change-set-type IMPORT \
       --template-url https://amzn-s3-demo-bucket.s3.us-west-2.amazonaws.com/TemplateToImport.json \
       --resources-to-import '[{"ResourceType":"AWS::DynamoDB::Table","LogicalResourceId":"GamesTable","ResourceIdentifier":{"TableName":"Games"}}]'

   nota

   A opção --resources-to-import não oferece suporte para a linguagem YAML incorporada. Os requisitos para usar sequências de escape de aspas em uma string JSON variam de acordo com o terminal utilizado. Para obter mais informações, consulte Using quotation marks inside strings no Guia do usuário da AWS Command Line Interface.

   Como alternativa, é possível usar um URL de arquivo como entrada para a opção --resources-to-import, conforme mostrado no exemplo a seguir.

   --resources-to-import file://ResourcesToImport.txt

4. Revise o conjunto de alterações para garantir que os recursos corretos sejam importados.

   aws cloudformation describe-change-set \
       --change-set-name ImportChangeSet --stack-name TargetStack

5. Para iniciar o conjunto de alterações e importar os recursos, use o comando execute-change-set, apresentado a seguir, e substitua o texto do espaço reservado. As tags no nível da pilha são aplicadas aos recursos importados no momento. Para ter mais informações, consulte Configurar opções da pilha. Após a conclusão bem-sucedida da operação (IMPORT_COMPLETE), os recursos são importados com êxito.

   aws cloudformation execute-change-set \
       --change-set-name ImportChangeSet --stack-name TargetStack

6. (Opcional) Execute a detecção de desvios na pilha IMPORT_COMPLETE para garantir que o modelo e a configuração real dos recursos importados sejam correspondentes. Para obter mais informações sobre como detectar desvios, consulte Detectar desvio em uma pilha inteira do CloudFormation.

   1. Execute a detecção de desvio na pilha especificada.

      aws cloudformation detect-stack-drift --stack-name TargetStack

      Se a detecção ocorrer com êxito, esse comando retornará o exemplo de saída apresentado a seguir.

      { "Stack-Drift-Detection-Id" : "624af370-311a-11e8-b6b7-500cexample" }

   2. Visualize o progresso de uma operação de detecção de desvio para o ID de detecção de desvio de pilha especificado.

      aws cloudformation describe-stack-drift-detection-status \
          --stack-drift-detection-id 624af370-311a-11e8-b6b7-500cexample

   3. Visualize as informações de desvio para os recursos que foram verificados em busca de desvios na pilha especificada.

      aws cloudformation describe-stack-resource-drifts --stack-name TargetStack

7. (Opcional) Se os recursos importados não corresponderem às configurações de modelo esperadas, corrija as configurações do modelo ou atualize diretamente os recursos. Para obter mais informações sobre como importar recursos com desvio, consulte Resolver o desvio com uma operação de importação.