Uso de la herramienta de migración de la AWS CLI v1-to-v2 para actualizar la versión 1 de la AWS CLI a la versión 2 de la AWS CLI

En este tema se describe la herramienta de migración de la AWS CLI v1-to-v2.

Recomendamos a los usuarios de la versión 1 de AWS CLI que actualicen a la versión 2 de AWS CLI para acceder a las nuevas características y al rendimiento mejorado. Hay cambios de comportamiento entre la versión 1 de AWS CLI y la versión 2 de AWS CLI que pueden requerir que actualice los scripts o comandos para conseguir el mismo comportamiento. La herramienta de migración de la AWS CLI v1-to-v2 analiza los scripts bash que contienen comandos de la versión 1 de la AWS CLI y detecta el uso de funciones que se han actualizado con cambios importantes en la versión 2 de la AWS CLI. Además, la herramienta puede modificar automáticamente los scripts para corregir la mayoría de los problemas que detecte. Esta herramienta mejora la experiencia de actualización al detectar y modificar automáticamente los comandos de la versión 1 de la AWS CLI en scripts bash para evitar problemas inesperados al actualizar a la versión 2.

En comparación con el modo de depuración de actualizaciones, la herramienta de migración de la AWS CLI v1-to-v2 es una herramienta independiente y no requiere la ejecución de comandos de la AWS CLI. Para obtener una comparación exhaustiva entre el modo de depuración de actualizaciones y la herramienta de migración de la AWS CLI v1-to-v2, consulte Uso de herramientas de migración de la AWS CLI para mitigar las interrupciones en Guía de migración para la versión 2 de la AWS CLI.

Para obtener más información, consulte Cambios importantes entre la AWS CLI versión 1 y la AWS CLI versión 2 en Nuevas características y cambios en la versión 2 de la AWS CLI.

Funcionamiento

La herramienta de migración de la AWS CLI v1-to-v2 es un paquete de Python capaz de linting scripts bash que utilizan la versión 1 de la AWS CLI. Al ser un linter estático, no depende de la versión 1 de la AWS CLI que haya instalado en la máquina. El linter se invoca a través de la línea de comandos, donde se proporciona como parámetro la ruta del archivo local al script bash.

La herramienta de migración también puede producir automáticamente un script bash modificado que resuelve la mayoría de los resultados que detecta modificando los comandos de la versión 1 de la AWS CLI utilizados en el script. La herramienta de migración modifica los comandos para que sean compatibles con la versión 2 de AWS y retiene el comportamiento de la versión 1.

Para algunos resultados, la herramienta de migración de la AWS CLI v1-to-v2 puede detectarlos pero no ofrecer una solución automática. En estos casos, la herramienta de migración las marca como detecciones que requieren una revisión manual.

Consulte Limitaciones para obtener una lista exhaustiva de los cambios importantes y las correcciones automáticas que admite la herramienta de migración de la AWS CLI v1-to-v2.

Requisitos previos

Python

Para usar esta herramienta, debe tener instalado Python 3.9 o una versión posterior.

Para comprobar que tiene instalada una versión correcta de Python, ejecute el siguiente comando en un terminal y confirme que el resultado muestra una versión de Python de al menos 3.9.

$ python3 --version

Si tiene una versión anterior de Python o no tiene Python instalado, puede descargar una versión compatible desde la página oficial de descargas de Python.

pip

Además de tener instalada una versión compatible de Python, debe tener instalado pip.

Para comprobar que pip se ha instalado, ejecute el siguiente comando:

$ python3 -m pip --version

Si ha instalado pip, se mostrará un resultado similar al que se incluye a continuación:

pip 25.0.1 from ~/.local/lib/python3.13/site-packages (python 3.13)

Si no ha instalado pip, consulte Instalar pip.

Instalación

Instale la herramienta de migración de la AWS CLI v1-to-v2 en un nuevo entorno virtual:

$ python3 -m venv .venv
$ source .venv/bin/activate
$ python3 -m pip install aws-cli-migrate

Uso

Modo de prueba (predeterminado)

Con el modo de prueba, puede detectar automáticamente los comandos de la versión 1 de la AWS CLI que están sujetos a cambios importantes sin modificar el script de entrada:

$ migrate-aws-cli --script upload_s3_files.sh

Modo de reparación automática

Con el modo de reparación automática, puede detectar y actualizar automáticamente los comandos de la versión 1 de la AWS CLI en el script de entrada para mitigar las interrupciones causadas por los cambios ingresados en la versión 2 de la AWS CLI, siempre que sea posible:

$ migrate-aws-cli --script upload_s3_files.sh --fix

si lo desea, puede proporcionar una ruta de salida mediante el parámetro --output para escribir el script actualizado, en lugar de actualizar el script de entrada:

$ migrate-aws-cli --script upload_s3_files.sh --output upload_s3_files_v2.sh --fix

modo interactivo

Con el modo interactivo, puede detectar automáticamente los comandos de la versión 1 de la AWS CLI que están sujetos a cambios importantes. La mayoría de los resultados mostrarán una solución sugerida para mitigar las interrupciones en la versión 2 de la AWS CLI. Puede revisar las correcciones sugeridas y decidir si las aplica. Si lo desea, proporcione una ruta de salida mediante el parámetro --output para controlar dónde escribir el script actualizado:

$ migrate-aws-cli --script upload_s3_files.sh --interactive \
--output upload_s3_files_v2.sh

el siguiente fragmento de código resultante es un resultado de ejemplo en modo interactivo:

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: 

la solución sugerida se muestra en un formato similar a un diff de Git. La herramienta de migración sugiere eliminar las líneas que comiencen con un - y sugiere agregar líneas que comiencen con un +. En el ejemplo anterior, la sugerencia puede interpretarse como la adición del parámetro --copy-props none al comando de la versión 1 de la AWS CLI que ejecuta una copia de Amazon S3.

Para cada corrección sugerida, puede ingresar cualquiera de los siguientes controles:

Es posible que algunos resultados estén marcados para su revisión manual sin que se sugiera una solución. Debe revisar estos resultados y comprobar si los cambios importantes a los que se hace referencia lo afectan. Si estos resultados lo afectan, debe seguir las instrucciones especificadas en la descripción del resultado para realizar los cambios necesarios a fin de evitar o prepararse para los cambios importantes ingresados en la versión 2 de la AWS CLI.

Limitaciones

La herramienta de migración de la AWS CLI v1-to-v2 no admite actualmente todos los cambios importantes ingresados en la versión 2 de la AWS CLI y tiene casos de falsos positivos en los que genera detecciones de comandos incluso si no se produjeran cambios importantes.

Recomendamos encarecidamente a los clientes que entiendan Cambios importantes entre la AWS CLI versión 1 y la AWS CLI versión 2 publicado en Nuevas características y cambios en la versión 2 de la AWS CLI.

Análisis basado en texto

La herramienta de migración analiza el script sin ejecutarlo. Esto limita la forma en que detecta los comandos de la AWS CLI para los cambios importantes. La herramienta de migración solo puede examinar el texto de un comando de la AWS CLI. No puede detectar los problemas que surgen en tiempo de ejecución, como almacenar parámetros obsoletos en una variable en lugar de pasarlos directamente a la AWS CLI.

Detección de cambios importantes no compatible

El grado de compatibilidad con los cambios importantes en la herramienta de migración se resume en la siguiente tabla.