Usar a Ferramenta de Migração da AWS CLI v1 para v2 para atualizar a AWS CLI versão 1 para a AWS CLI versão 2
Este tópico descreve a Ferramenta de Migração da AWS CLI v1 para v2.
Recomendamos que os usuários da AWS CLI versão 1 atualizem para a AWS CLI versão 2 para acessar novos recursos e obter desempenho aprimorado. Há alterações no comportamento entre a AWS CLI versão 1 e a AWS CLI versão 2 que podem exigir que você atualize seus scripts ou comandos para obter o mesmo comportamento. A Ferramenta de Migração da AWS CLI v1 para v2 analisa scripts bash que contêm comandos da AWS CLI versão 1 e detecta o uso de recursos que foram atualizados com alterações significativas na AWS CLI versão 2. Além disso, a ferramenta pode modificar automaticamente os scripts para corrigir a maioria dos problemas detectados. Essa ferramenta aprimora a experiência de atualização ao detectar e modificar automaticamente comandos da AWS CLI versão 1 em scripts bash para evitar problemas inesperados na atualização para a versão 2.
Em comparação com o modo de depuração de atualização, a Ferramenta de Migração da AWS CLI v1 para v2 é autônoma e não requer a execução de comandos da AWS CLI. Para ver uma comparação completa entre o modo de depuração de atualização e a Ferramenta de Migração da AWS CLI v1 para v2, consulte Usar ferramentas de migração da AWS CLI para mitigar falhas no Guia de migração para a AWS CLI versão 2.
Para ver mais detalhes, consulte Alterações de última hora entre a AWS CLI versão 1 e a AWS CLI versão 2 em Novos atributos e alterações na AWS CLI versão 2.
Como funciona
A Ferramenta de Migração da AWS CLI v1 para v2 é um pacote Python capaz de aplicar lint em scripts bash que usam a AWS CLI versão 1. Por ser um linter estático, a ferramenta não depende da versão da AWS CLI versão 1 que você tenha instalado em sua máquina. O linter é invocado por meio da linha de comandos e o caminho do arquivo local para o script bash é fornecido como um parâmetro.
A ferramenta de migração também pode produzir automaticamente um script bash modificado que resolve a maioria das descobertas detectadas modificando os comandos da AWS CLI versão 1 usados no script. A ferramenta de migração modifica os comandos para que sejam compatíveis com a AWS CLI versão 2 e mantenha o comportamento da versão 1.
Com relação a algumas descobertas, a Ferramenta de Migração da AWS CLI v1 para v2 pode detectá-las, mas não oferece uma correção automática. Nesses casos, a ferramenta de migração as sinaliza como detecções que exigem análise manual.
Consulte Limitações para ver uma lista completa das alterações que causam incompatibilidade e das correções automáticas permitidas pela Ferramenta de Migração da AWS CLI v1 para v2.
Pré-requisitos
Python
Para usar essa ferramenta, é necessário ter o Python 3.9 ou posterior instalado.
Para verificar se você tem uma versão correta do Python instalada, execute o comando a seguir em um terminal e confirme se a saída mostra uma versão do Python que seja pelo menos 3.9.
$python3 --version
Se você tem uma versão mais antiga do Python ou não tem o Python instalado, baixe uma versão compatível na página oficial de download do Python
pip
Além de ter uma versão compatível do Python instalada, é necessário ter o pip instalado.
Para verificar se o pip está instalado, execute o seguinte comando:
$python3 -m pip --version
Se você tiver o pip instalado, verá uma saída semelhante à seguinte:
pip 25.0.1 from ~/.local/lib/python3.13/site-packages (python 3.13)Se você não tiver o pip instalado, consulte Instalar o pip.
Instalação
Instale a Ferramenta de Migração da AWS CLI v1 para v2 em um novo ambiente virtual:
$python3 -m venv .venv$source .venv/bin/activate$python3 -m pip install aws-cli-migrate
Usage
Modo de simulação (padrão)
Com o modo de simulação, é possível detectar automaticamente os comandos da AWS CLI versão 1 sujeitos a alterações que causam incompatibilidade sem modificar o script de entrada:
$migrate-aws-cli --script upload_s3_files.sh
Modo de correção automática
Com o modo de correção automática, você pode detectar e atualizar automaticamente os comandos da AWS CLI versão 1 no script de entrada para mitigar falhas causadas por alterações introduzidas na AWS CLI versão 2, quando possível:
$migrate-aws-cli --script upload_s3_files.sh --fix
Opcionalmente, é possível fornecer um caminho de saída por meio do parâmetro --output para gravar o script atualizado, em vez de atualizar o script de entrada:
$migrate-aws-cli --script upload_s3_files.sh --output upload_s3_files_v2.sh --fix
Modo interativo
Com o modo interativo, é possível detectar automaticamente os comandos da AWS CLI versão 1 sujeitos a alterações que causam incompatibilidade. A maioria das descobertas mostrará uma correção sugerida para mitigar falhas na AWS CLI versão 2. Você pode analisar as correções sugeridas e decidir se deseja aplicá-las. Opcionalmente, forneça um caminho de saída por meio do parâmetro --output para controlar onde gravar o script atualizado:
$migrate-aws-cli --script upload_s3_files.sh --interactive \ --output upload_s3_files_v2.sh
O seguinte trecho de saída é um exemplo de descoberta no modo interativo:
14 14│
15 15│ aws s3 ls s3://mybucket
16 16│
17 │-aws s3 cp s3://amzn-demo-bucket s3://amzn-demo-bucket2 --recursive
17│+aws s3 cp s3://amzn-demo-bucket s3://amzn-demo-bucket2 --recursive --copy-props none
18 18│
19 19│ TEMPLATE_KEY="cloudformation/$(basename "$TEMPLATE_FILE")"
20 20│
examples/upload_s3_files.sh:17 [s3-copy] In AWS CLI v2, object properties will be copied
from the source in multipart copies between S3 buckets. If a copy is or becomes multipart
after upgrading to AWS CLI v2, extra API calls will be made. See
https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration-changes.html#cliv2-migration-s3-copy-metadata.
Apply this fix? [y] yes, [n] no, [a] accept all of type, [r] reject all of type, [u] update all,
[s] save and exit, [q] quit: A correção sugerida é mostrada em um formato semelhante a um Git diff. A ferramenta de migração sugere a remoção de linhas que começam com - e sugere a adição de linhas que começam com +. No exemplo anterior, a sugestão pode ser interpretada como a adição do parâmetro --copy-props none ao comando da AWS CLI versão 1 que executa uma cópia do Amazon S3.
Para cada correção sugerida, é possível inserir qualquer um dos seguintes controles:
-
Digite
ypara aceitar a correção sugerida. -
Digite
npara rejeitar a correção atual. -
Digite
apara aceitar todas as correções do mesmo tipo. -
Digite
rpara rejeitar todas as correções do mesmo tipo. -
Digite
upara aceitar todas as correções restantes. -
Digite
spara salvar e sair. -
Digite
qpara sair sem salvar.
Algumas descobertas podem ser marcadas para análise manual sem uma sugestão de correção. É necessário analisar essas descobertas e verificar se essas alterações que causam incompatibilidade se aplicam ao seu caso. Se essas descobertas se aplicarem ao seu caso, você deverá seguir as orientações especificadas na descrição da descoberta para fazer as alterações necessárias e evitar ou se preparar para alterações introduzidas na AWS CLI versão 2 que causam incompatibilidade.
Limitações
No momento, a Ferramenta de Migração da AWS CLI v1 para v2 não detecta todas as alterações introduzidas na AWS CLI versão 2 que causam incompatibilidade e há casos de falso-positivos em que ela apresenta detecções para comandos mesmo que nenhuma alteração desse tipo seja realmente enfrentada.
Recomendamos enfaticamente que os clientes entendam as Alterações de última hora entre a AWS CLI versão 1 e a AWS CLI versão 2 publicadas em Novos atributos e alterações na AWS CLI versão 2.
Análise baseada em texto
A ferramenta de migração analisa seu script sem o executar. Isso limita a forma como ela detecta comandos da AWS CLI para alterações que causam incompatibilidade. A ferramenta de migração pode examinar somente o texto de um comando da AWS CLI. Ela não consegue detectar problemas que surgem no runtime, como armazenar parâmetros obsoletos em uma variável em vez de transmiti-los diretamente à AWS CLI.
Alterações significativas que não é possível detectar
A extensão do suporte da ferramenta de migração a alterações que causam incompatibilidade é resumida na tabela a seguir.
