AWS CLI v1-v2 마이그레이션 도구를 사용하여 AWS CLI 버전 1을 AWS CLI 버전 2로 업그레이드

이 주제에서는 AWS CLI v1-v2 마이그레이션 도구를 설명합니다.

AWS CLI 버전 1 사용자는 AWS CLI 버전 2로 업그레이드하여 새로운 기능과 향상된 성능에 액세스하는 것이 좋습니다. AWS CLI 버전 1과 AWS CLI 버전 2 사이에는 동작 방식에 변경 사항이 있으므로 동일한 동작을 얻으려면 스크립트나 명령어를 업데이트해야 할 수 있습니다. AWS CLI v1-v2 마이그레이션 도구는 AWS CLI 버전 1 명령이 포함된 bash 스크립트를 분석하고 AWS CLI 버전 2에서 호환성 파괴 변경 사항으로 업데이트된 기능의 사용을 감지합니다. 또한 이 도구는 자동으로 스크립트를 수정하여 감지한 대부분의 문제를 해결할 수 있습니다. 이 도구는 bash 스크립트에서 AWS CLI 버전 1 명령을 자동으로 감지하고 수정하여 버전 2로 업그레이드할 때 발생할 수 있는 예기치 않은 문제를 방지함으로써 업그레이드 환경을 개선합니다.

업그레이드 디버그 모드와 비교했을 때, AWS CLI v1-v2 마이그레이션 도구는 독립 실행형 도구이며 AWS CLI 명령을 실행할 필요가 없습니다. 업그레이드 디버그 모드와 AWS CLI v1-v2 마이그레이션 도구 간의 자세한 비교는 AWS CLI 버전 2의 마이그레이션 가이드의 AWS CLI 마이그레이션 도구를 사용하여 호환성 문제 완화 섹션을 참조하세요.

자세한 내용은 AWS CLI 버전 2의 새로운 기능 및 변경 사항의 AWS CLI 버전 1과 AWS CLI 버전 2 간의 주요 변경 사항 섹션을 참조하세요.

작동 방식

AWS CLI v1-v2 마이그레이션 도구는 AWS CLI 버전 1을 사용하는 bash 스크립트를 린트할 수 있는 Python 패키지입니다. 정적 린터이므로 이는 시스템에 설치된 AWS CLI 버전 1의 버전에 좌우되지 않습니다. 이 린터는 명령줄을 통해 간접적으로 호출되며, 여기서 bash 스크립트의 로컬 파일 경로는 파라미터로 제공됩니다.

또한 이 마이그레이션 도구는 스크립트에 사용된 AWS CLI 버전 1 명령을 수정하여 감지한 대부분의 조사 결과를 해결하는 수정된 bash 스크립트를 자동으로 생성할 수 있습니다. 마이그레이션 도구는 AWS 버전 2와 호환되도록 명령을 수정하고 버전 1의 동작을 유지합니다.

일부 조사 결과의 경우 AWS CLI v1-v2 마이그레이션 도구는 이를 감지할 수 있지만 자동 수정은 제공하지 않습니다. 이러한 경우 마이그레이션 도구는 수동 검토가 필요한 감지로 플래그를 지정합니다.

AWS CLI v1-v2 마이그레이션 도구가 지원하는 호환성 파괴 변경 및 자동 수정의 전체 목록은 제한 사항 섹션을 참조하세요.

사전 조건

Python

이 도구를 사용하려면 Python 3.9 이상이 설치되어 있어야 합니다.

올바른 Python 버전이 설치되어 있는지 확인하려면 터미널에서 다음 명령을 실행하고 출력에 3.9 이상의 Python 버전이 표시되는지 확인합니다.

$ python3 --version

이전 버전의 Python이 있거나 Python이 설치되어 있지 않은 경우 공식 Python 다운로드 페이지에서 호환 버전을 다운로드할 수 있습니다.

pip

호환되는 버전의 Python을 설치하는 것 외에도 pip가 설치되어 있어야 합니다.

pip가 설치되었는지 확인하려면 다음 명령을 실행합니다.

$ python3 -m pip --version

pip가 설치된 경우 다음과 비슷한 출력이 표시됩니다.

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

pip가 설치되지 않은 경우 pip 설치를 참조하세요.

설치

AWS CLI v1-v2 마이그레이션 도구를 새 가상 환경에 설치합니다.

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

사용법

드라이 런 모드(기본값)

드라이 런 모드를 사용하면 입력 스크립트를 수정하지 않고도 호환성 파괴 변경 사항이 적용되는 AWS CLI 버전 1 명령을 자동으로 감지할 수 있습니다.

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

자동 수정 모드

자동 수정 모드를 사용하면 입력 스크립트에서 AWS CLI 버전 1 명령을 자동으로 감지하고 업데이트하여 가능한 경우 AWS CLI 버전 2에 도입된 변경으로 인한 호환성 문제를 완화할 수 있습니다.

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

선택적으로 --output 파라미터를 통해 출력 경로를 제공하여, 입력 스크립트를 업데이트하는 대신 업데이트된 스크립트를 작성할 수 있습니다.

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

대화형 모드

대화형 모드를 사용하면 호환성 파괴 변경 사항이 적용되는 AWS CLI 버전 1 명령을 자동으로 감지할 수 있습니다. 대부분의 조사 결과에는 AWS CLI 버전 2의 호환성 문제를 완화하기 위해 제안된 수정 사항이 표시됩니다. 제안된 수정 사항을 검토하고 적용할지 여부를 결정할 수 있습니다. 선택적으로 --output 파라미터를 통해 출력 경로를 제공하여 업데이트된 스크립트를 작성할 위치를 제어합니다.

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

다음 출력 코드 스니펫은 대화형 모드의 조사 결과 예시입니다.

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: 

제안된 수정 사항은 Git diff와 유사한 형식으로 표시됩니다. 마이그레이션 도구는 -로 시작하는 줄의 제거를 제안하고 +로 시작하는 줄을 추가할 것을 제안합니다. 이전 예시에서 제안 사항은 Amazon S3 복사본을 실행하는 AWS CLI 버전 1 명령에 --copy-props none 파라미터를 추가하는 것으로 해석될 수 있습니다.

제안된 각 수정 사항에 대해 다음 컨트롤 중 하나를 입력할 수 있습니다.

일부 조사 결과는 수정 사항 제안 없이 수동 검토 대상으로 플래그가 지정될 수 있습니다. 이러한 조사 결과를 검토하고 언급된 호환성 파괴 변경 사항의 영향을 받는지 확인해야 합니다. 이러한 조사 결과의 영향을 받는 경우 조사 결과 설명에 명시된 지침에 따라 AWS CLI 버전 2에 도입된 호환성 파괴 변경 사항을 방지하거나 그에 대비하는 데 필요한 변경을 수행해야 합니다.

제한 사항

AWS CLI v1-v2 마이그레이션 도구는 현재 AWS CLI 버전 2에 도입된 모든 호환성 파괴 변경 사항을 지원하지 않으며, 실제로 호환성 문제가 발생하지 않는 명령에 대해서도 호환성 파괴 변경이 감지되는 오탐 사례가 있습니다.

고객은 AWS CLI 버전 2의 새로운 기능 및 변경 사항에 게시된 AWS CLI 버전 1과 AWS CLI 버전 2 간의 주요 변경 사항 내용을 이해하는 것이 좋습니다.

텍스트 기반 분석

마이그레이션 도구는 스크립트를 실행하지 않고 분석합니다. 이로 인해 AWS CLI 명령의 호환성 파괴 변경에 대한 감지가 제한됩니다. 마이그레이션 도구는 AWS CLI 명령의 텍스트만 검사할 수 있습니다. 더 이상 사용되지 않는 파라미터를 AWS CLI에 직접 전달하는 대신 변수에 저장하는 등 런타임에 발생하는 문제를 감지할 수 없습니다.

지원되지 않는 주요 변경 사항 감지

마이그레이션 도구의 호환성 파괴 변경에 대한 지원 범위는 다음 표에 요약되어 있습니다.