# 업그레이드 디버그 모드를 사용하여 AWS CLI 버전 1을 AWS CLI 버전 2로 업그레이드
이 주제에서는 AWS CLI 버전 1의 업그레이드 디버그 모드에 대해 설명합니다.
AWS CLI 버전 1 사용자는 AWS CLI 버전 2로 업그레이드하여 새로운 기능과 향상된 성능에 액세스하는 것이 좋습니다. AWS CLI 버전 1과 AWS CLI 버전 2 사이에는 동작 방식에 변경 사항이 있으므로 동일한 동작을 얻으려면 스크립트나 명령어를 업데이트해야 할 수 있습니다. AWS CLI 버전 1의 업그레이드 디버그 모드는 AWS CLI 버전 2에서 동작이 다른 기능을 사용할 때 경고를 출력합니다. 이 기능은 예상치 못한 문제를 방지하기 위해 AWS CLI 버전 2로 업그레이드하기 전에 수정해야 하는 AWS CLI 버전 1 명령을 자동으로 감지하여 업그레이드 환경을 개선합니다.
자세한 내용은 [AWS CLI 버전 2의 새로운 기능 및 변경 사항](cliv2-migration-changes.md)의 [AWS CLI 버전 1과 AWS CLI 버전 2 간의 주요 변경 사항](cliv2-migration-changes.md#cliv2-migration-changes-breaking) 섹션을 참조하세요.
## 사전 조건
업그레이드 디버그 모드 기능은 버전 `1.44.0`의 AWS CLI에 도입되었습니다.
AWS CLI 버전 1을 사용하여 `aws --version`을 실행하고 AWS CLI 버전이 `1.44.0` 이상인지 확인합니다.
버전이 `1.44.0` 미만인 경우 [AWS CLI 설치, 업데이트 및 제거](https://docs.aws.amazon.com/cli/v1/userguide/cli-chap-install.html)를 참조하세요.
## 작동 방식
활성화된 경우 업그레이드 디버그 모드는 AWS CLI 버전 2의 주요 변경 사항으로 업데이트된 기능의 사용을 감지합니다. AWS CLI 버전 2로 업그레이드한 후 [AWS CLI 버전 1과 AWS CLI 버전 2 간의 주요 변경 사항](cliv2-migration-changes.md#cliv2-migration-changes-breaking)에 나열된 명령 또는 기능을 사용하는 경우 출력에 경고가 표시됩니다. 주요 변경 사항 감지는 사용된 명령, 제공된 인수, 실행 환경(예: 환경 변수, 구성 설정 등)을 기반으로 하며, 경우에 따라 사용 중인 AWS 계정의 리소스 콘텐츠 또는 구성을 기반으로 합니다.
경고는 AWS CLI 버전 2로 업그레이드할 때 예기치 않은 문제를 방지하기 위한 작업을 설명합니다. 경고 메시지에서 권장하는 사항을 변경한 후 명령을 다시 실행해 경고가 더 이상 표시되지 않는지 확인하여 명령이 성공적으로 업데이트되었는지 확인할 수 있습니다. 경고가 해결되었다는 것은 해당 명령이 AWS CLI 버전 2로 업그레이드할 때 설명된 호환성 파괴 변경이 이루어질 가능성이 더 이상 없음을 나타냅니다.
다음 예제에서는 이러한 경고가 어떻게 보이는지 보여줍니다. 이 명령은 예제 경고를 보여줍니다. 모든 경고 텍스트는 "AWS CLI V2 UPGRADE WARNING"으로 시작하고 그 뒤에 특정 경고 메시지가 있습니다. 이 경우 명령은 AWS CLI를 사용하여 URL의 콘텐츠를 검색하고 콘텐츠를 AWS CLI 버전 2에서 제거된 기능인 `--template-body` 파라미터 값으로 사용하기 때문에 경고가 출력됩니다.
```
$ aws cloudformation create-stack \
--stack-name "stack012345" \
--template-body "https://s3.amazonaws.com/amzn-s3-demo-bucket/template.json"
AWS CLI v2 UPGRADE WARNING: For input parameters that have a prefix of http:// or
https://, AWS CLI v2 will not automatically request the content of the URL for
the parameter, and the `cli_follow_urlparam` option has been removed. See
https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration-changes.html#cliv2-migration-paramfile.
```
다음 표에는 모든 주요 변경 사항과 AWS CLI 버전 2의 주요 변경 사항에 직면하지 않도록 하는 방법이 나와 있습니다. 디버그 모드에서 경고를 해결하는 해결 작업은 굵게 표시됩니다.
| 호환성에 영향을 미치는 주요 변경 사항 | v1에서 v2 동작으로 마이그레이션 | v2에서 v1 동작 유지 |
| --- | --- | --- |
| [텍스트 파일 인코딩을 설정하도록 환경 변수 추가](cliv2-migration-changes.md#cliv2-migration-encodingenvvar) | PYTHONUTF8 및 PYTHONIOENCODING 환경 변수의 설정을 해제합니다. | AWS\$1CLI\$1FILE\$1ENCODING 환경 변수를 v1에 지정된 인코딩으로 설정합니다. |
| [기본적으로 이진 파라미터가 base64 인코딩 문자열로 전달됨](cliv2-migration-changes.md#cliv2-migration-binaryparam) | 파라미터 값을 base64로 인코딩합니다. 파라미터가 파일에서 로드되는 경우 파일 콘텐츠를 base64로 인코딩합니다. | 설정값을 cli\$1binary\$1format로 설정합니다..raw-in-base64-out |
| [멀티파트 복사를 수행할 때 Amazon S3의 파일 속성 및 태그 처리가 개선됨](cliv2-migration-changes.md#cliv2-migration-s3-copy-metadata) | 해당 사항 없음. 버전 1에서는 버전 2 동작으로 마이그레이션할 수 없습니다. | --copy-props none 파라미터를 사용합니다. |
| [파라미터에 대한 `http://` 또는 `https://` URL의 자동 검색 안 함](cliv2-migration-changes.md#cliv2-migration-paramfile) | curl(또는 대체 도구)을 사용하여 URL의 콘텐츠를 로컬 파일로 다운로드합니다. 그런 다음 [file://](https://docs.aws.amazon.com/cli/v1/userguide/cli-usage-parameters-file.html)를 사용하여 파라미터에 파일 콘텐츠를 로드합니다. 또는 원시 URL을 파라미터 값으로 지정하도록 cli\$1follow\$1urlparam을 false로 구성합니다. | 해당 사항 없음. 버전 2에서 버전 1 동작을 유지할 수 없습니다. |
| [기본적으로 모든 출력에 사용되는 페이저](cliv2-migration-changes.md#cliv2-migration-output-pager) | 해당 사항 없음. 버전 1에서는 버전 2 동작으로 마이그레이션할 수 없습니다. | cli\$1pager 설정 또는 AWS\$1PAGER 변수를 빈 문자열로 설정합니다. |
| [타임스탬프 출력 값이 ISO 8601 형식으로 표준화됨](cliv2-migration-changes.md#cliv2-migration-timestamp) | cli\$1timestamp\$1format 설정을 iso8601로 설정합니다. | cli\$1timestamp\$1format 설정을 유선으로 설정합니다. |
| [변경 사항이 없는 CloudFormation 배포 처리가 개선됨](cliv2-migration-changes.md#cliv2-migration-cfn) | --no-fail-on-empty-changeset 파라미터를 사용합니다. | --fail-on-empty-changeset 파라미터를 사용합니다. |
| [`us-east-1` 리전의 리전 Amazon S3 엔드포인트 기본 동작이 변경됨](cliv2-migration-changes.md#cliv2-migration-s3-regional-endpoint) | AWS\$1ENDPOINT\$1URL\$1S3 환경 변수 또는 --endpoint-url 명령줄 옵션을 us-east-1 [리전 URL](https://docs.aws.amazon.com/general/latest/gr/s3.html#s3_region)로 설정합니다. | --region aws-global 명령줄 옵션을 사용합니다. |
| [`ecr get-login`이 제거되고 `ecr get-login-password`로 대체됨](cliv2-migration-changes.md#cliv2-migration-ecr-get-login) | (1.17.10 이상) [`ecr get-login`이 제거되고 `ecr get-login-password`로 대체됨](cliv2-migration-changes.md#cliv2-migration-ecr-get-login)을 사용하고 출력을 docker 명령으로 파이프합니다. | 해당 사항 없음. 버전 2에서 버전 1 동작을 유지할 수 없습니다. |
| [AWS CLI플러그인에 대한 버전 2 지원 변경](cliv2-migration-changes.md#cliv2-migration-profile-plugins) | 해당 사항 없음. 버전 1에서는 버전 2 동작으로 마이그레이션할 수 없습니다. | [cli\$1legacy\$1plugin\$1path](https://docs.aws.amazon.com/cli/latest/topic/config-vars.html#plugins)를 구성 파일의 [plugins] 섹션으로 구성합니다. 버전 2에서 플러그인을 테스트하고 버전 2 버전을 잠근 다음 업그레이드할 때마다 플러그인을 테스트합니다. |
| [숨겨진 별칭 지원이 제거됨](cliv2-migration-changes.md#cliv2-migration-aliases) | 더 이상 사용되지 않는 숨겨진 별칭을 모든 버전에서 작동하는 [숨겨진 별칭 지원이 제거됨](cliv2-migration-changes.md#cliv2-migration-aliases)로 전환합니다. | 해당 사항 없음. 버전 2에서 버전 1 동작을 유지할 수 없습니다. |
| [`api_versions` 구성 파일 설정은 지원되지 않음](cliv2-migration-changes.md#cliv2-migration-api-versions) | 이전 API 버전 사용을 최신 API 버전으로 마이그레이션 및 테스트하고 구성 설정에서 [api\$1versions](https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-files.html#cli-config-api_versions)를 제거합니다. | 해당 사항 없음. 버전 2에서 버전 1 동작을 유지할 수 없습니다. |
| [AWS CLI 버전 2는 Signature v4만 사용하여 Amazon S3 요청을 인증함](cliv2-migration-changes.md#cliv2-migration-sigv4) | 서명 버전을 버전 4로 지정합니다([요청 인증에서 서명 버전 지정](https://docs.aws.amazon.com/AmazonS3/latest/API/specify-signature-version.html) 참조). | 해당 사항 없음. 버전 2에서 버전 1 동작을 유지할 수 없습니다. |
| [AWS CLI 버전 2에서는 페이징 파라미터에 대한 일관성이 개선됨](cliv2-migration-changes.md#cliv2-migration-skeleton-paging) | 입력 JSON 파라미터의 페이지 매김 파라미터를 명령 자체로 이동합니다. | 입력 JSON 파라미터에서 페이지 매김 파라미터를 제거합니다. |
| [AWS CLI 버전 2는 모든 명령에서 보다 일관된 반환 코드를 제공함](cliv2-migration-changes.md#cliv2-migration-return-codes) | 해당 사항 없음. 버전 1에서는 버전 2 동작으로 마이그레이션할 수 없습니다. | 해당 사항 없음. 버전 2에서 버전 1 동작을 유지할 수 없습니다. |
## 제한 사항
고객이 [AWS CLI 버전 1과 AWS CLI 버전 2 간의 주요 변경 사항](cliv2-migration-changes.md#cliv2-migration-changes-breaking)를 검토하는 것이 좋습니다.
### 지원되지 않는 주요 변경 사항 감지
업그레이드 디버그 모드 기능은 [AWS CLI 버전 2는 모든 명령에서 보다 일관된 반환 코드를 제공함](cliv2-migration-changes.md#cliv2-migration-return-codes)를 제외한 모든 주요 변경 사항을 지원합니다. 이 모드는 AWS CLI 다운스트림에서 반환된 오류 코드를 사용하는 방법을 설명할 수 없습니다.
### 조건부 주요 변경 사항 감지
[타임스탬프 출력 값이 ISO 8601 형식으로 표준화됨](cliv2-migration-changes.md#cliv2-migration-timestamp) 감지는 감지가 AWS 계정 상태에 따라 달라지는 유일한 경우이며, 계정 리소스가 나중에 업데이트되는 경우 주요 변경 사항이 적용될 수 있습니다. 서비스의 API 응답에 타임스탬프가 포함되지 않으면 이 주요 변경 사항에 대한 감지가 이루어지지 않습니다.
AWS CLI 명령에서 반환된 타임스탬프 형식에 의존하고 아직 ISO 8601을 사용하도록 AWS CLI를 구성하지 않은 경우 버전 2로 업그레이드한 후 타임스탬프 처리가 중단되지 않도록 각별히 주의하세요.
### 해결할 수 없는 주요 변경 사항 감지
업그레이드 디버그 모드별 일부 경고 출력은 명령 또는 환경을 수정하여 해결할 수 없습니다. 다음은 해당 기능을 사용하는 한 업그레이드 디버그 모드에서 경고가 항상 출력되는 경우입니다.
+ [AWS CLI플러그인에 대한 버전 2 지원 변경](cliv2-migration-changes.md#cliv2-migration-profile-plugins) - [구성 파일](https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-files.html)의 플러그인에 의존하는 경우 업그레이드 디버그 모드는 항상 해결할 수 없는 경고를 출력합니다. 이 모드는 AWS CLI 버전 2에서 플러그인이 작동하는지 여부를 보장할 수 없습니다.
+ [멀티파트 복사를 수행할 때 Amazon S3의 파일 속성 및 태그 처리가 개선됨](cliv2-migration-changes.md#cliv2-migration-s3-copy-metadata) - `aws s3`가 bucket-to-bucket Amazon S3 복사를 수행하는 데 사용되는 경우 업그레이드 디버그 모드는 항상 해결할 수 없는 경고를 출력합니다.
### 거짓 감지
업그레이드 디버그 모드에서 출력되는 경고는 AWS CLI v2로 업그레이드한 후 주요 변경 사항이 발생할 것이라고 보장하지 않습니다. 다음은 AWS CLI v2에 주요 변경 사항이 도입되지 않았지만 업그레이드 디버그 모드에서 경고가 출력되는 경우입니다.
+ [텍스트 파일 인코딩을 설정하도록 환경 변수 추가](cliv2-migration-changes.md#cliv2-migration-encodingenvvar) - `PYTHONUTF8` 또는 `PYTHONIOENCODING` 환경 변수가 텍스트 파일 인코딩을 설정하도록 지정되어 있고 지정된 인코딩이 이미 설치된 로캘과 일치하는 경우, 디버그 모드가 인코딩이 설치된 로캘과 일치하는지 확인하지 않으므로 경고가 거짓 감지일 수 있습니다.
+ [멀티파트 복사를 수행할 때 Amazon S3의 파일 속성 및 태그 처리가 개선됨](cliv2-migration-changes.md#cliv2-migration-s3-copy-metadata) - `aws s3`가 bucket-to-bucket Amazon S3 복사를 수행하는 데 사용되고 소스 객체가 [멀티파트 임계값 크기](https://docs.aws.amazon.com/cli/latest/topic/s3-config.html#multipart-threshold) 미만이기 때문에 복사가 멀티파트가 아닌 경우 거짓 감지가 출력됩니다.
+ [타임스탬프 출력 값이 ISO 8601 형식으로 표준화됨](cliv2-migration-changes.md#cliv2-migration-timestamp) - cli\$1timestamp\$1format 구성 설정이 유선(기본값)으로 설정되어 있고 서비스에서 ISO 8601 형식의 타임스탬프를 반환하는 경우.
+ [변경 사항이 없는 CloudFormation 배포 처리가 개선됨](cliv2-migration-changes.md#cliv2-migration-cfn) - `--fail-on-empty-changeset` 플래그가 `aws cloudformation deploy` 명령과 함께 사용되고 결과 변경 세트가 비어 있는 경우 거짓 감지가 출력됩니다. 또한 변경 세트가 비어 있지 않고 `--no-fail-on-empty-changeset`가 사용되지 않는 경우 거짓 감지가 출력됩니다.
+ [`us-east-1` 리전의 리전 Amazon S3 엔드포인트 기본 동작이 변경됨](cliv2-migration-changes.md#cliv2-migration-s3-regional-endpoint) - `aws s3` 또는 `aws s3api`가 Amazon S3 작업을 수행하는 데 사용되고 리전이 `us-east-1`로 구성되며 `s3.us_east_1_regional_endpoint` 구성이 리전으로 구성되지 않고 [엔드포인트 구성 설정](https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-endpoints.html#endpoints-precedence)으로 인해 전역 Amazon S3 엔드포인트가 요청에 사용되는 경우 디버그 모드가 구성된 엔드포인트 설정을 확인하지 않으므로 경고가 거짓 감지일 수 있습니다.
## 업그레이드 디버그 모드 구성
우선 순위에 따라 나열된 다음 방법을 사용하여 업그레이드 디버그 모드를 활성화하거나 비활성화할 수 있습니다.
+ 명령줄 옵션으로 단일 명령에 대해 업그레이드 디버그 모드를 사용하거나 사용하지 않도록 설정합니다. [--v2-debug](https://docs.aws.amazon.com/cli//latest/userguide/cli-configure-options.html#cli-configure-options-v2-debug)를 사용하여 업그레이드 디버그 모드를 사용합니다.
+ 환경 변수는 [AWS\$1CLI\$1UPGRADE\$1DEBUG\$1MODE](https://docs.aws.amazon.com/cli//latest/userguide/cli-configure-envvars.html#envvars-list-aws_cli_upgrade_debug_mode) 변수를 사용합니다.